@staix/agent-hub 0.12.45 → 0.14.0

package/src/cli/help.ts

@@ -11,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"],
@@ -26,18 +26,24 @@ 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 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 costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
+    ["ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>]", "read SDLC metrics and control band tiers from board history (planner or person; read-only)"],
     ["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"],
@@ -70,11 +76,12 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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, one line per task at a terminal width; --full: whole titles and SDLC advice; --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"],
@@ -87,7 +94,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>] [--findings <json>]", "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"],
@@ -95,7 +102,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"],
@@ -105,6 +112,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"],

package/src/cli/identity.ts

@@ -14,7 +14,7 @@ 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)
@@ -22,7 +22,9 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
     || (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" || args[0] === "accept-departure"))
-    || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet";
+    || (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`;

package/src/cli/init.ts

@@ -1,9 +1,13 @@
+import { randomUUID } from "node:crypto";
 import { initShadow, repoOf } from "../hub/snapshots.ts";
 import { profileName, projectProfile, resolveProfile, mergeProfileOverrides, type ProfileName } from "../hub/profiles.ts";
 import { JCODE_MCP_FILE } from "./jcode-mcp.ts";
-import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { hubGitSync } from "../hub/git.ts";
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, renameSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { Stats } from "node:fs";
+import { realPath } from "../hub/project.ts";
+import { hubGitArgv, hubGitEnv, hubGitSync } from "../hub/git.ts";
 import { KIMI_MCP_FILE } from "./kimi-mcp.ts";
 import { AGY_PLUGIN_FILES } from "./agy-mcp.ts";
 
@@ -36,8 +40,70 @@ export interface InitChange {
   managedBlock?: "insert" | "replace" | "remove";
 }
 /** Content is internal to apply, never included in a public preview. */
-interface PlannedWrite extends InitChange { next?: string; shadow?: true; }
-function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedWrite[] {
+interface PlannedWrite extends InitChange { next?: string; shadow?: true; directory?: true; executable?: true; moveFrom?: string; expected?: { dev: number; ino: number }; }
+const RELEASE_BEGIN = "<!-- AGENT_HUB_RELEASE_GUARD:BEGIN (managed by `ahub init --release-guard`) -->";
+const RELEASE_END = "<!-- AGENT_HUB_RELEASE_GUARD:END -->";
+const HOOK_MARKER = "# agent-hub managed release pre-push guard";
+const shellQuote = (value: string) => "'" + value.replace(/'/g, "'\"'\"'") + "'";
+
+function releaseBlock(existing: string): string {
+  const block = `${RELEASE_BEGIN}\n${readFileSync(join(TEMPLATES, "release-guard.block.md"), "utf8").trim()}\n${RELEASE_END}`;
+  const start = existing.indexOf("<!-- AGENT_HUB_RELEASE_GUARD:BEGIN"), end = existing.indexOf(RELEASE_END, Math.max(start, 0));
+  if (start >= 0 && end > start) return existing.slice(0, start) + block + existing.slice(end + RELEASE_END.length);
+  if (start >= 0 || existing.includes(RELEASE_END)) throw new Error("release guard instruction markers are incomplete");
+  return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function regularHook(file: string): Stats | undefined {
+  const info = lstatSync(file, { throwIfNoEntry: false });
+  if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) throw new Error("release guard hook must be an unlinked regular file");
+  return info;
+}
+function releaseHookPlan(cwd: string): PlannedWrite[] {
+  for (const scope of [["--local"], ["--global"], []]) {
+    // Read the actual hooksPath without the hardened override masking it. All
+    // other portable Git hardening stays; `git config --get` executes no hook.
+    const argv = hubGitArgv(["config", ...scope, "--get", "core.hooksPath"]);
+    const override = argv.indexOf("core.hooksPath=/dev/null");
+    if (override < 1 || argv[override - 1] !== "-c") throw new Error("release guard Git hardening unavailable");
+    argv.splice(override - 1, 2);
+    const configured = spawnSync(argv[0]!, argv.slice(1), { cwd, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: 3000, maxBuffer: 16 * 1024 });
+    if (configured.status !== 1) throw new Error(configured.status === 0 ? "release guard refuses custom core.hooksPath; no files changed" : "release guard cannot verify core.hooksPath");
+  }
+  const common = hubGitSync(["rev-parse", "--git-common-dir"], { cwd, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: 3000 });
+  if (common.status !== 0 || !common.stdout.trim()) throw new Error("release guard requires a Git repository");
+  const raw = isAbsolute(common.stdout.trim()) ? common.stdout.trim() : resolve(cwd, common.stdout.trim());
+  const own = lstatSync(raw);
+  if (!own.isDirectory() || own.isSymbolicLink()) throw new Error("release guard Git directory must not be a link");
+  const commonDir = realPath(raw), hooks = join(commonDir, "hooks");
+  const parent = lstatSync(hooks, { throwIfNoEntry: false });
+  if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error("release guard hooks directory must not be a link");
+  const hook = join(hooks, "pre-push"), backup = join(hooks, "pre-push.agent-hub-original");
+  const original = regularHook(hook), saved = regularHook(backup);
+  const current = original ? readFileSync(hook, "utf8") : "";
+  const managed = current.startsWith(`#!/bin/sh\n${HOOK_MARKER}\n`);
+  if (!managed && saved) throw new Error("release guard backup is occupied; no files changed");
+  const wrapper = `#!/bin/sh
+${HOOK_MARKER}
+guard_input=$(umask 077; mktemp "\${TMPDIR:-/tmp}/ahub-release-guard.XXXXXX") || exit 1
+trap 'rm -f "$guard_input"' 0
+trap 'exit 1' 1 2 15
+${shellQuote(process.execPath)} ${shellQuote(join(import.meta.dir, "main.ts"))} sdlc release-guard-hook "$1" "$2" >"$guard_input" || exit "$?"
+if [ -x ${shellQuote(backup)} ]; then
+  ${shellQuote(backup)} "$@" <"$guard_input"
+else
+  exit 0
+fi
+`;
+  const plan: PlannedWrite[] = [];
+  if (!parent) plan.push({ action: "create", path: hooks, reason: "create default Git hooks directory", directory: true });
+  if (original && !managed) plan.push({ action: "create", path: backup, reason: "preserve original pre-push hook inode and mode", moveFrom: hook, expected: { dev: original.dev, ino: original.ino } });
+  if (current !== wrapper || original && !(original.mode & 0o111)) plan.push({ action: original ? "modify" : "create", path: hook, reason: "install release authorization pre-push guard", next: wrapper, executable: true });
+  return plan;
+}
+function changes(cwd: string, requested?: ProfileName, shadow = false, releaseGuard = false): PlannedWrite[] {
+  const originalAgents = existsSync(join(cwd, "AGENTS.md")) ? readFileSync(join(cwd, "AGENTS.md"), "utf8") : "";
+  const guarded = releaseGuard || originalAgents.includes("<!-- AGENT_HUB_RELEASE_GUARD:BEGIN");
+  const hooks = guarded ? releaseHookPlan(cwd) : [];
   const repository = shadow ? repoOf(cwd) : undefined;
   if (shadow && repository && !repository.shadow) throw new Error("project already has a Git work tree; shadow mode is for non-git folders");
   if (shadow) {
@@ -80,7 +146,8 @@ function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedW
   }
   const agents = join(cwd, "AGENTS.md");
   const existing = existsSync(agents) ? readFileSync(agents, "utf8") : "";
-  write(agents, upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")), "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
+  const instructions = upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8"));
+  write(agents, guarded ? releaseBlock(instructions) : instructions, "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
   const claude = join(cwd, "CLAUDE.md");
   const own = lstatSync(claude, { throwIfNoEntry: false });
   // The write preserves an existing inode, including AGENTS.md -> CLAUDE.md and hard links.
@@ -105,19 +172,50 @@ function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedW
   }
   if (existsSync(join(cwd, JCODE_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(JCODE_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${JCODE_MCP_FILE}\n`;
   write(ignore, lines, "ignore runtime state and machine-local configuration");
-  return changed;
+  return [...hooks, ...changed];
 }
 /** Read-only metadata, deliberately omitting project/user file contents. */
-export function planInit(cwd: string, profile?: ProfileName, shadow = false): InitChange[] {
-  return changes(cwd, profile, shadow).map(({ next, shadow: _shadow, ...change }) => change);
+export function planInit(cwd: string, profile?: ProfileName, shadow = false, releaseGuard = false): InitChange[] {
+  return changes(cwd, profile, shadow, releaseGuard).map(({ next, shadow: _shadow, directory, executable, moveFrom, expected, ...change }) => change);
 }
 /** Returns the paths it changed, applying the same plan as the preview. */
-export function init(cwd: string, profile?: ProfileName, shadow = false): string[] {
-  const plan = changes(cwd, profile, shadow);
+export function init(cwd: string, profile?: ProfileName, shadow = false, releaseGuard = false): string[] {
+  const plan = changes(cwd, profile, shadow, releaseGuard);
+  // Recheck hook parents and rename identities before any project write.
+  for (const change of plan.filter(change => change.executable || change.moveFrom)) {
+    const parent = lstatSync(dirname(change.path), { throwIfNoEntry: false });
+    if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error("release guard hook parent changed before installation");
+    if (change.moveFrom) {
+      const source = regularHook(change.moveFrom);
+      if (!source || source.dev !== change.expected?.dev || source.ino !== change.expected.ino || lstatSync(change.path, { throwIfNoEntry: false })) throw new Error("release guard hook changed before installation");
+    } else regularHook(change.path);
+  }
   mkdirSync(join(cwd, ".agenthub"), { recursive: true });
   for (const change of plan) {
     if (change.shadow) initShadow(cwd);
+    else if (change.directory) mkdirSync(change.path);
+    else if (change.moveFrom) continue; // Applied atomically with its prepared wrapper below.
     else if (change.action === "delete") unlinkSync(change.path);
+    else if (change.executable) {
+      const parent = lstatSync(dirname(change.path));
+      if (!parent.isDirectory() || parent.isSymbolicLink()) throw new Error("release guard hook parent changed before installation");
+      const current = regularHook(change.path), move = plan.find(row => row.moveFrom === change.path);
+      const temporary = join(dirname(change.path), `.pre-push.${randomUUID()}.tmp`);
+      let moved = false;
+      try {
+        // Prepare bytes before disturbing any existing gate. Refreshing our own
+        // managed hook is one atomic rename, so a failed write leaves it intact.
+        writeFileSync(temporary, change.next!, { mode: 0o755, flag: "wx" });
+        if (move) {
+          if (!current || current.dev !== move.expected?.dev || current.ino !== move.expected.ino || lstatSync(move.path, { throwIfNoEntry: false })) throw new Error("release guard hook changed before installation");
+          renameSync(change.path, move.path); moved = true;
+        }
+        renameSync(temporary, change.path);
+      } catch (error) {
+        if (moved && !lstatSync(change.path, { throwIfNoEntry: false })) renameSync(move!.path, change.path);
+        throw error;
+      } finally { if (lstatSync(temporary, { throwIfNoEntry: false })) unlinkSync(temporary); }
+    }
     else writeFileSync(change.path, change.next!);
   }
   return plan.map(change => change.path);

package/src/cli/main.ts

@@ -1,4 +1,9 @@
 #!/usr/bin/env bun
+import { hubGitSync, hubGitEnv } from "../hub/git.ts";
+import { parseReleaseGuardArgv, parseReleasePushUpdates } from "./sdlc-release-guard.ts";
+import { validReleaseVersion } from "../hub/sdlc-release-authorization.ts";
+import { agentVersions, runAgents } from "./agents.ts";
+import { assessVersion, COMPAT, configuredCommands } from "../adapters/compat.ts";
 import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 import { effectiveInstanceRoles } from "../hub/instances.ts";
 import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
@@ -74,14 +79,17 @@ import { selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
 import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { summarize, summarizeByTask } from "../hub/report.ts";
+import { readDogfood } from "../hub/dogfood-read.ts";
+import { dogfoodSince, formatDogfood } from "../hub/dogfood.ts";
+import { USAGE_GROUPS, LIMITS_MAX } from "../hub/usage-rollup.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
 import { COMPLETION_SHELLS, completionScript } from "./completion.ts";
-import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
+import { agentShellCause, classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
-import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, type DoctorCheck } from "./output.ts";
+import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
@@ -444,7 +452,14 @@ async function taskOp(op: string, a: Record<string, unknown>, throwOnError = fal
   try {
     if (op === "hub_task_cancel" && !hub.features.includes("task_cancel")) fail("this daemon does not support task cancellation; upgrade it first");
     const res = await hub.request({ t: "task", op, args: a }, timeoutMs ?? (op === "github_import" ? 60_000 : 30_000));
-    if (!res.ok) { if (throwOnError) throw new Error(res.error); audit("refused"); fail(res.error); }
+    if (!res.ok) {
+      if (throwOnError) throw new Error(res.error);
+      audit("refused");
+      // #711: an agent shell refused something only the person may do is told why it counts as an agent. The refusal and the authority stay as they were.
+      const cause = agentShellCause(identity, String(res.error));
+      if (cause) console.error(`ahub: ${res.error}\n${cause}`), process.exit(1);
+      fail(res.error);
+    }
     return res.text;
   } finally { if (!connection) hub.close(); }
 }
@@ -885,15 +900,15 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: () => {
-    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow"), ["--profile"], []);
-    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general] [--shadow] [--dry-run --json]");
+    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard"), ["--profile"], []);
+    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general] [--shadow] [--release-guard] [--dry-run --json]");
     const requestedProfile = flags.one["--profile"] === undefined ? undefined : profileName(flags.one["--profile"]);
     if (args.includes("--dry-run")) {
-      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"));
+      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
       return console.log(args.includes("--json") ? JSON.stringify(plan, null, 2) : plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`).join("\n") || "already up to date");
     }
     assertLifecycleAvailable();
-    const changed = init(cwd, requestedProfile, args.includes("--shadow"));
+    const changed = init(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
     registeredProject();
     console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
     const config = projectConfig(), examples = resolveProfile(config.profile, config.profile_overrides).example_checks;
@@ -1006,8 +1021,21 @@ const commands: Record<string, () => Promise<void> | void> = {
         printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
         return;
       }
+      if (operation === "discard") {
+        // #713: the person's bulk clear of one peer's queue. Without --yes it only says how many it would discard.
+        const yes = rest.includes("--yes");
+        const { one, rest: others } = takeFlags(rest.filter((word) => word !== "--yes"), ["--peer", "--reason", "--state"], []);
+        if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
+        if (yes && !one["--reason"]?.trim()) fail("ahub queue discard needs --reason <text> with --yes: it is recorded on every discarded delivery");
+        const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(one["--state"] ? { state: one["--state"] } : {}), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
+        if (!result.ok) fail(result.error);
+        if (options.json) return console.log(JSON.stringify(result, null, 2));
+        if (!yes) return console.log(`${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
+        console.log(`discarded ${result.discarded} of ${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
+        return;
+      }
       const [id, ...flags] = rest;
-      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N]");
+      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N] | discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
         const shown = await hub.request({ t: "queue", op: "show", id });
@@ -1192,6 +1220,50 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   sdlc: async () => {
     const sub = args[0], id = args[1] === undefined ? undefined : Number(args[1]);
+    if (sub === "authorize-release") {
+      if (args.length !== 2 || !validReleaseVersion(args[1])) fail("usage: ahub sdlc authorize-release <version>");
+      const result = hubGitSync(["rev-parse", "--verify", "HEAD"], { cwd, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: 2000 });
+      const commit = result.stdout?.trim();
+      if (result.status !== 0 || !commit || !/^[a-f0-9]{40}$/.test(commit)) fail("candidate commit unavailable");
+      const hub = await connect();
+      try { const reply = await hub.request({ t: "sdlc", op: sub, version: args[1], commit }, 30_000); if (!reply.ok) fail(reply.error); console.log(JSON.stringify(reply.authorization, null, 2)); }
+      finally { hub.close(); }
+      return;
+    }
+    if (sub === "release-guard" || sub === "release-guard-hook") {
+      let original: Buffer | undefined;
+      let request: Record<string, unknown>;
+      if (sub === "release-guard-hook") {
+        if (args.length !== 3) fail("release hook needs its remote name and URL");
+        const chunks: Buffer[] = []; let size = 0;
+        for await (const chunk of process.stdin) { const bytes = Buffer.from(chunk); size += bytes.length; if (size > 128 * 1024) fail("release push inventory exceeds the guard bound"); chunks.push(bytes); }
+        original = Buffer.concat(chunks);
+        let input: string;
+        try { input = new TextDecoder("utf-8", { fatal: true }).decode(original); } catch { fail("release push inventory is not UTF-8"); }
+        const parsed = parseReleasePushUpdates(args[1]!, args[2]!, input);
+        if (!parsed.ok) fail(parsed.reason);
+        // Ordinary branch pushes keep working with the daemon offline.
+        if (!parsed.updates.length) { process.stdout.write(original); return; }
+        request = { t: "sdlc", op: sub, remoteName: parsed.remoteName, remoteUrl: parsed.remoteUrl, stdin: input };
+      } else {
+        if (args[1] !== "--") fail("usage: ahub sdlc release-guard -- git push origin v<version> | gh release create v<version> | npm publish");
+        const argv = args.slice(2), parsed = parseReleaseGuardArgv(argv);
+        if (!parsed.ok) fail(parsed.reason);
+        // Literal preflights cannot attest a command redirected by ambient target selectors.
+        const selectors = ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", ...(parsed.request.kind === "gh-release" ? ["GH_REPO", "GH_HOST"] : []), ...(parsed.request.kind === "npm-publish" ? Object.keys(process.env).filter(key => /^npm_config_(?:prefix|workspace|workspaces|userconfig|globalconfig|registry)$/i.test(key)) : [])];
+        if (selectors.some(key => process.env[key] !== undefined)) fail("release guard refuses ambient target selectors");
+        request = { t: "sdlc", op: sub, argv };
+      }
+      let hub: ControlClient | undefined;
+      try {
+        hub = await connect();
+        const reply = await hub.request(request, 30_000);
+        if (!reply.ok) fail(reply.error ?? "release authorization refused");
+        if (original) process.stdout.write(original); else console.log("release authorization matched");
+      } catch { fail("release authorization unavailable; the daemon must be reachable with a matching person approval"); }
+      finally { hub?.close(); }
+      return;
+    }
     if (sub === "queue" || sub === "release") {
       const repo = args[1], liveIssues = args.slice(2).map(Number);
       if (!repo || args.length > 34 || (sub === "queue" && args.length !== 2) || liveIssues.some(id => !Number.isSafeInteger(id) || id <= 0)) fail("usage: ahub sdlc queue <owner/repository> | release <owner/repository> [live-issue...]");
@@ -1223,6 +1295,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
       return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));
     }
+    if (sub === "metrics") {
+      const flags = takeFlags(args.slice(1), ["--since"], []);
+      if (flags.rest.length) fail("usage: ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>]");
+      return console.log(await taskOp("hub_sdlc_metrics", { ...(flags.one["--since"] !== undefined ? { since: flags.one["--since"] } : {}) }));
+    }
     if (sub === "plan-review") {
       const revision = Number(args[2]);
       if (!Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(revision) || revision < 0 || args.length < 4) fail("usage: ahub sdlc plan-review <task> <revision> <reason...>");
@@ -1703,8 +1780,15 @@ const commands: Record<string, () => Promise<void> | void> = {
     const r = researchReport(records, from);
     console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatResearch(r).join("\n"));
   },
-  report: () => {
+  report: async () => {
     const options = outputOptions();
+    if (args.includes("--dogfood")) {
+      let from: number;
+      try { from = dogfoodSince(args.filter(arg => !arg.startsWith("--color="))); }
+      catch { return fail("usage: ahub report --dogfood [--since 7d|<iso>] [--json]"); }
+      const scorecard = await readDogfood(cwd, stateDir, from);
+      return console.log(options.json ? JSON.stringify(scorecard, null, 2) : formatDogfood(scorecard).join("\n"));
+    }
     const by = args.indexOf("--by");
     if (by >= 0 && args[by + 1] !== "task") return fail("--by takes task");
     const events = readEvents(join(stateDir, "events.jsonl"), since());
@@ -1712,6 +1796,32 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (options.json) return console.log(JSON.stringify(data, null, 2));
     printOutput(renderReport(data, options.columns, Date.now(), by >= 0), options.color);
   },
+  usage: async () => {
+    const options = outputOptions();
+    const rest = outputArguments();
+    const sub = rest[0] !== undefined && !rest[0].startsWith("--") ? rest[0] : undefined;
+    if (sub !== undefined && !["limits", "total"].includes(sub)) fail("usage: ahub usage [--since 7d|<iso>] [--by peer|task|issue|pr|release|day|model] [--json] | limits [--peer <id>] [--limit <n>] [--json] | total [--json]");
+    const flags = sub === undefined ? rest : rest.slice(1);
+    const valueFlags = sub === "limits" ? ["--peer", "--limit"] : sub === undefined ? ["--since", "--by"] : [];
+    for (let i = 0; i < flags.length; i++) {
+      if (!valueFlags.includes(flags[i]!)) fail(`unknown argument ${JSON.stringify(flags[i]!.slice(0, 40))}; run ahub help`);
+      if (flags[++i] === undefined || flags[i]!.startsWith("--")) fail(`${flags[i - 1]} needs a value`);
+    }
+    const value = (flag: string) => { const at = args.indexOf(flag); return at >= 0 ? args[at + 1] : undefined; };
+    const by = value("--by"), peer = value("--peer"), limitText = value("--limit");
+    const limit = limitText === undefined ? undefined : /^\d+$/.test(limitText) ? Number(limitText) : NaN;
+    if (limit !== undefined && !(limit >= 1 && limit <= LIMITS_MAX)) fail(`--limit takes a whole number from 1 to ${LIMITS_MAX}`);
+    if (by !== undefined && !(USAGE_GROUPS as readonly string[]).includes(by)) fail(`--by takes ${USAGE_GROUPS.join(", ")}`);
+    const from = since();
+    const hub = await connect();
+    const reply = await hub.request(sub === "limits" ? { t: "usage", op: "limits", ...(peer ? { peer } : {}), ...(limit !== undefined ? { limit } : {}) } : sub === "total" ? { t: "usage", op: "total" }
+      : { t: "usage", op: "query", by: by ?? "peer", ...(from ? { since: from } : {}) }, 35_000);
+    hub.close();
+    if (!reply.ok) return fail(String(reply.error ?? "usage refused"));
+    if (reply.behind) process.stderr.write("ahub: the usage roll-up is still catching up with the event log: these numbers are partial; run it again in a few seconds\n");
+    if (options.json) return console.log(JSON.stringify(sub === "limits" ? { limits: reply.limits, current: reply.current } : sub === "total" ? reply.total : reply.usage, null, 2));
+    printOutput(sub === "limits" ? renderLimits(reply.limits, reply.current, options.columns) : sub === "total" ? renderTotal(reply.total, options.columns) : renderUsage(reply.usage, options.columns), options.color);
+  },
   facts: async () => {
     if (!args.includes("--hook")) return fail("usage: ahub facts --hook (a Claude Code PreToolUse, PostToolUse and Stop hook)");
     try {
@@ -1949,6 +2059,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     fail("usage: ahub role list [--group <group>] | show <id> | assign <peer> <id> | clear <peer> [<id>]");
   },
+  agents: () => runAgents(args, configuredCommands(loadConfig(cwd)), fail),
+
   doctor: async () => {
     const options = outputOptions();
     if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
@@ -2001,10 +2113,14 @@ const commands: Record<string, () => Promise<void> | void> = {
             [servers.length ? `${servers.length} besides the hub's own would load in the hub-owned jcode (${servers.join(", ")}); jcode has no switch to choose them, so remove them from its config or use another JCODE_HOME` : "",
               unreadable.length ? `unreadable or unsafe, not listed: ${unreadable.join(", ")}` : ""].filter(Boolean).join("; ") || "none besides the hub's own");
         } else {
-          const v = version(probe.command[0]!);
-          row(v === probe.expected, probe.name, v === probe.expected ? probe.confirmed : probe.unconfirmed);
+          const verdict = assessVersion(probe.compat, COMPAT[probe.compat].parse(version(probe.command[0]!) ?? ""));
+          row(verdict.ok ? verdict.state === "verified" || undefined : false, probe.name, verdict.ok ? verdict.note ?? probe.confirmed : `${probe.unconfirmed}: ${verdict.reason}`);
         }
       }
+      // #691: one line for each installed gated CLI that is not on a verified version.
+      for (const agent of agentVersions(configuredCommands(config))) {
+        if (agent.executable && !(agent.verdict.ok && agent.verdict.state === "verified")) row(agent.verdict.ok ? undefined : false, `${agent.id} version`, agent.verdict.ok ? agent.verdict.note ?? agent.verdict.state : agent.verdict.reason);
+      }
       const omni = new OmniRoute(config.omniroute);
       const gateway = await omni.base();
       row(gateway ? true : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? false : undefined, "omniroute", gateway ? `${new URL(gateway).host} healthy` : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? "no candidate reachable (VPN off?); ahub local cannot run" : "not configured: set omniroute.urls in .agenthub/config.local.json (any OpenAI-compatible gateway); ahub local cannot run");