@staix/agent-hub 0.12.36 → 0.12.37

package/src/adapters/acp.ts

@@ -68,7 +68,7 @@ export interface AcpOptions {
   /** Production Qwen only; legacy benchmark adapters retain their own native policy. */
   qwen025?: boolean;
   /** A production adapter's source-pinned identity; no table is inferred from it. */
-  expectedAgent?: { name: string; version: string };
+  expectedAgent?: { name: string; version: string | ((version: unknown) => boolean) };
   /** Vendors with uncertain load semantics must explicitly echo the restored identity. */
   requireLoadSessionEcho?: boolean;
   /** Bound for native mode acknowledgement; defaults to the handshake deadline. */
@@ -242,7 +242,8 @@ export class AcpPeer extends BasePeer {
       // The configured peer id and command are labels, not an agent-specific mode contract.
       // Installed Kimi Code CLI's ACP initialize advertises this exact name.
       this.kimiAgent = init?.agentInfo?.name === "Kimi Code CLI";
-      if (this.opts.expectedAgent && (init?.agentInfo?.name !== this.opts.expectedAgent.name || init?.agentInfo?.version !== this.opts.expectedAgent.version)) throw new Error("native ACP identity is not verified for this production adapter");
+      const expected = this.opts.expectedAgent, version = init?.agentInfo?.version;
+      if (expected && (init?.agentInfo?.name !== expected.name || !(typeof expected.version === "function" ? expected.version(version) : version === expected.version))) throw new Error("native ACP identity is not verified for this production adapter");
       this.qwenAgent = qwenNativeIdentity(this.id, this.opts.qwen025, init, this.opts.kind);
       const resume = this.opts.resumeSessionId;
       if (!resume) return this.request("session/new", { cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });

package/src/adapters/claude-print.ts

@@ -1,10 +1,8 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { childEnv, peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { childEnv } from "../hub/child-process.ts";
 import { hubGitSync } from "../hub/git.ts";
 import { changedPathGroups } from "../hub/review-brief.ts";
-import { HUB, frame, type Envelope } from "../hub/envelope.ts";
-import { BasePeer } from "../hub/peers.ts";
+import { type Envelope } from "../hub/envelope.ts";
+import { ReviewerPrintPeer, type ReviewerBackend, type ReviewerPrintOptions } from "./reviewer-print.ts";
 
 export interface ClaudePrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 
@@ -23,6 +21,7 @@ export interface ClaudePrintOptions {
   /** Whether this peer recorded a verdict on the task since `since` (ms). */
   verdictSince(task: number, since: number): boolean;
   onUsage?(usage: ClaudePrintUsage, task: number): void;
+  onUnavailable?: ReviewerPrintOptions["onUnavailable"];
   log?(line: string): void;
 }
 
@@ -74,157 +73,20 @@ export function reviewDiff(cwd: string, commit: unknown, policy: { privatePath(p
   return `Diff of ${commit} against its merge base with the checkout's HEAD:\n${body}${note}`;
 }
 
-/** The review's leader exited but its process group could not be confirmed gone; the child handle is kept. */
-class GroupCleanupError extends Error {}
-
-const reviewTask = (env: Envelope): number | undefined => {
-  if (env.from !== HUB || env.kind !== "review") return undefined;
-  const id = Number(env.refs?.task);
-  return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+export const claudeReviewerBackend: ReviewerBackend = {
+  id: "claude",
+  prepare: async context => ({ command: context.command ?? ["claude"],
+    args: claudePrintArgs(context.sessionId, context.mcpConfig, context.systemPrompt, context.privatePaths),
+    isolation: { backend: "claude", version: "existing-223-contract", binary: (context.command ?? ["claude"])[0]!, profile: "strict-mcp-read-grep-glob",
+      readOnly: true, strictMcp: true, ephemeral: true, evidence: ["#223 fixed native allowlist, strict MCP config and unpersisted session"] } }),
+  usage: event => {
+    const row = event as { type?: string; usage?: ClaudePrintUsage } | null;
+    return row?.type === "result" ? row.usage : undefined;
+  },
 };
 
-/**
- * #223 R3: a hub-native Claude reviewer. Idle with no process; each hub review request runs one `claude -p` child in a
- * new session (never resumed), so no verdict sees an earlier round or builder chat. Its final text is not published:
- * the verdict is the child's own `hub_review` call.
- */
-export class ClaudePrintPeer extends BasePeer {
-  readonly hubNative = true;
-  private generation = 0;
-  private child: ChildProcess | undefined;
-  private activeDeliveryId: string | undefined;
-  /** The task whose review the running child was started for (R4: the hub records `fresh` for its verdict). */
-  reviewing: number | undefined;
-  private reviewSeq = 0;
-  /** Identifies the running child's authority over `task`; a replacement child for the same task gets a new token. */
-  reviewToken(task: number): number | undefined { return this.reviewing === task ? this.reviewSeq : undefined; }
-
-  constructor(id: string, private readonly opts: ClaudePrintOptions) { super(id, opts.watchdogMs); }
-
-  recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "claude-print", peer: this.id } }; }
-
-  async start(): Promise<void> {
-    // A retained child means a review's process group was never confirmed gone: no new review beside it.
-    if (this.child) throw new Error(`${this.id}: an earlier review's process group is still running; stop it first`);
-    this.setState("idle");
-  }
-
-  async stop(reason?: string): Promise<void> {
-    this.generation++; // fence before the first await: a late exit settles nothing
-    this.settle("needs_review", reason ?? "review stopped before settlement");
-    if (this.child) this.setState("busy"); // unavailable, not offline, until the group is confirmed gone
-    await this.kill(); // throws when the child could not be stopped; its handle is kept and the peer stays busy
-    this.setState("offline");
-  }
-
-  protected override onWatchdog(): void {
-    this.generation++;
-    this.settle("needs_review", "review watchdog timeout");
-    // Busy until the old child is gone: a new review never runs beside it.
-    void this.kill().then(() => { if (this.state === "busy") super.onWatchdog(); }, (error: Error) => this.opts.log?.(`[${this.id}] watchdog stop failed, staying busy: ${error.message}`));
-  }
-
-  async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
-    if (this.state !== "idle") {
-      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is ${this.state}` });
-      throw new Error(`${this.id} is ${this.state}`);
-    }
-    const generation = ++this.generation;
-    this.activeDeliveryId = deliveryId;
-    this.setState("busy");
-    if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
-    void this.run(envs, generation).catch((error: Error) => {
-      if (generation !== this.generation) return;
-      this.settle("needs_review", `claude reviewer failed: ${error.message}`);
-      void this.kill().then(() => this.setState("idle"), () => undefined);
-    });
-  }
-
-  private async run(envs: Envelope[], generation: number): Promise<void> {
-    const missing: number[] = [];
-    let started = false;
-    let failure: { state: "failed_safe" | "needs_review"; reason: string } | undefined;
-    for (const env of envs) {
-      const task = reviewTask(env);
-      if (task === undefined) continue; // a withdrawal or other notice: nothing to review
-      if (env.private) { failure = { state: "needs_review", reason: "a private review is the person's, never a cloud reviewer's" }; break; }
-      const since = Date.now();
-      let code: number | null;
-      try { code = await this.review(env, task, generation); }
-      catch (error) {
-        if (generation !== this.generation) return;
-        if (error instanceof GroupCleanupError) {
-          // Unavailable until a stop confirms the group gone: no new review runs beside the survivors.
-          this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
-          this.settle("needs_review", `review process group still running: ${error.message}`);
-          return;
-        }
-        // 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: `claude reviewer could not start: ${(error as Error).message}` }; break;
-      }
-      started = true;
-      if (generation !== this.generation) return;
-      let recorded = false;
-      try { recorded = this.opts.verdictSince(task, since); } catch (error) { this.opts.log?.(`[${this.id}] verdict check for task #${task} failed: ${(error as Error).message}`); }
-      if (!recorded) missing.push(task);
-      if (code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${code}`);
-    }
-    if (generation !== this.generation) return;
-    this.settle(failure?.state ?? (missing.length ? "needs_review" : "completed"), failure?.reason ?? (missing.length ? `no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
-    this.setState("idle");
-  }
-
-  private review(env: Envelope, task: number, generation: number): Promise<number | null> {
-    const [cmd = "claude", ...prefix] = this.opts.command ?? ["claude"];
-    const args = [...prefix, ...claudePrintArgs(randomUUID(), this.opts.mcpConfig, this.opts.systemPrompt, this.opts.privatePaths)];
-    return new Promise((resolve, reject) => {
-      const child = spawn(cmd, args, { cwd: this.opts.cwd, detached: true, env: peerChildEnv(this.id), stdio: ["pipe", "pipe", "ignore"] });
-      // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
-      this.child = child;
-      child.once("error", error => { if (this.child === child) this.child = undefined; reject(error); });
-      child.stdin!.on("error", () => { /* the child exited before reading its prompt; its exit settles the review */ });
-      child.once("spawn", () => {
-        trackGroup(child);
-        if (generation !== this.generation) { child.stdin!.destroy(); return; } // stopped meanwhile: no prompt
-        this.reviewing = task; this.reviewSeq++;
-        let facts: string | undefined;
-        try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
-        child.stdin!.end(`${frame(env)}${facts ? `\n\n${facts}` : ""}`);
-      });
-      let buffer = "";
-      child.stdout!.on("data", (chunk: Buffer) => {
-        if (generation !== this.generation) return;
-        this.touch();
-        buffer += chunk.toString("utf8");
-        for (let i; (i = buffer.indexOf("\n")) >= 0;) {
-          const line = buffer.slice(0, i); buffer = buffer.slice(i + 1);
-          try {
-            const event = JSON.parse(line) as { type?: string; usage?: ClaudePrintUsage };
-            if (event.type === "result" && event.usage) this.opts.onUsage?.(event.usage, task);
-          } catch { /* not a stream-json line */ }
-        }
-      });
-      child.once("exit", code => {
-        if (this.child === child) this.reviewing = undefined; // the verdict authority ends with the leader
-        // The review ends when its whole process group is gone (an MCP server or other descendant may outlive the leader).
-        stopOwnedProcess(child, { group: true }).then(() => { if (this.child === child) this.child = undefined; resolve(code); },
-          (error: Error) => reject(new GroupCleanupError(error.message)));
-      });
-    });
-  }
-
-  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string): void {
-    const id = this.activeDeliveryId;
-    this.activeDeliveryId = undefined;
-    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}) });
-  }
-
-  /** Revokes the verdict authority at once, then stops the child; on failure the handle is kept and the error thrown. */
-  private async kill(): Promise<void> {
-    this.reviewing = undefined;
-    const child = this.child;
-    if (!child) return;
-    await stopOwnedProcess(child, { group: true });
-    if (this.child === child) this.child = undefined;
-  }
+/** Compatibility wrapper for the released Claude transport and its existing tests. */
+export class ClaudePrintPeer extends ReviewerPrintPeer {
+  constructor(id: string, options: ClaudePrintOptions) { super(id, { ...options, backend: claudeReviewerBackend }); }
+  override recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "claude-print", peer: this.id } }; }
 }

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

