@staix/agent-hub 0.12.44 → 0.13.0

package/src/cli/console-symbols.ts

@@ -0,0 +1,74 @@
+import { planSymbolMatches } from "../hub/review-brief.ts";
+
+// #684 2b: the "changed symbols" block of the console's task detail. Pure data to fields, no terminal code. The hub's own observation of the changed
+// symbols (`codeSymbols`, PR #708) is read as it is; nothing is parsed from code here and nothing is asked of the hub beyond `task_show`.
+// Advisory only: ripwire does not report deleted symbols, so these lists never establish that a plan was or was not followed. The plan names are `plan.symbols`,
+// the same list `withCodeSymbols` reads as `planned` in the review brief (daemon.ts passes `task.plan?.symbols`), not a second source.
+
+export interface ChangedSymbol { id: string; path: string; name: string; kind: string }
+export interface SymbolBlock { state: "known" | "unknown"; complete: boolean; head?: string; matching: ChangedSymbol[]; unplanned: ChangedSymbol[]; untouched: string[] }
+
+const MAX_LINES = 40;
+const isPrivate = (task: any): boolean =>
+  !task || (Array.isArray(task.signals) && task.signals.some((s: unknown) => s === "pii" || s === "pii_path")) || task.title === "[pii]";
+const symbolsOf = (task: any): ChangedSymbol[] | undefined => {
+  const received = task?.codeSymbols;
+  if (!received || received.state !== "known" || !Array.isArray(received.symbols)) return undefined;
+  // Only the public receipt (`publicTaskCodeSymbols`, re-screened on every read) is shown. A stored receipt still carries `repositoryKey` and was never screened for
+  // the current policy: a task handed over in that shape reads as unknown, whatever feeds this renderer today (the renderer holds the rule itself).
+  if (Object.hasOwn(received, "repositoryKey")) return undefined;
+  const out: ChangedSymbol[] = [];
+  for (const s of received.symbols) if (s && typeof s.id === "string" && typeof s.path === "string" && typeof s.name === "string" && typeof s.kind === "string") out.push({ id: s.id, path: s.path, name: s.name, kind: s.kind });
+  return out;
+};
+
+/** Each changed symbol as matching the plan or unplanned, and each planned name nothing changed under as untouched. Unknown without code facts. */
+export function classifySymbols(task: any): SymbolBlock {
+  const changed = symbolsOf(task);
+  if (!changed) return { state: "unknown", complete: false, matching: [], unplanned: [], untouched: [] };
+  const plan: string[] = Array.isArray(task?.plan?.symbols) ? task.plan.symbols.filter((v: unknown): v is string => typeof v === "string") : [];
+  const matching = changed.filter(s => plan.some(p => planSymbolMatches(p, s.name)));
+  const unplanned = changed.filter(s => !plan.some(p => planSymbolMatches(p, s.name)));
+  const untouched = plan.filter(p => !changed.some(s => planSymbolMatches(p, s.name)));
+  return { state: "known", complete: task.codeSymbols.complete === true, ...(typeof task.codeSymbols.head === "string" ? { head: task.codeSymbols.head.slice(0, 8) } : {}), matching, unplanned, untouched };
+}
+
+/**
+ * The detail fields for a task (`symbols` and `symbols note`), or none for a private one. Values are objects of single words (`{ matching: name, in: path }`) so the console's field
+ * renderer quotes every agent-written string: a symbol name cannot pass for a hub label. Capped, with the count of what is left out.
+ */
+export function symbolFields(task: any): [string, unknown][] {
+  // Only a task as `task_show` shapes it (a numeric id and a state): any other detail an agent or a test hands the Tasks panel keeps its own layout.
+  if (!task || typeof task.id !== "number" || typeof task.state !== "string" || isPrivate(task)) return [];
+  const block = classifySymbols(task);
+  if (block.state === "unknown") return [["symbols", "changed symbols: unknown (no code facts)"]];
+  const items: Record<string, string>[] = [
+    ...block.matching.map(s => ({ matching: s.name, in: s.path })), ...block.unplanned.map(s => ({ unplanned: s.name, in: s.path })), ...block.untouched.map(name => ({ untouched: name })),
+  ];
+  const shown = items.slice(0, MAX_LINES);
+  const note = [`changed symbols: ${block.matching.length} matching, ${block.unplanned.length} unplanned, ${block.untouched.length} untouched${block.head ? ` at ${block.head}` : ""}`,
+    block.complete ? "" : "incomplete: some changed symbols were not listed, so an untouched one may have changed",
+    "advisory: deleted symbols are not reported"].filter(Boolean).join("; ");
+  return [["symbols", shown.length ? shown : "none observed"], ["symbols note", items.length > shown.length ? `${note}; ${items.length - shown.length} more not shown` : note]];
+}
+
+
+/** Render the hub's read-only pair verdicts; never derive disjointness from a local receipt or plan. */
+export function overlapFields(task: any): [string, unknown][] {
+  if (!task || typeof task.id !== "number" || typeof task.state !== "string" || isPrivate(task) || !Array.isArray(task.symbolOverlaps)) return [];
+  if (!task.symbolOverlaps.length) return [["overlaps", "none"]];
+  const items: Record<string, unknown>[] = [];
+  let invalid = 0;
+  for (const row of task.symbolOverlaps) {
+    if (!row || !Number.isSafeInteger(row.task) || row.task < 1 || !Array.isArray(row.files)
+      || !row.files.every((file: unknown) => typeof file === "string") || typeof row.sameFileDifferentSymbols !== "boolean") { invalid++; continue; }
+    items.push({ task: row.task, files: row.files.slice(0, MAX_LINES),
+      overlap: row.sameFileDifferentSymbols ? "same file, different symbols" : "overlap",
+      ...(row.files.length > MAX_LINES ? { omitted: `${row.files.length - MAX_LINES} files not shown` } : {}) });
+  }
+  if (!items.length) return [["overlaps", "unknown (invalid overlap data)"]];
+  const note = ["observed names only, deleted definitions may be missing",
+    items.length > MAX_LINES ? `${items.length - MAX_LINES} more not shown` : "",
+    invalid ? `${invalid} invalid rows withheld` : ""].filter(Boolean).join("; ");
+  return [["overlaps", items.slice(0, MAX_LINES)], ["overlap note", note]];
+}

