@staix/agent-hub 0.33.0 → 0.34.1

package/src/cli/install-paths.ts

@@ -0,0 +1,71 @@
+import { lstatSync, readlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { realPath } from "../hub/project.ts";
+
+export interface InstallPathOptions {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  globalFlag?: "-g" | "--global";
+}
+// Contract: #1245 limits lexical symlink inspection to eight hops; unknown paths use the resolved fallback.
+const MAX_LINK_HOPS = 8;
+const samePath = (left: string, right: string): boolean => {
+  try { return realPath(left) === realPath(right); } catch { return false; }
+};
+
+/** Follow only the leaf links, preserving lexical parent aliases such as current/. */
+function lexicalTarget(entry: string): string | undefined {
+  let link = resolve(entry);
+  const seen = new Set<string>();
+  try {
+    for (let hops = 0; hops <= MAX_LINK_HOPS; hops++) {
+      if (seen.has(link)) return;
+      seen.add(link);
+      if (!lstatSync(link).isSymbolicLink()) return link;
+      if (hops === MAX_LINK_HOPS) return;
+      link = resolve(dirname(link), readlinkSync(link));
+    }
+  } catch { /* Missing, unreadable and cyclic aliases are not evidence of this install. */ }
+}
+
+/** The PATH entry's canonical target must also be a CLI entry, not just a lookalike parent. */
+function pathPackageRoot(invocation: string): string | undefined {
+  const target = lexicalTarget(invocation);
+  if (!target?.endsWith(`${sep}src${sep}cli${sep}main.js`)) return;
+  try {
+    const canonical = realPath(invocation);
+    if (!canonical.endsWith(`${sep}src${sep}cli${sep}main.js`)) return;
+    const candidate = dirname(dirname(dirname(target)));
+    return samePath(candidate, dirname(dirname(dirname(canonical)))) ? candidate : undefined;
+  } catch { return; }
+}
+
+/** Bun resolves argv[1], Bun.main and import.meta.dir, through both bun <link> and a shebang (native probe, #1245). */
+export function stablePackageRoot(root: string, options: { invocation?: string } = {}): string {
+  const invocation = options.invocation ?? Bun.which("ahub", { PATH: process.env.PATH });
+  const candidate = invocation ? pathPackageRoot(invocation) : undefined;
+  return candidate && samePath(candidate, root) ? candidate : root;
+}
+
+export function stableBunRuntime(options: { runtime?: string; pathRuntime?: string } = {}): string {
+  const runtime = options.runtime ?? process.execPath, candidate = options.pathRuntime ?? Bun.which("bun", { PATH: process.env.PATH });
+  return candidate && lexicalTarget(candidate) && samePath(candidate, runtime) ? candidate : runtime;
+}
+
+/** Advice only; a staged daemon upgrade does not update the person's global CLI installation. */
+export function globalCliUpdateStep(version?: string, options: InstallPathOptions = {}): string {
+  const env = options.env ?? process.env;
+  const invocation = Bun.which("ahub", { PATH: env.PATH ?? "" });
+  const root = invocation ? pathPackageRoot(invocation) : undefined;
+  const generic = `update the global CLI${version ? ` to ${version}` : ""} the way it was installed`;
+  if (!root) return generic;
+  const global = join(env.BUN_INSTALL || join(options.home ?? homedir(), ".bun"), "install/global/node_modules");
+  let bunGlobal = false;
+  try {
+    const within = relative(realPath(global), realPath(root));
+    bunGlobal = within !== "" && within !== ".." && !within.startsWith(`..${sep}`) && !isAbsolute(within);
+  } catch { /* An unproven Bun prefix must not suggest updating a different CLI. */ }
+  if (bunGlobal) return `run \`bun add ${options.globalFlag ?? "-g"} @staix/agent-hub${version ? `@${version}` : ""}\``;
+  return `${generic} (running from ${root})`;
+}

package/src/cli/main.ts

@@ -43,6 +43,7 @@ import { readAutonomyDefaults, writeAutonomyDefaults } from "../hub/autonomy-def
 import { inheritMachineAutonomy, prepareAutonomyProject, runAllProjectAutonomy, type PreparedAutonomyProject } from "./autonomy-projects.ts";
 import { offlineAutonomyStatus } from "./autonomy-offline.ts";
 import { autonomyHomeStatus, usedClaudeHomes } from "./autonomy-homes.ts";
+import { shellQuote } from "./shell-quote.ts";
 import { discoverClaudeHomes } from "./claude-homes.ts";
 import { setupClaudeHomes } from "./setup-homes.ts";
 import { registerAconPlugin } from "./acon-register.ts";
@@ -89,7 +90,7 @@ import { createInterface as lineReader } from "node:readline";
 import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, writeOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner, supportsAction } from "../hub/recovery-store.ts";
 import { childEnv, personEnv } from "../hub/child-process.ts";
 import { abortRecovery, createOperation, disposeRecovery, recordRecoveryDelegation, repairedFreshSession, reattachRecovery, liveProjects, nextChoices, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation, type Inspection } from "./upgrade.ts";