@@ -0,0 +1,276 @@
+import { DENY_NAMES, DENY_SEGMENTS } from "@staix/agent-mem/platform";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+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";
+
+const VERSION = "0.146.0", TOOLS = ["hub_review", "hub_task_show"];
+const CAP = 128 * 1024, MAX_SERVERS = 64;
+const digest = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
+/** Conservative translation of the portable core's regex sources; unfamiliar syntax refuses the receipt. */
+export function codexCoreDenyGlobs(names: readonly string[] = DENY_NAMES, segments: readonly string[] = DENY_SEGMENTS): string[] {
+  if (names.length > 64 || segments.length > 64) throw new Error("core deny policy bound exceeded");
+  const globs: string[] = [];
+  for (const source of names) {
+    if (typeof source !== "string" || source.length > 256) throw new Error("unverified core deny pattern");
+    const anchored = source.startsWith("^");
+    let body = anchored ? source.slice(1) : source;
+    const branch = "(\\.|$)", branchSuffix = anchored && body.endsWith(branch);
+    const end = !branchSuffix && body.endsWith("$");
+    if (!anchored && !end) throw new Error("unverified core deny pattern");
+    if (branchSuffix) body = body.slice(0, -branch.length);
+    else if (end) body = body.slice(0, -1);
+    let literal = "";
+    for (let i = 0; i < body.length; i++) {
+      const char = body[i]!;
+      if (char === "\\" && body[i + 1] === ".") { literal += "."; i++; }
+      else if (/^[A-Za-z0-9_-]$/.test(char)) literal += char;
+      else throw new Error("unverified core deny pattern");
+    }
+    if (!literal) throw new Error("empty core deny pattern");
+    const glob = `/**/${anchored ? "" : "*"}${literal}${end ? "" : "*"}`;
+    globs.push(glob, `${glob}/**`);
+  }
+  for (const segment of segments) {
+    if (typeof segment !== "string" || segment.length > 256 || !/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(segment) || segment.split("/").some(part => part === "." || part === "..")) throw new Error("unverified core deny segment");
+    globs.push(`/**/${segment}`, `/**/${segment}/**`);
+  }
+  return [...new Set(globs)];
+}
+
+const inside = (file: string, root: string) => { const part = relative(root, file); return part === "" || part !== ".." && !part.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(part); };
+const object = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid metadata");
+  return value as Record<string, unknown>;
+};
+function toml(value: unknown): string {
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "number") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(toml).join(",")}]`;
+  return `{${Object.entries(object(value)).map(([key, item]) => `${JSON.stringify(key)}=${toml(item)}`).join(",")}}`;
+}
+function metadata(file: string): string {
+  try { const link = lstatSync(file), stat = statSync(file); return [link.dev, link.ino, link.mtimeMs, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":"); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent"; throw new Error("config metadata unavailable"); }
+}
+function configFiles(cwd: string, env: NodeJS.ProcessEnv): string[] {
+  const home = resolve(env.CODEX_HOME ?? join(homedir(), ".codex"));
+  const files = [join(home, "config.toml"), join(home, "cloud-config-bundle-cache.json"), "/etc/codex/config.toml", "/etc/codex/requirements.toml", "/etc/codex/managed_config.toml"];
+  // Include ancestors even outside the git root: no trust/layout assumption can hide a changed layer.
+  for (let dir = cwd; ; dir = dirname(dir)) { files.push(join(dir, ".codex", "config.toml")); if (dirname(dir) === dir) break; }
+  return files;
+}
+// Bounded host credential roots, not a universal private-home classifier. Never inspect their file contents.
+const HOST_CREDENTIAL_PATHS = [".config", ".ssh", ".aws", ".azure", ".kube", ".docker", ".gnupg", ".codex", ".claude", ".kimi", ".kimi-code", ".gemini", ".git-credentials", ".vault-token", "Library/Keychains", ".local/share/keyrings", ".password-store"] as const;
+const HOST_CREDENTIAL_ENV = ["XDG_CONFIG_HOME", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "KIMI_CODE_HOME", "KIMI_HOME", "GEMINI_CLI_HOME", "GNUPGHOME", "AWS_SHARED_CREDENTIALS_FILE", "AWS_CONFIG_FILE", "AZURE_CONFIG_DIR", "DOCKER_CONFIG", "GOOGLE_APPLICATION_CREDENTIALS"] as const;
+function hostCredentialRoots(env: NodeJS.ProcessEnv, cwd: string): string[] {
+  const home = resolve(cwd, env.HOME || homedir());
+  const homes = [...new Set([home, credentialCanonicalPath(home)])];
+  const roots: string[] = homes.flatMap(base => HOST_CREDENTIAL_PATHS.map(entry => join(base, entry)));
+  const configured = HOST_CREDENTIAL_ENV.flatMap(key => env[key] ? [env[key]!] : []);
+  if (env.KUBECONFIG) configured.push(...env.KUBECONFIG.split(delimiter).filter(Boolean));
+  if (configured.length > 64) throw new Error("credential root bound exceeded");
+  for (const entry of configured) {
+    if (Buffer.byteLength(entry) > 4096 || /\p{Cc}/u.test(entry)) throw new Error("invalid credential root");
+    roots.push(entry.startsWith("~/") ? resolve(home, entry.slice(2)) : resolve(cwd, entry));
+  }
+  return [...new Set(roots)];
+}
+/** Resolve absent descendants through the deepest existing ancestor; dangling links refuse admission. */
+function credentialCanonicalPath(lexical: string): string {
+  // Same strict ancestor algorithm as policyRealPath; importing path-policy here would cycle through the registry.
+  let ancestor = lexical;
+  for (;;) {
+    try { lstatSync(ancestor); break; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || dirname(ancestor) === ancestor) throw error;
+      ancestor = dirname(ancestor);
+    }
+  }
+  return join(realPath(ancestor), relative(ancestor, lexical));
+}
+function denyCredentialRoots(filesystem: Record<string, string>, roots: readonly string[], cwd: string): void {
+  for (const lexical of roots) {
+    // Native profile keys with glob metacharacters cannot represent these literal host locations safely.
+    if (/[?*\[\]{}]/.test(lexical)) throw new Error("unverified credential root syntax");
+    const targets = new Set([lexical, credentialCanonicalPath(lexical)]);
+    for (const target of targets) {
+      if (/[?*\[\]{}]/.test(target)) throw new Error("unverified credential root syntax");
+      if (inside(cwd, target)) throw new Error("credential root overlaps checkout");
+      filesystem[target] = "deny"; filesystem[`${target.replace(/\/$/, "")}/**`] = "deny";
+    }
+  }
+}
+
+function resolveCommand(ctx: ReviewerPrepareContext, cwd: string): { command: string[]; files: string[] } {
+  const [name = "codex", ...prefix] = ctx.command ?? [];
+  const found = isAbsolute(name) ? name : Bun.which(name);
+  if (!found) throw new Error("host executable unavailable");
+  let binary = realPath(found);
+  // Bind the actual native binary, not the mutable npm launcher/interpreter selection.
+  if (basename(binary) === "codex.js") {
+    const target = process.platform === "darwin" ? process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin"
+      : process.platform === "linux" ? process.arch === "arm64" ? "aarch64-unknown-linux-musl" : "x86_64-unknown-linux-musl" : undefined;
+    if (!target || !["arm64", "x64"].includes(process.arch)) throw new Error("unverified native platform");
+    const suffix = `${process.platform}-${process.arch === "x64" ? "x64" : "arm64"}`;
+    const manifest = createRequire(binary).resolve(`@openai/codex-${suffix}/package.json`);
+    binary = realPath(join(dirname(manifest), "vendor", target, "bin", "codex"));
+  }
+  const files = [binary];
+  if (inside(binary, cwd)) throw new Error("project executable refused");
+  for (const [index, arg] of prefix.entries()) {
+    // Privileged host argv may include a fixture/launcher script, but never a project-owned one.
+    if (isAbsolute(arg) && (index === 0 || /\.(?:js|ts|mjs|cjs|sh)$/.test(arg)) && existsSync(arg) && statSync(arg).isFile()) {
+      const file = realPath(arg); if (inside(file, cwd)) throw new Error("project command prefix refused"); files.push(file);
+    } else if (/\.(?:js|ts|mjs|cjs|sh)$/.test(arg)) throw new Error("unbound command prefix refused");
+  }
+  return { command: [binary, ...prefix], files };
+}
+interface Server { name: string; enabled: boolean; type: "stdio" | "http"; transport: Record<string, unknown> }
+function inventory(text: string): Server[] {
+  const raw: unknown = JSON.parse(text);
+  if (!Array.isArray(raw) || raw.length > MAX_SERVERS) throw new Error("inventory bound exceeded");
+  const seen = new Set<string>();
+  return raw.map(value => {
+    const row = object(value), transport = object(row.transport);
+    if (typeof row.name !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(row.name) || seen.has(row.name) || typeof row.enabled !== "boolean") throw new Error("invalid inventory identity");
+    seen.add(row.name);
+    const type = transport.type;
+    if (type !== "stdio" && type !== "http" && type !== "streamable_http") throw new Error("unverified MCP transport");
+    return { name: row.name, enabled: row.enabled, type: type === "stdio" ? "stdio" : "http", transport };
+  });
+}
+/** The configured MCP list omits runtime-synthesized Apps; verify the fixed feature gate separately. */
+function proveDisabledFeatures(text: string): void {
+  const rows = text.trim().split(/\r?\n/).map(line => line.trim());
+  if (rows.length > 512) throw new Error("feature inventory bound exceeded");
+  for (const name of ["apps", "plugins", "hooks"]) {
+    const matches = rows.filter(line => line.split(/\s+/)[0] === name);
+    if (matches.length !== 1 || !new RegExp(`^${name}\\s+stable\\s+false$`).test(matches[0]!)) throw new Error("effective feature isolation unverified");
+  }
+}
+function ownServer(text: string): Record<string, unknown> {
+  const config = object(JSON.parse(text)), servers = object(config.mcpServers);
+  if (Object.keys(servers).length !== 1 || !Object.hasOwn(servers, "agent-hub")) throw new Error("fixed hub MCP required");
+  const hub = object(servers["agent-hub"]);
+  if (Object.keys(hub).some(key => !["command", "args", "env"].includes(key)) || typeof hub.command !== "string" || !hub.command || hub.args !== undefined && (!Array.isArray(hub.args) || hub.args.some(arg => typeof arg !== "string"))) throw new Error("invalid hub transport");
+  const env = hub.env === undefined ? {} : object(hub.env);
+  if (Object.values(env).some(value => typeof value !== "string")) throw new Error("invalid hub environment");
+  return { command: hub.command, args: hub.args ?? [], env, enabled: true, required: true, enabled_tools: TOOLS };
+}
+
+/** All reads are model-free and bounded; stdout/config/env values never become diagnostic text. */
+async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }> {
+  let root: string | undefined;
+  try {
+    const cwd = realPath(ctx.cwd), env = peerChildEnv(ctx.peer), bound = resolveCommand(ctx, cwd);
+    const initialBinaryMetadata = bound.files.map(metadata).join(";");
+    // Hash content once per receipt, then fence the identity with dev/ino/size/mtime/ctime metadata.
+    const binaryHash = digest(bound.files.map(file => digest(readFileSync(file))).join(";"));
+    if (bound.files.map(metadata).join(";") !== initialBinaryMetadata) throw new Error("binary changed while hashing");
+    const watched = configFiles(cwd, env), initialConfig = watched.map(metadata).join(";");
+    const deadline = performance.now() + 12_000;
+    const current = () => {
+      if (ctx.signal.aborted || watched.map(metadata).join(";") !== initialConfig) return false;
+      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; }
+      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())));
+      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);
+        try { await stopOwnedProcess(child, { group: true, termMs: 100, killMs: 500 }); }
+        catch { reject(new Error("metadata cleanup unconfirmed")); return; }
+        if (failed || ctx.signal.aborted || code !== 0) reject(new Error("metadata proof refused")); else resolveOutput(output);
+      };
+      child.once("spawn", () => { trackGroup(child); if (ctx.signal.aborted) stop(); });
+      child.stdout.on("data", (chunk: Buffer) => { bytes += chunk.length; if (bytes > maxBytes) stop(); else if (capture) output += chunk.toString("utf8"); });
+      child.stderr.on("data", (chunk: Buffer) => { bytes += chunk.length; if (bytes > maxBytes) stop(); });
+      child.once("error", () => { failed = true; void finish(null); });
+      child.once("close", code => { void finish(code); });
+    });
+    if ((await run(["--version"])).trim() !== `codex-cli ${VERSION}`) throw new Error("native version has no isolation receipt");
+    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 = ["--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
+    proveDisabledFeatures(await run(["features", "list", ...policy]));
+    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 });
+    for (const server of before) servers[server.name] = server.type === "stdio" ? { command: "/usr/bin/false", enabled: false } : { url: "http://127.0.0.1:1", enabled: false };
+    const mcp = ["-c", `mcp_servers=${toml(servers)}`];
+    const after = inventory(await run(["mcp", "list", "--json", ...policy, ...mcp]));
+    if (after.length !== before.length + 1 || after.some(row => row.name !== "agent-hub" && !before.some(old => old.name === row.name)) || after.filter(row => row.enabled).map(row => row.name).join(",") !== "agent-hub") throw new Error("MCP inventory changed or is not strict");
+    const observed = object(JSON.parse(await run(["mcp", "get", "agent-hub", "--json", ...policy, ...mcp])));
+    if (observed.name !== "agent-hub" || observed.enabled !== true || !Array.isArray(observed.enabled_tools) || JSON.stringify(observed.enabled_tools) !== JSON.stringify(TOOLS)) throw new Error("hub tool allowlist unverified");
+    const observedTransport = object(observed.transport);
+    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.
+    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");
+    const fixtureHome = join(root, "host-home"), hostConfig = join(fixtureHome, ".config", "gh", "hosts.yml"), hostKube = join(fixtureHome, ".kube", "config"), hostDocker = join(fixtureHome, ".docker", "config.json"), hostAlias = join(root, "host-alias.yml");
+    for (const file of [hostConfig, hostKube, hostDocker]) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, "synthetic host credential fixture"); }
+    symlinkSync(hostConfig, hostAlias);
+    mkdirSync(coreStateDir, { recursive: true });
+    writeFileSync(coreName, "core name fixture"); writeFileSync(coreState, "core state fixture");
+    const globRoot = join(root, "glob"), nested = join(globRoot, "nested"), globFile = join(nested, "private.env"), alias = join(root, "alias.env");
+    mkdirSync(globRoot); mkdirSync(nested);
+    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" };
+    for (const glob of codexCoreDenyGlobs()) filesystem[glob] = "deny";
+    denyCredentialRoots(filesystem, [...hostCredentialRoots(env, cwd), ...hostCredentialRoots({ HOME: fixtureHome }, cwd)], cwd);
+    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.
+      if (/[{}]/.test(entry)) throw new Error("unverified private path pattern");
+      const homePath = entry === "~" || entry.startsWith("~/");
+      const absolute = homePath ? resolve(homedir(), entry.slice(2)) : isAbsolute(entry) ? entry : resolve(cwd, entry);
+      const patterns = new Set([absolute]);
+      if (!/[?*\[\]]/.test(absolute) && existsSync(absolute)) patterns.add(realPath(absolute));
+      if (!isAbsolute(entry) && !homePath && entry !== "." && entry !== "..") {
+        patterns.add(join(cwd, "**", entry));
+        // ctx combines PII path patterns and local substring denies: broadening is safer than omission.
+        if (!/[?*\[\]]/.test(entry)) patterns.add(join(cwd, "**", `*${entry.replace(/^\.\//, "").replace(/\/$/, "")}*`));
+      }
+      for (const pattern of patterns) { filesystem[pattern] = "deny"; filesystem[`${pattern.replace(/\/$/, "")}/**`] = "deny"; }
+    }
+    const profile = { filesystem, network: { enabled: false } }, permissions = ["-c", `permissions=${toml({ "ahub-review": profile })}`, "-c", 'default_permissions="ahub-review"'];
+    // ponytail: drain the pinned catalog without retaining it, capped at 4 MiB; replace with quiet config validation when the native CLI provides it.
+    await run(["debug", "models", "--bundled", ...policy, ...permissions], false, 4 * 1024 * 1024);
+    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");
+    if (!current()) throw new Error("binary or config changed during proof");
+    const cleanupRoot = root;
+    const launchProfile = digest(toml({ profile, servers, policy }));
+    return { command: bound.command, args: ["exec", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--json", "--color", "never", "-C", cwd, ...policy, ...permissions, ...mcp, "-c", `developer_instructions=${toml(ctx.systemPrompt)}`, "-"], env,
+      current: () => { try { return current(); } catch { return false; } },
+      cleanup: () => rmSync(cleanupRoot, { recursive: true, force: true }),
+      isolation: { backend: "codex", version: VERSION, binary: `sha256:${binaryHash}`, profile: `sha256:${launchProfile}`, readOnly: true, strictMcp: true, ephemeral: true,
+        evidence: ["model-free-mcp-inventory-disabled-ambient", "hub-tools-exact-allowlist", "plugins-and-hooks-disabled", "apps-disabled-effective-feature-readback", "web-search-disabled", "project-untrusted", "native-public-read-private-deny-write-deny", "native-glob-and-symlink-private-deny", "portable-core-name-and-state-deny", "standard-host-credential-roots-denied", "binary-config-stable", "binary-hash-once-metadata-fence", "session-ephemeral"] } };
+  } catch {
+    if (root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* unavailable remains refused */ } }
+    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)" };
+  }
+}
+
+export const codexReviewerBackend: ReviewerBackend = {
+  id: "codex", prepare,
+  usage(event) {
+    const row = event as { type?: string; usage?: { input_tokens?: number; output_tokens?: number; cached_input_tokens?: number } };
+    return row?.type === "turn.completed" && row.usage ? { input_tokens: row.usage.input_tokens, output_tokens: row.usage.output_tokens, cache_read_input_tokens: row.usage.cached_input_tokens } : undefined;
+  },
+};

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

