feat(server): link to another environment#16655

@@ -0,0 +1,452 @@
+import {
+  AuthMcpApprovalError,
+  AuthMcpClientAccess,
+  AuthMcpRegistrationError,
+  AuthMcpTokenError,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+import { isLocalLoopbackHost, isTailnetHost } from "@t3tools/shared/hostClassification";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/**
+ * How long a peer's descriptor may take before a route counts as unreachable.
+ * A tailnet or relayed route to a machine that is waking up takes longer.
+ */
+const probeTimeout = (origin: string) =>
+  isLocalLoopbackHost(new URL(origin).hostname) ? Duration.seconds(3) : Duration.seconds(10);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly secret_name: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+/** Fails with a fixed storage error; the cause goes to the log, not to the caller. */
+const failStorage = (cause: unknown) =>
+  Effect.logWarning("Peer link storage failed", cause).pipe(
+    Effect.andThen(
+      Effect.fail(
+        new PeerLinkError({
+          reason: "storage",
+          message:
+            "Linked environments could not be read or saved here. The server log has details.",
+        }),
+      ),
+    ),
+  );
+
+/**
+ * The base URL a peer is reached at, normalised to its origin. The pairing
+ * code and then the link's token travel to it, so plain http is accepted only
+ * where the network already encrypts: this machine, or a Tailscale address.
+ */
+const peerOrigin = (url: string) => {
+  const parsed = URL.parse(url);
+  if (parsed === null || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+    );
+  }
+  if (
+    parsed.protocol === "http:" &&
+    !isLocalLoopbackHost(parsed.hostname) &&
+    !isTailnetHost(parsed.hostname)
+  ) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
+      }),
+    );
+  }
+  return Effect.succeed(parsed.origin);
+};
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  /** A fresh name for one link's token; the row records it. */
+  const newSecretName = crypto.randomBytes(16).pipe(
+    Effect.map((bytes) => `peer-link-${Hex.encode(bytes)}`),
+    Effect.orDie,
+  );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(probeTimeout(origin)),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.catch(failStorage));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.catch(failStorage));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.catch(failStorage),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      const rejected = (message: string) =>
+        new PeerLinkError({ reason: "pairing_rejected", message });
+      // Only the peer's own refusals are rejections. A dropped connection or
+      // an answer this version cannot read is classified below.
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpRegistrationError), (error) =>
+            Effect.fail(
+              rejected(`The peer refused to register this environment: ${error.message}`),
+            ),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpApprovalError), (error) =>
+            Effect.fail(rejected(error.message)),
+          ),
+        );
+      const redirect = URL.parse(decided.redirectTo);
+      if (redirect === null) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${origin} answered the sign-in with an address this version cannot read. Update both environments.`,
+        });
+      }
+      const code = redirect.searchParams.get("code");
+      if (code === null || redirect.searchParams.get("state") !== state) {
+        return yield* rejected(
+          redirect.searchParams.get("error_description") ??
+            "The peer did not approve the link. Check the pairing code and try again.",
+        );
+      }
+      return yield* client.mcpOAuth
+        .token({
+          payload: {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: LINK_REDIRECT_URI,
+            client_id: registered.client_id,
+            code_verifier: verifier,
+            resource,
+          },
+        })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpTokenError), (error) =>
+            Effect.fail(rejected(`The peer refused the sign-in: ${error.message}`)),
+          ),
+        );
+    }).pipe(
+      // Endpoint errors are mapped above; what is left is the transport or an
+      // answer this version cannot decode.
+      Effect.catch((error) =>
+        error._tag === "PeerLinkError"
+          ? Effect.fail(error)
+          : Effect.fail(
+              new PeerLinkError({
+                reason: error._tag === "SchemaError" ? "incompatible" : "unreachable",
+                message:
+                  error._tag === "SchemaError"
+                    ? `${origin} answered in a shape this version does not understand. Update both environments.`
+                    : `${origin} stopped answering while linking.`,
+              }),
+            ),
+      ),
+    );
+
+  const link: PeerLinks["Service"]["link"] = (input) =>
+    Effect.gen(function* () {
+      const origins = yield* Effect.forEach(
+        [input.url, ...(input.alternateUrls ?? [])],
+        peerOrigin,
+      );
+      const primary = origins[0]!;
+      const descriptor = yield* describe(primary);
+      if (Option.isNone(descriptor)) {
+        return yield* new PeerLinkError({
+          reason: "not_a_t3_environment",
+          message: `Nothing at ${primary} answered as a T3 Code environment.`,
+        });
+      }
+      const peer = descriptor.value;
+      const self = yield* environment.getDescriptor;
+      if (peer.environmentId === self.environmentId) {
+        return yield* new PeerLinkError({
+          reason: "self",
+          message: "That address is this environment.",
+        });
+      }
+      if (peer.capabilities.mcpModeLimitHeader !== true) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${peer.label} runs a T3 Code version that cannot keep a linked agent's limits. Update it, then link again.`,
+        });
+      }
+      const issued = yield* signIn(primary, input, `T3 Code · ${self.label}`);
+      const now = yield* DateTime.now;
+      const linked: PeerLink = {
+        environmentId: peer.environmentId,
+        label: peer.label,
+        urls: origins,
+        access: input.access,
+        linkedAt: now,
+        expiresAt: DateTime.add(now, { seconds: issued.expires_in }),
+        lastReachedAt: now,
+        lastError: null,
+      };
+      // The token goes under a name of its own before the row points at it,
+      // so the row and its token are replaced together.
+      const secretName = yield* newSecretName;
+      yield* secrets
+        .set(secretName, new TextEncoder().encode(issued.access_token))
+        .pipe(Effect.catch(failStorage));
+      const urlsJson = yield* encodeUrls(origins).pipe(Effect.catch(failStorage));
+      const previous = yield* readRow(peer.environmentId);
+      yield* sql`
+        INSERT INTO peer_environment_links (
+          environment_id, secret_name, label, urls_json, access, linked_at, expires_at,
+          last_reached_at, last_error
+        ) VALUES (
+          ${linked.environmentId}, ${secretName}, ${linked.label}, ${urlsJson}, ${linked.access},
+          ${DateTime.formatIso(linked.linkedAt)}, ${DateTime.formatIso(linked.expiresAt)},
+          ${DateTime.formatIso(now)}, NULL
+        )
+        ON CONFLICT (environment_id) DO UPDATE SET
+          secret_name = excluded.secret_name,
+          label = excluded.label,
+          urls_json = excluded.urls_json,
+          access = excluded.access,
+          linked_at = excluded.linked_at,
+          expires_at = excluded.expires_at,
+          last_reached_at = excluded.last_reached_at,
+          last_error = NULL
+      `.pipe(Effect.catch(failStorage));
+      // Linking again replaces the old token. A racing link may leave its own
+      // behind; it is unused either way.
+      if (Option.isSome(previous) && previous.value.secret_name !== secretName) {
+        yield* secrets.remove(previous.value.secret_name).pipe(Effect.ignore);
+      }
+      return linked;
+    });
+
+  const statusOf = (link: PeerLink, now: DateTime.Utc) =>
+    DateTime.isLessThanOrEqualTo(link.expiresAt, now)
+      ? Effect.succeed<PeerLinkStatus>("expired")
+      : Effect.findFirst(link.urls, (url) =>
+          describe(url).pipe(
+            Effect.map(
+              (found) => Option.isSome(found) && found.value.environmentId === link.environmentId,
+            ),
+          ),
+        ).pipe(
+          Effect.map((answered): PeerLinkStatus =>
+            Option.isSome(answered) ? "reachable" : "unreachable",
+          ),
+        );
+
+  const list: PeerLinks["Service"]["list"] = Effect.gen(function* () {
+    const links = yield* Effect.forEach(yield* readRows, toLink);
+    const now = yield* DateTime.now;
+    return yield* Effect.forEach(
+      links,
+      (link) => statusOf(link, now).pipe(Effect.map((status) => ({ ...link, status }))),
+      { concurrency: "unbounded" },
+    );
+  });
+
+  const unlink: PeerLinks["Service"]["unlink"] = (environmentId) =>
+    Effect.gen(function* () {
+      const deleted = yield* sql<{ secret_name: string }>`
+        DELETE FROM peer_environment_links WHERE environment_id = ${environmentId}
+        RETURNING secret_name
+      `.pipe(Effect.catch(failStorage));
+      for (const row of deleted) {
+        yield* secrets.remove(row.secret_name).pipe(Effect.catch(failStorage));
+      }
+      return deleted.length > 0;
+    });
+
+  const resolve: PeerLinks["Service"]["resolve"] = (environmentId) =>
+    Effect.gen(function* () {
+      const row = yield* readRow(environmentId);
+      if (Option.isNone(row)) {
+        return yield* new PeerLinkError({
+          reason: "unknown_link",
+          message: `This environment is not linked to ${environmentId}. t3_environment_links lists the linked ones.`,
+        });
+      }
+      const link = yield* toLink(row.value);
+      if (DateTime.isLessThanOrEqualTo(link.expiresAt, yield* DateTime.now)) {
+        return yield* new PeerLinkError({
+          reason: "expired",
+          message: `The link to ${link.label} expired. Link it again with a new pairing code from ${link.label}.`,
+        });
+      }
+      const stored = yield* secrets.get(row.value.secret_name).pipe(Effect.catch(failStorage));
+      if (Option.isNone(stored)) {
+        return yield* new PeerLinkError({
+          reason: "unknown_link",
+          message: `The link to ${link.label} lost its credential. Link it again.`,
+        });
+      }
+      // The token goes only to an address that proves it is this peer, so a
+      // reused LAN address or a moved hostname never receives it.
+      const url = yield* Effect.findFirst(link.urls, (candidate) =>
+        describe(candidate).pipe(
+          Effect.map(
+            (found) => Option.isSome(found) && found.value.environmentId === environmentId,

@@ -0,0 +1,393 @@
+import {
+  AuthMcpClientAccess,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/** How long a peer's descriptor may take before a route counts as unreachable. */
+const PROBE_TIMEOUT = Duration.seconds(3);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+const storageError = (cause: unknown) =>
+  new PeerLinkError({
+    reason: "storage",
+    message: `Peer links could not be read or saved: ${String(cause)}`,
+  });
+
+/** The base URL a peer is reached at, normalised to its origin. */
+const peerOrigin = (url: string) =>
+  Effect.try({
+    try: () => {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error("protocol");
+      return parsed.origin;
+    },
+    catch: () =>
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+  });
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  const secretName = (environmentId: EnvironmentId) =>
+    crypto.digest("SHA-256", new TextEncoder().encode(environmentId)).pipe(
+      Effect.map((digest) => `peer-link-${Hex.encode(digest)}`),
+      Effect.orDie,
+    );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(PROBE_TIMEOUT),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.mapError(storageError));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.mapError(storageError));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.mapError(storageError),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      const rejected = (message: string) =>
+        new PeerLinkError({ reason: "pairing_rejected", message });
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          Effect.mapError((error) =>
+            rejected(`The peer refused to register this environment: ${error.message}`),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(Effect.mapError((error) => rejected(error.message)));
+      const redirect = new URL(decided.redirectTo);
+      const code = redirect.searchParams.get("code");
+      if (code === null || redirect.searchParams.get("state") !== state) {
+        return yield* rejected(
+          redirect.searchParams.get("error_description") ??
+            "The peer did not approve the link. Check the pairing code and try again.",
+        );
+      }
+      return yield* client.mcpOAuth
+        .token({
+          payload: {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: LINK_REDIRECT_URI,
+            client_id: registered.client_id,
+            code_verifier: verifier,
+            resource,
+          },
+        })
+        .pipe(
+          Effect.mapError((error) => rejected(`The peer refused the sign-in: ${error.message}`)),
+        );
+    }).pipe(
+      // Endpoint errors are mapped above; what is left is the transport or an
+      // answer this version cannot decode.
+      Effect.catch((error) =>
+        error._tag === "PeerLinkError"
+          ? Effect.fail(error)
+          : Effect.fail(
+              new PeerLinkError({
+                reason: error._tag === "SchemaError" ? "incompatible" : "unreachable",
+                message:
+                  error._tag === "SchemaError"
+                    ? `${origin} answered in a shape this version does not understand. Update both environments.`
+                    : `${origin} stopped answering while linking.`,
+              }),
+            ),
+      ),
+    );
+
+  const link: PeerLinks["Service"]["link"] = (input) =>
+    Effect.gen(function* () {
+      const origins = yield* Effect.forEach(
+        [input.url, ...(input.alternateUrls ?? [])],
+        peerOrigin,
+      );
+      const primary = origins[0]!;

@@ -0,0 +1,483 @@
+import {
+  AuthMcpClientAccess,
+  AuthMcpRegistrationError,
+  AuthMcpTokenError,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+import { isLocalLoopbackHost, isTailnetHost } from "@t3tools/shared/hostClassification";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/**
+ * How long a peer's descriptor may take before a route counts as unreachable.
+ * A tailnet or relayed route to a machine that is waking up takes longer.
+ */
+const probeTimeout = (origin: string) =>
+  isLocalLoopbackHost(new URL(origin).hostname) ? Duration.seconds(3) : Duration.seconds(10);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** The stored link, without asking the peer whether it answers. */
+    readonly get: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<Option.Option<PeerLink>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly secret_name: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+/** Fails with a fixed storage error that keeps its cause; the log gets the details. */
+const failStorage = (cause: unknown) =>
+  Effect.logWarning("Peer link storage failed", cause).pipe(
+    Effect.andThen(
+      Effect.fail(
+        new PeerLinkError({
+          reason: "storage",
+          message:
+            "Linked environments could not be read or saved here. The server log has details.",
+          cause,
+        }),
+      ),
+    ),
+  );
+
+/**
+ * The base URL a peer is reached at, normalised to its origin. The pairing
+ * code and then the link's token travel to it, so plain http is accepted only
+ * where the network already encrypts: this machine, or a Tailscale address.
+ */
+const peerOrigin = (url: string) => {
+  const parsed = URL.parse(url);
+  if (parsed === null || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+    );
+  }
+  if (
+    parsed.protocol === "http:" &&
+    !isLocalLoopbackHost(parsed.hostname) &&
+    !isTailnetHost(parsed.hostname)
+  ) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
+      }),
+    );
+  }
+  return Effect.succeed(parsed.origin);
+};
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  /** A fresh name for one link's token; the row records it. */
+  const newSecretName = crypto.randomBytes(16).pipe(
+    Effect.map((bytes) => `peer-link-${Hex.encode(bytes)}`),
+    Effect.orDie,
+  );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(probeTimeout(origin)),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.catch(failStorage));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.catch(failStorage));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.catch(failStorage),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      // Only the peer's own refusals are rejections. A dropped connection or
+      // an answer this version cannot read is classified below.
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          // A plain Schema.Error has no tag to catch by.
+          Effect.catchIf(Schema.is(AuthMcpRegistrationError), (error) =>
+            Effect.fail(
+              new PeerLinkError({
+                reason: "pairing_rejected",
+                message: `The peer refused to register this environment: ${error.message}`,
+              }),
+            ),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(
+          Effect.catchTags({
+            AuthMcpApprovalError: (error) =>
+              Effect.fail(
+                new PeerLinkError({ reason: "pairing_rejected", message: error.message }),
+              ),
+          }),
+        );
+      const redirect = URL.parse(decided.redirectTo);
+      if (redirect === null) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${origin} answered the sign-in with an address this version cannot read. Update both environments.`,
+        });
+      }
+      const code = redirect.searchParams.get("code");
+      if (code === null || redirect.searchParams.get("state") !== state) {
+        return yield* new PeerLinkError({
+          reason: "pairing_rejected",
+          message:
+            redirect.searchParams.get("error_description") ??
+            "The peer did not approve the link. Check the pairing code and try again.",
+        });
+      }
+      return yield* client.mcpOAuth
+        .token({
+          payload: {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: LINK_REDIRECT_URI,
+            client_id: registered.client_id,
+            code_verifier: verifier,
+            resource,
+          },
+        })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpTokenError), (error) =>
+            Effect.fail(
+              new PeerLinkError({
+                reason: "pairing_rejected",
+                message: `The peer refused the sign-in: ${error.message}`,
+              }),
+            ),
+          ),
+        );
+    }).pipe(
+      // Endpoint errors are mapped above; what is left is the transport or an
+      // answer this version cannot decode.
+      Effect.catchTags({
+        SchemaError: (cause) =>
+          Effect.fail(
+            new PeerLinkError({
+              reason: "incompatible",
+              message: `${origin} answered in a shape this version does not understand. Update both environments.`,
+              cause,
+            }),
+          ),
+        HttpClientError: (cause) =>
+          Effect.fail(
+            new PeerLinkError({
+              reason: "unreachable",
+              message: `${origin} stopped answering while linking.`,
+              cause,
+            }),
+          ),
+      }),
+    );
+
+  const link: PeerLinks["Service"]["link"] = (input) =>
+    Effect.gen(function* () {
+      const origins = yield* Effect.forEach(
+        [input.url, ...(input.alternateUrls ?? [])],
+        peerOrigin,
+      );
+      const primary = origins[0]!;
+      const descriptor = yield* describe(primary);
+      if (Option.isNone(descriptor)) {
+        return yield* new PeerLinkError({
+          reason: "not_a_t3_environment",
+          message: `Nothing at ${primary} answered as a T3 Code environment.`,
+        });
+      }
+      const peer = descriptor.value;
+      const self = yield* environment.getDescriptor;
+      if (peer.environmentId === self.environmentId) {
+        return yield* new PeerLinkError({
+          reason: "self",
+          message: "That address is this environment.",
+        });
+      }
+      if (peer.capabilities.mcpModeLimitHeader !== true) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${peer.label} runs a T3 Code version that cannot keep a linked agent's limits. Update it, then link again.`,
+        });
+      }
+      const issued = yield* signIn(primary, input, `T3 Code · ${self.label}`);
+      const now = yield* DateTime.now;
+      const linked: PeerLink = {
+        environmentId: peer.environmentId,
+        label: peer.label,
+        urls: origins,
+        access: input.access,
+        linkedAt: now,
+        expiresAt: DateTime.add(now, { seconds: issued.expires_in }),
+        lastReachedAt: now,
+        lastError: null,
+      };
+      // The token goes under a name of its own before the row points at it,
+      // so the row and its token are replaced together.
+      const secretName = yield* newSecretName;
+      yield* secrets
+        .set(secretName, new TextEncoder().encode(issued.access_token))
+        .pipe(Effect.catch(failStorage));
+      const urlsJson = yield* encodeUrls(origins).pipe(Effect.catch(failStorage));
+      const previous = yield* readRow(peer.environmentId);
+      yield* sql`
+        INSERT INTO peer_environment_links (
+          environment_id, secret_name, label, urls_json, access, linked_at, expires_at,
+          last_reached_at, last_error
+        ) VALUES (
+          ${linked.environmentId}, ${secretName}, ${linked.label}, ${urlsJson}, ${linked.access},
+          ${DateTime.formatIso(linked.linkedAt)}, ${DateTime.formatIso(linked.expiresAt)},
+          ${DateTime.formatIso(now)}, NULL
+        )
+        ON CONFLICT (environment_id) DO UPDATE SET
+          secret_name = excluded.secret_name,
+          label = excluded.label,
+          urls_json = excluded.urls_json,
+          access = excluded.access,
+          linked_at = excluded.linked_at,
+          expires_at = excluded.expires_at,
+          last_reached_at = excluded.last_reached_at,
+          last_error = NULL
+      `.pipe(Effect.catch(failStorage));

