@staix/agent-hub 0.12.19 → 0.12.21

package/src/cli/console.ts

@@ -1,10 +1,11 @@
+import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { StringDecoder } from "node:string_decoder";
 import type { ControlClient } from "../hub/control-client.ts";
 import { contextLine } from "./status-lines.ts";
 import { renderTailEvent } from "./tail-render.ts";
-import { initialConsoleState, paint, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, terminalText, wrap } from "./console-state.ts";
-import type { ConsoleEffect, ConsoleEvent, Tone } from "./console-state.ts";
+import { syncPermissionDefaults, permissionDefaultText, approvalFrom, initialConsoleState, keyTable, notify, paint, panelRows, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, streamTokens, wrapStreamTokens, terminalText, wrap } from "./console-state.ts";
+import type { ConsoleEffect, ConsoleEvent, Detail, Tone } from "./console-state.ts";
 import type { BusEvent } from "../hub/bus.ts";
 
 export interface ConsoleTerminal {
@@ -56,11 +57,16 @@ function nativeTerminal(): ConsoleTerminal {
     onSignal: listener => { process.on("SIGINT", listener); process.on("SIGTERM", listener); return () => { process.off("SIGINT", listener); process.off("SIGTERM", listener); }; },
   };
 }
+/** `task_show` text as labeled fields; a message that is not a task stays text. */
+function labeled(text: string): Detail {
+  try { const value = JSON.parse(text); return value && typeof value === "object" && !Array.isArray(value) ? value : String(value); }
+  catch { return text; }
+}
 /** One terminal client, no daemon ownership. All text crosses terminalText before writing. */
 export async function runConsole(options: ConsoleOptions): Promise<void> {
   const { client } = options; const terminal = options.terminal ?? nativeTerminal();
   const color = options.color ?? resolveColor(undefined, { isTTY: terminal.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
-  let state = initialConsoleState(!!options.panels);
+  let state = initialConsoleState(!!options.panels); state.project = basename(options.cwd);
   let columns = options.columns ?? terminal.columns; let rows = options.rows ?? terminal.rows;
   let active = true; let inAlternate = false; let plain = !terminal.isTTY || columns < 80 || rows < 24;
   let polling = false; let childRunning = false; let cancelChild: (() => void) | undefined;
@@ -68,17 +74,19 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const removers: (() => void)[] = []; const timers: ReturnType<typeof setInterval>[] = [];
   let resolveDone: () => void = () => {}; const done = new Promise<void>(resolve => { resolveDone = resolve; });
   let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
+  const notice = (text: string) => notify(state, text, Date.now());
   const safeWrite = (text: string) => terminal.write(paint([{ text }], color));
-  const streamLines = (event: ConsoleEvent) => terminalText(event.text).split("\n").flatMap((text, index) => wrap(text, columns).map(line => [{ text: line, ...(index === 0 && event.tone ? { tone: event.tone } : {}) }]));
+  const streamLines = (event: ConsoleEvent) => terminalText(event.text).split("\n").flatMap((text, index) => index === 0 ? wrapStreamTokens(text, columns, event.tone, event.kind) : wrap(text, columns).map(line => [{ text: line }]));
   const writeStream = (event: ConsoleEvent) => {
-    terminal.write(`\x1b[${rows - 3};1H`);
+    terminal.write(`\x1b[${rows - 4};1H`); // the scroll region ends above the rule and the three footer lines
     for (const line of streamLines(event)) { terminal.write(paint(line, color)); terminal.write("\r\n"); }
   };
-  const stream = (event: ConsoleEvent) => {
-    state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
+  /** `record: false` is for the console's own prints (the key table, a request viewed again): not events, so not in Events. */
+  const stream = (event: ConsoleEvent, record = true) => {
+    if (record) state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
     if (plain) {
       const [header, ...body] = terminalText(event.text).split("\n");
-      terminal.write(paint([{ text: header ?? "", tone: event.tone }, ...body.map(text => ({ text: "\n" + text }))], color) + "\n");
+      terminal.write(paint([...(color ? streamTokens(header ?? "", event.tone, event.kind) : [{ text: header ?? "" }]), ...body.map(text => ({ text: "\n" + text }))], color) + "\n");
     }
     else if (state.mode === "stream") writeStream(event);
     else { pendingStream.push(event); if (pendingStream.length > 1000) { pendingStream.shift(); droppedStream++; } }
@@ -87,14 +95,14 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     if (!active || plain) return;
     if (state.mode === "panels" && !inAlternate) { terminal.write("\x1b[r\x1b[?1049h\x1b[2J"); inAlternate = true; }
     else if (state.mode === "stream" && inAlternate) {
-      terminal.write(`\x1b[?1049l\x1b[1;${rows - 3}r`); inAlternate = false;
-      if (droppedStream) writeStream({ text: `${droppedStream} older panel-mode events omitted from console memory; inspect hub.log for the full stream.` });
+      terminal.write(`\x1b[?1049l\x1b[1;${rows - 4}r`); inAlternate = false;
+      if (droppedStream) writeStream({ text: `${plural(droppedStream, "older panel-mode event")} omitted from console memory; inspect hub.log for the full stream.` });
       for (const event of pendingStream) writeStream(event);
       pendingStream = []; droppedStream = 0;
     }
-    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - 3}r` : "\x1b[r");
+    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - 4}r` : "\x1b[r");
     const lines = renderConsoleLines(state, columns, rows);
-    const start = state.mode === "stream" ? rows - 2 : 1;
+    const start = rows - lines.length + 1;
     for (const [index, line] of lines.entries()) { terminal.write(`\x1b[${start + index};1H\x1b[2K`); terminal.write(paint(line, color)); }
     terminal.write(`\x1b[${rows};${Math.min(columns, Bun.stringWidth(paint(lines.at(-1) ?? [], false)) + 1)}H\x1b[?25h`);
   };
@@ -122,16 +130,19 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       ]);
       if (!active) return;
       const [status, budget, tasks, queue, ready] = replies;
