@staix/agent-hub 0.12.45 → 0.14.0

package/src/adapters/definitions/native-cli-preview-qwen.ts

@@ -1,3 +1,4 @@
+import { describe } from "../compat.ts";
 import { join } from "node:path";
 import type { Launch } from "../../cli/launch.ts";
 import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
@@ -16,7 +17,7 @@ export function previewQwen(ctx: NativePreviewContext) {
   if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
   launch = adapter.start.launch!({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
     userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
-  unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
+  unresolved.push({ field: "nativeIdentity", reason: `Qwen Code (${describe("qwen")}) identity and permission modes are checked at ACP initialization; preview starts nothing` });
 
   return finishPreview(ctx, launch, envNames, unresolved, undefined);
 }

package/src/adapters/definitions/qwen-native.ts

@@ -1,16 +1,20 @@
+import { assessVersion } from "../compat.ts";
 import type { PermissionMode } from "../../hub/permission-mode.ts";
 import type { Launch } from "../../cli/launch.ts";
 
 export const QWEN_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "auto-edit", "never-ask": "yolo" };
 
 export class QwenIdentityError extends Error {
-  constructor() { super("Qwen Code 0.25.0 native identity is not verified; check the executable and its advertised ACP version"); }
+  constructor(reason?: string) { super(reason ? `Qwen Code native identity is not verified: ${reason}` : "Qwen Code native identity is not verified; check the executable and its advertised ACP version"); }
 }
 
 export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown, kind?: string): boolean {
   const native = init as { agentInfo?: { name?: unknown; version?: unknown } } | null | undefined;
-  const verified = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
-  if (production && !verified) throw new QwenIdentityError();
+  const identity = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code";
+  // #691: a version refusal carries the compat reason (observed and verified versions, the trust command).
+  const version = identity ? assessVersion("qwen", native?.agentInfo?.version) : undefined;
+  if (production && !version?.ok) throw new QwenIdentityError(version && !version.ok ? version.reason : undefined);
+  const verified = !!version?.ok;
   return verified;
 }
 

package/src/adapters/definitions/qwen.ts

@@ -1,3 +1,4 @@
+import { describe } from "../compat.ts";
 import { runQwenEntry } from "./native-cli-entry-qwen.ts";
 import { previewQwen } from "./native-cli-preview-qwen.ts";
 import { QWEN_DISPLAY } from "./native-display.ts";
@@ -67,7 +68,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   turnEnd: "adapter",
   budget: { account: "qwen" },
   capabilities: { watch: true },
-  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
+  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", `start optional Qwen Code ACP (${describe("qwen")}; roster.qwen, default off)`]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
   display: QWEN_DISPLAY,
   hooks: { recallPlatform: "qwen" },
 };

package/src/adapters/jcode.ts

@@ -1,4 +1,5 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { assessVersion, COMPAT, type CompatVerdict } from "./compat.ts";
 import { createConnection } from "node:net";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -12,21 +13,25 @@ export interface JcodeOptions extends Omit<AcpOptions, "cmd" | "qwen025" | "expe
   command: string[];
   home: string;
   providerProfile?: string;
+  /** The hub peer id this Jcode acts for: "jcode" for the base peer, an instance id for an extra one (#685). */
+  peer?: string;
+  /** Initial native provider (`-p`), passed exactly as the person wrote it (#685). The hub never handles model credentials. */
+  provider?: string;
   /** How long a native steer may take to be acknowledged (#572); default 5 s. */
   steerTimeoutMs?: number;
 }
-export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string): string[] {
+export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string, provider?: string, peer = "jcode"): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
-  return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
-    ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", "agent-hub-jcode"] : ["--mcp-tools", "eager"])];
+  return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []), ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
+    ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", `agent-hub-${peer}`] : ["--mcp-tools", "eager"])];
 }
 export interface JcodeTuiBinding { launchId: string; sessionId: string }
 export type JcodeTuiState = { state: "waiting"; binding: JcodeTuiBinding } |
   { state: "ready"; binding: JcodeTuiBinding; launch: { cmd: string; args: string[]; env: NodeJS.ProcessEnv } };
 
