@staix/agent-hub 0.12.39 → 0.12.40

package/src/cli/main.ts

@@ -17,12 +17,12 @@ import { profileName, projectProfile, resolveProfile } from "../hub/profiles.ts"
 import { catalogAssignments, loadRoleCatalog, selectedRoles } from "../hub/roles.ts";
 import { attachWatch } from "./watch.ts";
 import { verifiedJcodeCommand } from "../adapters/jcode.ts";
-import { configureJcodeMcp } from "./jcode-mcp.ts";
+import { configureJcodeMcp, jcodeExtraMcpServers } from "./jcode-mcp.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { isPermissionMode } from "../hub/permission-mode.ts";
 import { parseSettingText, settingDef, settingText, type SettingRow } from "../hub/settings.ts";
 import { startModeOf } from "../hub/start-mode.ts";
-import { currentRouting } from "../hub/routing.ts";
+import { OVERLAY_FILE, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -50,13 +50,13 @@ import { createInterface } from "node:readline/promises";
 import { createInterface as lineReader } from "node:readline";
 import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner, supportsAction } from "../hub/recovery-store.ts";
 import { childEnv } from "../hub/child-process.ts";
-import { abortRecovery, createOperation, disposeRecovery, repairedFreshSession, reattachRecovery, liveProjects, nextChoices, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation, type Inspection } from "./upgrade.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 { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts";
 import { operationScreen, planScreen, type ScreenIO, type UpgradeHost } from "./upgrade-interactive.ts";
 import { readRecoveryPresentationFlags } from "./upgrade-presentation-flags.ts";
 import { renderOperation, renderBlocked, renderSummary, type RecoveryPresentationOptions } from "./upgrade-presentation.ts";
-import { recordTerminalLaunch, type TerminalPeer } from "./terminal-recovery.ts";
+import { recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, type TerminalPeer } from "./terminal-recovery.ts";
 import { stopAndArchiveSummary } from "./recovery-guidance.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 import { setupOllamaModel } from "./models-setup.ts";
@@ -74,7 +74,7 @@ import { summarize, summarizeByTask } from "../hub/report.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
 import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
-import { recordCliAudit } from "./identity-audit.ts";
+import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
 import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, type DoctorCheck } from "./output.ts";
