@staix/agent-hub 0.12.36 → 0.12.38

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

@@ -69,7 +69,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   turnEnd: "adapter",
   budget: { account: "qwen" },
   capabilities: { watch: true },
-  cli: { command: "qwen", startWords: () => ["qwen"] },
+  cli: { command: "qwen", launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
   display: QWEN_DISPLAY,
   hooks: { agentIdentity: init => { qwenNativeIdentity("qwen", true, init); }, recallPlatform: "qwen" },
 };

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

@@ -0,0 +1,33 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+import { claudeReviewerBackend } from "../claude-print.ts";
+import { codexReviewerBackend } from "../codex-review-isolation.ts";
+import { kimiReviewerBackend } from "../kimi-review.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", { backend: kimiReviewerBackend, defaultPool: true, declaration: "explicit" }, KIMI_DISPLAY);
+/** Data-only declared placeholder for route explanations; no factory, backend or native argv. */
+export const AGY_REVIEWER_VARIANT: AdapterDefinition = {
+  ...reviewerVariant("agy", "agy reviewer", { defaultPool: false, declaration: "automatic", unavailable: "agy is an implementer peer (#485)" }, { palette: { fg: "#6558a6", bg: "#f1effa" } }),
+  optional: true,
+};

package/src/adapters/jcode.ts

@@ -17,15 +17,29 @@ export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: s
   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"])];
 }
+/** Set on every owned jcode process: no Claude MCP import, and no native telemetry (jcode-telemetry-core is_enabled, #529). */
+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;
+}
+
 /** The wrapper contract preserves every configured prefix argument before the native probe. */
 export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
   const [bin, ...prefix] = command;
   if (!bin) return false;
   try {
-    const result = spawnSync(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: peerChildEnv("jcode"), encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 });
+    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 version.semver === "0.94.0";
+    return jcodeVersionSupported(version.semver);
   } catch { return false; }
 }
 
@@ -41,9 +55,10 @@ 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");
     jcodeCommand(jcode.command, "acp", "preview", jcode.cwd);
-    const root = mkdtempSync(join(tmpdir(), "ahub-jcode-")), socket = join(root, "s");
+    // 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_DISABLE_CLAUDE_MCP: "1" }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: "0.94.0" } });
+    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;
   }
 
@@ -53,7 +68,7 @@ export class JcodePeer extends AcpPeer {
     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_DISABLE_CLAUDE_MCP: "1" }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
+    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"] });
     this.server = server; trackGroup(server);
     try {
       await new Promise<void>((resolve, reject) => {

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

@@ -1,3 +1,4 @@
+import type { ReviewerBackend, ReviewerPrintOptions } from "./reviewer-print.ts";
 import type { SettingDef } from "../hub/settings.ts";
 import type { Addon } from "../hub/tooling.ts";
 import type { RecoveryContinuityBookmark } from "../hub/recovery-continuity.ts";
@@ -16,7 +17,7 @@ import type { PiOptions } from "./pi.ts";
 import type { ClaudePrintOptions } from "./claude-print.ts";
 
 export type StartForm = "tui" | "headless";
-export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print";
+export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print";
 
 /** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
 export interface LaunchContext {
@@ -55,7 +56,8 @@ export type DaemonPorts =
   | { jcode: JcodeOptions }
   | { pi: PiOptions }
   | { local: LocalOptions }
-  | { claudePrint: ClaudePrintOptions };
+  | { claudePrint: ClaudePrintOptions }
+  | { reviewerPrint: ReviewerPrintOptions };
 
 export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
@@ -115,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[];
@@ -227,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;
@@ -251,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[];
@@ -264,7 +294,9 @@ export interface AdapterDefinition {
   hooks?: Partial<NativeHooks>;
   /** #223: what a declared headless reviewer-only instance of this kind runs as. Fixed builtins only. */
   reviewerVariant?: AdapterDefinition;
+  /** Fixed host backend; runtime isolation proof is required before bus admission. */
+  reviewer?: { backend?: ReviewerBackend; defaultPool: boolean; unavailable?: string; declaration: "automatic" | "explicit" };
 }
 
 /** Explicit project declarations, passed by the bound host. No process-global instance registration. */
-export type KindMap = Readonly<Record<string, { readonly kind: string }>>;
+export type KindMap = Readonly<Record<string, { readonly kind: string; readonly roles?: readonly string[]; readonly start_mode?: "tui" | "headless"; readonly review_mode?: "fresh" }>>;

package/src/adapters/registry.ts

@@ -1,3 +1,5 @@
+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";
@@ -12,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;
@@ -25,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]);
+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. */
@@ -33,9 +35,12 @@ 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([]);
 const definitions = new Map<string, AdapterDefinition>();