@@ -1,3 +1,4 @@
+import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
 import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
 import { piConfigSchema, localConfigSchema, piRoutingSchema, localRoutingSchema, PI_SETTINGS, PI_RESTART_REASONS, LOCAL_RESTART_REASONS, piEffectiveConfig } from "./native-config-policy.ts";
@@ -65,7 +66,7 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
   identity: { mcp: "env" },
   permission: { modes: {}, unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
   session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "claude-print", crashPlan: () => ({ resume: {}, how: "claude reviewer: starts again; every review runs in a new session" }) },
-  turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true },
+  turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true }, reviewer: { backend: claudeReviewerBackend, defaultPool: true, declaration: "automatic" },
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
 };
 
@@ -88,6 +89,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     reviewerVariant: CLAUDE_REVIEWER_VARIANT,
   },
   {
+    reviewerVariant: CODEX_REVIEWER_VARIANT,
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
@@ -101,6 +103,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     cli: { command: "codex", retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
   },
   {
+    reviewerVariant: KIMI_REVIEWER_VARIANT,
     api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },

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

@@ -39,11 +39,27 @@ export function createLocal(ctx: CreateContext): PeerAdapter {
 }
 
 export function createClaudeReviewer(ctx: CreateContext): PeerAdapter {
+  if ("reviewerPrint" in ctx.daemon) {
+    const { ClaudePrintPeer } = require("../claude-print.ts") as typeof import("../claude-print.ts");
+    return new ClaudePrintPeer(ctx.instance, ctx.daemon.reviewerPrint);
+  }
   if (!("claudePrint" in ctx.daemon)) throw new Error("Claude reviewer requires its print transport options");
   const { ClaudePrintPeer } = require("../claude-print.ts") as typeof import("../claude-print.ts");
   return new ClaudePrintPeer(ctx.instance, ctx.daemon.claudePrint);
 }
 
+export function createCodexReviewer(ctx: CreateContext): PeerAdapter {
+  if (!("reviewerPrint" in ctx.daemon)) throw new Error("Codex reviewer requires its fresh print transport options");
+  const config = ctx.kindConfig as { codex_bin?: string };
+  return createReviewer({ ...ctx, daemon: { reviewerPrint: { ...ctx.daemon.reviewerPrint, command: ctx.daemon.reviewerPrint.command ?? [config.codex_bin ?? "codex"] } } });
+}
+
+export function createReviewer(ctx: CreateContext): PeerAdapter {
+  if (!("reviewerPrint" in ctx.daemon)) throw new Error("Reviewer requires its fresh print transport options");
+  const { ReviewerPrintPeer } = require("../reviewer-print.ts") as typeof import("../reviewer-print.ts");
+  return new ReviewerPrintPeer(ctx.instance, ctx.daemon.reviewerPrint);
+}
+
 /** Preserve existing transport option types and object identity; selection stays host-owned. */
 export const DAEMON_PORTS = {
   "codex-appserver": (options: Extract<DaemonPorts, { codex: unknown }>["codex"]) => ({ codex: options }),
@@ -51,5 +67,6 @@ export const DAEMON_PORTS = {
   "owned-acp": (options: Extract<DaemonPorts, { jcode: unknown }>["jcode"]) => ({ jcode: options }),
   "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
   "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),
+  "reviewer-print": (options: Extract<DaemonPorts, { reviewerPrint: unknown }>["reviewerPrint"]) => ({ reviewerPrint: options }),
   "claude-print": (options: Extract<DaemonPorts, { claudePrint: unknown }>["claudePrint"]) => ({ claudePrint: options }),
 } satisfies Record<DaemonEngine, unknown>;

package/src/adapters/definitions/native-policy-aux.ts

@@ -15,7 +15,7 @@ export function codexCrashPlan(meta: Record<string, unknown>): NativeCrashPlan {
 }
 
 export function jcodeCrashPlan(_meta: Record<string, unknown>): NativeCrashPlan {
-  return { how: "jcode: native 0.94.0 load does not prove the restored id; reopen the original conversation with its native client, no automatic fresh replacement" };
+  return { how: "jcode: native ACP load (verified on 0.94.0 and 0.98.1) does not prove the restored id; reopen the original conversation with its native client, no automatic fresh replacement" };
 }
 
 export function kimiCrashPlan(meta: Record<string, unknown>): NativeCrashPlan {

package/src/adapters/definitions/reviewer-variants.ts

@@ -0,0 +1,32 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+import { claudeReviewerBackend } from "../claude-print.ts";
+import { codexReviewerBackend } from "../codex-review-isolation.ts";
+import { createReviewer, createCodexReviewer } from "./native-factories.ts";
+import { CODEX_DISPLAY, KIMI_DISPLAY } from "./native-display.ts";
+
+export { claudeReviewerBackend };
+/** No launch path is exposed by metadata-only placeholders. */
+function unavailableLaunch(): never { throw new Error("Reviewer unavailable: verified runtime support is deferred to #533"); }
+
+function reviewerVariant(kind: string, displayName: string, reviewer: NonNullable<AdapterDefinition["reviewer"]>, display: AdapterDefinition["display"]): AdapterDefinition {
+  return {
+    api: 1, kind, family: kind, displayName, transport: "hub-native", roles: ["reviewer"],
+    defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
+    start: { ...(reviewer.backend ? { create: createReviewer, daemonPort: "reviewer-print" as const } : {}), forms: ["headless"], defaultForm: "headless", ownsTerminal: () => false,
+      launch: unavailableLaunch,
+      conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" },
+    permission: { modes: {}, readOnly: { kind: "hub-gate", allow: ["read", "search", "think"] }, unmanaged: "fresh read-only reviewer; an isolation receipt is required before startup" },
+    session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "reviewer-print", crashPlan: () => ({ resume: {}, how: "starts a fresh isolated review session" }) },
+    turnEnd: "adapter", budget: { account: kind }, routing: { reviewOnly: true },
+    reviewer, cli: { command: kind, startWords: () => [] }, display,
+  };
+}
+const codexVariant = reviewerVariant("codex", "Codex reviewer", { backend: codexReviewerBackend, defaultPool: true, declaration: "explicit" }, CODEX_DISPLAY);
+export const CODEX_REVIEWER_VARIANT: AdapterDefinition = { ...codexVariant, start: { ...codexVariant.start, create: createCodexReviewer } };
+export const KIMI_REVIEWER_VARIANT = reviewerVariant("kimi", "Kimi reviewer", { defaultPool: false, declaration: "explicit", unavailable: "Kimi reviewer unavailable: runtime and isolation verification deferred to #533" }, KIMI_DISPLAY);
+/** Data-only declared placeholder for route explanations; no factory, backend or native argv. */
+export const AGY_DEFINITION: AdapterDefinition = {
+  ...reviewerVariant("agy", "agy reviewer", { defaultPool: false, declaration: "automatic", unavailable: "agy reviewer unavailable: native adapter and isolation verification deferred to #533" }, { palette: { fg: "#6558a6", bg: "#f1effa" } }),
+  optional: true,
+};