-export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string): string[] {
+export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string, provider?: string): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
-  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev",
+  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []),
     ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : [])];
 }
 
@@ -65,17 +70,8 @@ export class JcodeOptionMismatch extends Error {
   constructor(readonly option: "--session-id" | "--model" | "--provider-profile") { super("Jcode launch options differ from its running session"); }
 }
 const JCODE_OWNED_ENV = { JCODE_DISABLE_CLAUDE_MCP: "1", JCODE_NO_TELEMETRY: "1" } as const;
-/** The oldest native release accepted; its ACP, serve and MCP contract was verified live on 0.98.1 (docs/verification). */
-export const JCODE_MIN_VERSION = "0.98.0";
-/** The first native release assumed to break that contract: the next major. Lower it when a release is shown to break. */
-export const JCODE_BREAKING_VERSION = "1.0.0";
-const release = (version: string) => /^(\d+)\.(\d+)\.(\d+)$/.exec(version)?.slice(1).map(Number);
-const compare = (a: number[], b: number[]) => a[0]! - b[0]! || a[1]! - b[1]! || a[2]! - b[2]!;
-/** A plain release from JCODE_MIN_VERSION up to, not including, JCODE_BREAKING_VERSION; the minor is not pinned (#529). */
-export function jcodeVersionSupported(version: unknown): boolean {
-  const v = typeof version === "string" ? release(version) : undefined;
-  return !!v && compare(v, release(JCODE_MIN_VERSION)!) >= 0 && compare(v, release(JCODE_BREAKING_VERSION)!) < 0;
-}
+/** #691: the verdict lives in `src/adapters/compat.ts` (line, verified versions, the person's trust); never pin here. */
+export const jcodeVersionSupported = (version: unknown): boolean => assessVersion("jcode", version).ok;
 
 /** A native steer the server did not take, with nothing sent: the message may safely stay queued. */
 class SteerRefused extends Error {}
@@ -137,20 +133,56 @@ function nativeSteer(socket: string, cwd: string, sessionId: string, text: strin
 }
 
 /** The wrapper contract preserves every configured prefix argument before the native probe. */
