@staix/agent-hub 0.12.37 → 0.12.38

package/src/adapters/kimi-review.ts

@@ -0,0 +1,161 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+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 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. */
+function assertCleanCwdAncestors(...candidates: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    let ancestor = resolve(candidate);
+    for (;;) {
+      if (!seen.has(ancestor)) {
+        seen.add(ancestor);
+        for (const marker of [".git", ".kimi-code", "AGENTS.md"]) {
+          if (lstatSync(join(ancestor, marker), { throwIfNoEntry: false }) !== undefined) {
+            throw new Error("private cwd ancestor contains ambient configuration");
+          }
+        }
+      }
+      const parent = dirname(ancestor); if (parent === ancestor) break; ancestor = parent;
+    }
+  }
+}
+const read = (file: string, limit = 262_144) => {
+  const stat = lstatSync(file); if (!stat.isFile() || stat.size > limit) throw new Error("unsupported reviewer file");
+  return readFileSync(file, "utf8");
+};
+const scalar = (value: unknown, depth = 0): string => {
+  if (depth > 4) throw new Error("managed model setting too deeply nested");
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value) && value.every(v => typeof v === "string")) return JSON.stringify(value);
+  if (object(value) && Object.keys(value).length <= 32) return `{ ${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)} = ${scalar(item, depth + 1)}`).join(", ")} }`;
+  throw new Error("unsupported managed model setting");
+};
+function managedConfig(raw: string): { config: string; lock: string } {
+  const config = Bun.TOML.parse(raw) as Record<string, unknown>;
+  if (!object(config.providers) || !object(config.models) || typeof config.default_model !== "string") throw new Error("managed Kimi configuration required");
+  const provider = config.providers[MANAGED], model = config.models[config.default_model];
+  if (!object(provider) || provider.type !== "kimi" || provider.api_key && provider.api_key !== "" || !object(provider.oauth) || provider.oauth.storage !== "file" || !object(model) || model.provider !== MANAGED) throw new Error("managed file-backed Kimi OAuth required");
+  const oauth = provider.oauth;
+  const key = oauth.key;
+  const lock = !key || key === "kimi-code" || key === "oauth/kimi-code" ? "kimi-code" : typeof key === "string" && key.startsWith("oauth/") ? key.slice(6) : key;
+  if (typeof lock !== "string" || !lock || basename(lock) !== lock || lock.startsWith(".")) throw new Error("unsupported OAuth slot");
+  if (typeof provider.base_url !== "string") throw new Error("managed Kimi endpoint required");
+  const endpoint = new URL(provider.base_url);
+  if (endpoint.protocol !== "https:" || !["api.kimi.ai", "api.kimi.com"].includes(endpoint.hostname) || endpoint.username || endpoint.password) throw new Error("unsupported managed Kimi endpoint");
+  if (oauth.oauth_host !== undefined) {
+    const auth = new URL(String(oauth.oauth_host));
+    if (auth.protocol !== "https:" || !["auth.kimi.ai", "auth.kimi.com"].includes(auth.hostname) || auth.username || auth.password) throw new Error("unsupported OAuth endpoint");
+  }
+  const lines = ["telemetry = false", "hooks = []", `default_model = ${scalar(config.default_model)}`,
+    ...(config.thinking === undefined ? [] : [`thinking = ${scalar(config.thinking)}`]),
+    `[providers.${scalar(MANAGED)}]`, 'type = "kimi"', `base_url = ${scalar(provider.base_url)}`, `[providers.${scalar(MANAGED)}.oauth]`];
+  for (const name of ["storage", "key", "oauth_host"]) if (oauth[name] !== undefined) lines.push(`${name} = ${scalar(oauth[name])}`);
+  lines.push(`[models.${scalar(config.default_model)}]`);
+  const modelFields = ["provider", "model", "protocol", "max_context_size", "max_input_size", "capabilities", "display_name", "support_efforts", "default_effort", "beta_api", "adaptive_thinking", "overrides"];
+  if (Object.keys(model).some(name => !modelFields.includes(name))) throw new Error("unsupported managed model setting");
+  if (model.overrides !== undefined && (!object(model.overrides) || Object.keys(model.overrides).some(name => !modelFields.includes(name) || ["provider", "overrides"].includes(name)))) throw new Error("unsupported managed model override");
+  for (const name of modelFields) if (model[name] !== undefined) lines.push(`${name} = ${scalar(model[name])}`);
+  return { config: lines.join("\n") + "\n", lock };
+}
+function mcpConfig(context: ReviewerPrepareContext): string {
+  const config: unknown = JSON.parse(context.mcpConfig);
+  if (!object(config) || !object(config.mcpServers)) throw new Error("review MCP unavailable");
+  if (context.task === undefined && Object.keys(config.mcpServers).length === 0) return context.mcpConfig;
+  if (Object.keys(config.mcpServers).join() !== "agent-hub") throw new Error("ambient MCP refused");
+  const server = config.mcpServers["agent-hub"];
+  if (!object(server) || Object.keys(server).some(k => !["transport", "url", "headers"].includes(k)) || server.transport !== "http" || typeof server.url !== "string" || !object(server.headers) || Object.keys(server.headers).join() !== "Authorization" || typeof server.headers.Authorization !== "string" || !server.headers.Authorization.startsWith("Bearer ")) throw new Error("task-bound HTTP MCP required");
+  const url = new URL(server.url);
+  if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/mcp" || url.username || url.password || url.search || url.hash) throw new Error("local review MCP required");
+  return context.mcpConfig;
+}
+async function version(command: readonly string[], cwd: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<string> {
+  return await new Promise((accept, reject) => {
+    const child = spawn(command[0]!, [...command.slice(1), "--version"], { cwd, env, detached: true, stdio: ["ignore", "pipe", "ignore"] });
+    let text = "", done = false;
+    const finish = async (code: number | null) => {
+      if (done) return; done = true; clearTimeout(timer); signal.removeEventListener("abort", abort);
+      try { await stopOwnedProcess(child, { group: true }); } catch { reject(new Error("version probe cleanup failed")); return; }
+      if (code !== 0 || signal.aborted) reject(new Error("version probe failed")); else accept(text.trim());
+    };
+    const abort = () => { void finish(null); };
+    const timer = setTimeout(abort, 5_000);
+    signal.addEventListener("abort", abort, { once: true });
+    child.once("spawn", () => trackGroup(child));
+    child.stdout.on("data", (bytes: Buffer) => { text += bytes.toString(); if (text.length > 4096) abort(); });
+    child.once("error", () => { void finish(null); }); child.once("close", code => { void finish(code); });
+    if (signal.aborted) abort();
+  });
+}
+/** Do not SIGKILL a live native refresh holder. A bounded incomplete stop retains the peer handle. */
+export async function stopKimiReview(child: ChildProcess, locks: readonly string[], graceMs = 10_000): Promise<void> {
+  const locked = () => locks.some(file => existsSync(file));
+  if (child.exitCode === null && child.signalCode === null && locked()) {
+    child.kill("SIGTERM");
+    const end = Date.now() + graceMs;
+    while (child.exitCode === null && child.signalCode === null && locked() && Date.now() < end) await Bun.sleep(50);
+    if (child.exitCode === null && child.signalCode === null && locked()) throw new Error("Kimi OAuth refresh still locked; graceful stop incomplete");
+  }
+  await stopOwnedProcess(child, { group: true });
+}
+
+export const kimiReviewerBackend: ReviewerBackend = {
+  id: "kimi", taskMcp: true, nativePolicy: true,
+  async prepare(context) {
+    let own: string | undefined;
+    try {
+      if (context.signal.aborted) throw new Error("cancelled");
+      const sourcePath = process.env.KIMI_CODE_HOME ?? join(process.env.HOME ?? homedir(), ".kimi-code"), source = realPath(sourcePath);
+      const sourceConfig = join(source, "config.toml"), original = read(sourceConfig), selected = managedConfig(original);
+      const sources = ["credentials", "oauth", "device_id"].map(name => realPath(join(source, name)));
+      if (!sources.every((file, index) => index < 2 ? lstatSync(file).isDirectory() : lstatSync(file).isFile())) throw new Error("native OAuth directories and device identity required");
+      const mcp = mcpConfig(context);
+      if (Buffer.byteLength(context.input ?? "") > 1_048_576) throw new Error("review facts exceed limit");
+      const lexicalRoot = mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), "ahub-kimi-review-"));
+      own = realPath(lexicalRoot);
+      assertCleanCwdAncestors(join(lexicalRoot, "workspace"), join(own, "workspace"));
+      const root = own, home = join(root, "home"), tool = join(root, "tool"), cwd = join(root, "workspace"), skills = join(root, "empty-skills"), temporary = join(root, "tmp");
+      for (const dir of [home, tool, cwd, skills, temporary]) mkdirSync(dir, { mode: 0o700 });
+      ["credentials", "oauth", "device_id"].forEach((name, index) => symlinkSync(sources[index]!, join(tool, name), index < 2 ? "dir" : "file"));
+      const agentFile = join(cwd, "reviewer.md"), configFile = join(tool, "config.toml"), mcpFile = join(tool, "mcp.json");
+      writeFileSync(configFile, selected.config, { mode: 0o600 }); writeFileSync(mcpFile, mcp, { mode: 0o600 });
+      writeFileSync(agentFile, `---\nname: hub-reviewer\ndescription: Fresh agent-hub reviewer\ntools:\n  - mcp__agent-hub__hub_review\n  - mcp__agent-hub__hub_task_show\nsubagents: []\n---\n\n${context.systemPrompt}\n\nUse only the supplied public facts and hub_task_show. Never claim to have read evidence that was not supplied.\n\n${context.input ?? "No review is active; startup self-check only."}\n`, { mode: 0o600 });
+      const env: NodeJS.ProcessEnv = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: home, KIMI_CODE_HOME: tool, TMPDIR: `${temporary}/`, XDG_CONFIG_HOME: join(home, ".config"), LANG: process.env.LANG ?? "en_US.UTF-8", TERM: "dumb", ...(process.env.USER ? { USER: process.env.USER } : {}) };
+      const native = context.command ?? [Bun.which("kimi", { PATH: process.env.PATH }) ?? "kimi"];
+      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");
+      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; };
+      return { command, args: ["-p", "Review the supplied task facts and record the evidence-based verdict with hub_review.", "--output-format", "stream-json", "--agent-file", agentFile, "--skills-dir", skills],
+        cwd, env, envMode: "replace", cleanup, watchCurrent: true,
+        stop: child => stopKimiReview(child, [join(sources[1]!, "kimi-code.lock"), join(sources[1]!, `${selected.lock}.lock`)]),
+        current: () => {
+          try {
+            assertCleanCwdAncestors(join(lexicalRoot,"workspace"),cwd);
+            const now = lstatSync(executable);
+            return !cleaned && !context.signal.aborted && realPath(sourcePath) === source && now.dev === executableStat.dev && now.ino === executableStat.ino && now.size === executableStat.size && now.mtimeMs === executableStat.mtimeMs && now.ctimeMs === executableStat.ctimeMs && hash(read(sourceConfig)) === hash(original)
+              && [configFile, mcpFile, agentFile].every((file, index) => hash(read(file, 2_097_152)) === fingerprints[index])
+              && ["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,
+          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"] },
+      };
+    } catch (error) {
+      if (own) rmSync(own, { recursive: true, force: true });
+      return { unavailable: `Kimi reviewer unavailable: ${(error as Error).message}` };
+    }
+  },
+};

package/src/adapters/registry-types.ts

@@ -117,12 +117,36 @@ export interface CapabilityManifest {
   }[];
 }
 
+export interface NativeFactsInput {
+  event: "SessionStart" | "PreInvocation" | "PostInvocation" | "PreToolUse" | "PostToolUse" | "Stop";
+  phase: "session" | "start" | "pre" | "post" | "stop";
+  sessionId: string;
+  transcriptPath: string;
+  workspacePaths: string[];
+  tool: string;
+  input: Record<string, unknown>;
+  toolUseId?: string;
+  invocation?: number;
+  fullyIdle?: boolean;
+  terminationReason?: string;
+}
+export interface NativeFactsTranscript {
+  completion?: { id: string; index: number };
+  factIds: string[];
+}
+/** Fixed native codec and bounded readback, never supplied by project configuration. */
+export interface NativeFactsPort {
+  decode(event: string, input: unknown): NativeFactsInput | undefined;
+  encode(event: string, text?: string): Record<string, unknown> | undefined;
+  read(session: string, transcript: string): NativeFactsTranscript;
+}
+
 /** Only the frozen native seams are extensible; a definition cannot add an arbitrary daemon callback. */
 export interface NativeHooks {
   agentIdentity(init: unknown): void;
   onAttach(instance: string): void;
   onDetach(instance: string): void;
-  factsHook: (msg: unknown) => unknown;
+  factsHook: NativeFactsPort;
   conversationRevert(turnId: string): Promise<void>;
   replaceSession(req: StartRequest): Promise<unknown>;
   pluginInventory(ctx: { home: string; cwd?: string; env: Readonly<Record<string, string | undefined>> }): Addon[];
@@ -229,6 +253,8 @@ export interface AdapterDefinition {
   routing?: {
     /** Takes reviews only: never chosen or nominated as a task owner, for any class. */
     reviewOnly?: true;
+    /** Fixed role ceiling; project roles cannot turn an unmanaged implementer into a planner/reviewer. */
+    allowedRoles?: readonly string[];
     localAllowedRefusal?: string;
     longContext?: "backend-limit" | "skip-owner";
     preferredTier?: boolean;
@@ -253,6 +279,8 @@ export interface AdapterDefinition {
   };
   cli: {
     command: string;
+    /** Configuration leaves that select this peer's next native launch command or provider profile. */
+    launchConfigKeys?: readonly string[];
     /** Restrictions only; core identity remains authoritative. */
     authority?: "person" | "conductor";
     personOnlyFlags?: readonly string[];

package/src/adapters/registry.ts

@@ -1,4 +1,5 @@
-import { AGY_DEFINITION } from "./definitions/reviewer-variants.ts";
+import { AGY_DEFINITION } from "./agy/definition.ts";
+import { AGY_REVIEWER_VARIANT } from "./definitions/reviewer-variants.ts";
 import { builtinCliEntries } from "./definitions/native-cli-entry.ts";
 import { builtinPreview } from "./definitions/native-cli-preview.ts";
 import { DAEMON_PORTS } from "./definitions/native-factories.ts";
@@ -13,7 +14,7 @@ export const ADAPTER_API = 1;
 
 /** Ordered compatibility projections stay typed independently of definition implementation inference. */
 export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
-export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
+export const OPTIONAL_PEERS = ["qwen", "jcode", "agy"] as const;
 export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
 export const START_MODE_PEERS = ["pi", "codex", "kimi"] as const;
 export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
@@ -26,7 +27,7 @@ function immutable<T>(value: T, seen = new WeakSet<object>()): T {
   return Object.freeze(value);
 }
 
-const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION, AGY_DEFINITION]);
+const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION, AGY_DEFINITION, AGY_REVIEWER_VARIANT]);
 for (const definition of [...fixedBuiltinDefinitions]) if (definition.reviewerVariant) fixedBuiltinDefinitions.add(definition.reviewerVariant);
 
 /** Keep the native catalog's order, independently of the legacy default-role object order. */
@@ -34,9 +35,10 @@ export const ADAPTERS: readonly AdapterDefinition[] = immutable([
   ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind !== "jcode"),
   QWEN_DEFINITION,
   ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
+  AGY_DEFINITION,
 ]);
 // Unavailable declarations are metadata, not supported native peers or launchers.
-const declarationOnlyDefinitions: readonly AdapterDefinition[] = immutable([AGY_DEFINITION]);
+const declarationOnlyDefinitions: readonly AdapterDefinition[] = immutable([]);
 const definitions = new Map<string, AdapterDefinition>();
 for (const definition of [...ADAPTERS, ...declarationOnlyDefinitions]) {
   assertDaemonEngine(definition);
@@ -95,7 +97,7 @@ export function familyOf(id: string, instances?: KindMap): string | undefined {
 }
 
 /** Compatibility projection order is observable in default role maps and planner selection. */
-const ROLE_ORDER = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode"] as const;
+const ROLE_ORDER = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode", "agy"] as const;
 export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;
 
 /** Callers own their role arrays, independent of immutable native policy. */
@@ -137,6 +139,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["routing", definition.routing !== undefined],
     ["reviewerVariant", definition.reviewerVariant !== undefined],
     ["reviewer", definition.reviewer !== undefined],
+    ["hooks.factsHook", declared(definition.hooks, "factsHook")],
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);
@@ -145,7 +148,13 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
 /** Ordered catalog projections consumed by generic core hosts. */
 export const STARTABLE_PEERS = SUPPORTED_PEERS;
 export type SupportedPeer = typeof SUPPORTED_PEERS[number];
-export function isSupportedPeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && ADAPTERS.some(definition => definition.kind === peer); }
+export function isSupportedPeer(peer: unknown, instances?: KindMap): peer is string {
+  if (typeof peer !== "string") return false;
+  if (ADAPTERS.some(definition => definition.kind === peer)) return true;
+  const kind = declaredKind(peer, instances);
+  const runtime = ADAPTERS.find(definition => definition.kind === kind), resolved = definitionOf(peer, instances);
+  return runtime !== undefined && resolved !== undefined && (resolved === runtime || resolved.reviewer?.unavailable === undefined);
+}
 export function isStartablePeer(peer: unknown): peer is SupportedPeer { return isSupportedPeer(peer) && definitionOf(peer)?.start.conductorStartable === true; }
 
 /** Body-free browser metadata, derived from the same native participation and managed-tool contracts. */

package/src/adapters/reviewer-mcp.ts

@@ -0,0 +1,85 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import type { HubTool } from "../hub/hub-tools.ts";
+import { sanitize } from "../hub/envelope.ts";
+
+export type ReviewerToolName = "hub_review" | "hub_task_show";
+export interface ReviewerMcpSession { config: string; close(): void }
+export interface ReviewerMcpOptions {
+  task: number;
+  current(): boolean;
+  tools: readonly HubTool[];
+  /** Fixed host port; the host still applies Tasks' role, privacy, head and running-child fences. */
+  call(name: ReviewerToolName, args: Record<string, unknown>): Promise<string>;
+}
+const NAMES: readonly ReviewerToolName[] = ["hub_review", "hub_task_show"];
+const BODY_CAP = 256 * 1024, RESULT_CAP = 4 * 1024 * 1024;
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+
+/** One revocable review capability. This server never reads a daemon control token or accepts a peer/role. */
+export function createReviewerMcpSession(options: ReviewerMcpOptions): ReviewerMcpSession {
+  if (!Number.isSafeInteger(options.task) || options.task < 1) throw new Error("reviewer MCP needs a task");
+  const tools = NAMES.map(name => {
+    const tool = options.tools.find(candidate => candidate.name === name);
+    if (!tool) throw new Error(`reviewer MCP tool missing: ${name}`);
+    return structuredClone(tool);
+  });
+  const authority = Buffer.from(`Bearer ${randomBytes(32).toString("hex")}`);
+  let closed = false, calls = 0;
+  const current = () => { try { return !closed && options.current(); } catch { return false; } };
+  const server = Bun.serve({ hostname: "127.0.0.1", port: 0, maxRequestBodySize: BODY_CAP,
+    async fetch(request) {
+      if (request.headers.has("origin")) return new Response("forbidden", { status: 403 });
+      const supplied = Buffer.from(request.headers.get("authorization") ?? "");
+      if (closed || supplied.length !== authority.length || !timingSafeEqual(supplied, authority)) return new Response("unauthorized", { status: 401 });
+      if (new URL(request.url).pathname !== "/mcp") return new Response("not found", { status: 404 });
+      if (request.method !== "POST") return new Response("method not allowed", { status: 405, headers: { Allow: "POST" } });
+      if (Number(request.headers.get("content-length")) > BODY_CAP) return new Response("body too large", { status: 413 });
+      let body: unknown;
+      try {
+        const reader = request.body?.getReader();
+        let size = 0; const parts: Uint8Array[] = [];
+        if (reader) for (;;) {
+          const part = await reader.read();
+          if (part.done) break;
+          size += part.value.byteLength;
+          if (size > BODY_CAP) { await reader.cancel(); return new Response("body too large", { status: 413 }); }
+          parts.push(part.value);
+        }
+        body = JSON.parse(Buffer.concat(parts).toString("utf8"));
+      } catch { return new Response("invalid request", { status: 400 }); }
+      if (!record(body) || body.jsonrpc !== "2.0" || typeof body.method !== "string") return new Response("invalid request", { status: 400 });
+      const id = body.id;
+      const reply = (result: unknown) => Response.json({ jsonrpc: "2.0", id, result });
+      const error = (message: string, code = -32602) => Response.json({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+      if (!current()) return error("review authority ended", -32001);
+      if (body.method === "notifications/initialized" && id === undefined) return new Response(null, { status: 202 });
+      if (typeof id !== "string" && typeof id !== "number") return error("request id required");
+      if (body.method === "initialize") return reply({ protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "agent-hub-review", version: "1" } });
+      if (body.method === "tools/list") return reply({ tools });
+      if (body.method !== "tools/call") return error("method unavailable", -32601);
+      if (!record(body.params)) return error("tool parameters required");
+      const name = body.params.name;
+      if (name !== "hub_review" && name !== "hub_task_show") return error("tool unavailable");
+      let args = body.params.arguments;
+      if (typeof args === "string") { try { args = JSON.parse(args); } catch { return error("invalid tool arguments"); } }
+      if (!record(args) || args.id !== options.task || !Number.isSafeInteger(args.id)) return error("tool is bound to its review task");
+      if (++calls > 64) return error("review tool call limit", -32002);
+      if (!current()) return error("review authority ended", -32001);
+      try {
+        const result = await options.call(name, args);
+        // Tasks.review rechecks its captured authority through its final write. A successful verdict
+        // ends that in_review binding itself; acknowledge its committed result, never fresh reads.
+        if (name !== "hub_review" && !current()) return error("review authority ended", -32001);
+        if (Buffer.byteLength(result) > RESULT_CAP) return error("tool result exceeds review limit");
+        return reply({ content: [{ type: "text", text: result }] });
+      } catch (failure) {
+        // The same host tool boundary supplies refusals to the released MCP transport.
+        const message = failure instanceof Error ? sanitize(failure.message).slice(0, 4000) : "review tool refused";
+        return reply({ isError: true, content: [{ type: "text", text: message }] });
+      }
+    },
+  });
+  return { config: JSON.stringify({ mcpServers: { "agent-hub": { transport: "http", url: `http://127.0.0.1:${server.port}/mcp`, headers: { Authorization: authority.toString() } } } }),
+    close() { if (closed) return; closed = true; authority.fill(0); void server.stop(true); },
+  };
+}