package/src/cli/console-usage.ts

@@ -0,0 +1,89 @@
+import type { Counter, LimitsResult, UsageResult, UsageRow } from "../hub/usage-rollup.ts";
+
+// #683 U3: what the console's Usage panel shows, as plain strings. No terminal code and no state import here: console-state.ts renders it.
+// Every number names its source, an unknown counter reads `unknown` (never 0), and a private task is `#id [pii]` with no title.
+
+/** What the console keeps from the `usage` op: one query per period, the limits history and, for the task selected in Tasks, its tokens per peer. */
+export interface UsageState {
+  today?: UsageResult; week?: UsageResult; life?: UsageResult; limits?: LimitsResult;
+  /** The selected task's tokens per peer, with the task id it was asked for. */
+  task?: UsageResult; taskId?: number;
+  at?: number; problem?: string;
+  /** The hub's roll-up was still behind the event log when it answered: the numbers are partial (a later poll catches up). */
+  behind?: boolean;
+}
+export interface UsagePeerRow { id: string }
+
+const TAG: Record<Counter["source"], string> = { native: "native", count: "hub", manual: "manual", partial: "at least", unknown: "unknown" };
+const compact = (n: number): string => n >= 1e7 ? `${Math.round(n / 1e6)}M` : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e4 ? `${Math.round(n / 1e3)}k` : String(n);
+/** `1.2M native`, `77 hub`, or `unknown`: a counter nobody reported is never shown as a number. */
+export const counterText = (c: Counter | undefined, exact = false): string => !c || c.value === null ? "unknown" : `${exact ? c.value : compact(c.value)} ${TAG[c.source]}`;
+/** A row's tokens: the provider's total when it reported one, otherwise what the hub counted, otherwise unknown. */
+export const rowTokens = (row: UsageRow | undefined): Counter =>
+  row && row.total.value !== null ? row.total : row && row.counted.value !== null ? row.counted : { value: null, source: "unknown" };
+const periodText = (row: UsageRow | undefined, exact = false): string => row ? counterText(rowTokens(row), exact) : "no records";
+
+const rowOf = (result: UsageResult | undefined, peer: string): UsageRow | undefined => result?.rows.find(row => row.key === peer);
+
+/** Every peer the panel can say something about: peers with usage in any period, and peers with a quota reading. */
+export function usagePeers(usage: UsageState | undefined, budget: Record<string, unknown>, peers: Record<string, unknown>): UsagePeerRow[] {
+  const ids = new Set<string>([...Object.keys(peers), ...Object.keys(budget)]);
+  for (const result of [usage?.today, usage?.week, usage?.life]) for (const row of result?.rows ?? []) ids.add(row.key);
+  return [...ids].sort().map(id => ({ id }));
+}
+
+interface Budget { windows?: { id: string; used: number; resetsAt?: number }[]; paused?: { resetsAt: number } }
+const windowText = (w: { id: string; used: number; resetsAt?: number }, rel: (at: number) => string) =>
+  `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${rel(w.resetsAt)}` : ""}`;
+const lastResets = (limits: LimitsResult | undefined, peer: string, count: number) =>
+  (limits?.history ?? []).filter(h => h.type === "quota_reset" && h.peer === peer).slice(-count).reverse();
+
+/** One table row: PEER, TODAY, 7D, LIFETIME, PAUSE, QUOTA, LAST RESET (PAUSE before QUOTA: a pause must survive a narrow terminal, the long quota text is what gives way). */
+export function usageCells(usage: UsageState | undefined, peer: string, budget: Budget | undefined, rel: (at: number) => string): string[] {
+  const reset = lastResets(usage?.limits, peer, 1)[0];
+  // The table is tight at 80 columns: a time still to come reads `3h00m`, not `in 3h00m` (the detail view spells it out).
+  const ahead = (at: number) => rel(at).replace(/^in /, "");
+  return [peer, periodText(rowOf(usage?.today, peer)), periodText(rowOf(usage?.week, peer)), periodText(rowOf(usage?.life, peer)),
+    budget?.paused ? ahead(budget.paused.resetsAt) : "-",
+    budget?.windows?.length ? budget.windows.map(w => windowText(w, ahead)).join(", ") : "-",
+    reset ? `${reset.window} ${rel(Date.parse(reset.at))}` : "-"];
+}
+export const USAGE_HEAD = ["PEER", "TODAY", "7D", "LIFETIME", "PAUSE", "QUOTA", "LAST RESET"];
+/** Only the last reset gives way to width; the others are cut shorter instead, so the 7D column and the pause are never dropped. */
+export const USAGE_DROP = ["LAST RESET"];
+
+/** The token split of one period: input, output, cache read, cache write, the total and the hub's own count, each with its source. */
+export function splitText(row: UsageRow | undefined): string {
+  if (!row) return "no records";
+  return [`total ${counterText(row.total, true)}`, `input ${counterText(row.input, true)}`, `output ${counterText(row.output, true)}`,
+    `cache read ${counterText(row.cacheRead, true)}`, `cache write ${counterText(row.cacheWrite, true)}`, `hub count ${counterText(row.counted, true)}`].join(", ");
+}
+export const taskLabel = (usage: UsageState | undefined): string =>
+  usage?.taskId === undefined ? "" : `#${usage.taskId}${usage.task?.taskPii ? " [pii]" : ""}`;
+
+/** The detail of one peer, as labelled one-line-per-field text. Values are hub-built from ids and numbers only. */
+export function usageDetail(usage: UsageState | undefined, peer: string, budget: Budget | undefined, rel: (at: number) => string): Record<string, string> {
+  const resets = lastResets(usage?.limits, peer, 3).map(h => `${h.window} ${rel(Date.parse(h.at))}`);
+  const out: Record<string, string> = {
+    peer,
+    quota: budget?.windows?.length ? budget.windows.map(w => windowText(w, rel)).join(", ") : "no reading",
+    pause: budget?.paused ? `budget pause, resumes ${rel(budget.paused.resetsAt)}` : "none",
+    "last resets": resets.length ? resets.join(", ") : "none recorded",
+    today: splitText(rowOf(usage?.today, peer)),
+    "last 7 days": splitText(rowOf(usage?.week, peer)),
+    lifetime: splitText(rowOf(usage?.life, peer)),
+  };
+  if (usage?.taskId !== undefined) out[`task ${taskLabel(usage)}`] = splitText(rowOf(usage.task, peer));
+  return out;
+}
+
+/** The lines under the table: the task selected in Tasks and its tokens per peer. */
+export function usageTaskLines(usage: UsageState | undefined, selectedTask: number | undefined): { text: string; tone?: "muted" | "info" | "failure" }[] {
+  if (selectedTask === undefined) return [{ text: "task: none selected; pick one in Tasks (3), then open Usage (7)", tone: "muted" }];
+  if (usage?.problem) return [];
+  if (usage?.taskId !== selectedTask || !usage.task) return [{ text: `task #${selectedTask}: loading...`, tone: "muted" }];
+  const rows = usage.task.rows;
+  const head = { text: `task ${taskLabel(usage)}: tokens per peer, all time`, tone: "info" as const };
+  if (!rows.length) return [head, { text: "  no usage recorded for this task", tone: "muted" }];
+  return [head, ...rows.map(row => ({ text: `  ${row.key}  ${counterText(rowTokens(row))}` }))];
+}