-export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
+export function jcodeVersion(command: string[], cwd: string): CompatVerdict {
   const [bin, ...prefix] = command;
-  if (!bin) return false;
+  if (!bin) return assessVersion("jcode", undefined);
   try {
     const result = spawnSync(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: { ...peerChildEnv("jcode"), ...JCODE_OWNED_ENV }, encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 });
-    if (result.status !== 0) return false;
-    const version = JSON.parse(result.stdout);
-    return jcodeVersionSupported(version.semver);
-  } catch { return false; }
+    return assessVersion("jcode", result.status === 0 ? COMPAT.jcode.parse(result.stdout) : undefined);
+  } catch { return assessVersion("jcode", undefined); }
+}
+export const verifiedJcodeCommand = (command: string[], cwd: string): boolean => jcodeVersion(command, cwd).ok;
+/** Collects at most `cap` bytes; the chunk that would pass it, and every later one, is refused and not kept. */
+export function boundedOutput(cap: number): { push(chunk: Buffer): boolean; text(): string; readonly size: number; readonly overflowed: boolean } {
+  const chunks: Buffer[] = [];
+  let size = 0, overflowed = false;
+  return {
+    push(chunk) { if (overflowed || size + chunk.length > cap) { overflowed = true; return false; } chunks.push(chunk); size += chunk.length; return true; },
+    text: () => Buffer.concat(chunks).toString("utf8"),
+    get size() { return size; },
+    get overflowed() { return overflowed; },
+  };
+}
+/**
+ * The daemon's preflight: the same probe without blocking the event loop (a slow wrapper must not stall peers). The probe owns its
+ * process group: at the deadline, or once stdout passes 64 KiB, the whole group is stopped, descendants included (kimi-review's pattern).
+ */
+export function jcodeVersionAsync(command: string[], cwd: string, timeoutMs = 10_000): Promise<CompatVerdict> {
+  const [bin, ...prefix] = command;
+  if (!bin) return Promise.resolve(assessVersion("jcode", undefined));
+  return new Promise(resolve => {
+    let child: ChildProcess;
+    try { child = spawn(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: { ...peerChildEnv("jcode"), ...JCODE_OWNED_ENV }, detached: true, stdio: ["ignore", "pipe", "ignore"] }); }
+    catch { resolve(assessVersion("jcode", undefined)); return; }
+    const output = boundedOutput(64 * 1024);
+    let done = false;
+    const finish = async (code: number | null) => {
+      if (done) return; done = true; clearTimeout(timer);
+      try { await stopOwnedProcess(child, { group: true }); } catch { resolve(assessVersion("jcode", undefined)); return; }
+      resolve(assessVersion("jcode", code === 0 && !output.overflowed ? COMPAT.jcode.parse(output.text()) : undefined));
+    };
+    const timer = setTimeout(() => { void finish(null); }, timeoutMs);
+    child.once("spawn", () => trackGroup(child));
+    // Chunks after the cap or after settling are drained and discarded, never buffered.
+    child.stdout!.on("data", (bytes: Buffer) => { if (!done && !output.push(bytes)) void finish(null); });
+    child.once("error", () => { void finish(null); });
+    child.once("close", code => { void finish(code); });
+  });
 }
 
 /** Both processes are ours. The user's global daemon and its sockets are never stopped. */
 export class JcodePeer extends AcpPeer {
-  private readonly launchId = crypto.randomUUID();
+  private readonly launchId: string;
   private socketIdentity: { dev: number; ino: number } | undefined;
   private readonly root: string;
   private readonly socket: string;
@@ -161,21 +193,28 @@ export class JcodePeer extends AcpPeer {
 
   constructor(private readonly jcode: JcodeOptions) {
     if (!isAbsolute(jcode.home)) throw new Error("jcode_home must be an absolute native data path");
+    const peer = jcode.peer ?? "jcode";
     jcodeCommand(jcode.command, "acp", "preview", jcode.cwd);
     // The name must end in ".sock": jcode names its debug socket by replacing that suffix, so "s" binds one path twice.
     const root = mkdtempSync(join(tmpdir(), "ahub-jcode-")), socket = join(root, "j.sock");
-    const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile);
-    super("jcode", { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
-    this.root = root; this.socket = socket;
+    const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile, jcode.provider, peer);
+    const launchId = crypto.randomUUID();
+    // The ACP child gets peerChildEnv(this.id): the instance id, so its hub tools act as this peer and never as the base Jcode. The launch id
+    // goes with it: the daemon admits a hub-tools hello for this peer only when it carries the id of this peer's current owned launch (#368).
+    super(peer, { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, AGENTHUB_LAUNCH_ID: launchId, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
+    this.root = root; this.socket = socket; this.launchId = launchId;
   }
 
+  /** True only for the id of this peer's current owned launch, while it is not ending: the proof a hub-tools hello must carry (#368). */
+  ownsLaunch(launchId: unknown): boolean { return !this.ending && typeof launchId === "string" && launchId === this.launchId; }
+
   override async start(): Promise<void> {
     // The native loader otherwise imports Codex MCP into the user's store on first use.
     if (!existsSync(join(this.jcode.home, "mcp.json"))) throw new Error("initialize Jcode's global MCP store with its native client before enabling this peer; the hub never initializes or copies it");
     if (existsSync(this.socket)) { this.preserveRoot = true; throw new Error("Jcode private socket is occupied; no daemon was adopted or removed"); }
     this.ending = false;
-    const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile);
-    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv("jcode"), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", ...JCODE_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
+    const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider, this.id);
+    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv(this.id), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", AGENTHUB_LAUNCH_ID: this.launchId, ...JCODE_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
     this.server = server; trackGroup(server);
     try {
       await new Promise<void>((resolve, reject) => {
@@ -279,11 +318,13 @@ export class JcodePeer extends AcpPeer {
       : options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile ? "--provider-profile" : undefined;
     if (differs) throw new JcodeOptionMismatch(differs);
     if (!savedSession(this.jcode.home, sessionId)) return { state: "waiting", binding };
-    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile);
-    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, ...JCODE_OWNED_ENV } } };
+    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider);
+    // The TUI is the person's own client of this peer's server. The shared project MCP entry names no peer (#685), so every launch
+    // path supplies its own id: the base Jcode's too, or its MCP child would fall back to the channel default.
+    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, AGENTHUB_PEER_ID: this.id, AGENTHUB_LAUNCH_ID: this.launchId, ...JCODE_OWNED_ENV } } };
   }
   override recoveryMetadata(): Record<string, unknown> {
-    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
+    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: this.id, mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
   }
 }
 