@@ -0,0 +1,393 @@
+import {
+  AuthMcpClientAccess,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/** How long a peer's descriptor may take before a route counts as unreachable. */
+const PROBE_TIMEOUT = Duration.seconds(3);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+const storageError = (cause: unknown) =>
+  new PeerLinkError({
+    reason: "storage",
+    message: `Peer links could not be read or saved: ${String(cause)}`,
+  });
+
+/** The base URL a peer is reached at, normalised to its origin. */
+const peerOrigin = (url: string) =>
+  Effect.try({
+    try: () => {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error("protocol");
+      return parsed.origin;
+    },
+    catch: () =>
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+  });
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  const secretName = (environmentId: EnvironmentId) =>
+    crypto.digest("SHA-256", new TextEncoder().encode(environmentId)).pipe(
+      Effect.map((digest) => `peer-link-${Hex.encode(digest)}`),
+      Effect.orDie,
+    );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(PROBE_TIMEOUT),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.mapError(storageError));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.mapError(storageError));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.mapError(storageError),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      const rejected = (message: string) =>
+        new PeerLinkError({ reason: "pairing_rejected", message });
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          Effect.mapError((error) =>
+            rejected(`The peer refused to register this environment: ${error.message}`),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(Effect.mapError((error) => rejected(error.message)));

@@ -0,0 +1,393 @@
+import {
+  AuthMcpClientAccess,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/** How long a peer's descriptor may take before a route counts as unreachable. */
+const PROBE_TIMEOUT = Duration.seconds(3);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+const storageError = (cause: unknown) =>
+  new PeerLinkError({
+    reason: "storage",
+    message: `Peer links could not be read or saved: ${String(cause)}`,
+  });

@@ -0,0 +1,247 @@
+import {
+  type EnvironmentId,
+  OrchestratorMcpFailure,
+  type PeerLinkError,
+  type ProviderInteractionMode,
+  type RuntimeMode,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as HttpBody from "effect/http/HttpBody";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+
+import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
+import * as PeerLinks from "./PeerLinks.ts";
+
+/** The only MCP protocol version a T3 Code `/mcp` registers. */
+const PROTOCOL_VERSION = "2025-06-18";
+
+/** The limits a call carries to the peer: the calling agent's modes here. */
+export interface PeerCallLimits {
+  readonly runtimeMode: RuntimeMode;
+  readonly interactionMode: ProviderInteractionMode;
+}
+
+/**
+ * Calls a linked environment's T3 MCP tools as this environment's outside
+ * agent. Each call carries the calling agent's limits in `T3-Mode-Limit`, so
+ * the peer enforces the narrower of those and the link's own access.
+ */
+export class PeerMcpClient extends Context.Service<
+  PeerMcpClient,
+  {
+    /** Calls `tool` on the peer and decodes its structured result with `success`. */
+    readonly call: <S extends Schema.Decoder<unknown>>(input: {
+      readonly environmentId: EnvironmentId;
+      readonly tool: string;
+      readonly arguments: Record<string, unknown>;
+      readonly limits: PeerCallLimits;
+      readonly success: S;
+    }) => Effect.Effect<S["Type"], OrchestratorMcpFailure>;
+  }
+>()("t3/peer/PeerMcpClient") {}
+
+const ToolCallResponse = Schema.Struct({
+  result: Schema.optional(
+    Schema.Struct({
+      content: Schema.Array(
+        Schema.Struct({ type: Schema.String, text: Schema.optional(Schema.String) }),
+      ),
+      structuredContent: Schema.optional(Schema.Unknown),
+      isError: Schema.optional(Schema.Boolean),
+    }),
+  ),
+  error: Schema.optional(Schema.Struct({ code: Schema.Number, message: Schema.String })),
+});
+const decodeToolCallResponse = Schema.decodeUnknownEffect(Schema.fromJsonString(ToolCallResponse));
+const decodeFailure = Schema.decodeUnknownOption(
+  Schema.fromJsonString(
+    Schema.Struct({ code: OrchestratorMcpFailure.fields.code, message: Schema.String }),
+  ),
+);
+
+/** A peer link problem, as the agent that asked hears it. */
+const fromLinkError = (error: PeerLinkError) =>
+  new OrchestratorMcpFailure({
+    code:
+      error.reason === "unknown_link"
+        ? "invalid_request"
+        : error.reason === "expired"
+          ? "capability_denied"
+          : "orchestration_error",
+    message: error.message,
+  });
+
+/** The body of an MCP response: JSON, or a single server-sent event carrying JSON. */
+const responseJson = (contentType: string | undefined, text: string) =>
+  contentType?.includes("text/event-stream") === true
+    ? text
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice("data:".length).trim())
+        .join("")
+    : text;
+
+const make = Effect.gen(function* () {
+  const links = yield* PeerLinks.PeerLinks;
+  const httpClient = yield* HttpClient.HttpClient;
+  // One MCP session per peer and address, reused across calls. The peer keeps
+  // sessions in memory, so a restart there answers 404 and we start a new one.
+  const sessions = yield* Ref.make<ReadonlyMap<string, string>>(new Map());
+
+  const post = (url: string, token: string, body: unknown, headers: Record<string, string>) =>
+    httpClient.execute(
+      HttpClientRequest.post(`${url}/mcp`).pipe(
+        HttpClientRequest.setHeaders({
+          accept: "application/json, text/event-stream",
+          authorization: `Bearer ${token}`,
+          ...headers,
+        }),
+        HttpClientRequest.setBody(HttpBody.text(JSON.stringify(body), "application/json")),
+      ),
+    );
+
+  const openSession = (url: string, token: string, limitHeader: Record<string, string>) =>
+    Effect.gen(function* () {
+      const initialized = yield* post(
+        url,
+        token,
+        {
+          jsonrpc: "2.0",
+          id: 0,
+          method: "initialize",
+          params: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "t3code-peer", version: "1" },
+          },
+        },
+        limitHeader,
+      );
+      const sessionId = initialized.headers["mcp-session-id"];
+      if (initialized.status !== 200 || sessionId === undefined) {
+        return yield* new OrchestratorMcpFailure({
+          code: initialized.status === 401 ? "capability_denied" : "orchestration_error",
+          message:
+            initialized.status === 401
+              ? "The linked environment no longer accepts this link. It may have been revoked there; link it again."
+              : `The linked environment refused to start an MCP session (HTTP ${initialized.status}).`,
+        });
+      }
+      yield* post(
+        url,
+        token,
+        { jsonrpc: "2.0", method: "notifications/initialized" },
+        { ...limitHeader, "mcp-session-id": sessionId, "mcp-protocol-version": PROTOCOL_VERSION },
+      );
+      return sessionId;
+    });
+
+  const call: PeerMcpClient["Service"]["call"] = (input) =>
+    Effect.gen(function* () {
+      const resolved = yield* links
+        .resolve(input.environmentId)
+        .pipe(Effect.mapError(fromLinkError));
+      const limitHeader = {
+        [McpInvocationContext.MODE_LIMIT_HEADER]: `${input.limits.runtimeMode}/${input.limits.interactionMode}`,
+      };
+      const sessionKey = `${input.environmentId} ${resolved.url}`;
+      const callOnce = (sessionId: string) =>
+        post(
+          resolved.url,
+          resolved.token,
+          {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: { name: input.tool, arguments: input.arguments },
+          },
+          { ...limitHeader, "mcp-session-id": sessionId, "mcp-protocol-version": PROTOCOL_VERSION },
+        );
+      const existing = (yield* Ref.get(sessions)).get(sessionKey);
+      const sessionId = existing ?? (yield* openSession(resolved.url, resolved.token, limitHeader));
+      let response = yield* callOnce(sessionId);
+      if (response.status === 404) {
+        const renewed = yield* openSession(resolved.url, resolved.token, limitHeader);
+        yield* Ref.update(sessions, (current) => new Map(current).set(sessionKey, renewed));
+        response = yield* callOnce(renewed);
+      } else if (existing === undefined) {
+        yield* Ref.update(sessions, (current) => new Map(current).set(sessionKey, sessionId));
+      }
+      if (response.status === 401) {
+        return yield* new OrchestratorMcpFailure({
+          code: "capability_denied",
+          message:
+            "The linked environment no longer accepts this link. It may have been revoked there; link it again.",
+        });
+      }
+      if (response.status !== 200) {
+        return yield* new OrchestratorMcpFailure({
+          code: "orchestration_error",
+          message: `The linked environment answered HTTP ${response.status}.`,
+        });
+      }
+      const body = yield* decodeToolCallResponse(
+        responseJson(response.headers["content-type"], yield* response.text),
+      ).pipe(
+        Effect.mapError(
+          () =>
+            new OrchestratorMcpFailure({
+              code: "orchestration_error",
+              message: "The linked environment answered in an unexpected shape.",
+            }),
+        ),
+      );
+      if (body.error !== undefined || body.result === undefined) {
+        return yield* new OrchestratorMcpFailure({
+          code: "invalid_request",
+          message: body.error?.message ?? "The linked environment returned no result.",
+        });
+      }
+      const text = body.result.content.map((part) => part.text ?? "").join("");
+      if (body.result.isError === true) {
+        // A refusal keeps the peer's own code, so the agent sees why it was refused.
+        const refused = decodeFailure(text);
+        return yield* refused._tag === "Some"
+          ? new OrchestratorMcpFailure({ code: refused.value.code, message: refused.value.message })
+          : new OrchestratorMcpFailure({
+              code: "orchestration_error",
+              message: text || "The linked environment refused the call.",
+            });
+      }
+      const success = Schema.fromJsonString(input.success);
+      return yield* Schema.decodeUnknownEffect(success)(text).pipe(

@@ -0,0 +1,393 @@
+import {
+  AuthMcpClientAccess,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/** How long a peer's descriptor may take before a route counts as unreachable. */
+const PROBE_TIMEOUT = Duration.seconds(3);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+const storageError = (cause: unknown) =>
+  new PeerLinkError({
+    reason: "storage",
+    message: `Peer links could not be read or saved: ${String(cause)}`,
+  });
+
+/** The base URL a peer is reached at, normalised to its origin. */
+const peerOrigin = (url: string) =>
+  Effect.try({
+    try: () => {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error("protocol");
+      return parsed.origin;
+    },
+    catch: () =>
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+  });
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  const secretName = (environmentId: EnvironmentId) =>
+    crypto.digest("SHA-256", new TextEncoder().encode(environmentId)).pipe(
+      Effect.map((digest) => `peer-link-${Hex.encode(digest)}`),
+      Effect.orDie,
+    );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(PROBE_TIMEOUT),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.mapError(storageError));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.mapError(storageError));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.mapError(storageError),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      const rejected = (message: string) =>
+        new PeerLinkError({ reason: "pairing_rejected", message });
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          Effect.mapError((error) =>
+            rejected(`The peer refused to register this environment: ${error.message}`),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(Effect.mapError((error) => rejected(error.message)));
+      const redirect = new URL(decided.redirectTo);

@@ -0,0 +1,466 @@
+import {
+  AuthMcpApprovalError,
+  AuthMcpClientAccess,
+  AuthMcpRegistrationError,
+  AuthMcpTokenError,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+import { isLocalLoopbackHost, isTailnetHost } from "@t3tools/shared/hostClassification";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/**
+ * How long a peer's descriptor may take before a route counts as unreachable.
+ * A tailnet or relayed route to a machine that is waking up takes longer.
+ */
+const probeTimeout = (origin: string) =>
+  isLocalLoopbackHost(new URL(origin).hostname) ? Duration.seconds(3) : Duration.seconds(10);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** The stored link, without asking the peer whether it answers. */
+    readonly get: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<Option.Option<PeerLink>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly secret_name: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+/** Fails with a fixed storage error; the cause goes to the log, not to the caller. */
+const failStorage = (cause: unknown) =>
+  Effect.logWarning("Peer link storage failed", cause).pipe(
+    Effect.andThen(
+      Effect.fail(
+        new PeerLinkError({
+          reason: "storage",
+          message:
+            "Linked environments could not be read or saved here. The server log has details.",
+        }),
+      ),
+    ),
+  );
+
+/**
+ * The base URL a peer is reached at, normalised to its origin. The pairing
+ * code and then the link's token travel to it, so plain http is accepted only
+ * where the network already encrypts: this machine, or a Tailscale address.
+ */
+const peerOrigin = (url: string) => {
+  const parsed = URL.parse(url);
+  if (parsed === null || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+    );
+  }
+  if (
+    parsed.protocol === "http:" &&
+    !isLocalLoopbackHost(parsed.hostname) &&
+    !isTailnetHost(parsed.hostname)
+  ) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
+      }),
+    );
+  }
+  return Effect.succeed(parsed.origin);
+};
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  /** A fresh name for one link's token; the row records it. */
+  const newSecretName = crypto.randomBytes(16).pipe(
+    Effect.map((bytes) => `peer-link-${Hex.encode(bytes)}`),
+    Effect.orDie,
+  );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(probeTimeout(origin)),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.catch(failStorage));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.catch(failStorage));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.catch(failStorage),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      const rejected = (message: string) =>
+        new PeerLinkError({ reason: "pairing_rejected", message });
+      // Only the peer's own refusals are rejections. A dropped connection or
+      // an answer this version cannot read is classified below.
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpRegistrationError), (error) =>
+            Effect.fail(
+              rejected(`The peer refused to register this environment: ${error.message}`),
+            ),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpApprovalError), (error) =>
+            Effect.fail(rejected(error.message)),
+          ),
+        );
+      const redirect = URL.parse(decided.redirectTo);
+      if (redirect === null) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${origin} answered the sign-in with an address this version cannot read. Update both environments.`,
+        });
+      }
+      const code = redirect.searchParams.get("code");
+      if (code === null || redirect.searchParams.get("state") !== state) {
+        return yield* rejected(
+          redirect.searchParams.get("error_description") ??
+            "The peer did not approve the link. Check the pairing code and try again.",
+        );
+      }
+      return yield* client.mcpOAuth
+        .token({
+          payload: {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: LINK_REDIRECT_URI,
+            client_id: registered.client_id,
+            code_verifier: verifier,
+            resource,
+          },
+        })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpTokenError), (error) =>
+            Effect.fail(rejected(`The peer refused the sign-in: ${error.message}`)),
+          ),
+        );
+    }).pipe(
+      // Endpoint errors are mapped above; what is left is the transport or an
+      // answer this version cannot decode.
+      Effect.catch((error) =>
+        error._tag === "PeerLinkError"
+          ? Effect.fail(error)
+          : Effect.fail(
+              new PeerLinkError({
+                reason: error._tag === "SchemaError" ? "incompatible" : "unreachable",
+                message:
+                  error._tag === "SchemaError"
+                    ? `${origin} answered in a shape this version does not understand. Update both environments.`
+                    : `${origin} stopped answering while linking.`,
+              }),
+            ),
+      ),
+    );
+
+  const link: PeerLinks["Service"]["link"] = (input) =>
+    Effect.gen(function* () {
+      const origins = yield* Effect.forEach(
+        [input.url, ...(input.alternateUrls ?? [])],
+        peerOrigin,
+      );
+      const primary = origins[0]!;
+      const descriptor = yield* describe(primary);
+      if (Option.isNone(descriptor)) {
+        return yield* new PeerLinkError({
+          reason: "not_a_t3_environment",
+          message: `Nothing at ${primary} answered as a T3 Code environment.`,
+        });
+      }
+      const peer = descriptor.value;
+      const self = yield* environment.getDescriptor;
+      if (peer.environmentId === self.environmentId) {
+        return yield* new PeerLinkError({
+          reason: "self",
+          message: "That address is this environment.",
+        });
+      }
+      if (peer.capabilities.mcpModeLimitHeader !== true) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${peer.label} runs a T3 Code version that cannot keep a linked agent's limits. Update it, then link again.`,
+        });
+      }
+      const issued = yield* signIn(primary, input, `T3 Code · ${self.label}`);
+      const now = yield* DateTime.now;
+      const linked: PeerLink = {
+        environmentId: peer.environmentId,
+        label: peer.label,
+        urls: origins,
+        access: input.access,
+        linkedAt: now,
+        expiresAt: DateTime.add(now, { seconds: issued.expires_in }),
+        lastReachedAt: now,
+        lastError: null,
+      };
+      // The token goes under a name of its own before the row points at it,
+      // so the row and its token are replaced together.
+      const secretName = yield* newSecretName;
+      yield* secrets
+        .set(secretName, new TextEncoder().encode(issued.access_token))
+        .pipe(Effect.catch(failStorage));
+      const urlsJson = yield* encodeUrls(origins).pipe(Effect.catch(failStorage));
+      const previous = yield* readRow(peer.environmentId);
+      yield* sql`
+        INSERT INTO peer_environment_links (
+          environment_id, secret_name, label, urls_json, access, linked_at, expires_at,
+          last_reached_at, last_error
+        ) VALUES (
+          ${linked.environmentId}, ${secretName}, ${linked.label}, ${urlsJson}, ${linked.access},
+          ${DateTime.formatIso(linked.linkedAt)}, ${DateTime.formatIso(linked.expiresAt)},
+          ${DateTime.formatIso(now)}, NULL
+        )
+        ON CONFLICT (environment_id) DO UPDATE SET
+          secret_name = excluded.secret_name,
+          label = excluded.label,
+          urls_json = excluded.urls_json,
+          access = excluded.access,
+          linked_at = excluded.linked_at,
+          expires_at = excluded.expires_at,
+          last_reached_at = excluded.last_reached_at,
+          last_error = NULL
+      `.pipe(Effect.catch(failStorage));
+      // Linking again replaces the old token. A racing link may leave its own
+      // behind; it is unused either way.
+      if (Option.isSome(previous) && previous.value.secret_name !== secretName) {
+        yield* secrets.remove(previous.value.secret_name).pipe(Effect.ignore);
+      }