package/src/cli/console.ts

@@ -4,6 +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 { reviewResult } from "./console-review.ts";
 import { syncPermissionDefaults, permissionDefaultText, approvalFrom, initialConsoleState, keyTable, notify, paint, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, streamTokens, wrapStreamTokens, terminalText, wrap, captureConsoleSelection, selectedPanelRow, appendEvent, FIRST_KEYS, LAST_KEYS } from "./console-state.ts";
 import type { ConsoleEffect, ConsoleEvent, Detail, Tone } from "./console-state.ts";
 import type { BusEvent } from "../hub/bus.ts";
@@ -192,6 +193,15 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         ...(panels ? [client.request({ t: "task", op: "hub_task_list", args: {} }, 3000), client.request({ t: "queue", op: "list" }, 3000), client.request({ t: "task", op: "hub_task_list", args: { ready: true } }, 3000)] : []),
         ...(panels && (state.panel === 1 || state.panel === 6) ? [client.request({ t: "settings_get" }, 3000)] : []),
       ]);
+      // #683 U3: the Usage panel asks the hub's roll-up only while it is open (UTC day, 7 UTC days, lifetime, the limits history and the selected task).
+      // The task is read at the time of the request, so a reply for a task that is no longer selected is dropped below.
+      const usageTask = panels && state.panel === 7 ? state.usageTask : undefined;
+      const usageReplies = panels && state.panel === 7 ? await (async () => {
+        const startOfDay = Date.UTC(new Date().getUTCFullYear(), new Date().getUTCMonth(), new Date().getUTCDate());
+        return Promise.all([client.request({ t: "usage", by: "peer", since: startOfDay }, 5000), client.request({ t: "usage", by: "peer", since: startOfDay - 6 * 86_400_000 }, 5000),
+          client.request({ t: "usage", by: "peer" }, 5000), client.request({ t: "usage", op: "limits", limit: 1000 }, 5000),
+          ...(usageTask !== undefined ? [client.request({ t: "usage", by: "peer", task: usageTask }, 5000)] : [])]);
+      })() : undefined;
       if (!active) return;
       const [status, budget, tasks, queue, ready, settings] = replies;
       captureConsoleSelection(state);