@@ -167,7 +167,7 @@ const delegatedPeer = liveTest && caller.role === "tools" && commandAccess !== "
 const identity = delegatedPeer ? { role: "console" as const } : caller;
 function audit(outcome: "run" | "refused" | "invalid"): void {
   if (caller.role === "console") return;
-  try { recordCliAudit(stateDir, caller.role === "tools" ? caller.peer : "unknown", commandLabel, delegatedPeer && outcome === "run" ? "delegated" : outcome); }
+  try { recordCliAudit(stateDir, caller.role === "tools" ? caller.peer : "unknown", commandLabel, outcome); }
   catch {
     if (delegatedPeer) fail("live-test delegation audit unavailable; nothing was executed");
     console.error("ahub: CLI audit could not be recorded (outbox unavailable or full)");
@@ -176,7 +176,42 @@ function audit(outcome: "run" | "refused" | "invalid"): void {
 if (identity.role === "invalid") { audit("invalid"); fail(`${identity.reason}; use ahub console or a terminal with no agent markers`); }
 if (delegationRefused) { audit("refused"); fail(LIVE_TEST_PERSON_REFUSAL); }
 if (identity.role === "tools" && commandAccess === "console") { audit("refused"); fail(peerCommandRefusal(identity.peer, commandLabel)); }
-if (identity.role === "tools" || delegatedPeer) audit("run");
+// Recovery keeps its authoritative delegation audit in the operation receipt, independent of an old source drain.
+// With no daemon manifest, local bootstrap commands have no consumer to negotiate with; use the compatible outcome.
+const recoveryAudit = ["upgrade", "restart", "recovery", "recovery-run"].includes(cmd);
+const noAuditConsumer = !existsSync(join(stateDir, "status.json")) && !existsSync(join(stateDir, "hub.pid"));
+let delegatedAuditHub: ControlClient | undefined;
+let delegatedConnectionTaken = false;
+let releaseAuditInstance: (() => void) | undefined;
+if (delegatedPeer && !recoveryAudit && !noAuditConsumer) {
+  let published = false;
+  try {
+    const auditId = await recordDelegatedCliAudit(stateDir, delegatedPeer, commandLabel, async () => {
+      // The validated invocation already has operational console authority; a tools hello would add a roster gate.
+      delegatedAuditHub = await ControlClient.connect(stateDir, { role: "console", projectRoot: cwd });
+      return delegatedAuditHub.instanceId ? delegatedAuditHub.features : [];
+    });
+    published = true;
+    releaseAuditInstance = ControlClient.pinInstance(stateDir, delegatedAuditHub!.instanceId!);
+    assertDelegatedAuditConsumer();
+    const retained = await delegatedAuditHub!.request({ t: "cli_audit_ack", auditId }, 3000);
+    if (retained.ok !== true || retained.auditId !== auditId || retained.instanceId !== delegatedAuditHub!.instanceId) {
+      throw new Error("live-test audit retention was not confirmed; nothing was executed; inspect the hub or upgrade it before retrying");
+    }
+  } catch (error) {
+    releaseAuditInstance?.(); delegatedAuditHub?.close();
+    if (published) {
+      try { recordCliAudit(stateDir, delegatedPeer, commandLabel, "refused"); }
+      catch { fail("live-test delegation audit unavailable; nothing was executed"); }
+    }
+    fail((error as Error).message);
+  }
+} else if (identity.role === "tools" || delegatedPeer) audit("run");
+function assertDelegatedAuditConsumer(): void {
+  if (delegatedAuditHub && ((!delegatedConnectionTaken && !delegatedAuditHub.isOpen) || readControl(stateDir)?.instanceId !== delegatedAuditHub.instanceId)) {
+    throw new Error("delegated audit consumer changed; refusing further actions; inspect the result before retrying");
+  }
+}
 // Forward only to ahub's own continuation commands, never to native agent argv or an environment flag.
 const liveTestArgs = liveTest ? ["--live-test"] : [];
 const invokedFrom = process.cwd(); // relative paths a person types (a bench suite) are theirs, not the project's
@@ -199,7 +234,12 @@ function printOutput(lines: Span[][], color: boolean): void {
 }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
-const connect = () => ControlClient.connect(stateDir, identity.role === "tools" ? { role: "tools", peer: identity.peer, projectRoot: cwd } : { role: "console", projectRoot: cwd });
+const connect = async () => {
+  assertDelegatedAuditConsumer();
+  if (delegatedAuditHub && !delegatedConnectionTaken) { delegatedConnectionTaken = true; return delegatedAuditHub; }
+  return ControlClient.connect(stateDir, identity.role === "tools" ? { role: "tools", peer: identity.peer, projectRoot: cwd }
+    : { role: "console", projectRoot: cwd, ...(delegatedAuditHub ? { instanceId: delegatedAuditHub.instanceId } : {}) });
+};
 
 function registeredProject(): Project {
   const registry = new Registry();
@@ -509,7 +549,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
       if (current.fingerprint !== plan.fingerprint) throw new Error("the plan changed during review; review it again");
       // The check above takes seconds: a Ctrl+C in that time is still a no.
       if (interrupted()) throw new Error("interrupted; nothing was started");
-      const operation = createOperation(plan, preserveSource(plan));
+      const operation = createOperation(plan, preserveSource(plan), undefined, delegatedPeer ? { peer: delegatedPeer, command: kind } : undefined);
       spawnRecovery(operation, true);
       return operation;
     },
@@ -583,7 +623,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   const current = await makeUpgradePlan(kind, plan.version, kind === "restart" ? cwd : undefined);
   if (current.fingerprint !== plan.fingerprint) fail("plan changed during review; run the command again");
   const sourceRoot = preserveSource(plan);
-  const operation = createOperation(plan, sourceRoot);
+  const operation = createOperation(plan, sourceRoot, undefined, delegatedPeer ? { peer: delegatedPeer, command: kind } : undefined);
   if (display.json) { spawnRecovery(operation, true); console.log(JSON.stringify(publicOperation(operation), null, 2)); }
   else spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
 }
@@ -707,8 +747,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       else if (humanRecovery(false)) printRecoveryStatus(operation, `runner ${runner} is still working on this operation`, display.options);
       else console.log(`runner ${runner} is still working on this operation; ${recoveryCommand(operation, "status")}`);
     }
-    else if (display.json) { spawnRecovery(operation, true); console.log(JSON.stringify(publicOperation(operation), null, 2)); }
-    else spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
+    else {
+      if (delegatedPeer) operation = recordRecoveryDelegation(operation.id, { peer: delegatedPeer, command: "recovery resume" });
+      if (display.json) { spawnRecovery(operation, true); console.log(JSON.stringify(publicOperation(operation), null, 2)); }
+      else spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
+    }
   },
   "recovery-run": async () => {
     if (args.length !== 1 || process.env.AGENTHUB_RECOVERY_OPERATION !== args[0]) fail("recovery-run is an internal command");
@@ -859,7 +902,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       projectConfig, connect: nativeConnect, fail,
       exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
       execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, selectedInstance ?? entry.command, context.executionCwd), takeFlags,