@@ -0,0 +1,466 @@
+import {
+  AuthMcpApprovalError,
+  AuthMcpClientAccess,
+  AuthMcpRegistrationError,
+  AuthMcpTokenError,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+import { isLocalLoopbackHost, isTailnetHost } from "@t3tools/shared/hostClassification";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/**
+ * How long a peer's descriptor may take before a route counts as unreachable.
+ * A tailnet or relayed route to a machine that is waking up takes longer.
+ */
+const probeTimeout = (origin: string) =>
+  isLocalLoopbackHost(new URL(origin).hostname) ? Duration.seconds(3) : Duration.seconds(10);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** The stored link, without asking the peer whether it answers. */
+    readonly get: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<Option.Option<PeerLink>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly secret_name: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+/** Fails with a fixed storage error; the cause goes to the log, not to the caller. */
+const failStorage = (cause: unknown) =>
+  Effect.logWarning("Peer link storage failed", cause).pipe(
+    Effect.andThen(
+      Effect.fail(
+        new PeerLinkError({
+          reason: "storage",
+          message:
+            "Linked environments could not be read or saved here. The server log has details.",
+        }),
+      ),
+    ),
+  );
+
+/**
+ * The base URL a peer is reached at, normalised to its origin. The pairing
+ * code and then the link's token travel to it, so plain http is accepted only
+ * where the network already encrypts: this machine, or a Tailscale address.
+ */
+const peerOrigin = (url: string) => {
+  const parsed = URL.parse(url);
+  if (parsed === null || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+    );
+  }
+  if (
+    parsed.protocol === "http:" &&
+    !isLocalLoopbackHost(parsed.hostname) &&
+    !isTailnetHost(parsed.hostname)
+  ) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
+      }),
+    );
+  }
+  return Effect.succeed(parsed.origin);
+};
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  /** A fresh name for one link's token; the row records it. */
+  const newSecretName = crypto.randomBytes(16).pipe(
+    Effect.map((bytes) => `peer-link-${Hex.encode(bytes)}`),
+    Effect.orDie,
+  );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(

@@ -0,0 +1,393 @@
+import {
+  AuthMcpClientAccess,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { HttpClient } from "effect/http";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/** How long a peer's descriptor may take before a route counts as unreachable. */
+const PROBE_TIMEOUT = Duration.seconds(3);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+const storageError = (cause: unknown) =>
+  new PeerLinkError({
+    reason: "storage",
+    message: `Peer links could not be read or saved: ${String(cause)}`,
+  });
+
+/** The base URL a peer is reached at, normalised to its origin. */
+const peerOrigin = (url: string) =>
+  Effect.try({
+    try: () => {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error("protocol");
+      return parsed.origin;
+    },
+    catch: () =>
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+  });
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  const secretName = (environmentId: EnvironmentId) =>
+    crypto.digest("SHA-256", new TextEncoder().encode(environmentId)).pipe(
+      Effect.map((digest) => `peer-link-${Hex.encode(digest)}`),
+      Effect.orDie,
+    );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(PROBE_TIMEOUT),
+      Effect.option,
+    );
+
+  const toLink = (row: PeerLinkRow) =>
+    Effect.gen(function* () {
+      return {
+        environmentId: EnvironmentId.make(row.environment_id),
+        label: row.label,
+        urls: yield* decodeUrls(row.urls_json),
+        access: yield* decodeAccess(row.access),
+        linkedAt: DateTime.makeUnsafe(row.linked_at),
+        expiresAt: DateTime.makeUnsafe(row.expires_at),
+        lastReachedAt:
+          row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+        lastError: row.last_error,
+      } satisfies PeerLink;
+    }).pipe(Effect.mapError(storageError));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.mapError(storageError));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.mapError(storageError),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = (origin: string, input: PeerLinkCreateInput, clientName: string) =>
+    Effect.gen(function* () {
+      const client = yield* clientFor(origin);
+      const rejected = (message: string) =>
+        new PeerLinkError({ reason: "pairing_rejected", message });
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          Effect.mapError((error) =>
+            rejected(`The peer refused to register this environment: ${error.message}`),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(Effect.mapError((error) => rejected(error.message)));
+      const redirect = new URL(decided.redirectTo);
+      const code = redirect.searchParams.get("code");
+      if (code === null || redirect.searchParams.get("state") !== state) {
+        return yield* rejected(
+          redirect.searchParams.get("error_description") ??
+            "The peer did not approve the link. Check the pairing code and try again.",
+        );
+      }
+      return yield* client.mcpOAuth
+        .token({
+          payload: {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: LINK_REDIRECT_URI,
+            client_id: registered.client_id,
+            code_verifier: verifier,
+            resource,
+          },
+        })
+        .pipe(
+          Effect.mapError((error) => rejected(`The peer refused the sign-in: ${error.message}`)),
+        );
+    }).pipe(
+      // Endpoint errors are mapped above; what is left is the transport or an
+      // answer this version cannot decode.
+      Effect.catch((error) =>
+        error._tag === "PeerLinkError"
+          ? Effect.fail(error)
+          : Effect.fail(
+              new PeerLinkError({
+                reason: error._tag === "SchemaError" ? "incompatible" : "unreachable",
+                message:
+                  error._tag === "SchemaError"
+                    ? `${origin} answered in a shape this version does not understand. Update both environments.`
+                    : `${origin} stopped answering while linking.`,
+              }),
+            ),
+      ),
+    );
+
+  const link: PeerLinks["Service"]["link"] = (input) =>
+    Effect.gen(function* () {
+      const origins = yield* Effect.forEach(
+        [input.url, ...(input.alternateUrls ?? [])],
+        peerOrigin,
+      );
+      const primary = origins[0]!;
+      const descriptor = yield* describe(primary);
+      if (Option.isNone(descriptor)) {
+        return yield* new PeerLinkError({
+          reason: "not_a_t3_environment",
+          message: `Nothing at ${primary} answered as a T3 Code environment.`,
+        });
+      }
+      const peer = descriptor.value;
+      const self = yield* environment.getDescriptor;
+      if (peer.environmentId === self.environmentId) {
+        return yield* new PeerLinkError({
+          reason: "self",
+          message: "That address is this environment.",
+        });
+      }
+      if (peer.capabilities.mcpModeLimitHeader !== true) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${peer.label} runs a T3 Code version that cannot keep a linked agent's limits. Update it, then link again.`,
+        });
+      }
+      const issued = yield* signIn(primary, input, `T3 Code · ${self.label}`);
+      const now = yield* DateTime.now;
+      const linked: PeerLink = {
+        environmentId: peer.environmentId,
+        label: peer.label,
+        urls: origins,
+        access: input.access,
+        linkedAt: now,
+        expiresAt: DateTime.add(now, { seconds: issued.expires_in }),
+        lastReachedAt: now,
+        lastError: null,
+      };
+      yield* secrets