+      if (status.status?.tasks && status.ok !== false) state.taskCounts = status.status.tasks;
       if (status.status?.peers) state.peers = status.status.peers;
+      if (syncPermissionDefaults(state, status.status?.permissionDefaults) && state.confirm?.type === "permission_default") stream({ text: permissionDefaultText(state.confirm), kind: "permission_default", peer: state.confirm.peer, tone: "attention" });
       if (budget.budget) state.budget = budget.budget;
-      if (tasks?.ok && state.mode === "panels") { const parsed = JSON.parse(tasks.text); if (Array.isArray(parsed)) {
+      if (tasks?.ok) { const parsed = JSON.parse(tasks.text); if (Array.isArray(parsed)) {
           const readyIds = new Set(ready?.ok ? JSON.parse(ready.text).map((task: any) => task.id) : []);
           state.tasks = parsed.map(task => ({ ...task, ready: readyIds.has(task.id) }));
+          state.tasksKnown = true;
         } }
       if (queue?.ok && state.mode === "panels" && Array.isArray(queue.deliveries)) state.queue = queue.deliveries;
-      const error = replies.find(reply => reply.ok === false)?.error; if (error) state.notice = String(error);
+      const error = replies.find(reply => reply.ok === false)?.error; if (error) notice(String(error));
       draw();
-    } catch (error) { if (active) { state.notice = String((error as Error).message); draw(); } }
+    } catch (error) { if (active) { notice(String((error as Error).message)); draw(); } }
     finally { polling = false; }
   };
   const run = options.runCommand ?? ((args, output, finished) => {
@@ -148,43 +159,62 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   });
   const effect = async (action: ConsoleEffect) => {
     if (action.type === "exit") return stop();
+    if (action.type === "permission_default") {
+      const result = await client.request({ t: "permission_default", peer: action.peer, confirmed: action.confirmed }, 35_000);
+      if (!active) return;
+      if (result.ok === false) {
+        notice(String(result.error ?? "permission default refused"));
+      } else stream({ text: `  ${action.peer} never-ask default ${action.confirmed ? "enabled" : "cancelled for this hub"}`, kind: "permission_default", peer: action.peer, tone: "attention" });
+      await refresh(); draw(); return;
+    }
     if (action.type === "permit") {
       client.send({ t: "permit", surface: "console", id: action.id, ...(action.option ? { option: action.option } : {}) });
       if (!action.option) stream({ text: `  ! denial requested for permission ${action.id}`, kind: "permission", tone: "failure" });
       return;
     }
+    if (action.type === "keys") return stream({ text: keyTable(columns).map(line => paint(line, false)).join("\n"), kind: "console" }, false);
+    if (action.type === "print") return stream({ text: action.text, kind: action.kind, ...(action.tone ? { tone: action.tone } : {}) }, false);
     if (action.type === "show") {
       const result = await client.request(action.panel === 3 ? { t: "task", op: "task_show", args: { id: action.id } } : { t: "queue", op: "show", id: action.id }, 3000);
-      if (!active) return;
+      // A late reply is for the panel and row it was asked for: once the person has moved on, it would show one item
+      // while the keys act on another, so it is dropped.
+      if (!active || state.mode !== "panels" || state.panel !== action.panel || state.help || state.detail !== undefined || String(panelRows(state)[state.selection]?.id) !== action.id) return;
       state.detailOffset = 0;
-      state.detail = result.ok === false ? String(result.error) : action.panel === 3 ? String(result.text) : JSON.stringify(result.delivery, null, 2);
+      state.detail = result.ok === false ? String(result.error) : action.panel === 3 ? labeled(String(result.text)) : result.delivery ?? "delivery not found";
       draw(); return;
     }
-    if (childRunning) { state.notice = "a command is already running"; draw(); return; }
+    if (childRunning) { notice("a command is already running"); draw(); return; }
     childRunning = true;
     stream({ text: `> ${action.args.join(" ")}`, kind: "command" });
     try {
-      cancelChild = run(action.args, text => { if (active) { stream({ text, kind: "command" }); draw(); } }, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); });
-    } catch (error) { childRunning = false; state.notice = String((error as Error).message); draw(); }
+      // Output lines sit at column 4, as message bodies do: what a command prints can carry peer text, and columns 0 and 2 are the hub's.
+      const output = (text: string) => { if (active) { stream({ text: text.replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
+      cancelChild = run(action.args, output, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); });
+    } catch (error) { childRunning = false; notice(String((error as Error).message)); draw(); }
   };
   const handle = (key: string) => {
     if (!active) return;
     const result = reduceConsole(state, key); state = result.state;
-    if (state.mode === "panels" && (plain || columns < 80 || rows < 24)) { state.mode = "stream"; state.notice = "panels need at least 80x24"; }
+    if (state.mode === "panels" && (plain || columns < 80 || rows < 24)) { state.mode = "stream"; notice("panels need at least 80x24"); }
     for (const action of result.effects) void effect(action).catch(error => stop(`Console error: ${String(error.message)}`));
     draw();
-    if (key === "v" && state.detail && state.mode === "stream") { stream({ text: state.detail, kind: "permission" }); state.detail = undefined; draw(); }
     if (key === "\t") void refresh();
   };
   client.onPush = msg => {
     if (!active) return;
     try {
       if (msg.t === "event") stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t, tone: eventTone(msg.e) });