@@ -217,6 +227,12 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       }
       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 (usageReplies) {
+        const [today, week, life, limits, task] = usageReplies, failed = usageReplies.find(reply => reply?.ok === false);
+        if (failed || !today?.usage || !week?.usage || !life?.usage || !limits?.limits) state.usage = { ...state.usage, problem: String(failed?.error ?? "usage is unavailable") };
+        else state.usage = { today: today.usage, week: week.usage, life: life.usage, limits: limits.limits, at: Date.now(), ...(usageReplies.some(reply => reply?.behind) ? { behind: true } : {}),
+          ...(usageTask !== undefined && task?.usage && state.usageTask === usageTask ? { task: task.usage, taskId: usageTask } : {}) };
+      }
       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) }));
@@ -304,7 +320,16 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       let diagnostic = "";
       // 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) { diagnostic = (diagnostic + terminalText(text)).slice(-2000); stream({ text: terminalText(text).replace(/\t/g, " ").replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
-      cancelChild = run(action.args, output, (code = 0) => { childRunning = false; cancelChild = undefined; if (active) { if (code) notice(diagnostic.trim() || `command exited ${code}`); void refresh(); } }, Math.max(1, columns - 4));
+      cancelChild = run(action.args, output, (code = 0) => {
+        childRunning = false; cancelChild = undefined;
+        if (active) {
+          // #711: a review's result is a notice in panels mode too (where the stream is not on screen): `#372 approved`, or the CLI's own refusal verbatim.
+          const review = reviewResult(action.args, code, diagnostic.trim());
+          if (review) notify(state, review.text, Date.now(), review.tone === "success" ? "success" : "failure");
+          else if (code) notice(diagnostic.trim() || `command exited ${code}`);
+          void refresh(); draw();
+        }
+      }, Math.max(1, columns - 4));
     } catch (error) { childRunning = false; notice(String((error as Error).message)); draw(); }
   };
   const handle = (key: string) => {

package/src/cli/help.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS, deriveAdapterLists, type AdapterDefinition } from "../adapters/registry.ts";
 import { VERSION } from "../version.ts";
 import { paint, wrap, type Span } from "./console-state.ts";
 
