@staix/agent-hub 0.12.19 → 0.12.20

package/src/cli/main.ts

@@ -10,7 +10,7 @@ import { loadConfig } from "../hub/daemon.ts";
 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 { inspectProject, processAlive, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
@@ -22,9 +22,9 @@ 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";
@@ -40,7 +40,9 @@ import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, peerCommandRef
 import { recordCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { 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 +53,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 +60,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) {
@@ -157,6 +108,30 @@ function registeredProject(): Project {
   finally { registry.close(); }
 }
 
+/** 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 && processAlive(control.pid) !== false) return true;
+  let text: string;
+  try { text = readFileSync(join(stateDir, "hub.pid"), "utf8").trim(); } catch { return false; }
+  if (/^\d+$/.test(text)) return processAlive(Number(text)) !== false;
+  // 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; }
@@ -353,9 +328,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 +341,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 +367,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 +401,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),
 
@@ -546,12 +554,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 });
     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 +591,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 +607,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 "..."');
@@ -943,18 +962,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)) {
+        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 +1136,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) {

package/src/cli/preview.ts

@@ -71,6 +71,7 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi", raw: s
     unresolved.push({ field: "bridge/relay endpoints and owner credentials", reason: "assigned at runtime; preview does not bind a server or start a model" });
     if (!value("--session-id") && !value("--session-file")) unresolved.push({ field: "sessionId", reason: "new native session identity is not allocated by preview" });
   }
+  if (tool === "claude") envNames.push("AGENTHUB_CHANNEL");
   if (tool === "claude" || tool === "codex") {
     envNames.push("AGENTHUB_INSTANCE_ID", "AGENTHUB_LAUNCH_ID");
     unresolved.push({ field: "env.AGENTHUB_INSTANCE_ID", reason: tool === "claude" ? "injected when an existing daemon instance is read at launch; preview does not read runtime state" : "injected when a verified Orca terminal launch is recorded against the daemon; preview does not record it" });

package/src/cli/reset.ts

@@ -0,0 +1,194 @@
+import { constants, Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Bus } from "../hub/bus.ts";
+import { DeliveryJournal } from "../hub/delivery-journal.ts";
+import type { Project } from "../hub/registry.ts";
+
+/** Agent session resume pointers. `pi-sessions/` holds Pi transcripts, history rather than pointers, and stays. */
+export const SESSION_POINTERS = ["sessions.json", "claude-session.json", "claude-context.json"];
+/** What a running daemon publishes; a daemon that did not stop cleanly (crash, SIGKILL, forced exit) leaves it. */
+export const MANIFEST = ["status.json", "control-token", "hub.pid"];
+
+/** A state the reset cannot read the same way twice: rerunning fails alike, while `--all` archives it as it is. */
+export function damagedState(error: unknown): boolean {
+  return error instanceof SyntaxError || /invalid delivery journal|not a database|malformed|corrupt/i.test((error as Error)?.message ?? "");
+}
+
+/**
+ * What may be printed about a failure: a parser's message can quote the data it choked on (envelope bodies, task text),
+ * so JSON and SQLite errors are named by class and code only. Every other message is written by the hub or the system.
+ */
+export function failureText(error: unknown): string {
+  const e = error as NodeJS.ErrnoException;
+  if (e instanceof SyntaxError || e?.name === "SQLiteError") return `${[e.name, e.code].filter(Boolean).join(" ")} reading hub.db`;
+  return e?.message ?? String(error);
+}
+
+/** Ids and peer names only: a reset never prints task or message text (#214). */
+export interface ResetPlan {
+  queued: string[];
+  needsReview: string[];
+  /** Dispatching or accepted: the journal holds them as needs_review once the hub has stopped. */
+  inFlight: string[];
+  manualHolds: string[];
+  budgetPauses: string[];
+  conductorHolds: string[];
+  sessionPointers: string[];
+  entries: number;
+}
+
+const isList = (value: unknown, item: (v: unknown) => boolean) => Array.isArray(value) && value.every(item);
+const isText = (v: unknown) => typeof v === "string";
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const isEnvelope = (v: unknown) => isObject(v) && typeof v.id === "string";
+/** Valid JSON of the wrong shape is damage as well: the journal refuses it on every open, so the message says so. */
+const shaped = (ok: boolean, what: string) => { if (!ok) throw new Error(`invalid delivery journal: ${what} has the wrong shape`); };
+
+/** What a reset would act on, read from the state directory without changing it (hub.db opened read-only). */
+export function planReset(stateDir: string, projectId: string): ResetPlan {
+  const plan: ResetPlan = { queued: [], needsReview: [], inFlight: [], manualHolds: [], budgetPauses: [], conductorHolds: [],
+    sessionPointers: SESSION_POINTERS.filter((name) => existsSync(join(stateDir, name))), entries: existsSync(stateDir) ? readdirSync(stateDir).length : 0 };
+  const file = join(stateDir, "hub.db");
+  if (!existsSync(file)) return plan;
+  // A read-only open of a WAL database creates hub.db-wal and -shm when the last writer's close removed them (Linux),
+  // and fails without them on macOS. Without them no writer is mid-transaction, so `immutable` reads hub.db alone and
+  // writes nothing. ponytail: a -wal left without its -shm (deleted by hand) is ignored then, and commits still in
+  // it go unlisted; open plainly in that corner if it ever matters. SQLITE_OPEN_URI is passed because Linux builds do
+  // not parse `file:` names by default (the name then fails as a plain path).
+  const quiet = !existsSync(`${file}-wal`) || !existsSync(`${file}-shm`);
+  const db = quiet ? new Database(`file:${file.replace(/[%?#]/g, (c) => `%${c.charCodeAt(0).toString(16)}`)}?immutable=1`, constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI) : new Database(file, { readonly: true });
+  try {
+    const has = (table: string) => !!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+    const peers = (table: string) => has(table) ? (db.query(`SELECT peer FROM ${table} ORDER BY peer`).all() as { peer: string }[]).map((row) => row.peer) : [];
+    plan.budgetPauses = peers("budget_pauses");
+    plan.conductorHolds = peers("conductor_holds");
+    if (!has("deliveries")) return plan;
+    const rows = db.query("SELECT id, peer, state, originals FROM deliveries WHERE project_id = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY created_at, id").all(projectId) as { id: string; peer: string; state: string; originals: string }[];
+    for (const row of rows) (row.state === "queued" ? plan.queued : row.state === "needs_review" ? plan.needsReview : plan.inFlight).push(row.id);
+    const meta = db.query("SELECT bus_snapshot, manual_paused FROM delivery_meta WHERE project_id = ?").get(projectId) as { bus_snapshot: string; manual_paused: string } | null;
+    const bus: unknown = JSON.parse(meta?.bus_snapshot || "{}"), manual: unknown = JSON.parse(meta?.manual_paused || "[]");
+    shaped(isList(manual, isText), "manual_paused");
+    shaped(isObject(bus) && (bus.manualPaused === undefined || isList(bus.manualPaused, isText)) && (bus.queues === undefined || (isObject(bus.queues) && Object.values(bus.queues).every((queue) => isList(queue, isEnvelope)))), "bus_snapshot");
+    const { queues = {}, manualPaused = [] } = bus as { queues?: Record<string, { id: string }[]>; manualPaused?: string[] };
+    plan.manualHolds = [...new Set([...manual as string[], ...manualPaused])].sort();
+    // As Bus.queueList: a queued envelope that no open row stands for is listed as q:<peer>:<envelope id>.
+    // ponytail: the rule is copied so the dry run never opens the journal for writing; the reset tests compare the
+    // listed ids with the settled ones. Share one pure helper with queueList if that rule changes.
+    const recorded = new Set(rows.flatMap((row) => {
+      const originals: unknown = JSON.parse(row.originals);
+      shaped(isList(originals, isEnvelope), `delivery ${row.id} originals`);
+      return (originals as { id: string }[]).map((env) => `${row.peer}:${env.id}`);
+    }));
+    for (const [peer, queue] of Object.entries(queues)) for (const env of queue) if (!recorded.has(`${peer}:${env.id}`)) plan.queued.push(`q:${peer}:${env.id}`);
+  } finally { db.close(); }
+  return plan;
+}
+
+const named = (label: string, items: string[]) => `${label} ${items.length}${items.length ? `: ${items.join(", ")}` : ""}`;
+/** The runtime scope, ids and counts: the deliveries first, then the holds and pointers. */
+export function resetLines(plan: ResetPlan): string[] {
+  return [
+    `deliveries: ${named("queued", plan.queued)}; ${named("needs_review", plan.needsReview)}; ${named("in flight", plan.inFlight)}`,
+    named("manual holds", plan.manualHolds),
+    named("budget pauses", plan.budgetPauses),
+    named("conductor holds", plan.conductorHolds),
+    named("session pointers", plan.sessionPointers),
+  ];
+}
+
+/**
+ * Runtime reset of a stopped hub: every queued and needs_review delivery is discarded with reason `reset` through
+ * the journal (one resolution_history entry each), manual, budget and conductor holds are cleared and the session
+ * pointers dropped, with a crashed run's manifest. The board, logs, audit, recovery records and execution budgets stay.
+ */
+export function resetRuntime(stateDir: string, project: Project): { settled: string[]; plan: ResetPlan; stale: string[] } {
+  const file = join(stateDir, "hub.db");
+  const plan = planReset(stateDir, project.id);
+  const settled: string[] = [];
+  if (existsSync(file)) {
+    // Opening the journal as a new instance turns dispatching and accepted rows of the stopped run into needs_review.
+    const journal = new DeliveryJournal({ file, projectRoot: project.root, projectId: project.id, instanceId: randomUUID() });
+    const bus = new Bus({ journal });
+    try {
+      for (const { id } of bus.queueList().filter((row) => row.state === "queued" || row.state === "needs_review")) {
+        // Read again each time: a queue entry's revision is the journal's, and every resolution moves it on.
+        bus.resolveDelivery(id, bus.queueShow(id)!.revision, "discard", "reset");
+        settled.push(id);
+      }
+      bus.setManualPaused([]);
+    } finally { bus.closeJournal(); }
+    const db = new Database(file);
+    try {
+      db.transaction(() => {
+        for (const table of ["budget_pauses", "conductor_holds"]) {
+          if (db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) db.run(`DELETE FROM ${table}`);
+        }
+      })();
+    } finally { db.close(); }
+  }
+  for (const name of SESSION_POINTERS) rmSync(join(stateDir, name), { force: true });
+  // The caller has checked that no daemon behind these is alive or uncertain: they are a crashed run's leftovers.
+  const stale = MANIFEST.filter((name) => existsSync(join(stateDir, name)));
+  for (const name of stale) rmSync(join(stateDir, name), { force: true });
+  return { settled, plan, stale };
+}
+
+/**
+ * Why `--all` must not move this state directory into `<root>/.agenthub/archive`, or undefined. An agent with write
+ * access to the project, or a repository that commits `.agenthub/`, could otherwise turn the archive into a symlink and
+ * have hub.db (PII) moved out of the project, or the `.gitignore` into one that truncates any file it names.
+ */
+export function archiveProblem(root: string, stateDir: string): string | undefined {
+  const uid = process.getuid?.();
+  const own = (path: string) => { const st = lstatSync(path); return st.isDirectory() && (uid === undefined || st.uid === uid); };
+  for (const dir of [join(root, ".agenthub"), stateDir]) if (!own(dir)) return `${dir} is not a directory of this user`;
+  const archive = join(root, ".agenthub", "archive");
+  if (lstatSync(archive, { throwIfNoEntry: false }) && !own(archive)) return `${archive} is not a directory of this user (a symlink, or another owner's)`;
+  const ignore = lstatSync(join(archive, ".gitignore"), { throwIfNoEntry: false });
+  if (ignore && !ignore.isFile()) return `${join(archive, ".gitignore")} is not a regular file`;
+  return undefined;
+}
+
+/**
+ * Full reset, first step: the state directory moves to `.agenthub/archive/state-<UTC time>/` (0700). Nothing is
+ * deleted; moving the archive back restores it. Only the default `<root>/.agenthub/state` qualifies (the caller checks).
+ * The rename is the last step: when this throws, nothing was moved.
+ */
+export function archiveState(root: string, stateDir: string, now = new Date()): string {
+  const problem = archiveProblem(root, stateDir);
+  if (problem) throw new Error(problem);
+  const archive = join(root, ".agenthub", "archive");
+  if (!lstatSync(archive, { throwIfNoEntry: false })) mkdirSync(archive, { mode: 0o700 });
+  // hub.db holds task text, PII included: keep the archive out of git whatever the project's .gitignore says.
+  // The local worker's denylist (src/local/deny.ts) keeps it out of its tools, sandbox and memory capture.
+  // Verified, not only created: an edited, emptied or hard-linked one is replaced by a rename, never written through.
+  // Turn snapshots exclude the archive as well.
+  const ignore = join(archive, ".gitignore");
+  const current = lstatSync(ignore, { throwIfNoEntry: false });
+  if (!current || current.nlink > 1 || readFileSync(ignore, "utf8") !== "*\n") {
+    const temporary = join(archive, `.gitignore.${randomUUID()}.tmp`);
+    try { writeFileSync(temporary, "*\n", { flag: "wx", mode: 0o600 }); renameSync(temporary, ignore); }
+    finally { rmSync(temporary, { force: true }); }
+  }
+  const target = join(archive, `state-${now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")}`);
+  if (lstatSync(target, { throwIfNoEntry: false })) throw new Error(`${target} already exists`);
+  chmodSync(stateDir, 0o700);
+  // ponytail: checked, then renamed by path; a symlink swapped in for .agenthub/archive in the microseconds between
+  // still wins. Rename relative to a held directory descriptor (renameat) if Bun ever exposes one.
+  renameSync(stateDir, target);
+  return target;
+}
+
+/**
+ * Full reset, second step: a new state directory with only the archive's `project.json`, so the project id and
+ * registration stay. Something else may have created the directory meanwhile (the status line tee, 0755).
+ */
+export function startState(stateDir: string, archived: string): void {
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const st = lstatSync(stateDir);
+  if (!st.isDirectory() || st.uid !== (process.getuid?.() ?? st.uid)) throw new Error(`${stateDir} was re-created as something other than a directory of this user`);
+  chmodSync(stateDir, 0o700);
+  if (existsSync(join(archived, "project.json"))) copyFileSync(join(archived, "project.json"), join(stateDir, "project.json"));
+}

package/src/cli/status-lines.ts

@@ -1,8 +1,8 @@
 import type { ContextView } from "../hub/context-window.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; paused?: string; servedBy?: string; requestedModel?: string }
-export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string }
+export interface PeerRow { context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; toolsOnly?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
 export function backendLabel(backend: BackendRow): string {
@@ -11,8 +11,9 @@ export function backendLabel(backend: BackendRow): string {
   return alias.startsWith(`${kind}/`) ? alias : `${kind}/${alias}`;
 }
 
-export function contextLine(reading: ContextView): string {
-  return `context ${reading.used === null ? "unknown" : `${Math.round(reading.used * 100)}%`} (${reading.freshness}${reading.source ? `, ${reading.source}` : ""}${reading.measuredAt !== null ? `, measured ${new Date(reading.measuredAt).toISOString()}` : ""})`;
+/** `measured` reads as an ISO time unless `time` says otherwise: the console uses local time, as its event headers do. */
+export function contextLine(reading: ContextView, time = (at: number) => new Date(at).toISOString()): string {
+  return `context ${reading.used === null ? "unknown" : `${Math.round(reading.used * 100)}%`} (${reading.freshness}${reading.source ? `, ${reading.source}` : ""}${reading.measuredAt !== null ? `, measured ${time(reading.measuredAt)}` : ""})`;
 }
 
 export function peerLine(id: string, p: PeerRow): string {
@@ -24,6 +25,7 @@ export function peerLine(id: string, p: PeerRow): string {
     (p.heldBy ? `  ${p.holdNote ?? `held by needs_review ${p.heldBy}; ahub queue resolve ${p.heldBy} --action completed|retry|discard --reason <text>`}` : "") +
     (p.oldestQueuedAt !== undefined ? `  oldest ${Math.max(0, Math.floor((Date.now() - p.oldestQueuedAt) / 1000))}s` : "") +
     (p.attached === false ? "  disconnected" : "") +
+    (p.toolsOnly ? `  ${p.toolsOnly}` : "") +
     (p.paused ? `  (${p.paused})` : "") +
     (p.servedBy ? `  last call: ${p.servedBy}` : "") +
     // Which backend the peer asked for on its last turn: without it, telling a Pi DGX turn from an MLX one
@@ -36,5 +38,7 @@ export function backendLine(backend: BackendRow): string {
   return `  model    ${backendLabel(backend)} ${backend.state ?? "unknown"} active ${backend.active ?? 0}` +
     (backend.requestedModel ? ` requested ${backend.requestedModel}` : "") +
     (backend.actualModel ? ` actual ${backend.actualModel}` : "") +
-    (backend.provider ? ` provider ${backend.provider}` : "");
+    (backend.provider ? ` provider ${backend.provider}` : "") +
+    (backend.coolingUntil ? ` cooling down until ${backend.coolingUntil} after ${backend.failures ?? "?"} failures` : "") +
+    (backend.failingUntil ? ` last dispatch failed, no load moves until ${backend.failingUntil}` : "");
 }