-import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
+import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource, reattachPlannedTerminals } from "./upgrade-runtime.ts";
 import { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts";
 import { globalUpdateAdvice, runtimeVersionWarnings } from "./runtime-version-warning.ts";
 import { operationScreen, planScreen, type ScreenIO, type UpgradeHost } from "./upgrade-interactive.ts";
@@ -722,6 +723,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
     endInspection: recoveryEndInspection,
     afterCompleted: (op) => globalUpdateLines(op.plan.version),
     endPeer: (planned, peer) => endPlannedPeer(planned, peer),
+    reattachTerminals: (planned, terminals) => reattachPlannedTerminals(planned, terminals),
     runnerStoppable: (id) => signedRunner(id) !== undefined,
     stopRunner: (id) => stopSignedRunner(id),
     entry: join(import.meta.dir, "main.js"),
@@ -2931,6 +2933,23 @@ const commands: Record<string, () => Promise<void> | void> = {
       }
       const plugin = pluginState(parseList<InstalledPlugin>(spawnSync(DOCTOR_PLUGIN_PROBE.command, [...DOCTOR_PLUGIN_PROBE.argv], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
       row(plugin.state === "current", DOCTOR_PLUGIN_PROBE.name, plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
+      let profileRegistry: Registry | undefined;
+      try {
+        profileRegistry = new Registry();
+        const profiles = await autonomyHomeStatus(profileRegistry, homedir(), process.env, join(import.meta.dir, "..", ".."), (argv, options) => {
+          const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 });
+          return { status: result.status ?? -1, stdout: result.stdout ?? "" };
+        });
+        for (const profile of profiles.homes) {
+          const installed = profile.hook.state === "installed";
+          checks.push({ name: `Claude profile hook: ${profile.home.path}`, section: "Hub", level: installed ? "ok" : "warn",
+            detail: installed ? profile.hook.reason : `${profile.hook.reason} Run CLAUDE_CONFIG_DIR=${shellQuote(profile.home.path)} ahub setup.` });
+        }
+        if (!profiles.complete) checks.push({ name: "Claude profile discovery", section: "Hub", level: "unknown",
+          detail: profiles.notices.join("; ") || "Claude profile discovery is incomplete; inspect the registered projects and selected homes before setup." });
+      } catch {
+        checks.push({ name: "Claude profile discovery", section: "Hub", level: "unknown", detail: "Claude profile inventory is unavailable; inspect the machine registry and selected homes before setup." });
+      } finally { profileRegistry?.close(); }
       if (up) checks.push(...runtimeVersionWarnings(daemonVersion, VERSION, plugin.state === "missing" ? undefined : plugin.version));
 
       const config = loadConfig(cwd);

package/src/cli/recovery-package.ts

@@ -212,24 +212,32 @@ export function stageCurrentRuntime(sourceRoot: string, version: string, home =
   } finally { if (!registry) owner.close(); }
 }
 
+/** #1253: npm 12 wraps `npm view --json` output for one package in a one-element array; npm 11 printed the value itself. Anything else is not one release. */
+function npmViewJson(stdout: string): unknown {
+  let value: unknown;
+  try { value = JSON.parse(stdout); } catch { return undefined; }
+  if (!Array.isArray(value)) return value;
+  return value.length === 1 ? value[0] : undefined;
+}
+
 export async function registryRelease(version: string, run: RunCommand = runCommand): Promise<{ version: string; integrity: string }> {
   exactVersion(version);
   const result = await run(["npm", "view", `@staix/agent-hub@${version}`, "version", "dist.integrity", "--json"], { timeoutMs: 30_000 });
   if (result.code !== 0) throw new Error(`registry metadata unavailable for @staix/agent-hub@${version}`);
-  const data = JSON.parse(result.stdout);
-  if (data.version !== version || typeof data["dist.integrity"] !== "string" || !data["dist.integrity"].startsWith("sha512-")) {
-    throw new Error("registry returned an unexpected release identity");
+  const data = npmViewJson(result.stdout) as Record<string, unknown> | undefined;
+  const integrity = data?.["dist.integrity"];
+  if (data?.version !== version || typeof integrity !== "string" || !integrity.startsWith("sha512-")) {
+    throw new Error(`registry returned an unexpected release identity for @staix/agent-hub@${version} (expected one release with a sha512 integrity from \`npm view --json\`); check \`npm view @staix/agent-hub@${version} version dist.integrity --json\` and your npm version`);
   }
-  return { version, integrity: data["dist.integrity"] };
+  return { version, integrity };
 }
 
 /** #272: the registry's latest release, the target when `--to` is left out. */
 export async function latestRelease(run: RunCommand = runCommand): Promise<string> {
   const result = await run(["npm", "view", "@staix/agent-hub", "version", "--json"], { timeoutMs: 30_000 });
   if (result.code !== 0) throw new Error("registry metadata unavailable for @staix/agent-hub; name the release with --to <version>");
-  let version: unknown;
-  try { version = JSON.parse(result.stdout); } catch { /* reported below */ }
-  if (typeof version !== "string") throw new Error("registry returned an unexpected latest release; name the release with --to <version>");
+  const version = npmViewJson(result.stdout);
+  if (typeof version !== "string") throw new Error("registry returned an unexpected latest release (expected one version from `npm view --json`); check `npm view @staix/agent-hub version --json`, or name the release with --to <version>");
   return exactVersion(version);
 }
 

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/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 {
@@ -652,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" :
@@ -660,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"]);
@@ -733,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 };
@@ -814,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) {
@@ -830,7 +886,7 @@ 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 } : {}) };
 }
 
 /**

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;

package/src/hub/handoff.ts

@@ -130,7 +130,7 @@ export function resolveTarget(name: string, projects: readonly RegisteredProject
 export function handoffConnectFailure(error: unknown, target: { id: string; root: string }): { code: HandoffRefusalCode; reach: "unreachable"; cause: string; message: string } {
   const code = typeof (error as { code?: unknown })?.code === "number" || typeof (error as { code?: unknown })?.code === "string" ? (error as { code: number | string }).code : undefined;
   if (code === 4426) return { code: "older_target", reach: "unreachable", cause: "wire version differs",
-    message: `the hub of ${target.id} speaks another wire version than this one: upgrade whichever is older (\`ahub upgrade\` in ${target.root}, and the global CLI with \`bun add -g @staix/agent-hub\`), then hand the task off again` };
+    message: `the hub of ${target.id} speaks another wire version than this one: upgrade whichever is older (\`ahub upgrade\` in ${target.root}, and the global CLI the way it was installed; \`ahub doctor\` names the exact step), then hand the task off again` };
   if (code === 4404) return { code: "mismatch", reach: "unreachable", cause: "another hub or instance answered",
     message: `the hub answering for ${target.root} is not the instance this project's registry names (it was restarted, or another project took its port): run \`ahub projects\` to see what is registered, and \`ahub up\` in ${target.root} if it is not running` };
   if (code === "AHUB_CONNECT_TIMEOUT") return { code: "not_running", reach: "unreachable", cause: "no answer in time",