@@ -10,7 +11,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub projects [--json] [--color=auto|always|never]", "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 [--profile dev|research|writing|general] [--shadow] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)"],
+    ["ahub init [--profile dev|research|writing|general] [--shadow] [--release-guard] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)"],
     ["ahub --live-test [--project <path|id>] <command> [args...]", "user-authorized operational console delegation; ordinary calls retain peer identity; person-authored content refuses"],
     ["ahub help [command]", "this help, or one command's entries; also --help and -h"],
     ["ahub version | --version", "print the installed version"],
@@ -25,17 +26,23 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub pet --palette <blue|teal|violet|ochre>", "save the floating window's base color to pet.palette in .agenthub/config.local.json"],
     ["ahub sdlc status [task] | explain <task> | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action (person only)"],
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
+    ["ahub sdlc authorize-release <version>", "approve this daemon checkout commit, version and fresh docs (person only; restart revokes)"],
+    ["ahub sdlc release-guard -- <literal git push|gh release create|npm publish argv>", "read-only authorization preflight; init --release-guard installs the tag pre-push hook"],
+    ["ahub sdlc release-guard-hook <remote-name> <remote-url>", "internal pre-push readback; validates version tags and forwards exact stdin on success"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
-    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N --ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
+    ["ahub sdlc accept-departure <task> <head> <reason...>", "accept current plan departures on that exact PR head (person only)"],
+    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N] [--ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
     ["ahub sdlc train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
-    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason>", "assign approved/in-flight work without changing execution"],
+    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason...>", "assign approved/in-flight work without changing execution"],
     ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
     ["ahub backlog groom | return <task> <revision> <reason...>", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
     ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
     ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
-    ["ahub doctor [--json] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
+    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
     ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
+    ["ahub agents [--json]", "show each gated agent CLI's installed version and verdict (verified, in-line, trusted, refused or unknown)"],
+    ["ahub agents trust <id> <version> [--revoke]", "accept an untested agent CLI version on this machine (person only; runtime proofs still run)"],
     ["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] [--json] [--verbose] [--color=auto|always|never]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
@@ -49,15 +56,6 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["Agents", [
     ["ahub <configured-kind> [--mode headless] [--as <instance>] [--session-id <id>] [--print-command | --dry-run]", "start a trusted config.local.json ACP kind (default off roster); native argv is withheld in previews"],
-    ["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] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"],
-    ["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"],
-    ["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.x TUI (1.4.2 verified) in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"],
-    ["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"],
-    ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
-    ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
-    ["ahub claude|codex|kimi|qwen|pi|local --as <instance> [options...]", "start an extra instance of that kind declared under instances in .agenthub/config.local.json"],
     ["ahub role list [--group <group>] | show <id>", "read bounded catalog guidance with layer and content hash"],
     ["ahub role assign <peer> <id> | clear <peer> [<id>]", "person only: add or clear catalog guidance, applied at the next peer start"],
     ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
@@ -71,17 +69,18 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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 roster [--json] [--color=auto|always|never]", "human only: every known peer, participation, start mode and retained work"],
-    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff"],
+    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
     ["ahub settings [list] [--json] | get <key> [--json]", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "human only: change or reload validated settings, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
     ["ahub queue list [--peer <id>] [--json] [--color=auto|always|never]", "inspect durable deliveries"],
     ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "inspect one delivery and revision"],
-    ["ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text> [--revision N]", "resolve a queued or needs_review delivery; --revision binds the displayed row instead of a fresh show"],
+    ["ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text> [--revision N]", "resolve a queued or needs_review delivery; --revision binds the displayed row instead of a fresh show; a queued delivery can be discarded while its peer is busy, and a refusal names its cause"],
+    ["ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes] [--json]", "person only: without --yes count one peer's queued (default) deliveries; with --yes discard them all with the reason, one recorded discard each; other peers' queues are untouched"],
   ]],
   ["Tasks and review", [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person only: read bounded open issues into deduplicated Backlog; never writes GitHub"],
-    ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--json] [--color=auto|always|never]", "the task board; --ready: proposed tasks with nothing left to wait for"],
+    ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--json] [--full] [--color=auto|always|never]", "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] [--backlog] [--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 backlog list | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision>", "person only: stage and plan work, preserve pins/frozen scope and refuse stale edits"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision>", "person only: planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],
@@ -94,7 +93,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "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>]... [--head <sha>]", "give a review verdict on a task"],
+    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>]", "give a review verdict on a task; the person can do the same in ahub console: Tasks, select the task, r, then a (approve) or c (request changes, with a note)"],
     ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
     ["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"],
@@ -102,7 +101,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub remember <text...>", "save a note to the memory all agents share"],
   ]],
   ["Budget", [
-    ["ahub budget [--json] [--color=auto|always|never]", "quota windows per peer, and who is paused until when"],
+    ["ahub budget [--json] [--full] [--color=auto|always|never]", "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 status [id] [--json] [--color=auto|always|never]", "read execution counters and limits"],
@@ -112,6 +111,10 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub turns [peer] [--limit N] [--json] [--color=auto|always|never]", "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] [--color=auto|always|never]", "turns, tokens, messages, overlaps and task events per period"],
+    ["ahub report --dogfood [--since 7d|<iso>] [--json]", "read-only scorecard: flow, quality, cost, delivery, performance and adoption; missing evidence is unknown"],
+    ["ahub usage [--since 7d|<iso>] [--by peer|task|issue|pr|release|day|model] [--json] [--color=auto|always|never]", "tokens per group from the incremental roll-up: the provider's total with and without cache reads, input, output, reasoning and the hub's own count; each number names its source, unknown is never 0"],
+    ["ahub usage limits [--peer <id>] [--limit <n>] [--json] [--color=auto|always|never]", "current quota windows and the history of pauses, resumes and resets"],
+    ["ahub usage total [--json] [--color=auto|always|never]", "lifetime development tokens since the first event, per peer and overall"],
     ["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 addons [--since 30d] [--all] [--json]", "approved tasks with each add-on (claude-mem, ponytail, ripwire, ...) on against off, with intervals; association, not cause"],
@@ -145,7 +148,18 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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 })));
+export function helpEntries(definitions: readonly AdapterDefinition[] = ADAPTERS): readonly HelpEntry[] {
+  const byKind = new Map(definitions.map(definition => [definition.kind, definition]));
+  const order = deriveAdapterLists(definitions).HELP_ORDER;
+  const native = order.flatMap(kind => byKind.get(kind)?.cli.usage ?? []);
+  const instanceKinds = order.filter(kind => byKind.get(kind)?.instances !== undefined);
+  const instances: readonly [string, string] = [`ahub ${instanceKinds.join("|")} --as <instance> [options...]`, "start an extra instance of that kind declared under instances in .agenthub/config.local.json"];
+  return SECTIONS.flatMap(([section, rows]) => {
+    const entries: readonly (readonly [string, string])[] = section === "Agents" ? [rows[0]!, ...native, ...(instanceKinds.length ? [instances] : []), ...rows.slice(1)] : rows;
+    return entries.map(([usage, description]) => ({ section, usage, description }));
+  });
+}
+export const HELP = helpEntries();
 
 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. */
