@staix/agent-hub 0.13.0 → 0.14.0

package/plugins/agent-hub/server.js

@@ -1224,13 +1224,13 @@ var DEFAULT_WATCHDOG_MS = 300000;
 // src/adapters/reviewer-print.ts
 import { spawn as spawn2 } from "child_process";
 import { randomUUID as randomUUID2 } from "crypto";
-var MAX_REVIEW_FRAME_BYTES, MAX_REVIEW_OUTPUT_BYTES, GroupCleanupError, reviewTarget = (env) => {
+var ReviewerUnavailableError, MAX_REVIEW_FRAME_BYTES, MAX_REVIEW_OUTPUT_BYTES, GroupCleanupError, reviewTarget = (env) => {
   const task = reviewTask(env);
   if (task === undefined || env.private)
     return;
   const revision = Number(env.refs?.reviewRevision);
   return { task, ...typeof env.refs?.commit === "string" ? { head: env.refs.commit } : {}, ...Number.isSafeInteger(revision) && revision > 0 ? { flowRevision: revision } : {} };
-}, remainingFailures = (batch, start, cause) => batch.targets.slice(start).flatMap((target) => target ? [{ ...target, cause }] : []), reviewTask = (env) => {
+}, remainingFailures = (batch, start, cause, why) => batch.targets.slice(start).flatMap((target) => target ? [{ ...target, cause, ...why ? { causeClass: why.causeClass, ...why.causeDetail ? { causeDetail: why.causeDetail } : {} } : {} }] : []), reviewTask = (env) => {
   if (env.from !== HUB || env.kind !== "review")
     return;
   const id = Number(env.refs?.task);
@@ -1239,6 +1239,15 @@ var MAX_REVIEW_FRAME_BYTES, MAX_REVIEW_OUTPUT_BYTES, GroupCleanupError, reviewTa
 var init_reviewer_print = __esm(() => {
   init_child_process();
   init_envelope();
+  ReviewerUnavailableError = class ReviewerUnavailableError extends Error {
+    causeClass;
+    detail;
+    constructor(message, causeClass, detail) {
+      super(message);
+      this.causeClass = causeClass;
+      this.detail = detail;
+    }
+  };
   MAX_REVIEW_FRAME_BYTES = 256 * 1024;
   MAX_REVIEW_OUTPUT_BYTES = 4 * 1024 * 1024;
   GroupCleanupError = class GroupCleanupError extends Error {
@@ -1404,7 +1413,9 @@ var init_reviewer_print = __esm(() => {
             return;
           }
           failure = { state: started ? "needs_review" : "failed_safe", reason: `reviewer could not start: ${error.message}` };
-          reroute.push(...remainingFailures(batch, index, "start_failed"));
+          const why = error instanceof ReviewerUnavailableError ? { causeClass: error.causeClass, causeDetail: error.detail } : { causeClass: "unknown" };
+          this.opts.log?.(`[${this.id}] review of task #${task} could not start [cause: ${why.causeClass}]`);
+          reroute.push(...remainingFailures(batch, index, "start_failed", why));
           batch.next = envs.length;
           break;
         }
@@ -1476,12 +1487,12 @@ var init_reviewer_print = __esm(() => {
           ...task === undefined ? {} : { task }
         });
         if ("unavailable" in launch)
-          throw new Error(launch.unavailable);
+          throw new ReviewerUnavailableError(launch.unavailable, launch.causeClass ?? "unknown", launch.detail);
         const proof = launch.isolation;
         const policy = this.opts.backend.nativePolicy ? proof?.enforcement === "native-policy" && proof.freshSession === true && proof.hubToolsOnly === true : proof?.strictMcp === true && proof.ephemeral === true;
         if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || !policy || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length) {
           await launch.cleanup?.();
-          throw new Error("reviewer isolation is unavailable or preparation was cancelled");
+          throw new ReviewerUnavailableError("reviewer isolation is unavailable or preparation was cancelled", "unknown");
         }
         return launch;
       })();
@@ -1525,7 +1536,7 @@ ${facts}` : ""}`;
       try {
         launch = await this.prepare(randomUUID2(), input, task, mcp?.config);
         if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false)
-          throw new Error("reviewer isolation or admission changed before child spawn");
+          throw new ReviewerUnavailableError("reviewer isolation or admission changed before child spawn", launch.current?.() === false ? "binary" : "unknown");
         this.receipt = launch.isolation;
         const [cmd, ...prefix] = launch.command;
         let quota = false;
@@ -1916,6 +1927,7 @@ function ownServer(text) {
 }
 async function prepare(ctx) {
   let root;
+  let leg = "binary", timedOut = false;
   try {
     const cwd = realPath(ctx.cwd), env = peerChildEnv(ctx.peer), bound = resolveCommand(ctx, cwd);
     const initialBinaryMetadata = bound.files.map(metadata).join(";");
@@ -1931,6 +1943,8 @@ async function prepare(ctx) {
     };
     const run = (args, capture = true, maxBytes = CAP) => new Promise((resolveOutput, reject) => {
       if (ctx.signal.aborted || performance.now() >= deadline) {
+        if (!ctx.signal.aborted)
+          timedOut = true;
         reject(new Error("metadata deadline"));
         return;
       }
@@ -1941,7 +1955,11 @@ async function prepare(ctx) {
         failed = true;
         finish(null);
       };
-      const timer = setTimeout(stop, Math.max(1, Math.min(2000, deadline - performance.now())));
+      const timer = setTimeout(() => {
+        if (!ctx.signal.aborted)
+          timedOut = true;
+        stop();
+      }, Math.max(1, Math.min(2000, deadline - performance.now())));
       ctx.signal.addEventListener("abort", stop, { once: true });
       const finish = async (code) => {
         if (settled)
@@ -1985,15 +2003,19 @@ async function prepare(ctx) {
         finish(code);
       });
     });
+    leg = "version";
     const verdict = assessVersion("codex-review", COMPAT["codex-review"].parse(await run(["--version"])));
     if (!verdict.ok)
       throw new VersionRefusal(verdict.reason);
     const version = verdict.version;
+    leg = "mcp_inventory";
     if (Buffer.byteLength(ctx.mcpConfig) > CAP || ctx.privatePaths.length > 128)
       throw new Error("policy bounds exceeded");
     const hub = ownServer(ctx.mcpConfig);
     const policy = ["-c", "notify=[]", "--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
+    leg = "plugins_hooks_apps";
     proveDisabledFeatures(await run(["features", "list", ...policy]));
+    leg = "mcp_inventory";
     const before = inventory(await run(["mcp", "list", "--json", ...policy]));
     if (before.some((row) => row.name === "agent-hub"))
       throw new Error("ambient hub MCP collision");
@@ -2011,6 +2033,7 @@ async function prepare(ctx) {
     const observedEnv = object2(observedTransport.env ?? {}), intendedEnv = object2(hub.env);
     if (observedTransport.type !== "stdio" || observedTransport.command !== hub.command || JSON.stringify(observedTransport.args ?? []) !== JSON.stringify(hub.args) || Object.keys(observedEnv).length !== Object.keys(intendedEnv).length || Object.entries(intendedEnv).some(([key, value]) => observedEnv[key] !== value))
       throw new Error("hub transport changed");
+    leg = "sandbox_proof";
     root = realPath(mkdtempSync(join5(tmpdir(), "ahub-codex-review-isolation-")));
     const privateFile = join5(root, "private.env"), publicFile = join5(root, "public.txt"), writeFile = join5(root, "write-proof");
     const coreName = join5(root, ".env"), coreStateDir = join5(root, ".agenthub", "state"), coreState = join5(coreStateDir, "private.txt");
@@ -2031,9 +2054,11 @@ async function prepare(ctx) {
     writeFileSync3(globFile, "glob private fixture");
     symlinkSync(globFile, alias);
     const filesystem = { "/": "read", [privateFile]: "deny", [join5(globRoot, "**", "*.env")]: "deny" };
+    leg = "credential_root";
     for (const glob of codexCoreDenyGlobs())
       filesystem[glob] = "deny";
     denyCredentialRoots(filesystem, [...hostCredentialRoots(env, cwd), ...hostCredentialRoots({ HOME: fixtureHome }, cwd)], cwd);
+    leg = "sandbox_proof";
     for (const entry of ctx.privatePaths) {
       if (typeof entry !== "string" || !entry || Buffer.byteLength(entry) > 4096 || /\p{Cc}/u.test(entry))
         throw new Error("invalid private path policy");
@@ -2070,6 +2095,7 @@ AHUB_CODEX_HOST_KUBE_DENIED
 AHUB_CODEX_HOST_DOCKER_DENIED
 AHUB_CODEX_HOST_ALIAS_DENIED` || existsSync2(writeFile))
       throw new Error("native sandbox isolation unverified");
+    leg = "binary";
     if (!current())
       throw new Error("binary or config changed during proof");
     const cleanupRoot = root;
@@ -2104,12 +2130,12 @@ AHUB_CODEX_HOST_ALIAS_DENIED` || existsSync2(writeFile))
       } catch {}
     }
     if (error instanceof VersionRefusal)
-      return { unavailable: error.message };
+      return { unavailable: error.message, causeClass: "version" };
     if (error instanceof CredentialRootError) {
       const why = { dangling: "a dangling link", unreadable: "an unreadable path", unsupported: "unsupported syntax or overlapping the checkout" }[error.kind];
-      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)` };
+      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)`, causeClass: "credential_root", detail: `${error.label}: ${why}` };
     }
-    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)" };
+    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)", causeClass: timedOut ? "timeout" : leg };
   }
 }
 var TOOLS, VersionRefusal, CAP, MAX_SERVERS = 64, digest = (value) => createHash2("sha256").update(value).digest("hex"), inside = (file, root) => {
@@ -7968,6 +7994,19 @@ var init_review_findings = __esm(() => {
   MAX_BYTES2 = 64 * 1024;
 });
 
+// src/hub/sdlc-metrics.ts
+var HOUR = 3600000, SD_FLOOR;
+var init_sdlc_metrics = __esm(() => {
+  SD_FLOOR = {
+    acceptance_to_plan_ms: HOUR / 2,
+    acceptance_to_first_review_ms: HOUR / 2,
+    first_pass_approval: 0.5,
+    rework_rounds: 0.5,
+    first_pass_check: 0.5,
+    stale_head_re_reviews: 0.5
+  };
+});
+
 // src/hub/workflow.ts
 var init_workflow = __esm(() => {
   init_sdlc();
@@ -7984,6 +8023,7 @@ var init_sdlc = __esm(() => {
   init_test_integrity();
   init_plan_conformance();
   init_review_findings();
+  init_sdlc_metrics();
   init_workflow();
   init_child_process();
   init_host_executable();
@@ -8966,7 +9006,8 @@ var init_hub_tools = __esm(() => {
   PLANNER_REVIEW_TOOLS = [
     tool("hub_planner_groom", "Read a bounded planner grooming digest of dependencies, repository-scoped overlaps, WIP and blockers. No board change; unavailable evidence stays unknown.", {}),
     tool("hub_plan_review", "Record a planner review against the task planning revision and host-read issue edit time. Configured planner or person only; never accepts caller issue timestamps.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str2, maxLength: 1000 }, ...costPlanProperties }, ["id", "revision", "reason"]),
-    tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes. S7 owns automatic band proposals.", { repo: str2 }),
+    tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes.", { repo: str2 }),
+    tool("hub_sdlc_metrics", "Read SDLC metrics from board history: time from acceptance to plan, first review and merge, first-pass approval and rework rounds, first-pass CI and same-head reruns, stale-head re-reviews, stalls, and the control band tiers when sdlc.toml sets [bands]. Planner/person only; read-only, no model and no GitHub issue.", { since: str2 }),
     tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Refuses execution/branch/commit evidence; planner or person only.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str2, maxLength: 1000 } }, ["id", "revision", "reason"])
   ];
   TASK_TOOLS.push(...PLANNER_REVIEW_TOOLS);
@@ -9003,7 +9044,7 @@ function safeModelLabel(value) {
 var init_tool_refusal = () => {};
 
 // src/hub/spec-read.ts
-var BODY_LIMIT, RESULT_LIMIT, STDOUT_LIMIT;
+var BODY_LIMIT, RESULT_LIMIT, STDOUT_LIMIT, NOT_A_REPOSITORY;
 var init_spec_read = __esm(() => {
   init_tool_refusal();
   init_host_executable();
@@ -9011,6 +9052,7 @@ var init_spec_read = __esm(() => {
   BODY_LIMIT = 64 * 1024;
   RESULT_LIMIT = 80 * 1024;
   STDOUT_LIMIT = 512 * 1024;
+  NOT_A_REPOSITORY = new Set(["pr", "pull", "issue", "issues", "task", "tasks", "bug", "fix", "phase", "step", "item", "ticket", "gh", "id", "no", "nr", "p", "s", "t", "u"]);
 });
 
 // src/models/route/config.ts
@@ -9945,6 +9987,23 @@ async function runCodexEntry(ctx) {
   const peer = ctx.instance ?? "codex";
   const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, exec } = ctx;
   const { launcherPreview, buildLaunch, readControl, prepareTerminalLaunch, registerTerminalLaunch } = ctx.helpers;
+  if (ctx.hubStarted) {
+    if (args.includes("--print-command") || args.includes("--dry-run"))
+      return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
+    const hub = await connect();
+    try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition);
+      if (warning)
+        console.error(warning);
+      const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      if (res.ok !== true)
+        fail(String(res.error ?? `${peer} was not started`));
+    } finally {
+      hub.close();
+    }
+    return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
+  }
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try {
       return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2));
@@ -11179,7 +11238,7 @@ var init_builtin_metadata = __esm(() => {
         ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"])
       },
       identity: { mcp: "channel-plugin" },
-      instances: { mode: "external", roles: ["reviewer", "planner"] },
+      instances: { mode: "external", roles: ["planner", "implementer", "verifier", "reviewer"] },
       attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
       permission: { grants: {
         ask: "Claude's own permission rules decide",
@@ -19574,10 +19633,11 @@ init_git();
 
 // src/hub/tasks.ts
 init_spec_read();
+init_sdlc_metrics();
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.13.0",
+  version: "0.14.0",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -19925,19 +19985,29 @@ function validateInstances(raw, catalog) {
     const unavailableReviewer = freshReviewer && !!(definition.reviewerVariant ?? definition).reviewer?.unavailable;
     if (!unavailableReviewer && runtime.instances?.mode !== "external" && !supportsHeadlessInstances(runtime))
       return fail4(`${path}.kind`, definition.reviewerVariant ? 'unsupported; this kind only declares headless reviewer instances with roles exactly ["reviewer"]' : "unsupported; explicit external instance policy or a headless instance policy with a headless factory is required");
+    if (declaredRoles.includes("planner") && definition.projection?.plannerEligible !== true)
+      return fail4(`${path}.roles`, "this kind cannot plan");
     if (external) {
       const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
       if (entry.start_mode && definition.reviewerVariant) {
+        const reviewerRoles = declared.length === 1 && declared[0] === "reviewer";
+        if (!reviewerRoles && declared.includes("implementer") && declared.every((role) => role === "implementer" || role === "verifier"))
+          return fail4(`${path}.start_mode`, "headless Claude implementer is not available in this release");
+        if (!reviewerRoles)
+          return fail4(`${path}.roles`, 'a headless channel-kind instance is a reviewer: roles must be exactly ["reviewer"]');
         if (entry.worktree)
           return fail4(path, "a headless reviewer reads the project checkout: worktree is not supported");
-        if (declared.length !== 1 || declared[0] !== "reviewer")
-          return fail4(`${path}.roles`, 'a headless channel-kind instance is a reviewer: roles must be exactly ["reviewer"]');
       } else {
-        if (entry.start_mode || entry.worktree)
-          return fail4(path, `a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles ["reviewer"] and start_mode "headless"`);
+        if (entry.start_mode)
+          return fail4(`${path}.start_mode`, `a channel instance starts only from the person's terminal (ahub <kind> --as <id>); a headless reviewer declares roles ["reviewer"] and start_mode "headless"`);
         const allowed = definition.instances?.roles ?? definition.roles;
         if (!declared.length || declared.some((role) => !allowed.includes(role)))
-          return fail4(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+          return fail4(`${path}.roles`, `a channel instance must declare its roles within: ${allowed.join(", ")}`);
+        const writes = declared.includes("implementer") || declared.includes("verifier");
+        if (writes && !entry.worktree)
+          return fail4(`${path}.worktree`, "an implementer or verifier channel instance needs its own worktree");
+        if (!writes && entry.worktree)
+          return fail4(`${path}.worktree`, "a planner or reviewer channel instance reads the project checkout: worktree is not supported");
       }
     } else {
       const allowed = runtime.instances?.roles;
@@ -19990,7 +20060,8 @@ function effectiveInstanceRoles(id, declarations, policyRoles, catalog) {
     throw new Error(`${id}: no declared native instance`);
   const declaration = declarations && Object.hasOwn(declarations, id) ? declarations[id] : undefined;
   const ownRoles = (key) => Object.hasOwn(policyRoles, key) ? policyRoles[key] : undefined;
-  return [...declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles];
+  const roles = declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles;
+  return roles.filter((role) => role !== "planner" || definition.projection?.plannerEligible === true);
 }
 
 // src/hub/instance-config.ts

package/src/adapters/codex-review-isolation.ts

@@ -8,7 +8,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { realPath } from "../hub/project.ts";
-import type { ReviewerBackend, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
+import type { ReviewerBackend, ReviewerCauseClass, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
 
 const TOOLS = ["hub_review", "hub_task_show"];
 /** A version refusal names only versions and a command, so the daemon may show it (#691). */
@@ -176,8 +176,10 @@ function ownServer(text: string): Record<string, unknown> {
 }
 
 /** All reads are model-free and bounded; stdout/config/env values never become diagnostic text. */
-async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }> {
+async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string; causeClass?: ReviewerCauseClass; detail?: string }> {
   let root: string | undefined;
+  // #722: the proof leg being run, so a refusal names a class and never text from the native CLI. `timedOut` is set by `run` only.
+  let leg: ReviewerCauseClass = "binary", timedOut = false;
   try {
     const cwd = realPath(ctx.cwd), env = peerChildEnv(ctx.peer), bound = resolveCommand(ctx, cwd);
     const initialBinaryMetadata = bound.files.map(metadata).join(";");
@@ -191,12 +193,12 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
       return bound.files.map(metadata).join(";") === initialBinaryMetadata;
     };
     const run = (args: readonly string[], capture = true, maxBytes = CAP) => new Promise<string>((resolveOutput, reject) => {
-      if (ctx.signal.aborted || performance.now() >= deadline) { reject(new Error("metadata deadline")); return; }
+      if (ctx.signal.aborted || performance.now() >= deadline) { if (!ctx.signal.aborted) timedOut = true; reject(new Error("metadata deadline")); return; }
       const [cmd, ...prefix] = bound.command;
       const child = spawn(cmd!, [...prefix, ...args], { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
       let output = "", bytes = 0, failed = false, settled = false;
       const stop = () => { failed = true; void finish(null); };
-      const timer = setTimeout(stop, Math.max(1, Math.min(2000, deadline - performance.now())));
+      const timer = setTimeout(() => { if (!ctx.signal.aborted) timedOut = true; stop(); }, Math.max(1, Math.min(2000, deadline - performance.now())));
       ctx.signal.addEventListener("abort", stop, { once: true });
       const finish = async (code: number | null) => {
         if (settled) return; settled = true; clearTimeout(timer); ctx.signal.removeEventListener("abort", stop);
@@ -211,14 +213,18 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
       child.once("close", code => { void finish(code); });
     });
     // #691: the verified versions and the person's trust live in compat.ts; every proof below still runs after trust.
+    leg = "version";
     const verdict = assessVersion("codex-review", COMPAT["codex-review"].parse(await run(["--version"])));
     if (!verdict.ok) throw new VersionRefusal(verdict.reason);
     const version = verdict.version;
+    leg = "mcp_inventory";
     if (Buffer.byteLength(ctx.mcpConfig) > CAP || ctx.privatePaths.length > 128) throw new Error("policy bounds exceeded");
     const hub = ownServer(ctx.mcpConfig);
     // Apps creates a runtime MCP server outside the configured inventory; independently pin and read back its gate.
     const policy = ["-c", "notify=[]", "--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
+    leg = "plugins_hooks_apps";
     proveDisabledFeatures(await run(["features", "list", ...policy]));
+    leg = "mcp_inventory";
     const before = inventory(await run(["mcp", "list", "--json", ...policy]));
     if (before.some(row => row.name === "agent-hub")) throw new Error("ambient hub MCP collision");
     const servers: Record<string, unknown> = Object.assign(Object.create(null), { "agent-hub": hub });
@@ -232,6 +238,7 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     const observedEnv = object(observedTransport.env ?? {}), intendedEnv = object(hub.env);
     if (observedTransport.type !== "stdio" || observedTransport.command !== hub.command || JSON.stringify(observedTransport.args ?? []) !== JSON.stringify(hub.args) || Object.keys(observedEnv).length !== Object.keys(intendedEnv).length || Object.entries(intendedEnv).some(([key, value]) => observedEnv[key] !== value)) throw new Error("hub transport changed");
     // A real native sandbox probes a fresh private fixture: the model never sees these files.
+    leg = "sandbox_proof";
     root = realPath(mkdtempSync(join(tmpdir(), "ahub-codex-review-isolation-")));
     const privateFile = join(root, "private.env"), publicFile = join(root, "public.txt"), writeFile = join(root, "write-proof");
     const coreName = join(root, ".env"), coreStateDir = join(root, ".agenthub", "state"), coreState = join(coreStateDir, "private.txt");
@@ -245,8 +252,10 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     writeFileSync(privateFile, "private fixture"); writeFileSync(publicFile, "public fixture"); writeFileSync(globFile, "glob private fixture");
     symlinkSync(globFile, alias);
     const filesystem: Record<string, string> = { "/": "read", [privateFile]: "deny", [join(globRoot, "**", "*.env")]: "deny" };
+    leg = "credential_root";
     for (const glob of codexCoreDenyGlobs()) filesystem[glob] = "deny";
     denyCredentialRoots(filesystem, [...hostCredentialRoots(env, cwd), ...hostCredentialRoots({ HOME: fixtureHome }, cwd)], cwd);
+    leg = "sandbox_proof";
     for (const entry of ctx.privatePaths) {
       if (typeof entry !== "string" || !entry || Buffer.byteLength(entry) > 4096 || /\p{Cc}/u.test(entry)) throw new Error("invalid private path policy");
       // Native Seatbelt supports *, ?, and closed character classes, not brace alternatives.
@@ -268,6 +277,7 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     const script = 'if /bin/cat "$1" >/dev/null 2>&1; then echo AHUB_CODEX_PUBLIC_READ; fi; if /bin/cat "$2" >/dev/null 2>&1; then exit 12; else echo AHUB_CODEX_PRIVATE_DENIED; fi; if (echo no > "$3") 2>/dev/null; then exit 13; else echo AHUB_CODEX_WRITE_DENIED; fi; if /bin/cat "$4" >/dev/null 2>&1; then exit 14; else echo AHUB_CODEX_GLOB_PRIVATE_DENIED; fi; if /bin/cat "$5" >/dev/null 2>&1; then exit 15; else echo AHUB_CODEX_ALIAS_PRIVATE_DENIED; fi; if /bin/cat "$6" >/dev/null 2>&1; then exit 16; else echo AHUB_CODEX_CORE_NAME_DENIED; fi; if /bin/cat "$7" >/dev/null 2>&1; then exit 17; else echo AHUB_CODEX_CORE_STATE_DENIED; fi; if /bin/cat "$8" >/dev/null 2>&1; then exit 18; else echo AHUB_CODEX_HOST_CONFIG_DENIED; fi; if /bin/cat "$9" >/dev/null 2>&1; then exit 19; else echo AHUB_CODEX_HOST_KUBE_DENIED; fi; if /bin/cat "${10}" >/dev/null 2>&1; then exit 20; else echo AHUB_CODEX_HOST_DOCKER_DENIED; fi; if /bin/cat "${11}" >/dev/null 2>&1; then exit 21; else echo AHUB_CODEX_HOST_ALIAS_DENIED; fi';
     const proof = await run(["sandbox", "-P", "ahub-review", "-C", cwd, ...policy, ...permissions, "/bin/sh", "-c", script, "proof", publicFile, privateFile, writeFile, globFile, alias, coreName, coreState, hostConfig, hostKube, hostDocker, hostAlias]);
     if (proof.trim() !== "AHUB_CODEX_PUBLIC_READ\nAHUB_CODEX_PRIVATE_DENIED\nAHUB_CODEX_WRITE_DENIED\nAHUB_CODEX_GLOB_PRIVATE_DENIED\nAHUB_CODEX_ALIAS_PRIVATE_DENIED\nAHUB_CODEX_CORE_NAME_DENIED\nAHUB_CODEX_CORE_STATE_DENIED\nAHUB_CODEX_HOST_CONFIG_DENIED\nAHUB_CODEX_HOST_KUBE_DENIED\nAHUB_CODEX_HOST_DOCKER_DENIED\nAHUB_CODEX_HOST_ALIAS_DENIED" || existsSync(writeFile)) throw new Error("native sandbox isolation unverified");
+    leg = "binary";
     if (!current()) throw new Error("binary or config changed during proof");
     const cleanupRoot = root;
     const launchProfile = digest(toml({ profile, servers, policy }));
@@ -279,12 +289,13 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
   } catch (error) {
     if (root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* unavailable remains refused */ } }
     // Name only the path class of an unusable credential root so a stale ~/.docker link is fixable; never a path or contents.
-    if (error instanceof VersionRefusal) return { unavailable: error.message };
+    if (error instanceof VersionRefusal) return { unavailable: error.message, causeClass: "version" };
     if (error instanceof CredentialRootError) {
       const why = { dangling: "a dangling link", unreadable: "an unreadable path", unsupported: "unsupported syntax or overlapping the checkout" }[error.kind];
-      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)` };
+      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)`, causeClass: "credential_root", detail: `${error.label}: ${why}` };
     }
-    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)" };
+    // A timeout is a proof command that ran out of time, whichever leg it was on; every other refusal names the leg that was running.
+    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)", causeClass: timedOut ? "timeout" : leg };
   }
 }
 

package/src/adapters/definitions/builtin-metadata.ts

@@ -89,7 +89,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
-    identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["reviewer", "planner"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
+    identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["planner", "implementer", "verifier", "reviewer"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
     // Approval enforcement belongs to the verified native transport and host permission gate.
     permission: { grants: { ask: "Claude's own permission rules decide",
       "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",

package/src/adapters/definitions/native-cli-entry-codex.ts

@@ -5,6 +5,19 @@ export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "codex";
   const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, exec } = ctx;
   const { launcherPreview, buildLaunch, readControl, prepareTerminalLaunch, registerTerminalLaunch } = ctx.helpers;
+  if (ctx.hubStarted) {
+    // #720: the hub starts a headless reviewer (a fresh Codex per review); nothing runs in this terminal, so there is no TUI launch,
+    // no terminal recovery and no exec. Launch arguments were already refused by instanceLaunchArguments.
+    if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
+    const hub = await connect();
+    try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
+      const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      if (res.ok !== true) fail(String(res.error ?? `${peer} was not started`));
+    } finally { hub.close(); }
+    return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
+  }
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }

package/src/adapters/reviewer-print.ts

@@ -6,6 +6,28 @@ import { BasePeer } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import type { ReviewerMcpSession } from "./reviewer-mcp.ts";
 
+/** #722: the closed list of legs a reviewer's per-review start can fail on. A class names a leg, never a path, content or token. */
+export const REVIEWER_CAUSE_CLASSES = ["version", "binary", "mcp_inventory", "plugins_hooks_apps", "sandbox_proof", "credential_root", "timeout", "unknown"] as const;
+export type ReviewerCauseClass = typeof REVIEWER_CAUSE_CLASSES[number];
+const REVIEWER_CAUSE_HINT: Record<ReviewerCauseClass, string> = {
+  version: "the CLI version is neither verified nor trusted; see ahub agents",
+  binary: "the CLI binary or a watched config file could not be bound, or changed during the proof; check the configured binary and retry",
+  mcp_inventory: "the MCP server inventory or the hub server entry did not match the proof",
+  plugins_hooks_apps: "plugins, hooks or apps could not be proven disabled",
+  sandbox_proof: "the native sandbox proof did not pass",
+  credential_root: "a host credential root is unusable; remove or repair it",
+  timeout: "a proof command timed out",
+  unknown: "unclassified; inspect hub.log",
+};
+/** The one wording for the unavailable reason, the log and `ahub status`. `detail` is only ever a credential-root path class. */
+export function reviewerUnavailableReason(cause: ReviewerCauseClass, detail?: string): string {
+  return `reviewer isolation unavailable [cause: ${cause}]: ${REVIEWER_CAUSE_HINT[cause]}${detail ? ` (${detail})` : ""}`;
+}
+/** A prepare refusal that carries its class to the host; the message stays the backend's own text. */
+export class ReviewerUnavailableError extends Error {
+  constructor(message: string, readonly causeClass: ReviewerCauseClass, readonly detail?: string) { super(message); }
+}
+
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
   backend: string;
@@ -51,7 +73,7 @@ export interface ReviewerBackend {
   id: string;
   taskMcp?: true;
   nativePolicy?: true;
-  prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }>;
+  prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string; causeClass?: ReviewerCauseClass; detail?: string }>;
   usage?(event: unknown): ReviewerPrintUsage | undefined;
   failure?(event: unknown): "quota" | undefined;
 }
@@ -60,6 +82,9 @@ export interface ReviewerFailure {
   head?: string;
   flowRevision?: number;
   cause: "start_failed" | "quota" | "no_verdict";
+  /** Only for `start_failed`: the leg that refused (#722). */
+  causeClass?: ReviewerCauseClass;
+  causeDetail?: string;
 }
 
 export interface ReviewerReviewBinding { readonly head?: string; readonly flowRevision?: number }
@@ -93,8 +118,8 @@ const reviewTarget = (env: Envelope): ReviewTarget | undefined => {
   const revision = Number(env.refs?.reviewRevision);
   return { task, ...(typeof env.refs?.commit === "string" ? { head: env.refs.commit } : {}), ...(Number.isSafeInteger(revision) && revision > 0 ? { flowRevision: revision } : {}) };
 };
-const remainingFailures = (batch: ReviewBatch, start: number, cause: ReviewerFailure["cause"]): ReviewerFailure[] =>
-  batch.targets.slice(start).flatMap(target => target ? [{ ...target, cause }] : []);
+const remainingFailures = (batch: ReviewBatch, start: number, cause: ReviewerFailure["cause"], why?: { causeClass: ReviewerCauseClass; causeDetail?: string }): ReviewerFailure[] =>
+  batch.targets.slice(start).flatMap(target => target ? [{ ...target, cause, ...(why ? { causeClass: why.causeClass, ...(why.causeDetail ? { causeDetail: why.causeDetail } : {}) } : {}) }] : []);
 const reviewTask = (env: Envelope): number | undefined => {
   if (env.from !== HUB || env.kind !== "review") return undefined;
   const id = Number(env.refs?.task);
@@ -225,7 +250,9 @@ export class ReviewerPrintPeer extends BasePeer {
         }
         // Once an earlier review in this batch ran, the batch had effects: hold it for a person, never requeue it.
         failure = { state: started ? "needs_review" : "failed_safe", reason: `reviewer could not start: ${(error as Error).message}` };
-        reroute.push(...remainingFailures(batch, index, "start_failed"));
+        const why = error instanceof ReviewerUnavailableError ? { causeClass: error.causeClass, causeDetail: error.detail } : { causeClass: "unknown" as const };
+        this.opts.log?.(`[${this.id}] review of task #${task} could not start [cause: ${why.causeClass}]`);
+        reroute.push(...remainingFailures(batch, index, "start_failed", why));
         batch.next = envs.length;
         break;
       }
@@ -273,14 +300,14 @@ export class ReviewerPrintPeer extends BasePeer {
         mcpConfig: this.opts.backend.taskMcp ? (mcpConfig ?? '{"mcpServers":{}}') : this.opts.mcpConfig,
         systemPrompt: this.opts.systemPrompt, privatePaths: this.opts.privatePaths ?? [], command: this.opts.command, signal: abort.signal,
         ...(input === undefined ? {} : { input }), ...(task === undefined ? {} : { task }) });
-      if ("unavailable" in launch) throw new Error(launch.unavailable);
+      if ("unavailable" in launch) throw new ReviewerUnavailableError(launch.unavailable, launch.causeClass ?? "unknown", launch.detail);
       const proof = launch.isolation;
       const policy = this.opts.backend.nativePolicy
         ? proof?.enforcement === "native-policy" && proof.freshSession === true && proof.hubToolsOnly === true
         : proof?.strictMcp === true && proof.ephemeral === true;
       if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || !policy || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length) {
         await launch.cleanup?.();
-        throw new Error("reviewer isolation is unavailable or preparation was cancelled");
+        throw new ReviewerUnavailableError("reviewer isolation is unavailable or preparation was cancelled", "unknown");
       }
       return launch;
     })();
@@ -307,7 +334,7 @@ export class ReviewerPrintPeer extends BasePeer {
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
     launch = await this.prepare(randomUUID(), input, task, mcp?.config);
-    if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false) throw new Error("reviewer isolation or admission changed before child spawn");
+    if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation or admission changed before child spawn", launch.current?.() === false ? "binary" : "unknown");
     this.receipt = launch.isolation;
     const [cmd, ...prefix] = launch.command;
     let quota = false;

package/src/cli/help.ts

@@ -35,6 +35,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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"],
@@ -80,7 +81,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["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] [--full] [--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"],

package/src/cli/main.ts

@@ -1295,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...>");