@staix/agent-hub 0.12.20 → 0.12.21

package/src/cli/console-state.ts

@@ -1,9 +1,13 @@
+import { PERMISSION_MODES } from "../hub/permission-mode.ts";
+import { taskProgress } from "../ui/task-progress.ts";
+import type { ProgressStage } from "../ui/task-progress.ts";
 import { sanitize } from "../hub/envelope.ts";
 
 export interface Approval {
   id: string; peer: string; title: string; expiresAt: number;
   options: { optionId: string; name: string; kind: string }[];
 }
+export interface PermissionDefault { peer: string; mode: "never-ask"; source: string }
 export interface ConsoleEvent { text: string; peer?: string; kind?: string; tone?: Tone }
 export interface ConsoleState {
   mode: "stream" | "panels"; panel: number; selection: number;
@@ -15,18 +19,57 @@ export interface ConsoleState {
   autoSelected?: boolean;
   input: string; editing: boolean; history: string[]; historyIndex: number;
   approvals: Approval[]; events: ConsoleEvent[]; peers: Record<string, any>; budget: Record<string, any>;
-  tasks: any[]; queue: any[]; detail?: Detail; detailOffset: number; help: boolean; notice: string; noticeAt?: number; noticeTone?: Tone;
+  tasks: any[]; tasksKnown?: boolean; taskCounts?: Record<string, number>; queue: any[]; detail?: Detail; detailOffset: number; help: boolean; notice: string; noticeAt?: number; noticeTone?: Tone;
   peerFilter?: string; kindFilter?: string; project?: string;
-  confirm?: { type: "permission"; id: string; option: string; peer: string } | { type: "command"; args: string[] };
+  confirm?: { type: "permission"; id: string; option: string; peer: string } | { type: "command"; args: string[] } | { type: "permission_default"; peer: string; source: string };
   optionChoice?: string;
+  modeChoice?: string;
+  permissionDefaults: PermissionDefault[];
+  permissionDefaultsHandled: string[];
 }
 /** A detail view: text as the stream shows it, or labeled fields. */
 export type Detail = string | Record<string, unknown>;
 export type ConsoleEffect = { type: "exit" } | { type: "permit"; id: string; option?: string } |
-  { type: "command"; args: string[] } | { type: "show"; panel: number; id: string } | { type: "print"; text: string; kind: string; tone?: Tone } | { type: "keys" };
+  { type: "permission_default"; peer: string; confirmed: boolean } | { type: "command"; args: string[] } | { type: "show"; panel: number; id: string } | { type: "print"; text: string; kind: string; tone?: Tone } | { type: "keys" };
 export function initialConsoleState(panels = false): ConsoleState {
   return { mode: panels ? "panels" : "stream", panel: 1, selection: 0,
-    input: "", editing: false, history: [], historyIndex: 0, approvals: [], events: [], peers: {}, budget: {}, tasks: [], queue: [], detailOffset: 0, help: false, notice: "" };
+    input: "", editing: false, history: [], historyIndex: 0, approvals: [], events: [], peers: {}, budget: {}, tasks: [], tasksKnown: false, queue: [], permissionDefaults: [], permissionDefaultsHandled: [], detailOffset: 0, help: false, notice: "" };
+}
+/** Approval frequency does not create a common sandbox across native peers. */
+export function permissionBoundary(peer: string): string {
+  if (peer === "pi" || peer === "local") return `${peer}: inside hub sandbox, path guard and denylist`;
+  if (peer === "claude" || peer === "codex") return `${peer}: native vendor bounds; no hub sandbox`;
+  return `${peer}: runs its own tools; NO hub sandbox`;
+}
+function permissionModeRefusal(peer: string, mode: unknown): string | undefined {
+  if (mode === "unmanaged") return `${peer} permission mode is unmanaged; use its native controls`;
+  if (mode === "unverified") return `${peer} permission mode is unverified; start with ahub ${peer} and run a tool first`;
+  if (mode === "unknown") return `${peer} permission mode is unknown; inspect or reconnect its native session`;
+  return undefined;
+}
+/** Queue sizes and timestamps do not make a refused/default-deferred peer ready. */
+function permissionDefaultFingerprint(s: ConsoleState, row: Pick<PermissionDefault, "peer" | "source">): string {
+  const peer = s.peers[row.peer];
+  // Readiness, not activity: a peer going idle or busy does not make a deferred default worth asking about again.
+  return JSON.stringify([row.peer, row.source, !peer ? "absent" : peer.state === "offline" ? "offline" : "attached", peer?.permissionMode ?? "ask", peer?.attached ?? !!peer, peer?.claiming ?? false, peer?.toolsOnly ?? false]);
+}
+/** Offer one file default only when no other keyboard decision or edit is active. */
+export function syncPermissionDefaults(s: ConsoleState, rows: unknown): boolean {
+  if (!Array.isArray(rows)) rows = [];
+  s.permissionDefaults = (rows as unknown[]).filter((row): row is PermissionDefault => !!row && typeof row === "object" &&
+    typeof (row as PermissionDefault).peer === "string" && (row as PermissionDefault).mode === "never-ask" && typeof (row as PermissionDefault).source === "string");
+  const current = new Set(s.permissionDefaults.map(row => permissionDefaultFingerprint(s, row)));
+  s.permissionDefaultsHandled = s.permissionDefaultsHandled.filter(fingerprint => current.has(fingerprint));
+  const pending = s.confirm;
+  if (pending?.type === "permission_default" && !s.permissionDefaults.some(row => row.peer === pending.peer && row.source === pending.source)) s.confirm = undefined;
+  if (s.confirm || s.editing || s.input || s.modeChoice || s.optionChoice || s.help) return false;
+  const next = s.permissionDefaults.find(row => !s.permissionDefaultsHandled.includes(permissionDefaultFingerprint(s, row)));
+  if (!next) return false;
+  s.confirm = { type: "permission_default", peer: next.peer, source: next.source };
+  return true;
+}
+export function permissionDefaultText(row: Pick<PermissionDefault, "peer" | "source">): string {
+  return `never-ask default for ${row.peer} from ${quoted(row.source)}\n${permissionBoundary(row.peer)}\nUntil you answer y, this default stays ask. y enables; n cancels for this hub; Esc defers.`;
 }
 /** Strip terminal controls before any daemon or child output reaches a terminal. Preserve printable Unicode. */
 export function terminalText(value: unknown): string {
@@ -36,10 +79,12 @@ export function terminalText(value: unknown): string {
     .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
     .replace(/\x1b[^\n]?/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, ""));
 }
-export type Tone = "info" | "strong" | "success" | "attention" | "failure" | "muted";
+export type Tone = "info" | "strong" | "success" | "attention" | "failure" | "muted" | "peerClaude" | "peerCodex" | "taskKeyword" | "number" | "issueRef" | "taskRef";
 export interface Span { text: string; tone?: Tone }
 export const PALETTE: Readonly<Record<Tone, string>> = Object.freeze({
   info: "\x1b[36m", strong: "\x1b[1;36m", success: "\x1b[32m", attention: "\x1b[33m", failure: "\x1b[31m", muted: "\x1b[90m",
+  peerClaude: "\x1b[94m", peerCodex: "\x1b[96m",
+  taskKeyword: "\x1b[35m", number: "\x1b[1m", issueRef: "\x1b[4m", taskRef: "\x1b[4;35m",
 });
 export function paint(line: Span[], color: boolean): string {
   return line.map(span => {
@@ -48,6 +93,83 @@ export function paint(line: Span[], color: boolean): string {
     return color && sgr && text ? sgr + text + "\x1b[0m" : text;
   }).join("");
 }
+/** Console stream headers only. Tokenize sanitized text; bodies and command output stay plain. */
+export function streamTokens(value: string, eventTone?: Tone, kind?: string): Span[] {
+  const text = terminalText(value);
+  if (kind === "command" || kind === "console") return [{ text }];
+  const peers: Readonly<Record<string, Tone>> = { claude: "peerClaude", codex: "peerCodex" };
+  // Hub-written peer slots only; words such as local/pi/hub in a title do not identify a speaker.
+  const peerSlots = new Set<number>();
+  const leading = text.match(/^\s*(?:[.?*!]\s+)?([A-Za-z_][A-Za-z_0-9-]*)(?=:| is | asks permission:| permission )/);
+  if (leading) peerSlots.add(leading[0].lastIndexOf(leading[1]!));
+  const route = text.match(/^\s*(?:[0-9:]+ (?:AM|PM) )?([A-Za-z_][A-Za-z_0-9-]*) -> ([A-Za-z_][A-Za-z_0-9,-]*|\*)/);
+  if (route) {
+    const start = route[0].indexOf(route[1]!); peerSlots.add(start);
+    let at = route[0].lastIndexOf(route[2]!);
+    for (const recipient of route[2]!.split(",")) { peerSlots.add(at); at += recipient.length + 1; }
+  }
+  if (/^\s*\* task #[0-9]+ .+ (?:accepted by|assigned to) [A-Za-z_][A-Za-z_0-9-]*$/.test(text) && !/ declined| reason:/.test(text)) {
+    const owner = text.match(/(?:accepted by|assigned to) ([A-Za-z_][A-Za-z_0-9-]*)$/);
+    if (owner) peerSlots.add(owner.index! + owner[0].lastIndexOf(owner[1]!));
+  }
+  const marker = text.match(/^\s*([.?*!])/);
+  const markerAt = marker ? marker[0].length - 1 : -1;
+  const state = kind === "state" ? text.match(/ is ([A-Za-z_]+)$/) : undefined;
+  const stateAt = state ? state.index! + 4 : -1;
+  const permissionIds = new Set<number>();
+  for (const match of text.matchAll(/\b(?:permission|request|permit) ([0-9]{8})(?=\b)/g)) permissionIds.add(match.index + match[0].length - 8);
+  const taskKeyword = text.match(/^\s*\*?\s*(task)(?![\w-])/i);
+  const taskKeywordAt = taskKeyword ? taskKeyword[0].length - taskKeyword[1]!.length : -1;
+  const out: Span[] = []; let end = 0; let previousToken = ""; let previousStart = -1;
+  for (const match of text.matchAll(/(?<![\p{L}\p{N}_#-])#[0-9]+(?![\p{L}\p{N}_-])|(?<![\p{L}\p{N}_#.:-])(?:[0-9]+(?::[0-9]+)+(?: AM| PM)?|[0-9]+(?:\.[0-9]+)?(?:%|ms|s|m|h)?)(?![\p{L}\p{N}_%-]|[.:][\p{L}\p{N}])|[A-Za-z_][A-Za-z_0-9-]*|->|[.?*!]/gu)) {
+    const token = match[0]; const start = match.index;
+    const gap = text.slice(end, start);
+    if (gap) out.push({ text: gap });
+    let tone: Tone | undefined;
+    // ponytail: legacy notices have no typed reference ranges. Classify task/review prefixes textually;
+    // assign/which #N remains an issue reference until notices carry structured reference spans.
+    if (token.startsWith("#")) {
+      const task = previousToken.toLowerCase() === "task" && /^\s*$/.test(gap);
+      const review = previousToken.toLowerCase() === "review" && /^\s*$/.test(gap) && text[previousStart - 1] === "[" && text[start + token.length] === "]";
+      tone = task || review ? "taskRef" : "issueRef";
+    }
+    else if (start === taskKeywordAt) tone = "taskKeyword";
+    else if (/^[0-9]/.test(token) && !permissionIds.has(start)) tone = "number";
+    else if (peerSlots.has(start) && Object.hasOwn(peers, token)) tone = peers[token];
+    else if (start === markerAt || start === stateAt || (route && token === "->" && start < route[0].length)) tone = eventTone;
+    out.push({ text: token, ...(tone ? { tone } : {}) });
+    previousToken = token; previousStart = start; end = start + token.length;
+  }
+  if (end < text.length) out.push({ text: text.slice(end) });
+  return out;
+}
+/** Wrap plain text first, then project original token spans onto it, preserving trusted slots across continuations. */
+export function wrapStreamTokens(value: string, columns: number, tone?: Tone, kind?: string): Span[][] {
+  const spans = streamTokens(terminalText(value).replace(/\t/g, " "), tone, kind);
+  const text = spans.map(s => s.text).join("");
+  let cursor = 0; let projecting = true; let spanIndex = 0; let spanAt = 0;
+  return wrap(text, columns).map((line, index) => {
+    const content = line.trimStart();
+    const start = projecting ? text.indexOf(content, cursor) : -1;
+    if (!content || start < 0) {
+      if (content) projecting = false;
+      // Only the first physical header can have structural markers. Never infer structure from a continuation.
+      return index === 0 ? streamTokens(line, tone, kind).map(s => ({ text: s.text, ...(s.tone === tone && tone ? { tone } : {}) })) : [{ text: line }];
+    }
+    const end = start + content.length; cursor = end;
+    const out: Span[] = [{ text: line.slice(0, line.length - content.length) }];
+    while (spanIndex < spans.length && spanAt + spans[spanIndex]!.text.length <= start) {
+      spanAt += spans[spanIndex++]!.text.length;
+    }
+    while (spanIndex < spans.length && spanAt < end) {
+      const span = spans[spanIndex]!; const next = spanAt + span.text.length;
+      out.push({ ...span, text: span.text.slice(Math.max(0, start - spanAt), Math.min(span.text.length, end - spanAt)) });
+      if (next > end) break;
+      spanAt = next; spanIndex++;
+    }
+    return out;
+  });
+}
 export function resolveColor(flag: string | undefined, env: { isTTY: boolean; TERM?: string; NO_COLOR?: string }): boolean | Error {
   if (flag === "always") return true;
   if (flag === "never") return false;
@@ -188,7 +310,7 @@ const KEYS: [string, string[]][] = [
   ["Command", ["Enter run", "Esc cancel", "Up/Down history", "Ctrl-U clear"]],
   ["Panels", ["1-5 panel", "j/k or arrows move", "Enter view", "j/k scroll a view"]],
   ["Approvals", ["a allow (then y)", "d deny", "v view", "[ ] select"]],
-  ["Peers", ["p pause", "r resume"]],
+  ["Peers", ["p pause", "r resume", "m permission mode"]],
   ["Tasks", ["a assign (then y)", "r review"]],
   ["Queue", ["r resolve (reason, then y)"]],
   ["Events", ["f peer filter", "g kind filter"]],
@@ -222,7 +344,7 @@ function bound(s: ConsoleState): ConsoleState {
   if (s.requestDetail && s.requestDetail !== s.approvalId) { s.requestDetail = s.approvalId; s.detailOffset = 0; }
   return s;
 }
-const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "ask", "remember", "route", "turns", "undo", "check-path", "report"]);
+const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "turns", "undo", "check-path", "report"]);
 /** A tiny argv parser, never a shell. Quotes group arguments; backslash escapes one character. */
 export function parseConsoleCommand(input: string): string[] {
   const words: string[] = []; let word = ""; let quote = ""; let escaped = false; let started = false;
@@ -241,7 +363,8 @@ export function parseConsoleCommand(input: string): string[] {
   return words;
 }
 export function commandNeedsConfirmation(args: string[]): boolean {
-  return (args[0] === "task" && args[1] === "assign") || (args[0] === "queue" && args[1] === "resolve") || (args[0] === "permit" && args[2] !== "deny");
+  const positional = args.filter(arg => arg !== "--yes");
+  return (positional[0] === "permission" && positional[2] === "never-ask") || (args[0] === "task" && args[1] === "assign") || (args[0] === "queue" && args[1] === "resolve") || (args[0] === "permit" && args[2] !== "deny");
 }
 export function panelRows(s: ConsoleState): any[] {
   if (s.panel === 1) return Object.entries(s.peers).map(([id, peer]) => ({ id, ...peer, budget: s.budget[id] }));
@@ -264,8 +387,15 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   if (key === "\x03") { effects.push({ type: "exit" }); return done(); }
   if (s.confirm) {
     const confirm = s.confirm; s.confirm = undefined;
+    if (confirm.type === "permission_default") {
+      if (key !== "y" && key !== "n" && key !== "\x1b") { s.confirm = confirm; return done(); }
+      s.permissionDefaultsHandled = [...s.permissionDefaultsHandled, permissionDefaultFingerprint(s, confirm)];
+      if (key === "\x1b") { notify(s, `${confirm.peer} never-ask default deferred; remains pending and ask`, now, "attention"); return done(); }
+      effects.push({ type: "permission_default", peer: confirm.peer, confirmed: key === "y" });
+      return done();
+    }
     if (key === "y") {
-      if (confirm.type === "command") effects.push({ type: "command", args: confirm.args });
+      if (confirm.type === "command") effects.push({ type: "command", args: confirm.args[0] === "permission" && confirm.args[2] === "never-ask" ? [...confirm.args.filter(arg => arg !== "--yes"), "--yes"] : confirm.args });
       else if (s.approvals.some(a => a.id === confirm.id && allowOptions(a).some(o => o.optionId === confirm.option))) {
         effects.push({ type: "permit", id: confirm.id, option: confirm.option });
         answered(confirm.id);
@@ -273,6 +403,19 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     }
     return done();
   }
+  if (s.modeChoice) {
+    const peer = s.modeChoice;
+    if (key === "\x1b") { s.modeChoice = undefined; return done(); }
+    const mode = PERMISSION_MODES[Number(key) - 1];
+    if (/^[1-3]$/.test(key) && mode) {
+      s.modeChoice = undefined;
+      if (!s.peers[peer] || s.peers[peer].state === "offline") notify(s, `${peer} is no longer attached`, now);
+      else if (permissionModeRefusal(peer, s.peers[peer].permissionMode)) notify(s, permissionModeRefusal(peer, s.peers[peer].permissionMode)!, now);
+      else if (mode === "never-ask") s.confirm = { type: "command", args: ["permission", peer, mode] };
+      else effects.push({ type: "command", args: ["permission", peer, mode] });
+    }
+    return done();
+  }
   if (s.help && s.mode === "panels" && !["?", "\x1b", "q"].includes(key)) return done(); // the key table is modal
   if (s.editing || s.input) {
     if (key === "\x1b") { s.input = ""; s.editing = false; }
@@ -285,7 +428,8 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
       const input = s.input; s.input = ""; s.editing = false;
       if (!input.trim()) return done();
       try {
-        const args = parseConsoleCommand(input);
+        const parsed = parseConsoleCommand(input);
+        const args = parsed[0] === "permission" ? [...parsed.filter(arg => arg !== "--yes"), ...(parsed.includes("--yes") ? ["--yes"] : [])] : parsed;
         if (args[0] === "queue" && args[1] === "resolve") {
           const reason = args.indexOf("--reason");
           if (reason < 0 || !args[reason + 1]?.trim()) throw new Error("queue resolve requires --reason");
@@ -351,6 +495,14 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     return done();
   }
   if (s.mode === "panels" && item !== undefined && item !== null) {
+    if (s.panel === 1 && key === "m") {
+      const peer = String(item);
+      const info = s.peers[peer];
+      if (!info || info.state === "offline") notify(s, `${peer} is not attached`, now);
+      else if (permissionModeRefusal(peer, info.permissionMode)) notify(s, permissionModeRefusal(peer, info.permissionMode)!, now);
+      else s.modeChoice = peer;
+      return done();
+    }
     const prefill = s.panel === 1 && key === "p" ? `pause ${item}` : s.panel === 1 && key === "r" ? `resume ${item}` :
       s.panel === 3 && key === "a" ? `task assign ${item} ` : s.panel === 3 && key === "r" ? `review ${item} ` :
       s.panel === 4 && key === "r" ? `queue resolve ${item} --action retry --reason ` : undefined;
@@ -373,12 +525,13 @@ const NOTICE_MS = 10_000;
 const TABLES: Record<number, string[]> = {
   1: ["PEER", "STATE", "LINK", "Q", "!", "REVIEW", "PAUSE", "QUOTA", "MODEL"],
   2: ["ID", "PEER", "LEFT", "TITLE"],
-  3: ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "TITLE"],
+  3: ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "TITLE", "STAGE"],
   4: ["ID", "PEER", "STATE", "REV", "AGE"],
 };
+const showPermissionModes = (s: ConsoleState) => Object.values(s.peers).some(peer => peer.permissionMode && peer.permissionMode !== "ask");
 const count = (n: unknown) => typeof n === "number" && n ? String(n) : "-";
 /** One span per column of a panel row; zero counters and unknown values read `-`. */
-function cells(s: ConsoleState, row: any, selected: boolean, now: number): Span[] {
+function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages?: Map<number, ProgressStage>): Span[] {
   const id = (text: unknown, tone: Tone | undefined) => span(text, tone && (selected ? "strong" : tone));
   if (s.panel === 1) {
     const b = s.budget[row.id];
@@ -386,6 +539,7 @@ function cells(s: ConsoleState, row: any, selected: boolean, now: number): Span[
       ? `${row.paused.by ?? "paused"}${typeof row.paused.at === "number" ? ` ${duration(now - row.paused.at)}` : ""}`
       : row.paused === "manual" ? "user" : row.paused ? String(row.paused).split(":")[0] : "-";
     return [id(row.id, row.state === "offline" ? undefined : "info"), span(row.state, stateTone(row.state)),
+      ...(showPermissionModes(s) ? [span(row.permissionMode && row.permissionMode !== "ask" ? row.permissionMode : "-", row.permissionMode === "never-ask" ? "attention" : undefined)] : []),
       span(row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
       span(count(row.queued)), span(count(row.queuedImportant), row.queuedImportant ? "attention" : undefined),
       span(count(row.needsReview), row.needsReview ? "failure" : undefined), span(paused, paused === "-" ? undefined : "attention"),
@@ -397,8 +551,10 @@ function cells(s: ConsoleState, row: any, selected: boolean, now: number): Span[
     const last = row.history?.at(-1);
     const at = last?.at ?? row.updated ?? row.created;
     const failed = last?.event === "check failed" || last?.event === "failed";
-    return [id(`#${row.id}`, "info"), span(`${row.state}${failed && row.state !== last.event ? ` ${last.event}` : ""}${row.ready ? " ready" : ""}`, failed ? "failure" : row.ready ? "attention" : stateTone(row.state)),
-      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title)];
+    const stage = stages?.get(row.id);
+    const meter = stage ? "[" + "#".repeat(stage.stage - (stage.changes ? 1 : 0)) + (stage.changes ? "!" : "") + "-".repeat(4 - stage.stage) + "]" : "[----]";
+    return [id(`#${row.id}`, "info"), span(`${row.state}${failed && row.state !== last.event ? ` ${last.event}` : ""}${row.ready ? " ready" : ""}${stage?.waiting ? " waiting" : ""}`, failed ? "failure" : row.ready || stage?.waiting ? "attention" : stateTone(row.state)),
+      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(meter, stage?.changes ? "failure" : stateTone(row.state))];
   }
   if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
   const [header, ...body] = String(row.text).split("\n");
@@ -413,22 +569,33 @@ function table(head: string[], rows: Span[][], columns: number): Span[][] {
   const cap = Math.max(24, Math.floor(columns / 3));
   const width = (cell: Span | undefined) => Bun.stringWidth(flat(cell?.text));
   const widths = head.map((h, i) => Math.min(cap, rows.reduce((max, row) => Math.max(max, width(row[i])), Bun.stringWidth(h))));
+  const flexible = head.includes("STAGE") ? head.indexOf("TITLE") : head.length - 1;
+  if (head.includes("STAGE")) {
+    // Keep the original columns adjacent; stage meters occupy a fixed right-edge column.
+    const room = () => columns - 2 - widths.reduce((sum, value, index) => sum + (index === flexible ? 0 : value), 0) - 2 * (head.length - 1);
+    for (const key of ["CLASS", "OWNER", "REVIEWER", "AGE", "STATE"]) {
+      const metadata = head.indexOf(key);
+      while (room() < 7 && widths[metadata]! > head[metadata]!.length) widths[metadata] = widths[metadata]! - 1;
+    }
+    widths[flexible] = Math.max(0, room());
+  }
   return [head.map(h => span(h, "info")), ...rows].map(row => row.map((cell, i) => {
-    if (i === head.length - 1) return cell;
+    if (i === head.length - 1 && flexible === i) return cell;
     const text = fit(cell.text, widths[i]!);
-    return { ...cell, text: text + " ".repeat(widths[i]! - Bun.stringWidth(text) + 2) };
+    return { ...cell, text: text + " ".repeat(Math.max(0, widths[i]! - Bun.stringWidth(text)) + (i === head.length - 1 ? 0 : 2)) };
   }));
 }
 /** The footer's key hint: only keys that act in this mode, panel and state. */
-function hint(s: ConsoleState): string {
+function hint(s: ConsoleState, columns: number): string {
   const pending = selectedApproval(s) ? ["a allow", "d deny"] : [];
   if (s.mode === "stream") return [...pending, ...(pending.length ? ["v view"] : []), ...(s.approvals.length > (pending.length ? 1 : 0) ? ["[ ] select"] : []), "Tab panels", ": command", "? keys", "q quit"].join("  ");
   if (s.help) return "? or Esc close  q quit";
   const approvals = s.panel === 2 ? pending : [];
   if (s.detail !== undefined || s.requestDetail) return [...approvals, "j/k scroll", "Esc back", "? keys", "q quit"].join("  ");
   const rows = panelRows(s); const row = rows[selection(s)];
-  const context = !row ? [] : s.panel === 1 ? ["p pause", "r resume"] : s.panel === 3 ? ["a assign", "r review"] : s.panel === 4 ? ["r resolve"] : [];
-  return [...approvals, ...context, ...(s.panel === 5 ? ["f peer", "g kind"] : []), ...(rows.length ? ["j/k move"] : []), ...(row ? ["Enter view"] : []), "? keys", ": command", "Tab stream", "q quit"].join("  ");
+  const context = !row ? [] : s.panel === 1 ? ["p pause", "r resume", "m permission mode"] : s.panel === 3 ? ["a assign", "r review"] : s.panel === 4 ? ["r resolve"] : [];
+  const text = [...approvals, ...context, ...(s.panel === 5 ? ["f peer", "g kind"] : []), ...(rows.length ? ["j/k move"] : []), ...(row ? ["Enter view"] : []), "? keys", ": command", "Tab stream", "q quit"].join("  ");
+  return s.panel === 1 && Bun.stringWidth(text) > columns ? text.replace("m permission mode", "m mode").replace("j/k move", "j/k").replace(": command", ": cmd") : text;
 }
 /** The project, then the tabs: the active one in brackets, pending approvals and held deliveries counted. */
 function header(s: ConsoleState, columns: number): Span[] {
@@ -446,45 +613,76 @@ function header(s: ConsoleState, columns: number): Span[] {
 const more = (line: Span[], text?: string): Span[] => [span("(more)".padEnd(Bun.stringWidth(line[0]!.text)), "attention"), ...(text === undefined ? line.slice(1) : [span(text)])];
 export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24, now = Date.now()): Span[][] {
   const permission = selectedApproval(s);
-  let prompt = s.editing ? `: ${s.input}` : hint(s);
+  let prompt = s.editing ? `: ${s.input}` : hint(s, columns);
   if (s.confirm?.type === "permission") prompt = `allow ${quoted(s.confirm.option)} for ${s.confirm.peer} (request ${s.confirm.id})? y/N`;
   if (s.confirm?.type === "command") prompt = `${s.confirm.args.join(" ")}? y/N`;
+  if (s.modeChoice) prompt = `permission ${s.modeChoice}: 1 ask  2 ask-when-needed  3 never-ask  Esc cancel`;
   const choice = s.optionChoice ? s.approvals.find(a => a.id === s.optionChoice) : undefined;
   if (choice) prompt = `allow request ${choice.id} (${choice.peer}) with: ${allowOptions(choice).map((o, i) => `${i + 1} ${quoted(o.name)}`).join("  ")}  Esc cancel`;
   const summary: Span[] = [];
   for (const [id, p] of Object.entries(s.peers)) {
     if (summary.length) summary.push(span(" "));
     summary.push(span(id, p.state === "offline" ? undefined : "info"), span(":"), span(p.state, stateTone(p.state)), span(` q${p.queued ?? 0}`));
+    if (p.permissionMode && p.permissionMode !== "ask") summary.push(span(` ${p.permissionMode}`, "attention"));
     if (p.needsReview) summary.push(span(` review${p.needsReview}`, "failure"));
     if (p.paused) summary.push(span(" paused", "attention"));
     if (p.toolsOnly) summary.push(span(" tools-only: ahub claude", "attention"));
   }
   const quotas = Object.entries(s.budget).map(([id, b]) => `${id}:${b.windows?.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%`).join("/") ?? "?"}`).join(" ");
-  if (quotas) summary.push(span(` | ${quotas}`));
+  if (quotas) summary.push(span(`${summary.length ? " | " : ""}${quotas}`));
   const approvals = [span(plural(s.approvals.length, "approval"), s.approvals.length ? "attention" : undefined)];
   if (permission) approvals.push(span(` | ${permission.peer} ${permission.id}`, "attention"), span(` ${duration(permission.expiresAt - now)} left`, "muted"));
   else if (s.approvals.length) approvals.push(span(" | none selected", "muted"));
-  if (s.notice && now - (s.noticeAt ?? now) < NOTICE_MS) approvals.push(span(" | "), span(s.notice, s.noticeTone ?? "failure"));
-  const footer = [fitLine(summary, columns), fitLine(approvals, columns), fitLine([span(prompt, s.confirm || s.optionChoice ? "attention" : undefined)], columns)];
+  const noticeShown = !!s.notice && now - (s.noticeAt ?? now) < NOTICE_MS;
+  if (noticeShown) approvals.push(span(" | "), span(s.notice, s.noticeTone ?? "failure"));
+  const neverPeer = s.confirm?.type === "permission_default" ? s.confirm.peer : s.confirm?.type === "command" && s.confirm.args[0] === "permission" && s.confirm.args[2] === "never-ask" ? s.confirm.args[1] : undefined;
+  const defaultSource = s.confirm?.type === "permission_default" ? s.confirm.source : undefined;
+  if (s.confirm?.type === "permission_default") prompt = `enable never-ask default for ${s.confirm.peer}? y/n Esc defer`;
+  const footer = [fitLine(neverPeer ? [span(permissionBoundary(neverPeer), "attention")] : summary, columns),
+    fitLine(defaultSource !== undefined ? [span(`source ${quoted(defaultSource.split(/[\\/]/).at(-1))}; stays ask until y`, "attention")] : approvals, columns),
+    fitLine([span(prompt, s.confirm || s.optionChoice ? "attention" : undefined)], columns)];
   const rule = [span("-".repeat(Math.max(0, columns)), "muted")];
-  if (s.mode === "stream") return [rule, ...footer];
+  if (s.mode === "stream") {
+    const counts = s.taskCounts;
+    const total = counts ? Object.values(counts).reduce((sum, value) => sum + value, 0) : 0;
+    const taskCount = span(counts ? `tasks ${counts.approved ?? 0}/${total} approved` : "tasks loading...", counts ? "success" : "attention");
+    if (!noticeShown && defaultSource === undefined && (counts || !s.approvals.length) && Bun.stringWidth(taskCount.text + " | " + approvals.map(s => s.text).join("")) <= columns) {
+      footer[1] = fitLine([taskCount, span(" | "), ...approvals], columns);
+    }
+    return [rule, ...footer];
+  }
+  const progress = taskProgress(s.tasks);
   const height = rows - 6; // header, rule, body, rule, three footer lines
   const lines: Span[][] = [];
-  if (s.help) lines.push(...keyTable(columns));
+  if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer)], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
+  else if (s.help) lines.push(...keyTable(columns));
   else if (s.detail !== undefined || (s.requestDetail && permission)) {
     const detail = s.detail !== undefined ? detailLines(s.detail, columns, now) : fieldLines(approvalFields(permission!), columns, now).flat();
     lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - height))));
   }
   else {
-    const data = panelRows(s); const head = TABLES[s.panel]; const at = selection(s);
+    const data = panelRows(s); const head = s.panel === 1 && showPermissionModes(s) ? ["PEER", "STATE", "MODE", ...TABLES[1]!.slice(2)] : TABLES[s.panel]; const at = selection(s);
     // Below the Approvals table: the selected request's title, its allow options and deny, one line each. Deny always
     // shows; options that do not fit are counted, rows give way to the rest, and the title gets what is left.
     const [title = [], allow = [], deny = []] = s.panel === 2 && permission ? fieldLines(approvalFields(permission).slice(3), columns, now) : [];
     const fits = Math.max(1, height - 5); // table header, one row, rule, one title line, deny
     if (allow.length > fits) allow.splice(fits - 1, Infinity, more(allow[0]!, `${plural(allow.length - fits + 1, "more option")}: Enter shows them all`));
     const tail = [...allow, ...deny];
-    const capacity = Math.max(1, s.panel === 2 ? Math.min(Math.floor(height / 2) - 1, height - 3 - tail.length) : height - 1); const start = Math.max(0, at - capacity + 1);
-    const rowsOf = head ? table(head, data.map((row, i) => cells(s, row, i === at, now)), columns) : undefined;
+    const capacity = Math.max(1, s.panel === 2 ? Math.min(Math.floor(height / 2) - 1, height - 3 - tail.length) : height - (s.panel === 3 ? 2 : 1)); const start = Math.max(0, at - capacity + 1);
+    const stages = new Map(progress.stages.map(stage => [stage.id, stage]));
+    const rowsOf = head ? table(head, data.map((row, i) => cells(s, row, i === at, now, stages)), columns) : undefined;
+    if (s.panel === 3) {
+      const done = progress.total ? Math.floor(progress.counts.approved * 20 / progress.total) : 0;
+      const main = s.tasksKnown === false && !progress.total ? "tasks loading..." : `${progress.counts.approved}/${progress.total} approved [${"#".repeat(done)}${".".repeat(20 - done)}] ${progress.total ? Math.floor(progress.counts.approved * 100 / progress.total) : 0}%`;
+      const known = s.tasksKnown !== false || progress.total > 0;
+      const parts = [span(main, known ? "success" : "attention")];
+      for (const [label, value, tone] of [["changes", progress.counts.changes_requested, "failure"], ["review", progress.counts.in_review, "attention"], ["waiting", progress.counts.waiting, "attention"], ["in progress", progress.counts.in_progress, undefined], ["proposed", progress.counts.proposed, undefined], ...(progress.counts.unknown ? [["unknown", progress.counts.unknown, "attention"] as const] : [])] as const) {
+        const extra = `  ${label} ${value}`;
+        if (!known || Bun.stringWidth(parts.map(p => p.text).join("") + extra) > columns) break;
+        parts.push(span(extra, tone));
+      }
+      lines.push(fitLine(parts, columns));
+    }
     lines.push(fitLine([span("  "), ...(rowsOf?.[0] ?? [span(`peer ${s.peerFilter ?? "all"}  kind ${s.kindFilter ?? "all"}`, "info")])], columns));
     for (let i = start; i < Math.min(data.length, start + capacity); i++) {
       const selected = i === at;

package/src/cli/console.ts

@@ -4,7 +4,7 @@ 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 { approvalFrom, initialConsoleState, keyTable, notify, paint, panelRows, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, terminalText, wrap } 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";
 
@@ -76,7 +76,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   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 - 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"); }
@@ -86,7 +86,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     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++; } }
@@ -130,11 +130,14 @@ 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) notice(String(error));
@@ -156,6 +159,14 @@ 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" });
@@ -221,6 +232,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         // 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);

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

@@ -43,6 +43,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ["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"],
@@ -54,6 +55,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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"],
@@ -71,6 +73,14 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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", [