@staix/agent-hub 0.12.22 → 0.12.24

package/src/cli/main.ts

@@ -1,5 +1,21 @@
 #!/usr/bin/env bun
+import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board-read.ts";
+import { matchesPolicy } from "../hub/path-policy.ts";
+import { projectedDiff } from "../hub/projected-diff.ts";
+import { TextProjections } from "../hub/text-projection.ts";
+import { terminalText } from "./console-state.ts";
+import { petView, readPet, renderPet } from "./pet.ts";
+import { loadPetConfig } from "./pet-config.ts";
+import { profileName, projectProfile, resolveProfile } from "../hub/profiles.ts";
+import { catalogAssignments, loadRoleCatalog, selectedRoles } from "../hub/roles.ts";
+import { attachWatch } from "./watch.ts";
+import { verifiedJcodeCommand } from "../adapters/jcode.ts";
+import { configureJcodeMcp } from "./jcode-mcp.ts";
+import { qwenSessionId } from "../hub/crash.ts";
 import { isPermissionMode } from "../hub/permission-mode.ts";
+import { parseSettingText, settingDef, settingText, type SettingRow } from "../hub/settings.ts";
+import { isSupportedPeer } from "../hub/peer-catalog.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";
@@ -9,7 +25,7 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
-import { projectContext, realPath } from "../hub/project.ts";
+import { hubHome, projectContext, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
 import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
@@ -18,7 +34,8 @@ 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, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
+import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
+import { configureKimiMcp } from "./kimi-mcp.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
@@ -35,19 +52,21 @@ 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 { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatReport as formatBenchReport, formatRuns, MEMORY_MODES, readRuns, runSummary, sameSuite, type MemoryMode } 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 { ADDONS, isAddon, type AddonName } from "../hub/tooling.ts";
+import { goalCommand, memoryCommand } from "./memory.ts";
+import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.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, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, 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";
@@ -107,6 +126,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 });
@@ -158,7 +193,7 @@ async function healthy(): Promise<boolean> {
   finally { hub?.close(); }
 }
 
-function exec(bin: string, argv: string[], tool?: "claude" | "codex"): never {
+function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi"): never {
   const env = tool ? nativeLaunchEnv(tool, childEnv()) : childEnv();
   const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
@@ -174,12 +209,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;
@@ -189,8 +230,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() {
@@ -199,15 +240,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. */
@@ -250,43 +286,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`);
 }
 
@@ -295,12 +328,13 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-async function taskOp(op: string, a: Record<string, unknown>): 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;
+async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false, connection?: ControlClient): Promise<string> {
+  const hub = connection ?? await connect();
+  try {
+    const res = await hub.request({ t: "task", op, args: a }, op === "github_import" ? 60_000 : 30_000);
+    if (!res.ok) { if (throwOnError) throw new Error(res.error); audit("refused"); fail(res.error); }
+    return res.text;
+  } finally { if (!connection) hub.close(); }
 }
 
 /** Reads hub.db's turn records; `none` when the hub never kept one (snapshots off, no git work tree, an older hub). */
@@ -448,6 +482,7 @@ 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));
   const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined);
   console.log(JSON.stringify(plan, null, 2));
@@ -538,12 +573,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();
@@ -554,11 +593,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 });
@@ -601,14 +643,19 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: () => {
+    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow"), ["--profile"], []);
+    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general] [--shadow] [--dry-run --json]");
+    const requestedProfile = flags.one["--profile"] === undefined ? undefined : profileName(flags.one["--profile"]);
     if (args.includes("--dry-run")) {
-      const plan = planInit(cwd);
+      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"));
       return console.log(args.includes("--json") ? JSON.stringify(plan, null, 2) : plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`).join("\n") || "already up to date");
     }
     assertLifecycleAvailable();
-    const changed = init(cwd);
+    const changed = init(cwd, requestedProfile, args.includes("--shadow"));
     registeredProject();
     console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
+    const config = projectConfig(), examples = resolveProfile(config.profile, config.profile_overrides).example_checks;
+    if (examples.length) console.log(terminalText("Example checks (advisory):\n" + examples.map(example => "- " + example).join("\n")));
   },
 
   // Internal: the detached daemon process started by ahub up or the manager.