package/src/adapters/reviewer-print.ts

@@ -4,6 +4,7 @@ import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process
 import { HUB, frame } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
+import type { ReviewerMcpSession } from "./reviewer-mcp.ts";
 
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
@@ -12,8 +13,11 @@ export interface ReviewerIsolationReceipt {
   binary: string;
   profile: string;
   readOnly: true;
-  strictMcp: true;
-  ephemeral: true;
+  strictMcp: boolean;
+  ephemeral: boolean;
+  enforcement?: "kernel" | "native-policy";
+  freshSession?: true;
+  hubToolsOnly?: true;
   evidence: readonly string[];
 }
 export interface ReviewerPrepareContext {
@@ -25,6 +29,9 @@ export interface ReviewerPrepareContext {
   privatePaths: readonly string[];
   command?: readonly string[];
   signal: AbortSignal;
+  /** Host-framed public review evidence, never configuration-selected argv. */
+  input?: string;
+  task?: number;
 }
 export interface ReviewerLaunch {
   command: readonly string[];
@@ -34,9 +41,16 @@ export interface ReviewerLaunch {
   current?: () => boolean;
   env?: NodeJS.ProcessEnv;
   cleanup?: () => void | Promise<void>;
+  cwd?: string;
+  envMode?: "replace";
+  stop?: (child: ChildProcess) => Promise<void>;
+  /** Latch a change in native policy for the running review, not just at spawn. */
+  watchCurrent?: true;
 }
 export interface ReviewerBackend {
   id: string;
+  taskMcp?: true;
+  nativePolicy?: true;
   prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }>;
   usage?(event: unknown): ReviewerPrintUsage | undefined;
   failure?(event: unknown): "quota" | undefined;
@@ -48,6 +62,7 @@ export interface ReviewerFailure {
   cause: "start_failed" | "quota" | "no_verdict";
 }
 
+export interface ReviewerReviewBinding { readonly head?: string; readonly flowRevision?: number }
 export interface ReviewerPrintOptions {
   cwd: string;
   command?: readonly string[];
@@ -61,6 +76,10 @@ export interface ReviewerPrintOptions {
   onUsage?(usage: ReviewerPrintUsage, task: number): void;
   onUnavailable?(failure: ReviewerFailure, current: () => boolean): void | Promise<void>;
   log?(line: string): void;
+  taskMcp?(task: number, current: () => boolean): ReviewerMcpSession;
+  /** Synchronous host task/privacy/policy fence, checked again after awaited preparation. */
+  admit?(env: Envelope): boolean;
+  bindingCurrent?(task: number, binding: ReviewerReviewBinding): boolean;
 }
 
 // ponytail: 256 KiB per NDJSON frame and 4 MiB stdout per review child. Raise only with measured native receipts.
@@ -86,6 +105,10 @@ export class ReviewerPrintPeer extends BasePeer {
   readonly hubNative = true;
   private generation = 0;
   private child: ChildProcess | undefined;
+  private childStop: ((child: ChildProcess) => Promise<void>) | undefined;
+  private childCleanup: (() => Promise<void>) | undefined;
+  private childCurrent: (() => boolean) | undefined;
+  private reviewMcpClose: (() => void) | undefined;
   private activeDeliveryId: string | undefined;
   private batch: ReviewBatch | undefined;
   private preparation: { abort: AbortController; done: Promise<ReviewerLaunch> } | undefined;
@@ -94,8 +117,18 @@ export class ReviewerPrintPeer extends BasePeer {
   /** The task whose review the running child was started for (R4: the hub records `fresh` for its verdict). */
   reviewing: number | undefined;
   private reviewSeq = 0;
+  private runningBinding: { task: number; binding: ReviewerReviewBinding } | undefined;
+  /** Immutable envelope identity of this running child, never the board's later head. */
+  reviewBinding(task: number): ReviewerReviewBinding | undefined {
+    return this.reviewing === task && this.runningBinding?.task === task ? this.runningBinding.binding : undefined;
+  }
   /** 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; }
+  reviewToken(task: number): number | undefined {
+    if (this.reviewing !== task) return undefined;
+    try { if (this.childCurrent?.() === false) { this.abortReview("review policy changed"); return undefined; } }
+    catch { this.abortReview("review policy changed"); return undefined; }
+    return this.reviewSeq;
+  }
 
   constructor(id: string, private readonly opts: ReviewerPrintOptions) { super(id, opts.watchdogMs); }
 
@@ -119,6 +152,7 @@ export class ReviewerPrintPeer extends BasePeer {
 
   async stop(reason?: string): Promise<void> {
     this.generation++; // fence before the first await: a late exit settles nothing
+    this.reviewMcpClose?.();
     this.receipt = undefined;
     this.batch = undefined;
     this.preparation?.abort.abort();
@@ -131,9 +165,10 @@ export class ReviewerPrintPeer extends BasePeer {
 
   protected override onWatchdog(): void { this.abortReview("review watchdog timeout"); }
 
-  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded"): void {
+  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded" | "review policy changed"): void {
     const generation = ++this.generation, batch = this.batch, preparation = this.preparation;
     this.reviewing = undefined;
+    this.reviewMcpClose?.();
     this.receipt = undefined;
     this.clearWatchdog();
     preparation?.abort.abort();
@@ -230,14 +265,20 @@ export class ReviewerPrintPeer extends BasePeer {
     }
   }
 
-  private prepare(sessionId: string): Promise<ReviewerLaunch> {
+  private prepare(sessionId: string, input?: string, task?: number, mcpConfig?: string): Promise<ReviewerLaunch> {
     const abort = new AbortController();
     const done = (async () => {
-      const launch = await this.opts.backend.prepare({ peer: this.id, cwd: this.opts.cwd, sessionId, mcpConfig: this.opts.mcpConfig,
-        systemPrompt: this.opts.systemPrompt, privatePaths: this.opts.privatePaths ?? [], command: this.opts.command, signal: abort.signal });
+      if (this.opts.backend.taskMcp && !this.opts.taskMcp) throw new Error("task-bound reviewer MCP is unavailable");
+      const launch = await this.opts.backend.prepare({ peer: this.id, cwd: this.opts.cwd, sessionId,
+        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);
       const proof = launch.isolation;
-      if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || proof.strictMcp !== true || proof.ephemeral !== true || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length) {
+      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");
       }
@@ -250,25 +291,44 @@ export class ReviewerPrintPeer extends BasePeer {
   }
 
   private async review(env: Envelope, task: number, generation: number): Promise<{ code: number | null; quota: boolean }> {
-    const launch = await this.prepare(randomUUID());
+    if (this.opts.admit?.(env) === false) throw new Error("review admission changed");
+    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}`); }
+    const input = `${frame(env)}${facts ? `\n\n${facts}` : ""}`;
+    let launch: ReviewerLaunch | undefined;
+    const revision=Number(env.refs?.reviewRevision);
+    const binding: ReviewerReviewBinding=Object.freeze({head:env.refs?.commit,flowRevision:Number.isSafeInteger(revision)&&revision>0?revision:undefined});
+    const mcp = this.opts.backend.taskMcp ? this.opts.taskMcp?.(task, () => generation === this.generation && this.reviewToken(task) !== undefined && this.opts.bindingCurrent?.(task,binding) !== false) : undefined;
+    let mcpClosed=false;
+    const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
+    this.reviewMcpClose=closeMcp;
+    let ownedChild: ChildProcess | undefined, releasing: Promise<void> | undefined;
+    let policyTimer: ReturnType<typeof setInterval> | undefined;
+    const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
-    if (generation !== this.generation || launch.current?.() === false) throw new Error("reviewer isolation changed before child spawn");
+    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");
     this.receipt = launch.isolation;
     const [cmd, ...prefix] = launch.command;
     let quota = false;
     return await new Promise<{ code: number | null; quota: boolean }>((resolve, reject) => {
-      const child = spawn(cmd!, [...prefix, ...launch.args], { cwd: this.opts.cwd, detached: true, env: peerChildEnv(this.id, { ...process.env, ...launch.env }), stdio: ["pipe", "pipe", "ignore"] });
+      const child = spawn(cmd!, [...prefix, ...launch!.args], { cwd: launch!.cwd ?? this.opts.cwd, detached: true,
+        env: peerChildEnv(this.id, launch!.envMode === "replace" ? launch!.env : { ...process.env, ...launch!.env }), 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); });
+      ownedChild = child;
+      this.childStop = launch!.stop;
+      this.childCleanup = release;
+      this.childCurrent = launch!.watchCurrent ? launch!.current : undefined;
+      child.once("error", error => { if (this.child === child) { this.child = undefined; this.childStop = 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.runningBinding={task,binding};
         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}` : ""}`);
+        if (this.childCurrent) policyTimer = setInterval(() => { this.reviewToken(task); }, 100);
+        child.stdin!.end(input);
       });
       let buffer = "", outputBytes = 0;
       child.stdout!.on("data", (chunk: Buffer) => {
@@ -290,14 +350,16 @@ export class ReviewerPrintPeer extends BasePeer {
         this.touch();
       });
       child.once("exit", code => {
-        if (this.child === child) this.reviewing = undefined; // the verdict authority ends with the leader
+        if (this.child === child) { this.reviewing = undefined; this.runningBinding=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, quota }); },
+        (launch!.stop ? launch!.stop(child) : stopOwnedProcess(child, { group: true })).then(() => { if (this.child === child) { this.child = undefined; this.childStop = undefined; } resolve({ code, quota }); },
           (error: Error) => reject(new GroupCleanupError(error.message)));
       });
     });
     } finally {
-      try { await launch.cleanup?.(); }
+      closeMcp();
+      if (policyTimer) clearInterval(policyTimer);
+      try { if (!ownedChild || this.child !== ownedChild) { await release(); if (this.childCleanup === release) this.childCleanup = undefined; } }
       catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
     }
   }
@@ -311,9 +373,10 @@ export class ReviewerPrintPeer extends BasePeer {
   /** 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;
+    this.runningBinding=undefined;
     const child = this.child;
     if (!child) return;
-    await stopOwnedProcess(child, { group: true });
-    if (this.child === child) this.child = undefined;
+    await (this.childStop ? this.childStop(child) : stopOwnedProcess(child, { group: true }));
+    if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childStop = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
   }
 }