@staix/agent-hub 0.12.19 → 0.12.21

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { isPermissionMode } from "../hub/permission-mode.ts";
 import { currentRouting } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -11,20 +12,21 @@ import { factsHook } from "./facts-hook.ts";
 import { 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";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { buildLaunch, claudeObservationHooks, nativeLaunchEnv, UNATTENDED_WARNING } from "./launch.ts";
+import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, claudeObservationHooks, nativeLaunchEnv, UNATTENDED_WARNING } from "./launch.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
 import { freeText } from "./free-text.ts";
 import { createInterface } from "node:readline/promises";
-import { assertLifecycleAvailable, readOperation } from "../hub/recovery-store.ts";
+import { activeOperation, assertLifecycleAvailable, readOperation, recoveryLock, recoveryRunner } from "../hub/recovery-store.ts";
 import { childEnv } from "../hub/child-process.ts";
-import { abortRecovery, createOperation, publicOperation, registeredProjects, runRecovery, type RecoveryOperation } from "./upgrade.ts";
+import { abortRecovery, createOperation, disposeRecovery, liveProjects, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation } from "./upgrade.ts";
 import { makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
 import { recordTerminalLaunch } from "./terminal-recovery.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
@@ -33,14 +35,19 @@ 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 { parseSince, readEvents } from "../hub/events.ts";
+import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatReport as formatBenchReport, formatRuns, readRuns, runSummary, sameSuite } from "../hub/bench.ts";
+import { benchPreflight, defaultIo, runBench } from "./bench.ts";
+import { appendRecords, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { formatReport, summarize, formatTaskReport, summarizeByTask } from "../hub/report.ts";
 import { 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 { resolveColor } from "./console-state.ts";
+import { permissionBoundary, resolveColor } from "./console-state.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";
 
 /** `--since 7d|24h|<iso>` for export and report; everything when absent. */
 const since = (): number => {
@@ -51,62 +58,6 @@ const since = (): number => {
   return t;
 };
 
-const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory
-
-  ahub --project <path|id> <command>  select a repository or worktree explicitly
-  ahub projects [--json]         list registered projects and live status
-  ahub projects remove <id>      forget a stopped registration (keeps project files)
-  ahub status --all              show every registered project
-  ahub ui --all [--no-open]      open the unified project dashboard
-  ahub ui --all --stop           stop only the dashboard manager
-  ahub setup [--yes]            install or update the Claude Code channel plugin from this package, then run doctor
-  ahub init [--dry-run --json]   preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)
-  ahub up [--unattended] [--no-console]  start the daemon; interactive terminals enter console
-  ahub console [--panels] [--color=auto|always|never]  enter the human console, leaving the daemon running on exit
-  ahub upgrade --to <version> [--dry-run] [--yes]   review and upgrade running projects
-  ahub restart [--dry-run] [--yes]                 recover this project's runtime
-  ahub recovery status|resume|abort <operation-id> inspect, resume or cancel a preflight
-  ahub claude [--print-command] [args...]         launch Claude Code with the hub channel   [--unattended]
-  ahub codex [--print-command] [args...]          start the Codex adapter and attach the TUI [--unattended]
-  ahub kimi [--print-command] [--model <alias>]   start Kimi headless under ACP
-  ahub pi [--print-command] [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]  start Pi
-  ahub models setup|status|start|stop  prepare or inspect local Ollama MLX (legacy stop is explicit)
-  ahub local [--route <id> | --model <id>]
-                               start the hub-native worker on the self-hosted models (routing.toml)
-  ahub say [@peer ...] <text>   send as the console user (no @peer = broadcast); delivered at once,
-                               start the text with [STATUS] to let it batch or [FYI] for the record only
-  ahub pause|resume <peer>      hold a peer's deliveries in its queue / release them
-  ahub budget execution configure <config.json> | status [id] | disable <id>
-  ahub budget                   quota windows per peer, and who is paused until when
-  ahub budget set <peer> <0..1> [--resets-in 30m] [--window 5h|week]   feed a reading by hand (also: test the relay)
-  ahub budget resume <peer>     override a budget pause; readings are ignored for that peer until the window resets
-  ahub board [state | --ready]  the task board; --ready: proposed tasks with nothing left to wait for
-  ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--detail <text>]
-  ahub task show|escalate <id>  full task with history (PII text included) / hand it to the next peer in escalate_to
-  ahub task assign <id> <peer>  give a task to a peer yourself
-  ahub review <id> approved|changes_requested [note...] [--unmet <item>]...
-  ahub remember <text...>       save a note to the memory all agents share
-  ahub ask [--remember] <question...>   answer from the task board, shared memory and this run's log, with the ids it rests on
-  ahub route explain <id>       why a task went where it went
-  ahub route explain --class <c> <title...>   what would happen to such a task now
-  ahub ui [--no-open]           open the local dashboard (or print its one-time link)
-  ahub tail                     live stream of messages, states and permission requests
-  ahub permit <id> <option>     answer a permission request shown by tail ("deny" cancels)
-  ahub queue list [--peer <id>] [--json]       inspect durable deliveries
-  ahub queue show <delivery-id>               inspect one delivery and revision
-  ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>
-  ahub status | logs [-f] | doctor | kill
-  ahub export [--since 7d|<iso>]  structured events (events.jsonl) as JSON lines; never message bodies
-  ahub report [--since 7d|<iso>] [--by task] [--json]  turns, tokens, messages, overlaps and task events per period
-  ahub check-path <file> [--peer <id>]  other owners' open tasks that claim or changed a file
-  ahub check-path --hook        the same as a Claude Code PreToolUse hook (templates/claude-hooks.json); never blocks
-  ahub facts --hook             turn-free facts as a Claude Code PreToolUse, PostToolUse and Stop hook (issue #108); never blocks
-  ahub turns [peer] [--limit N]  recent turns and the files each changed (a git work tree only)
-  ahub undo <turn> [--yes] [--context]  put back the files a turn changed; refuses files changed since.
-                               Without --yes it only lists them; --context also drops a Codex turn from its conversation
-  ahub doctor --orphans [--kill]  list registrations whose project root is gone; --kill stops their
-                               daemons (SIGTERM, then SIGKILL) only after the process identity checks out`;
-
 const argv = process.argv.slice(2);
 let selector: string | undefined;
 if (argv[0] === "--project") {
@@ -114,7 +65,12 @@ if (argv[0] === "--project") {
   selector = argv.shift();
   if (!selector || selector.startsWith("--")) fail("--project needs a path or project ID");
 }
-const [cmd = "help", ...args] = argv;
+const [given = "help", ...rest] = argv;
+// `ahub <command> -h` alone asks for that command's help instead of running it. Elsewhere `-h` may be message text
+// (`ahub say try ls -h`), and claude and codex pass their arguments on to the agent.
+const asksHelp = (a: string | undefined) => a === "--help" || a === "-h";
+const cmd = asksHelp(given) || (given !== "claude" && given !== "codex" && rest.length === 1 && asksHelp(rest[0])) ? "help" : given;
+const args = cmd === "help" && given !== "help" && !asksHelp(given) ? [given] : rest;
 let selected: { root: string; stateDir: string };
 try {
   if (selector) {
@@ -146,6 +102,7 @@ function audit(outcome: "run" | "refused" | "invalid"): void {
 if (identity.role === "invalid") { audit("invalid"); fail(`${identity.reason}; use ahub console or a terminal with no agent markers`); }
 if (identity.role === "tools" && commandAccess === "console") { audit("refused"); fail(peerCommandRefusal(identity.peer, commandLabel)); }
 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}`); }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