@@ -619,10 +666,10 @@ 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]");
+    if (args.some(arg => arg !== "--panels" && arg !== "--no-pet" && !arg.startsWith("--color=")) || args.filter(arg => arg.startsWith("--color=")).length > 1) fail("usage: ahub console [--panels] [--no-pet] [--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);
-    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels"), color });
+    if (color instanceof Error) return fail("usage: ahub console [--panels] [--no-pet] [--color=auto|always|never]");
+    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels"), noPet: args.includes("--no-pet"), color });
   },
 
   up: async () => {
@@ -703,26 +750,116 @@ const commands: Record<string, () => Promise<void> | void> = {
     exec(launch.cmd, launch.args, "codex");
   },
 
+  jcode: async () => {
+    if (args.includes("--print-command") || args.includes("--dry-run")) {
+      try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
+    }
+    assertLifecycleAvailable();
+    const { one, rest } = takeFlags(args, ["--mode", "--model", "--provider-profile", "--session-id"], []);
+    if (rest.length || (one["--mode"] !== undefined && one["--mode"] !== "headless")) fail("usage: ahub jcode [--mode headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
+    if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Jcode session identity");
+    const hub = await connect();
+    try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      if (snapshot?.roster?.find((row: any) => row.peer === "jcode")?.on !== true) fail("jcode is off roster; add it with ahub roster add jcode");
+      const written = configureJcodeMcp(cwd, stateDir, resolve(import.meta.dir, "../../plugins/agent-hub/server.js"));
+      if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
+      const reply = await hub.request({ t: "start", peer: "jcode", args: { mode: "headless", model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+      if (!reply.ok) fail(reply.error);
+      console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox");
+    } finally { hub.close(); }
+  },
+
+  qwen: async () => {
+    if (args.includes("--print-command") || args.includes("--dry-run")) {
+      try { return console.log(JSON.stringify(launcherPreview("qwen", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview Qwen launch: invalid arguments or configuration (details withheld)"); }
+    }
+    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 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);
+      if (!reply.ok) fail(reply.error);
+      console.log(reply.already ? "qwen is already attached" : "qwen attached (headless); use ahub say @qwen and the console for approvals");
+    } finally { hub.close(); }
+  },
   kimi: async () => {
     if (args.includes("--print-command") || args.includes("--dry-run")) {
       try { return console.log(JSON.stringify(launcherPreview("kimi", args, cwd, stateDir, unattendedEnv), null, 2)); }
       catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
     }
-    const i = args.indexOf("--model");
-    const model = i === -1 ? undefined : args[i + 1] ?? fail("--model needs an alias");
+    assertLifecycleAvailable();
+    const { one, rest } = takeFlags(args, ["--mode", "--model"], []);
+    const mode = one["--mode"] ?? startModeOf(projectConfig().peers, "kimi"), model = one["--model"];
+    if (rest.length || !["tui", "headless"].includes(mode)) fail("usage: ahub kimi [--mode tui|headless] [--model <alias>]");
+    if (mode === "tui" && one["--mode"] === undefined && !(process.stdin.isTTY && process.stdout.isTTY)) {
+      if (model) fail("Kimi's TUI needs a terminal for these options; run in a terminal or add --mode headless");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "peer_start", peer: "kimi" }, 35_000);
+        if (!reply.ok) fail(reply.error);
+        return console.log(reply.already ? "kimi is already attached" : `kimi: opened a terminal running ${reply.command}; it attaches pull-only when its TUI is ready`);
+      } finally { hub.close(); }
+    }
     const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "kimi", args: { model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
-    hub.close();
-    if (!res.ok) fail(res.error);
-    console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
+    try {
+      if (mode === "tui") {
+        const launch = buildKimiTuiLaunch(projectConfig().kimi_cmd, model);
+        const snapshot = (await hub.request({ t: "status" })).status;
+        if (snapshot?.roster?.find((row: any) => row.peer === "kimi")?.on === false) fail("kimi is off roster; add it with ahub roster add kimi");
+        const peer = snapshot?.peers?.kimi;
+        if (peer && !["offline"].includes(peer.state) && !peer.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
+        const admission = await hub.request({ t: "start", peer: "kimi", args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+        if (!admission.ok) fail(admission.error);
+        let result: ReturnType<typeof spawnSync>;
+        try {
+          const written = configureKimiMcp(cwd, stateDir, resolve(import.meta.dir, "../../plugins/agent-hub/server.js"), "tui");
+          if (written.tracked) console.error(".kimi-code/mcp.json is tracked; the agent-hub entry contains machine paths. Review this local change before committing it.");
+          result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+        } finally {
+          if (admission.admissionId) await hub.request({ t: "kimi_launch_end", admissionId: admission.admissionId }).catch(() => {});
+        }
+        if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
+        process.exit(result.status ?? 1);
+      }
+      const peer = (await hub.request({ t: "status" })).status?.peers?.kimi;
+      if (peer?.pullOnly && peer.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
+      configureKimiMcp(cwd, stateDir, resolve(import.meta.dir, "../../plugins/agent-hub/server.js"), "headless");
+      const res = await hub.request({ t: "start", peer: "kimi", args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      if (!res.ok) fail(res.error);
+      console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
+    } finally { hub.close(); }
   },
 
   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();
@@ -758,17 +895,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");
@@ -794,21 +933,22 @@ const commands: Record<string, () => Promise<void> | void> = {
     hub.close();
     if (!res.ok) fail(res.error);
     if (res.recorded) return console.log("recorded only ([FYI]); no peer was interrupted");
-    console.log(res.targets.length ? `queued for: ${res.targets.join(", ")}` : "no peers attached; nothing delivered");
+    console.log(paint([{ text: res.targets.length ? `queued for: ${res.targets.join(", ")}` : "no peers attached; nothing delivered" }], false));
+    if (typeof res.notice === "string" && res.notice) console.log(paint([{ text: res.notice }], false));
   },
 
   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;
@@ -817,9 +957,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);
@@ -827,6 +968,30 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
 
+  watch: async () => {
+    const peer = args[0];
+    if (peer !== "kimi" && peer !== "qwen") 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);
+    const hub = await connect();
+    const input = process.stdin;
+    const raw = !!input.isRaw;
+    let leave = () => {};
+    const closed = new Promise<void>(resolve => { leave = resolve; });
+    const key = (chunk: Buffer) => { if (chunk.includes(3) || chunk.toString().includes("q")) leave(); };
+    hub.onClose = leave;
+    process.on("SIGINT", leave);
+    try {
+      await attachWatch(hub, peer, line => console.log(line), { columns: () => process.stdout.columns || 80, color, noThoughts: args.includes("--no-thoughts") });
+      if (input.isTTY) { input.setRawMode(true); input.on("data", key); input.resume(); }
+      await closed;
+    } finally {
+      input.off("data", key); process.off("SIGINT", leave);
+      if (input.isTTY) input.setRawMode(raw);
+      input.pause(); hub.close();
+    }
+  },
   tail: async () => {
     const hub = await connect();
     hub.onPush = (msg) => {
@@ -844,18 +1009,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") {
@@ -876,28 +1044,127 @@ 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);
+  },
+
+  backlog: async () => {
+    const [sub, id, revision, value, ...reason] = args;
+    if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_backlog_list", {}));
+    if (sub === "add" && args.length >= 3) return console.log(await taskOp("hub_task_propose", { class: id, title: args.slice(2).join(" "), backlog: true }));
+    if (!/^[1-9]\d*$/.test(id ?? "")) fail("usage: ahub backlog list|add <class> <title...>|pull|return <id>|plan|pin <id> <revision> <value> <reason...>|undo <id> <revision>");
+    if (["pull", "return"].includes(sub ?? "") && args.length === 2) return console.log(await taskOp(sub === "pull" ? "backlog_pull" : "backlog_return", { id }));
+    if (!/^\d+$/.test(revision ?? "")) fail("planning revision is required");
+    if (sub === "pull-ready" && args.length >= 4) return console.log(await taskOp("hub_backlog_pull", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
+    if (sub === "split" && value && reason.length) {
+      let parts: unknown;try { parts=JSON.parse(value); } catch { return fail("split parts must be JSON"); }
+      return console.log(await taskOp("hub_backlog_split", { id: Number(id), revision: Number(revision), parts, reason: reason.join(" ") }));
     }
+    if (sub === "undo" && args.length === 3) return console.log(await taskOp("hub_backlog_undo", { id: Number(id), revision: Number(revision) }));
+    if (!["plan", "pin"].includes(sub ?? "") || !value || !reason.length) fail("planning needs fields and a reason");
+    let fields: unknown;
+    try { fields = sub === "pin" ? { pinned: value === "true" ? true : value === "false" ? false : undefined } : JSON.parse(value); }
+    catch { return fail("planning fields must be JSON"); }
+    if (sub === "pin" && value !== "true" && value !== "false") fail("pin must be true or false");
+    console.log(await taskOp("hub_backlog_plan", { id: Number(id), revision: Number(revision), fields, reason: reason.join(" ") }));
+  },
+
+  release: async () => {
+    const [sub, name, revision, value] = args;
+    if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_release_list", {}));
+    if (sub === "show" && name && args.length === 2) {
+      return console.log(await taskOp("release_show", { name }));
+    }
+    if (sub === "new" && name && revision && args.length === 4 && /^\d+$/.test(value ?? "")) return console.log(await taskOp("release_new", { name, goal: revision, order: Number(value) }));
+    if (!name || !/^\d+$/.test(revision ?? "")) fail("usage: ahub release new <name> <goal> <order>|list|show <name>|plan <name> <revision> <dates-json>|activate|freeze|ship|drop <name> <revision>");
+    const states: Record<string, string> = { activate: "active", freeze: "frozen", ship: "shipped", drop: "dropped" };
+    let fields: unknown;
+    if (sub === "plan" && value && args.length === 4) {
+      try { fields = JSON.parse(value); } catch { return fail("release dates must be JSON"); }
+    } else if (sub && Object.hasOwn(states, sub) && args.length === 3) fields = { state: states[sub] };
+    else return fail("invalid release command");
+    console.log(await taskOp("release_change", { name, revision: Number(revision), fields }));
   },
 
   board: async () => {
-    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 (args[0] === "import") {
+      if (args[1] !== "github" || (args.length - 2) % 2 !== 0) fail("usage: ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]");
+      const selection: Record<string, string> = {};
+      for (let i = 2; i < args.length; i += 2) { const key = args[i]!, value = args[i+1]; if (!["--repo", "--label", "--milestone"].includes(key) || !value || Object.hasOwn(selection, key.slice(2))) fail("invalid GitHub import options"); selection[key.slice(2)] = value; }
+      if (!selection.label) fail("GitHub import requires --label");
+      return console.log(await taskOp("github_import", selection));
+    }
+    const options = outputOptions();
+    const { one, rest } = takeFlags(args, ["--release", "--release-id"], []);
+    if (one["--release"] !== undefined && !one["--release"].trim() || one["--release"] !== undefined && one["--release-id"] !== undefined || one["--release-id"] !== undefined && !/^[1-9]\d*$/.test(one["--release-id"])) fail("choose --release <nonempty name> or --release-id <positive id>");
+    const release = one["--release-id"] ? "#"+one["--release-id"] : one["--release"];
+    const boardHub = await connect();
+    try {
+    let boardStatus: any;
+    if (release) { const reply = await boardHub.request({ t: "status" }); boardStatus = reply.status; if (!supportsBoardReleaseFilter(boardStatus)) fail("running hub does not support release filters; use a compatible daemon"); }
+    const ready = rest.includes("--ready"), byColumn = rest.includes("--columns");
+    const state = rest.find((a) => !a.startsWith("--"));
+    if (byColumn && !boardStatus) boardStatus = (await boardHub.request({ t: "status" })).status;
+    if (byColumn && !supportsBoardColumnMetadata(boardStatus)) fail("running hub does not support accurate board column metadata; use a compatible daemon");
+    const tasks = JSON.parse(await taskOp("hub_task_list", { ...(ready ? { ready: true } : state ? { state } : {}), ...(release ? { release } : {}), ...(byColumn ? { columnMetadata: true } : {}) }, false, boardHub)) as any[];
+    if (options.json && !byColumn) return console.log(JSON.stringify(tasks, null, 2));
+    let allTasks: any[] | null = tasks;
+    if (ready || state || release) {
+      try { allTasks = JSON.parse(await taskOp("hub_task_list", byColumn ? { columnMetadata: true } : {}, true, boardHub)) as any[]; }
+      catch (error) {
+        if (byColumn) fail("board column dependency context unavailable; retry with a complete snapshot");
+        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));
+      }
+    }
+    if (byColumn) {
+      const status = (await boardHub.request({ t: "status" })).status; if (!status?.peers) fail("peer status unavailable"); if (options.json) console.log(JSON.stringify({ tasks, ...boardColumnModel(tasks, status.peers, allTasks) }, null, 2)); else printOutput(renderBoardColumns(tasks, status.peers, options.columns, Date.now(), options.full, allTasks), options.color);
+    } else printOutput(renderBoard(tasks, options.columns, Date.now(), options.full, allTasks), options.color);
+    } finally { boardHub.close(); }
+  },
+
+  sdlc: async () => {
+    const sub = args[0], id = args[1] === undefined ? undefined : Number(args[1]);
+    if (sub === "queue" || sub === "release") {
+      const repo = args[1], liveIssues = args.slice(2).map(Number);
+      if (!repo || args.length > 34 || (sub === "queue" && args.length !== 2) || liveIssues.some(id => !Number.isSafeInteger(id) || id <= 0)) fail("usage: ahub sdlc queue <owner/repository> | release <owner/repository> [live-issue...]");
+      const hub = await connect();
+      try { const reply = await hub.request({ t: "sdlc", op: sub, repo, liveIssues }, 30_000); if (!reply.ok) fail(reply.error); console.log(JSON.stringify(reply, null, 2)); }
+      finally { hub.close(); }
+      return;
+    }
+    if (sub === "record") {
+      if (args.length !== 3 || !Number.isSafeInteger(id) || id! <= 0 || Buffer.byteLength(args[2]!) > 32768) fail("usage: ahub sdlc record <task> '<receipt JSON>'");
+      let receipt: unknown; try { receipt = JSON.parse(args[2]!); } catch { fail("receipt must be valid JSON"); }
+      return console.log(await taskOp("hub_sdlc_record", { id, receipt }));
+    }
+    if (!["status", "explain", "export"].includes(sub ?? "") || args.length > 2 || (["explain", "export"].includes(sub ?? "") && id === undefined) || (id !== undefined && (!Number.isSafeInteger(id) || id <= 0))) fail("usage: ahub sdlc status [task] | explain <task> | export <task>");
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "sdlc", op: sub, ...(id === undefined ? {} : { id }) }, 30_000);
+      if (!reply.ok) fail(reply.error);
+      console.log(JSON.stringify(reply, null, 2));
+    } finally { hub.close(); }
   },
 
   task: async () => {
     const [sub, ...rest] = args;
+    if (sub === "role") {
+      if (rest.length !== 2 || !/^[1-9]\d*$/.test(rest[0]!)) fail("usage: ahub task role <id> <role|none>");
+      const hub = await connect();
+      try { const reply = await hub.request({ t: "task_catalog_role", id: Number(rest[0]), role: rest[1] === "none" ? null : rest[1] }); if (!reply.ok) fail(reply.error); console.log(reply.text); }
+      finally { hub.close(); }
+      return;
+    }
     if (sub === "show") return console.log(await taskOp("task_show", { id: rest[0] }));
     if (sub === "escalate") return console.log(await taskOp("task_escalate", { id: rest[0] }));
-    if (sub === "assign") return console.log(await taskOp("task_assign", { id: rest[0], peer: rest[1] }));
+    if (sub === "assign") {
+      const { one, rest: positional } = takeFlags(rest, ["--role"], []);
+      const role = one["--role"] ?? "owner";
+      if (positional.length !== 2 || !["owner", "reviewer"].includes(role)) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer]");
+      return console.log(await taskOp("task_assign", { id: positional[0], peer: positional[1], ...(role === "reviewer" ? { role } : {}) }));
+    }
     if (sub === "label") {
       // #247: a person's later verdict on an approved task (the identity gate keeps it human-only), for research records.
       const { one, rest: positional } = takeFlags(rest, ["--created"], []);
@@ -912,20 +1179,20 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub !== "propose" || rest.length < 1) fail("usage: ahub task propose [<class>] <title...> | show <id> | assign <id> <peer> | escalate <id>");
     // `--class` is the explicit form. A first word that is a class name is still taken as the class (the documented
     // short form), but said out loud: "review the auth module" would otherwise be filed as class review, silently.
-    const urgent = rest.includes("--urgent");
-    const flags = takeFlags(rest.filter((a) => a !== "--urgent"), ["--owner", "--detail", "--class"], ["--path", "--after"]);
-    const positional = !flags.one["--class"] && (CLASSES as readonly string[]).includes(flags.rest[0] ?? "") && flags.rest.length > 1;
+    const urgent = rest.includes("--urgent"), backlog = rest.includes("--backlog");
+    const flags = takeFlags(rest.filter((a) => a !== "--urgent" && a !== "--backlog"), ["--owner", "--detail", "--class"], ["--path", "--after"]);
+    const positional = !flags.one["--class"] && ((CLASSES as readonly string[]).includes(flags.rest[0] ?? "") || Object.hasOwn((() => { const config = projectConfig(); return resolveProfile(config.profile, config.profile_overrides); })().classes, flags.rest[0] ?? "")) && flags.rest.length > 1;
     const cls = flags.one["--class"] ?? (positional ? flags.rest[0] : undefined);
     const title = (positional ? flags.rest.slice(1) : flags.rest).join(" ");
     if (positional) console.error(`note: "${cls}" was taken as the class and left out of the title; use --class <c> when the title itself starts with that word`);
-    console.log(await taskOp("hub_task_propose", { ...(cls ? { class: cls } : {}), title, owner: flags.one["--owner"], detail: flags.one["--detail"], ...(flags.many["--path"]?.length ? { refs: { paths: flags.many["--path"] } } : {}), ...(flags.many["--after"]?.length ? { after: flags.many["--after"].map(Number) } : {}), ...(urgent ? { urgent: true } : {}) }));
+    console.log(await taskOp("hub_task_propose", { ...(cls ? { class: cls } : {}), title, owner: flags.one["--owner"], detail: flags.one["--detail"], ...(flags.many["--path"]?.length ? { refs: { paths: flags.many["--path"] } } : {}), ...(flags.many["--after"]?.length ? { after: flags.many["--after"].map(Number) } : {}), ...(urgent ? { urgent: true } : {}), ...(backlog ? { backlog: true } : {}) }));
   },
 
   review: async () => {
-    const { many, rest } = takeFlags(args, [], ["--unmet"]);
+    const { one, many, rest } = takeFlags(args, ["--head"], ["--unmet"]);
     const [id, verdict, ...note] = rest;
     if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]...");
-    console.log(await taskOp("hub_review", { id: Number(id), verdict, note: note.join(" "), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
+    console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
   },
 
   remember: async () => console.log(await taskOp("hub_remember", { text: freeText(args, "ahub remember <text>") })),
@@ -990,6 +1257,99 @@ const commands: Record<string, () => Promise<void> | void> = {
     } 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.
+  roster: async () => {
+    const options = outputOptions(), flags = args.filter(arg => arg.startsWith("--")), positional = outputArguments().filter(arg => arg !== "--yes" && arg !== "--now");
+    const [sub = "list", peer, ...extra] = positional;
+    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !isSupportedPeer(peer)) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
+    const hub = await connect();
+    try {
+      const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused")); return reply; };
+      if (sub === "list") {
+        const view = await request({ t: "settings_get" });
+        if (!Array.isArray(view.roster)) fail("upgrade the running hub to use ahub roster");
+        return options.json ? console.log(JSON.stringify(view.roster, null, 2)) : printOutput(renderRoster(view.roster, options.columns), options.color);
+      }
+      const key = `roster.${peer}`, value = sub === "add";
+      const preview = await request({ t: "settings_preview", key, value });
+      printOutput((preview.lines ?? []).map((text: string) => [{ text }]), options.color);
+      if (sub === "remove" && !flags.includes("--yes")) {
+        if (!process.stdin.isTTY) fail("not a terminal: nothing was changed; rerun with --yes after reviewing the preview");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        let answer: string; try { answer = await rl.question(`Remove ${peer}? [y/N] `); } finally { rl.close(); }
+        if (!/^(y|yes)$/i.test(answer.trim())) return console.log("nothing was changed");
+      }
+      const result = await request({ t: "settings_set", key, value, ...(sub === "remove" ? { confirm: peer, now: flags.includes("--now") } : {}) });
+      printOutput([[{ text: result.text }]], options.color);
+    } finally { hub.close(); }
+  },
+  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", "--now"], 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}`);
+    if (flags.includes("--now") && (typeof def !== "object" || def.group !== "Roster")) fail(usage);
+    const value = sub === "set" ? parseSettingText(def!, text!) : undefined;
+    const peer = def?.group === "Permissions" || def?.group === "Roster" ? 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") {
+        const view = await request({ t: "settings_get" }), undoDef = settingDef(view.undo);
+        const rosterPeer = typeof undoDef !== "string" && undoDef.group === "Roster" ? undoDef.path[1] : undefined;
+        let confirm: string | undefined;
+        if (rosterPeer) {
+          if (!process.stdin.isTTY) fail("undoing a roster setting needs confirmation in a terminal; use ahub settings set for an explicit scripted change");
+          const rl = createInterface({ input: process.stdin, output: process.stdout });
+          try { confirm = (await rl.question(`Type ${rosterPeer} to confirm this roster undo: `)).trim(); } finally { rl.close(); }
+        }
+        return console.log(paint([{ text: (await request({ t: "settings_undo", ...(confirm ? { confirm } : {}) })).text }], false));
+      }
+      if (sub === "set" && flags.includes("--preview")) {
+        const preview = await request({ t: "settings_preview", key, value });
+        for (const line of preview.lines ?? []) console.log(paint([{ text: line }], false));
+        // 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, now: flags.includes("--now"), ...(flags.includes("--yes") && peer ? { confirm: peer } : {}) });
+        console.log(paint([{ text: reply.text }], false));
+        if (typeof reply.note === "string" && reply.note) console.log(paint([{ text: reply.note }], false));
+        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 ${row.applies === "peer start" ? "peer" : "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.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.undo) console.log(`\nahub settings undo puts back the last write (${view.undo})`);
+    } finally { hub.close(); }
+  },
+
   permit: async () => {
     const [id, option] = args;
     if (!id || !option) fail("usage: ahub permit <id> <option|deny>");
@@ -999,24 +1359,30 @@ const commands: Record<string, () => Promise<void> | void> = {
     hub.close();
   },
 
+  pet: () => {
+    if (args.some(arg => arg !== "--short")) return fail("usage: ahub pet [--short]");
+    const short = args.includes("--short");
+    let character: import("../pet/frame.ts").CharacterId | undefined;
+    try { character = loadPetConfig(cwd).character; } catch { /* explicit structural reads remain available with malformed presentation config */ }
+    const text = renderPet(readPet(stateDir), short, character);
+    process.stdout.write(short ? text : text + "\n");
+  },
+
   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);
+      if (status.needs) { const pet = loadPetConfig(cwd); if (pet.enabled) console.log(renderPet(petView(status), false, pet.character)); }
+      // #258: open long-term tasks and who holds them, as of this machine's last memory sync.
+      if (existsSync(join(hubHome(), "memory", "index.db"))) {
+        try { const lines = await goalCommand(["list"], cwd); if (!lines.startsWith("no open")) console.log(`\nlong-term tasks\n${lines}`); } catch { /* memory unreadable: status goes on */ }
+      }
+    } finally { hub.close(); }
   },
 
   logs: () => exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]),
