@staix/agent-hub 0.12.23 → 0.12.24

package/src/cli/main.ts

@@ -1,6 +1,20 @@
 #!/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";
@@ -11,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";
@@ -20,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";
@@ -39,9 +54,11 @@ import { setupOllamaModel } from "./models-setup.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 { 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";
@@ -49,7 +66,7 @@ import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, peerCommandRef
 import { recordCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
-import { outputWidth, renderStatus, renderBoard, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, type DoctorCheck } from "./output.ts";
+import { 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";
@@ -176,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}`);
@@ -311,13 +328,13 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false): Promise<string> {
-  const hub = await connect();
+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 });
+    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 { hub.close(); }
+  } 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). */
@@ -465,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));
@@ -625,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.
@@ -643,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("usage: ahub console [--panels] [--color=auto|always|never]");
-    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 () => {
@@ -727,18 +750,89 @@ 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 () => {
@@ -839,7 +933,8 @@ 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 () => {
@@ -873,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) => {
@@ -930,28 +1049,122 @@ const commands: Record<string, () => Promise<void> | void> = {
     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 () => {
+    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 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 (options.json) return console.log(JSON.stringify(tasks, null, 2));
+    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) {
-      try { allTasks = JSON.parse(await taskOp("hub_task_list", {}, true)) as any[]; }
+    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));
       }
     }
-    printOutput(renderBoard(tasks, options.columns, Date.now(), options.full, allTasks), options.color);
+    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"], []);
@@ -966,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>") })),
@@ -1047,16 +1260,42 @@ const commands: Record<string, () => Promise<void> | void> = {
   // #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"], undo: [] };
+    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.path.at(-1)! : 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`);
@@ -1071,19 +1310,29 @@ const commands: Record<string, () => Promise<void> | void> = {
         }
         return reply;
       };
-      if (sub === "undo") return console.log((await request({ t: "settings_undo" })).text);
+      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(line);
+        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, ...(flags.includes("--yes") && peer ? { confirm: peer } : {}) });
-        console.log(reply.text);
-        if (typeof reply.note === "string" && reply.note) console.log(reply.note);
+        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" });
@@ -1093,9 +1342,9 @@ const commands: Record<string, () => Promise<void> | void> = {
       let group = "";
       for (const row of rows) {
         if (sub === "list" && row.group !== group) console.log(`${group ? "\n" : ""}${group = row.group}`);
-        const facts = [`from ${row.source}`, row.applies === "live" ? "applies at once" : row.applies === "peer start" ? "applies at the peer's next start" : "read at hub start", ...(row.pending !== undefined ? [`${settingText(row.pending)} at the next hub start`] : []), ...(row.note ? [row.note] : [])];
+        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.values ?? []).join(", ")}${row.file === "this hub run" ? "" : ", or inherit to remove the machine-local value"}${row.risk === "raises" ? "; a dashboard needs a settings session (ahub ui --settings) to raise it" : ""}`);
+        if (sub === "get") console.log(`  ${row.label}; written to ${row.file}; takes ${row.type === "boolean" ? "true, false" : row.type === "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(); }
@@ -1110,6 +1359,15 @@ 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 () => {
     const options = outputOptions();
     if (args.includes("--all")) return printProjects(options);
@@ -1119,6 +1377,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       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(); }
   },
 
@@ -1131,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); }
     }
@@ -1182,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++;
     }
@@ -1205,7 +1489,12 @@ 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"));
   },
@@ -1284,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;
@@ -1304,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 }));
@@ -1406,6 +1700,32 @@ 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 () => {
     const options = outputOptions();
     if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
@@ -1415,16 +1735,22 @@ const commands: Record<string, () => Promise<void> | void> = {
     };
     const checks: DoctorCheck[] = [];
     const row = (ok: boolean | undefined, name: string, detail: string) => {
-      const section: DoctorCheck["section"] = ["bun", "claude", "codex", "kimi"].includes(name) ? "Tools"
+      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", "ahub daemon", "switchyard", "pi mlx"].includes(name) || section === "Memory";
+      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 });
     };
 
     try {
+      const catalog = loadRoleCatalog(cwd);
+      for (const error of catalog.errors) row(false, "catalog role", `${error.id}: ${error.reason}`);
+      try {
+        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");
@@ -1450,7 +1776,14 @@ const commands: Record<string, () => Promise<void> | void> = {
 
       const config = loadConfig(cwd);
       row(!config.ignored, "config", config.ignored ? `${config.ignored.join("; ")} (move them to .agenthub/config.local.json)` : "no machine-local field ignored");
-      for (const line of config.retired ?? []) row(false, "retired setting", line); // issue #83
+      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");
@@ -1493,8 +1826,10 @@ 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";