-      else if (msg.t === "context") stream({ text: `  ${msg.peer}: ${contextLine(msg.reading)}`, peer: msg.peer, kind: "context" });
+      else if (msg.t === "context") stream({ text: `  ${msg.peer}: ${contextLine(msg.reading, at => new Date(at).toLocaleTimeString())}`, peer: msg.peer, kind: "context" });
       else if (msg.t === "notice") stream({ text: `  * ${msg.line}`, kind: "notice" });
       else if (msg.t === "permission") {
-        stream({ text: `  ? ${msg.peer} asks permission: ${String(msg.title).replace(/\n/g, "\n      | ")}\n    answer with: ahub permit ${msg.id} <${msg.options.map((o: any) => `${o.optionId} (${o.name})`).join(", ")}> | deny`, peer: msg.peer, kind: "permission", tone: "attention" });
-        if (typeof msg.expiresAt === "number" && msg.expiresAt > Date.now() && !state.approvals.some(a => a.id === msg.id)) state.approvals.push(msg);
+        const request = approvalFrom(msg);
+        stream({ text: permissionText(request), peer: request.peer, kind: "permission", tone: "attention" });
+        // Only the first request is selected on arrival: once a selection has ended, a request that arrives as the person
+        // reacts must not take its place, so from then on only [ ], j or k select.
+        if (request.expiresAt > Date.now() && !state.approvals.some(a => a.id === request.id)) {
+          state.approvals.push(request);
+          if (!state.autoSelected) { state.approvalId = request.id; state.autoSelected = true; }
+        }
       } else if (msg.t === "permission_closed") {
         state.approvals = state.approvals.filter(a => a.id !== msg.id); state = pruneApprovals(state, Date.now());
         if (msg.reason === "expired" || msg.outcome === "cancelled" || msg.outcome?.startsWith("reject")) stream({ text: `  ! ${msg.peer} permission ${msg.id} ${msg.reason ?? msg.outcome}`, peer: msg.peer, kind: "permission", tone: "failure" });
@@ -199,7 +229,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       terminal.raw(true);
       removers.push(terminal.onData(text => {
         // A pasted chunk can only edit text, never approve, confirm or run commands. Bracketed-paste delimiters are stripped.
+        // Under the modal key table it does nothing at all.
         if (Array.from(text).length > 1 && !["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D"].includes(text)) {
+          if (state.help && state.mode === "panels") return;
+          if (state.confirm?.type === "permission_default") { draw(); return; }
           state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
           state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();
         } else handle(text);
@@ -208,7 +241,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         columns = terminal.columns; rows = terminal.rows; plain = columns < 80 || rows < 24;
         if (plain) {
           if (inAlternate) { terminal.write("\x1b[?1049l"); inAlternate = false; }
-          terminal.write("\x1b[r"); state.mode = "stream"; state.notice = "panels need at least 80x24";
+          terminal.write("\x1b[r"); state.mode = "stream"; notice("panels need at least 80x24");
           safeWrite("\nTerminal below 80x24; showing the plain stream.\n");
         }
         draw();

package/src/cli/facts-hook.ts

@@ -1,14 +1,51 @@
 #!/usr/bin/env bun
-// Claude Code PreToolUse, PostToolUse and Stop hook for turn-free facts (issue #108). `ahub claude` adds it to the
-// session's settings in a turn-free project. It never blocks or fails a tool call: a hub that is down, an advisory
-// project or any error prints nothing. A fact comes back as `additionalContext`, which Claude Code adds with the tool
-// call; the hub confirms it from the transcript row Claude Code writes for it, by tool use id, before it counts as seen.
+// Managed Claude hook transport for turn-free facts, native observations and runtime permissions.
+// PreToolUse preserves facts additionalContext and adds permission decisions; other phases observe only.
+// A failed or timed-out hub decides nothing, leaving Claude's native permission rules in effect.
+import { relative, resolve, isAbsolute } from "node:path";
+import { realPath } from "../hub/project.ts";
+import { isAgentConfigPath, isPermissionMode, hardLinked, isHubWritePath } from "../hub/permission-mode.ts";
 import { ControlClient } from "../hub/control-client.ts";
 
 /** A library call may target another hub; only the managed command hook inherits that target's native identity. */
-export function nativeHookIdentity(stateDir: string, peer: string, env: NodeJS.ProcessEnv = process.env): { nativeInstanceId?: string; nativeLaunchId?: string } {
+export function nativeHookIdentity(stateDir: string, peer: string, env: NodeJS.ProcessEnv = process.env): { nativeInstanceId?: string; nativeLaunchId?: string; hookPurpose?: string } {
   if (env.AGENTHUB_STATE_DIR !== stateDir || env.AGENTHUB_PEER_ID !== peer) return {};
-  return { ...(env.AGENTHUB_INSTANCE_ID ? { nativeInstanceId: env.AGENTHUB_INSTANCE_ID } : {}), ...(env.AGENTHUB_LAUNCH_ID ? { nativeLaunchId: env.AGENTHUB_LAUNCH_ID } : {}) };
+  return { ...(env.AGENTHUB_INSTANCE_ID ? { nativeInstanceId: env.AGENTHUB_INSTANCE_ID } : {}), ...(env.AGENTHUB_LAUNCH_ID ? { nativeLaunchId: env.AGENTHUB_LAUNCH_ID } : {}), ...(["facts", "idle", "facts-and-idle", "permission"].includes(env.AGENTHUB_HOOK_PURPOSE ?? "") ? { hookPurpose: env.AGENTHUB_HOOK_PURPOSE } : {}) };
+}
+
+/** Only resolving project paths outside the hub/native configuration directories receive a file grant. */
+export function projectFileTool(tool: unknown, input: unknown, projectRoot: unknown): boolean {
+  if (typeof projectRoot !== "string" || !isAbsolute(projectRoot) || !input || typeof input !== "object" || Array.isArray(input)) return false;
+  const args = input as Record<string, unknown>;
+  const key = ["Read", "Edit", "Write", "MultiEdit"].includes(String(tool)) ? "file_path" : tool === "NotebookEdit" ? "notebook_path" : ["LS", "Glob", "Grep"].includes(String(tool)) ? "path" : undefined;
+  if (!key) return false;
+  const optional = tool === "Glob" || tool === "Grep";
+  if (args[key] !== undefined && (typeof args[key] !== "string" || !args[key])) return false;
+  if (!optional && args[key] === undefined) return false;
+  try {
+    const root = realPath(projectRoot);
+    const protectedPath = (path: string) => isAgentConfigPath(path) || isHubWritePath(path);
+    const safe = (path: string) => {
+      const requested = resolve(root, path), lexical = relative(root, requested);
+      if (protectedPath(lexical)) return false;
+      const real = realPath(requested), canonical = relative(root, real);
+      // A hard link is another name for a file that may sit in a protected directory.
+      return canonical !== ".." && !canonical.startsWith("../") && !isAbsolute(canonical) && !protectedPath(canonical) && !hardLinked(real);
+    };
+    const target = typeof args[key] === "string" ? args[key] as string : root;
+    if (target.split(/[\\/]/).includes("..") || !safe(target)) return false;
+    if (tool === "Grep" && args.glob !== undefined) {
+      if (typeof args.glob !== "string" || !args.glob || args.glob.split(/[\\/]/).includes("..") || protectedPath(args.glob)) return false;
+      if (/[?*[{]/.test(args.glob) || !safe(resolve(root, target, args.glob))) return false;
+    }
+    if (tool === "Glob") {
+      if (typeof args.pattern !== "string" || !args.pattern) return false;
+      if (args.pattern.split(/[\\/]/).includes("..") || protectedPath(args.pattern)) return false;
+      // Wildcard expansions can enter symlinked or protected directories; their exact targets are unknown here.
+      if (/[?*[{]/.test(args.pattern) || !safe(resolve(root, target, args.pattern))) return false;
+    }
+    return true;
+  } catch { return false; }
 }
 
 /** The hook's stdout for one Claude Code hook input, or undefined for none. */
@@ -28,8 +65,13 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
       ...(typeof input.transcript_path === "string" ? { transcriptPath: input.transcript_path } : {}),
       startedMs: performance.now(), // this process's own start-up and connect time, for the latency record
     }, timeoutMs);
-    if (phase !== "pre" || !res?.ok || typeof res.text !== "string" || !res.text) return undefined;
-    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: res.text } });
+    if (phase !== "pre" || !res?.ok) return undefined;
+    const permission = isPermissionMode(res.permission) ? res.permission : "ask";
+    const fileTool = projectFileTool(input.tool_name, input.tool_input, res.projectRoot);
+    const allow = input.hook_event_name === "PreToolUse" && (permission === "never-ask" || permission === "ask-when-needed" && fileTool);
+    const text = typeof res.text === "string" && res.text ? res.text : undefined;
+    if (!allow && !text) return undefined;
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", ...(text ? { additionalContext: text } : {}), ...(allow ? { permissionDecision: "allow" } : {}) } });
   } finally {
     hub.close();
   }

package/src/cli/help.ts

@@ -0,0 +1,130 @@
+import { VERSION } from "../version.ts";
+import { paint, wrap, type Span } from "./console-state.ts";
+
+/** One usage form of `ahub help`: the usage starts with `ahub <command>`, alternatives joined by `|`. */
+export interface HelpEntry { section: string; usage: string; description: string }
+
+const SECTIONS: [string, [usage: string, description: string][]][] = [
+  ["Projects", [
+    ["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 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 help [command]", "this help, or one command's entries; also --help and -h"],
+    ["ahub version | --version", "print the installed version"],
+  ]],
+  ["Daemon and runtime", [
+    ["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 status", "the hub, its peers, model backends and task counts"],
+    ["ahub status --all", "show every registered project"],
+    ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
+    ["ahub doctor", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
+    ["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"],
+    ["ahub kill", "stop this project's hub"],
+    ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
+    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime"],
+    ["ahub upgrade --to <version> [--dry-run] [--yes]", "review and upgrade running projects"],
+    ["ahub recovery status|resume|abort <operation-id>", "inspect, resume or cancel a preflight; status names the next actions"],
+    ["ahub recovery dispose <operation-id> --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
+    ["ahub recovery dispose <operation-id> --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
+    ["ahub daemon [--unattended]", "internal: the detached hub process that ahub up or the dashboard manager starts"],
+    ["ahub recovery-run <operation-id>", "internal: the detached runner of an upgrade, restart or recovery resume"],
+  ]],
+  ["Agents", [
+    ["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"],
+    ["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"],
+    ["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 local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
+    ["ahub models setup|status|start|stop", "prepare or inspect local Ollama MLX (legacy stop is explicit)"],
+  ]],
+  ["Messages and approvals", [
+    ["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 tail", "live stream of messages, states and permission requests"],
+    ["ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]", "human only: inspect or set a running peer mode; never-ask requires --yes; config never-ask waits for console y"],
+    ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
+    ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
+    ["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>", "release a delivery held as needs_review: mark it completed, retry it or discard it"],
+  ]],
+  ["Tasks and review", [
+    ["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>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
+    ["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; a task that still waits is reserved for that peer instead"],
+    ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned", "your later verdict on an approved task, kept in the research records (research must be on)"],
+    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]...", "give a review verdict on a task"],
+    ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
+    ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
+    ["ahub ask [--remember] <question...>", "answer from the task board, shared memory and this run's log, with the ids it rests on"],
+    ["ahub remember <text...>", "save a note to the memory all agents share"],
+  ]],
+  ["Budget", [
+    ["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 budget execution configure <config.json> | status [id] | disable <id>", "opt-in limits on model calls, tool calls, time and tokens for pi and local"],
+  ]],
+  ["History and reports", [
+    ["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 report [--since 7d|<iso>] [--by task] [--json]", "turns, tokens, messages, overlaps and task events per period"],
+    ["ahub export [--since 7d|<iso>]", "structured events (events.jsonl) as JSON lines; never message bodies"],
+    ["ahub research [--since 30d] [--all] [--json]", "success, first-pass, rework and check-failure rates, tokens and wall time per approved task, from the opt-in research records"],
+    ["ahub research export [--format jsonl|csv] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text"],
+    ["ahub research backfill", "build this project's research records once from events.jsonl"],
+    ["ahub bench run <suite.json> --arm <label> [--repeat N] [--tasks a,b]", "run a benchmark suite against the peers attached here, in a project kept for benchmarks (it resets the work tree)"],
+    ["ahub bench list|status", "benchmark runs on this machine / the one running now"],
+    ["ahub bench report <run> [--json]", "pass rate, first pass, rework, tokens and wall time per task and overall"],
+    ["ahub bench compare <run|arm>... [--suite <name>] [--mixed] [--json]", "compare arms of one suite with 95% bootstrap intervals; inconclusive below 5 counted attempts per arm"],
+    ["ahub bench export [--format jsonl|csv]", "benchmark records for outside analysis: ids, outcomes and counts, never suite text"],
+    ["ahub check-path <file> [--peer <id>]", "other owners' open tasks that claim or changed a file"],
+  ]],
+  ["Hooks", [
+    ["ahub check-path --hook", "check-path 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"],
+  ]],
+  ["Dashboard", [
+    ["ahub ui [--no-open]", "open the local dashboard (or print its one-time link)"],
+    ["ahub ui --all [--no-open]", "open the unified project dashboard"],
+    ["ahub ui --all --stop", "stop only the dashboard manager"],
+    ["ahub manager", "internal: the dashboard manager process that ahub ui --all starts"],
+  ]],
+];
+export const HELP: readonly HelpEntry[] = SECTIONS.flatMap(([section, rows]) => rows.map(([usage, description]) => ({ section, usage, description })));
+
+const COMMAND = /^ahub (-{0,2}[a-z][a-z-]*(?: ?\| ?-{0,2}[a-z][a-z-]*)*)/;
+/** The command words a usage documents: `ahub pause|resume <peer>` documents pause and resume. */
+export function helpCommands(entry: HelpEntry): string[] {
+  return COMMAND.exec(entry.usage)?.[1]!.split(/ ?\| ?/) ?? [];
+}
+
+const DESCRIPTION = 34;
+/**
+ * Usage at 2 spaces, description at one fixed column, wrapped at word boundaries to the terminal width
+ * (80 to 100 columns). A usage too long for that column puts its description on the next line.
+ * With a command, only its entries; an unknown command renders nothing.
+ */
+export function renderHelp(columns: number, color: boolean, command?: string): string {
+  const width = Math.min(100, Math.max(80, columns || 80));
+  const entries = command === undefined ? HELP : HELP.filter(entry => helpCommands(entry).includes(command));
+  const lines: Span[][] = command === undefined ? wrap(`agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory`, width, 0).map(text => [{ text }]) : [];
+  let section = "";
+  for (const entry of entries) {
+    if (entry.section !== section) {
+      if (lines.length) lines.push([]);
+      lines.push([{ text: entry.section, tone: "strong" }]);
+      section = entry.section;
+    }
+    const prefix = COMMAND.exec(entry.usage)?.[0] ?? "";
+    const usage = wrap(entry.usage, width - 4, 0);
+    const description = wrap(entry.description, width - DESCRIPTION, 0);
+    const first: Span[] = [{ text: "  " }, { text: prefix, tone: "info" }, { text: usage[0]!.slice(prefix.length) }];
+    if (usage.length === 1 && 2 + Bun.stringWidth(usage[0]!) + 2 <= DESCRIPTION) first.push({ text: " ".repeat(DESCRIPTION - 2 - Bun.stringWidth(usage[0]!)) + description.shift() });
+    lines.push(first, ...usage.slice(1).map(text => [{ text: `    ${text}` }]), ...description.map(text => [{ text: " ".repeat(DESCRIPTION) + text }]));
+  }
+  return lines.map(line => paint(line, color)).join("\n");
+}

package/src/cli/identity.ts

@@ -26,6 +26,7 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
+  if (command === "permission") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -33,18 +34,23 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
     return "console";
   }
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
+  // #247: reading the research measures and records is harmless (ids and counts only); writing them is a person's.
+  if (command === "research") return args[0] === "backfill" ? "console" : "allowed";
+  // #251: a run resets the bench project's tree and proposes work; reading results is harmless.
+  // The subcommand is the first argument that is not --json, which the command accepts anywhere.
+  if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
   if (command === "budget") return !args.length || args.every((arg) => arg === "--json") ? "allowed" : "console";
   if (["claude", "codex", "kimi", "pi", "local", "pause", "resume"].includes(command)) return "conductor";
-  if (["help", "--help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
+  if (["help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
   return "console";
 }
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[]): string {
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "status", "logs", "export", "report", "facts", "check-path", "turns", "undo", "kill", "doctor"].includes(command)) return "unknown";
-  if (["task", "queue", "budget", "route", "recovery", "models", "projects"].includes(command)) {
-    const sub = args[0];
-    if (sub && ["propose", "show", "assign", "escalate", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "setup", "start", "stop", "remove"].includes(sub)) return `${command} ${sub}`;
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "bench"].includes(command)) {
+    const sub = command === "bench" ? args.find((arg) => arg !== "--json") : args[0];
+    if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "run", "report", "compare"].includes(sub)) return `${command} ${sub}`;
   }
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }