feat(server,web,mobile): an agent sets up a link to another environment#17129

@@ -0,0 +1,278 @@
+import {
+  type AuthMcpClientAccess,
+  type EnvironmentId,
+  type EnvironmentMachineKind,
+  type OrchestrationV2TurnItem,
+  type PeerLinkRequestAnswerInput,
+  resolveEnvironmentMachineKind,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+
+import type { EnvironmentPresentation } from "./connection/presentation.ts";
+import { connectionRoutes, routeHttpBaseUrl } from "./connection/routes.ts";
+import type { RelayDiscoveredEnvironment } from "./relay/discovery.ts";
+
+export type LinkRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "link_request" }>;
+
+/** The access a request opens with: the agent's suggestion, else supervised. */
+export const linkRequestDefaultAccess = (
+  item: Pick<LinkRequestItem, "requestedAccess">,
+): AuthMcpClientAccess => item.requestedAccess ?? "approval-required";
+
+/** What the card calls the other environment: its own name, else the address asked for. */
+export const linkRequestTargetName = (item: Pick<LinkRequestItem, "label" | "url">): string =>
+  item.label?.trim() || item.url || "a machine";
+
+/** A machine the user could link a thread's environment to. */
+export interface LinkableMachine {
+  readonly environmentId: EnvironmentId;
+  readonly label: string;
+  readonly machine: EnvironmentMachineKind;
+  readonly connected: boolean;
+  /** Found on the user's T3 Connect account rather than saved in this client. */
+  readonly connectOnly: boolean;
+  /** Whether the thread's environment already has a link to it. */
+  readonly linked: boolean;
+  /**
+   * Where the client knows it answers, most preferred first: the addresses it
+   * reports, then its saved routes, a T3 Connect route by its Connect address.
+   * The server keeps only those that answer as this machine. Empty for a
+   * machine reached only over SSH, whose forward lives in this client.
+   */
+  readonly urls: ReadonlyArray<string>;
+}
+
+/**
+ * The machines in the client's catalog other than the thread's own
+ * environment, in catalog order, then the ones only T3 Connect knows.
+ * `linkedIds` are the environments the thread's environment links to already.
+ * `connect` is what relay discovery found, by environment id: a server reaches
+ * a machine there as a browser does, so its Connect address is a usable one.
+ */
+export function linkableMachines(input: {
+  readonly environments: ReadonlyArray<
+    EnvironmentPresentation & { readonly environmentId: EnvironmentId }
+  >;
+  readonly threadEnvironmentId: EnvironmentId;
+  readonly linkedIds: ReadonlySet<EnvironmentId>;
+  readonly connect: ReadonlyMap<string, RelayDiscoveredEnvironment>;
+}): ReadonlyArray<LinkableMachine> {
+  const saved = input.environments
+    .filter((environment) => environment.environmentId !== input.threadEnvironmentId)
+    .map((environment) => {
+      const reported = (environment.serverConfig?.directEndpoints ?? []).map(
+        (endpoint) => endpoint.httpBaseUrl,
+      );
+      const connect = input.connect.get(environment.environmentId)?.environment.endpoint;
+      const routes = connectionRoutes(environment.entry).flatMap((route) => {
+        const url =
+          route.target._tag === "RelayConnectionTarget"
+            ? connect?.httpBaseUrl
+            : routeHttpBaseUrl(route);
+        return url === null || url === undefined ? [] : [url];
+      });
+      return {
+        environmentId: environment.environmentId,
+        label: environment.entry.target.label,
+        machine: resolveEnvironmentMachineKind(environment.serverConfig),
+        connected: environment.connection.phase === "connected",
+        connectOnly: false,
+        linked: input.linkedIds.has(environment.environmentId),
+        urls: [...new Set([...reported, ...routes])],

@@ -0,0 +1,394 @@
+/**
+ * PeerLinkRequests - links an agent asks the user to make.
+ *
+ * The agent rarely knows where the user's machines answer, so it usually
+ * names none: the user picks the machine in a card, along with the access,
+ * and their client answers with the addresses it knows for that machine and
+ * a pairing code from it, which the client mints with its own session there
+ * or the user pastes. The code goes straight
+ * to `PeerLinks.link` and is never recorded, so it never reaches the
+ * transcript, projections, or the agent's context.
+ *
+ * Asking does not wait: provider CLIs abandon a tool call after a few
+ * minutes, and a person may answer much later. The card stays open until the
+ * user answers it or stops or archives the thread, and the answer reaches the
+ * agent as a notification in its thread.
+ *
+ * @module PeerLinkRequests
+ */
+import {
+  CommandId,
+  MessageId,
+  type NodeId,
+  type OrchestrationV2Notification,
+  type OrchestrationV2TurnItem,
+  type OrchestratorMcpEnvironmentLinkInput,
+  type OrchestratorMcpEnvironmentLinkResult,
+  OrchestratorMcpFailure,
+  type PeerLink,
+  PeerLinkError,
+  PeerLinkRequestError,
+  type PeerLinkRequestAnswerInput,
+  type RunId,
+  type ThreadId,
+  TurnItemId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Semaphore from "effect/Semaphore";
+
+import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
+import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
+import * as PeerLinks from "./PeerLinks.ts";
+
+type LinkRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "link_request" }>;
+
+/** The request as it was asked, which every update of its card repeats. */
+type LinkRequestAsk = Pick<
+  LinkRequestItem,
+  "id" | "threadId" | "url" | "reason" | "environmentId" | "label" | "hint" | "requestedAccess"
+> & { readonly runId: RunId; readonly nodeId: NodeId };
+
+/** The notification that tells the agent how its card ended. */
+type LinkRequestWake = {
+  readonly messageId: MessageId;
+  readonly text: string;
+  readonly notification: OrchestrationV2Notification;
+};
+
+/** What a card update may change. */
+type LinkRequestOutcome = Pick<
+  LinkRequestItem,
+  "linkStatus" | "linkedEnvironmentId" | "linkedLabel" | "linkedAccess" | "failure"
+>;
+
+const failure = (code: OrchestratorMcpFailure["code"], message: string) =>
+  new OrchestratorMcpFailure({ code, message });
+
+const errorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : typeof error === "string" ? error : "unknown error";
+
+export class PeerLinkRequests extends Context.Service<
+  PeerLinkRequests,
+  {
+    /**
+     * Shows a link card in the calling thread and returns at once. A retry
+     * with the same clientRequestId returns the card's current outcome.
+     */
+    readonly request: (
+      scope: McpInvocationContext.McpInvocationScope,
+      input: OrchestratorMcpEnvironmentLinkInput,
+    ) => Effect.Effect<OrchestratorMcpEnvironmentLinkResult, OrchestratorMcpFailure>;
+    /**
+     * Answers a pending card and tells the agent. Linking uses the pairing
+     * code once; a link the other environment refuses closes the card as
+     * failed, with its reason.
+     */
+    readonly answer: (
+      input: PeerLinkRequestAnswerInput,
+    ) => Effect.Effect<void, PeerLinkRequestError>;
+  }
+>()("t3/peer/PeerLinkRequests") {}
+
+const make = Effect.gen(function* () {
+  const threadManagement = yield* ThreadManagementService.ThreadManagementService;
+  const peerLinks = yield* PeerLinks.PeerLinks;
+  const crypto = yield* Crypto.Crypto;
+
+  const readCard = (threadId: ThreadId, turnItemId: TurnItemId) =>
+    threadManagement
+      .getThreadRecords(threadId, ["turnItems"], {
+        turnItemTypes: ["link_request"],
+        messageRoles: [],
+      })
+      .pipe(
+        Effect.map((records) => {
+          const item = records.turnItems.find((candidate) => candidate.id === turnItemId);
+          // A deleted thread's cards went with it.
+          return item?.type === "link_request" && records.thread.deletedAt === null
+            ? item
+            : undefined;
+        }),
+      );
+
+  const record = (
+    card: LinkRequestAsk,
+    outcome: LinkRequestOutcome,
+    commandId: CommandId,
+    wake?: LinkRequestWake,
+  ) =>
+    threadManagement.dispatch({
+      type: "link_request.record",
+      commandId,
+      threadId: card.threadId,
+      runId: card.runId,
+      nodeId: card.nodeId,
+      turnItemId: card.id,
+      ...(card.url === undefined ? {} : { url: card.url }),
+      reason: card.reason,
+      ...(card.environmentId === undefined ? {} : { environmentId: card.environmentId }),
+      ...(card.label === undefined ? {} : { label: card.label }),
+      ...(card.hint === undefined ? {} : { hint: card.hint }),
+      ...(card.requestedAccess === undefined ? {} : { requestedAccess: card.requestedAccess }),
+      ...outcome,
+      ...(wake === undefined ? {} : { wake }),
+    });
+
+  const request: PeerLinkRequests["Service"]["request"] = (scope, input) =>
+    Effect.gen(function* () {
+      // The card is shown in, and answered from, the caller's own thread.
+      const threadScope = yield* McpInvocationContext.requireThreadScope(
+        scope,
+        "t3_environment_link",
+      );
+      const threadId = threadScope.thread.threadId;
+      const unreadable = (error: unknown) =>
+        failure("orchestration_error", `Unable to read the link request: ${errorMessage(error)}`);
+      if (input.url !== undefined && input.environmentId !== undefined) {
+        return yield* failure(
+          "invalid_request",
+          "Pass either environmentId or url, not both. Pass neither to let the user pick the machine.",
+        );
+      }
+      // A machine already linked needs no card: the agent can use it now.
+      if (input.environmentId !== undefined) {
+        const linked = yield* peerLinks
+          .get(input.environmentId)
+          .pipe(Effect.mapError((error) => failure("orchestration_error", error.message)));
+        if (Option.isSome(linked)) {
+          return {
+            status: "linked",
+            environmentId: linked.value.environmentId,
+            label: linked.value.label,
+            access: linked.value.access,
+          } as const;
+        }
+      }
+      const key = input.clientRequestId ?? (yield* crypto.randomUUIDv4.pipe(Effect.orDie));
+      // Turn item ids are global; scope the key to this thread. A retry with
+      // the same clientRequestId finds this card and records nothing.
+      const turnItemId = TurnItemId.make(
+        `turn-item:link-request:${encodeURIComponent(threadId)}:${encodeURIComponent(key)}`,

@@ -0,0 +1,42 @@
+import { mintPeerPairingCode } from "@t3tools/client-runtime/state/peerPairingCode";
+import type { EnvironmentId } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { Atom, AtomRegistry } from "effect/reactivity";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+import { appAtomRegistry } from "./atom-registry";
+import { environmentSession } from "./session";
+
+// Each read mints a new one-use code; nothing keeps one once it is read.
+const peerPairingCodeAtom = Atom.family((environmentId: EnvironmentId) =>
+  connectionAtomRuntime
+    .atom((get) => {
+      const prepared = Option.getOrNull(
+        get(environmentSession.preparedConnectionValueAtom(environmentId)),
+      );
+      if (prepared === null) return Effect.never;
+      return mintPeerPairingCode(prepared);
+    })
+    .pipe(Atom.withLabel(`mobile-peer-pairing-code:${environmentId}`)),
+);
+
+/**
+ * A fresh pairing code minted on `environmentId` with this client's session
+ * there, for answering a link request. Fails with `PeerPairingCodeError` when
+ * the session may not create one.
+ */
+export function mintPairingCodeOn(environmentId: EnvironmentId): Promise<string> {
+  const atom = peerPairingCodeAtom(environmentId);

@@ -0,0 +1,471 @@
+import { useAtomValue } from "@effect/atom-react";
+import {
+  type LinkableMachine,
+  linkRequestAnswerInput,
+  linkRequestDefaultAccess,
+  linkRequestDisplay,
+  linkRequestFailureMessage,
+  linkRequestInitialMachine,
+  type LinkRequestItem,
+  linkRequestTargetName,
+  rankMachinesByHint,
+} from "@t3tools/client-runtime/link-request";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import {
+  AuthAccessWriteScope,
+  type AuthMcpClientAccess,
+  type EnvironmentId,
+  type OrchestrationV2ProjectedTurnItem,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { CheckIcon, LinkIcon, MinusIcon, XIcon } from "lucide-react";
+import { useId, useMemo, useRef, useState } from "react";
+
+import { useEnvironmentScope, usePreparedConnection } from "../../state/session";
+import { mintPairingCodeOn } from "../../state/peerPairingCode";
+import { useLinkableMachines } from "../../state/peerLinks";
+import { serverEnvironment } from "../../state/server";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { accessConfig } from "../auth/ConnectAgentSurface";
+import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
+import { LinkAccessPicker } from "../settings/LinkAccessPicker";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Radio, RadioGroup } from "../ui/radio-group";
+import { WorkLogRow } from "./WorkLog";
+
+const accessLabel = (access: AuthMcpClientAccess) => accessConfig[access].label;
+
+/** The machine list's row for linking by an address typed in. */
+const ANOTHER_ADDRESS = "another-address";
+
+/** Whether the agent left the machine for the user to pick. */
+const picksMachine = (item: LinkRequestItem) =>
+  item.environmentId === undefined && item.url === undefined;
+
+/**
+ * Inline card for a link an agent asked the user to make. The user picks the
+ * access in a dialog; the pairing code lives only in that dialog's state and
+ * the RPC payload, and is never logged, toasted, or persisted.
+ */
+export function LinkRequestCard(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly visibility: OrchestrationV2ProjectedTurnItem["visibility"];
+}) {
+  const { item } = props;
+  const display = linkRequestDisplay(item, props.visibility, accessLabel);
+  if (display.kind === "answered" || display.kind === "pending-elsewhere") {
+    const Icon =
+      display.kind === "pending-elsewhere"
+        ? LinkIcon
+        : display.outcome === "linked"
+          ? CheckIcon
+          : display.outcome === "failed"
+            ? XIcon
+            : MinusIcon;
+    return (
+      <WorkLogRow
+        data-v2-item-type={item.type}
+        icon={<Icon className="size-3.5 text-icon-muted" aria-hidden />}
+        label={display.label}
+      />
+    );
+  }
+  return <PendingLinkRequest environmentId={props.environmentId} item={item} />;
+}
+
+function PendingLinkRequest(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+}) {
+  const { item } = props;
+  const [open, setOpen] = useState(false);
+  const [declining, setDeclining] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "decline link request",
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const canAnswer = useAtomValue(
+    serverEnvironment.answerLinkRequest.permissionAtom(props.environmentId),
+  );
+  const target = linkRequestTargetName(item);
+
+  const decline = async () => {
+    const input = linkRequestAnswerInput(item, { type: "decline" });
+    if (input === null) return;
+    setDeclining(true);
+    setError(null);
+    const result = await answer({ environmentId: props.environmentId, input }).finally(() =>
+      setDeclining(false),
+    );
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+    }
+  };
+
+  return (
+    <div
+      data-v2-item-type={item.type}
+      className="flex min-w-0 flex-col gap-3 rounded-xl border border-border/60 bg-card p-4"
+    >
+      <div className="flex min-w-0 flex-col gap-1">
+        <p className="text-sm font-medium text-foreground">
+          {picksMachine(item)
+            ? "Link a machine to this environment"
+            : `Link ${target} to this environment`}
+        </p>
+        {item.reason.trim() ? <p className="text-sm text-muted-foreground">{item.reason}</p> : null}
+        {item.label !== undefined && item.url !== undefined ? (
+          <p className="truncate text-xs text-muted-foreground/80">{item.url}</p>
+        ) : null}
+      </div>
+      {error !== null ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {canAnswer ? (
+        <div className="flex min-w-0 items-center justify-end gap-2">
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            disabled={declining}
+            onClick={() => void decline()}
+          >
+            Decline
+          </Button>
+          <Button type="button" size="xs" disabled={declining} onClick={() => setOpen(true)}>
+            {picksMachine(item) ? "Choose machine…" : "Review link…"}
+          </Button>
+        </div>
+      ) : (
+        <p className="text-xs text-muted-foreground">
+          Only a session that manages access here can answer this.
+        </p>
+      )}
+      <LinkRequestDialog
+        environmentId={props.environmentId}
+        item={item}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    </div>
+  );
+}
+
+/**
+ * What the dialog links: a machine from the client's catalog, or an address.
+ * `urls` is empty when the client knows no direct address for the machine,
+ * so the user types one.
+ */
+type DialogTarget =
+  | { readonly kind: "none" }
+  | {
+      readonly kind: "machine";
+      readonly environmentId: EnvironmentId;
+      readonly label: string;
+      readonly urls: ReadonlyArray<string>;
+      readonly linked: boolean;
+    }
+  | { readonly kind: "address" };
+
+function resolveTarget(
+  item: LinkRequestItem,
+  machines: ReadonlyArray<LinkableMachine>,
+  choice: string | null,
+): DialogTarget {
+  if (item.environmentId === undefined && item.url !== undefined) return { kind: "address" };
+  const chosen = item.environmentId ?? choice;
+  if (chosen === null) return { kind: "none" };
+  if (chosen === ANOTHER_ADDRESS) return { kind: "address" };
+  const machine = machines.find((candidate) => candidate.environmentId === chosen);
+  return {
+    kind: "machine",
+    environmentId: machine?.environmentId ?? (chosen as EnvironmentId),
+    label: machine?.label ?? linkRequestTargetName(item),
+    urls: [...new Set([...(machine?.urls ?? []), ...(item.url === undefined ? [] : [item.url])])],
+    linked: machine?.linked ?? false,
+  };
+}
+
+function LinkRequestDialog(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}) {
+  const { item } = props;
+  const formId = useId();
+  const pickMachine = picksMachine(item);
+  const listed = useLinkableMachines(props.environmentId, props.open);
+  const machines = useMemo(() => rankMachinesByHint(listed, item.hint), [listed, item.hint]);
+  // Null until the user picks; until then the hint's best match is picked.
+  const [choice, setChoice] = useState<string | null>(null);
+  const [address, setAddress] = useState(item.url ?? "");
+  const [access, setAccess] = useState<AuthMcpClientAccess>(() => linkRequestDefaultAccess(item));
+  const [pairingCode, setPairingCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Machines whose minting already failed, so the dialog asks for a code instead.
+  const [mintFailed, setMintFailed] = useState<ReadonlySet<EnvironmentId>>(new Set());
+  // Enter then a click can both run before a re-render; this guard is synchronous.
+  const inFlight = useRef(false);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "answer link request",
+    // The failure cause holds the request, and with it the code; keep it out of the console.
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const selected = choice ?? linkRequestInitialMachine(item, machines);
+  const target = resolveTarget(item, machines, selected);
+  const targetName = target.kind === "machine" ? target.label : linkRequestTargetName(item);
+  // This client can mint a code there when it is connected to that
+  // environment with a session that may create pairing links.
+  const targetId = target.kind === "machine" ? target.environmentId : null;
+  const connected = usePreparedConnection(targetId);
+  const mayMint = useEnvironmentScope(targetId, AuthAccessWriteScope);
+  const canMint =
+    targetId !== null && Option.isSome(connected) && mayMint && !mintFailed.has(targetId);
+  const needsAddress =
+    target.kind === "address" || (target.kind === "machine" && target.urls.length === 0);
+  const useExisting = target.kind === "machine" && target.linked;
+  const ready =
+    target.kind !== "none" &&
+    (useExisting ||
+      ((!needsAddress || address.trim().length > 0) && (canMint || pairingCode.trim().length > 0)));
+
+  const reset = () => {
+    setChoice(null);
+    setAddress(item.url ?? "");
+    setAccess(linkRequestDefaultAccess(item));
+    setPairingCode("");
+    setError(null);
+  };
+
+  const submit = async () => {
+    if (inFlight.current || target.kind === "none") return;
+    inFlight.current = true;
+    setBusy(true);
+    setError(null);
+    try {
+      let input;
+      if (target.kind === "machine" && target.linked) {
+        input = linkRequestAnswerInput(item, {
+          type: "use-existing",
+          environmentId: target.environmentId,
+        });
+      } else {
+        let code = pairingCode;
+        if (canMint && targetId !== null) {
+          try {
+            code = await mintPairingCodeOn(targetId);
+          } catch (cause) {
+            setMintFailed((failed) => new Set(failed).add(targetId));
+            setError(linkRequestFailureMessage(cause));
+            return;
+          }
+        }
+        input = linkRequestAnswerInput(item, {
+          type: "link",
+          target:
+            target.kind === "address"
+              ? { url: address }
+              : { ...target, urls: needsAddress ? [address.trim()] : target.urls },
+          access,
+          pairingCode: code,
+        });
+      }
+      if (input === null) return;
+      const result = await answer({ environmentId: props.environmentId, input });
+      if (result._tag === "Success") {
+        // The card switches to its answered row once the item updates.
+        setPairingCode("");
+        props.onOpenChange(false);
+        return;
+      }
+      if (!isAtomCommandInterrupted(result)) {
+        setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+      }
+    } finally {
+      inFlight.current = false;
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Dialog
+      open={props.open}
+      onOpenChange={(next) => {
+        props.onOpenChange(next);
+        if (!next) reset();
+      }}
+    >
+      <DialogPopup className="max-w-md">
+        <DialogHeader>
+          <DialogTitle>{pickMachine ? "Link a machine" : `Link ${targetName}`}</DialogTitle>
+          <DialogDescription>
+            Agents here can then launch, message and wait on threads there. It appears in that
+            machine's Connections, where it can be revoked.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel>
+          <form
+            id={formId}
+            className="space-y-4"
+            autoComplete="off"
+            onSubmit={(event) => {
+              event.preventDefault();
+              void submit();
+            }}
+          >
+            {pickMachine ? (
+              <MachinePicker
+                machines={machines}
+                value={selected}
+                disabled={busy}
+                onChange={(next) => {
+                  setChoice(next);
+                  setError(null);
+                }}
+              />
+            ) : item.url !== undefined ? (
+              <p className="truncate text-xs text-muted-foreground">{item.url}</p>
+            ) : null}
+            {needsAddress && !(item.url !== undefined && item.environmentId === undefined) ? (
+              <label className="block space-y-1.5">
+                <span className="block text-xs font-medium text-foreground">Address</span>
+                <Input
+                  value={address}
+                  onChange={(event) => setAddress(event.target.value)}
+                  placeholder="https://machine.tailnet.ts.net"
+                  disabled={busy}
+                  nativeInput
+                  spellCheck={false}
+                />
+                {target.kind === "machine" ? (
+                  <span className="block text-xs text-muted-foreground">
+                    This app reaches {target.label} only through T3 Connect or SSH. Enter its https
+                    or Tailscale address.
+                  </span>
+                ) : null}
+              </label>
+            ) : null}
+            {useExisting ? (
+              <p className="text-xs text-muted-foreground">
+                This environment is already linked to {targetName}. The agent can use that link as
+                it is; change its access in Settings → Connections.
+              </p>
+            ) : target.kind === "none" ? null : (
+              <>
+                {canMint ? null : (
+                  <label className="block space-y-1.5">
+                    <span className="block text-xs font-medium text-foreground">Pairing code</span>
+                    <Input
+                      value={pairingCode}
+                      onChange={(event) => setPairingCode(event.target.value)}
+                      placeholder="Paste the code"
+                      disabled={busy}
+                      autoComplete="one-time-code"
+                      nativeInput
+                      spellCheck={false}
+                    />
+                    <span className="block text-xs text-muted-foreground">
+                      Create a link on {targetName}: Settings → Connections → Create link, then
+                      paste its code here.
+                    </span>
+                  </label>
+                )}
+                <LinkAccessPicker value={access} onChange={setAccess} />

@@ -0,0 +1,471 @@
+import { useAtomValue } from "@effect/atom-react";
+import {
+  type LinkableMachine,
+  linkRequestAnswerInput,
+  linkRequestDefaultAccess,
+  linkRequestDisplay,
+  linkRequestFailureMessage,
+  linkRequestInitialMachine,
+  type LinkRequestItem,
+  linkRequestTargetName,
+  rankMachinesByHint,
+} from "@t3tools/client-runtime/link-request";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import {
+  AuthAccessWriteScope,
+  type AuthMcpClientAccess,
+  type EnvironmentId,
+  type OrchestrationV2ProjectedTurnItem,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { CheckIcon, LinkIcon, MinusIcon, XIcon } from "lucide-react";
+import { useId, useMemo, useRef, useState } from "react";
+
+import { useEnvironmentScope, usePreparedConnection } from "../../state/session";
+import { mintPairingCodeOn } from "../../state/peerPairingCode";
+import { useLinkableMachines } from "../../state/peerLinks";
+import { serverEnvironment } from "../../state/server";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { accessConfig } from "../auth/ConnectAgentSurface";
+import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
+import { LinkAccessPicker } from "../settings/LinkAccessPicker";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Radio, RadioGroup } from "../ui/radio-group";
+import { WorkLogRow } from "./WorkLog";
+
+const accessLabel = (access: AuthMcpClientAccess) => accessConfig[access].label;
+
+/** The machine list's row for linking by an address typed in. */
+const ANOTHER_ADDRESS = "another-address";
+
+/** Whether the agent left the machine for the user to pick. */
+const picksMachine = (item: LinkRequestItem) =>
+  item.environmentId === undefined && item.url === undefined;
+
+/**
+ * Inline card for a link an agent asked the user to make. The user picks the
+ * access in a dialog; the pairing code lives only in that dialog's state and
+ * the RPC payload, and is never logged, toasted, or persisted.
+ */
+export function LinkRequestCard(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly visibility: OrchestrationV2ProjectedTurnItem["visibility"];
+}) {
+  const { item } = props;
+  const display = linkRequestDisplay(item, props.visibility, accessLabel);
+  if (display.kind === "answered" || display.kind === "pending-elsewhere") {
+    const Icon =
+      display.kind === "pending-elsewhere"
+        ? LinkIcon
+        : display.outcome === "linked"
+          ? CheckIcon
+          : display.outcome === "failed"
+            ? XIcon
+            : MinusIcon;
+    return (
+      <WorkLogRow
+        data-v2-item-type={item.type}
+        icon={<Icon className="size-3.5 text-icon-muted" aria-hidden />}
+        label={display.label}
+      />
+    );
+  }
+  return <PendingLinkRequest environmentId={props.environmentId} item={item} />;
+}
+
+function PendingLinkRequest(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+}) {
+  const { item } = props;
+  const [open, setOpen] = useState(false);
+  const [declining, setDeclining] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "decline link request",
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const canAnswer = useAtomValue(
+    serverEnvironment.answerLinkRequest.permissionAtom(props.environmentId),
+  );
+  const target = linkRequestTargetName(item);
+
+  const decline = async () => {
+    const input = linkRequestAnswerInput(item, { type: "decline" });
+    if (input === null) return;
+    setDeclining(true);
+    setError(null);
+    const result = await answer({ environmentId: props.environmentId, input }).finally(() =>
+      setDeclining(false),
+    );
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+    }
+  };
+
+  return (
+    <div
+      data-v2-item-type={item.type}
+      className="flex min-w-0 flex-col gap-3 rounded-xl border border-border/60 bg-card p-4"
+    >
+      <div className="flex min-w-0 flex-col gap-1">
+        <p className="text-sm font-medium text-foreground">
+          {picksMachine(item)
+            ? "Link a machine to this environment"
+            : `Link ${target} to this environment`}
+        </p>
+        {item.reason.trim() ? <p className="text-sm text-muted-foreground">{item.reason}</p> : null}
+        {item.label !== undefined && item.url !== undefined ? (
+          <p className="truncate text-xs text-muted-foreground/80">{item.url}</p>
+        ) : null}
+      </div>
+      {error !== null ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {canAnswer ? (
+        <div className="flex min-w-0 items-center justify-end gap-2">
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            disabled={declining}
+            onClick={() => void decline()}
+          >
+            Decline
+          </Button>
+          <Button type="button" size="xs" disabled={declining} onClick={() => setOpen(true)}>
+            {picksMachine(item) ? "Choose machine…" : "Review link…"}
+          </Button>
+        </div>
+      ) : (
+        <p className="text-xs text-muted-foreground">
+          Only a session that manages access here can answer this.
+        </p>
+      )}
+      <LinkRequestDialog
+        environmentId={props.environmentId}
+        item={item}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    </div>
+  );
+}
+
+/**
+ * What the dialog links: a machine from the client's catalog, or an address.
+ * `urls` is empty when the client knows no direct address for the machine,
+ * so the user types one.
+ */
+type DialogTarget =
+  | { readonly kind: "none" }
+  | {
+      readonly kind: "machine";
+      readonly environmentId: EnvironmentId;
+      readonly label: string;
+      readonly urls: ReadonlyArray<string>;
+      readonly linked: boolean;
+    }
+  | { readonly kind: "address" };
+
+function resolveTarget(
+  item: LinkRequestItem,
+  machines: ReadonlyArray<LinkableMachine>,
+  choice: string | null,
+): DialogTarget {
+  if (item.environmentId === undefined && item.url !== undefined) return { kind: "address" };
+  const chosen = item.environmentId ?? choice;
+  if (chosen === null) return { kind: "none" };
+  if (chosen === ANOTHER_ADDRESS) return { kind: "address" };
+  const machine = machines.find((candidate) => candidate.environmentId === chosen);
+  return {
+    kind: "machine",
+    environmentId: machine?.environmentId ?? (chosen as EnvironmentId),
+    label: machine?.label ?? linkRequestTargetName(item),
+    urls: [...new Set([...(machine?.urls ?? []), ...(item.url === undefined ? [] : [item.url])])],
+    linked: machine?.linked ?? false,
+  };
+}
+
+function LinkRequestDialog(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}) {
+  const { item } = props;
+  const formId = useId();
+  const pickMachine = picksMachine(item);
+  const listed = useLinkableMachines(props.environmentId, props.open);
+  const machines = useMemo(() => rankMachinesByHint(listed, item.hint), [listed, item.hint]);
+  // Null until the user picks; until then the hint's best match is picked.
+  const [choice, setChoice] = useState<string | null>(null);
+  const [address, setAddress] = useState(item.url ?? "");
+  const [access, setAccess] = useState<AuthMcpClientAccess>(() => linkRequestDefaultAccess(item));
+  const [pairingCode, setPairingCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Machines whose minting already failed, so the dialog asks for a code instead.
+  const [mintFailed, setMintFailed] = useState<ReadonlySet<EnvironmentId>>(new Set());
+  // Enter then a click can both run before a re-render; this guard is synchronous.
+  const inFlight = useRef(false);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "answer link request",
+    // The failure cause holds the request, and with it the code; keep it out of the console.
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const selected = choice ?? linkRequestInitialMachine(item, machines);
+  const target = resolveTarget(item, machines, selected);
+  const targetName = target.kind === "machine" ? target.label : linkRequestTargetName(item);
+  // This client can mint a code there when it is connected to that
+  // environment with a session that may create pairing links.
+  const targetId = target.kind === "machine" ? target.environmentId : null;
+  const connected = usePreparedConnection(targetId);
+  const mayMint = useEnvironmentScope(targetId, AuthAccessWriteScope);
+  const canMint =
+    targetId !== null && Option.isSome(connected) && mayMint && !mintFailed.has(targetId);
+  const needsAddress =
+    target.kind === "address" || (target.kind === "machine" && target.urls.length === 0);
+  const useExisting = target.kind === "machine" && target.linked;
+  const ready =
+    target.kind !== "none" &&
+    (useExisting ||
+      ((!needsAddress || address.trim().length > 0) && (canMint || pairingCode.trim().length > 0)));
+
+  const reset = () => {
+    setChoice(null);
+    setAddress(item.url ?? "");
+    setAccess(linkRequestDefaultAccess(item));
+    setPairingCode("");
+    setError(null);
+  };
+
+  const submit = async () => {
+    if (inFlight.current || target.kind === "none") return;
+    inFlight.current = true;
+    setBusy(true);
+    setError(null);
+    try {
+      let input;
+      if (target.kind === "machine" && target.linked) {
+        input = linkRequestAnswerInput(item, {
+          type: "use-existing",
+          environmentId: target.environmentId,
+        });
+      } else {
+        let code = pairingCode;
+        if (canMint && targetId !== null) {
+          try {
+            code = await mintPairingCodeOn(targetId);
+          } catch (cause) {
+            setMintFailed((failed) => new Set(failed).add(targetId));
+            setError(linkRequestFailureMessage(cause));
+            return;
+          }
+        }
+        input = linkRequestAnswerInput(item, {
+          type: "link",
+          target:
+            target.kind === "address"
+              ? { url: address }
+              : { ...target, urls: needsAddress ? [address.trim()] : target.urls },
+          access,
+          pairingCode: code,
+        });
+      }
+      if (input === null) return;
+      const result = await answer({ environmentId: props.environmentId, input });
+      if (result._tag === "Success") {
+        // The card switches to its answered row once the item updates.
+        setPairingCode("");
+        props.onOpenChange(false);
+        return;
+      }
+      if (!isAtomCommandInterrupted(result)) {
+        setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+      }
+    } finally {
+      inFlight.current = false;
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Dialog
+      open={props.open}
+      onOpenChange={(next) => {
+        props.onOpenChange(next);
+        if (!next) reset();
+      }}
+    >
+      <DialogPopup className="max-w-md">
+        <DialogHeader>
+          <DialogTitle>{pickMachine ? "Link a machine" : `Link ${targetName}`}</DialogTitle>
+          <DialogDescription>
+            Agents here can then launch, message and wait on threads there. It appears in that
+            machine's Connections, where it can be revoked.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel>
+          <form
+            id={formId}
+            className="space-y-4"
+            autoComplete="off"
+            onSubmit={(event) => {
+              event.preventDefault();
+              void submit();
+            }}
+          >
+            {pickMachine ? (
+              <MachinePicker
+                machines={machines}
+                value={selected}
+                disabled={busy}
+                onChange={(next) => {
+                  setChoice(next);
+                  setError(null);
+                }}
+              />
+            ) : item.url !== undefined ? (
+              <p className="truncate text-xs text-muted-foreground">{item.url}</p>
+            ) : null}
+            {needsAddress && !(item.url !== undefined && item.environmentId === undefined) ? (
+              <label className="block space-y-1.5">
+                <span className="block text-xs font-medium text-foreground">Address</span>
+                <Input
+                  value={address}
+                  onChange={(event) => setAddress(event.target.value)}
+                  placeholder="https://machine.tailnet.ts.net"
+                  disabled={busy}
+                  nativeInput
+                  spellCheck={false}
+                />
+                {target.kind === "machine" ? (
+                  <span className="block text-xs text-muted-foreground">
+                    This app reaches {target.label} only through T3 Connect or SSH. Enter its https
+                    or Tailscale address.
+                  </span>
+                ) : null}
+              </label>
+            ) : null}
+            {useExisting ? (
+              <p className="text-xs text-muted-foreground">
+                This environment is already linked to {targetName}. The agent can use that link as
+                it is; change its access in Settings → Connections.
+              </p>
+            ) : target.kind === "none" ? null : (
+              <>
+                {canMint ? null : (
+                  <label className="block space-y-1.5">
+                    <span className="block text-xs font-medium text-foreground">Pairing code</span>
+                    <Input
+                      value={pairingCode}
+                      onChange={(event) => setPairingCode(event.target.value)}
+                      placeholder="Paste the code"
+                      disabled={busy}
+                      autoComplete="one-time-code"
+                      nativeInput
+                      spellCheck={false}
+                    />
+                    <span className="block text-xs text-muted-foreground">
+                      Create a link on {targetName}: Settings → Connections → Create link, then
+                      paste its code here.
+                    </span>
+                  </label>
+                )}
+                <LinkAccessPicker value={access} onChange={setAccess} />
+              </>
+            )}
+            {error !== null ? (
+              <p role="alert" className="text-xs text-destructive">
+                {error}
+              </p>
+            ) : null}
+          </form>
+        </DialogPanel>
+        <DialogFooter variant="bare">
+          <Button
+            variant="outline"
+            type="button"
+            disabled={busy}
+            onClick={() => props.onOpenChange(false)}

@@ -0,0 +1,512 @@
+import { useAtomValue } from "@effect/atom-react";
+import {
+  type LinkableMachine,
+  linkRequestAnswerInput,
+  linkRequestDefaultAccess,
+  linkRequestDisplay,
+  linkRequestFailureMessage,
+  linkRequestInitialMachine,
+  type LinkRequestItem,
+  linkRequestTargetName,
+  rankMachinesByHint,
+} from "@t3tools/client-runtime/link-request";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import {
+  AuthAccessWriteScope,
+  type AuthMcpClientAccess,
+  type EnvironmentId,
+  type OrchestrationV2ProjectedTurnItem,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { CheckIcon, LinkIcon, MinusIcon, XIcon } from "lucide-react";
+import { useId, useMemo, useRef, useState } from "react";
+
+import { useEnvironmentScope, usePreparedConnection } from "../../state/session";
+import { mintPairingCodeOn } from "../../state/peerPairingCode";
+import { useLinkableMachines } from "../../state/peerLinks";
+import { serverEnvironment } from "../../state/server";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { accessConfig } from "../auth/ConnectAgentSurface";
+import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
+import { LinkAccessPicker } from "../settings/LinkAccessPicker";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import { Dialog } from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Radio, RadioGroup } from "../ui/radio-group";
+import { WizardFooter, WizardHeader, WizardPanel, WizardPopup, WizardSteps } from "../ui/wizard";
+import { WorkLogRow } from "./WorkLog";
+
+const accessLabel = (access: AuthMcpClientAccess) => accessConfig[access].label;
+
+/** The machine list's row for linking by an address typed in. */
+const ANOTHER_ADDRESS = "another-address";
+
+/** Whether the agent left the machine for the user to pick. */
+const picksMachine = (item: LinkRequestItem) =>
+  item.environmentId === undefined && item.url === undefined;
+
+/**
+ * Inline card for a link an agent asked the user to make. The user picks the
+ * access in a dialog; the pairing code lives only in that dialog's state and
+ * the RPC payload, and is never logged, toasted, or persisted.
+ */
+export function LinkRequestCard(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly visibility: OrchestrationV2ProjectedTurnItem["visibility"];
+}) {
+  const { item } = props;
+  const display = linkRequestDisplay(item, props.visibility, accessLabel);
+  if (display.kind === "answered" || display.kind === "pending-elsewhere") {
+    const Icon =
+      display.kind === "pending-elsewhere"
+        ? LinkIcon
+        : display.outcome === "linked"
+          ? CheckIcon
+          : display.outcome === "failed"
+            ? XIcon
+            : MinusIcon;
+    return (
+      <WorkLogRow
+        data-v2-item-type={item.type}
+        icon={<Icon className="size-3.5 text-icon-muted" aria-hidden />}
+        label={display.label}
+      />
+    );
+  }
+  return <PendingLinkRequest environmentId={props.environmentId} item={item} />;
+}
+
+function PendingLinkRequest(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+}) {
+  const { item } = props;
+  const [open, setOpen] = useState(false);
+  const [declining, setDeclining] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "decline link request",
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const canAnswer = useAtomValue(
+    serverEnvironment.answerLinkRequest.permissionAtom(props.environmentId),
+  );
+  const target = linkRequestTargetName(item);
+
+  const decline = async () => {
+    const input = linkRequestAnswerInput(item, { type: "decline" });
+    if (input === null) return;
+    setDeclining(true);
+    setError(null);
+    const result = await answer({ environmentId: props.environmentId, input }).finally(() =>
+      setDeclining(false),
+    );
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+    }
+  };
+
+  return (
+    <div
+      data-v2-item-type={item.type}
+      className="flex min-w-0 flex-col gap-3 rounded-xl border border-border/60 bg-card p-4"
+    >
+      <div className="flex min-w-0 flex-col gap-1">
+        <p className="text-sm font-medium text-foreground">
+          {picksMachine(item)
+            ? "Link a machine to this environment"
+            : `Link ${target} to this environment`}
+        </p>
+        {item.reason.trim() ? <p className="text-sm text-muted-foreground">{item.reason}</p> : null}
+        {item.label !== undefined && item.url !== undefined ? (
+          <p className="truncate text-xs text-muted-foreground/80">{item.url}</p>
+        ) : null}
+      </div>
+      {error !== null ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {canAnswer ? (
+        <div className="flex min-w-0 items-center justify-end gap-2">
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            disabled={declining}
+            onClick={() => void decline()}
+          >
+            Decline
+          </Button>
+          <Button type="button" size="xs" disabled={declining} onClick={() => setOpen(true)}>
+            {picksMachine(item) ? "Choose machine…" : "Review link…"}
+          </Button>
+        </div>
+      ) : (
+        <p className="text-xs text-muted-foreground">
+          Only a session that manages access here can answer this.
+        </p>
+      )}
+      <LinkRequestDialog
+        environmentId={props.environmentId}
+        item={item}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    </div>
+  );
+}
+
+/**
+ * What the dialog links: a machine from the client's catalog, or an address.
+ * `urls` is empty when the client knows no direct address for the machine,
+ * so the user types one.
+ */
+type DialogTarget =
+  | { readonly kind: "none" }
+  | {
+      readonly kind: "machine";
+      readonly environmentId: EnvironmentId;
+      readonly label: string;
+      readonly urls: ReadonlyArray<string>;
+      readonly linked: boolean;
+    }
+  | { readonly kind: "address" };
+
+function resolveTarget(
+  item: LinkRequestItem,
+  machines: ReadonlyArray<LinkableMachine>,
+  choice: string | null,
+): DialogTarget {
+  if (item.environmentId === undefined && item.url !== undefined) return { kind: "address" };
+  const chosen = item.environmentId ?? choice;
+  if (chosen === null) return { kind: "none" };
+  if (chosen === ANOTHER_ADDRESS) return { kind: "address" };
+  const machine = machines.find((candidate) => candidate.environmentId === chosen);
+  return {
+    kind: "machine",
+    environmentId: machine?.environmentId ?? (chosen as EnvironmentId),
+    label: machine?.label ?? linkRequestTargetName(item),
+    urls: [...new Set([...(machine?.urls ?? []), ...(item.url === undefined ? [] : [item.url])])],
+    linked: machine?.linked ?? false,
+  };
+}
+
+/** The dialog's steps: where to link, then what agents may do there. */
+type LinkStep = "machine" | "access";
+
+function LinkRequestDialog(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}) {
+  const { item } = props;
+  const formId = useId();
+  const pickMachine = picksMachine(item);
+  const listed = useLinkableMachines(props.environmentId, props.open);
+  const machines = useMemo(() => rankMachinesByHint(listed, item.hint), [listed, item.hint]);
+  // Null until the user picks; until then the hint's best match is picked.
+  const [choice, setChoice] = useState<string | null>(null);
+  const [address, setAddress] = useState(item.url ?? "");
+  const [access, setAccess] = useState<AuthMcpClientAccess>(() => linkRequestDefaultAccess(item));
+  const [pairingCode, setPairingCode] = useState("");
+  const [step, setStep] = useState<LinkStep>("machine");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Machines whose minting already failed, so the dialog asks for a code instead.
+  const [mintFailed, setMintFailed] = useState<ReadonlySet<EnvironmentId>>(new Set());
+  // Enter then a click can both run before a re-render; this guard is synchronous.
+  const inFlight = useRef(false);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "answer link request",
+    // The failure cause holds the request, and with it the code; keep it out of the console.
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const selected = choice ?? linkRequestInitialMachine(item, machines);
+  const target = resolveTarget(item, machines, selected);
+  const targetName = target.kind === "machine" ? target.label : linkRequestTargetName(item);
+  // This client can mint a code there when it is connected to that
+  // environment with a session that may create pairing links.
+  const targetId = target.kind === "machine" ? target.environmentId : null;
+  const connected = usePreparedConnection(targetId);
+  const mayMint = useEnvironmentScope(targetId, AuthAccessWriteScope);
+  const canMint =
+    targetId !== null && Option.isSome(connected) && mayMint && !mintFailed.has(targetId);
+  const needsAddress =
+    target.kind === "address" || (target.kind === "machine" && target.urls.length === 0);
+  // An address the agent gave is already filled in; only one the user must type is asked for.
+  const asksAddress = needsAddress && !(item.url !== undefined && item.environmentId === undefined);
+  const useExisting = target.kind === "machine" && target.linked;
+  // A named machine with an address it answers at has nothing to choose before access.
+  const steps: ReadonlyArray<LinkStep> =
+    pickMachine || asksAddress ? ["machine", "access"] : ["access"];
+  const current: LinkStep = steps.includes(step) ? step : "access";
+  const machineReady =
+    target.kind !== "none" && (useExisting || !needsAddress || address.trim().length > 0);
+  const ready = machineReady && (useExisting || canMint || pairingCode.trim().length > 0);
+
+  const reset = () => {
+    setChoice(null);
+    setAddress(item.url ?? "");
+    setAccess(linkRequestDefaultAccess(item));
+    setPairingCode("");
+    setStep("machine");
+    setError(null);
+  };
+
+  const submit = async () => {
+    if (inFlight.current || target.kind === "none") return;
+    inFlight.current = true;
+    setBusy(true);
+    setError(null);
+    try {
+      let input;
+      if (target.kind === "machine" && target.linked) {
+        input = linkRequestAnswerInput(item, {
+          type: "use-existing",
+          environmentId: target.environmentId,
+        });
+      } else {
+        let code = pairingCode;
+        if (canMint && targetId !== null) {
+          try {
+            code = await mintPairingCodeOn(targetId);
+          } catch (cause) {
+            setMintFailed((failed) => new Set(failed).add(targetId));
+            setError(linkRequestFailureMessage(cause));
+            return;
+          }
+        }
+        input = linkRequestAnswerInput(item, {
+          type: "link",
+          target:
+            target.kind === "address"
+              ? { url: address }
+              : { ...target, urls: needsAddress ? [address.trim()] : target.urls },
+          access,
+          pairingCode: code,
+        });
+      }
+      if (input === null) return;
+      const result = await answer({ environmentId: props.environmentId, input });
+      if (result._tag === "Success") {
+        // The card switches to its answered row once the item updates.
+        setPairingCode("");
+        props.onOpenChange(false);
+        return;

@@ -0,0 +1,503 @@
+import { useAtomValue } from "@effect/atom-react";
+import {
+  type LinkableMachine,
+  linkRequestAnswerInput,
+  linkRequestDefaultAccess,
+  linkRequestDisplay,
+  linkRequestFailureMessage,
+  linkRequestInitialMachine,
+  type LinkRequestItem,
+  linkRequestTargetName,
+  rankMachinesByHint,
+} from "@t3tools/client-runtime/link-request";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import {
+  AuthAccessWriteScope,
+  type AuthMcpClientAccess,
+  type EnvironmentId,
+  type OrchestrationV2ProjectedTurnItem,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { CheckIcon, LinkIcon, MinusIcon, XIcon } from "lucide-react";
+import { useId, useMemo, useRef, useState } from "react";
+
+import { useEnvironmentScope, usePreparedConnection } from "../../state/session";
+import { mintPairingCodeOn } from "../../state/peerPairingCode";
+import { useLinkableMachines } from "../../state/peerLinks";
+import { serverEnvironment } from "../../state/server";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { accessConfig } from "../auth/ConnectAgentSurface";
+import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
+import { LinkAccessPicker } from "../settings/LinkAccessPicker";
+import { ANOTHER_ADDRESS, LinkMachineBadge } from "../settings/LinkMachineSelect";
+import { Button } from "../ui/button";
+import { Dialog } from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Radio, RadioGroup } from "../ui/radio-group";
+import { WizardFooter, WizardHeader, WizardPanel, WizardPopup, WizardSteps } from "../ui/wizard";
+import { WorkLogRow } from "./WorkLog";
+
+const accessLabel = (access: AuthMcpClientAccess) => accessConfig[access].label;
+
+/** Whether the agent left the machine for the user to pick. */
+const picksMachine = (item: LinkRequestItem) =>
+  item.environmentId === undefined && item.url === undefined;
+
+/**
+ * Inline card for a link an agent asked the user to make. The user picks the
+ * access in a dialog; the pairing code lives only in that dialog's state and
+ * the RPC payload, and is never logged, toasted, or persisted.
+ */
+export function LinkRequestCard(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly visibility: OrchestrationV2ProjectedTurnItem["visibility"];
+}) {
+  const { item } = props;
+  const display = linkRequestDisplay(item, props.visibility, accessLabel);
+  if (display.kind === "answered" || display.kind === "pending-elsewhere") {
+    const Icon =
+      display.kind === "pending-elsewhere"
+        ? LinkIcon
+        : display.outcome === "linked"
+          ? CheckIcon
+          : display.outcome === "failed"
+            ? XIcon
+            : MinusIcon;
+    return (
+      <WorkLogRow
+        data-v2-item-type={item.type}
+        icon={<Icon className="size-3.5 text-icon-muted" aria-hidden />}
+        label={display.label}
+      />
+    );
+  }
+  return <PendingLinkRequest environmentId={props.environmentId} item={item} />;
+}
+
+function PendingLinkRequest(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+}) {
+  const { item } = props;
+  const [open, setOpen] = useState(false);
+  const [declining, setDeclining] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "decline link request",
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const canAnswer = useAtomValue(
+    serverEnvironment.answerLinkRequest.permissionAtom(props.environmentId),
+  );
+  const target = linkRequestTargetName(item);
+
+  const decline = async () => {
+    const input = linkRequestAnswerInput(item, { type: "decline" });
+    if (input === null) return;
+    setDeclining(true);
+    setError(null);
+    const result = await answer({ environmentId: props.environmentId, input }).finally(() =>
+      setDeclining(false),
+    );
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+    }
+  };
+
+  return (
+    <div
+      data-v2-item-type={item.type}
+      className="flex min-w-0 flex-col gap-3 rounded-xl border border-border/60 bg-card p-4"
+    >
+      <div className="flex min-w-0 flex-col gap-1">
+        <p className="text-sm font-medium text-foreground">
+          {picksMachine(item)
+            ? "Link a machine to this environment"
+            : `Link ${target} to this environment`}
+        </p>
+        {item.reason.trim() ? <p className="text-sm text-muted-foreground">{item.reason}</p> : null}
+        {item.label !== undefined && item.url !== undefined ? (
+          <p className="truncate text-xs text-muted-foreground/80">{item.url}</p>
+        ) : null}
+      </div>
+      {error !== null ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+      {canAnswer ? (
+        <div className="flex min-w-0 items-center justify-end gap-2">
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            disabled={declining}
+            onClick={() => void decline()}
+          >
+            Decline
+          </Button>
+          <Button type="button" size="xs" disabled={declining} onClick={() => setOpen(true)}>
+            {picksMachine(item) ? "Choose machine…" : "Review link…"}
+          </Button>
+        </div>
+      ) : (
+        <p className="text-xs text-muted-foreground">
+          Only a session that manages access here can answer this.
+        </p>
+      )}
+      <LinkRequestDialog
+        environmentId={props.environmentId}
+        item={item}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    </div>
+  );
+}
+
+/**
+ * What the dialog links: a machine from the client's catalog, or an address.
+ * `urls` is empty when the client knows no direct address for the machine,
+ * so the user types one.
+ */
+type DialogTarget =
+  | { readonly kind: "none" }
+  | {
+      readonly kind: "machine";
+      readonly environmentId: EnvironmentId;
+      readonly label: string;
+      readonly urls: ReadonlyArray<string>;
+      readonly linked: boolean;
+    }
+  | { readonly kind: "address" };
+
+function resolveTarget(
+  item: LinkRequestItem,
+  machines: ReadonlyArray<LinkableMachine>,
+  choice: string | null,
+): DialogTarget {
+  if (item.environmentId === undefined && item.url !== undefined) return { kind: "address" };
+  const chosen = item.environmentId ?? choice;
+  if (chosen === null) return { kind: "none" };
+  if (chosen === ANOTHER_ADDRESS) return { kind: "address" };
+  const machine = machines.find((candidate) => candidate.environmentId === chosen);
+  return {
+    kind: "machine",
+    environmentId: machine?.environmentId ?? (chosen as EnvironmentId),
+    label: machine?.label ?? linkRequestTargetName(item),
+    urls: [...new Set([...(machine?.urls ?? []), ...(item.url === undefined ? [] : [item.url])])],
+    linked: machine?.linked ?? false,
+  };
+}
+
+/** The dialog's steps: where to link, then what agents may do there. */
+type LinkStep = "machine" | "access";
+
+function LinkRequestDialog(props: {
+  readonly environmentId: EnvironmentId;
+  readonly item: LinkRequestItem;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}) {
+  const { item } = props;
+  const formId = useId();
+  const pickMachine = picksMachine(item);
+  const listed = useLinkableMachines(props.environmentId, props.open);
+  const machines = useMemo(() => rankMachinesByHint(listed, item.hint), [listed, item.hint]);
+  // Null until the user picks; until then the hint's best match is picked.
+  const [choice, setChoice] = useState<string | null>(null);
+  const [address, setAddress] = useState(item.url ?? "");
+  const [access, setAccess] = useState<AuthMcpClientAccess>(() => linkRequestDefaultAccess(item));
+  const [pairingCode, setPairingCode] = useState("");
+  const [step, setStep] = useState<LinkStep>("machine");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Machines whose minting already failed, so the dialog asks for a code instead.
+  const [mintFailed, setMintFailed] = useState<ReadonlySet<EnvironmentId>>(new Set());
+  // Enter then a click can both run before a re-render; this guard is synchronous.
+  const inFlight = useRef(false);
+  const answer = useAtomCommand(serverEnvironment.answerLinkRequest, {
+    label: "answer link request",
+    // The failure cause holds the request, and with it the code; keep it out of the console.
+    reportFailure: false,
+    reportDefect: false,
+  });
+  const selected = choice ?? linkRequestInitialMachine(item, machines);
+  const target = resolveTarget(item, machines, selected);
+  const targetName = target.kind === "machine" ? target.label : linkRequestTargetName(item);
+  // This client can mint a code there when it is connected to that
+  // environment with a session that may create pairing links.
+  const targetId = target.kind === "machine" ? target.environmentId : null;
+  const connected = usePreparedConnection(targetId);
+  const mayMint = useEnvironmentScope(targetId, AuthAccessWriteScope);
+  const canMint =
+    targetId !== null && Option.isSome(connected) && mayMint && !mintFailed.has(targetId);
+  const needsAddress =
+    target.kind === "address" || (target.kind === "machine" && target.urls.length === 0);
+  // An address the agent gave is already filled in; only one the user must type is asked for.
+  const asksAddress = needsAddress && !(item.url !== undefined && item.environmentId === undefined);
+  const useExisting = target.kind === "machine" && target.linked;
+  // A named machine with an address it answers at has nothing to choose before access.
+  const steps: ReadonlyArray<LinkStep> =
+    pickMachine || asksAddress ? ["machine", "access"] : ["access"];
+  const current: LinkStep = steps.includes(step) ? step : "access";
+  const machineReady =
+    target.kind !== "none" && (useExisting || !needsAddress || address.trim().length > 0);
+  const ready = machineReady && (useExisting || canMint || pairingCode.trim().length > 0);
+
+  const reset = () => {
+    setChoice(null);
+    setAddress(item.url ?? "");
+    setAccess(linkRequestDefaultAccess(item));
+    setPairingCode("");
+    setStep("machine");
+    setError(null);
+  };
+
+  // Every close resets, so a reopened dialog never shows the last answer or its pairing code.
+  const close = () => {
+    props.onOpenChange(false);
+    reset();
+  };
+
+  const submit = async () => {
+    if (inFlight.current || target.kind === "none") return;
+    inFlight.current = true;
+    setBusy(true);
+    setError(null);
+    try {
+      let input;
+      if (target.kind === "machine" && target.linked) {
+        input = linkRequestAnswerInput(item, {
+          type: "use-existing",
+          environmentId: target.environmentId,
+        });
+      } else {
+        let code = pairingCode;
+        if (canMint && targetId !== null) {
+          try {
+            code = await mintPairingCodeOn(targetId);
+          } catch (cause) {
+            setMintFailed((failed) => new Set(failed).add(targetId));
+            setError(linkRequestFailureMessage(cause));
+            return;
+          }
+        }
+        input = linkRequestAnswerInput(item, {
+          type: "link",
+          target:
+            target.kind === "address"
+              ? { url: address }
+              : { ...target, urls: needsAddress ? [address.trim()] : target.urls },
+          access,
+          pairingCode: code,
+        });
+      }
+      if (input === null) return;
+      const result = await answer({ environmentId: props.environmentId, input });
+      if (result._tag === "Success") {
+        // The card switches to its answered row once the item updates.
+        close();
+        return;
+      }
+      if (!isAtomCommandInterrupted(result)) {
+        setError(linkRequestFailureMessage(squashAtomCommandFailure(result)));
+      }
+    } finally {
+      inFlight.current = false;
+      setBusy(false);
+    }
+  };
+
+  // The machine step ends the dialog when the machine is linked here already.
+  const finishesHere = current === "access" || useExisting;
+
+  return (
+    <Dialog
+      open={props.open}
+      onOpenChange={(next) => {
+        // An answer that lands after a close would still link, and would close a reopened dialog.
+        if (!next && busy) return;
+        if (next) props.onOpenChange(true);
+        else close();
+      }}
+    >
+      <WizardPopup>
+        <WizardHeader
+          title={pickMachine ? "Link a machine" : `Link ${targetName}`}
+          description="Agents here can then launch, message and wait on threads there. Revoke it in that machine's Connections."
+        >
+          {steps.length > 1 && !useExisting ? (
+            <WizardSteps
+              steps={["Machine", "Access"]}
+              currentStep={steps.indexOf(current)}
+              summaries={[target.kind === "none" ? null : targetName, null]}
+              showSummaries
+              isStepDisabled={(index) => busy || (index === 1 && !machineReady)}
+              onStepChange={(index) => {
+                const next = steps[index];
+                if (next !== undefined) setStep(next);
+              }}
+            />
+          ) : null}
+        </WizardHeader>
+        <WizardPanel holdHeight={busy}>
+          <form
+            id={formId}
+            className="space-y-4"
+            autoComplete="off"
+            onSubmit={(event) => {
+              event.preventDefault();
+              if (finishesHere) void submit();
+              else if (machineReady) setStep("access");
+            }}
+          >
+            {current === "machine" ? (
+              <>
+                {pickMachine ? (
+                  <MachinePicker
+                    machines={machines}
+                    value={selected}
+                    disabled={busy}
+                    onChange={(next) => {
+                      setChoice(next);
+                      setError(null);
+                    }}
+                  />
+                ) : null}
+                {asksAddress ? (
+                  <label className="block space-y-1.5">
+                    <span className="block text-xs font-medium text-foreground">Address</span>
+                    <Input
+                      value={address}
+                      onChange={(event) => setAddress(event.target.value)}
+                      placeholder="https://machine.tailnet.ts.net"
+                      disabled={busy}
+                      nativeInput
+                      spellCheck={false}
+                    />
+                    {target.kind === "machine" ? (
+                      <span className="block text-xs text-muted-foreground">
+                        This app has no address for {target.label} that another machine can reach.
+                        Enter its https or Tailscale address.
+                      </span>
+                    ) : null}
+                  </label>
+                ) : null}
+                {useExisting ? (
+                  <p className="text-xs text-muted-foreground">
+                    This environment is already linked to {targetName}. The agent can use that link
+                    as it is; change its access in Settings → Connections.
+                  </p>
+                ) : null}
+              </>
+            ) : (

@@ -7342,6 +7344,170 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
     },
   );
 
+  /**
+   * Records or updates the card for a link an agent asked the user to make.
+   * The pairing code goes straight to the link and never through orchestration.
+   */
+  const dispatchLinkRequestRecord = Effect.fn("orchestrationV2.dispatch.linkRequestRecord")(
+    function* (
+      command: Extract<OrchestrationV2InternalCommand, { readonly type: "link_request.record" }>,
+      events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
+      effects: Ref.Ref<Array<PendingOrchestrationEffectV2>>,
+    ) {
+      const projection = yield* projectionStore
+        .getThreadRecords(
+          command.threadId,
+          ["runs", "nodes", "turnItems", "attempts", "providerTurns"],
+          { turnItemTypes: ["link_request"], messageRoles: [] },
+        )
+        .pipe(
+          Effect.mapError(
+            (cause) => new OrchestratorProjectionError({ threadId: command.threadId, cause }),
+          ),
+        );
+      const run = projection.runs.find((candidate) => candidate.id === command.runId);
+      if (run === undefined || run.rootNodeId !== command.nodeId) {
+        return yield* new OrchestratorDispatchError({
+          commandId: command.commandId,
+          commandType: command.type,
+          cause: `Node ${command.nodeId} is not the root of run ${command.runId}.`,
+        });
+      }

@@ -0,0 +1,394 @@
+/**
+ * PeerLinkRequests - links an agent asks the user to make.
+ *
+ * The agent rarely knows where the user's machines answer, so it usually
+ * names none: the user picks the machine in a card, along with the access,
+ * and their client answers with the addresses it knows for that machine and
+ * a pairing code from it, which the client mints with its own session there
+ * or the user pastes. The code goes straight
+ * to `PeerLinks.link` and is never recorded, so it never reaches the
+ * transcript, projections, or the agent's context.
+ *
+ * Asking does not wait: provider CLIs abandon a tool call after a few
+ * minutes, and a person may answer much later. The card stays open until the
+ * user answers it or stops or archives the thread, and the answer reaches the
+ * agent as a notification in its thread.
+ *
+ * @module PeerLinkRequests
+ */
+import {
+  CommandId,
+  MessageId,
+  type NodeId,
+  type OrchestrationV2Notification,
+  type OrchestrationV2TurnItem,
+  type OrchestratorMcpEnvironmentLinkInput,
+  type OrchestratorMcpEnvironmentLinkResult,
+  OrchestratorMcpFailure,
+  type PeerLink,
+  PeerLinkError,
+  PeerLinkRequestError,
+  type PeerLinkRequestAnswerInput,
+  type RunId,
+  type ThreadId,
+  TurnItemId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Semaphore from "effect/Semaphore";
+
+import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
+import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
+import * as PeerLinks from "./PeerLinks.ts";
+
+type LinkRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "link_request" }>;
+
+/** The request as it was asked, which every update of its card repeats. */
+type LinkRequestAsk = Pick<
+  LinkRequestItem,
+  "id" | "threadId" | "url" | "reason" | "environmentId" | "label" | "hint" | "requestedAccess"
+> & { readonly runId: RunId; readonly nodeId: NodeId };
+
+/** The notification that tells the agent how its card ended. */
+type LinkRequestWake = {
+  readonly messageId: MessageId;
+  readonly text: string;
+  readonly notification: OrchestrationV2Notification;
+};
+
+/** What a card update may change. */
+type LinkRequestOutcome = Pick<
+  LinkRequestItem,
+  "linkStatus" | "linkedEnvironmentId" | "linkedLabel" | "linkedAccess" | "failure"
+>;
+
+const failure = (code: OrchestratorMcpFailure["code"], message: string) =>
+  new OrchestratorMcpFailure({ code, message });
+
+const errorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : typeof error === "string" ? error : "unknown error";
+
+export class PeerLinkRequests extends Context.Service<
+  PeerLinkRequests,
+  {
+    /**
+     * Shows a link card in the calling thread and returns at once. A retry
+     * with the same clientRequestId returns the card's current outcome.
+     */
+    readonly request: (
+      scope: McpInvocationContext.McpInvocationScope,
+      input: OrchestratorMcpEnvironmentLinkInput,
+    ) => Effect.Effect<OrchestratorMcpEnvironmentLinkResult, OrchestratorMcpFailure>;
+    /**
+     * Answers a pending card and tells the agent. Linking uses the pairing
+     * code once; a link the other environment refuses closes the card as
+     * failed, with its reason.
+     */
+    readonly answer: (
+      input: PeerLinkRequestAnswerInput,
+    ) => Effect.Effect<void, PeerLinkRequestError>;
+  }
+>()("t3/peer/PeerLinkRequests") {}
+
+const make = Effect.gen(function* () {
+  const threadManagement = yield* ThreadManagementService.ThreadManagementService;
+  const peerLinks = yield* PeerLinks.PeerLinks;
+  const crypto = yield* Crypto.Crypto;
+
+  const readCard = (threadId: ThreadId, turnItemId: TurnItemId) =>
+    threadManagement
+      .getThreadRecords(threadId, ["turnItems"], {
+        turnItemTypes: ["link_request"],
+        messageRoles: [],
+      })
+      .pipe(
+        Effect.map((records) => {
+          const item = records.turnItems.find((candidate) => candidate.id === turnItemId);
+          // A deleted thread's cards went with it.
+          return item?.type === "link_request" && records.thread.deletedAt === null
+            ? item
+            : undefined;
+        }),
+      );
+
+  const record = (
+    card: LinkRequestAsk,
+    outcome: LinkRequestOutcome,
+    commandId: CommandId,
+    wake?: LinkRequestWake,
+  ) =>
+    threadManagement.dispatch({
+      type: "link_request.record",
+      commandId,
+      threadId: card.threadId,
+      runId: card.runId,
+      nodeId: card.nodeId,
+      turnItemId: card.id,
+      ...(card.url === undefined ? {} : { url: card.url }),
+      reason: card.reason,
+      ...(card.environmentId === undefined ? {} : { environmentId: card.environmentId }),
+      ...(card.label === undefined ? {} : { label: card.label }),
+      ...(card.hint === undefined ? {} : { hint: card.hint }),
+      ...(card.requestedAccess === undefined ? {} : { requestedAccess: card.requestedAccess }),
+      ...outcome,
+      ...(wake === undefined ? {} : { wake }),
+    });
+
+  const request: PeerLinkRequests["Service"]["request"] = (scope, input) =>
+    Effect.gen(function* () {
+      // The card is shown in, and answered from, the caller's own thread.
+      const threadScope = yield* McpInvocationContext.requireThreadScope(
+        scope,
+        "t3_environment_link",
+      );
+      const threadId = threadScope.thread.threadId;
+      const unreadable = (error: unknown) =>
+        failure("orchestration_error", `Unable to read the link request: ${errorMessage(error)}`);
+      if (input.url !== undefined && input.environmentId !== undefined) {
+        return yield* failure(
+          "invalid_request",
+          "Pass either environmentId or url, not both. Pass neither to let the user pick the machine.",
+        );
+      }
+      // A machine already linked needs no card: the agent can use it now.
+      if (input.environmentId !== undefined) {
+        const linked = yield* peerLinks
+          .get(input.environmentId)
+          .pipe(Effect.mapError((error) => failure("orchestration_error", error.message)));
+        if (Option.isSome(linked)) {

@@ -0,0 +1,414 @@
+// Measures React renders in a running T3 Code Dev client. See
+// docs/internals/mobile-development.md#measuring-renders.
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeSocket from "@effect/platform-node/NodeSocket";
+import {
+  CommandId,
+  EnvironmentId,
+  ExecutionEnvironmentDescriptor,
+  ORCHESTRATION_PROTOCOL_HEADER,
+  ORCHESTRATION_PROTOCOL_VERSION,
+  OrchestrationV2ShellSnapshot,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+  WsRpcGroup,
+  type OrchestrationV2ThreadProjection,
+} from "@t3tools/contracts";
+import * as Console from "effect/Console";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { Command, Flag } from "effect/cli";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { Socket } from "effect/socket";
+
+const RenderReport = Schema.Struct({
+  commits: Schema.Number,
+  totalRenders: Schema.Number,
+  components: Schema.Array(Schema.Struct({ key: Schema.String, count: Schema.Number })),
+  causes: Schema.Array(Schema.Struct({ key: Schema.String, count: Schema.Number })),
+});
+type RenderReport = typeof RenderReport.Type;
+const decodeReport = Schema.decodeUnknownEffect(Schema.fromJsonString(RenderReport));
+const InspectorTargets = Schema.Array(
+  Schema.Struct({ appId: Schema.String, webSocketDebuggerUrl: Schema.String }),
+);
+const CdpReply = Schema.Struct({
+  id: Schema.Number,
+  result: Schema.optional(
+    Schema.Struct({
+      result: Schema.optional(Schema.Struct({ value: Schema.optional(Schema.Unknown) })),
+      exceptionDetails: Schema.optional(Schema.Unknown),
+    }),
+  ),
+});
+const decodeCdpReply = Schema.decodeUnknownOption(Schema.fromJsonString(CdpReply));
+const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+
+class MeasureError extends Schema.TaggedError<MeasureError>()("MeasureError", {
+  message: Schema.String,
+}) {}
+
+const STREAM_PROMPT =
+  "Think it through step by step, then write a 3000-word essay on the history of typesetting in plain paragraphs with a few headings. Do not use any tools.";
+
+interface Options {
+  readonly server: string;
+  readonly token: string;
+  readonly metro: string;
+  readonly scheme: string;
+  readonly runs: number;
+  readonly windowSeconds: number;
+  readonly provider: string;
+  readonly model: string;
+  readonly projectRoot: string;
+}
+
+const uuid = Effect.flatMap(Crypto.Crypto, (crypto) => crypto.randomUUIDv4());
+
+const median = (values: ReadonlyArray<number>) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle]! : (sorted[middle - 1]! + sorted[middle]!) / 2;
+};
+
+/** One Hermes inspector session, reached through Metro's inspector proxy. */
+const connectInspector = Effect.fn("measure.connectInspector")(function* (metro: string) {
+  const http = yield* HttpClient.HttpClient;
+  const targets = yield* http
+    .get(`${metro}/json/list`)
+    .pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(InspectorTargets)));
+  const target = targets.find((entry) => entry.appId.startsWith("com.t3tools.t3code"));
+  if (!target)
+    return yield* new MeasureError({ message: `No T3 Code app is attached to Metro at ${metro}.` });
+  // Expo terminates inspector sockets whose Origin differs from the URL Metro
+  // advertises (the LAN address with `--lan`), so pass that URL as `--metro`.
+  const socket = yield* Socket.makeWebSocket(target.webSocketDebuggerUrl, {
+    headers: { origin: new URL(metro).origin },
+    openTimeout: "10 seconds",
+  });
+  const writer = yield* socket.writer;
+  const reader = yield* socket.reader;
+  let nextId = 0;
+  return Effect.fn("measure.evaluate")(function* (expression: string) {
+    const id = ++nextId;
+    yield* writer.write(
+      encodeJson({ id, method: "Runtime.evaluate", params: { expression, returnByValue: true } }),
+    );
+    while (true) {
+      for (const frame of yield* reader.pull) {
+        const text = typeof frame === "string" ? frame : new TextDecoder().decode(frame);
+        const reply = decodeCdpReply(text);
+        if (Option.isNone(reply) || reply.value.id !== id) continue;
+        if (reply.value.result?.exceptionDetails)
+          return yield* new MeasureError({
+            message: `Evaluation failed: ${encodeJson(reply.value.result.exceptionDetails)}`,
+          });
+        return reply.value.result?.result?.value;
+      }
+    }
+  });
+});
+
+const connectServer = Effect.fn("measure.connectServer")(function* (options: Options) {
+  const http = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.mapRequest((request) =>
+      request.pipe(
+        HttpClientRequest.bearerToken(options.token),
+        HttpClientRequest.setHeader(
+          ORCHESTRATION_PROTOCOL_HEADER,
+          String(ORCHESTRATION_PROTOCOL_VERSION),
+        ),
+      ),
+    ),
+    HttpClient.filterStatusOk,
+  );
+  const descriptor = yield* http
+    .get(`${options.server}/.well-known/t3/environment`)
+    .pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(ExecutionEnvironmentDescriptor)));
+  const shell = yield* http
+    .get(`${options.server}/api/orchestration/shell`)
+    .pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(OrchestrationV2ShellSnapshot)));
+  let projectId = shell.projects.find(
+    (project) => project.workspaceRoot === options.projectRoot,
+  )?.id;
+  // A project record outlives its folder, and turns fail without it.
+  yield* (yield* FileSystem.FileSystem).makeDirectory(options.projectRoot, { recursive: true });

@@ -7342,6 +7344,170 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
     },
   );
 
+  /**
+   * Records or updates the card for a link an agent asked the user to make.
+   * The pairing code goes straight to the link and never through orchestration.
+   */
+  const dispatchLinkRequestRecord = Effect.fn("orchestrationV2.dispatch.linkRequestRecord")(
+    function* (
+      command: Extract<OrchestrationV2InternalCommand, { readonly type: "link_request.record" }>,
+      events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
+      effects: Ref.Ref<Array<PendingOrchestrationEffectV2>>,
+    ) {
+      const projection = yield* projectionStore
+        .getThreadRecords(
+          command.threadId,
+          ["runs", "nodes", "turnItems", "attempts", "providerTurns"],
+          { turnItemTypes: ["link_request"], messageRoles: [] },
+        )
+        .pipe(
+          Effect.mapError(
+            (cause) => new OrchestratorProjectionError({ threadId: command.threadId, cause }),
+          ),
+        );
+      const run = projection.runs.find((candidate) => candidate.id === command.runId);
+      if (run === undefined || run.rootNodeId !== command.nodeId) {

@@ -0,0 +1,414 @@
+// Measures React renders in a running T3 Code Dev client. See
+// docs/internals/mobile-development.md#measuring-renders.
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeSocket from "@effect/platform-node/NodeSocket";
+import {
+  CommandId,
+  EnvironmentId,
+  ExecutionEnvironmentDescriptor,
+  ORCHESTRATION_PROTOCOL_HEADER,
+  ORCHESTRATION_PROTOCOL_VERSION,
+  OrchestrationV2ShellSnapshot,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+  WsRpcGroup,
+  type OrchestrationV2ThreadProjection,
+} from "@t3tools/contracts";
+import * as Console from "effect/Console";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { Command, Flag } from "effect/cli";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { Socket } from "effect/socket";
+
+const RenderReport = Schema.Struct({
+  commits: Schema.Number,
+  totalRenders: Schema.Number,
+  components: Schema.Array(Schema.Struct({ key: Schema.String, count: Schema.Number })),
+  causes: Schema.Array(Schema.Struct({ key: Schema.String, count: Schema.Number })),
+});
+type RenderReport = typeof RenderReport.Type;
+const decodeReport = Schema.decodeUnknownEffect(Schema.fromJsonString(RenderReport));
+const InspectorTargets = Schema.Array(
+  Schema.Struct({ appId: Schema.String, webSocketDebuggerUrl: Schema.String }),
+);
+const CdpReply = Schema.Struct({
+  id: Schema.Number,
+  result: Schema.optional(
+    Schema.Struct({
+      result: Schema.optional(Schema.Struct({ value: Schema.optional(Schema.Unknown) })),
+      exceptionDetails: Schema.optional(Schema.Unknown),
+    }),
+  ),
+});
+const decodeCdpReply = Schema.decodeUnknownOption(Schema.fromJsonString(CdpReply));
+const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+
+class MeasureError extends Schema.TaggedError<MeasureError>()("MeasureError", {
+  message: Schema.String,
+}) {}
+
+const STREAM_PROMPT =
+  "Think it through step by step, then write a 3000-word essay on the history of typesetting in plain paragraphs with a few headings. Do not use any tools.";
+
+interface Options {
+  readonly server: string;
+  readonly token: string;
+  readonly metro: string;
+  readonly scheme: string;
+  readonly runs: number;
+  readonly windowSeconds: number;
+  readonly provider: string;
+  readonly model: string;
+  readonly projectRoot: string;
+}
+
+const uuid = Effect.flatMap(Crypto.Crypto, (crypto) => crypto.randomUUIDv4());
+
+const median = (values: ReadonlyArray<number>) => {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle]! : (sorted[middle - 1]! + sorted[middle]!) / 2;
+};
+
+/** One Hermes inspector session, reached through Metro's inspector proxy. */
+const connectInspector = Effect.fn("measure.connectInspector")(function* (metro: string) {
+  const http = yield* HttpClient.HttpClient;
+  const targets = yield* http
+    .get(`${metro}/json/list`)
+    .pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(InspectorTargets)));
+  const target = targets.find((entry) => entry.appId.startsWith("com.t3tools.t3code"));
+  if (!target)
+    return yield* new MeasureError({ message: `No T3 Code app is attached to Metro at ${metro}.` });
+  // Expo terminates inspector sockets whose Origin differs from the URL Metro
+  // advertises (the LAN address with `--lan`), so pass that URL as `--metro`.
+  const socket = yield* Socket.makeWebSocket(target.webSocketDebuggerUrl, {
+    headers: { origin: new URL(metro).origin },
+    openTimeout: "10 seconds",
+  });
+  const writer = yield* socket.writer;
+  const reader = yield* socket.reader;
+  let nextId = 0;
+  return Effect.fn("measure.evaluate")(function* (expression: string) {
+    const id = ++nextId;
+    yield* writer.write(
+      encodeJson({ id, method: "Runtime.evaluate", params: { expression, returnByValue: true } }),
+    );
+    while (true) {
+      for (const frame of yield* reader.pull) {
+        const text = typeof frame === "string" ? frame : new TextDecoder().decode(frame);
+        const reply = decodeCdpReply(text);
+        if (Option.isNone(reply) || reply.value.id !== id) continue;
+        if (reply.value.result?.exceptionDetails)
+          return yield* new MeasureError({
+            message: `Evaluation failed: ${encodeJson(reply.value.result.exceptionDetails)}`,
+          });
+        return reply.value.result?.result?.value;
+      }
+    }
+  });
+});
+
+const connectServer = Effect.fn("measure.connectServer")(function* (options: Options) {
+  const http = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.mapRequest((request) =>
+      request.pipe(
+        HttpClientRequest.bearerToken(options.token),
+        HttpClientRequest.setHeader(
+          ORCHESTRATION_PROTOCOL_HEADER,
+          String(ORCHESTRATION_PROTOCOL_VERSION),
+        ),
+      ),
+    ),
+    HttpClient.filterStatusOk,
+  );
+  const descriptor = yield* http
+    .get(`${options.server}/.well-known/t3/environment`)
+    .pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(ExecutionEnvironmentDescriptor)));
+  const shell = yield* http
+    .get(`${options.server}/api/orchestration/shell`)
+    .pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(OrchestrationV2ShellSnapshot)));
+  let projectId = shell.projects.find(

@@ -0,0 +1,419 @@
+/**
+ * PeerLinkRequests - links an agent asks the user to make.
+ *
+ * The agent rarely knows where the user's machines answer, so it usually
+ * names none: the user picks the machine in a card, along with the access,
+ * and their client answers with the addresses it knows for that machine and
+ * a pairing code from it, which the client mints with its own session there
+ * or the user pastes. The code goes straight
+ * to `PeerLinks.link` and is never recorded, so it never reaches the
+ * transcript, projections, or the agent's context.
+ *
+ * Asking does not wait: provider CLIs abandon a tool call after a few
+ * minutes, and a person may answer much later. The card stays open until the
+ * user answers it or stops or archives the thread, and the answer reaches the
+ * agent as a notification in its thread.
+ *
+ * @module PeerLinkRequests
+ */
+import {
+  CommandId,
+  type EnvironmentId,
+  MessageId,
+  type NodeId,
+  type OrchestrationV2Notification,
+  type OrchestrationV2TurnItem,
+  type OrchestratorMcpEnvironmentLinkInput,
+  type OrchestratorMcpEnvironmentLinkResult,
+  OrchestratorMcpFailure,
+  type PeerLink,
+  PeerLinkError,
+  PeerLinkRequestError,
+  type PeerLinkRequestAnswerInput,
+  type RunId,
+  type ThreadId,
+  TurnItemId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as KeyedLock from "@t3tools/shared/KeyedLock";
+
+import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
+import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
+import * as PeerLinks from "./PeerLinks.ts";
+
+type LinkRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "link_request" }>;
+
+/** The request as it was asked, which every update of its card repeats. */
+type LinkRequestAsk = Pick<
+  LinkRequestItem,
+  "id" | "threadId" | "url" | "reason" | "environmentId" | "label" | "hint" | "requestedAccess"
+> & { readonly runId: RunId; readonly nodeId: NodeId };
+
+/** The notification that tells the agent how its card ended. */
+type LinkRequestWake = {
+  readonly messageId: MessageId;
+  readonly text: string;
+  readonly notification: OrchestrationV2Notification;
+};
+
+/** What a card update may change. */
+type LinkRequestOutcome = Pick<
+  LinkRequestItem,
+  "linkStatus" | "linkedEnvironmentId" | "linkedLabel" | "linkedAccess" | "failure"
+>;
+
+const errorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : typeof error === "string" ? error : "unknown error";
+
+export class PeerLinkRequests extends Context.Service<
+  PeerLinkRequests,
+  {
+    /**
+     * Shows a link card in the calling thread and returns at once. A retry
+     * with the same clientRequestId returns the card's current outcome.
+     */
+    readonly request: (
+      scope: McpInvocationContext.McpInvocationScope,
+      input: OrchestratorMcpEnvironmentLinkInput,
+    ) => Effect.Effect<OrchestratorMcpEnvironmentLinkResult, OrchestratorMcpFailure>;
+    /**
+     * Answers a pending card and tells the agent. Linking uses the pairing
+     * code once; a link the other environment refuses closes the card as
+     * failed, with its reason.
+     */
+    readonly answer: (
+      input: PeerLinkRequestAnswerInput,
+    ) => Effect.Effect<void, PeerLinkRequestError>;
+  }
+>()("t3/peer/PeerLinkRequests") {}
+
+const make = Effect.gen(function* () {
+  const threadManagement = yield* ThreadManagementService.ThreadManagementService;
+  const peerLinks = yield* PeerLinks.PeerLinks;
+  const crypto = yield* Crypto.Crypto;
+
+  const readCard = (threadId: ThreadId, turnItemId: TurnItemId) =>
+    threadManagement
+      .getThreadRecords(threadId, ["turnItems"], {
+        turnItemTypes: ["link_request"],
+        messageRoles: [],
+      })
+      .pipe(
+        Effect.map((records) => {
+          const item = records.turnItems.find((candidate) => candidate.id === turnItemId);
+          // A deleted thread's cards went with it.
+          return item?.type === "link_request" && records.thread.deletedAt === null
+            ? item
+            : undefined;
+        }),
+      );
+
+  /**
+   * The stored link to `environmentId`, or nothing once it has expired: an
+   * expired link needs a new pairing code, which only the card asks for.
+   */
+  const usableLink = (environmentId: EnvironmentId) =>
+    Effect.all([peerLinks.get(environmentId), DateTime.now]).pipe(
+      Effect.map(([linked, now]) =>
+        Option.filter(linked, (link) => DateTime.isGreaterThan(link.expiresAt, now)),

@@ -0,0 +1,424 @@
+/**
+ * PeerLinkRequests - links an agent asks the user to make.
+ *
+ * The agent rarely knows where the user's machines answer, so it usually
+ * names none: the user picks the machine in a card, along with the access,
+ * and their client answers with the addresses it knows for that machine and
+ * a pairing code from it, which the client mints with its own session there
+ * or the user pastes. The code goes straight
+ * to `PeerLinks.link` and is never recorded, so it never reaches the
+ * transcript, projections, or the agent's context.
+ *
+ * Asking does not wait: provider CLIs abandon a tool call after a few
+ * minutes, and a person may answer much later. The card stays open until the
+ * user answers it or stops or archives the thread, and the answer reaches the
+ * agent as a notification in its thread.
+ *
+ * @module PeerLinkRequests
+ */
+import {
+  CommandId,
+  type EnvironmentId,
+  MessageId,
+  type NodeId,
+  type OrchestrationV2Notification,
+  type OrchestrationV2TurnItem,
+  type OrchestratorMcpEnvironmentLinkInput,
+  type OrchestratorMcpEnvironmentLinkResult,
+  OrchestratorMcpFailure,
+  type PeerLink,
+  PeerLinkError,
+  PeerLinkRequestError,
+  type PeerLinkRequestAnswerInput,
+  type RunId,
+  type ThreadId,
+  TurnItemId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as KeyedLock from "@t3tools/shared/KeyedLock";
+
+import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
+import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
+import * as PeerLinks from "./PeerLinks.ts";
+
+type LinkRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "link_request" }>;
+
+/** The request as it was asked, which every update of its card repeats. */
+type LinkRequestAsk = Pick<
+  LinkRequestItem,
+  "id" | "threadId" | "url" | "reason" | "environmentId" | "label" | "hint" | "requestedAccess"
+> & { readonly runId: RunId; readonly nodeId: NodeId };
+
+/** The notification that tells the agent how its card ended. */
+type LinkRequestWake = {
+  readonly messageId: MessageId;
+  readonly text: string;
+  readonly notification: OrchestrationV2Notification;
+};
+
+/** What a card update may change. */
+type LinkRequestOutcome = Pick<
+  LinkRequestItem,
+  "linkStatus" | "linkedEnvironmentId" | "linkedLabel" | "linkedAccess" | "failure"
+>;
+
+const errorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : typeof error === "string" ? error : "unknown error";
+
+export class PeerLinkRequests extends Context.Service<
+  PeerLinkRequests,
+  {
+    /**
+     * Shows a link card in the calling thread and returns at once. A retry
+     * with the same clientRequestId returns the card's current outcome.
+     */
+    readonly request: (
+      scope: McpInvocationContext.McpInvocationScope,
+      input: OrchestratorMcpEnvironmentLinkInput,
+    ) => Effect.Effect<OrchestratorMcpEnvironmentLinkResult, OrchestratorMcpFailure>;
+    /**
+     * Answers a pending card and tells the agent. Linking uses the pairing
+     * code once; a link the other environment refuses closes the card as
+     * failed, with its reason.
+     */
+    readonly answer: (
+      input: PeerLinkRequestAnswerInput,
+    ) => Effect.Effect<void, PeerLinkRequestError>;
+  }
+>()("t3/peer/PeerLinkRequests") {}
+
+const make = Effect.gen(function* () {
+  const threadManagement = yield* ThreadManagementService.ThreadManagementService;
+  const peerLinks = yield* PeerLinks.PeerLinks;
+  const crypto = yield* Crypto.Crypto;
+
+  const readCard = (threadId: ThreadId, turnItemId: TurnItemId) =>
+    threadManagement
+      .getThreadRecords(threadId, ["turnItems"], {
+        turnItemTypes: ["link_request"],
+        messageRoles: [],
+      })
+      .pipe(
+        Effect.map((records) => {
+          const item = records.turnItems.find((candidate) => candidate.id === turnItemId);
+          // A deleted thread's cards went with it.
+          return item?.type === "link_request" && records.thread.deletedAt === null
+            ? item
+            : undefined;
+        }),
+      );
+
+  /**
+   * The stored link to `environmentId`, or nothing once it has expired: an
+   * expired link needs a new pairing code, which only the card asks for.
+   */
+  const usableLink = (environmentId: EnvironmentId) =>
+    Effect.all([peerLinks.get(environmentId), DateTime.now]).pipe(
+      Effect.map(([linked, now]) =>
+        Option.filter(linked, (link) => DateTime.isGreaterThan(link.expiresAt, now)),
+      ),
+    );
+
+  const record = (
+    card: LinkRequestAsk,
+    outcome: LinkRequestOutcome,
+    commandId: CommandId,
+    wake?: LinkRequestWake,
+  ) =>
+    threadManagement.dispatch({
+      type: "link_request.record",
+      commandId,
+      threadId: card.threadId,
+      runId: card.runId,
+      nodeId: card.nodeId,
+      turnItemId: card.id,
+      ...(card.url === undefined ? {} : { url: card.url }),
+      reason: card.reason,
+      ...(card.environmentId === undefined ? {} : { environmentId: card.environmentId }),
+      ...(card.label === undefined ? {} : { label: card.label }),
+      ...(card.hint === undefined ? {} : { hint: card.hint }),
+      ...(card.requestedAccess === undefined ? {} : { requestedAccess: card.requestedAccess }),
+      ...outcome,
+      ...(wake === undefined ? {} : { wake }),
+    });
+
+  const request: PeerLinkRequests["Service"]["request"] = Effect.fn("PeerLinkRequests.request")(
+    function* (scope, input) {
+      // The card is shown in, and answered from, the caller's own thread.
+      const threadScope = yield* McpInvocationContext.requireThreadScope(
+        scope,
+        "t3_environment_link",
+      );
+      const threadId = threadScope.thread.threadId;
+      const unreadable = (error: unknown) =>
+        new OrchestratorMcpFailure({
+          code: "orchestration_error",
+          message: `Unable to read the link request: ${errorMessage(error)}`,
+        });
+      if (input.url !== undefined && input.environmentId !== undefined) {
+        return yield* new OrchestratorMcpFailure({
+          code: "invalid_request",
+          message:
+            "Pass either environmentId or url, not both. Pass neither to let the user pick the machine.",
+        });
+      }
+      // A machine already linked needs no card: the agent can use it now.
+      if (input.environmentId !== undefined) {