@@ -159,9 +173,10 @@ const DESCRIPTION = 34;
  * (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 {
+export function renderHelp(columns: number, color: boolean, command?: string, definitions?: readonly AdapterDefinition[]): string {
   const width = Math.min(100, Math.max(80, columns || 80));
-  const entries = command === undefined ? HELP : HELP.filter(entry => helpCommands(entry).includes(command));
+  const model = definitions === undefined ? HELP : helpEntries(definitions);
+  const entries = command === undefined ? model : model.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) {

package/src/cli/identity.ts

@@ -14,15 +14,17 @@ export const LIVE_TEST_PERSON_REFUSAL = "live-test cannot write person-attribute
 
 /** Person verdicts and user-authored workflow content are never delegated. */
 export function liveTestRefusal(command: string, args: readonly string[], context: { repairedFresh?: boolean } = {}): boolean {
-  if (command === "sdlc" && (args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) return true;
+  if (command === "sdlc" && (args[0] === "authorize-release" || args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   const sub = command === "recovery" ? recoveryAction(args) : args.find(arg => arg !== "--json");
   return ["task", "role", "goal"].includes(command)
     || (command === "backlog" && sub !== "list") || (command === "release" && !["list", "show"].includes(sub ?? ""))
     || (command === "memory" && sub !== "graph")
     || (command === "recovery" && (sub === "reattach" || sub === "dispose" && context.repairedFresh === true))
-    || (command === "board" && args[0] === "import") || (command === "sdlc" && (args[0] === "record" || args[0] === "accept"))
-    || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet";
+    || (command === "board" && args[0] === "import") || (command === "sdlc" && (args[0] === "record" || args[0] === "accept" || args[0] === "accept-departure"))
+    || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet"
+    // #691: trusting an untested agent CLI version is the person's consent, never a delegated live-test operation.
+    || (command === "agents" && !args.every(arg => arg === "--json"));
 }
 
 export type CliIdentity =
@@ -59,6 +61,7 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
   if (command === "pet" && args.includes("--window")) return "console";
   if (command === "permission" || command === "stop" || command === "watch") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
+  if (command === "sdlc" && ["release-guard", "release-guard-hook"].includes(args[0] ?? "")) return "allowed";
   if (command === "role") return ["list", "show"].includes(args[0] ?? "") ? "allowed" : "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -66,6 +69,8 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
     return "console";
   }
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
+  // #691: reading agent CLI versions is harmless; trusting an untested version on this machine is a person's.
+  if (command === "agents") return args.every(arg => arg === "--json") ? "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";
   // #258: reading hub memory is harmless; promote, demote, forget, supersede and rebuild are a person's.
@@ -78,7 +83,7 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
   if (native?.cli.authority === "person") return "console";
   if (native || ["pause", "resume"].includes(command)) return "conductor";
   if (command === "board" && args[0] === "import") return "console";
-  if (["help", "version", "--version", "completion", "say", "status", "pet", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
+  if (["help", "version", "--version", "completion", "say", "status", "pet", "board", "report", "usage", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
   return "console";
 }
 
@@ -87,14 +92,32 @@ export function cliCommandLabel(command: string, args: readonly string[], catalo
   if (command === "backlog") return ["list", "add", "pull", "pull-ready", "split", "return", "plan", "pin", "undo"].includes(args[0] ?? "") ? `backlog ${args[0]}` : "backlog";
   if (command === "board" && args[0] === "import") return "board import";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
-  if (!(catalog?.definitionOf(command) ?? definitionOf(command)) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
-  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench"].includes(command)) {
+  if (!(catalog?.definitionOf(command) ?? definitionOf(command)) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor", "agents"].includes(command)) return "unknown";
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench", "agents"].includes(command)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
-    if (sub && ["propose", "show", "assign", "unassign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take"].includes(sub)) return `${command} ${sub}`;
+    if (sub && ["propose", "show", "assign", "unassign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "discard", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take", "trust"].includes(sub)) return `${command} ${sub}`;
   }
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }
 
+/**
+ * #711: a hub refusal that only the person or the task's own reviewer could have avoided ("only its reviewer (user) or the console user can do that",
+ * "only the person may ..."). The wording is the hub's, so this reads it and never invents it: anything else gets no extra line.
+ */
+export const personOnlyRefusal = (error: string): boolean => /\bonly\b[^.]*\b(?:console user|the person)\b/i.test(error);
+
+/**
+ * #711: the extra stderr line for an agent shell that was refused something only the person may do. The refusal itself and the authority are unchanged: this only
+ * says why the shell was treated as an agent and where to act as the person. `undefined` for the console identity and for any refusal that is not person-only.
+ */
+export function agentShellCause(identity: CliIdentity, error: string, env: Readonly<Record<string, string | undefined>> = process.env): string | undefined {
+  if (identity.role !== "tools" || !personOnlyRefusal(error)) return undefined;
+  const markers = ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"].filter(name => env[name] !== undefined);
+  const set = markers.length ? `${markers.join(" and ")} ${markers.length === 1 ? "is" : "are"} set` : "an agent marker is set";
+  const task = /\btask #(\d+)\b/.exec(error)?.[1];
+  return `This shell runs as agent "${identity.peer}" (${set}), not as you. Run the command in your own terminal, or use the ahub console: ${task ? `Tasks, select #${task}, r` : "Tasks, select the task, r"}.`;
+}
+
 export function peerCommandRefusal(peer: string, command: string, env: Readonly<Record<string, string | undefined>> = process.env): string {
   const markers = ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "AGENTHUB_PEER_ID", "CODEX_THREAD_ID"].filter(name => env[name] !== undefined);
   return `${peer} cannot run ahub ${command}; the person runs it in ahub console or a terminal. Refused because inherited agent markers${markers.length ? ` (${markers.join(", ")})` : ""} identify this shell as an agent. A ! command in an agent session runs as that agent; use a separate terminal outside the agent session`;