@staix/agent-hub 0.12.31 → 0.12.33

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { definitionOf } from "../adapters/registry.ts";
 import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board-read.ts";
 import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
@@ -43,13 +44,16 @@ import { VERSION } from "../version.ts";
 import { freeText } from "./free-text.ts";
 import { createInterface } from "node:readline/promises";
 import { createInterface as lineReader } from "node:readline";
-import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner } from "../hub/recovery-store.ts";
+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, liveProjects, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation } from "./upgrade.ts";
+import { abortRecovery, createOperation, disposeRecovery, 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 { recordTerminalLaunch } from "./terminal-recovery.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 { stopAndArchiveSummary } from "./recovery-guidance.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 import { setupOllamaModel } from "./models-setup.ts";
 
@@ -65,7 +69,7 @@ import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, label
 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, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
+import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
@@ -138,7 +142,7 @@ 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 cannot write person-attributed content; use peer tools or a person's terminal"); }
+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");
 // Forward only to ahub's own continuation commands, never to native agent argv or an environment flag.
@@ -399,21 +403,50 @@ async function hold(t: "pause" | "resume"): Promise<void> {
   console.log(`${args[0]} is ${res.state}`);
 }
 
-function spawnRecovery(operation: RecoveryOperation, quiet = false): void {
+function recoveryDisplay() {
+  return readRecoveryPresentationFlags(args, { isTTY: !!process.stdout.isTTY, columns: process.stdout.columns ?? 80, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
+}
+const humanRecovery = (json: boolean) => !json && !!process.stdin.isTTY && !!process.stdout.isTTY;
+const printRecovery = (lines: readonly string[]) => { for (const line of lines) console.log(line); };
+function recoveryFormatting(entry: string, presentation: RecoveryPresentationOptions): string[] {
+  // ponytail: old retained coordinators have no presentation parser; capability metadata can replace this display-only module-presence check.
+  return existsSync(join(dirname(entry), "upgrade-presentation-flags.ts"))
+    ? [`--color=${presentation.color ? "always" : "never"}`, ...(presentation.verbose ? ["--verbose"] : [])] : [];
+}
+function printRecoveryStatus(op: RecoveryOperation, message: string, presentation: RecoveryPresentationOptions): void {
+  printRecovery(wrap(message, presentation.columns));
+  printRecovery(wrap(`ahub recovery status ${op.id}`, presentation.columns));
+  if (presentation.verbose) {
+    printRecovery(wrap("Retained bun coordinator (main.js), wrapped command:", presentation.columns));
+    printRecovery(wrap(recoveryCommand(op, "status"), presentation.columns));
+  }
+}
+async function recoveryEndInspection(op: RecoveryOperation): Promise<Record<string, Inspection | undefined>> {
+  const driver = makeRecoveryDriver(undefined, delegatedPeer);
+  return Object.fromEntries(await Promise.all(op.plan.projects.map(async planned => [planned.project.id, await driver.inspect(planned.project).catch(() => undefined)] as const)));
+}
+
+function spawnRecovery(operation: RecoveryOperation, quiet = false, presentation?: RecoveryPresentationOptions): void {
   const child = spawn(process.execPath, [join(operation.sourceRoot, "src/cli/main.js"), ...liveTestArgs, "recovery-run", operation.id], {
     cwd, detached: true, stdio: "ignore", env: { ...process.env, AGENTHUB_RECOVERY_OPERATION: operation.id },
   });
   child.on("error", () => console.error(`runner launch failed; use ${recoveryCommand(operation, "resume")}`));
   child.unref();
   // #215: the operation's own coordinator, which has every recovery command; the global ahub may be older mid-upgrade.
-  if (!quiet) console.log(`Recovery operation ${operation.id} scheduled.\n${recoveryCommand(operation, "status")}`);
+  if (!quiet) {
+    if (presentation) {
+      printRecovery(wrap(`Recovery operation ${operation.id} scheduled.`, presentation.columns));
+      printRecovery(wrap(`ahub recovery status ${operation.id}`, presentation.columns));
+      if (presentation.verbose) printRecovery(wrap(recoveryCommand(operation, "status"), presentation.columns));
+    } else console.log(`Recovery operation ${operation.id} scheduled.\n${recoveryCommand(operation, "status")}`);
+  }
 }
 
 /** #272: a terminal session for the interactive screens. One line reader for the whole session, in the terminal's own
  *  line mode, so Ctrl+C stays a signal: from then on every question answers null and the screens leave. The terminal
  *  is not read again after it (a parent that died on the same Ctrl+C may have handed it back to the shell), and no
  *  runner is ever stopped by it. */
-async function onTerminal(screens: (io: ScreenIO) => Promise<void>): Promise<void> {
+async function onTerminal(screens: (io: ScreenIO) => Promise<void>, presentation?: RecoveryPresentationOptions): Promise<void> {
   const rl = lineReader({ input: process.stdin, terminal: false });
   const lines: string[] = [], waiters: ((line: string | null) => void)[] = [];
   let ended = false, interrupted = false;
@@ -423,6 +456,7 @@ async function onTerminal(screens: (io: ScreenIO) => Promise<void>): Promise<voi
   process.on("SIGINT", onInterrupt);
   try {
     await screens({
+      ...(presentation ? { presentation: { ...presentation, get columns() { return process.stdout.columns ?? presentation.columns; } } } : {}),
       ask: (question) => {
         if (interrupted) return Promise.resolve(null);
         process.stdout.write(question);
@@ -434,7 +468,13 @@ async function onTerminal(screens: (io: ScreenIO) => Promise<void>): Promise<voi
         // The command owns the terminal while it runs; a reader whose input already ended has nothing to pause.
         if (!ended) rl.pause();
         const done = (code: number) => { if (!ended) rl.resume(); resolve(code); };
-        const child = spawn(process.execPath, [argv[0]!, ...liveTestArgs, ...argv.slice(1)], { cwd, stdio: "inherit" });
+        const formatting = presentation && argv[1] === "recovery" ? recoveryFormatting(argv[0]!, presentation) : [];
+        // A capable screen child updates the receipt; its parent owns the human view after the action.
+        // Older coordinators keep their existing terminal contract and receive no unsupported JSON flag.
+        const quiet = formatting.length > 0;
+        const child = spawn(process.execPath, [argv[0]!, ...liveTestArgs, ...argv.slice(1), ...formatting, ...(quiet ? ["--json"] : [])], {
+          cwd, stdio: quiet ? ["inherit", "ignore", "inherit"] : "inherit",
+        });
         child.on("error", () => done(1));
         child.on("close", (code) => done(code ?? 1));
       }),
@@ -464,6 +504,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
     read: (id) => readOperation<RecoveryOperation>(id),
     runner: recoveryRunner,
     live: (op) => liveProjects(op, makeRecoveryDriver(undefined, delegatedPeer).inspect),
+    endInspection: recoveryEndInspection,
     endPeer: (planned, peer) => endPlannedPeer(planned, peer),
     runnerStoppable: (id) => signedRunner(id) !== undefined,
     stopRunner: (id) => stopSignedRunner(id),
@@ -473,12 +514,13 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
 }
 
 async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
-  const { one, rest } = takeFlags(args, ["--to"], []);
+  const display = recoveryDisplay();
+  const { one, rest } = takeFlags(display.args, ["--to"], []);
   if (rest.some((a) => !["--dry-run", "--yes"].includes(a)) || (kind === "restart" && one["--to"])) fail("usage: ahub upgrade [--to <version>] [--dry-run] [--yes] | ahub restart [--dry-run] [--yes]");
   if (kind === "upgrade" && selector) fail("upgrade changes the shared package/plugin; omit --project to review all affected running projects");
-  const dry = rest.includes("--dry-run"), yes = rest.includes("--yes");
+  const yes = rest.includes("--yes"), dry = rest.includes("--dry-run") || (display.json && !yes);
   // #272: on a terminal, with neither flag, the plan is reviewed, applied and followed in one session.
-  const interactive = !dry && !yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+  const interactive = !dry && !yes && humanRecovery(display.json);
   let to = one["--to"];
   if (kind === "upgrade" && !to) {
     if (yes || (!dry && !interactive)) fail("upgrade requires --to <exact-version>");
@@ -489,7 +531,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   if (to !== undefined) { try { exactVersion(to); } catch (error) { fail((error as Error).message); } }
   // An older CLI must not coordinate a newer target (docs/operations.md): the target's own coordinator takes over.
   if (kind === "upgrade" && newerVersion(to!, VERSION) && process.env.AGENTHUB_UPGRADE_HANDOVER !== "1") {
-    const argv = ["x", "--package", `@staix/agent-hub@${to}`, "ahub", ...liveTestArgs, "upgrade", "--to", to!, ...rest];
+    const argv = ["x", "--package", `@staix/agent-hub@${to}`, "ahub", ...liveTestArgs, "upgrade", "--to", to!, ...rest, ...display.flags, ...(dry && !rest.includes("--dry-run") ? ["--dry-run"] : [])];
     console.error(`ahub: ${to} is newer than this CLI (${VERSION}), so its own coordinator runs the upgrade: bun ${argv.join(" ")}`);
     if (interactive) {
       const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -506,16 +548,17 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
     process.exit(code);
   }
   if (kind === "upgrade") console.error("ahub: Kimi now defaults to its own TUI (pull-only) in projects without peers.kimi.start_mode. To keep ACP: ahub settings set peers.kimi.start_mode headless");
-  if (interactive) return onTerminal((io) => planScreen(upgradeHost(kind, to ?? VERSION), io));
+  if (interactive) return onTerminal((io) => planScreen(upgradeHost(kind, to ?? VERSION), io), display.options);
   const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined);
-  console.log(JSON.stringify(plan, null, 2));
+  const jsonApply = display.json && yes && !dry;
+  if (!jsonApply) console.log(JSON.stringify(plan, null, 2));
   // #206: name every blocker and reconnect-only session on stderr, not only inside the JSON above.
   for (const p of plan.projects) for (const peer of p.reconnectOnly ?? []) console.error(`ahub: ${p.project.id}: ${peer} is reconnect-only (unmanaged session): its plugin reattaches to the new hub; no terminal is closed or relaunched`);
   for (const p of plan.projects) for (const peer of p.freshStart ?? []) console.error(`ahub: ${p.project.id}: ${peer} restarts as a new session: its thread has no rollout and the hub recorded no turn on it, so nothing is lost`);
   const blockers = [...plan.blockers, ...plan.projects.flatMap((p) => p.blockers.map((b) => `${p.project.id}: ${b}`))];
   for (const blocker of blockers) console.error(`ahub: blocker: ${blocker}`);
   if (dry) return;
-  if (blockers.length) fail("plan has blockers; no runtime was changed");
+  if (blockers.length) { if (jsonApply) console.log(JSON.stringify(plan, null, 2)); fail("plan has blockers; no runtime was changed"); }
   assertLifecycleAvailable();
   if (!yes) {
     if (!process.stdin.isTTY) fail("review --dry-run and use --yes in non-interactive sessions");
@@ -528,50 +571,128 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   if (current.fingerprint !== plan.fingerprint) fail("plan changed during review; run the command again");
   const sourceRoot = preserveSource(plan);
   const operation = createOperation(plan, sourceRoot);
-  spawnRecovery(operation);
+  if (display.json) { spawnRecovery(operation, true); console.log(JSON.stringify(publicOperation(operation), null, 2)); }
+  else spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
+}
+
+/** Strict person command: recorded identity only, no session or terminal overrides. */
+function parseRecoveryReattach(argv: readonly string[]): { id: string; peer: TerminalPeer } | undefined {
+  if (argv.length !== 3 || argv[0] !== "reattach" || !operationIdPattern.test(argv[1]!) || !["codex", "claude", "pi"].includes(argv[2]!)) return undefined;
+  return { id: argv[1]!, peer: argv[2] as TerminalPeer };
 }
 
 const commands: Record<string, () => Promise<void> | void> = {
   upgrade: () => upgrade("upgrade"),
   restart: () => upgrade("restart"),
   recovery: async () => {
-    const [action, given, ...more] = args;
+    const display = recoveryDisplay();
+    const [action, given, ...more] = display.args;
     const usage = "usage: ahub recovery [status|resume|abort] [<operation-id>] | ahub recovery dispose [<operation-id>] --fresh-session <peer>|--stop-and-archive --reason <text>";
+    if (action === "reattach") {
+      const selected = parseRecoveryReattach(display.args);
+      if (!selected) fail("usage: ahub recovery reattach <operation-id> codex|claude|pi");
+      let operation: RecoveryOperation;
+      try { operation = readOperation<RecoveryOperation>(selected.id); }
+      catch { fail(`recovery receipt ${selected.id} cannot be read; inspect the retained operation with ahub recovery status ${selected.id}; no session was started`); }
+      if (typeof operation.sourceRoot !== "string" || !operation.sourceRoot.trim()) fail(`recovery receipt ${selected.id} has no retained coordinator path; inspect it with ahub recovery status ${selected.id}; no session was started`);
+      const coordinator = join(operation.sourceRoot, "src/cli/main.js");
+      if (!existsSync(coordinator)) fail(`the retained coordinator for ${selected.id} is unavailable; restore its retained package and inspect ahub recovery status ${selected.id} before retrying; no session was started`);
+      let coordinatorIsCurrent: boolean;
+      try { coordinatorIsCurrent = realPath(coordinator) === realPath(join(import.meta.dir, "main.js")); }
+      catch { fail(`the retained coordinator for ${selected.id} cannot be resolved; inspect ahub recovery status ${selected.id} before retrying; no session was started`); }
+      if (supportsAction(operation.sourceRoot, "reattach") && !coordinatorIsCurrent) {
+        if (humanRecovery(display.json)) {
+          for (const line of wrap("ahub: using the operation's retained coordinator for reattachment", display.options.columns)) console.error(line);
+          if (display.options.verbose) for (const line of wrap(recoveryCommand(operation, "reattach", selected.peer), display.options.columns)) console.error(line);
+        } else console.error(`ahub: using the operation's coordinator: ${recoveryCommand(operation, "reattach", selected.peer)}`);
+        const formatting = recoveryFormatting(coordinator, display.options);
+        const code = await new Promise<number>(resolve => {
+          const child = spawn(process.execPath, [coordinator, "recovery", "reattach", selected.id, selected.peer, ...formatting], { cwd, stdio: display.json ? ["inherit", "ignore", "inherit"] : "inherit", env: process.env });
+          child.on("error", () => { console.error(`ahub: coordinator could not start; ${recoveryCommand(operation, "status")}`); resolve(1); });
+          child.on("close", status => resolve(status ?? 1));
+        });
+        process.exitCode = code;
+        if (display.json && code === 0) console.log(JSON.stringify(publicOperation(readOperation<RecoveryOperation>(selected.id)), null, 2));
+        return;
+      }
+      const result = await reattachRecovery(selected.id, selected.peer, makeRecoveryDriver());
+      if (humanRecovery(display.json)) {
+        printRecovery(renderOperation(result, undefined, display.options));
+        const live = await liveProjects(result, makeRecoveryDriver(undefined, delegatedPeer).inspect);
+        printRecovery(renderBlocked(result, nextChoices(result, undefined, live), display.options));
+      } else {
+        console.log(JSON.stringify(publicOperation(result), null, 2));
+        if (!display.json) console.log(nextActionsText(result));
+      }
+      return;
+    }
     // #272: without an id, the operation that holds the machine's lock; bare on a terminal, its screen.
     const named = !!given && operationIdPattern.test(given);
     const id = named ? given : recoveryLock();
     const rest = named || given === undefined ? more : [given, ...more];
-    if (action === undefined && process.stdin.isTTY && process.stdout.isTTY) {
+    if (action === undefined && humanRecovery(display.json)) {
       if (!id) return console.log("no recovery operation is open");
-      return onTerminal(async (io) => { await operationScreen(upgradeHost("restart", VERSION), io, id); });
+      return onTerminal(async (io) => { await operationScreen(upgradeHost("restart", VERSION), io, id); }, display.options);
     }
     if (!["status", "resume", "abort", "dispose"].includes(action ?? "") || (action !== "dispose" && rest.length)) fail(usage);
     if (!id) fail("no recovery operation holds the lock; name one by its id");
-    const operation = readOperation<RecoveryOperation>(id);
+    const delegatedFresh = delegatedPeer && action === "dispose" ? takeFlags(rest, ["--fresh-session", "--reason"], []).one["--fresh-session"] : undefined;
+    let operation: RecoveryOperation;
+    try { operation = readOperation<RecoveryOperation>(id); }
+    catch (error) {
+      if (delegatedFresh !== undefined) { audit("refused"); fail(LIVE_TEST_PERSON_REFUSAL); }
+      throw error;
+    }
+    if (delegatedFresh !== undefined) {
+      const repairedFresh = repairedFreshSession(operation, delegatedFresh);
+      if (repairedFresh === undefined || liveTestRefusal("recovery", display.args, { repairedFresh })) {
+        audit("refused"); fail(LIVE_TEST_PERSON_REFUSAL);
+      }
+    }
     const runner = recoveryRunner(id);
     if (action === "status") {
       // #215: abort and resume are offered by what the open sources show, read as the runner's errors read them.
       const live = runner ? {} : await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer).inspect);
       console.log(JSON.stringify(publicOperation(operation, runner, live), null, 2));
     }
-    else if (action === "abort") { await abortRecovery(id, makeRecoveryDriver(undefined, delegatedPeer)); console.log("preflight cancelled; no committed transition was rolled back"); }
+    else if (action === "abort") {
+      await abortRecovery(id, makeRecoveryDriver(undefined, delegatedPeer));
+      if (display.json) console.log(JSON.stringify(publicOperation(readOperation<RecoveryOperation>(id)), null, 2));
+      else console.log("preflight cancelled; no committed transition was rolled back");
+    }
     else if (action === "dispose") {
-      // Console authority (including explicit --live-test delegation); the reason is kept in the operation's audit.
+      // Console authority; #408 live-test delegation remains for ordinary fresh choices, never repaired loss.
       const { one, rest: flags } = takeFlags(rest, ["--fresh-session", "--reason"], []);
       const stop = flags.length === 1 && flags[0] === "--stop-and-archive";
       const reason = one["--reason"]?.trim() ?? "";
       if (!reason || reason.length > 500 || (flags.length && !stop) || stop === !!one["--fresh-session"]) fail(usage);
       const result = await disposeRecovery(id, stop ? { stop: true } : { fresh: one["--fresh-session"]! }, reason, makeRecoveryDriver(undefined, delegatedPeer));
-      if (!stop) { console.log(`${one["--fresh-session"]}: a fresh session is accepted and the lost one is recorded; resuming`); return spawnRecovery(result); }
-      console.log(JSON.stringify(publicOperation(result), null, 2));
-      console.log(`${result.plan.kind} abandoned, not completed; the recovery lock is released. A project whose target ran starts again with that version's CLI.`);
+      if (!stop) {
+        if (display.json) { console.log(JSON.stringify(publicOperation(result), null, 2)); return spawnRecovery(result, true); }
+        console.log(`${one["--fresh-session"]}: a fresh session is accepted and the lost one is recorded; resuming`);
+        return spawnRecovery(result, false, humanRecovery(false) ? display.options : undefined);
+      }
+      if (humanRecovery(display.json)) printRecovery(renderSummary(result, await recoveryEndInspection(result), display.options));
+      else {
+        console.log(JSON.stringify(publicOperation(result), null, 2));
+        if (!display.json) for (const line of stopAndArchiveSummary(result)) console.log(line);
+      }
     }
-    else if (["completed", "cancelled"].includes(operation.phase)) console.log(`recovery is already ${operation.phase}`);
+    else if (["completed", "cancelled"].includes(operation.phase)) console.log(display.json ? JSON.stringify(publicOperation(operation, runner), null, 2) : `recovery is already ${operation.phase}`);
     // #215: an operation being abandoned is never resumed, whichever coordinator started it (an older one would).
     else if (operation.disposition) fail(`a stop-and-archive of this operation is partway; nothing was resumed; ${nextActionsText(operation, await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer).inspect))}`);
-    else if (runner === "unknown") console.log(`whether a runner holds this operation could not be read; nothing was started; ${recoveryCommand(operation, "status")}`);
-    else if (runner) console.log(`runner ${runner} is still working on this operation; ${recoveryCommand(operation, "status")}`);
-    else spawnRecovery(operation);
+    else if (runner === "unknown") {
+      if (display.json) console.log(JSON.stringify(publicOperation(operation, runner), null, 2));
+      else if (humanRecovery(false)) printRecoveryStatus(operation, "Runner ownership is unknown; nothing was started.", display.options);
+      else console.log(`whether a runner holds this operation could not be read; nothing was started; ${recoveryCommand(operation, "status")}`);
+    }
+    else if (runner) {
+      if (display.json) console.log(JSON.stringify(publicOperation(operation, runner), null, 2));
+      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);
   },
   "recovery-run": async () => {
     if (args.length !== 1 || process.env.AGENTHUB_RECOVERY_OPERATION !== args[0]) fail("recovery-run is an internal command");
@@ -804,8 +925,9 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     assertLifecycleAvailable();
     const { one, rest } = takeFlags(args, ["--mode", "--model", "--session-id"], []);
-    if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Qwen session identity");
-    if (rest.length || (one["--mode"] !== undefined && one["--mode"] !== "headless")) fail("Qwen TUI is not offered before verification; usage: ahub qwen [--mode headless] [--model <alias>] [--session-id <id>]");
+    const adapter = definitionOf("qwen")!;
+    if (one["--session-id"] !== undefined && !adapter.session.crashIdentity?.({ sessionId: one["--session-id"] }).sessionId) fail("invalid Qwen session identity");
+    if (rest.length || (one["--mode"] !== undefined && !(adapter.start.forms as readonly string[]).includes(one["--mode"]))) fail("Qwen TUI is not offered before verification; usage: ahub qwen [--mode headless] [--model <alias>] [--session-id <id>]");
     const hub = await connect();
     try {
       const reply = await hub.request({ t: "start", peer: "qwen", args: { mode: "headless", ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
@@ -1003,7 +1125,7 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   watch: async () => {
     const peer = args[0];
-    if (peer !== "kimi" && peer !== "qwen") fail("usage: ahub watch kimi|qwen [--no-thoughts] [--color=auto|always|never]");
+    if (typeof peer !== "string" || !definitionOf(peer)?.capabilities?.watch) fail("usage: ahub watch kimi|qwen [--no-thoughts] [--color=auto|always|never]");
     if (args.slice(1).some(arg => arg !== "--no-thoughts" && !/^--color=(auto|always|never)$/.test(arg))) fail("unsupported watch option");
     const color = resolveColor(args.find(arg => arg.startsWith("--color="))?.slice(8), { isTTY: !!process.stdout.isTTY, ...process.env });
     if (color instanceof Error) fail(color.message);
@@ -1331,11 +1453,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
   settings: async () => {
-    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo";
+    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo | reload";
     const flags = args.filter((arg) => arg.startsWith("--")), [sub = "list", key, text, ...extra] = args.filter((arg) => !arg.startsWith("--"));
-    const allowed: Record<string, string[]> = { list: ["--json"], get: ["--json"], set: ["--yes", "--preview", "--now"], undo: [] };
+    const allowed: Record<string, string[]> = { list: ["--json"], get: ["--json"], set: ["--yes", "--preview", "--now"], undo: [], reload: [] };
     if (!Object.hasOwn(allowed, sub) || flags.some((flag) => !allowed[sub]!.includes(flag)) || extra.length) fail(usage);
-    if ((sub === "get" && (!key || text !== undefined)) || (sub === "set" && (!key || text === undefined)) || ((sub === "list" || sub === "undo") && key !== undefined)) fail(usage);
+    if ((sub === "get" && (!key || text !== undefined)) || (sub === "set" && (!key || text === undefined)) || ((sub === "list" || sub === "undo" || sub === "reload") && key !== undefined)) fail(usage);
     const def = key === undefined ? undefined : settingDef(key);
     if (typeof def === "string") fail(`${key}: ${def}`);
     if (flags.includes("--now") && (typeof def !== "object" || def.group !== "Roster")) fail(usage);
@@ -1355,6 +1477,43 @@ const commands: Record<string, () => Promise<void> | void> = {
         }
         return reply;
       };
+      if (sub === "reload") {
+        let result = await request({ t: "settings_reload" });
+        const confirmation = result.confirmation;
+        if (Array.isArray(result.rejected)) for (const row of result.rejected.slice(0, 100)) console.log(terminalText(`${String(row.key).slice(0, 160)}: ${String(row.reason).slice(0, 1000)}`));
+        if (confirmation !== undefined) {
+          if (!confirmation || typeof confirmation.token !== "string" || !confirmation.token || confirmation.token.length > 256 || !Array.isArray(confirmation.keys) || !confirmation.keys.length || confirmation.keys.length > 200 || confirmation.keys.some((key: unknown) => typeof key !== "string" || key.length > 160)) fail("invalid reload confirmation; guarded settings were not applied");
+          const fullValue = (value: unknown): boolean => {
+            if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > 16_384) return false;
+            if (value === "(unset)") return true;
+            try { JSON.parse(value); return true; } catch { return false; }
+          };
+          if (Buffer.byteLength(JSON.stringify(result), "utf8") > 131_072 || new Set(confirmation.keys).size !== confirmation.keys.length || !Array.isArray(confirmation.changes) || confirmation.changes.length !== confirmation.keys.length || confirmation.changes.some((change: unknown, index: number) => {
+            if (!change || typeof change !== "object" || Array.isArray(change)) return true;
+            const row = change as Record<string, unknown>;
+            return row.key !== confirmation.keys[index] || !fullValue(row.before) || !fullValue(row.after) || (row.effect !== undefined && (typeof row.effect !== "string" || Buffer.byteLength(row.effect, "utf8") > 2048));
+          })) fail("reload preview is incomplete or unavailable; upgrade the running hub and run ahub settings reload again to review every full value; guarded settings were not applied");
+          const token = confirmation.token;
+          console.log("Guarded settings awaiting confirmation:");
+          for (const change of confirmation.changes) {
+            console.log(`  ${terminalText(change.key)}: ${terminalText(change.before)} -> ${terminalText(change.after)}`);
+            if (change.effect !== undefined) console.log(`    ${terminalText(change.effect)}`);
+          }
+          if (!process.stdin.isTTY || !process.stdout.isTTY) fail("guarded settings need an interactive person's terminal; run ahub settings reload there; guarded settings were not applied");
+          const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+          const ended = new AbortController();
+          rl.once("close", () => ended.abort());
+          let accepted = false;
+          try { accepted = (await rl.question("Apply guarded settings? [y/N] ", { signal: AbortSignal.any([AbortSignal.timeout(30_000), ended.signal]) })).trim().toLowerCase() === "y"; }
+          catch { /* EOF, cancellation and a missed confirmation deadline grant nothing. */ }
+          finally { rl.close(); }
+          if (!accepted) return console.log("guarded settings were not applied");
+          result = await request({ t: "settings_reload", confirm: token });
+          if (result.confirmation !== undefined) fail("reload candidate changed; run ahub settings reload again to review it; guarded settings were not applied");
+          if (Array.isArray(result.rejected)) for (const row of result.rejected.slice(0, 100)) console.log(terminalText(`${String(row.key).slice(0, 160)}: ${String(row.reason).slice(0, 1000)}`));
+        }
+        return console.log(paint([{ text: result.text }], false));
+      }
       if (sub === "undo") {
         const view = await request({ t: "settings_get" }), undoDef = settingDef(view.undo);
         const rosterPeer = typeof undoDef !== "string" && undoDef.group === "Roster" ? undoDef.path[1] : undefined;
@@ -1382,15 +1541,16 @@ const commands: Record<string, () => Promise<void> | void> = {
       }
       const view = await request({ t: "settings_get" });
       const rows = (view.rows as SettingRow[]).filter((row) => sub === "list" || row.key === key);
-      if (flags.includes("--json")) return console.log(JSON.stringify(sub === "get" ? rows[0] : { rows, ...(view.undo ? { undo: view.undo } : {}) }, null, 2));
+      if (flags.includes("--json")) return console.log(JSON.stringify(sub === "get" ? rows[0] : { rows, pendingRestart: view.pendingRestart ?? [], ...(view.undo ? { undo: view.undo } : {}) }, null, 2));
       const width = Math.max(...rows.map((row) => row.key.length)), valueWidth = Math.max(...rows.map((row) => settingText(row.value).length));
       let group = "";
       for (const row of rows) {
         if (sub === "list" && row.group !== group) console.log(`${group ? "\n" : ""}${group = row.group}`);
-        const facts = [`from ${row.source}`, row.applies === "live" ? "applies at once" : row.applies === "peer start" ? "applies at the peer's next start" : "read at hub start", ...(row.pending !== undefined ? [`${settingText(row.pending)} at the next ${row.applies === "peer start" ? "peer" : "hub"} start`] : []), ...(row.note ? [row.note] : [])];
+        const facts = [`from ${row.source}`, `file: ${settingText(row.fileValue === undefined ? row.pending ?? row.value : row.fileValue)}`, row.applies === "live" ? "applies at once" : row.applies === "next use" ? "applies at next use" : "pending restart", ...(row.restartReason ? [row.restartReason] : []), ...(row.note ? [row.note] : [])];
         console.log(`  ${row.key.padEnd(width)}  ${settingText(row.value).padEnd(valueWidth)}  ${facts.join("; ")}`);
-        if (sub === "get") console.log(`  ${row.label}; written to ${row.file}; takes ${row.type === "boolean" ? "true, false" : row.type === "peers" ? "a comma list of peer ids" : row.type === "roles" ? "up to two comma-separated catalog ids" : (row.values ?? []).join(", ")}${row.file === "this hub run" ? "" : ", or inherit to remove the machine-local value"}${row.risk === "raises" ? "; a dashboard needs a settings session (ahub ui --settings) to raise it" : ""}`);
+        if (sub === "get") console.log(`  ${row.label}; written to ${row.file}; takes ${row.type === "boolean" ? "true, false" : row.type === "integer" || row.type === "number" ? `a number from ${row.min ?? 0} to ${row.max ?? "the configured bound"}` : row.type === "peers" ? "a comma list of peer ids" : row.type === "roles" ? "up to two comma-separated catalog ids" : (row.values ?? []).join(", ")}${row.file === "this hub run" ? "" : ", or inherit to remove the machine-local value"}${row.risk === "raises" ? "; a dashboard needs a settings session (ahub ui --settings) to raise it" : ""}`);
       }
+      if (sub === "list" && view.pendingRestart?.length) console.log(`\npending restart: ${view.pendingRestart.map((entry: { key: string }) => entry.key).join(", ")}`);
       if (sub === "list" && view.undo) console.log(`\nahub settings undo puts back the last write (${view.undo})`);
     } finally { hub.close(); }
   },
@@ -1842,6 +2002,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         row(verifiedJcodeCommand(config.jcode_cmd, cwd), "jcode", "CLI/source identity only; provider, project MCP and native teardown require separate receipts; native policy unmanaged");
       }
       if (config.roster.qwen === true) {
+        // ponytail: keep this bounded CLI-version probe and 0.25.0 pin in the A1 guard baseline; A2 moves every version probe together when VersionContext gains its observed input.
         const v = version(config.qwen_cmd[0]!);
         row(v === "0.25.0", "qwen", v === "0.25.0" ? "CLI reports 0.25.0; native ACP identity/modes and provider access require a separate live check" : "Qwen Code 0.25.0 executable not confirmed; provider and ACP readiness unknown");
       } // issue #83

package/src/cli/output.ts

@@ -7,6 +7,7 @@ import { formatReport, formatTaskReport, type Report, type TaskReport } from "..
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  pendingRestart?: readonly { key: string; reason: 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 };
@@ -188,6 +189,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   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"));
   for (const stall of data.taskStalls ?? []) out.push(...detail(`task #${stall.task} stalled`, `${stall.cause.kind}${stall.cause.peer ? ` ${stall.cause.peer}` : ""}${stall.cause.dependency ? ` #${stall.cause.dependency}` : ""}: ${stall.cause.code}; configure the peer, ahub task assign ${stall.task} <peer>, or ahub task cancel ${stall.task} --reason <text>`, columns, "attention"));
   for (const offer of data.pendingTaskOffers ?? []) out.push(...detail("task offer", `open ${offer.peer}: task #${offer.task} is waiting for it`, columns, "attention"));
   if (data.memoryProfile) {

package/src/cli/preview.ts

@@ -1,3 +1,4 @@
+import { definitionOf, kindOf } from "../adapters/registry.ts";
 import { jcodeCommand } from "../adapters/jcode.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { readFileSync } from "node:fs";
@@ -7,7 +8,7 @@ import { childEnv } from "../hub/child-process.ts";
 import { relayModelIds } from "../models/relay.ts";
 import { buildPiLaunch } from "../pi/launch.ts";
 import { startModeOf } from "../hub/start-mode.ts";
-import { buildLaunch, buildKimiLaunch, buildQwenLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks, type Launch } from "./launch.ts";
+import { buildLaunch, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks, type Launch } from "./launch.ts";
 import { kimiMcpPlan } from "./kimi-mcp.ts";
 
 const REDACTED = "[redacted]";
@@ -71,14 +72,16 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
     launch = { cmd: cmd[0]!, args: cmd.slice(1) };
     unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
     unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });
-  } else if (tool === "qwen") {
+  } else if (kindOf(tool) === "qwen") {
     const mode = value("--mode") ?? "headless", model = value("--model");
-    if (mode !== "headless") throw new Error("Qwen TUI is not offered before verification");
+    const adapter = definitionOf(tool)!;
+    if (!(adapter.start.forms as readonly string[]).includes(mode)) throw new Error("Qwen TUI is not offered before verification");
     for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Qwen option");
     const sessionId = value("--session-id");
-    if (sessionId !== undefined && !qwenSessionId(sessionId)) throw new Error("invalid Qwen session identity");
+    if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
     if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
-    launch = buildQwenLaunch(nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model ? REDACTED : undefined);
+    launch = adapter.start.launch({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(import.meta.dir, "main.js"),
+      userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
     unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
   } else if (tool === "kimi") {
     const model = value("--model");