package/src/adapters/kimi-review.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { assessVersion, COMPAT } from "./compat.ts";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -7,7 +8,7 @@ import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { realPath } from "../hub/project.ts";
 import type { ReviewerBackend, ReviewerPrepareContext } from "./reviewer-print.ts";
 
-const VERSION = "2.2.0", MANAGED = "managed:kimi-code";
+const MANAGED = "managed:kimi-code";
 const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
 const hash = (text: string) => createHash("sha256").update(text).digest("hex");
 /** Native discovery can walk above cwd; check lexical aliases as well as the physical temporary root. */
@@ -133,7 +134,9 @@ export const kimiReviewerBackend: ReviewerBackend = {
       const executable = realPath(Bun.which(native[0]!, { PATH: process.env.PATH }) ?? resolve(native[0]!));
       const command = [executable, ...native.slice(1)];
       const executableStat = lstatSync(executable);
-      if (await version(command, cwd, env, context.signal) !== VERSION) throw new Error("unsupported Kimi version; receipt covers 2.2.0");
+      // #691: the verified versions and the person's trust live in compat.ts.
+      const verdict = assessVersion("kimi-review", COMPAT["kimi-review"].parse(await version(command, cwd, env, context.signal)));
+      if (!verdict.ok) throw new Error(verdict.reason);
       const fingerprints = [configFile, mcpFile, agentFile].map(file => hash(read(file, 2_097_152)));
       let cleaned = false;
       const cleanup = () => { if (cleaned) return; rmSync(root, { recursive: true, force: true }); cleaned = true; };
@@ -149,7 +152,7 @@ export const kimiReviewerBackend: ReviewerBackend = {
               && ["credentials", "oauth", "device_id"].every((name, index) => realPath(join(source, name)) === sources[index] && realPath(join(tool, name)) === sources[index]);
           } catch { return false; }
         },
-        isolation: { backend: "kimi", version: VERSION, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
+        isolation: { backend: "kimi", version: verdict.version, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
           enforcement: "native-policy", freshSession: true, hubToolsOnly: true,
           evidence: ["#533 person ruling2026-10-19: native execution-time exact tool allowlist, no kernel sandbox", "private config/cwd/empty skills; shared OAuth directory symlinks and native lock/atomic rename", "task-bound in-process hub MCP; no full control token", "residual: interruption mid-refresh may require native re-login"] },
       };

package/src/adapters/registry-types.ts

