@staix/agent-hub 0.12.21 → 0.12.23

package/src/cli/main.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env bun
 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 { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -18,33 +20,36 @@ import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, claudeObservationHooks, nativeLaunchEnv, UNATTENDED_WARNING } from "./launch.ts";
+import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
 import { freeText } from "./free-text.ts";
 import { createInterface } from "node:readline/promises";
-import { activeOperation, assertLifecycleAvailable, readOperation, recoveryLock, recoveryRunner } from "../hub/recovery-store.ts";
+import { createInterface as lineReader } from "node:readline";
+import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner } 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 { makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.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 { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 import { setupOllamaModel } from "./models-setup.ts";
 
-import { unknownContext } from "../hub/context-window.ts";
-import { backendLine, contextLine, peerLine, type BackendRow, type PeerRow } from "./status-lines.ts";
+import { contextLine, type PeerRow } from "./status-lines.ts";
 import { parseSince, readEvents } from "../hub/events.ts";
 import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatReport as formatBenchReport, formatRuns, readRuns, runSummary, sameSuite } from "../hub/bench.ts";
 import { benchPreflight, defaultIo, runBench } from "./bench.ts";
 import { appendRecords, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
-import { formatReport, summarize, formatTaskReport, summarizeByTask } from "../hub/report.ts";
+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, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
-import { permissionBoundary, resolveColor } from "./console-state.ts";
+import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
+import { outputWidth, renderStatus, renderBoard, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, type DoctorCheck } from "./output.ts";
 import { renderHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
@@ -104,6 +109,22 @@ if (identity.role === "tools" && commandAccess === "console") { audit("refused")
 if (identity.role === "tools") audit("run");
 const invokedFrom = process.cwd(); // relative paths a person types (a bench suite) are theirs, not the project's
 try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
+/** One-shot output flags do not alter the fetched JSON document. */
+function outputOptions() {
+  const flags = args.filter(arg => arg.startsWith("--color="));
+  if (flags.length > 1 || args.includes("--color")) fail(`usage: ahub ${cmd} [--color=auto|always|never] [--json] [--full]`);
+  const color = resolveColor(flags[0]?.slice("--color=".length), { isTTY: !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
+  if (color instanceof Error) fail(`usage: ahub ${cmd} [--color=auto|always|never] [--json] [--full]`);
+  return { color: color === true, json: args.includes("--json"), full: args.includes("--full"),
+    columns: outputWidth({ isTTY: !!process.stdout.isTTY, columns: process.stdout.columns, COLUMNS: process.env.COLUMNS }) };
+}
+/** Remove only presentation flags from read-only command positional arguments. */
+function outputArguments(): string[] {
+  return args.filter(arg => arg !== "--json" && arg !== "--full" && !arg.startsWith("--color="));
+}
+function printOutput(lines: Span[][], color: boolean): void {
+  for (const line of lines) console.log(paint(line, color));
+}
 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 });
@@ -171,12 +192,18 @@ function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): nev
   process.exit(res.status ?? 1);
 }
 
-function piFlags(): { mode: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; model?: string; sessionId?: string; sessionFile?: string } {
+/** `mode` is absent when no flag chose one: the caller takes the configured start mode (#269). `--headless` is `--mode headless`. */
+function piFlags(): { mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; model?: string; sessionId?: string; sessionFile?: string } {
+  const usage = "usage: ahub pi [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id> | --session-file <path>]";
+  if (args.includes("--headless")) {
+    if (args.includes("--mode")) fail(usage);
+    args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
+  }
   for (const flag of ["--mode", "--backend", "--model", "--session-id", "--session-file"]) {
     const index = args.indexOf(flag);
     if (index >= 0 && (!args[index + 1] || args[index + 1]!.startsWith("--"))) fail(`${flag} needs a value`);
   }
-  const mode = (args.includes("--mode") ? args[args.indexOf("--mode") + 1] : "headless") as string;
+  const mode = (args.includes("--mode") ? args[args.indexOf("--mode") + 1] : undefined) as string | undefined;
   const backend = (args.includes("--backend") ? args[args.indexOf("--backend") + 1] : undefined) as string | undefined;
   const model = args.includes("--model") ? args[args.indexOf("--model") + 1] : undefined;
   const sessionId = args.includes("--session-id") ? args[args.indexOf("--session-id") + 1] : undefined;
@@ -186,8 +213,8 @@ function piFlags(): { mode: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"
     if (!valueFlags.has(args[i]!)) fail(`unknown Pi option: ${args[i]}`);
     i++;
   }
-  if (!["headless", "tui"].includes(mode) || (backend !== undefined && !["auto", "dgx", "mlx"].includes(backend)) || (sessionId && sessionFile)) fail("usage: ahub pi [--mode headless|tui] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id> | --session-file <path>]");
-  return { mode: mode as "headless" | "tui", ...(backend ? { backend: backend as "auto" | "dgx" | "mlx" } : {}), ...(model ? { model } : {}), ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}) };
+  if ((mode !== undefined && !["headless", "tui"].includes(mode)) || (backend !== undefined && !["auto", "dgx", "mlx"].includes(backend)) || (sessionId && sessionFile)) fail(usage);
+  return { ...(mode ? { mode: mode as "headless" | "tui" } : {}), ...(backend ? { backend: backend as "auto" | "dgx" | "mlx" } : {}), ...(model ? { model } : {}), ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}) };
 }
 
 async function projectRows() {
@@ -196,15 +223,10 @@ async function projectRows() {
   finally { registry.close(); }
 }
 
-async function printProjects(json = false) {
-  const rows = await projectRows();
-  if (json) return console.log(JSON.stringify(rows, null, 2));
-  for (const row of rows) {
-    console.log(`${row.id}  ${row.state.padEnd(12)} ${row.root}`);
-    if (row.status) console.log(`  peers ${Object.keys(row.status.peers ?? {}).length}, control ${row.status.controlPort}, tasks ${JSON.stringify(row.status.tasks ?? {})}`);
-    if (row.error) console.log(`  ${row.error}`);
-  }
-  if (!rows.length) console.log("No registered projects. Run ahub init in a project directory.");
+async function printProjects(options: ReturnType<typeof outputOptions>) {
+  const projects = await projectRows();
+  if (options.json) return console.log(JSON.stringify(projects, null, 2));
+  printOutput(renderProjects(projects, options.columns, Date.now()), options.color);
 }
 
 /** Full command line of a live process, undefined once it is gone. */
@@ -247,43 +269,40 @@ function orphanPids(project: Project): number[] {
 
 const processGone = (pid: number): boolean => !processCommandLine(pid);
 
-async function killOrphan(pid: number, root: string): Promise<boolean> {
+async function killOrphan(pid: number, root: string, diagnostic: (text: string) => void = text => console.log(text)): Promise<boolean> {
   if (!hubDaemonCommand(pid, root)) {
-    console.log(`    pid ${pid}: command line is not this project's hub daemon; refusing to kill`);
+    diagnostic(`    pid ${pid}: command line is not this project's hub daemon; refusing to kill`);
     return false;
   }
   try { process.kill(pid, "SIGTERM"); } catch { return true; } // exited meanwhile
   const graceful = Date.now() + 3_000;
   while (Date.now() < graceful && !processGone(pid)) await Bun.sleep(100);
-  if (processGone(pid)) { console.log(`    pid ${pid}: stopped with SIGTERM`); return true; }
+  if (processGone(pid)) { diagnostic(`    pid ${pid}: stopped with SIGTERM`); return true; }
   // The PID may have been reused since SIGTERM; verify identity again before escalating.
   if (!hubDaemonCommand(pid, root)) {
-    console.log(`    pid ${pid}: identity changed after SIGTERM; refusing SIGKILL`);
+    diagnostic(`    pid ${pid}: identity changed after SIGTERM; refusing SIGKILL`);
     return false;
   }
   try { process.kill(pid, "SIGKILL"); } catch { return true; }
   const hard = Date.now() + 2_000;
   while (Date.now() < hard && !processGone(pid)) await Bun.sleep(100);
   if (!processGone(pid)) {
-    console.log(`    pid ${pid}: still alive after SIGKILL`);
+    diagnostic(`    pid ${pid}: still alive after SIGKILL`);
     return false;
   }
-  console.log(`    pid ${pid}: killed with SIGKILL`);
+  diagnostic(`    pid ${pid}: killed with SIGKILL`);
   return true;
 }
 
-async function orphanDoctor(kill: boolean): Promise<void> {
-  const orphans = registeredProjects().filter((project) => !existsSync(project.root));
-  if (!orphans.length) return console.log("no orphaned hub registrations");
-  console.log("orphaned hub registrations (the project root is gone):");
+async function orphanDoctor(kill: boolean, options: ReturnType<typeof outputOptions>): Promise<void> {
+  const orphans = registeredProjects().filter(project => !existsSync(project.root)).map(project => ({ project, pids: orphanPids(project) }));
+  if (options.json) console.log(JSON.stringify(orphans, null, 2));
+  else printOutput(renderOrphans(orphans, options.columns, Date.now(), kill), options.color);
   let failed = 0;
-  for (const project of orphans) {
-    const pids = orphanPids(project);
-    console.log(`  ${project.id}  ${project.root}${pids.length ? `  live pid ${pids.join(", ")}` : "  no live process"}`);
-    if (!kill) continue;
-    for (const pid of pids) if (!(await killOrphan(pid, project.root))) failed++;
-  }
-  if (!kill) console.log("kill live orphans with `ahub doctor --orphans --kill`, then forget each row with `ahub projects remove <id>`");
+  const diagnostic = (text: string) => options.json
+    ? console.error(paint([{ text }], false))
+    : printOutput(wrap(text, options.columns ?? Infinity).map(text => [{ text }]), options.color);
+  if (kill) for (const { project, pids } of orphans) for (const pid of pids) if (!(await killOrphan(pid, project.root, diagnostic))) failed++;
   if (failed) fail(`${failed} orphaned hub process(es) could not be stopped`);
 }
 
@@ -292,12 +311,13 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-async function taskOp(op: string, a: Record<string, unknown>): Promise<string> {
+async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false): Promise<string> {
   const hub = await connect();
-  const res = await hub.request({ t: "task", op, args: a });
-  hub.close();
-  if (!res.ok) { audit("refused"); fail(res.error); }
-  return res.text;
+  try {
+    const res = await hub.request({ t: "task", op, args: a });
+    if (!res.ok) { if (throwOnError) throw new Error(res.error); audit("refused"); fail(res.error); }
+    return res.text;
+  } finally { hub.close(); }
 }
 
 /** Reads hub.db's turn records; `none` when the hub never kept one (snapshots off, no git work tree, an older hub). */
@@ -339,32 +359,124 @@ async function hold(t: "pause" | "resume"): Promise<void> {
   console.log(`${args[0]} is ${res.state}`);
 }
 
-function spawnRecovery(operation: RecoveryOperation): void {
+function spawnRecovery(operation: RecoveryOperation, quiet = false): void {
   const child = spawn(process.execPath, [join(operation.sourceRoot, "src/cli/main.js"), "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.
-  console.log(`Recovery operation ${operation.id} scheduled.\n${recoveryCommand(operation, "status")}`);
+  if (!quiet) 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> {
+  const rl = lineReader({ input: process.stdin, terminal: false });
+  const lines: string[] = [], waiters: ((line: string | null) => void)[] = [];
+  let ended = false, interrupted = false;
+  rl.on("line", (line) => { const next = waiters.shift(); if (next) next(line.trim()); else lines.push(line.trim()); });
+  rl.on("close", () => { ended = true; for (const waiter of waiters.splice(0)) waiter(null); });
+  const onInterrupt = () => { interrupted = true; for (const waiter of waiters.splice(0)) waiter(null); };
+  process.on("SIGINT", onInterrupt);
+  try {
+    await screens({
+      ask: (question) => {
+        if (interrupted) return Promise.resolve(null);
+        process.stdout.write(question);
+        const typed = lines.shift();
+        return typed !== undefined ? Promise.resolve(typed) : ended ? Promise.resolve(null) : new Promise((resolve) => waiters.push(resolve));
+      },
+      out: (line) => console.log(line),
+      run: (argv) => new Promise((resolve) => {
+        // 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, { cwd, stdio: "inherit" });
+        child.on("error", () => done(1));
+        child.on("close", (code) => done(code ?? 1));
+      }),
+      sleep: (ms) => Bun.sleep(ms),
+      interrupted: () => interrupted,
+      // Scripted input (a pipe) is answers typed ahead for the next question; only a terminal's line is a key press.
+      typed: () => !ended && lines.splice(0).length > 0,
+    });
+  } finally { process.off("SIGINT", onInterrupt); rl.close(); }
+}
+
+function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost {
+  const scope = kind === "restart" ? cwd : undefined;
+  return {
+    plan: () => makeUpgradePlan(kind, version, scope),
+    apply: async (plan, interrupted) => {
+      assertLifecycleAvailable();
+      const current = await makeUpgradePlan(kind, plan.version, scope);
+      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));
+      spawnRecovery(operation, true);
+      return operation;
+    },
+    lock: recoveryLock,
+    read: (id) => readOperation<RecoveryOperation>(id),
+    runner: recoveryRunner,
+    live: (op) => liveProjects(op, makeRecoveryDriver().inspect),
+    endPeer: (planned, peer) => endPlannedPeer(planned, peer),
+    runnerStoppable: (id) => signedRunner(id) !== undefined,
+    stopRunner: (id) => stopSignedRunner(id),
+    entry: join(import.meta.dir, "main.js"),
+    version: VERSION,
+  };
 }
 
 async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   const { one, rest } = takeFlags(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" && !one["--to"]) fail("upgrade requires --to <exact-version>");
+  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 plan = await makeUpgradePlan(kind, one["--to"] ?? VERSION, kind === "restart" ? cwd : undefined);
+  const dry = rest.includes("--dry-run"), yes = rest.includes("--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;
+  let to = one["--to"];
+  if (kind === "upgrade" && !to) {
+    if (yes || (!dry && !interactive)) fail("upgrade requires --to <exact-version>");
+    to = await latestRelease();
+    console.error(`ahub: the latest release is ${to}`);
+  }
+  // Before the value reaches a package spec or the registry: a range such as 0.13 would resolve to whatever matches.
+  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", "upgrade", "--to", to!, ...rest];
+    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 });
+      try { if (!/^(|y|yes)$/i.test((await rl.question("Continue? [Y/n] ")).trim())) return; } finally { rl.close(); }
+    }
+    // The coordinator owns the terminal from here. This process only waits, and a Ctrl+C meant for that session must not
+    // end it first and hand the terminal back to the shell under it.
+    process.on("SIGINT", () => {});
+    const code = await new Promise<number>((resolve) => {
+      const child = spawn(process.execPath, argv, { cwd, stdio: "inherit", env: { ...process.env, AGENTHUB_UPGRADE_HANDOVER: "1" } });
+      child.on("error", (error) => { console.error(`ahub: cannot run bun x: ${error.message}`); resolve(1); });
+      child.on("close", (status) => resolve(status ?? 1));
+    });
+    process.exit(code);
+  }
+  if (interactive) return onTerminal((io) => planScreen(upgradeHost(kind, to ?? VERSION), io));
+  const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined);
   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 (args.includes("--dry-run")) return;
+  if (dry) return;
   if (blockers.length) fail("plan has blockers; no runtime was changed");
   assertLifecycleAvailable();
-  if (!args.includes("--yes")) {
+  if (!yes) {
     if (!process.stdin.isTTY) fail("review --dry-run and use --yes in non-interactive sessions");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -382,9 +494,18 @@ const commands: Record<string, () => Promise<void> | void> = {
   upgrade: () => upgrade("upgrade"),
   restart: () => upgrade("restart"),
   recovery: async () => {
-    const [action, id, ...rest] = 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 (!id || !["status", "resume", "abort", "dispose"].includes(action ?? "") || (action !== "dispose" && rest.length)) fail(usage);
+    const [action, given, ...more] = args;
+    const usage = "usage: ahub recovery [status|resume|abort] [<operation-id>] | ahub recovery dispose [<operation-id>] --fresh-session <peer>|--stop-and-archive --reason <text>";
+    // #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 (!id) return console.log("no recovery operation is open");
+      return onTerminal(async (io) => { await operationScreen(upgradeHost("restart", VERSION), io, id); });
+    }
+    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 runner = recoveryRunner(id);
     if (action === "status") {
@@ -434,12 +555,16 @@ const commands: Record<string, () => Promise<void> | void> = {
       console.log("registration removed; project files were kept");
       return;
     }
-    if (args.some((arg) => arg !== "--json")) fail("usage: ahub projects [--json]");
-    await printProjects(args.includes("--json"));
+    const options = outputOptions();
+    if (outputArguments().length) fail("usage: ahub projects [--json] [--full] [--color=auto|always|never]");
+    await printProjects(options);
   },
 
   ui: async () => {
-    if (args.some((arg) => !["--no-open", "--all", "--stop"].includes(arg))) fail("usage: ahub ui [--all] [--no-open] | --all --stop");
+    if (args.some((arg) => !["--no-open", "--all", "--stop", "--settings"].includes(arg))) fail("usage: ahub ui [--settings] [--no-open] | --all [--no-open] | --all --stop");
+    // #269: a settings session belongs to one project's hub; the unified dashboard stays an ordinary session.
+    const settings = args.includes("--settings");
+    if (settings && args.includes("--all")) fail("ahub ui --settings opens one project's dashboard; run it without --all");
     if (args.includes("--stop")) {
       if (!args.includes("--all") || args.includes("--no-open")) fail("usage: ahub ui --all --stop");
       await stopManager();
@@ -450,11 +575,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     else {
       const hub = await connect();
       try {
-        const res = await hub.request({ t: "ui" }, 10_000);
+        const res = await hub.request({ t: "ui", ...(settings ? { settings: true } : {}) }, 10_000);
         if (!res.ok) fail(res.error);
+        // A hub older than #269 ignores the field and would hand out an ordinary session without saying so.
+        if (settings && res.settings !== true) fail("this hub does not open settings sessions; upgrade the running hub to use ahub ui --settings");
         url = res.url;
       } finally { hub.close(); }
     }
+    if (settings) console.error("Settings session: for 15 minutes this dashboard session may change permission modes, routing and start settings.");
     if (args.includes("--no-open")) return console.log(url);
     const opener = process.platform === "darwin" ? "open" : "xdg-open";
     const opened = spawnSync(opener, [url], { stdio: "ignore", timeout: 10_000 });
@@ -517,7 +645,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   console: async () => {
     if (args.some(arg => arg !== "--panels" && !arg.startsWith("--color=")) || args.filter(arg => arg.startsWith("--color=")).length > 1) fail("usage: ahub console [--panels] [--color=auto|always|never]");
     const color = resolveColor(args.find(arg => arg.startsWith("--color="))?.slice("--color=".length), { isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
-    if (color instanceof Error) return fail(color.message);
+    if (color instanceof Error) return fail("usage: ahub console [--panels] [--color=auto|always|never]");
     await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels"), color });
   },
 
@@ -556,18 +684,18 @@ const commands: Record<string, () => Promise<void> | void> = {
     let previousLaunch: unknown;
     try { previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")); } catch { /* no previous managed launch */ }
     const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
-    let result: ReturnType<typeof spawnSync>;
+    let result: Awaited<ReturnType<typeof runClaudeLaunch>>;
     try {
+      let launchRecord: ClaudeLaunchRecord | undefined;
       if (control?.instanceId) {
         // Publish only the final launch's installed hook and effective permission flags.
-        const file = join(stateDir, "claude-launch.json");
-        writeFileSync(`${file}.tmp`, JSON.stringify({ instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true }), { mode: 0o600 });
-        chmodSync(`${file}.tmp`, 0o600); renameSync(`${file}.tmp`, file);
+        launchRecord = { instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
+        recordClaudeLaunch(stateDir, launchRecord);
         cleanupStaleClaudeSettings(stateDir, previousLaunch);
       }
       if (launch.warning) console.error(launch.warning);
       const env = nativeLaunchEnv("claude", childEnv());
-      result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+      result = await runClaudeLaunch(launch, { cwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
     } finally {
       cleanupClaudeSettings(stateDir, launch.settingsFile);
     }
@@ -614,11 +742,30 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   pi: async () => {
+    // --headless is --mode headless everywhere this command goes: the preview, the hub and the conductor path.
+    if (args.includes("--headless") && !args.includes("--mode")) args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
     if (args.includes("--print-command") || args.includes("--dry-run")) {
       try { return console.log(JSON.stringify(launcherPreview("pi", args, cwd, stateDir, unattendedEnv), null, 2)); }
       catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
     }
-    const options = piFlags();
+    const flags = piFlags();
+    // #269: with no flag, Pi's start mode decides, and that is its TUI unless a person set headless.
+    const options = { ...flags, mode: flags.mode ?? startModeOf(projectConfig().peers, "pi") };
+    if (flags.mode === undefined && options.mode === "tui" && !(process.stdin.isTTY && process.stdout.isTTY)) {
+      // The default asked for the TUI and there is no terminal here (the console's command line, a script): the hub
+      // opens one, or says how to. It is never downgraded to headless. The fixed command carries no option, so one
+      // that was given needs a terminal of its own. An explicit --mode tui is taken at its word, as before.
+      if (Object.keys(flags).length) fail("Pi's TUI needs a terminal, and these options are not passed to one the hub opens: run this in a terminal, or add --mode headless");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "peer_start", peer: "pi" }, 35_000);
+        if (reply.ok !== true) {
+          const error = String(reply.error ?? "pi start refused");
+          fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_start"/i.test(error) ? `${error}; upgrade the running hub, or run ahub pi --mode headless` : error);
+        }
+        return console.log(reply.already ? "pi is already attached" : reply.opened ? `pi: opened a terminal running ${reply.command}; it attaches when its TUI is ready` : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
+      } finally { hub.close(); }
+    }
     // #215: as for Codex, a TUI launch by the recovery operation holding the lock records itself before the hub round
     // trip, so a resume in that window never reads it as gone; an ordinary launch records only after the hub accepted it.
     const recovering = options.mode === "tui" && !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock();
@@ -654,17 +801,19 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   models: async () => {
-    const action = args[0] ?? "status";
+    const action = outputArguments()[0] ?? "status";
+    const options = action === "status" ? outputOptions() : undefined;
+    const showStatus = (data: unknown) => options!.json ? console.log(JSON.stringify(data, null, 2)) : printOutput(renderModelsStatus(data, options!.columns, Date.now()), options!.color);
     const configured = projectConfig().mlx;
     if (configured.enabled === false) {
-      if (action === "status") return console.log(JSON.stringify({ state: "disabled", enabled: false }, null, 2));
+      if (action === "status") return showStatus({ state: "disabled", enabled: false });
       if (["setup", "start", "stop"].includes(action)) fail("MLX is disabled by mlx.enabled=false; models commands do not manage shared Ollama");
       fail("usage: ahub models setup|status|start|stop");
     }
     const runtimeDir = configured.runtimeDir ? resolve(cwd, configured.runtimeDir) : join(homedir(), ".agenthub", "runtimes", "mlx");
     const modelPath = configured.modelPath ? resolve(cwd, configured.modelPath) : join(homedir(), ".agenthub", "models", "qwen3-8b-mlx");
     const mlxOptions = configured.provider === "ollama" ? configured : { ...configured, runtimeDir, modelPath };
-    if (action === "status") return console.log(JSON.stringify(await inspectMlx(mlxOptions), null, 2));
+    if (action === "status") return showStatus(await inspectMlx(mlxOptions));
     if (action === "start") { const handle = await ensureMlx(mlxOptions); return console.log(JSON.stringify(handle.status(), null, 2)); }
     if (action === "stop") { await stopMlx(mlxOptions); return console.log("MLX stopped"); }
     if (action !== "setup") fail("usage: ahub models setup|status|start|stop");
@@ -694,17 +843,17 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   queue: async () => {
-    const [operation = "list", ...rest] = args;
+    const options = outputOptions();
+    const [operation = "list", ...rest] = outputArguments();
     const hub = await connect();
     try {
       if (operation === "list") {
         const { one, rest: flags } = takeFlags(rest, ["--peer"], []);
-        if (flags.some((flag) => flag !== "--json")) fail("usage: ahub queue list [--peer <id>] [--json]");
+        if (flags.length) fail("usage: ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]");
         const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}) });
         if (!result.ok) fail(result.error);
-        if (flags.includes("--json")) return console.log(JSON.stringify(result.deliveries, null, 2));
-        for (const row of result.deliveries) console.log(`${row.id}  ${row.peer}  ${row.state}  revision ${row.revision}${row.important ? "  important" : ""}`);
-        if (!result.deliveries.length) console.log("no retained deliveries");
+        if (options.json) return console.log(JSON.stringify(result.deliveries, null, 2));
+        printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
         return;
       }
       const [id, ...flags] = rest;
@@ -713,9 +862,10 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (!shown.ok) fail(shown.error);
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
-        return console.log(JSON.stringify(shown.delivery, null, 2));
+        if (options.json) return console.log(JSON.stringify(shown.delivery, null, 2));
+        return printOutput(renderQueueShow(shown.delivery, options.columns, Date.now()), options.color);
       }
-      const { one, rest: extra } = takeFlags(flags, ["--action", "--reason"], []);
+      const { one, rest: extra } = takeFlags(args.slice(2), ["--action", "--reason"], []);
       if (extra.length || !["completed", "retry", "discard"].includes(one["--action"] ?? "") || !one["--reason"]?.trim()) fail("usage: ahub queue resolve <id> --action completed|retry|discard --reason <text>");
       const result = await hub.request({ t: "queue", op: "resolve", id, revision: shown.delivery.revision, action: one["--action"], reason: one["--reason"] });
       if (!result.ok) fail(result.error);
@@ -740,18 +890,21 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   budget: async () => {
+    const options = outputOptions();
     const hub = await connect();
-    if (args[0] === "execution") {
-      const op = args[1] ?? "status";
-      let request: Record<string, unknown> = { t: "execution_budget", op, ...(args[2] ? { id: args[2] } : {}) };
+    if (outputArguments()[0] === "execution") {
+      const op = outputArguments()[1] ?? "status";
+      let request: Record<string, unknown> = { t: "execution_budget", op, ...(outputArguments()[2] ? { id: outputArguments()[2] } : {}) };
       if (op === "configure") {
-        if (!args[2]) { hub.close(); fail("usage: ahub budget execution configure <config.json>"); }
-        try { request = { t: "execution_budget", op, config: JSON.parse(readFileSync(args[2]!, "utf8")) }; }
+        if (!outputArguments()[2]) { hub.close(); fail("usage: ahub budget execution configure <config.json>"); }
+        try { request = { t: "execution_budget", op, config: JSON.parse(readFileSync(outputArguments()[2]!, "utf8")) }; }
         catch { hub.close(); fail("cannot read execution budget JSON configuration"); }
       }
       const result = await hub.request(request); hub.close();
       if (!result.ok) fail(result.error);
-      return console.log(JSON.stringify(result.budgets ?? result.budget ?? { disabled: result.disabled }, null, 2));
+      const data = result.budgets ?? result.budget ?? { disabled: result.disabled };
+      if (op !== "status" || options.json) return console.log(JSON.stringify(data, null, 2));
+      return printOutput(renderExecutionBudgetStatus(result.budgets, options.columns, Date.now()), options.color);
     }
     let set: Record<string, unknown> | undefined;
     if (args[0] === "resume") {
@@ -772,21 +925,26 @@ const commands: Record<string, () => Promise<void> | void> = {
     const res = await hub.request({ t: "budget", ...(set ? { set } : {}) });
     hub.close();
     if (!res.ok) fail(res.error);
-    const peers = Object.entries(res.budget as Record<string, any>);
-    if (!peers.length) return console.log(`no quota readings yet (gate ${res.gate}). Sources: Codex rate limits, Claude's status line (ahub claude), ahub budget set.`);
-    const left = (at: number) => { const s = Math.max(0, Math.round((at - Date.now()) / 1000)); return s >= 3600 ? `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`; };
-    for (const [peer, b] of peers) {
-      console.log(`${peer}${b.paused ? `  PAUSED: ${b.paused.reason}, resumes in ${left(b.paused.resetsAt)}` : ""}`);
-      for (const w of b.windows) console.log(`  ${String(w.id).padEnd(7)} ${String(Math.round(w.used * 100)).padStart(3)}%${w.resetsAt ? `  resets in ${left(w.resetsAt)}` : ""}  [${w.source}, ${Math.round((Date.now() - w.at) / 1000)}s ago${w.stale ? ", STALE" : ""}]`);
-    }
+    const data = { budget: res.budget, gate: res.gate };
+    if (options.json) return console.log(JSON.stringify(data, null, 2));
+    printOutput(renderBudget(data, options.columns, Date.now(), options.full), options.color);
   },
 
   board: async () => {
+    const options = outputOptions();
     const ready = args.includes("--ready");
     const state = args.find((a) => !a.startsWith("--"));
     const tasks = JSON.parse(await taskOp("hub_task_list", ready ? { ready: true } : state ? { state } : {})) as any[];
-    if (!tasks.length) return console.log("no tasks");
-    for (const t of tasks) console.log(`#${String(t.id).padEnd(4)} ${t.state.padEnd(18)} ${t.class.padEnd(10)} ${(t.owner ?? "-").padEnd(8)} review:${(t.reviewer ?? "-").padEnd(8)} ${t.title}${t.deps?.length ? `  (after ${t.deps.map((d: number) => `#${d}`).join(", ")})` : ""}${t.signals.includes("pii") ? `  (ahub task show ${t.id})` : ""}`);
+    if (options.json) return console.log(JSON.stringify(tasks, null, 2));
+    let allTasks: any[] | null = tasks;
+    if (ready || state) {
+      try { allTasks = JSON.parse(await taskOp("hub_task_list", {}, true)) as any[]; }
+      catch (error) {
+        allTasks = null;
+        console.error(paint([{ text: `ahub: board dependency stages unavailable; showing filtered rows without stages: ${String((error as Error).message).replace(/[\n\t]/g, " ")}` }], false));
+      }
+    }
+    printOutput(renderBoard(tasks, options.columns, Date.now(), options.full, allTasks), options.color);
   },
 
   task: async () => {
@@ -853,6 +1011,20 @@ const commands: Record<string, () => Promise<void> | void> = {
   pause: () => hold("pause"),
   resume: () => hold("resume"),
 
+  stop: async () => {
+    const peer = args[0];
+    if (args.length !== 1 || !peer || !/^[a-z][a-z0-9-]{0,31}$/.test(peer)) fail("usage: ahub stop <peer>");
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "peer_stop", peer }, 35_000);
+      if (reply.ok !== true) {
+        const error = String(reply.error ?? "peer stop request refused");
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_stop"/i.test(error) ? `${error}; upgrade the running hub to use ahub stop` : error);
+      }
+      console.log(`${peer}: ${reply.state}`);
+    } finally { hub.close(); }
+  },
+
   permission: async () => {
     const positional = args.filter(arg => arg !== "--yes");
     const [peer, mode] = positional;
@@ -868,6 +1040,64 @@ const commands: Record<string, () => Promise<void> | void> = {
       }
       if (reply.peers) for (const [id, value] of Object.entries(reply.peers)) console.log(`${id}: ${value}`);
       else console.log(`${peer}: ${reply.permissionMode}`);
+      if (typeof reply.note === "string" && reply.note) console.log(reply.note);
+    } finally { hub.close(); }
+  },
+
+  // #269: the terminal's side of the settings registry. Everything the dashboard's Settings section can do, and the
+  // same refusals; it talks to the running hub, so a setting is validated and announced in one place.
+  // ponytail: needs a running hub, also for a value read only at hub start; a file-only path if that gets in the way.
+  settings: async () => {
+    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo";
+    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"], undo: [] };
+    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);
+    const def = key === undefined ? undefined : settingDef(key);
+    if (typeof def === "string") fail(`${key}: ${def}`);
+    const value = sub === "set" ? parseSettingText(def!, text!) : undefined;
+    const peer = def?.group === "Permissions" ? def.path.at(-1)! : undefined;
+    if (sub === "set" && value === "never-ask" && !flags.includes("--preview")) {
+      if (!flags.includes("--yes")) fail("never-ask requires --yes; nothing was changed");
+      console.error(`never-ask: ${permissionBoundary(peer!)}; approval prompts are disabled`);
+    }
+    const hub = await connect();
+    try {
+      const request = async (message: Record<string, unknown>) => {
+        const reply = await hub.request(message, 35_000);
+        if (reply.ok !== true) {
+          const error = String(reply.error ?? "settings request refused");
+          fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "settings_/i.test(error) ? `${error}; upgrade the running hub to use ahub settings` : error);
+        }
+        return reply;
+      };
+      if (sub === "undo") return console.log((await request({ t: "settings_undo" })).text);
+      if (sub === "set" && flags.includes("--preview")) {
+        const preview = await request({ t: "settings_preview", key, value });
+        for (const line of preview.lines ?? []) console.log(line);
+        // Each side is `route explain`: the task line, "if it were assigned now:", then the trace.
+        for (const task of preview.tasks ?? []) console.log([task.before[0], "  before:", ...task.before.slice(2).map((line: string) => `    ${line}`), "  after:", ...task.after.slice(2).map((line: string) => `    ${line}`)].join("\n"));
+        if (preview.hidden) console.log(`${preview.hidden} more open tasks are not shown`);
+        return console.log("preview only; nothing was changed");
+      }
+      if (sub === "set") {
+        const reply = await request({ t: "settings_set", key, value, ...(flags.includes("--yes") && peer ? { confirm: peer } : {}) });
+        console.log(reply.text);
+        if (typeof reply.note === "string" && reply.note) console.log(reply.note);
+        return;
+      }
+      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));
+      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 hub start`] : []), ...(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.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.undo) console.log(`\nahub settings undo puts back the last write (${view.undo})`);
     } finally { hub.close(); }
   },
 
@@ -881,23 +1111,15 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   status: async () => {
-    if (args.includes("--all")) return printProjects(args.includes("--json"));
+    const options = outputOptions();
+    if (args.includes("--all")) return printProjects(options);
     const hub = await connect();
-    const { status } = await hub.request({ t: "status" });
-    hub.close();
-    if (args.includes("--json")) return console.log(JSON.stringify(status, null, 2));
-    console.log(`hub pid ${status.pid}, control 127.0.0.1:${status.controlPort}, ${status.cwd}`);
-    if (status.deliveryError) console.log(`  delivery storage: ${status.deliveryError}; dispatch is stopped`);
-    for (const pending of status.permissionDefaults ?? []) console.log(`  permission default ${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`);
-    for (const line of (status as { crash?: string[] }).crash ?? []) console.log(`  crash recovery: ${line}`);
-    const peers = Object.entries(status.peers as Record<string, PeerRow>);
-    for (const [id, p] of peers) console.log(peerLine(id, { ...p, context: p.context ?? unknownContext() }));
-    const models = (status as any).models?.backends as BackendRow[] | undefined;
-    if (models?.length) for (const backend of models) console.log(backendLine(backend));
-    if (status.switchyard) console.log(`  switchyard: ${status.switchyard}`);
-    const counts = Object.entries(status.tasks ?? {}).map(([s, n]) => `${n} ${s}`).join(", ");
-    if (counts) console.log(`  tasks: ${counts} (ahub board)`);
-    if (!peers.length) console.log("  no peers attached yet (ahub claude | ahub codex | ahub kimi)");
+    try {
+      const { status } = await hub.request({ t: "status" });
+      if (options.json) return console.log(JSON.stringify(status, null, 2));
+      const quota = await hub.request({ t: "budget" });
+      printOutput(renderStatus({ ...status, budget: quota.budget ?? {} }, options.columns, Date.now(), options.full), options.color);
+    } finally { hub.close(); }
   },
 
   logs: () => exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]),
@@ -988,15 +1210,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatResearch(r).join("\n"));
   },
   report: () => {
+    const options = outputOptions();
     const by = args.indexOf("--by");
     if (by >= 0 && args[by + 1] !== "task") return fail("--by takes task");
     const events = readEvents(join(stateDir, "events.jsonl"), since());
-    if (by >= 0) {
-      const r = summarizeByTask(events);
-      return console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatTaskReport(r).join("\n"));
-    }
-    const r = summarize(events);
-    console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatReport(r).join("\n"));
+    const data = by >= 0 ? summarizeByTask(events) : summarize(events);
+    if (options.json) return console.log(JSON.stringify(data, null, 2));
+    printOutput(renderReport(data, options.columns, Date.now(), by >= 0), options.color);
   },
   facts: async () => {
     if (!args.includes("--hook")) return fail("usage: ahub facts --hook (a Claude Code PreToolUse, PostToolUse and Stop hook)");
@@ -1051,17 +1271,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
   },
   turns: () => {
-    const { one, rest } = takeFlags(args, ["--limit"], []);
-    const rows = turnRecords((t) => t.list(rest[0], Number(one["--limit"]) || 20), []);
-    if (!rows.length) return console.log("no turns recorded (they need a git work tree and snapshots.enabled)");
-    for (const r of rows) {
-      const shown = r.changed.slice(0, 5).join(", ") + (r.changed.length > 5 ? ", ..." : "");
-      const files = r.changed.length ? `: ${shown}` : "";
-      let status = "";
-      if (!r.ended) status = " (running)";
-      else if (!r.end_tree) status = " (no end snapshot)";
-      console.log(`${r.id}  ${new Date(r.started).toLocaleString()}${status}  ${r.changed.length} files${files}`);
-    }
+    const options = outputOptions();
+    const { one, rest } = takeFlags(outputArguments(), ["--limit"], []);
+    const turns = turnRecords(t => t.list(rest[0], Number(one["--limit"]) || 20), []);
+    if (options.json) return console.log(JSON.stringify(turns, null, 2));
+    printOutput(renderTurns(turns, options.columns, Date.now()), options.color);
   },
   undo: async () => {
     const id = args.find((a) => !a.startsWith("--")) ?? fail("usage: ahub undo <turn> [--yes] [--context]");
@@ -1193,67 +1407,83 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   doctor: async () => {
-    if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"));
+    const options = outputOptions();
+    if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
     const version = (bin: string) => {
       const res = spawnSync(bin, ["--version"], { encoding: "utf8" });
       return res.status === 0 ? res.stdout.trim().split("\n")[0]! : undefined;
     };
-    const row = (ok: boolean | undefined, name: string, detail: string) =>
-      console.log(`  ${ok === undefined ? "?" : ok ? "ok" : "--"}  ${name.padEnd(22)} ${detail}`);
+    const checks: DoctorCheck[] = [];
+    const row = (ok: boolean | undefined, name: string, detail: string) => {
+      const section: DoctorCheck["section"] = ["bun", "claude", "codex", "kimi"].includes(name) ? "Tools"
+        : name === "config" || name === "retired setting" ? "Config"
+        : name.startsWith("memory") ? "Memory"
+        : ["omniroute", "omniroute key", "local fixed_model", "switchyard", "pi mlx"].includes(name) ? "Models" : "Hub";
+      const optional = ["claude", "codex", "kimi", "ahub daemon", "switchyard", "pi mlx"].includes(name) || section === "Memory";
+      const level: DoctorCheck["level"] = ok === undefined ? (["switchyard", "omniroute"].includes(name) ? "warn" : "unknown") : ok ? "ok" : optional ? "warn" : "fail";
+      checks.push({ section, level, name, detail });
+    };
 
-    for (const bin of ["bun", "claude", "codex", "kimi"]) {
-      const v = version(bin);
-      row(!!v, bin, v ?? "not found on PATH");
-    }
-    const up = await healthy();
-    row(up, "ahub daemon", up ? readControl(stateDir)!.url : "not running (ahub up)");
-    if (up) {
-      const hub = await connect();
-      try {
-        const { status } = await hub.request({ t: "status" });
-        const pending = Object.values(status.peers as Record<string, PeerRow>).reduce((n, peer) => n + (peer.needsReview ?? 0), 0);
-        row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
-        const observed = await hub.request({ t: "recovery", op: "inspect", expectedInstanceId: status.instanceId });
-        for (const peer of Object.values(observed.recovery?.peers ?? {}) as { id: string; state: string; sessionId?: string; threadId?: string }[]) {
-          if (!["claude", "codex"].includes(peer.id) || peer.state === "offline") continue;
-          const identity = peer.id === "claude" ? peer.sessionId : peer.threadId;
-          row(!!identity, `${peer.id} recovery ID`, identity ? "recorded" : `missing; verify the current conversation and reconnect with ahub ${peer.id} before upgrading`);
-        }
-      } finally { hub.close(); }
-    }
-    const plugin = pluginState(parseList<InstalledPlugin>(spawnSync("claude", ["plugin", "list", "--json"], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
-    row(plugin.state === "current", "claude plugin", 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`);
-
-    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); // issue #83
-    const omni = new OmniRoute(config.omniroute);
-    const gateway = await omni.base();
-    row(!!gateway, "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()) {
-      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(false, "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 mlxConfig = config.mlx;
-    if (mlxConfig.enabled === false) row(true, "pi mlx", "disabled (mlx.enabled=false; local endpoint not probed)");
-    else {
-      const mlx = await inspectMlx({ ...mlxConfig, runtimeDir: mlxConfig.runtimeDir ? resolve(cwd, mlxConfig.runtimeDir) : undefined, modelPath: mlxConfig.modelPath ? resolve(cwd, mlxConfig.modelPath) : undefined });
-      row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
-    }
+    try {
+      for (const bin of ["bun", "claude", "codex", "kimi"]) {
+        const v = version(bin);
+        row(!!v, bin, v ?? "not found on PATH");
+      }
+      const up = await healthy();
+      row(up, "ahub daemon", up ? readControl(stateDir)!.url : "not running (ahub up)");
+      if (up) {
+        const hub = await connect();
+        try {
+          const { status } = await hub.request({ t: "status" });
+          const pending = Object.values(status.peers as Record<string, PeerRow>).reduce((n, peer) => n + (peer.needsReview ?? 0), 0);
+          row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
+          const observed = await hub.request({ t: "recovery", op: "inspect", expectedInstanceId: status.instanceId });
+          for (const peer of Object.values(observed.recovery?.peers ?? {}) as { id: string; state: string; sessionId?: string; threadId?: string }[]) {
+            if (!["claude", "codex"].includes(peer.id) || peer.state === "offline") continue;
+            const identity = peer.id === "claude" ? peer.sessionId : peer.threadId;
+            row(!!identity, `${peer.id} recovery ID`, identity ? "recorded" : `missing; verify the current conversation and reconnect with ahub ${peer.id} before upgrading`);
+          }
+        } finally { hub.close(); }
+      }
+      const plugin = pluginState(parseList<InstalledPlugin>(spawnSync("claude", ["plugin", "list", "--json"], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
+      row(plugin.state === "current", "claude plugin", 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`);
+
+      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); // issue #83
+      const omni = new OmniRoute(config.omniroute);
+      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()) {
+        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 mlxConfig = config.mlx;
+      if (mlxConfig.enabled === false) row(true, "pi mlx", "disabled (mlx.enabled=false; local endpoint not probed)");
+      else {
+        const mlx = await inspectMlx({ ...mlxConfig, runtimeDir: mlxConfig.runtimeDir ? resolve(cwd, mlxConfig.runtimeDir) : undefined, modelPath: mlxConfig.modelPath ? resolve(cwd, mlxConfig.modelPath) : undefined });
+        row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
+      }
 
-    const memory = new MemoryClient();
-    const mem = await memory.health();
-    row(mem.ok, "memory worker", mem.ok ? `claude-mem ${mem.version ?? ""} at ${memory.url}` : `unavailable at ${memory.url} (the hub works without it)`);
-    const bridge = spawnSync("dot", ["ai", "memory", "status"], { encoding: "utf8" });
-    const out = bridge.error ? "" : bridge.stdout.replace(/\x1b\[[0-9;]*m/g, "");
-    for (const tool of ["codex", "kimi"]) {
-      row(bridge.error ? undefined : new RegExp(`✓\\s+${tool} ready`).test(out), `memory capture: ${tool}`, bridge.error ? "unknown (`dot ai memory status` not available)" : "per `dot ai memory status`");
+      const memory = new MemoryClient();
+      const mem = await memory.health();
+      row(mem.ok, "memory worker", mem.ok ? `claude-mem ${mem.version ?? ""} at ${memory.url}` : `unavailable at ${memory.url} (the hub works without it)`);
+      const bridge = spawnSync("dot", ["ai", "memory", "status"], { encoding: "utf8" });
+      const out = bridge.error ? "" : bridge.stdout.replace(/\x1b\[[0-9;]*m/g, "");
+      for (const tool of ["codex", "kimi"]) {
+        const ready = new RegExp(`✓\\s+${tool} ready`).test(out);
+        row(bridge.error ? undefined : ready, `memory capture: ${tool}`, bridge.error ? "unknown (`dot ai memory status` not available)" : `${ready ? "ready" : "not ready"}, per ` + "`dot ai memory status`");
+      }
+    } finally {
+      // Preserve findings already collected if a later probe (for example config parsing) throws.
+      if (options.json) console.log(JSON.stringify(checks, null, 2));
+      else printOutput(renderDoctor(checks, options.columns, Date.now(), options.full), options.color);
     }
   },
 };
@@ -1271,9 +1501,11 @@ async function runConductorCommand(): Promise<void> {
     input = { peer: args[0] };
   } else {
     // Native TUIs return a human launch command through the daemon; an agent shell never executes it.
+    if (cmd === "pi" && args.length === 1 && args[0] === "--headless") args.splice(0, 1, "--mode", "headless");
     if (args.length && !(cmd === "pi" && args.length === 2 && args[0] === "--mode" && ["headless", "tui"].includes(args[1] ?? ""))) fail(`conductor starts accept no launch overrides; use ahub ${cmd}${cmd === "pi" ? " [--mode headless|tui]" : ""}`);
     op = "hub_peer_start";
-    input = { peer: cmd, ...(cmd === "pi" ? { mode: args[1] ?? "headless" } : {}) };
+    // #269: a mode may only repeat the peer's start mode, which a person sets; without one the hub takes that mode.
+    input = { peer: cmd, ...(cmd === "pi" && args[1] ? { mode: args[1] } : {}) };
   }
   console.log(await taskOp(op, input));
 }