@staix/agent-hub 0.32.0 → 0.34.0

package/src/cli/room.ts

@@ -1,3 +1,4 @@
+import { projectRoomUnavailable, projectRoomDiagnostics, type RoomStatusDiagnostics } from "../rooms/status.ts";
 import { decodeBase64url } from "../rooms/crypto.ts";
 import { roomReceiptReasonText, type RoomReceiptReason } from "../rooms/application.ts";
 import { frame, type Envelope } from "../hub/envelope.ts";
@@ -17,8 +18,9 @@ export type RoomRequest = (message: Record<string, unknown>) => Promise<any>;
 export interface RoomConfirmationIO { isTTY(): boolean; answer(prompt: string): Promise<string> }
 
 export class RoomCliError extends Error {
-  constructor(readonly code: "usage" | "refused" | "invalid_reply" | "inbox_list_limit" | "confirmation_required" | "not_confirmed" | "confirmation_mismatch" | "epoch_rotated_hold_unavailable") {
-    const message = { refused: "operation refused", invalid_reply: "invalid control reply", inbox_list_limit: "inbox list exceeds the limit; choose a room name", confirmation_required: "confirmation required; use a TTY or --confirm with the member fingerprint prefix", not_confirmed: "not confirmed; nothing executed", confirmation_mismatch: "confirmation does not match the member fingerprint; nothing executed",
+  constructor(readonly code: "usage" | "refused" | "invalid_reply" | "inbox_list_limit" | "confirmation_required" | "not_confirmed" | "confirmation_mismatch" | "epoch_rotated_hold_unavailable" | "rooms_unavailable", availability?: unknown) {
+    const unavailable = projectRoomUnavailable(availability);
+    const message = { rooms_unavailable: `unavailable (${unavailable?.code ?? "unknown"}); ${unavailable?.nextStep ?? "Run ahub status to inspect room storage before retrying."}`, refused: "operation refused", invalid_reply: "invalid control reply", inbox_list_limit: "inbox list exceeds the limit; choose a room name", confirmation_required: "confirmation required; use a TTY or --confirm with the member fingerprint prefix", not_confirmed: "not confirmed; nothing executed", confirmation_mismatch: "confirmation does not match the member fingerprint; nothing executed",
       epoch_rotated_hold_unavailable: "epoch rotated but delivery journal holds are unavailable; inspect ahub room status and ahub queue show before another mutation" };
     super(code === "usage" ? ROOM_USAGE : `room: ${message[code]}`);
     this.name = "RoomCliError";
@@ -145,7 +147,7 @@ type DeliveryState = "pending" | "dispatching" | "accepted" | "completed" | "com
 interface DeliveryRow { direction: "inbound" | "outbound"; id: string; application: string; peer: string; state: DeliveryState; disposition?: "accept" | "completed" | "retry" | "discard"; lateReceipt?: "completed (admitted)" | "completed (inbox)" | "failed_safe"; refusalReason?: RoomReceiptReason; holdReason?: "epoch rotated" }
 interface DeliverySummary { direction: "inbound"; pending: number; needsReview: number; truncated: boolean }
 interface RemotePeerRow { id: string; state: "idle" | "busy" | "paused" | "offline"; presence?: "idle" | "busy" | "paused" | "offline" | "unknown"; liveness?: "untracked" }
-interface RoomRow { name: string; room: string; owner: string; member: string; epoch: string; state: string; deliveries?: (DeliveryRow | DeliverySummary)[]; remotePeers?: RemotePeerRow[] }
+interface RoomRow extends RoomStatusDiagnostics { name: string; room: string; owner: string; member: string; epoch: string; state: string; deliveries?: (DeliveryRow | DeliverySummary)[]; remotePeers?: RemotePeerRow[] }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const REMOTE_ID = /^[a-z][a-z0-9-]{0,31}@[a-z][a-z0-9-]{0,31}$/;
 const REFUSAL_REASONS: readonly RoomReceiptReason[] = ["admitted", "not_exposed", "boundary_refused", "invalid_message", "rate_limited", "hop", "person_inbox_unsupported", "inbox_admitted", "inbox_full", "inbox_oversize", "inbox_expired", "inbox_age_unavailable"];
@@ -194,7 +196,10 @@ function record(value: unknown): Record<string, unknown> {
 }
 function success(value: unknown): Record<string, unknown> {
   const row = record(value);
-  if (row.ok !== true) fail(row.code === "epoch_rotated_hold_unavailable" ? "epoch_rotated_hold_unavailable" : "refused");
+  if (row.ok !== true) {
+    if (row.code === "rooms_unavailable") throw new RoomCliError("rooms_unavailable", row.roomsUnavailable);
+    fail(row.code === "epoch_rotated_hold_unavailable" ? "epoch_rotated_hold_unavailable" : "refused");
+  }
   return row;
 }
 function roomRows(value: unknown): RoomRow[] {
@@ -206,7 +211,7 @@ function roomRows(value: unknown): RoomRow[] {
       || typeof row.epoch !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(row.epoch)
       || typeof row.state !== "string" || !/^[a-z][a-z_-]{0,31}$/.test(row.state)) return fail("invalid_reply");
     // Ignore all other fields, even from a newer daemon: read output never grows into room bodies or secrets.
-    return { name: row.name, room: row.room, owner: row.owner, member: row.member, epoch: row.epoch, state: row.state,
+    return { name: row.name, room: row.room, owner: row.owner, member: row.member, epoch: row.epoch, state: row.state, ...projectRoomDiagnostics(row),
       ...(row.deliveries !== undefined ? { deliveries: deliveryRows(row.deliveries) } : {}), ...(row.remotePeers !== undefined ? { remotePeers: remotePeerRows(row.remotePeers) } : {}) };
   });
 }
@@ -274,6 +279,13 @@ export async function runRoomCommand(args: readonly string[], request: RoomReque
     console.log(`Rooms (${rows.length})`);
     for (const row of rows) {
       console.log(`${row.name} ${row.room} epoch ${row.epoch} ${row.state}\n  owner ${row.owner}\n  member ${row.member}`);
+      if (command.op === "status") {
+        const health = row.health, age = (value: number | null | undefined) => typeof value === "number" ? `${value}ms` : "unknown";
+        if (row.state === "online" && (row.linkCause === null || row.linkCause === undefined)) console.log("  link online");
+        else console.log(`  link cause ${row.linkCause ?? "unknown"}; next: ${row.linkNextStep ?? "Check broker availability, then read ahub room status again."}`);
+        console.log(`  outbox ${health?.outboxDepth ?? "unknown"}; oldest ${age(health?.oldestOutboxAgeMs)}; last receipt ${age(health?.lastReceiptAgeMs)}`);
+        console.log(`  refused: ${health?.refused ? Object.entries(health.refused).map(([reason, count]) => `${reason} ${count}`).join(", ") : "unknown"}`);
+      }
       for (const peer of row.remotePeers ?? []) console.log(`  peer ${peer.id}: ${peer.presence ?? peer.state}${peer.liveness === "untracked" ? "; liveness not tracked (broker without ephemeral); upgrade the broker to track liveness" : ""}`);
       for (const delivery of row.deliveries ?? []) {
         if (!("id" in delivery)) console.log(`  inbound: pending ${delivery.pending}, needs_review ${delivery.needsReview}${delivery.truncated ? "; truncated" : ""}`);

package/src/cli/runtime-version-warning.ts

@@ -1,3 +1,4 @@
+import { globalCliUpdateStep, type InstallPathOptions } from "./install-paths.ts";
 import type { DoctorCheck } from "./output.ts";
 import { parseList, pluginState, type InstalledPlugin } from "./setup.ts";
 
@@ -5,7 +6,7 @@ const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(
 const version = (value: unknown): string | undefined => typeof value === "string" && value.length <= 64 && VERSION.exec(value)?.[0] === value ? value : undefined;
 
 /** Authenticated daemon status and the existing plugin inventory only. Suggestions never run an update. */
-export function runtimeVersionWarnings(daemonVersion: unknown, cliVersion: unknown, pluginVersion: unknown): DoctorCheck[] {
+export function runtimeVersionWarnings(daemonVersion: unknown, cliVersion: unknown, pluginVersion: unknown, install: InstallPathOptions = {}): DoctorCheck[] {
   const running = version(daemonVersion), cli = version(cliVersion), plugin = version(pluginVersion);
   const rows: DoctorCheck[] = [];
   const unknown = (name: string, detail: string) => rows.push({ section: "Hub", level: "unknown", name, detail });
@@ -18,7 +19,7 @@ export function runtimeVersionWarnings(daemonVersion: unknown, cliVersion: unkno
   else try {
     cliOlder = Bun.semver.order(cli, running) < 0;
     if (cliOlder) rows.push({ section: "Hub", level: "warn", name: "CLI versus daemon",
-      detail: `running daemon ${running} is newer than this CLI ${cli}; update separately: bun add --global @staix/agent-hub@${running}` });
+      detail: `running daemon ${running} is newer than this CLI ${cli}; update separately: ${globalCliUpdateStep(running, { ...install, globalFlag: "--global" })}` });
   } catch { unknown("CLI versus daemon", "CLI and daemon versions could not be compared"); }
   if (!plugin) unknown("plugin versus daemon", "installed plugin version unavailable; run ahub setup with an updated CLI to inspect it");
   else try {
@@ -36,16 +37,16 @@ export function runtimeVersionWarnings(daemonVersion: unknown, cliVersion: unkno
  * target release's own coordinator (`AGENTHUB_UPGRADE_HANDOVER=1`, set by every release since #272), the process that prints is the target itself and cannot see the CLI that started it, but that
  * CLI is older by construction (it handed over because the target was newer), so `handedOver` stands for it. An unknown plugin (no `claude`, unreadable inventory) is never a claim.
  */
-export function globalUpdateAfterUpgrade(target: unknown, cli: unknown, plugin: unknown, handedOver = false): string[] {
+export function globalUpdateAfterUpgrade(target: unknown, cli: unknown, plugin: unknown, handedOver = false, install: InstallPathOptions = {}): string[] {
   const running = version(target);
   if (!running) return [];
-  const warned = new Set(runtimeVersionWarnings(running, handedOver ? undefined : cli, plugin).filter(row => row.level === "warn").map(row => row.name));
+  const warned = new Set(runtimeVersionWarnings(running, handedOver ? undefined : cli, plugin, install).filter(row => row.level === "warn").map(row => row.name));
   const cliOlder = handedOver || warned.has("CLI versus daemon"), pluginOlder = warned.has("plugin versus daemon");
   if (!cliOlder && !pluginOlder) return [];
   return [
     "ahub upgrade does not update the global CLI or the shared Claude plugin.",
     cliOlder
-      ? `${handedOver ? "The CLI that started this upgrade is older than the daemon this upgrade installs" : "The global CLI is older than the daemon this upgrade installs"} (${running}): run \`bun add -g @staix/agent-hub@${running}\` and then \`ahub setup\` yourself.`
+      ? `${handedOver ? "The CLI that started this upgrade is older than the daemon this upgrade installs" : "The global CLI is older than the daemon this upgrade installs"} (${running}): ${globalCliUpdateStep(running, install)} and then \`ahub setup\` yourself.`
       : `The installed plugin is older than the daemon this upgrade installs (${running}): run \`ahub setup\` yourself.`,
   ];
 }
@@ -59,6 +60,7 @@ export interface GlobalUpdateInputs {
   handedOver: boolean;
   /** Where this release's shipped plugin bundle lives, for `pluginState`. */
   packageRoot: string;
+  install?: InstallPathOptions;
   /** The same `claude plugin list --json` probe `ahub doctor` runs. */
   probe: () => { status: number | null; stdout?: string | null };
 }
@@ -74,5 +76,5 @@ export function globalUpdateAdvice(input: GlobalUpdateInputs): string[] {
     const state = pluginState(parseList<InstalledPlugin>(probed.status === 0 ? probed.stdout ?? "" : ""), input.packageRoot);
     plugin = state.state === "missing" ? undefined : state.version;
   } catch { /* an unknown plugin: the CLI half below does not depend on it */ }
-  try { return globalUpdateAfterUpgrade(input.target, input.cli, plugin, input.handedOver); } catch { return []; }
+  try { return globalUpdateAfterUpgrade(input.target, input.cli, plugin, input.handedOver, input.install); } catch { return []; }
 }

package/src/cli/setup-homes.ts

@@ -1,7 +1,8 @@
 import { checkClaudeHome, claudeHomeEnvironment, type ClaudeHome, type ClaudeHomeProbe } from "./claude-homes.ts";
-import { installClaudeProfileHook } from "./claude-profile-hook.ts";
+import { installClaudeProfileHook, type ClaudeProfileHookOptions } from "./claude-profile-hook.ts";
+import { join } from "node:path";
 
-const marketplaceRemovalRefusal = (home: string) => new Error(`Claude setup refused marketplace removal in ${home}; non-user plugin rows were preserved`);
+const marketplaceRemovalRefusal = (home: string, detail: string) => new Error(`Claude setup refused marketplace removal in ${JSON.stringify(home)}; non-user plugin rows were preserved. ${detail}. Selected home plugin inventory: ${JSON.stringify(join(home, "plugins/installed_plugins.json"))}.`);
 
 export interface SetupHomesPorts {
   env: NodeJS.ProcessEnv;
@@ -14,18 +15,20 @@ export interface SetupHomesPorts {
   ask(prompt: string): Promise<string | null>;
   print(line: string): void;
   current?(): void;
+  /** Fixed host/test hook command options; never selected from project configuration. */
+  hook?: ClaudeProfileHookOptions;
 }
 /** Selected homes only. Native plugin operations and the project-neutral hook share one person confirmation. */
 export async function setupClaudeHomes(ports: SetupHomesPorts): Promise<void> {
   ports.current?.();
   if (!ports.homes.length) { ports.print("No Claude configuration home in use was found; set CLAUDE_CONFIG_DIR to select one."); return; }
   const initial = [];
-  for (const home of ports.homes) initial.push(await checkClaudeHome(home, ports.packageRoot, ports.env, ports.probe, undefined, true));
+  for (const home of ports.homes) initial.push(await checkClaudeHome(home, ports.packageRoot, ports.env, ports.probe, undefined, true, ports.hook));
   for (const check of initial) {
     ports.print(`Claude home ${check.home.path}: plugin ${check.plugin.state}; hook ${check.hook.state}.`);
     for (const notice of ("notices" in check.plugin ? check.plugin.notices : undefined) ?? []) ports.print(`${check.home.path}: ${notice}.`);
     if (check.plugin.state === "unknown" || check.hook.state === "refused") throw new Error(`Claude setup cannot safely inspect ${check.home.path}; nothing was changed`);
-    if (check.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
+    if (check.next?.blocked) throw marketplaceRemovalRefusal(check.home.path, check.next.why);
   }
   for (const check of initial) if (check.next) ports.print(`${check.home.path}: ${check.next.blocked ? "setup blocked" : check.next.argv.join(" ")} (${check.next.why})`);
   if (initial.every(check => !check.next && check.hook.state === "installed")) return;
@@ -36,25 +39,25 @@ export async function setupClaudeHomes(ports: SetupHomesPorts): Promise<void> {
     let current = check;
     for (let step = 0; current.next && step < 6; step++) {
       const action = current.next;
-      if (action.blocked) throw marketplaceRemovalRefusal(check.home.path);
+      if (action.blocked) throw marketplaceRemovalRefusal(check.home.path, action.why);
       ports.print(`${check.home.path}: ${action.argv.join(" ")} (${action.why})`);
       ports.current?.();
       if (action.argv[2] === "marketplace" && action.argv[3] === "remove") {
-        const fresh = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true);
+        const fresh = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true, ports.hook);
         if (fresh.plugin.state === "unknown") throw new Error(`Claude plugin inventory is unavailable for ${check.home.path}`);
-        if (fresh.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
+        if (fresh.next?.blocked) throw marketplaceRemovalRefusal(check.home.path, fresh.next.why);
         if (JSON.stringify(fresh.next?.argv) !== JSON.stringify(action.argv)) { current = fresh; continue; }
         current = fresh;
         ports.current?.();
       }
       if (await ports.run(action.argv, claudeHomeEnvironment(check.home, ports.env)) !== 0) throw new Error(`Claude plugin setup failed for ${check.home.path}; no later home was changed`);
-      current = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true);
+      current = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true, ports.hook);
       if (current.plugin.state === "unknown") throw new Error(`Claude plugin inventory is unavailable for ${check.home.path}`);
-      if (current.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
+      if (current.next?.blocked) throw marketplaceRemovalRefusal(check.home.path, current.next.why);
     }
     if (current.next) throw new Error(`Claude setup exceeded six plugin steps for ${check.home.path}`);
     ports.current?.();
-    const hook = installClaudeProfileHook(check.home);
+    const hook = installClaudeProfileHook(check.home, ports.hook);
     if (hook.state !== "installed") throw new Error(hook.reason);
     ports.print(`${check.home.path}: plugin current; hook ${hook.changed ? "installed" : "current"}. ${hook.reason}`);
   }

package/src/cli/status-lines.ts

@@ -1,3 +1,4 @@
+import { projectRoomUnavailable } from "../rooms/status.ts";
 import type { ContextView } from "../hub/context-window.ts";
 import { memorySyncNextStep, type MemorySyncCause } from "../hub/memory-sync-state.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
@@ -35,7 +36,7 @@ export function memorySyncLine(sync: MemorySyncRow, time = (at: number) => new D
   const cause = (causes.includes(sync.cause ?? "") ? sync.cause : "unknown") as MemorySyncCause;
   if (cause === "declined" && sync.placementActive === false) {
     const declined = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? String(sync.declinedCount) : "unknown";
-    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store (agent-mem has no activation command yet, agent-mem#281). Inspect with `ahub memory declined`.";
+    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store. Activation is person-only: preview with `amem migrate --sync-placement --dry-run` and declare every writer via --writer-root. The hub does not yet supply the fresh placementAttestation required for active-placement sync (#1173). Inspect with `ahub memory declined`.";
   }
   const count = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? `, ${sync.declinedCount} declined` : "";
   const ids = cause === "declined" && sync.declinedIdsKnown === false ? "; declined ID set unknown" : "";
@@ -55,3 +56,9 @@ export function reviewInputHealthLine(health: ReviewInputHealthRow): string | un
   const state = health.state === "incomplete" || health.state === "corrupt" ? health.state : "unknown";
   return `${state} (${cause}); next: ${next}`;
 }
+
+/** Room failures carry a closed cause and locally generated next step only. */
+export function roomsUnavailableLine(value: unknown): string {
+  const unavailable = projectRoomUnavailable(value);
+  return `rooms: unavailable (${unavailable?.code ?? "unknown"}); next: ${unavailable?.nextStep ?? "Run ahub room status to inspect room storage and broker availability."}`;
+}

package/src/cli/terminal-recovery.ts

@@ -100,6 +100,18 @@ export interface TerminalInspection {
   byPeer: Partial<Record<TerminalPeer, TerminalBinding>>;
   blockers: RecoveryBlocker[];
   manualRequired: boolean;
+  /** #1246: terminals whose identity was verified (handle, incarnation, worktree, root, peer) and that read orphaned but still connected: the only ones a person may have switched back. */
+  orphaned?: OrphanedTerminal[];
+}
+
+/** #1246: one verified orphaned-but-connected terminal, as the plan records it. Never a session or a launch. */
+export interface OrphanedTerminal {
+  peer: TerminalPeer;
+  handle: string;
+  incarnationId: string;
+  worktreeId: string;
+  /** The terminal's worktree root as Orca reported it and the plan matched it. */
+  root: string;
 }
 
 export interface IdleResult {
@@ -206,17 +218,32 @@ function decoded(result: CommandResult): unknown {
   }
 }
 
+/** Orca's structured error, from the JSON it prints on stdout or stderr. */
+function orcaError(result: CommandResult): Record<string, unknown> {
+  const fromStdout = object(object(decoded(result)).error);
+  if (fromStdout.code !== undefined) return fromStdout;
+  try { return object(object(JSON.parse(bytes(result.stderr))).error); } catch { return {}; }
+}
+
+function errorCode(result: CommandResult): unknown {
+  return orcaError(result).code;
+}
+
+/** #1233: Orca prints its error as JSON on stdout with an empty stderr, so its code comes before the exit-status fallback. */
 function errorText(result: CommandResult): string {
+  const { code, message } = orcaError(result);
+  if (typeof code === "string") return typeof message === "string" && message !== code ? `${code}: ${message.slice(0, 200)}` : code;
   const stderr = bytes(result.stderr).trim();
   return stderr || `exit status ${commandStatus(result)}`;
 }
 
-/** Orca's structured error code, from the JSON it prints on stdout or stderr. */
-function errorCode(result: CommandResult): unknown {
-  const fromStdout = object(object(decoded(result)).error).code;
-  if (fromStdout !== undefined) return fromStdout;
-  try { return object(object(JSON.parse(bytes(result.stderr))).error).code; } catch { return undefined; }
-}
+/**
+ * Orca 1.4.250 answers a terminal it can no longer reach with one of these codes, and its own CLI groups all four as
+ * gone (docs/verification/2026-11-06-orca-1.4.250-cli-contract.md). A wait on a pane whose process ended throws
+ * terminal_exited, so restoration must read it as gone and check the launcher, not stop on a command error (#1233).
+ */
+const GONE_CODES = new Set(["terminal_handle_stale", "terminal_exited", "terminal_gone", "no_connected_pty"]);
+const GONE_STATES: Record<string, string> = { terminal_handle_stale: "no longer exists", terminal_exited: "exited (terminal_exited)" };
 
 function runnerFailure(argv: readonly string[], result: CommandResult): RecoveryBlocker {
   return { code: "command-error", message: `Orca ${argv.slice(0, 2).join(" ")} failed: ${errorText(result)}` };
@@ -226,9 +253,11 @@ async function run(runner: CommandRunner, argv: readonly string[]): Promise<unkn
   const result = await runner(argv);
   if (commandStatus(result) !== 0) {
     // Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a handle whose terminal was removed with `{"ok":false,"error":{"code":"terminal_handle_stale"}}`.
-    if (errorCode(result) === "terminal_handle_stale") {
+    const code = errorCode(result);
+    if (typeof code === "string" && GONE_CODES.has(code)) {
       const handle = argv.includes("--terminal") ? argv[argv.indexOf("--terminal") + 1] : undefined;
-      throw new OrcaCommandError({ code: "terminal-gone", message: `the Orca terminal${handle ? ` ${handle}` : ""} no longer exists` });
+      const state = GONE_STATES[code] ?? `is gone (${code})`;
+      throw new OrcaCommandError({ code: "terminal-gone", message: `the Orca terminal${handle ? ` ${handle}` : ""} ${state}` });
     }
     throw new OrcaCommandError(runnerFailure(argv, result));
   }
@@ -236,7 +265,9 @@ async function run(runner: CommandRunner, argv: readonly string[]): Promise<unkn
   const root = object(value);
   const payload = responseResult(value);
   if (root.ok === false || payload.ok === false) {
-    throw new OrcaCommandError({ code: "command-error", message: `Orca ${argv.slice(0, 2).join(" ")} returned ok:false${typeof root.error === "string" ? `: ${root.error}` : ""}` });
+    const error = root.error ?? payload.error;
+    const detail = typeof error === "string" ? error : object(error).code;
+    throw new OrcaCommandError({ code: "command-error", message: `Orca ${argv.slice(0, 2).join(" ")} returned ok:false${typeof detail === "string" && detail ? `: ${detail}` : ""}` });
   }
   return value;
 }
@@ -633,7 +664,7 @@ function blocker(code: RecoveryBlocker["code"], message: string, peer?: Terminal
     code === "ownership-unknown" ? "confirm the terminal owner in Orca, then resume recovery" :
     code === "ambiguous-terminal" ? "close or identify the duplicate terminal, then resume recovery" :
     code === "ambiguous-create" ? "inspect the existing terminal and attach the original session before resuming" :
-    code === "terminal-orphaned" ? `reattach the pane with orca terminal switch --terminal ${shellQuote(handle!)}; then refresh the recovery plan` :
+    code === "terminal-orphaned" ? `reattach the pane with orca terminal switch --terminal ${shellQuote(handle!)}; then refresh in ahub upgrade ([r] on the plan, [s] on an open operation), or rerun it` :
     code === "terminal-unready" ? "finish or cancel the active terminal turn, then resume recovery" :
     code === "launcher-exited" ? "the session was not restored; the coordinator's error names the choices" :
     code === "terminal-gone" ? "the terminal was closed; inspect the project's terminals in Orca before resuming recovery" :
@@ -641,6 +672,48 @@ function blocker(code: RecoveryBlocker["code"], message: string, peer?: Terminal
   return { code, message, ...(peer ? { peer } : {}), ...(handle ? { handle, terminalReference: handle } : {}), nextAction };
 }
 
+/** #1246: how long a switched pane is re-read before it still counts as orphaned. Orca's `terminal show` can lag a switch by a moment. */
+export const REATTACH_BOUND_MS = 5_000;
+const REATTACH_POLL_MS = 250;
+
+/**
+ * #1246: the one mutation the upgrade menu offers for an orphaned-but-connected pane: `orca terminal switch` for exactly
+ * this handle, after reading it again and finding the identity the plan verified (handle, incarnation, worktree, root)
+ * still orphaned and connected. It then re-reads the pane until `orphaned` is false, at most `boundMs`. A pane that is
+ * already not orphaned is `reattached` with no switch. A changed identity, a disconnected pane or any failed Orca call is
+ * `unavailable` (nothing, or nothing more, was done); a pane still orphaned at the bound stays `still-orphaned`.
+ */
+export async function reattachOrphanedTerminal(terminal: OrphanedTerminal, options?: CommandRunner | TerminalRecoveryOptions, boundMs = REATTACH_BOUND_MS): Promise<"reattached" | "still-orphaned" | "unavailable"> {
+  const config = normalizeOptions(options);
+  const read = async (): Promise<Record<string, unknown> | undefined> => {
+    const shown = terminalObject(await run(config.runner, ["terminal", "show", "--terminal", terminal.handle, "--json"]));
+    const same = nestedString(shown, ["handle"]) === terminal.handle && nestedString(shown, ["incarnationId"]) === terminal.incarnationId && nestedString(shown, ["worktreeId"]) === terminal.worktreeId
+      && rootMatches(shown.worktreePath ?? shown.projectRoot, terminal.root);
+    return same ? shown : undefined;
+  };
+  // The runner is also bounded by its caller; this race keeps a runner that ignores its timeout from holding the screen past the bound.
+  const within = async <T>(work: Promise<T>, ms: number): Promise<T> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try { return await Promise.race([work, new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("reattach bound exceeded")), ms); })]); }
+    finally { if (timer) clearTimeout(timer); }
+  };
+  try {
+    const before = await within(read(), boundMs);
+    if (!before) return "unavailable";
+    if (before.orphaned === false) return "reattached";
+    if (before.orphaned !== true || before.connected !== true) return "unavailable";
+    await within(run(config.runner, ["terminal", "switch", "--terminal", terminal.handle, "--json"]), boundMs);
+    const deadline = Date.now() + boundMs;
+    for (;;) {
+      const shown = await within(read(), deadline - Date.now());
+      if (!shown) return "unavailable";
+      if (shown.orphaned === false) return "reattached";
+      if (Date.now() >= deadline) return "still-orphaned";
+      await Bun.sleep(Math.min(REATTACH_POLL_MS, deadline - Date.now()));
+    }
+  } catch { return "unavailable"; }
+}
+
 function verifyBindingData(actual: Record<string, unknown>, binding: TerminalBinding): RecoveryBlocker | undefined {
   const handle = nestedString(actual, ["handle"]);
   const incarnation = nestedString(actual, ["incarnationId"]);
@@ -714,6 +787,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
   const config = normalizeOptions(options);
   const blockers: RecoveryBlocker[] = [];
   const bindings: TerminalBinding[] = [];
+  const orphaned: OrphanedTerminal[] = [];
   const byPeer: Partial<Record<TerminalPeer, TerminalBinding>> = {};
   const requested = (Object.entries(sessions) as [TerminalPeer, string | SessionRef | undefined][]).map(([peer, value]) => [peer, typeof value === "string" ? { sessionId: value } : value] as const).filter((entry): entry is [TerminalPeer, SessionRef] => !!entry[1]?.sessionId);
   if (!requested.length) return { bindings, byPeer, blockers, manualRequired: false };
@@ -795,7 +869,8 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       continue;
     }
     if (terminal.orphaned === true && terminal.connected === true) {
-      blockers.push(blocker("terminal-orphaned", `terminal ${handle} is orphaned but still connected`, peer, handle));
+      blockers.push(blocker("terminal-orphaned", `the ${peer} terminal ${handle} in ${projectRoot} is orphaned but still connected`, peer, handle));
+      orphaned.push({ peer, handle, incarnationId, worktreeId, root: expectedTerminalRoot });
       continue;
     }
     if (terminal.orphaned === true || terminal.connected === false) {
@@ -811,19 +886,22 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
     bindings.push(binding);
     byPeer[peer] = binding;
   }
-  return { bindings, byPeer, blockers, manualRequired: blockers.length > 0 };
+  return { bindings, byPeer, blockers, manualRequired: blockers.length > 0, ...(orphaned.length ? { orphaned } : {}) };
 }
 
 /**
  * One bounded Orca wait. Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a wait that timed out with exit 1 and `{"ok":false,"error":{"code":"timeout"}}`:
- * that is "not satisfied", not a failure. Any other failure still throws.
+ * that is "not satisfied", not a failure. Any other failure still throws. 1.4.250 also answers ok with `satisfied: false`
+ * and a `blockedReason` (seen: `agent-update-prompt`) when the TUI waits on a prompt; the reason is passed on (#1233).
  */
-async function waitSatisfied(runner: CommandRunner, handle: string, timeoutMs: number): Promise<boolean> {
+async function waitSatisfied(runner: CommandRunner, handle: string, timeoutMs: number): Promise<{ satisfied: boolean; blockedReason?: string }> {
   const argv = ["terminal", "wait", "--terminal", handle, "--for", "tui-idle", "--timeout-ms", String(timeoutMs), "--json"];
   const result = await runner(argv);
-  if (commandStatus(result) !== 0 && errorCode(result) === "timeout") return false;
+  if (commandStatus(result) !== 0 && errorCode(result) === "timeout") return { satisfied: false };
   const root = responseResult(await run(async () => result, argv));
-  return root.satisfied === true || object(root.wait).satisfied === true;
+  if (root.satisfied === true || object(root.wait).satisfied === true) return { satisfied: true };
+  const reason = root.blockedReason ?? object(root.wait).blockedReason;
+  return typeof reason === "string" ? { satisfied: false, blockedReason: reason.slice(0, 100) } : { satisfied: false };
 }
 
 /** Wait only on the captured terminal and only for Orca's supported TUI-idle condition. */
@@ -832,8 +910,8 @@ export async function waitForIdle(binding: TerminalBinding, timeoutMs: number, o
   const timeout = Number.isFinite(timeoutMs) && timeoutMs >= 0 ? Math.min(Math.floor(timeoutMs), MAX_WAIT_MS) : 0;
   try {
     await showBinding(binding, config);
-    const satisfied = await waitSatisfied(config.runner, binding.handle, timeout);
-    const blockers = satisfied ? [] : [blocker("terminal-unready", `terminal ${binding.handle} did not become idle before the bounded wait`, binding.peer, binding.handle)];
+    const { satisfied, blockedReason } = await waitSatisfied(config.runner, binding.handle, timeout);
+    const blockers = satisfied ? [] : [blocker("terminal-unready", `terminal ${binding.handle} did not become idle before the bounded wait${blockedReason ? ` (Orca: blocked by ${blockedReason})` : ""}`, binding.peer, binding.handle)];
     return { satisfied, manualRequired: !satisfied, blockers };
   } catch (error) {
     const item = error instanceof OrcaCommandError ? error.blocker : blocker("command-error", String(error), binding.peer, binding.handle);

package/src/cli/upgrade-interactive.ts

@@ -1,3 +1,4 @@
+import { globalCliUpdateStep } from "./install-paths.ts";
 import { definitionOf } from "../adapters/registry.ts";
 import { renderPlan, renderOperation, renderBlocked, renderSummary, renderStep, renderWait, renderMenu, choiceInstruction, type RecoveryPresentationOptions, type MenuPresentationItem } from "./upgrade-presentation.ts";
 import { quoted, wrap } from "./console-state.ts";
@@ -5,6 +6,7 @@ import { operationLines, stepLabel } from "./upgrade-labels.ts";
 export { operationLines, stepLabel } from "./upgrade-labels.ts";
 import { recoveryArgv } from "../hub/recovery-store.ts";
 import { cancellableWait, nextChoices, publicOperation, type Inspection, type PlannedProject, type RecoveryOperation, type RecoveryPeer, type UpgradePlan } from "./upgrade.ts";
+import { shellQuote, type OrphanedTerminal } from "./terminal-recovery.ts";
 
 /**
  * #272: the interactive screens of `ahub upgrade`, `ahub restart` and bare `ahub recovery`. They add no way to change
@@ -36,6 +38,11 @@ export interface UpgradeHost {
   apply(plan: UpgradePlan, interrupted: () => boolean): Promise<RecoveryOperation>;
   /** End one attached agent now: close a TUI agent's terminal, or ask the hub to stop a headless one. One line of outcome. */
   endPeer(planned: PlannedProject, peer: RecoveryPeer): Promise<string>;
+  /**
+   * #1246: switch back exactly these verified orphaned-but-connected panes of one project and wait, bounded, until each reads
+   * not orphaned. One line of outcome each. Optional: a host without it never offers the key.
+   */
+  reattachTerminals?(planned: PlannedProject, terminals: readonly OrphanedTerminal[]): Promise<string[]>;
   /** This selected project's hold, or an authoritative retained legacy machine hold. A reset may name another project. */
   lock(projectRoot?: string): string | undefined;
   read(id: string): RecoveryOperation;
@@ -106,12 +113,14 @@ function peerAction(planned: PlannedProject, peer: RecoveryPeer): string {
   if (peer.state === "offline") return "offline, left as it is";
   if (planned.unrecordedTerminals?.includes(peer.id)) return planned.reconnectOnly?.includes(peer.id)
     ? "attached, launcher unrecorded; reconnects by itself (its terminal is left alone)"
-    : "attached, launcher unrecorded; end it in its terminal or resume the original conversation, then refresh the plan";
+    : "attached, launcher unrecorded; end it in its terminal or resume the original conversation, then press [r] refresh";
   if (planned.reconnectOnly?.includes(peer.id)) return "reconnects by itself (unmanaged session; its terminal is left alone)";
   if (planned.freshStart?.includes(peer.id)) return "restarts as a new session (no turn to lose)";
   const terminal = (planned.terminals as { peer: string; handle: string }[]).find((t) => t.peer === peer.id);
   if (terminal) return `resumes its session in a new terminal (replaces ${terminal.handle})`;
-  if (peerKind(planned, peer) === "unmanaged") return "attached, terminal ownership unverified; resolve its evidence or end it in its terminal or resume the original conversation, then refresh the plan";
+  const orphan = planned.orphanedTerminals?.find((t) => t.peer === peer.id);
+  if (orphan) return `attached, terminal ${orphan.handle} is orphaned but still connected; reattach it with orca terminal switch --terminal ${shellQuote(orphan.handle)} (the upgrade menu's [t] does it), then press [r] refresh`;
+  if (peerKind(planned, peer) === "unmanaged") return "attached, terminal ownership unverified; resolve its evidence or end it in its terminal or resume the original conversation, then press [r] refresh";
   return definitionOf(peer.id)?.session.restoreOnStart ? "restarts headless on its recorded session" : "restarts headless as a new session";
 }
 
@@ -335,15 +344,18 @@ export async function planScreen(host: UpgradeHost, io: ScreenIO): Promise<void>
     if (io.presentation) emit(io, renderPlan(plan, host.version, io.presentation, planLines(plan, host.version)));
     else for (const line of planLines(plan, host.version)) human(io, line);
     const blocked = plan.blockers.length > 0 || plan.projects.some((p) => p.blockers.length > 0);
-    if (!plan.projects.length) human(io, plan.kind === "upgrade" && plan.scope === undefined ? `no hub is running, so nothing is carried over: install with \`bun add -g @staix/agent-hub@${plan.version}\`, then \`ahub setup\`` : "this project's hub is not running: `ahub up` starts it");
+    if (!plan.projects.length) human(io, plan.kind === "upgrade" && plan.scope === undefined ? `no hub is running, so nothing is carried over: ${globalCliUpdateStep(plan.version)}, then \`ahub setup\`` : "this project's hub is not running: `ahub up` starts it");
     const endable = plan.projects.flatMap((p) => p.source.peers.filter((peer) => ["tui", "headless"].includes(peerKind(p, peer))).map((peer) => ({ planned: p, peer })));
-    const keys = [...(blocked ? [] : ["[a] apply"]), "[r] refresh", ...(endable.length ? ["[k] end agents"] : []), "[j] plan as JSON", ...(plan.projects.length ? ["[x] reset a project's hub"] : []), "[q] quit"];
+    // #1246: only the terminals the plan verified as orphaned but still connected, and only on a host that can switch them.
+    const orphaned = host.reattachTerminals ? plan.projects.flatMap((p) => (p.orphanedTerminals ?? []).map((terminal) => ({ planned: p, terminal }))) : [];
+    const keys = [...(blocked ? [] : ["[a] apply"]), "[r] refresh", ...(orphaned.length ? [`[t] reattach ${orphaned.length} orphaned terminal${orphaned.length === 1 ? "" : "s"}`] : []), ...(endable.length ? ["[k] end agents"] : []), "[j] plan as JSON", ...(plan.projects.length ? ["[x] reset a project's hub"] : []), "[q] quit"];
     const preferred = "r"; // Enter never closes terminals, stops a hub, resumes or reattaches implicitly.
     if (io.presentation) {
-      if (blocked) human(io, "Blocked: take the next action each blocker names, then refresh.");
+      if (blocked) human(io, "Blocked: take the next action each blocker names, then press [r] refresh.");
       const items: MenuPresentationItem[] = [
         ...(!blocked ? [{ key: "a", label: "apply this reviewed plan" }] : []),
         { key: "r", label: "refresh the plan", recommended: preferred === "r" },
+        ...(orphaned.length ? [{ key: "t", label: `reattach ${orphaned.length} orphaned terminal${orphaned.length === 1 ? "" : "s"} (orca terminal switch; nothing else changes)` }] : []),
         ...(endable.length ? [{ key: "k", label: "end selected agents before upgrading", destructive: true }] : []),
         { key: "j", label: "plan as JSON" },
         ...(plan.projects.length ? [{ key: "x", label: "reset a project's hub", destructive: true }] : []),
@@ -351,12 +363,23 @@ export async function planScreen(host: UpgradeHost, io: ScreenIO): Promise<void>
       ];
       emit(io, renderMenu(items, io.presentation));
     }
-    const entered = (await ask(io, io.presentation ? "> " : `${blocked ? "Blocked: take the next action each blocker names, then refresh.\n" : ""}${keys.join("  ")}: `))?.toLowerCase();
+    const entered = (await ask(io, io.presentation ? "> " : `${blocked ? "Blocked: take the next action each blocker names, then press [r] refresh.\n" : ""}${keys.join("  ")}: `))?.toLowerCase();
     const answer = entered === undefined ? "q" : io.presentation && entered === "" ? preferred : entered;
     if (answer === "q") return touched ? undefined : human(io, "nothing was changed");
     if (answer === "j") io.out(JSON.stringify(plan, null, 2));
     else if (answer === "x" && plan.projects.length) { touched = true; await resetFlow(host, io, plan.projects.map((p) => p.project)); }
     else if (answer === "k" && endable.length) touched = (await endAgents(host, io, endable)) || touched;
+    else if (answer === "t" && orphaned.length) {
+      touched = true;
+      for (const p of plan.projects) {
+        const mine = (p.orphanedTerminals ?? []);
+        if (!mine.length) continue;
+        if (io.interrupted()) { human(io, "interrupted: no further terminal was switched"); break; }
+        try { for (const line of await host.reattachTerminals!(p, mine)) human(io, `  ${line}`); }
+        catch (error) { human(io, `  ${p.project.id}: not reattached (${(error as Error).message}). Next: inspect the terminal in Orca, then press [r] refresh`); }
+      }
+      // The loop plans again: a terminal that reads not orphaned is no blocker, one that does not stays one.
+    }
     else if (answer === "a" && !blocked) {
       touched = true;
       let op: RecoveryOperation;

package/src/cli/upgrade-output.ts

@@ -1,5 +1,6 @@
+import { globalCliUpdateStep } from "./install-paths.ts";
 // Human output for the commands #814 T3 converts: the non-interactive restart/upgrade plan, `recovery status`, and
-// `budget execution configure|disable`. Pure: data in, lines out. It only composes the renderers the interactive
+// `budget execution configure|disable`. Recovery rendering is data in, lines out; CLI update advice inspects the install path. It composes the renderers the interactive
 // screens already use (`planLines`, `renderPlan`, `renderOperation`, `renderBlocked`, `choiceInstruction`), so the
 // non-interactive text never says something the screens would not. `--json` is the caller's branch and prints the
 // document exactly as before.
@@ -22,7 +23,7 @@ export function renderUpgradePlan(plan: UpgradePlan, current: string, options: R
   const out = renderPlan(plan, current, options, planLines(plan, current));
   const blocked = plan.blockers.length > 0 || plan.projects.some(project => project.blockers.length > 0);
   if (!plan.projects.length) out.push(...text(plan.kind === "upgrade"
-    ? `No hub is running, so nothing is carried over: install with \`bun add -g @staix/agent-hub@${plan.version}\`, then \`ahub setup\`.`
+    ? `No hub is running, so nothing is carried over: ${globalCliUpdateStep(plan.version)}, then \`ahub setup\`.`
     : "This project's hub is not running: `ahub up` starts it.", "muted", options));
   out.push(...text(blocked
     ? "Blocked: take the next action each blocker names, then run this again. Nothing was changed."

package/src/cli/upgrade-runtime.ts

@@ -17,7 +17,7 @@ import { awaitStopped, inspectProject } from "../hub/lifecycle.ts";
 import type { Project } from "../hub/registry.ts";
 import { canonicalPath, hubHome, realPath } from "../hub/project.ts";
 import { packageDigest, preserveRuntimePackage, preserveRuntimeSource, stageCurrentRuntime, registryRelease, runCommand, stageRelease, verifyPackage, type RunCommand } from "./recovery-package.ts";
-import { inspectSavedTerminal, inspectTerminals, closeTerminal, createTerminal, launcherOf, recordPath, waitForIdle, shellQuote, type SessionRef, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
+import { inspectSavedTerminal, inspectTerminals, closeTerminal, createTerminal, launcherOf, recordPath, reattachOrphanedTerminal, REATTACH_BOUND_MS, waitForIdle, shellQuote, type OrphanedTerminal, type SessionRef, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
 import { ReattachmentRequired, MissingRecordedSession, FinalRefusal, planFingerprint, recoveryScope, registeredProjects, targetReadsWaivers, type Inspection, type PlannedProject, type ProjectProgress, type RecoveryDriver, type RecoveryOperation, type RecoveryPeer, type UpgradePlan } from "./upgrade.ts";
 import { SHARED_CHANNEL_VERSION_ARGV, nativeRecordedSessionState } from "../adapters/definitions/native-recovery.ts";
 import { refreshManager } from "../hub/manager.ts";
@@ -65,9 +65,9 @@ function legacyTargetLists(root: string, probe: { file: string; exportName: stri
   return !!values && new RegExp(`["']${name}["']`).test(values);
 }
 
-function terminalOptions(run: RunCommand = runCommand): TerminalRecoveryOptions {
+function terminalOptions(run: RunCommand = runCommand, timeoutMs = 610_000): TerminalRecoveryOptions {
   return { orcaExecutable: orcaExecutable(), runner: async (args) => {
-    const result = await run([orcaExecutable(), ...args], { timeoutMs: 610_000 });
+    const result = await run([orcaExecutable(), ...args], { timeoutMs });
     return { status: result.code, stdout: result.stdout, stderr: result.stderr };
   } };
 }
@@ -420,12 +420,42 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
         ? `${unresumable(binding)}; manual-required; next action: make that store readable, then make a new plan`
         : `${unresumable(binding)}, and the hub cannot show that no turn ran on it, so its conversation may not come back after the restart; manual-required; next action: end that Codex session and close its Orca terminal ${binding.handle} (ahub codex starts a new one later), then make a new plan`);
     }
-    body.projects.push({ project, source, terminals: terminals.bindings, blockers, ...(reconnectOnly.length ? { reconnectOnly } : {}), ...(unrecordedTerminals.length ? { unrecordedTerminals } : {}), ...(freshStart.length ? { freshStart } : {}) });
+    body.projects.push({ project, source, terminals: terminals.bindings, blockers, ...(reconnectOnly.length ? { reconnectOnly } : {}), ...(unrecordedTerminals.length ? { unrecordedTerminals } : {}), ...(freshStart.length ? { freshStart } : {}), ...(terminals.orphaned?.length ? { orphanedTerminals: terminals.orphaned } : {}) });
   }
   if (!body.projects.length) body.blockers.push("no running registered projects in scope");
   return { ...body, fingerprint: planFingerprint(body) };
 }
 
+/** #1246: one line of outcome per `reattachOrphanedTerminal` result. */
+const REATTACH_LINES: Record<Awaited<ReturnType<typeof reattachOrphanedTerminal>>, (name: string, handle: string) => string> = {
+  reattached: (name, handle) => `${name}: terminal ${handle} reattached`,
+  "still-orphaned": (name, handle) => `${name}: terminal ${handle} is still orphaned after the switch; it stays a blocker. Next: inspect it in Orca, then press [r] refresh`,
+  unavailable: (name, handle) => `${name}: terminal ${handle} not switched or not confirmed (its identity changed, it is not connected, or Orca did not answer). Next: inspect it in Orca, then press [r] refresh`,
+};
+
+/**
+ * #1246: switch back the orphaned-but-connected panes the plan verified, and nothing else. Each handle is read again by
+ * `reattachOrphanedTerminal` (identity, still orphaned and connected) before `orca terminal switch`, then polled for at
+ * most 5 s, and every Orca call is itself bounded by that time. A recovery hold on this project (or the machine) refuses all of them. One line of outcome per terminal; the caller plans again.
+ */
+export async function reattachPlannedTerminals(planned: PlannedProject, terminals: readonly OrphanedTerminal[], deps: { run?: RunCommand; home?: string; lock?: (projectRoot: string) => string | undefined; boundMs?: number } = {}): Promise<string[]> {
+  const { run = runCommand, home = hubHome(), boundMs = REATTACH_BOUND_MS } = deps;
+  // The project's own hold (project_locks) as well as a legacy machine hold: recoveryLock without a root reads only the latter.
+  const lock = deps.lock ?? ((projectRoot: string) => recoveryLock(home, projectRoot));
+  const verified = terminals.filter((t) => planned.orphanedTerminals?.some((o) => o.handle === t.handle && o.incarnationId === t.incarnationId && o.worktreeId === t.worktreeId && o.root === t.root && o.peer === t.peer));
+  const lines: string[] = [];
+  for (const terminal of terminals) {
+    const name = `${planned.project.id}/${terminal.peer}`;
+    if (!verified.includes(terminal)) { lines.push(`${name}: terminal ${terminal.handle} is not one the plan verified; not switched. Next: press [r] refresh to re-plan`); continue; }
+    let owner: string | undefined;
+    try { owner = lock(planned.project.root); } catch (error) { lines.push(`${name}: terminal ${terminal.handle} not switched (${(error as Error).message}). Next: check the recovery state, then press [r] refresh`); continue; }
+    if (owner) { lines.push(`${name}: terminal ${terminal.handle} not switched (recovery operation ${owner} holds the lock). Next: wait for or resume that operation, then press [r] refresh`); continue; }
+    const result = await reattachOrphanedTerminal(terminal, terminalOptions(run, boundMs), boundMs);
+    lines.push(REATTACH_LINES[result](name, terminal.handle));
+  }
+  return lines;
+}
+
 /** Freeze the coordinator/source package before its mutable global installation is replaced. */
 export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
   if (plan.projects?.length === 0) throw new Error("no running projects to recover");

package/src/cli/upgrade.ts

@@ -15,7 +15,7 @@ import { hubHome } from "../hub/project.ts";
 import { readRecoveryWaits } from "./recovery-waits.ts";
 import { acquireRecoveryLock, claimRunner, coordinatorCurrent, operationIdPattern, readOperation, recoveryCommand, recoveryLock, releaseRecoveryLock, writeOperation } from "../hub/recovery-store.ts";
 import { resolveAcceptedBinding, piArchiveExit, recordedPeerGuidance, type RecoveryNativePeer } from "./recovery-guidance.ts";
-import type { TerminalBinding } from "./terminal-recovery.ts";
+import type { OrphanedTerminal, TerminalBinding } from "./terminal-recovery.ts";
 import { RecoveryPresentationError, type RecoveryPresentationCause, type RecoveryWaitTiming } from "./upgrade-presentation-data.ts";
 
 const projectDefinition = (peer: string, root?: string) => {
@@ -65,6 +65,8 @@ export interface PlannedProject {
   unrecordedTerminals?: string[];
   /** #215: Codex threads with no rollout and no turn the hub recorded; they restart as a new session, nothing to lose. */
   freshStart?: string[];
+  /** #1246: verified terminals that read orphaned but still connected; the plan menu may switch exactly these. Part of the fingerprint. */
+  orphanedTerminals?: OrphanedTerminal[];
 }
 export interface UpgradePlan {
   schema: 1;