@@ -1028,18 +1394,26 @@ const commands: Record<string, () => Promise<void> | void> = {
     const json = args.includes("--json");
     const [sub, ...rest] = args.filter((a) => a !== "--json");
     if (sub === "run") {
-      const { one, rest: positional } = takeFlags(rest, ["--arm", "--repeat", "--tasks"], []);
+      const { one, many, rest: positional } = takeFlags(rest, ["--arm", "--repeat", "--tasks", "--memory"], ["--addon"]);
+      if (one["--memory"] !== undefined && !(MEMORY_MODES as readonly string[]).includes(one["--memory"])) fail(`--memory takes ${MEMORY_MODES.join(", ")}`);
+      // #248: `--addon ripwire=off` declares the arm's add-on state; the run refuses peers that do not match it.
+      const addons: Partial<Record<AddonName, "on" | "off">> = {};
+      for (const spec of many["--addon"] ?? []) {
+        const [name, state] = spec.split("=");
+        if (!name || !isAddon(name) || (state !== "on" && state !== "off") || addons[name]) fail(`--addon takes <name>=on|off once per add-on, name one of ${ADDONS.join(", ")}`);
+        addons[name] = state;
+      }
       const suite = positional[0];
       const repeat = one["--repeat"] === undefined ? 1 : Number(one["--repeat"]);
       if (!suite || positional.length !== 1 || !one["--arm"]?.trim() || !Number.isSafeInteger(repeat) || repeat < 1 || repeat > 100) {
-        fail("usage: ahub bench run <suite.json> --arm <label> [--repeat 1..100] [--tasks a,b]");
+        fail("usage: ahub bench run <suite.json> --arm <label> [--repeat 1..100] [--tasks a,b] [--addon <name>=on|off]... [--memory off|claude-mem|native|both]");
       }
       await benchPreflight(cwd, loadConfig(cwd).bench.enabled); // the suite's refs are checked once it is read
       let interrupted = false;
       const stop = () => { interrupted = true; console.log("stopping at the next check: the attempt in progress is recorded as interrupted (a task still open is named)"); };
       process.on("SIGINT", stop);
       try {
-        const run = await runBench({ cwd, stateDir, suitePath: resolve(invokedFrom, suite!), arm: one["--arm"]!.trim(), repeat, only: one["--tasks"]?.split(",").map((t) => t.trim()).filter(Boolean), stopped: () => interrupted }, defaultIo(stateDir, cwd));
+        const run = await runBench({ cwd, stateDir, suitePath: resolve(invokedFrom, suite!), arm: one["--arm"]!.trim(), repeat, addons, ...(one["--memory"] ? { memory: one["--memory"] as MemoryMode } : {}), only: one["--tasks"]?.split(",").map((t) => t.trim()).filter(Boolean), stopped: () => interrupted }, defaultIo(stateDir, cwd));
         return console.log(formatBenchReport(benchReport(readRuns().filter((r) => r.header.run === run))).join("\n"));
       } finally { process.off("SIGINT", stop); }
     }
@@ -1079,12 +1453,25 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     fail("usage: ahub bench run|list|status|report|compare|export (ahub help bench)");
   },