@@ -132,6 +133,7 @@ export const migrationEntries = [
   [61, "PullRequestReviewGuides", Migration0061],
   [62, "ThreadFailureLookupIndex", Migration0062],
   [63, "DropUnusedV1Projections", Migration0063],
+  [64, "PeerLinks", Migration0064],

@@ -0,0 +1,489 @@
+import {
+  AuthMcpClientAccess,
+  AuthMcpRegistrationError,
+  AuthMcpTokenError,
+  EnvironmentHttpApi,
+  EnvironmentId,
+  type PeerLink,
+  type PeerLinkCreateInput,
+  PeerLinkError,
+  type PeerLinkStatus,
+  type PeerLinkSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Hex from "effect/encoding/Hex";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+import { isLocalLoopbackHost, isTailnetHost } from "@t3tools/shared/hostClassification";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+
+/** The redirect registered for a link. Nothing ever listens there: the code comes back in the response. */
+const LINK_REDIRECT_URI = "http://127.0.0.1/t3code-peer-link";
+/**
+ * How long a peer's descriptor may take before a route counts as unreachable.
+ * A tailnet or relayed route to a machine that is waking up takes longer.
+ */
+const probeTimeout = (origin: string) =>
+  isLocalLoopbackHost(new URL(origin).hostname) ? Duration.seconds(3) : Duration.seconds(10);
+
+/** A usable link: where to reach the peer and the token to send there. */
+export interface ResolvedPeerLink {
+  readonly link: PeerLink;
+  /** The first address that answered as this peer. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * Links from this environment to others. Linking signs this environment in to
+ * the peer's `/mcp` as an outside agent with a pairing code from the peer, the
+ * same MCP OAuth flow an outside agent uses, without a browser. The peer's
+ * session token is kept in the server secret store; the table keeps the rest.
+ */
+export class PeerLinks extends Context.Service<
+  PeerLinks,
+  {
+    readonly link: (input: PeerLinkCreateInput) => Effect.Effect<PeerLink, PeerLinkError>;
+    readonly list: Effect.Effect<ReadonlyArray<PeerLinkSummary>, PeerLinkError>;
+    /** The stored link, without asking the peer whether it answers. */
+    readonly get: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<Option.Option<PeerLink>, PeerLinkError>;
+    /** Forgets the link here. The peer still lists the session until it is revoked there. */
+    readonly unlink: (environmentId: EnvironmentId) => Effect.Effect<boolean, PeerLinkError>;
+    /** An address that answers as the linked peer, with its token, ready to call. */
+    readonly resolve: (
+      environmentId: EnvironmentId,
+    ) => Effect.Effect<ResolvedPeerLink, PeerLinkError>;
+    /** Records the outcome of a call, so listing shows whether the peer answered last time. */
+    readonly recordOutcome: (
+      environmentId: EnvironmentId,
+      outcome: { readonly error: string | null },
+    ) => Effect.Effect<void>;
+  }
+>()("t3/peer/PeerLinks") {}
+
+interface PeerLinkRow {
+  readonly environment_id: string;
+  readonly secret_name: string;
+  readonly label: string;
+  readonly urls_json: string;
+  readonly access: string;
+  readonly linked_at: string;
+  readonly expires_at: string;
+  readonly last_reached_at: string | null;
+  readonly last_error: string | null;
+}
+
+const decodeUrls = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const encodeUrls = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+const decodeAccess = Schema.decodeUnknownEffect(AuthMcpClientAccess);
+
+/** Fails with a fixed storage error that keeps its cause; the log gets the details. */
+const failStorage = (cause: unknown) =>
+  Effect.logWarning("Peer link storage failed", cause).pipe(
+    Effect.andThen(
+      Effect.fail(
+        new PeerLinkError({
+          reason: "storage",
+          message:
+            "Linked environments could not be read or saved here. The server log has details.",
+          cause,
+        }),
+      ),
+    ),
+  );
+
+/**
+ * The base URL a peer is reached at, normalised to its origin. The pairing
+ * code and then the link's token travel to it, so plain http is accepted only
+ * where the network already encrypts: this machine, or a Tailscale address.
+ */
+const peerOrigin = (url: string) => {
+  const parsed = URL.parse(url);
+  if (parsed === null || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is not an http or https address.`,
+      }),
+    );
+  }
+  if (
+    parsed.protocol === "http:" &&
+    !isLocalLoopbackHost(parsed.hostname) &&
+    !isTailnetHost(parsed.hostname)
+  ) {
+    return Effect.fail(
+      new PeerLinkError({
+        reason: "unreachable",
+        message: `${url} is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
+      }),
+    );
+  }
+  return Effect.succeed(parsed.origin);
+};
+
+const make = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const crypto = yield* Crypto.Crypto;
+  const httpClient = yield* HttpClient.HttpClient;
+  const environment = yield* ServerEnvironment.ServerEnvironment;
+
+  /** A fresh name for one link's token; the row records it. */
+  const newSecretName = crypto.randomBytes(16).pipe(
+    Effect.map((bytes) => `peer-link-${Hex.encode(bytes)}`),
+    Effect.orDie,
+  );
+
+  // Only the origin `peerOrigin` checked may receive a pairing code or token:
+  // a redirect could forward them anywhere, including plain http.
+  const peerHttpClient = HttpClient.transform(httpClient, (response) =>
+    Effect.provideService(response, FetchHttpClient.RequestInit, { redirect: "manual" }),
+  );
+
+  const clientFor = (origin: string) =>
+    HttpApiClient.make(EnvironmentHttpApi, { baseUrl: origin }).pipe(
+      Effect.provideService(HttpClient.HttpClient, peerHttpClient),
+    );
+
+  /** The environment answering at `origin`, or nothing when it does not answer as T3 Code. */
+  const describe = (origin: string) =>
+    clientFor(origin).pipe(
+      Effect.flatMap((client) => client.metadata.descriptor()),
+      Effect.timeout(probeTimeout(origin)),
+      Effect.option,
+    );
+
+  const toLink = Effect.fn("PeerLinks.toLink")(function* (row: PeerLinkRow) {
+    return {
+      environmentId: EnvironmentId.make(row.environment_id),
+      label: row.label,
+      urls: yield* decodeUrls(row.urls_json),
+      access: yield* decodeAccess(row.access),
+      linkedAt: DateTime.makeUnsafe(row.linked_at),
+      expiresAt: DateTime.makeUnsafe(row.expires_at),
+      lastReachedAt: row.last_reached_at === null ? null : DateTime.makeUnsafe(row.last_reached_at),
+      lastError: row.last_error,
+    } satisfies PeerLink;
+  }, Effect.catch(failStorage));
+
+  const readRows = sql<PeerLinkRow>`
+    SELECT * FROM peer_environment_links ORDER BY label, environment_id
+  `.pipe(Effect.catch(failStorage));
+
+  const readRow = (environmentId: EnvironmentId) =>
+    sql<PeerLinkRow>`
+      SELECT * FROM peer_environment_links WHERE environment_id = ${environmentId}
+    `.pipe(
+      Effect.catch(failStorage),
+      Effect.map((rows) => Option.fromNullishOr(rows[0])),
+    );
+
+  /** Signs in to the peer's `/mcp` with a pairing code: register, decide, exchange. */
+  const signIn = Effect.fn("PeerLinks.signIn")(
+    function* (origin: string, input: PeerLinkCreateInput, clientName: string) {
+      const client = yield* clientFor(origin);
+      // Only the peer's own refusals are rejections. A dropped connection or
+      // an answer this version cannot read is classified below.
+      const registered = yield* client.mcpOAuth
+        .register({ payload: { client_name: clientName, redirect_uris: [LINK_REDIRECT_URI] } })
+        .pipe(
+          // A plain Schema.Error has no tag to catch by.
+          Effect.catchIf(Schema.is(AuthMcpRegistrationError), (error) =>
+            Effect.fail(
+              new PeerLinkError({
+                reason: "pairing_rejected",
+                message: `The peer refused to register this environment: ${error.message}`,
+              }),
+            ),
+          ),
+        );
+      const verifier = Base64Url.encode(yield* crypto.randomBytes(32).pipe(Effect.orDie));
+      const challenge = Base64Url.encode(
+        yield* crypto.digest("SHA-256", new TextEncoder().encode(verifier)).pipe(Effect.orDie),
+      );
+      const state = Base64Url.encode(yield* crypto.randomBytes(16).pipe(Effect.orDie));
+      const resource = `${origin}/mcp`;
+      const decided = yield* client.mcpOAuth
+        .decision({
+          payload: {
+            authorization: {
+              response_type: "code",
+              client_id: registered.client_id,
+              redirect_uri: LINK_REDIRECT_URI,
+              code_challenge: challenge,
+              code_challenge_method: "S256",
+              state,
+              resource,
+            },
+            decision: { _tag: "pairing-code", access: input.access, code: input.pairingCode },
+          },
+        })
+        .pipe(
+          Effect.catchTags({
+            AuthMcpApprovalError: (error) =>
+              Effect.fail(
+                new PeerLinkError({ reason: "pairing_rejected", message: error.message }),
+              ),
+          }),
+        );
+      const redirect = URL.parse(decided.redirectTo);
+      if (redirect === null) {
+        return yield* new PeerLinkError({
+          reason: "incompatible",
+          message: `${origin} answered the sign-in with an address this version cannot read. Update both environments.`,
+        });
+      }
+      const code = redirect.searchParams.get("code");
+      if (code === null || redirect.searchParams.get("state") !== state) {
+        return yield* new PeerLinkError({
+          reason: "pairing_rejected",
+          message:
+            redirect.searchParams.get("error_description") ??
+            "The peer did not approve the link. Check the pairing code and try again.",
+        });
+      }
+      return yield* client.mcpOAuth
+        .token({
+          payload: {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: LINK_REDIRECT_URI,
+            client_id: registered.client_id,
+            code_verifier: verifier,
+            resource,
+          },
+        })
+        .pipe(
+          Effect.catchIf(Schema.is(AuthMcpTokenError), (error) =>
+            Effect.fail(
+              new PeerLinkError({
+                reason: "pairing_rejected",
+                message: `The peer refused the sign-in: ${error.message}`,
+              }),
+            ),
+          ),
+        );
+    },
+    (effect, origin, input, clientName) =>
+      effect.pipe(
+        // Endpoint errors are mapped above; what is left is the transport or an
+        // answer this version cannot decode.
+        Effect.catchTags({
+          SchemaError: (cause) =>
+            Effect.fail(
+              new PeerLinkError({
+                reason: "incompatible",
+                message: `${origin} answered in a shape this version does not understand. Update both environments.`,
+                cause,
+              }),
+            ),
+          HttpClientError: (cause) =>
+            Effect.fail(
+              new PeerLinkError({
+                reason: "unreachable",
+                message: `${origin} stopped answering while linking.`,
+                cause,
+              }),
+            ),
+        }),
+      ),
+  );
+
+  const link: PeerLinks["Service"]["link"] = Effect.fn("PeerLinks.link")(function* (input) {
+    const origins = yield* Effect.forEach([input.url, ...(input.alternateUrls ?? [])], peerOrigin);
+    const primary = origins[0]!;
+    const descriptor = yield* describe(primary);
+    if (Option.isNone(descriptor)) {
+      return yield* new PeerLinkError({
+        reason: "not_a_t3_environment",
+        message: `Nothing at ${primary} answered as a T3 Code environment.`,
+      });
+    }
+    const peer = descriptor.value;
+    const self = yield* environment.getDescriptor;
+    if (peer.environmentId === self.environmentId) {
+      return yield* new PeerLinkError({
+        reason: "self",
+        message: "That address is this environment.",
+      });
+    }
+    if (peer.capabilities.mcpModeLimitHeader !== true) {
+      return yield* new PeerLinkError({
+        reason: "incompatible",
+        message: `${peer.label} runs a T3 Code version that cannot keep a linked agent's limits. Update it, then link again.`,
+      });
+    }
+    const issued = yield* signIn(primary, input, `T3 Code · ${self.label}`);
+    const now = yield* DateTime.now;
+    const linked: PeerLink = {
+      environmentId: peer.environmentId,
+      label: peer.label,
+      urls: origins,
+      access: input.access,
+      linkedAt: now,
+      expiresAt: DateTime.add(now, { seconds: issued.expires_in }),
+      lastReachedAt: now,
+      lastError: null,
+    };
+    // The token goes under a name of its own before the row points at it,
+    // so the row and its token are replaced together.
+    const secretName = yield* newSecretName;
+    yield* secrets
+      .set(secretName, new TextEncoder().encode(issued.access_token))
+      .pipe(Effect.catch(failStorage));
+    const urlsJson = yield* encodeUrls(origins).pipe(Effect.catch(failStorage));
+    const previous = yield* readRow(peer.environmentId);
+    yield* sql`
+        INSERT INTO peer_environment_links (
+          environment_id, secret_name, label, urls_json, access, linked_at, expires_at,
+          last_reached_at, last_error
+        ) VALUES (
+          ${linked.environmentId}, ${secretName}, ${linked.label}, ${urlsJson}, ${linked.access},
+          ${DateTime.formatIso(linked.linkedAt)}, ${DateTime.formatIso(linked.expiresAt)},
+          ${DateTime.formatIso(now)}, NULL
+        )
+        ON CONFLICT (environment_id) DO UPDATE SET
+          secret_name = excluded.secret_name,
+          label = excluded.label,
+          urls_json = excluded.urls_json,
+          access = excluded.access,
+          linked_at = excluded.linked_at,
+          expires_at = excluded.expires_at,
+          last_reached_at = excluded.last_reached_at,
+          last_error = NULL
+      `.pipe(Effect.catch(failStorage));
+    // Linking again replaces the old token. A racing link may leave its own
+    // behind; it is unused either way.
+    if (Option.isSome(previous) && previous.value.secret_name !== secretName) {
+      yield* secrets.remove(previous.value.secret_name).pipe(Effect.ignore);
+    }
+    return linked;
+  });
+
+  const statusOf = (link: PeerLink, now: DateTime.Utc) =>
+    DateTime.isLessThanOrEqualTo(link.expiresAt, now)
+      ? Effect.succeed<PeerLinkStatus>("expired")
+      : Effect.findFirst(link.urls, (url) =>
+          describe(url).pipe(
+            Effect.map(
+              (found) => Option.isSome(found) && found.value.environmentId === link.environmentId,
+            ),
+          ),
+        ).pipe(
+          Effect.map((answered): PeerLinkStatus =>
+            Option.isSome(answered) ? "reachable" : "unreachable",
+          ),
+        );
+
+  const list: PeerLinks["Service"]["list"] = Effect.gen(function* () {
+    const links = yield* Effect.forEach(yield* readRows, toLink);
+    const now = yield* DateTime.now;
+    return yield* Effect.forEach(
+      links,
+      (link) => statusOf(link, now).pipe(Effect.map((status) => ({ ...link, status }))),
+      { concurrency: "unbounded" },
+    );
+  });
+
+  const get: PeerLinks["Service"]["get"] = (environmentId) =>
+    readRow(environmentId).pipe(
+      Effect.flatMap(
+        Option.match({
+          onNone: () => Effect.succeed(Option.none()),
+          onSome: (row) => Effect.map(toLink(row), Option.some),
+        }),
+      ),
+    );
+
+  const unlink: PeerLinks["Service"]["unlink"] = Effect.fn("PeerLinks.unlink")(
+    function* (environmentId) {
+      const deleted = yield* sql<{ secret_name: string }>`
+        DELETE FROM peer_environment_links WHERE environment_id = ${environmentId}
+        RETURNING secret_name
+      `.pipe(Effect.catch(failStorage));
+      for (const row of deleted) {
+        yield* secrets.remove(row.secret_name).pipe(Effect.catch(failStorage));
+      }
+      return deleted.length > 0;
+    },
+  );
+
+  const resolve: PeerLinks["Service"]["resolve"] = Effect.fn("PeerLinks.resolve")(
+    function* (environmentId) {
+      const row = yield* readRow(environmentId);
+      if (Option.isNone(row)) {
+        return yield* new PeerLinkError({
+          reason: "unknown_link",
+          message: `This environment is not linked to ${environmentId}. t3_environment_links lists the linked ones.`,
+        });
+      }
+      const link = yield* toLink(row.value);
+      if (DateTime.isLessThanOrEqualTo(link.expiresAt, yield* DateTime.now)) {
+        return yield* new PeerLinkError({
+          reason: "expired",
+          message: `The link to ${link.label} expired. Link it again with a new pairing code from ${link.label}.`,
+        });
+      }
+      const stored = yield* secrets.get(row.value.secret_name).pipe(Effect.catch(failStorage));
+      if (Option.isNone(stored)) {
+        return yield* new PeerLinkError({
+          reason: "unknown_link",
+          message: `The link to ${link.label} lost its credential. Link it again.`,
+        });
+      }
+      // The token goes only to an address that proves it is this peer, so a
+      // reused LAN address or a moved hostname never receives it.
+      const url = yield* Effect.findFirst(link.urls, (candidate) =>
+        describe(candidate).pipe(
+          Effect.map(
+            (found) => Option.isSome(found) && found.value.environmentId === environmentId,