-      helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, recoveryLock, processSignature,
+      helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, recoveryLock, processSignature,
         buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
         nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,
         buildKimiTuiLaunch, startModeOf },
@@ -1551,7 +1594,9 @@ const commands: Record<string, () => Promise<void> | void> = {
     // #258: the hub's own memory on this machine; reads are anyone's, changes a person's.
     if (args.filter(arg => arg !== "--json")[0] === "profile-check") {
       if (args.some(arg => arg !== "profile-check" && arg !== "--json")) fail("usage: ahub memory profile-check [--json]");
-      const result = await checkMemoryProfiles(selectedMemoryProfile());
+      let selected: ReturnType<typeof selectedMemoryProfile>;
+      try { selected = selectedMemoryProfile(); } catch (e) { return fail((e as Error).message); } // an inactive split names the resume remedy
+      const result = await checkMemoryProfiles(selected);
       console.log(args.includes("--json") ? JSON.stringify(result, null, 2) : formatMemoryProfileCheck(result));
       if (!result.ready) process.exitCode = 1;
       return;
@@ -1887,9 +1932,16 @@ const commands: Record<string, () => Promise<void> | void> = {
       const config = loadConfig(cwd);
       row(!config.ignored, "config", config.ignored ? `${config.ignored.join("; ")} (move them to .agenthub/config.local.json)` : "no machine-local field ignored");
       for (const line of config.retired ?? []) row(false, "retired setting", line);
+      const { routing, errors: routingErrors } = inspectDoctorRouting(cwd);
+      for (const error of routingErrors) row(false, "routing", error);
       for (const probe of nativeDoctorOptionalProbes(config)) {
         if (probe.kind === "source-identity") row(verifiedJcodeCommand(probe.command, cwd), probe.name, probe.detail);
-        else {
+        else if (probe.kind === "jcode-mcp") {
+          const { servers, unreadable } = jcodeExtraMcpServers(cwd, probe.home);
+          row(servers.length || unreadable.length ? false : true, probe.name,
+            [servers.length ? `${servers.length} besides the hub's own would load in the hub-owned jcode (${servers.join(", ")}); jcode has no switch to choose them, so remove them from its config or use another JCODE_HOME` : "",
+              unreadable.length ? `unreadable or unsafe, not listed: ${unreadable.join(", ")}` : ""].filter(Boolean).join("; ") || "none besides the hub's own");
+        } else {
           const v = version(probe.command[0]!);
           row(v === probe.expected, probe.name, v === probe.expected ? probe.confirmed : probe.unconfirmed);
         }
@@ -1898,15 +1950,18 @@ const commands: Record<string, () => Promise<void> | void> = {
       const gateway = await omni.base();
       row(gateway ? true : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? false : undefined, "omniroute", gateway ? `${new URL(gateway).host} healthy` : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? "no candidate reachable (VPN off?); ahub local cannot run" : "not configured: set omniroute.urls in .agenthub/config.local.json (any OpenAI-compatible gateway); ahub local cannot run");
       row(!!omni.apiKey(), "omniroute key", omni.apiKey() ? "present" : "missing: set OMNIROUTE_API_KEY or omniroute.api_key_file in .agenthub/config.local.json");
-      if (gateway && omni.apiKey()) {
+      if (!routing) {
+        row(undefined, "routing models", "routing could not be read");
+      } else if (gateway && omni.apiKey()) {
         try {
-          const fixed = currentRouting(cwd).local.fixed_model;
-          const served = (await omni.models()).includes(fixed);
-          row(served, "local fixed_model", served ? `${fixed} served` : `${fixed} is not served by the gateway`);
-        } catch { row(undefined, "local fixed_model", "could not read the gateway model inventory"); }
-      }
-      const sy = spawnSync(process.env.AGENTHUB_SWITCHYARD_BIN ?? "switchyard-server", ["--version"], { encoding: "utf8" });
-      row(sy.status === 0 ? true : undefined, "switchyard", sy.status === 0 ? sy.stdout.trim() : "not installed: ahub local uses fixed_model on OmniRoute (cargo install --locked switchyard-server)");
+          const aliases = new Set([routing.local.fixed_model, ...Object.values(routing.classes).flatMap(policy => policy.fixed_model ? [policy.fixed_model] : []),
+            ...Object.values(routing.hub_routes ?? {}).flatMap(route => [route.efficient ?? "fast", route.capable ?? "coding", ...(route.judge ? [route.judge] : [])])]);
+          const served = new Set(await omni.models());
+          const missing = [...aliases].filter(alias => !served.has(alias)).sort();
+          for (const alias of missing) row(false, "routing model", `${alias} is not served by the gateway`);
+          if (!missing.length) row(true, "routing models", `all ${aliases.size} routing aliases are served`);
+        } catch { row(undefined, "routing models", "could not read the gateway model inventory"); }
+      } else row(undefined, "routing models", "gateway model inventory unavailable");
       const mlxConfig = config.mlx;
       if (mlxConfig.enabled === false) row(true, "pi mlx", "disabled (mlx.enabled=false; local endpoint not probed)");
       else {
@@ -1931,6 +1986,60 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 };
 
+function sanitizeRoutingParseError(file: "routing.toml" | "routing.local.toml", error: unknown): string {
+  const raw = ((error as Error)?.message || "invalid TOML").split("\n")[0]!.trim();
+  const cleaned = raw
+    .replace(/^(TOML Parse error: Strings must be quoted): ".*"$/, "$1")
+    .replace(/^(TOML Parse error: Cannot redefine (?:key|table)) '.*'$/, "$1")
+    .replace(/^Invalid regular expression: \/.*\/[a-z]*: /, "Invalid regular expression: ");
+  return cleaned.startsWith(`${file}:`) ? `.agenthub/${cleaned}`
+    : cleaned.startsWith(`.agenthub/${file}:`) ? cleaned
+    : `.agenthub/${file}: ${cleaned}`;
+}
+
+function inspectDoctorRouting(cwd: string): { routing?: Routing; errors: string[] } {
+  const errors: string[] = [];
+  let baseText: string | undefined;
+  try {
+    baseText = readFileSync(join(cwd, ".agenthub", "routing.toml"), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") baseText = routingText(cwd);
+    else errors.push(sanitizeRoutingParseError("routing.toml", error));
+  }
+  let baseRouting: Routing | undefined;
+  if (baseText !== undefined) {
+    try {
+      baseRouting = parseRouting(baseText);
+    } catch (error) {
+      errors.push(sanitizeRoutingParseError("routing.toml", error));
+    }
+  }
+  let overlayText: string | undefined;
+  try {
+    overlayText = readFileSync(join(cwd, ".agenthub", OVERLAY_FILE), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      errors.push(sanitizeRoutingParseError("routing.local.toml", error));
+    }
+  }
+  let overlay: RoutingOverlay | undefined;
+  if (overlayText !== undefined) {
+    try {
+      overlay = parseOverlay(overlayText);
+    } catch (error) {
+      errors.push(sanitizeRoutingParseError("routing.local.toml", error));
+    }
+  }
+  if (errors.length || !baseText) return { errors };
+  if (overlay === undefined) return { routing: baseRouting, errors };
+  try {
+    return { routing: parseRouting(baseText, overlay), errors };
+  } catch (error) {
+    errors.push(sanitizeRoutingParseError("routing.local.toml", error));
+    return { errors };
+  }
+}
+
 async function runConductorCommand(): Promise<void> {
   let op: string;
   let input: Record<string, unknown>;
@@ -1958,8 +2067,9 @@ async function runConductorCommand(): Promise<void> {
 }
 const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? (() => fail(`unknown command "${cmd}"; run ahub help`));
 try {
+  assertDelegatedAuditConsumer(); // Local command paths must not begin after the authenticated consumer was replaced either.
   await run();
 } catch (e) {
   audit("refused");
   fail((e as Error).message);
-}
+} finally { releaseAuditInstance?.(); delegatedAuditHub?.close(); }

package/src/cli/output.ts

@@ -10,13 +10,15 @@ export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" |
 export interface StatusOutput {
   pendingRestart?: readonly { key: string; reason: string }[];
   retainedConfig?: readonly { key: string; reason: string }[];
+  /** #572 AC3: advisory, present while the project root checkout is on a branch other than the default. */
+  mainCheckout?: string;
   taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
   taskWip?: Record<string, { wip: number; wipLimit: number }>;
   pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
-  tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[]; switchyard?: string;
+  tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[];
 }
 export interface BudgetOutput { budget: Record<string, any>; gate?: number }
 export interface RosterRow { peer: string; on: boolean; startMode: string; state: string; queued: number; tasks: number }
@@ -192,6 +194,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
   for (const pending of data.pendingRestart ?? []) out.push(...detail("pending restart", `${pending.key}: ${pending.reason}`, columns, "attention"));
+  if (data.mainCheckout) out.push(...detail("main checkout", data.mainCheckout, columns, "attention"));
   if (data.retainedConfig?.length) {
     out.push(...detail("config retained", `${data.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, columns, "attention"));
     for (const pending of data.retainedConfig) out.push(...detail("retained reason", `${pending.key}: ${pending.reason}`, columns, "attention"));
@@ -244,6 +247,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
+    if (typeof p.importantWaitingSince === "number" && p.importantWaitingNote) out.push(...detail("important waiting", `${p.importantWaitingNote.replace(/^\d+ important messages? waiting/, "important messages waiting")}`, columns, "attention"));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));
     return out;
   });
@@ -255,7 +259,6 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     out.push([], ...rows(["MODEL", "STATE", "ACTIVE", "REQUESTED", "ACTUAL", "PROVIDER"], data.models.backends.map(b => [span(backendLabel(b)), span(b.state ?? "unknown", stateTone(b.state ?? "")), span(b.active || "-"), span(b.requestedModel ?? "-"), span(b.actualModel ?? "-"), span(b.provider ?? "-")]), columns));
     for (const b of data.models.backends) for (const [key, label] of [["coolingUntil", "cooling"], ["failingUntil", "dispatch held"]]) if (b[key!]) { const at = Date.parse(b[key!]); out.push(...detail(`${backendLabel(b)} ${label}`, `${Number.isFinite(at) ? relative(at, now) : "unknown"}${key === "coolingUntil" && typeof b.failures === "number" ? ` after ${b.failures} failures` : key === "failingUntil" ? "; no load moves until then" : ""}`, columns, "attention")); }
   }
-  if (data.switchyard) out.push(...detail("switchyard", data.switchyard, columns));
   const counts = Object.entries(data.tasks ?? {}).map(([state, count]) => `${count} ${state}`).join(", ");
   if (counts) out.push([], ...lines(`TASKS  ${counts} (ahub board)`, columns));
   return out;

package/src/cli/status-lines.ts

@@ -1,7 +1,7 @@
 import type { ContextView } from "../hub/context-window.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */

package/src/cli/terminal-recovery.ts

@@ -10,6 +10,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { atomicPrivateJSON } from "../hub/recovery-store.ts";
+import type { ControlClient } from "../hub/control-client.ts";
 
 /** The only terminal commands used by this adapter. Keep this list in sync with Orca's public CLI. */
 export type OrcaTerminalCommand = "list" | "show" | "wait" | "close" | "create";
@@ -73,6 +74,7 @@ export interface RecoveryBlocker {
     | "ownership-unknown"
     | "ambiguous-terminal"
     | "terminal-unready"
+    | "terminal-orphaned"
     | "command-error"
     | "ambiguous-create"
     | "launcher-exited"
@@ -443,7 +445,7 @@ export async function launcherOf(peer: TerminalPeer, projectRoot: string, option
  * Capture the Orca terminal handed to an ahub launcher. This is the authenticated
  * identity source for legacy Orca payloads that omit agent/session metadata.
  */
-export async function recordTerminalLaunch(peer: TerminalPeer, projectRoot: string, stateDir: string, instanceId: string, options?: CommandRunner | TerminalRecoveryOptions): Promise<RecordedTerminalLaunch | undefined> {
+export async function prepareTerminalLaunch(peer: TerminalPeer, projectRoot: string, stateDir: string, instanceId: string, options?: CommandRunner | TerminalRecoveryOptions): Promise<RecordedTerminalLaunch | undefined> {
   const config = normalizeOptions(options);
   const handle = process.env.ORCA_TERMINAL_HANDLE;
   const worktreeIdFromEnv = process.env.ORCA_WORKTREE_ID;
@@ -465,17 +467,59 @@ export async function recordTerminalLaunch(peer: TerminalPeer, projectRoot: stri
   process.env.AGENTHUB_LAUNCH_ID = launchId;
   process.env.AGENTHUB_INSTANCE_ID = instanceId;
   const row: RecordedTerminalLaunch = { peer, projectRoot, ...(!definitionOf(peer) ? { executionCwd: expectedRoot, terminalRoot: actualRoot } : {}), stateDir, instanceId, launcherPid: process.pid, launcherSignature, launchId, handle, incarnationId, worktreeId: actualWorktree, env: allowedEnv({ env: process.env }) };
+  return row;
+}
+
+/** Decode a console candidate against this daemon, never against paths supplied by that candidate. */
+export function terminalLaunchCandidate(value: unknown, projectRoot: string, stateDir: string, instanceId: string): RecordedTerminalLaunch | undefined {
+  if (!validRecord(value) || JSON.stringify(value).length > 32 * 1024 || value.projectRoot !== projectRoot || value.stateDir !== stateDir || value.instanceId !== instanceId ||
+      !Number.isSafeInteger(value.launcherPid) || value.launcherPid <= 0 || value.launchId.length > 128 || value.launcherSignature.length > 256) return undefined;
+  try {
+    const expected = executionRoot(value.peer, projectRoot, value.executionCwd);
+    if (value.executionCwd !== undefined && value.executionCwd !== expected || value.terminalRoot !== undefined && value.terminalRoot !== projectRoot && value.terminalRoot !== expected) return undefined;
+    return { peer: value.peer, projectRoot, stateDir, instanceId, launcherPid: value.launcherPid, launcherSignature: value.launcherSignature,
+      launchId: value.launchId, handle: value.handle, incarnationId: value.incarnationId, worktreeId: value.worktreeId,
+      ...(value.executionCwd ? { executionCwd: value.executionCwd } : {}), ...(value.terminalRoot ? { terminalRoot: value.terminalRoot } : {}), env: allowedEnv({ env: object(value.env) }) };
+  } catch { return undefined; }
+}
+
+/** Old daemons may launch the TUI, but cannot turn a pre-attach candidate into recovery authority. */
+export async function registerTerminalLaunch(client: Pick<ControlClient, "features" | "request">, row: RecordedTerminalLaunch, operationId?: string): Promise<void> {
+  if (!client.features.includes("terminal_owner")) {
+    console.error("terminal launcher is unrecorded; upgrade the running hub for managed terminal recovery");
+    return;
+  }
+  const result = await client.request({ t: "terminal_launch", launch: row, ...(operationId ? { operationId } : {}) });
+  if (result.ok !== true) throw new Error("terminal launch registration failed; inspect ahub status before launching again");
+}
+
+/** Capture alone is not ownership: a refused native child must leave the live row untouched. */
+export async function recordTerminalLaunch(peer: TerminalPeer, projectRoot: string, stateDir: string, instanceId: string, options?: CommandRunner | TerminalRecoveryOptions, isCurrentOwner?: (row: RecordedTerminalLaunch) => boolean): Promise<RecordedTerminalLaunch | undefined> {
+  const row = await prepareTerminalLaunch(peer, projectRoot, stateDir, instanceId, options);
+  if (!row || !isCurrentOwner) return undefined;
+  return await publishTerminalLaunch(stateDir, row, () => isCurrentOwner(row), options) ? row : undefined;
+}
+
+/** Only the daemon's current native-owner proof may publish a captured candidate. No await after its final fence. */
+export async function publishTerminalLaunch(stateDir: string, row: RecordedTerminalLaunch, isCurrent: () => boolean, options?: CommandRunner | TerminalRecoveryOptions): Promise<boolean> {
+  const config = normalizeOptions(options);
+  if (!isCurrent() || await launcherState(row, config.processIdentity, config.legacyIdentity) !== "live") return false;
+  const terminal = terminalObject(await run(config.runner, ["terminal", "show", "--terminal", row.handle, "--json"]));
+  const expectedRoot = executionRoot(row.peer, row.projectRoot, row.executionCwd);
+  if (nestedString(terminal, ["handle"]) !== row.handle || nestedString(terminal, ["incarnationId"]) !== row.incarnationId ||
+      nestedString(terminal, ["worktreeId"]) !== row.worktreeId || nestedString(terminal, ["worktreePath", "projectRoot"]) !== (row.terminalRoot ?? expectedRoot)) return false;
+  if (await launcherState(row, config.processIdentity, config.legacyIdentity) !== "live" || !terminalLaunchCandidate(row, row.projectRoot, stateDir, row.instanceId) || !isCurrent()) return false;
   const existing = launchRecords(stateDir);
   // #215: rewriting an unreadable file would replace every other launcher's record with this one, and recovery would
   // then read those launchers as gone.
   if (existing === "unreadable") {
-    throw new OrcaCommandError(blocker("command-error", `${recordPath(stateDir)} cannot be read, so recording this launch would erase every other launcher's record; next action: inspect that file and move it aside (recovery then treats sessions it recorded as unmanaged), then launch again`, peer, handle));
+    throw new OrcaCommandError(blocker("command-error", `${recordPath(stateDir)} cannot be read, so recording this launch would erase every other launcher's record; next action: inspect that file and move it aside (recovery then treats sessions it recorded as unmanaged), then launch again`, row.peer, row.handle));
   }
   // #228: every row that cannot be evaluated goes back unchanged; only this peer's valid row for this instance is replaced.
-  const rows = existing.all.filter((item) => !(validRecord(item) && item.peer === peer && item.instanceId === instanceId));
+  const rows = existing.all.filter((item) => !(validRecord(item) && item.peer === row.peer && item.projectRoot === row.projectRoot && item.instanceId === row.instanceId));
   rows.push(row);
   writeLaunchRecords(stateDir, rows);
-  return row;
+  return true;
 }
 
 function rootMatches(actual: unknown, expected: string): boolean {
@@ -567,6 +611,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-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" :
@@ -610,6 +655,7 @@ export async function inspectSavedTerminal(binding: TerminalBinding, options?: C
     if (!completeIdentity(shown)) return unknown();
     const issue = verifyBindingData(shown, binding);
     if (issue) return { state: "changed", blocker: issue };
+    if (shown.orphaned === true && shown.connected === true) return { state: "unknown", blocker: blocker("terminal-orphaned", "the saved terminal is orphaned but still connected", binding.peer, binding.handle) };
     if (shown.orphaned === true) return { state: "orphaned", blocker: blocker("terminal-gone", "the saved terminal is orphaned", binding.peer, binding.handle) };
     if (shown.connected === false) return unknown();
     return { state: "present" };
@@ -725,6 +771,10 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       blockers.push(blocker("stale-terminal", `terminal metadata lacks a stable handle, incarnation or worktree id`, peer, handle));
       continue;
     }
+    if (terminal.orphaned === true && terminal.connected === true) {
+      blockers.push(blocker("terminal-orphaned", `terminal ${handle} is orphaned but still connected`, peer, handle));
+      continue;
+    }
     if (terminal.orphaned === true || terminal.connected === false) {
       blockers.push(blocker("terminal-unready", `terminal ${handle} is orphaned or disconnected`, peer, handle));
       continue;

package/src/cli/upgrade-interactive.ts

@@ -84,6 +84,7 @@ const left = (op: { id: string; sourceRoot?: string }, io: ScreenIO): string =>
 export function peerKind(planned: PlannedProject, peer: RecoveryPeer): "tui" | "headless" | "unmanaged" | "offline" {
   if (peer.state === "offline") return "offline";
   if ((planned.terminals as { peer: string }[]).some((t) => t.peer === peer.id)) return "tui";
+  if (planned.unrecordedTerminals?.includes(peer.id)) return "unmanaged";
   const unrecorded = definitionOf(peer.id)?.session.unrecordedTerminal;
   if (unrecorded === "always" || unrecorded === "tui" && peer.args?.mode === "tui") return "unmanaged";
   return "headless";
@@ -91,10 +92,14 @@ export function peerKind(planned: PlannedProject, peer: RecoveryPeer): "tui" | "
 
 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";
   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";
   return definitionOf(peer.id)?.session.restoreOnStart ? "restarts headless on its recorded session" : "restarts headless as a new session";
 }
 

package/src/cli/upgrade-runtime.ts

@@ -252,6 +252,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     if (source.recovery?.operationId && source.recovery.phase !== "released") blockers.push(`existing recovery operation ${source.recovery.operationId} must be resolved first`);
     const sessions: Partial<Record<TerminalBinding["peer"], string | SessionRef>> = {};
     const reconnectOnly: string[] = [];
+    const unrecordedTerminals: string[] = [];
     for (const peer of source.peers) {
       if (peer.state === "offline") continue;
       const adapter = projectDefinition(peer.id, project.root);
@@ -271,6 +272,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
         }
         const launcher = recorded?.state === "live" ? recorded.record! : undefined;
         if (!launcher) {
+          unrecordedTerminals.push(peer.id);
           delete peer.sessionId;
           if (source.protocol === PROTOCOL) reconnectOnly.push(peer.id);
           else blockers.push(`${peer.id}: unmanaged session (no live ahub claude launcher recorded) runs a protocol-${source.protocol} plugin and cannot reconnect to a protocol-${PROTOCOL} hub; next action: end that Claude session, or relaunch it with ahub claude in an Orca terminal, then make a new plan`);
@@ -300,6 +302,16 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
       ...terminalOptions(run), stateDir: project.stateDir, instanceId: source.instanceId,
     });
     blockers.push(...terminals.blockers.map((b) => `${b.message}${b.terminalReference ? ` (terminal ${b.terminalReference})` : ""}${b.nextAction ? `; next action: ${b.nextAction}` : ""}`));
+    for (const peer of source.peers) {
+      if (peer.state === "offline" || unrecordedTerminals.includes(peer.id) || terminals.bindings.some(binding => binding.peer === peer.id)) continue;
+      const unrecorded = projectDefinition(peer.id, project.root)?.session.unrecordedTerminal;
+      if (unrecorded !== "always" && !(unrecorded === "tui" && peer.args?.mode === "tui")) continue;
+      const recorded = await launcherOf(peer.id, project.root, { ...terminalOptions(run), stateDir: project.stateDir, instanceId: source.instanceId });
+      // Unknown or unreadable evidence remains unknown; exact Orca ownership above is an independent positive proof.
+      if (recorded && recorded.state !== "gone") continue;
+      unrecordedTerminals.push(peer.id);
+      blockers.push(`${peer.id}: attached, launcher unrecorded; no current live launcher or verified terminal binding; manual-required; next action: end it in its terminal, or resume the original conversation through its native resume flow in an Orca terminal, then make a new plan`);
+    }
     const freshStart: string[] = [];
     for (const binding of terminals.bindings) if (projectDefinition(binding.peer, binding.projectRoot)?.session.missingEvidence === "rollout") {
       const transcript = sessionState(binding);
@@ -309,7 +321,7 @@ 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 } : {}), ...(freshStart.length ? { freshStart } : {}) });
+    body.projects.push({ project, source, terminals: terminals.bindings, blockers, ...(reconnectOnly.length ? { reconnectOnly } : {}), ...(unrecordedTerminals.length ? { unrecordedTerminals } : {}), ...(freshStart.length ? { freshStart } : {}) });
   }
   if (!body.projects.length) body.blockers.push("no running registered projects in scope");
   return { ...body, fingerprint: planFingerprint(body) };