+  memory: async () => {
+    // #258: the hub's own memory on this machine; reads are anyone's, changes a person's.
+    try { console.log(await memoryCommand(args, cwd)); } catch (e) { fail((e as Error).message); }
+  },
+  goal: async () => {
+    // #258: long-term tasks; a link goes through the project's hub, so Tasks validates the board task.
+    const link = async (goal: string, task: string) => {
+      const hub = await connect();
+      try { const r = await hub.request({ t: "goal_link", goal, task: Number(task) }); if (!r.ok) throw new Error(String(r.error)); return String(r.text); }
+      finally { hub.close(); }
+    };
+    try { console.log(await goalCommand(args, cwd, { link })); } catch (e) { fail((e as Error).message); }
+  },
   research: () => {
     // #247: measures from the opt-in research records; `export` writes them out, `backfill` builds them from events.jsonl.
     const [sub] = args;
     // Another project is `ahub --project <dir> research`; anything unknown is refused rather than ignored.
     const flags = new Set(["--all", "--json", "--since", "--format"]), valued = new Set(["--since", "--format"]);
-    for (let i = sub === "export" || sub === "backfill" ? 1 : 0; i < args.length; i++) {
+    for (let i = sub === "export" || sub === "backfill" || sub === "addons" ? 1 : 0; i < args.length; i++) {
       if (!flags.has(args[i]!)) fail(`ahub research: unknown argument ${args[i]} (another project: ahub --project <dir> research)`);
       if (valued.has(args[i]!)) i++;
     }
@@ -1102,20 +1489,23 @@ const commands: Record<string, () => Promise<void> | void> = {
       const kept = records.filter((r) => r.kind === "label" || Date.parse(r.approvedAt) >= from);
       return void process.stdout.write(args.includes("--format") && format === "csv" ? toCsv(kept) : kept.map((r) => JSON.stringify(r)).join("\n") + (kept.length ? "\n" : ""));
     }
-    if (sub !== undefined && !sub.startsWith("--")) fail("usage: ahub research [--since 30d] [--all] [--json] | export [--format jsonl|csv] [--since] [--all] | backfill");
+    if (sub === "addons") {
+      // #248: approved tasks with each add-on on against off, by the tooling fingerprint in their records.
+      const rows = addonReport(records, from);
+      return console.log(args.includes("--json") ? JSON.stringify(rows, null, 2) : formatAddons(rows).join("\n"));
+    }
+    if (sub !== undefined && !sub.startsWith("--")) fail("usage: ahub research [--since 30d] [--all] [--json] | addons [--since] [--all] [--json] | export [--format jsonl|csv] [--since] [--all] | backfill");
     const r = researchReport(records, from);
     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)");
@@ -1170,17 +1560,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]");
@@ -1189,9 +1573,10 @@ const commands: Record<string, () => Promise<void> | void> = {
     const { start_tree: startTree, end_tree: endTree } = turn;
     if (!startTree || !endTree) fail(`turn ${id} has no ${startTree ? "end" : "start"} snapshot: the hub stopped during it, or a snapshot failed (see hub.log)`);
     const repo = repoOf(cwd) ?? fail(`${cwd} is not in a git work tree`);
-    if (!hasTree(repo.top, startTree) || !hasTree(repo.top, endTree)) fail(`turn ${id}'s snapshots are gone from the git object store (git gc prunes them after two weeks)`);
+    if (!hasTree(repo, startTree) || !hasTree(repo, endTree)) fail(`turn ${id}'s snapshots are gone from the git object store (git gc prunes them after two weeks)`);
     // Another peer's turn that overlapped this one in time has its changes in this turn's diff as well.
-    const keep = Math.max(1, Number(projectConfig().snapshots.keep) || 20);
+    const undoConfig = projectConfig();
+    const keep = Math.max(1, Number(undoConfig.snapshots.keep) || 20);
     const overlapping = turnRecords((t) => t.overlapping(turn, keep), { paths: [] as string[], unknown: [] as string[] });
     if (overlapping.unknown.length) fail(`refusing to undo ${id}: these turns of other peers ran at the same time and their changes are not known (still running, cut short, or not snapshotted): ${overlapping.unknown.join(", ")}`);
     let reverted = false;
@@ -1209,6 +1594,10 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (first.undone) return console.log(`turn ${id} is already undone: its files are as they were before it started`);
     console.log(first.restore.length ? `turn ${id} changed:\n  ${first.restore.join("\n  ")}` : `turn ${id} changed no files`);
     console.log("(every change made in the project during the turn counts as its own, including any by Claude or by you)");
+    const projections = new TextProjections({ cwd, stateDir, config: undoConfig.text_projection ?? {}, deny: undoConfig.local.deny, readAllow: undoConfig.local.read_allow, log: line => console.error(line) });
+    const preview = projectedDiff({ repo, from: endTree, to: startTree, paths: first.restore, projections, deny: undoConfig.local.deny, privatePath: path => matchesPolicy(cwd, join(repo.top, path), undoConfig.pii?.paths ?? []) });
+    if (preview) console.log(terminalText("Undo preview (end snapshot to start snapshot):\n" + preview));
+
     if (!args.includes("--yes")) return console.log("nothing was changed; add --yes to restore these files");
     if (args.includes("--context")) {
       console.log(await taskOp("turn_revert", { turn: id }));
@@ -1311,68 +1700,123 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log("Claude Code sessions attached to this hub lost their hub session: relaunch them with ahub claude");
   },
 
+  role: async () => {
+    const catalog = loadRoleCatalog(cwd);
+    if (args[0] === "list") {
+      const { one, rest } = takeFlags(args.slice(1), ["--group"], []);
+      if (rest.length) fail("usage: ahub role list [--group <group>]");
+      return console.log(paint([{ text: JSON.stringify({ roles: [...catalog.roles.values()].filter(role => !one["--group"] || role.group === one["--group"]).map(({ body: _body, review: _review, ...role }) => role), errors: catalog.errors }, null, 2) }], false));
+    }
+    if (args[0] === "show" && args.length === 2) {
+      const role = catalog.roles.get(args[1]!); if (!role) fail("unknown catalog role; run ahub role list");
+      return console.log(paint([{ text: JSON.stringify(role, null, 2) }], false));
+    }
+    if (["assign", "clear"].includes(args[0] ?? "")) {
+      const [op, peer, id] = args;
+      if (!peer || !isSupportedPeer(peer) || !id && op === "assign" || args.length > 3) fail("usage: ahub role assign <peer> <id> | clear <peer> [<id>]");
+      const hub = await connect();
+      try {
+        const view = await hub.request({ t: "settings_get" }); if (!view.ok) fail(view.error);
+        const row = (view.rows as SettingRow[]).find(row => row.key === `catalog_roles.${peer}`); if (!row) fail("this hub does not support catalog role settings");
+        const current = Array.isArray(row!.pending) ? row!.pending : Array.isArray(row!.value) ? row!.value : [];
+        const value = op === "assign" ? [...new Set([...current, id!])] : id ? current.filter(role => role !== id) : [];
+        const reply = await hub.request({ t: "settings_set", key: row!.key, value }); if (!reply.ok) fail(reply.error); console.log(reply.text);
+      } finally { hub.close(); }
+      return;
+    }
+    fail("usage: ahub role list [--group <group>] | show <id> | assign <peer> <id> | clear <peer> [<id>]");
+  },
   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", "qwen", "jcode"].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", "qwen", "jcode", "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 catalog = loadRoleCatalog(cwd);
+      for (const error of catalog.errors) row(false, "catalog role", `${error.id}: ${error.reason}`);
       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}` : ""}`);