@@ -202,7 +202,9 @@ export interface AdapterDefinition {
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
-  instances?: { mode: "external" | "headless"; roles?: readonly string[] };
+  instances?: { mode: "external" | "headless"; roles?: readonly string[];
+    /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */
+    nativeHome?: true };
   attach?: {
     /** The authenticated external hello may claim this id; independent of MCP configuration shape. */
     externalHello?: boolean;

package/src/adapters/registry.ts

@@ -232,6 +232,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["routing", definition.routing !== undefined],
     ["projection", definition.projection !== undefined],
+    ["instances.nativeHome", declared(definition.instances, "nativeHome")], // #685: a fixed-builtin assumption, one native data home per declared instance
     ["reviewerVariant", definition.reviewerVariant !== undefined],
     ["reviewer", definition.reviewer !== undefined],
     ["hooks.factsHook", declared(definition.hooks, "factsHook")],

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/agents.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { assessVersion, COMPAT, describe, isCompatId, readTrust, trustFile, writeTrust, type CompatId, type CompatVerdict } from "../adapters/compat.ts";
+
+/** #691: what `ahub agents` and `ahub doctor` show for each gated native CLI. */
+export interface AgentVersionRow { id: CompatId; executable?: string; verdict: CompatVerdict; policy: string }
+
+/** `commands` carries the configured argv (codex_bin, jcode_cmd, qwen_cmd); the probe words follow it. */
+export function agentVersions(commands: Partial<Record<CompatId, readonly string[]>> = {}): AgentVersionRow[] {
+  const trusted = readTrust();
+  return (Object.keys(COMPAT) as CompatId[]).map(id => {
+    const [defaultBin, ...words] = COMPAT[id].probe;
+    const [bin = defaultBin, ...prefix] = commands[id] ?? [defaultBin];
+    const executable = Bun.which(bin) ?? undefined;
+    if (!executable) return { id, verdict: { ok: false, state: "unknown", reason: `${COMPAT[id].label} not found on PATH` }, policy: describe(id) };
+    const result = spawnSync(executable, [...prefix, ...words], { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" } });
+    return { id, executable, verdict: assessVersion(id, result.status === 0 ? COMPAT[id].parse(result.stdout ?? "") : undefined, trusted), policy: describe(id) };
+  });
+}
+
+export function runAgents(args: string[], commands: Partial<Record<CompatId, readonly string[]>>, fail: (message: string) => never): void {
+  const [sub, id, version, ...rest] = args.filter(arg => arg !== "--json");
+  if (sub === "trust") {
+    const revoke = rest.includes("--revoke");
+    if (!isCompatId(id) || !version || rest.some(arg => arg !== "--revoke")) fail(`usage: ahub agents trust <${Object.keys(COMPAT).join("|")}> <version> [--revoke]`);
+    // The issue requires saying what trust covers before it is recorded.
+    if (!revoke) console.log(`${COMPAT[id].label} ${version}: ${COMPAT[id].trustNote}`);
+    let rows;
+    try { rows = writeTrust(id, version, revoke); } catch (error) { fail((error as Error).message); }
+    if (revoke) return console.log(`revoked: ${id} ${version} (${rows.length} trusted on this machine, ${trustFile()})`);
+    console.log(`trusted on this machine: ${COMPAT[id].label} ${version}\nUndo: ahub agents trust ${id} ${version} --revoke`);
+    return;
+  }
+  if (sub !== undefined) fail("usage: ahub agents [--json] | ahub agents trust <id> <version> [--revoke]");
+  const rows = agentVersions(commands);
+  if (args.includes("--json")) return console.log(JSON.stringify(rows.map(row => ({ id: row.id, executable: row.executable ?? null, ...row.verdict, policy: row.policy })), null, 2));
+  for (const row of rows) {
+    const v = row.verdict;
+    console.log(`${row.id.padEnd(13)} ${(v.version ?? "-").padEnd(10)} ${v.state.padEnd(9)} ${row.policy}${v.ok ? (v.note ? `\n${" ".repeat(14)}${v.note}` : "") : `\n${" ".repeat(14)}${v.reason}`}`);
+  }
+}

package/src/cli/console-review.ts

@@ -0,0 +1,54 @@
+// #711 / #380: the console's review guidance. Pure strings and decisions, no terminal code and no state import: console-state.ts renders them.
+// Nothing here changes authority: the console runs `ahub review` as the person, and the hub decides.
+
+export type Verdict = "approved" | "changes_requested";
+/** The task a review choice was opened for, taken from the selected row or the open detail. */
+export interface ReviewChoice { id: number; title: string; reviewerIsUser: boolean }
+
+const MAX_TITLE = 40;
+const clean = (text: string) => text.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim();
+/** The title as the choice line shows it: quoted, one line, cut to the width; a private task is `[pii]`. */
+export function choiceTitle(row: { title?: unknown; signals?: unknown }): string {
+  const priv = (Array.isArray(row.signals) && row.signals.some(s => s === "pii" || s === "pii_path")) || row.title === "[pii]";
+  if (priv) return "[pii]";
+  const text = clean(String(row.title ?? ""));
+  return JSON.stringify(text.length > MAX_TITLE ? `${text.slice(0, MAX_TITLE - 3)}...` : text);
+}
+
+/** The choice for a task row, or undefined when it is not one the person can review (not in review). */
+export function reviewChoiceFor(row: any): ReviewChoice | undefined {
+  if (!row || row.state !== "in_review" || !Number.isSafeInteger(Number(row.id)) || Number(row.id) <= 0) return undefined;
+  return { id: Number(row.id), title: choiceTitle(row), reviewerIsUser: row.reviewer === "user" };
+}
+
+/** The prompt line while the choice is open (#711 change 1). The title is already quoted. */
+export const choicePrompt = (c: ReviewChoice): string => `review #${c.id} ${c.title}: a approve  c request changes  Esc cancel`;
+/** What `a` and `c` prefill on the input line. The trailing space is where the note goes. */
+export const verdictInput = (id: number, verdict: Verdict): string => `review ${id} ${verdict} `;
+/** The guide line shown above the input after a choice (#711 change 1). */
+export const verdictGuide = (id: number, verdict: Verdict): string =>
+  verdict === "approved" ? `Enter approves #${id}. You can type a note first. Esc cancels.` : "Say what to fix, then Enter. Esc cancels.";
+
+/** The footer hint for a task in review (#711 change 2): the verb, and whose review it is when it is the person's. */
+export const reviewHint = (reviewer: unknown): string => reviewer === "user" ? "your review: r approve or request changes" : "r approve or request changes";
+
+/**
+ * A `review <id> <verdict> [note]` line the person typed, checked before it is sent: a changes request must say what to fix (#711 change 1). Returns the refusal,
+ * or undefined when the line is fine or is not a review line at all (other commands are validated where they always were).
+ */
+export function reviewRefusal(args: readonly string[]): string | undefined {
+  if (args[0] !== "review") return undefined;
+  const verdict = args[2];
+  if (verdict !== "changes_requested") return undefined;
+  const note = args.slice(3).filter(word => !word.startsWith("--")).join(" ").trim();
+  return note ? undefined : "say what to fix before requesting changes";
+}
+
+/** The notice after a review command finished: `#372 approved`, `#372 changes requested`, or the CLI's own refusal verbatim (#711 change 3). */
+export function reviewResult(args: readonly string[], code: number, diagnostic: string): { text: string; tone: "success" | "failure" } | undefined {
+  if (args[0] !== "review" || !/^\d+$/.test(args[1] ?? "")) return undefined;
+  const verdict = args[2];
+  if (verdict !== "approved" && verdict !== "changes_requested") return undefined;
+  if (code) return { text: clean(diagnostic) || `command exited ${code}`, tone: "failure" };
+  return { text: `#${args[1]} ${verdict === "approved" ? "approved" : "changes requested"}`, tone: "success" };
+}