@@ -157,6 +114,40 @@ function registeredProject(): Project {
   finally { registry.close(); }
 }
 
+/** #247: this project's registration for its research records; writing needs `research.enabled` in its config. */
+function researchProject(writes = true): Project {
+  const project = matchingProject() ?? fail("this project has no hub registration; run ahub up here once first");
+  if (writes && !loadConfig(cwd).research.enabled) fail('research records are off for this project; set "research": { "enabled": true } in .agenthub/config.json first');
+  return project;
+}
+
+/** The registration of exactly this root and state directory, the only one kill and reset act on; never registers. */
+function matchingProject(): Project | undefined {
+  const registry = new Registry();
+  try { return registry.list().find((p) => p.root === cwd && p.stateDir === stateDir); }
+  finally { registry.close(); }
+}
+const hubManifest = () => !!readControl(stateDir) || existsSync(join(stateDir, "hub.pid"));
+/** A reset is never part of an upgrade or recovery: any operation holding the machine's lock refuses it, whatever
+ *  AGENTHUB_RECOVERY_OPERATION says (assertLifecycleAvailable lets that operation's own processes through). */
+function resetLockFree(): void {
+  const owner = recoveryLock();
+  if (owner) throw new Error(`${activeOperation(owner)}; nothing was changed`);
+}
+/** A manifest whose daemon is alive or uncertain, by inspectProject's rule; a crashed daemon's leftovers do not count. */
+function liveManifest(): boolean {
+  const control = readControl(stateDir);
+  if (control && processLiveness(control.pid, control.pidSignature) !== "gone") return true;
+  // A signed manifest is this release's daemon, which writes no hub.pid: one beside it is an older run's leftover.
+  if (control?.pidSignature) return false;
+  let text: string;
+  // Only daemons up to 0.12.20 wrote hub.pid (#226): an unsigned legacy record.
+  try { text = readFileSync(join(stateDir, "hub.pid"), "utf8").trim(); } catch { return false; }
+  if (/^\d+$/.test(text)) return processLiveness(Number(text)) !== "gone";
+  // Empty or garbled: beside a dead daemon's status it is that daemon's leftover too; alone it proves nothing.
+  return !control;
+}
+
 async function healthy(): Promise<boolean> {
   let hub: ControlClient | undefined;
   try { hub = await connect(); const reply = await hub.request({ t: "status" }, 3000); return reply.status?.cwd === cwd; }
@@ -242,17 +233,16 @@ function hubDaemonCommand(pid: number, root: string): string | undefined {
 
 /** Live PID candidates for a registration whose project root is gone: the claim, the manifest, the legacy pid file. */
 function orphanPids(project: Project): number[] {
+  // #226: a recorded pid counts only while its signature (when one was recorded) still names its process.
   const candidates = new Set<number>();
-  if (typeof project.pid === "number") candidates.add(project.pid);
+  if (typeof project.pid === "number" && processLiveness(project.pid, project.pidSignature) === "live") candidates.add(project.pid);
   const control = readControl(project.stateDir);
-  if (control && Number.isSafeInteger(control.pid)) candidates.add(control.pid!);
+  if (control && Number.isSafeInteger(control.pid) && processLiveness(control.pid, control.pidSignature) === "live") candidates.add(control.pid!);
   try {
     const pid = Number(readFileSync(join(project.stateDir, "hub.pid"), "utf8").trim());
     if (Number.isSafeInteger(pid) && pid > 0) candidates.add(pid);
   } catch { /* no legacy pid file */ }
-  return [...candidates].filter((pid) => {
-    try { process.kill(pid, 0); return true; } catch { return false; }
-  });
+  return [...candidates].filter((pid) => processLiveness(pid) === "live");
 }
 
 const processGone = (pid: number): boolean => !processCommandLine(pid);
@@ -353,9 +343,10 @@ function spawnRecovery(operation: RecoveryOperation): void {
   const child = spawn(process.execPath, [join(operation.sourceRoot, "src/cli/main.js"), "recovery-run", operation.id], {
     cwd, detached: true, stdio: "ignore", env: { ...process.env, AGENTHUB_RECOVERY_OPERATION: operation.id },
   });
-  child.on("error", () => console.error(`runner launch failed; use ahub recovery resume ${operation.id}`));
+  child.on("error", () => console.error(`runner launch failed; use ${recoveryCommand(operation, "resume")}`));
   child.unref();
-  console.log(`Recovery operation ${operation.id} scheduled.\nahub recovery status ${operation.id}`);
+  // #215: the operation's own coordinator, which has every recovery command; the global ahub may be older mid-upgrade.
+  console.log(`Recovery operation ${operation.id} scheduled.\n${recoveryCommand(operation, "status")}`);
 }
 
 async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
@@ -365,8 +356,13 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   if (kind === "upgrade" && selector) fail("upgrade changes the shared package/plugin; omit --project to review all affected running projects");
   const plan = await makeUpgradePlan(kind, one["--to"] ?? VERSION, kind === "restart" ? cwd : undefined);
   console.log(JSON.stringify(plan, null, 2));
+  // #206: name every blocker and reconnect-only session on stderr, not only inside the JSON above.
+  for (const p of plan.projects) for (const peer of p.reconnectOnly ?? []) console.error(`ahub: ${p.project.id}: ${peer} is reconnect-only (unmanaged session): its plugin reattaches to the new hub; no terminal is closed or relaunched`);
+  for (const p of plan.projects) for (const peer of p.freshStart ?? []) console.error(`ahub: ${p.project.id}: ${peer} restarts as a new session: its thread has no rollout and the hub recorded no turn on it, so nothing is lost`);
+  const blockers = [...plan.blockers, ...plan.projects.flatMap((p) => p.blockers.map((b) => `${p.project.id}: ${b}`))];
+  for (const blocker of blockers) console.error(`ahub: blocker: ${blocker}`);
   if (args.includes("--dry-run")) return;
-  if (plan.blockers.length || plan.projects.some((p) => p.blockers.length)) fail("plan has blockers; no runtime was changed");
+  if (blockers.length) fail("plan has blockers; no runtime was changed");
   assertLifecycleAvailable();
   if (!args.includes("--yes")) {
     if (!process.stdin.isTTY) fail("review --dry-run and use --yes in non-interactive sessions");
@@ -386,12 +382,33 @@ const commands: Record<string, () => Promise<void> | void> = {
   upgrade: () => upgrade("upgrade"),
   restart: () => upgrade("restart"),
   recovery: async () => {
-    const [action, id] = args;
-    if (args.length !== 2 || !id || !["status", "resume", "abort"].includes(action ?? "")) fail("usage: ahub recovery status|resume|abort <operation-id>");
+    const [action, id, ...rest] = args;
+    const usage = "usage: ahub recovery status|resume|abort <operation-id> | ahub recovery dispose <operation-id> --fresh-session <peer>|--stop-and-archive --reason <text>";
+    if (!id || !["status", "resume", "abort", "dispose"].includes(action ?? "") || (action !== "dispose" && rest.length)) fail(usage);
     const operation = readOperation<RecoveryOperation>(id);
-    if (action === "status") console.log(JSON.stringify(publicOperation(operation), null, 2));
+    const runner = recoveryRunner(id);
+    if (action === "status") {
+      // #215: abort and resume are offered by what the open sources show, read as the runner's errors read them.
+      const live = runner ? {} : await liveProjects(operation, makeRecoveryDriver().inspect);
+      console.log(JSON.stringify(publicOperation(operation, runner, live), null, 2));
+    }
     else if (action === "abort") { await abortRecovery(id, makeRecoveryDriver()); console.log("preflight cancelled; no committed transition was rolled back"); }
+    else if (action === "dispose") {
+      // #215: human-only (the identity gate refuses agent shells); the reason is kept in the operation's audit.
+      const { one, rest: flags } = takeFlags(rest, ["--fresh-session", "--reason"], []);
+      const stop = flags.length === 1 && flags[0] === "--stop-and-archive";
+      const reason = one["--reason"]?.trim() ?? "";
+      if (!reason || reason.length > 500 || (flags.length && !stop) || stop === !!one["--fresh-session"]) fail(usage);
+      const result = await disposeRecovery(id, stop ? { stop: true } : { fresh: one["--fresh-session"]! }, reason, makeRecoveryDriver());
+      if (!stop) { console.log(`${one["--fresh-session"]}: a fresh session is accepted and the lost one is recorded; resuming`); return spawnRecovery(result); }
+      console.log(JSON.stringify(publicOperation(result), null, 2));
+      console.log(`${result.plan.kind} abandoned, not completed; the recovery lock is released. A project whose target ran starts again with that version's CLI.`);
+    }
     else if (["completed", "cancelled"].includes(operation.phase)) console.log(`recovery is already ${operation.phase}`);
+    // #215: an operation being abandoned is never resumed, whichever coordinator started it (an older one would).
+    else if (operation.disposition) fail(`a stop-and-archive of this operation is partway; nothing was resumed; ${nextActionsText(operation, await liveProjects(operation, makeRecoveryDriver().inspect))}`);
+    else if (runner === "unknown") console.log(`whether a runner holds this operation could not be read; nothing was started; ${recoveryCommand(operation, "status")}`);
+    else if (runner) console.log(`runner ${runner} is still working on this operation; ${recoveryCommand(operation, "status")}`);
     else spawnRecovery(operation);
   },
   "recovery-run": async () => {
@@ -399,7 +416,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     const result = await runRecovery(args[0]!, makeRecoveryDriver());
     if (result.phase !== "completed") process.exitCode = 1;
   },
-  help: () => console.log(USAGE),
+  help: () => {
+    const color = resolveColor(undefined, { isTTY: !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
+    const topic = asksHelp(args[0]) ? undefined : args[0];
+    const text = renderHelp(process.stdout.columns ?? 80, color, topic);
+    if (!text) fail(`unknown command "${topic}"; run ahub help`);
+    console.log(text);
+  },
   "--version": () => console.log(VERSION),
   version: () => console.log(VERSION),
 
@@ -517,10 +540,6 @@ const commands: Record<string, () => Promise<void> | void> = {
       process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
       const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
       if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
-      // Native hook identity exists in an ordinary terminal too; this is not an Orca recovery record.
-      const file = join(stateDir, "claude-launch.json");
-      writeFileSync(`${file}.tmp`, JSON.stringify({ instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID }), { mode: 0o600 });
-      chmodSync(`${file}.tmp`, 0o600); renameSync(`${file}.tmp`, file);
     }
     // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
     // project local, then project, then user.
@@ -534,9 +553,26 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     // Turn-free facts and opted-in task sweeps share native PreToolUse/PostToolUse/Stop observations.
     const facts = claudeObservationHooks(projectConfig(), { script: join(import.meta.dir, "facts-hook.ts"), stateDir });
+    let previousLaunch: unknown;
+    try { previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")); } catch { /* no previous managed launch */ }
     const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
-    if (launch.warning) console.error(launch.warning);
-    exec(launch.cmd, launch.args, "claude");
+    let result: ReturnType<typeof spawnSync>;
+    try {
+      if (control?.instanceId) {
+        // Publish only the final launch's installed hook and effective permission flags.
+        const file = join(stateDir, "claude-launch.json");
+        writeFileSync(`${file}.tmp`, JSON.stringify({ instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true }), { mode: 0o600 });
+        chmodSync(`${file}.tmp`, 0o600); renameSync(`${file}.tmp`, file);
+        cleanupStaleClaudeSettings(stateDir, previousLaunch);
+      }
+      if (launch.warning) console.error(launch.warning);
+      const env = nativeLaunchEnv("claude", childEnv());
+      result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+    } finally {
+      cleanupClaudeSettings(stateDir, launch.settingsFile);
+    }
+    if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
+    process.exit(result.status ?? 1);
   },
 
   codex: async () => {
@@ -546,12 +582,18 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     assertLifecycleAvailable();
     const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: "pending" }); // refuse bad flags before starting anything
+    // #215: a launch by a recovery operation records itself before the hub round trip, so the coordinator never takes
+    // a launcher still starting for one that never ran. An ordinary launch records only once the hub accepted it: a
+    // refused start must not replace the record of a Codex already running here (one row per peer and instance).
+    const recovering = !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock(); // not an id a restored session inherited
+    const before = readControl(stateDir);
+    if (recovering && before?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, before.instanceId);
     const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "codex", operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+    const res = await hub.request({ t: "start", peer: "codex", args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     hub.close();
     if (!res.ok) fail(res.error);
     const control = readControl(stateDir);
-    if (control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
+    if (!recovering && control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
     const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
     if (launch0.warning) console.error(launch0.warning);
     exec(launch.cmd, launch.args, "codex");
@@ -577,6 +619,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
     }
     const options = piFlags();
+    // #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();
+    const before = readControl(stateDir);
+    if (recovering && before?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, before.instanceId);
     const hub = await connect();
     const res = await hub.request({ t: "start", peer: "pi", args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     hub.close();
@@ -588,7 +635,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
       delete launchEnv.AGENTHUB_UNATTENDED;
       const control = readControl(stateDir);
-      if (control?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, control.instanceId);
+      if (!recovering && control?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, control.instanceId);
       return execWithEnv(launch.cmd, launch.args, launchEnv);
     }
     console.log(res.already ? "pi is already attached" : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
@@ -747,6 +794,17 @@ const commands: Record<string, () => Promise<void> | void> = {
     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 === "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"], []);
+      const id = Number(positional[0]), label = positional[1] as Label;
+      if (positional.length !== 2 || !/^[1-9]\d*$/.test(positional[0]!) || !Number.isSafeInteger(id) || !(LABELS as readonly string[]).includes(label)) fail(`usage: ahub task label <id> ${LABELS.join("|")} [--created <time from ahub research export>]`);
+      const project = researchProject();
+      let record: TaskRecord;
+      try { record = labelTarget(readStores(project.id), readEvents(join(stateDir, "events.jsonl")), id, one["--created"]); } catch (error) { fail((error as Error).message); }
+      appendRecords(project.id, [{ schema: RESEARCH_SCHEMA, kind: "label", project: projectKey(project.id), task: id, createdAt: record!.createdAt!, label, at: new Date().toISOString() }]);
+      return console.log(`task #${id} (approved ${record!.approvedAt}) labelled ${label} in the research records`);
+    }
     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.
@@ -795,6 +853,24 @@ const commands: Record<string, () => Promise<void> | void> = {
   pause: () => hold("pause"),
   resume: () => hold("resume"),
 
+  permission: async () => {
+    const positional = args.filter(arg => arg !== "--yes");
+    const [peer, mode] = positional;
+    if (positional.length > 2 || positional.some(arg => arg.startsWith("--")) || (mode !== undefined && !isPermissionMode(mode))) fail("usage: ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]");
+    if (mode === "never-ask" && !args.includes("--yes")) fail("never-ask requires --yes; nothing was changed");
+    if (mode === "never-ask" && peer) console.error(`never-ask: ${permissionBoundary(peer)}; approval prompts are disabled`);
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "permission", ...(peer ? { peer } : {}), ...(mode ? { mode, confirmed: args.includes("--yes") } : {}) }, 35_000);
+      if (reply.ok === false) {
+        const error = String(reply.error ?? "permission request refused");
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "permission"/i.test(error) ? `${error}; upgrade the running hub to use ahub permission` : error);
+      }
+      if (reply.peers) for (const [id, value] of Object.entries(reply.peers)) console.log(`${id}: ${value}`);
+      else console.log(`${peer}: ${reply.permissionMode}`);
+    } finally { hub.close(); }
+  },
+
   permit: async () => {
     const [id, option] = args;
     if (!id || !option) fail("usage: ahub permit <id> <option|deny>");
@@ -812,6 +888,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     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() }));
@@ -827,6 +904,89 @@ const commands: Record<string, () => Promise<void> | void> = {
   export: () => {
     for (const e of readEvents(join(stateDir, "events.jsonl"), since())) console.log(JSON.stringify(e));
   },
+  bench: async () => {
+    // #251: benchmark suites run against the peers attached here, and their comparison across arms.
+    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 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]");
+      }
+      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));
+        return console.log(formatBenchReport(benchReport(readRuns().filter((r) => r.header.run === run))).join("\n"));
+      } finally { process.off("SIGINT", stop); }
+    }
+    const runs = readRuns();
+    if (sub === undefined || sub === "list") return console.log(json ? JSON.stringify(runs.map(runSummary), null, 2) : formatRuns(runs).join("\n"));
+    if (sub === "status") {
+      const live = runs.filter((r) => r.state === "running" || r.state === "unknown");
+      return console.log(json ? JSON.stringify(live.map(runSummary), null, 2) : live.length ? formatRuns(live).join("\n") : "no benchmark run is running");
+    }
+    if (sub === "report") {
+      const run = runs.find((r) => r.header.run === rest[0]) ?? fail(`usage: ahub bench report <run> (ahub bench list shows the runs)`);
+      const r = benchReport([run]);
+      return console.log(json ? JSON.stringify(r, null, 2) : formatBenchReport(r).join("\n"));
+    }
+    if (sub === "compare") {
+      const mixed = rest.includes("--mixed");
+      const { one, rest: picks } = takeFlags(rest.filter((a) => a !== "--mixed"), ["--suite"], []);
+      const scoped = one["--suite"] ? runs.filter((r) => r.header.suite === one["--suite"]) : runs;
+      const groups = picks.map((pick) => {
+        const byRun = scoped.filter((r) => r.header.run === pick);
+        const chosen = byRun.length ? byRun : armRuns(scoped, pick);
+        if (!chosen.length) fail(`no run, or arm with a run that is over, named ${pick}${one["--suite"] ? ` in suite ${one["--suite"]}` : ""}`);
+        return { arm: byRun.length ? `${pick} [${byRun[0]!.header.arm}]` : pick, runs: chosen };
+      });
+      if (groups.length < 2) fail("usage: ahub bench compare <run|arm> <run|arm>... [--suite <name>] [--mixed] [--json]");
+      const differs = sameSuite(groups);
+      if (differs && !mixed) fail(`${differs}; compare runs of one suite file (name runs by id, or --suite when the names differ), or pass --mixed to compare them anyway`);
+      const c = benchCompare(groups);
+      return console.log(json ? JSON.stringify(c, null, 2) : formatCompare(c).join("\n"));
+    }
+    if (sub === "export") {
+      const format = rest.includes("--format") ? rest[rest.indexOf("--format") + 1] : "jsonl";
+      if (format !== "jsonl" && format !== "csv") fail("--format takes jsonl or csv");
+      if (format === "csv") return void process.stdout.write(benchCsv(runs));
+      for (const r of runs) for (const record of [r.header, ...r.attempts, ...(r.end ? [r.end] : [])]) console.log(JSON.stringify(record));
+      return;
+    }
+    fail("usage: ahub bench run|list|status|report|compare|export (ahub help bench)");
+  },
+  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++) {
+      if (!flags.has(args[i]!)) fail(`ahub research: unknown argument ${args[i]} (another project: ahub --project <dir> research)`);
+      if (valued.has(args[i]!)) i++;
+    }
+    if (sub === "backfill") {
+      const project = researchProject();
+      const written = appendRecords(project.id, taskRecords(readEvents(join(stateDir, "events.jsonl")), project.id, { version: VERSION, source: "backfill" }));
+      return console.log(`${written} research record${written === 1 ? "" : "s"} written from this project's events`);
+    }
+    const all = args.includes("--all");
+    const records = readStores(all ? undefined : researchProject(false).id);
+    const from = since();
+    if (sub === "export") {
+      const format = args[args.indexOf("--format") + 1] ?? "jsonl";
+      if (args.includes("--format") && !["jsonl", "csv"].includes(format)) fail("--format takes jsonl or csv");
+      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");
+    const r = researchReport(records, from);
+    console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatResearch(r).join("\n"));
+  },
   report: () => {
     const by = args.indexOf("--by");
     if (by >= 0 && args[by + 1] !== "task") return fail("--by takes task");
@@ -943,18 +1103,95 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   kill: async () => {
-    const registry = new Registry();
-    let project: Project | undefined;
-    try { project = registry.list().find((p) => p.root === cwd && p.stateDir === stateDir); }
-    finally { registry.close(); }
+    const project = matchingProject();
     if (!project) {
-      if (!readControl(stateDir) && !existsSync(join(stateDir, "hub.pid"))) return console.log("hub is not running");
+      if (!hubManifest()) return console.log("hub is not running");
       fail("hub has no matching registration; use its matching CLI to stop it before upgrading");
     }
     await stopProject(project);
     console.log("hub stopped");
   },
 
+  reset: async () => {
+    if (args.some((a) => !["--all", "--yes"].includes(a))) fail("usage: ahub reset [--all] [--yes]");
+    const all = args.includes("--all");
+    resetLockFree();
+    // Registered with another state directory: `ahub up` here would register the default one and orphan that state.
+    const elsewhere = registeredProjects().find((p) => p.root === cwd);
+    const project = matchingProject() ?? fail(hubManifest() ? "hub has no matching registration; use its matching CLI to stop it; nothing was changed"
+      : elsewhere ? `this project is registered with the state directory ${elsewhere.stateDir}; run ahub --project ${elsewhere.id} reset; nothing was changed`
+        : "no registration matches this project and state directory; nothing was changed (ahub up registers it)");
+    if (!existsSync(stateDir)) return console.log("no state directory; nothing to reset");
+    // A state directory elsewhere (AGENTHUB_STATE_DIR, or a symlink) would cross file systems or pull outside state
+    // into the project tree.
+    if (all && stateDir !== join(cwd, ".agenthub", "state")) fail(`--all moves only ${join(cwd, ".agenthub", "state")}; this project's state is in ${stateDir}: stop the hub and archive it by hand; nothing was changed`);
+    const unsafe = all ? archiveProblem(cwd, stateDir) : undefined;
+    if (unsafe) fail(`${unsafe}; nothing was changed`);
+    const live = await inspectProject(project);
+    if (!["stopped", "running", "stopping"].includes(live.state)) fail(`${live.error ?? `hub is ${live.state}`}; nothing was changed`);
+    const recovery = live.status?.recovery as { operationId?: string; phase?: string } | undefined;
+    if (recovery?.operationId && recovery.phase !== "released") fail(`recovery operation ${recovery.operationId} is open in this hub; nothing was changed`);
+    const kept = "kept: the board, logs and audit, recovery records, execution budgets, configuration and pi-sessions/";
+    const memory = "claude-mem is not touched: notes saved with hub_remember stay in shared memory";
+    if (!args.includes("--yes")) {
+      // Planned only for the dry run: `--all --yes` archives a state directory it cannot read as it is.
+      let plan: ResetPlan | undefined, unread: string | undefined;
+      try { plan = planReset(stateDir, project.id); }
+      catch (error) {
+        if (!all) fail(`cannot read the state (${failureText(error)}); nothing was changed${damagedState(error) ? "; ahub reset --all --yes archives it as it is" : ""}`);
+        unread = failureText(error);
+      }
+      console.log(`ahub reset${all ? " --all" : ""}, dry run: the hub is ${live.state}${live.state === "stopped" ? "" : "; --yes stops it first, as ahub kill does"}`);
+      if (all) {
+        console.log(`  move ${stateDir}${plan ? ` (${plan.entries} entries)` : ""} to ${join(cwd, ".agenthub", "archive")}/state-<UTC time>/ (0700), then start an empty state directory holding only project.json; project ${project.id} keeps its id and registration`);
+        console.log(unread ? `  could not read the state (${unread}); it is archived as it is` : "  archived as they are:");
+      } else console.log('  settle as discard with reason "reset", clear and drop:');
+      for (const line of plan ? resetLines(plan) : []) console.log(`    ${line}`);
+      const stale = live.state === "stopped" && !all ? MANIFEST.filter((name) => existsSync(join(stateDir, name))) : [];
+      if (stale.length) console.log(`  remove the manifest a hub left when it did not stop cleanly: ${stale.join(", ")}`);
+      console.log(`  ${all ? ".agenthub/config.json, config.local.json and routing.toml are outside the state directory and stay" : kept}`);
+      console.log(`  ${memory}`);
+      return console.log("nothing was changed; add --yes to apply");
+    }
+    await stopProject(project);
+    if (live.state !== "stopped") console.log("hub stopped");
+    // Hold the claim a daemon takes to run: a hub started after the stop holds it (refused here), and none can start
+    // while the reset acts. A reset that dies leaves a claim with a dead pid, which the next start takes over.
+    const registry = new Registry();
+    // The prefix tells a concurrent reset's claim from a daemon's.
+    const claim = `reset-${randomUUID()}`;
+    try {
+      if (!registry.claim(project.id, claim, process.pid, processSignature(process.pid))) {
+        const holder = registry.get(project.id);
+        throw new Error(holder?.instanceId?.startsWith("reset-") ? `another ahub reset of this project is running (pid ${holder.pid}); nothing was reset` : "a hub started after the stop; nothing was reset, run ahub reset again");
+      }
+      if (liveManifest()) throw new Error("a hub started after the stop; nothing was reset, run ahub reset again");
+      // An upgrade or recovery that took the machine's lock after the first check must not run beside the reset.
+      resetLockFree();
+      if (all) {
+        let archived: string;
+        try { archived = archiveState(cwd, stateDir); }
+        catch (error) { throw new Error(`the hub is stopped; nothing was moved: ${failureText(error)}`); }
+        console.log(`moved the state directory to ${archived}`);
+        try { startState(stateDir, archived); }
+        catch (error) { throw new Error(`${(error as Error).message}; the state directory is archived at ${archived}: create ${stateDir} (0700) and copy project.json from the archive`); }
+        console.log(`the new state directory holds only project.json (to restore: ahub kill, move ${stateDir} into ${join(cwd, ".agenthub", "archive")}/, then move the archive back to ${stateDir})`);
+      } else {
+        let result: ReturnType<typeof resetRuntime>;
+        try { result = resetRuntime(stateDir, project); }
+        catch (error) {
+          throw new Error(`${failureText(error)}; the hub is stopped and the reset is incomplete: ${damagedState(error) ? "the state cannot be read, so a rerun fails the same way; ahub reset --all --yes archives it as it is" : "run ahub reset --yes again to finish it"}`);
+        }
+        console.log(`settled ${result.settled.length} deliveries as discard with reason "reset"`);
+        for (const line of resetLines(result.plan).slice(1)) console.log(`cleared ${line}`);
+        if (result.stale.length) console.log(`removed the manifest a hub left when it did not stop cleanly: ${result.stale.join(", ")}`);
+        console.log(kept);
+      }
+    } finally { registry.release(project.id, claim); registry.close(); }
+    console.log(memory);
+    console.log("Claude Code sessions attached to this hub lost their hub session: relaunch them with ahub claude");
+  },
+
   doctor: async () => {
     if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"));
     const version = (bin: string) => {
@@ -1040,7 +1277,7 @@ async function runConductorCommand(): Promise<void> {
   }
   console.log(await taskOp(op, input));
 }
-const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : commands[cmd] ?? (() => fail(`unknown command "${cmd}"\n\n${USAGE}`));
+const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? (() => fail(`unknown command "${cmd}"; run ahub help`));
 try {
   await run();
 } catch (e) {