-    }
+        const config = loadConfig(cwd), assigned = catalogAssignments(config.catalog_roles);
+        for (const peer of Object.keys(assigned)) selectedRoles(peer, config.roles, assigned, catalog);
+      } catch { row(false, "catalog roles", "invalid assignment id, shape or flow base"); }
+      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);
+      if (config.roster.jcode === true) {
+        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) {
+        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
+      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);
     }
   },
 };
@@ -1382,17 +1826,21 @@ async function runConductorCommand(): Promise<void> {
   let input: Record<string, unknown>;
   if (cmd === "task") {
     op = args[0] === "assign" ? "hub_task_assign" : "hub_task_escalate";
-    if (!args[1] || (args[0] === "assign" && !args[2]) || args.length !== (args[0] === "assign" ? 3 : 2)) fail("usage: ahub task assign <id> <peer> | escalate <id>");
-    input = { id: Number(args[1]), ...(args[0] === "assign" ? { peer: args[2] } : {}) };
+    const { one, rest: positional } = takeFlags(args.slice(1), args[0] === "assign" ? ["--role"] : [], []);
+    const role = one["--role"] ?? "owner";
+    if (!positional[0] || positional.length !== (args[0] === "assign" ? 2 : 1) || !["owner", "reviewer"].includes(role)) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer] | escalate <id>");
+    input = { id: Number(positional[0]), ...(args[0] === "assign" ? { peer: positional[1], ...(role === "reviewer" ? { role } : {}) } : {}) };
   } else if (cmd === "pause" || cmd === "resume") {
     if (args.length !== 1) fail(`usage: ahub ${cmd} <peer>`);
     op = cmd === "pause" ? "hub_peer_hold" : "hub_peer_release";
     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));
 }