-for (const definition of ADAPTERS) {
+for (const definition of [...ADAPTERS, ...declarationOnlyDefinitions]) {
   assertDaemonEngine(definition);
   assertNativeCapabilityScope(definition);
   if (definition.reviewerVariant) { assertDaemonEngine(definition.reviewerVariant); assertNativeCapabilityScope(definition.reviewerVariant); }
@@ -43,6 +48,10 @@ for (const definition of ADAPTERS) {
   definitions.set(definition.kind, definition);
 }
 
+/** Default kind slots derive from fixed reviewer policy, not a second vendor list in the host. */
+export const REVIEW_POOL_KINDS: readonly string[] = Object.freeze([...definitions.values()].filter(definition => !!(definition.reviewerVariant ?? definition).reviewer).map(definition => definition.kind));
+export const DEFAULT_REVIEW_POOL: readonly string[] = Object.freeze(ADAPTERS.filter(definition => (definition.reviewerVariant ?? definition).reviewer?.defaultPool === true).map(definition => definition.kind));
+
 /** Native quota handoff platform names, distinct from per-delivery recall injection policy. */
 export const QUOTA_HANDOFF_PLATFORMS: Readonly<Record<string, string>> = Object.freeze(Object.fromEntries(
   ADAPTERS.flatMap(adapter => adapter.hooks?.recallPlatform ? [[adapter.kind, adapter.hooks.recallPlatform]] : []),
@@ -77,14 +86,18 @@ export function definitionOf(id: string, instances?: KindMap): AdapterDefinition
   const kind = kindOf(id, instances);
   const definition = kind === undefined ? undefined : definitions.get(kind);
   // #223: only a declared extra (never the builtin id) with start_mode "headless" runs as the kind's reviewer variant.
-  return definition?.reviewerVariant && kind !== id && ownField(ownField(instances, id), "start_mode") === "headless" ? definition.reviewerVariant : definition;
+  const declaration = ownField(instances, id), roles = ownField(declaration, "roles");
+  const reviewerOnly = Array.isArray(roles) && !types.isProxy(roles) && roles.length === 1 && Object.getOwnPropertyDescriptor(roles, "0")?.value === "reviewer";
+  const variant = definition?.reviewerVariant;
+  const fresh = variant?.reviewer?.declaration === "automatic" || ownField(declaration, "review_mode") === "fresh";
+  return variant && kind !== id && reviewerOnly && ownField(declaration, "start_mode") === "headless" && fresh ? variant : definition;
 }
 export function familyOf(id: string, instances?: KindMap): string | undefined {
   return definitionOf(id, instances)?.family;
 }
 
 /** 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. */
@@ -125,6 +138,8 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["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`);
@@ -133,8 +148,14 @@ 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" && definitionOf(peer) !== undefined; }
-export function isStartablePeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && definitionOf(peer)?.start.conductorStartable === true; }
+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. */
 export const ADAPTER_DISPLAY = Object.fromEntries(ADAPTERS.map(adapter => [adapter.kind, {

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); },
+  };
+}