@staix/agent-hub 0.34.0 → 0.35.0

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

@@ -1,8 +1,41 @@
 import { retainedLaunchWarning } from "./native-cli-retained.ts";
-import { resolve } from "node:path";
-import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { assessVersion, COMPAT } from "../compat.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
+import { cleanupKimiPlugin, ensureKimiPlugin, type KimiPluginOptions } from "../../cli/kimi-plugin.ts";
+
+export function kimiTuiVersionGate(stdout: string): { ok: true; message?: string } | { ok: false; message: string } {
+  const verdict = assessVersion("kimi-tui", COMPAT["kimi-tui"].parse(stdout));
+  if (!verdict.ok) return { ok: false, message: verdict.reason };
+  return verdict.note ? { ok: true, message: verdict.note } : { ok: true };
+}
+
+export function kimiTuiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv) {
+  return { cwd, env, stdio: "inherit" as const };
+}
+
+export function kimiTuiVersionProbe(launch: { cmd: string; args: string[] }): { cmd: string; args: string[] } {
+  return { cmd: launch.cmd, args: [...launch.args, "--version"] };
+}
+
+function runKimiTui(cmd: string, args: string[], cwd: string, env: NodeJS.ProcessEnv): Promise<{ error?: Error; status: number | null }> {
+  const child = spawn(cmd, args, kimiTuiSpawnOptions(cwd, env));
+  return new Promise(resolveExit => {
+    const forward = (signal: NodeJS.Signals) => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      try { child.kill(signal); } catch { /* the native child may exit as the signal arrives */ }
+    };
+    const onInterrupt = () => forward("SIGINT"), onTerminate = () => forward("SIGTERM"), onHangup = () => forward("SIGHUP");
+    const cleanup = () => { process.off("SIGINT", onInterrupt); process.off("SIGTERM", onTerminate); process.off("SIGHUP", onHangup); };
+    process.on("SIGINT", onInterrupt); process.on("SIGTERM", onTerminate); process.on("SIGHUP", onHangup);
+    child.once("error", error => { cleanup(); resolveExit({ error, status: null }); });
+    child.once("close", code => { cleanup(); resolveExit({ status: code }); });
+  });
+}
 
 export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "kimi";
@@ -42,20 +75,56 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       if (!admission.ok) fail(admission.error);
       const runningCommand = admission.retainedLaunchConfig?.kimi_cmd;
       let launch: ReturnType<typeof buildKimiTuiLaunch>;
-      let result: ReturnType<typeof spawnSync>;
+      let result: { error?: Error; status: number | null };
       try {
         // Inside the try: a kimi_cmd with no TUI form throws here, and the admission must still be released (#549).
         // The running hub's value wins over the file's while a reload is retained (#654): when it has no TUI form, say whose it is, so the
         // error is not read as a fault in the file. The words themselves are never echoed.
         const running = Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string");
-        try { launch = buildKimiTuiLaunch(running ? runningCommand : projectConfig().kimi_cmd, model); }
+        const command = running ? runningCommand : projectConfig().kimi_cmd;
+        try { launch = buildKimiTuiLaunch(command, model); }
         catch (error) {
           throw running ? new Error(`${(error as Error).message} (the command is the running hub's kimi_cmd: the value in the config file is retained until ahub settings reload)`) : error;
         }
-        // The daemon's own bundle, so the MCP server matches the hub it talks to (#502); this CLI's copy only for an older hub.
-        const written = configureKimiMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"), "tui");
+        const probe = kimiTuiVersionProbe(buildKimiTuiLaunch(command));
+        const version = spawnSync(probe.cmd, probe.args, { encoding: "utf8", timeout: 5000, maxBuffer: 4096, env: nativeLaunchEnv("kimi", childEnv()) });
+        const gate = kimiTuiVersionGate(version.status === 0 ? version.stdout : "");
+        if (version.status === 0 && version.stdout.trim() && gate.message) console.error(`${gate.message}. Completion receipts are off; the TUI launches as before.`);
+        // The daemon's own bundles, so the MCP server and native hook match the hub they talk to (#502, #1282).
+        const serverBundle = bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js");
+        const written = configureKimiMcp(cwd, stateDir, serverBundle, "tui");
         if (written.tracked) console.error(".kimi-code/mcp.json is tracked; the agent-hub entry contains machine paths. Review this local change before committing it.");
-        result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+        const nativeEnv: NodeJS.ProcessEnv = { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+        if (!gate.ok) {
+          result = await runKimiTui(launch.cmd, launch.args, cwd, nativeEnv);
+        } else {
+          const nativeHome = nativeEnv.KIMI_CODE_HOME ?? join(nativeEnv.HOME ?? homedir(), ".kimi-code");
+          let nativeLaunchId: string | undefined, completionEnv: NodeJS.ProcessEnv | undefined, plugin: KimiPluginOptions | undefined;
+          try {
+            mkdirSync(nativeHome, { recursive: true, mode: 0o700 });
+            const native = await hub.request({ t: "native_hook_launch", op: "begin", peer, nativeHome });
+            if (!native.ok || typeof native.launchId !== "string" || typeof native.instanceId !== "string") throw new Error(native.error ?? "native hook launch was not admitted");
+            nativeLaunchId = native.launchId;
+            plugin = { home: nativeHome, hookScript: resolve(serverBundle, "../kimi-hook.js"), launchId: native.launchId, replaceStale: true };
+            console.error(`Kimi TUI completion facts: installing a launch-scoped native plugin under ${join(nativeHome, "plugins", "managed", "agent-hub")}; it will be removed after this TUI exits`);
+            ensureKimiPlugin(plugin);
+            completionEnv = { ...nativeEnv, AGENTHUB_INSTANCE_ID: native.instanceId, AGENTHUB_LAUNCH_ID: native.launchId, AGENTHUB_HOOK_PURPOSE: "facts" };
+          } catch (error) {
+            console.error(`Kimi TUI completion facts are unavailable: ${(error as Error).message}. Continuing without completion receipts; resolve the cause and restart to enable them.`);
+            if (nativeLaunchId) await hub.request({ t: "native_hook_launch", op: "end", peer, launchId: nativeLaunchId }).catch(() => {});
+            if (plugin) try { cleanupKimiPlugin(plugin); } catch { console.error(`Managed Kimi plugin cleanup refused: files or ownership changed; inspect ${join(nativeHome, "plugins", "managed", "agent-hub")} before removing it`); }
+          }
+          if (completionEnv) {
+            try {
+              result = await runKimiTui(launch.cmd, launch.args, cwd, completionEnv);
+            } finally {
+              if (nativeLaunchId) await hub.request({ t: "native_hook_launch", op: "end", peer, launchId: nativeLaunchId }).catch(() => {});
+              if (plugin) try { cleanupKimiPlugin(plugin); } catch { console.error(`Managed Kimi plugin cleanup refused: files or ownership changed; inspect ${join(nativeHome, "plugins", "managed", "agent-hub")} before removing it`); }
+            }
+          } else {
+            result = await runKimiTui(launch.cmd, launch.args, cwd, nativeEnv);
+          }
+        }
       } finally {
         if (admission.admissionId) await hub.request({ t: "kimi_launch_end", admissionId: admission.admissionId }).catch(() => {});
       }

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

@@ -26,10 +26,10 @@ export interface NativePreviewContext {
   /** The declared extra instance a `--as <id>` launch selected; its own model fields belong in the preview (#685). */
   instance?: string;
 }
-export interface NativePreviewMetadata { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean } }
+export interface NativePreviewMetadata { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean }; completionPlugin?: { file: string; action: string; changed: boolean } }
 export type NativePreviewBuilder = (ctx: NativePreviewContext) => NativePreview;
 export interface NativePreview {
-  tool: string; mode?: "tui" | "headless"; mcp?: NativePreviewMetadata["mcp"];
+  tool: string; mode?: "tui" | "headless"; mcp?: NativePreviewMetadata["mcp"]; completionPlugin?: NativePreviewMetadata["completionPlugin"];
   cmd: string; args: string[]; settings: string | undefined; envNames: string[]; warning?: string;
   unresolved: { field: string; reason: string }[]; redaction: string; needs: string[];
 }

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

@@ -1,4 +1,6 @@
 import { join } from "node:path";
+import { homedir } from "node:os";
+import { kimiPluginPreview } from "../../cli/kimi-plugin.ts";
 import type { Launch } from "../../cli/launch.ts";
 import { REDACTED, nativeCommand, previewState, finishPreview, type NativePreviewContext, type NativePreviewMetadata } from "./native-cli-preview-common.ts";
 
@@ -9,6 +11,7 @@ export function previewKimi(ctx: NativePreviewContext) {
   let envNames = state.envNames;
   let launch: Launch;
   let kimiMetadata: NativePreviewMetadata | undefined;
+  let completionPlugin: NativePreviewMetadata["completionPlugin"];
   const model = value("--model");
   const mode = value("--mode") ?? startModeOf(config.peers, "kimi");
   if (mode !== "tui" && mode !== "headless") throw new Error("invalid Kimi mode");
@@ -19,10 +22,14 @@ export function previewKimi(ctx: NativePreviewContext) {
   } else {
     const native = buildKimiTuiLaunch(config.kimi_cmd, model ? REDACTED : undefined);
     launch = { ...native, cmd: native.cmd === "kimi" ? "kimi" : REDACTED, args: native.args.map(arg => arg === "--model" || arg === REDACTED ? arg : REDACTED) };
-    envNames = Object.keys(nativeLaunchEnv("kimi", childEnv())).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
+    const nativeEnv = nativeLaunchEnv("kimi", childEnv());
+    envNames = Object.keys(nativeEnv).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR", "AGENTHUB_INSTANCE_ID", "AGENTHUB_LAUNCH_ID", "AGENTHUB_HOOK_PURPOSE"]);
+    unresolved.push({ field: "nativeLaunchId", reason: "native completion facts bind to the launch admitted by the running hub" });
+    const home = nativeEnv.KIMI_CODE_HOME ?? join(nativeEnv.HOME ?? homedir(), ".kimi-code");
+    completionPlugin = kimiPluginPreview(home, join(cliDir, "../../plugins/agent-hub/kimi-hook.js"));
   }
   const { file, action, changed, tracked } = kimiMcpPlan(cwd, stateDir, join(cliDir, "../../plugins/agent-hub/server.js"), mode);
-  kimiMetadata = { mode, mcp: { file, action, changed, tracked } };
+  kimiMetadata = { mode, mcp: { file, action, changed, tracked }, ...(completionPlugin ? { completionPlugin } : {}) };
 
   return finishPreview(ctx, launch, envNames, unresolved, kimiMetadata);
 }

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

@@ -16,11 +16,13 @@ function reviewerVariant(kind: string, displayName: string, reviewer: NonNullabl
     permission: { 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 },
+    // A fresh reviewer never inherits a long-lived ACP setter through a base/variant merge.
+    modelOverride: undefined,
     reviewer, cli: { command: kind, startWords: () => [] }, display,
   };
 }
 const codexVariant = reviewerVariant("codex", "Codex reviewer", { backend: codexReviewerBackend, defaultPool: true, declaration: "explicit", scope: "code" }, CODEX_DISPLAY);
-export const CODEX_REVIEWER_VARIANT: AdapterDefinition = { ...codexVariant, start: { ...codexVariant.start, create: createCodexReviewer } };
+export const CODEX_REVIEWER_VARIANT: AdapterDefinition = { ...codexVariant, modelOverride: { boundary: "turn" }, start: { ...codexVariant.start, create: createCodexReviewer } };
 export const KIMI_REVIEWER_VARIANT = reviewerVariant("kimi", "Kimi reviewer", { backend: kimiReviewerBackend, defaultPool: true, declaration: "explicit", scope: "code" }, KIMI_DISPLAY);
 /** Data-only declared placeholder for route explanations; no factory, backend or native argv. */
 export const AGY_REVIEWER_VARIANT: AdapterDefinition = {

package/src/adapters/kimi-review-policy-worker.js

@@ -0,0 +1,2 @@
+// Source entry; the plugin carries a self-contained bundle at this same basename.
+import "./kimi-review-policy-worker.ts";

package/src/adapters/kimi-review-policy-worker.ts

@@ -0,0 +1,85 @@
+import { isMainThread, parentPort, workerData, Worker } from "node:worker_threads";
+import { checkKimiReviewPolicy, projectKimiReviewPolicyBinding, type KimiReviewPolicyBinding } from "./kimi-review-policy.ts";
+import type { ReviewerPolicyProbe } from "./reviewer-policy-watch.ts";
+
+/** Trusted host fixture only: two numeric cells, entered count then release flag. */
+export interface KimiReviewPolicyWorkerOptions { gate?: SharedArrayBuffer }
+export type KimiReviewPolicyFactory = (binding: KimiReviewPolicyBinding) => ReviewerPolicyProbe;
+
+export function startKimiReviewPolicyWatch(binding: KimiReviewPolicyBinding, options: KimiReviewPolicyWorkerOptions = {}): ReviewerPolicyProbe {
+  const projected = projectKimiReviewPolicyBinding(binding);
+  if (options.gate && options.gate.byteLength !== 8) throw new Error("review policy fixture gate is invalid");
+  let worker: Worker;
+  try {
+    worker = new Worker(new URL("./kimi-review-policy-worker.js", import.meta.url), {
+      env: {}, execArgv: [], stdout: true, stderr: true,
+      workerData: { binding: projected, ...(options.gate ? { gate: options.gate } : {}) },
+    });
+  } catch { throw new Error("review policy worker could not start; retry the review"); }
+  let failed = false, stopping = false, exited = false, sequence = 0;
+  let pending: { id: number; resolve: (current: boolean) => void } | undefined;
+  let stopWork: Promise<void> | undefined;
+  let resolveExit!: () => void, resolveFailure!: () => void;
+  const exit = new Promise<void>(resolve => { resolveExit = resolve; });
+  const failure = new Promise<void>(resolve => { resolveFailure = resolve; });
+  const settle = (current: boolean) => { const request = pending; pending = undefined; request?.resolve(current); };
+  const fail = () => { failed = true; resolveFailure(); settle(false); };
+  worker.on("error", fail);
+  worker.on("exit", () => { exited = true; fail(); resolveExit(); });
+  try {
+    // Never inherit/forward worker output. Unexpected output invalidates the proof.
+    worker.stdout?.on("data", fail); worker.stderr?.on("data", fail);
+    worker.on("message", (message: unknown) => {
+      if (stopping || failed) return;
+      if (!message || typeof message !== "object" || Array.isArray(message)) return fail();
+      const reply = message as Record<string, unknown>;
+      if (Object.keys(reply).sort().join() !== "current,id" || !pending || reply.id !== pending.id || typeof reply.current !== "boolean") return fail();
+      if (!reply.current) return fail();
+      settle(true);
+    });
+  } catch { fail(); } // Return ownership even if runtime stream setup failed.
+  return {
+    failure,
+    check() {
+      if (failed || stopping || exited) return Promise.resolve(false);
+      if (pending || sequence >= Number.MAX_SAFE_INTEGER) { fail(); return Promise.resolve(false); }
+      return new Promise<boolean>(resolve => {
+        pending = { id: ++sequence, resolve };
+        try { worker.postMessage({ id: sequence }); } catch { fail(); }
+      });
+    },
+    stop() {
+      if (stopWork) return stopWork;
+      stopping = true; fail();
+      stopWork = (async () => {
+        if (!exited) await worker.terminate();
+        await exit;
+      })().catch(() => {
+        stopWork = undefined; // The same owner may explicitly retry an unconfirmed join.
+        throw new Error("review policy worker stop is unconfirmed; retry stopping the review");
+      });
+      return stopWork;
+    },
+  };
+}
+
+if (!isMainThread) {
+  const port = parentPort;
+  if (!port || Object.keys(process.env).length !== 0 || process.execArgv.length !== 0) throw new Error("review policy worker environment is invalid");
+  const data = workerData as { binding: KimiReviewPolicyBinding; gate?: SharedArrayBuffer };
+  const binding = projectKimiReviewPolicyBinding(data.binding);
+  const gate = data.gate ? new Int32Array(data.gate) : undefined;
+  if (gate && gate.length !== 2) throw new Error("review policy fixture gate is invalid");
+  let last = 0;
+  port.on("message", (message: unknown) => {
+    if (!message || typeof message !== "object" || Array.isArray(message)) throw new Error("review policy request is invalid");
+    const request = message as Record<string, unknown>;
+    if (Object.keys(request).join() !== "id" || request.id !== last + 1) throw new Error("review policy request is invalid");
+    last++;
+    if (gate) {
+      Atomics.add(gate, 0, 1); Atomics.notify(gate, 0);
+      while (Atomics.load(gate, 1) === 0) Atomics.wait(gate, 1, 0);
+    }
+    port.postMessage({ id: last, current: checkKimiReviewPolicy(binding) });
+  });
+}

package/src/adapters/kimi-review-policy.ts

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { realPath } from "../hub/project.ts";
+
+export interface KimiReviewPolicyBinding {
+  readonly lexicalCwd: string;
+  readonly physicalCwd: string;
+  readonly sourcePath: string;
+  readonly source: string;
+  readonly sourceConfig: string;
+  readonly sourceConfigHash: string;
+  readonly executable: string;
+  readonly executableStat: Readonly<{ dev: number; ino: number; size: number; mtimeMs: number; ctimeMs: number }>;
+  readonly privateFiles: readonly Readonly<{ path: string; hash: string }>[];
+  readonly tool: string;
+  readonly authTargets: readonly string[];
+}
+export const kimiReviewFingerprint = (text: string): string => createHash("sha256").update(text).digest("hex");
+export function readKimiReviewFile(file: string, limit = 262_144): string {
+  const stat = lstatSync(file); if (!stat.isFile() || stat.size > limit) throw new Error("unsupported reviewer file");
+  return readFileSync(file, "utf8");
+}
+/** Native discovery can walk above cwd; check lexical aliases as well as the physical temporary root. */
+export 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;
+    }
+  }
+}
+/** Closed projection: no input, config contents, environment or extra caller fields cross the worker boundary. */
+export function projectKimiReviewPolicyBinding(binding: KimiReviewPolicyBinding): KimiReviewPolicyBinding {
+  return Object.freeze({
+    lexicalCwd: binding.lexicalCwd, physicalCwd: binding.physicalCwd,
+    sourcePath: binding.sourcePath, source: binding.source,
+    sourceConfig: binding.sourceConfig, sourceConfigHash: binding.sourceConfigHash,
+    executable: binding.executable,
+    executableStat: Object.freeze({ dev: binding.executableStat.dev, ino: binding.executableStat.ino,
+      size: binding.executableStat.size, mtimeMs: binding.executableStat.mtimeMs, ctimeMs: binding.executableStat.ctimeMs }),
+    privateFiles: Object.freeze(binding.privateFiles.map(file => Object.freeze({ path: file.path, hash: file.hash }))),
+    tool: binding.tool, authTargets: Object.freeze(binding.authTargets.map(target => target)),
+  });
+}
+/** The complete filesystem fence, shared by synchronous authority checks and the periodic worker. */
+export function checkKimiReviewPolicy(binding: KimiReviewPolicyBinding): boolean {
+  try {
+    assertCleanCwdAncestors(binding.lexicalCwd, binding.physicalCwd);
+    const now = lstatSync(binding.executable), expected = binding.executableStat;
+    return realPath(binding.sourcePath) === binding.source
+      && now.dev === expected.dev && now.ino === expected.ino && now.size === expected.size
+      && now.mtimeMs === expected.mtimeMs && now.ctimeMs === expected.ctimeMs
+      && kimiReviewFingerprint(readKimiReviewFile(binding.sourceConfig)) === binding.sourceConfigHash
+      && binding.privateFiles.length === 3 && binding.privateFiles.every(file => kimiReviewFingerprint(readKimiReviewFile(file.path, 2_097_152)) === file.hash)
+      && binding.authTargets.length === 3 && ["credentials", "oauth", "device_id"].every((name, index) =>
+        realPath(join(binding.source, name)) === binding.authTargets[index] && realPath(join(binding.tool, name)) === binding.authTargets[index]);
+  } catch { return false; }
+}

package/src/adapters/kimi-review.ts

@@ -1,38 +1,16 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { assessVersion, COMPAT } from "./compat.ts";
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, 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";
+import type { ReviewerBackend, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
+import { assertCleanCwdAncestors, checkKimiReviewPolicy, kimiReviewFingerprint as hash, projectKimiReviewPolicyBinding, readKimiReviewFile as read } from "./kimi-review-policy.ts";
+import { startKimiReviewPolicyWatch, type KimiReviewPolicyFactory } from "./kimi-review-policy-worker.ts";
 
 const MANAGED = "managed:kimi-code";
 const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
-const hash = (text: string) => createHash("sha256").update(text).digest("hex");
-/** Native discovery can walk above cwd; check lexical aliases as well as the physical temporary root. */
-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);
@@ -108,9 +86,7 @@ export async function stopKimiReview(child: ChildProcess, locks: readonly string
   await stopOwnedProcess(child, { group: true });
 }
 
-export const kimiReviewerBackend: ReviewerBackend = {
-  id: "kimi", taskMcp: true, nativePolicy: true,
-  async prepare(context) {
+export async function prepareKimiReviewer(context: ReviewerPrepareContext, policyFactory: KimiReviewPolicyFactory = startKimiReviewPolicyWatch): Promise<ReviewerLaunch | { unavailable: string }> {
     let own: string | undefined;
     try {
       if (context.signal.aborted) throw new Error("cancelled");
@@ -138,19 +114,40 @@ export const kimiReviewerBackend: ReviewerBackend = {
       const verdict = assessVersion("kimi-review", COMPAT["kimi-review"].parse(await version(command, cwd, env, context.signal)));
       if (!verdict.ok) throw new Error(verdict.reason);
       const fingerprints = [configFile, mcpFile, agentFile].map(file => hash(read(file, 2_097_152)));
-      let cleaned = false;
-      const cleanup = () => { if (cleaned) return; rmSync(root, { recursive: true, force: true }); cleaned = true; };
+      const binding = projectKimiReviewPolicyBinding({
+        lexicalCwd: join(lexicalRoot, "workspace"), physicalCwd: cwd,
+        sourcePath, source, sourceConfig, sourceConfigHash: hash(original), executable,
+        executableStat: { dev: executableStat.dev, ino: executableStat.ino, size: executableStat.size, mtimeMs: executableStat.mtimeMs, ctimeMs: executableStat.ctimeMs },
+        privateFiles: [configFile, mcpFile, agentFile].map((path, index) => ({ path, hash: fingerprints[index]! })),
+        tool, authTargets: sources,
+      });
+      let policyProbe: ReturnType<KimiReviewPolicyFactory> | undefined;
+      let cleaned = false, cleaning: Promise<void> | undefined;
+      const remove = () => { if (cleaned) return; rmSync(root, { recursive: true, force: true }); cleaned = true; };
+      const cleanup = () => {
+        if (cleaned) return;
+        if (!policyProbe) { remove(); return; }
+        return cleaning ??= policyProbe.stop().then(remove).catch(error => { cleaning = undefined; throw error; });
+      };
       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; }
+        current: () => !cleaned && !context.signal.aborted && checkKimiReviewPolicy(binding),
+        startPolicyWatch: () => {
+          if (cleaned || context.signal.aborted) throw new Error("review policy is no longer current; retry the review");
+          if (!policyProbe) {
+            const probe = policyFactory(projectKimiReviewPolicyBinding(binding));
+            policyProbe = {
+              failure: probe.failure,
+              async check() {
+                if (cleaned || context.signal.aborted) return false;
+                const current = await probe.check();
+                return !cleaned && !context.signal.aborted && current;
+              },
+              stop: () => probe.stop(),
+            };
+          }
+          return policyProbe;
         },
         isolation: { backend: "kimi", version: verdict.version, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
           enforcement: "native-policy", freshSession: true, hubToolsOnly: true,
@@ -160,5 +157,8 @@ export const kimiReviewerBackend: ReviewerBackend = {
       if (own) rmSync(own, { recursive: true, force: true });
       return { unavailable: `Kimi reviewer unavailable: ${(error as Error).message}` };
     }
-  },
+}
+
+export const kimiReviewerBackend: ReviewerBackend = {
+  id: "kimi", taskMcp: true, nativePolicy: true, prepare: context => prepareKimiReviewer(context),
 };

package/src/adapters/kimi-tui-facts.ts

@@ -0,0 +1,153 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { homedir } from "node:os";
+import { realPath } from "../hub/project.ts";
+import type { NativeFactsInput, NativeFactsPort, NativeFactsTranscript } from "./registry-types.ts";
+
+const EVENTS = ["TurnStarted", "Stop", "StopFailure", "Interrupt", "SessionEnd", "TaskStarted", "Notification"] as const;
+const SESSION = /^session_[A-Za-z0-9_-]{1,120}$/;
+const AGENT = /^[A-Za-z0-9._-]{1,64}$/;
+const TASK = /^[A-Za-z0-9._:-]{1,128}$/;
+const INDEX_CAP = 16 * 1024 * 1024;
+const WIRE_CAP = 8 * 1024 * 1024;
+const TASK_CAP = 64 * 1024;
+const MAX_AGENTS = 256;
+const MAX_TASKS = 256;
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const integer = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) >= 0;
+const inside = (root: string, path: string) => { const rel = relative(root, path); return rel !== "" && rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel); };
+
+export function decodeKimiTuiHook(event: string, value: unknown): NativeFactsInput | undefined {
+  if (!(EVENTS as readonly string[]).includes(event) || !record(value) || value.hook_event_name !== event || value.client_type !== "kimi_code_cli"
+    || typeof value.session_id !== "string" || !SESSION.test(value.session_id) || typeof value.cwd !== "string" || !isAbsolute(value.cwd) || value.cwd.length > 4096) return;
+  if ((event === "TurnStarted" || event === "Interrupt") && !integer(value.turn_id)) return;
+  if (event === "TaskStarted" && (typeof value.task_id !== "string" || !TASK.test(value.task_id))) return;
+  const home = process.env.KIMI_CODE_HOME ?? join(process.env.HOME ?? homedir(), ".kimi-code");
+  const transcriptPath = value.agentHubTranscriptPath ?? join(home, "session_index.jsonl");
+  if (typeof transcriptPath !== "string" || !isAbsolute(transcriptPath) || transcriptPath.length > 4096) return;
+  const phase = ({ TurnStarted: "start", Stop: "stop", StopFailure: "stop", Interrupt: "stop", SessionEnd: "session", TaskStarted: "pre", Notification: "post" } as const)[event as typeof EVENTS[number]];
+  return { event: event as NativeFactsInput["event"], phase, sessionId: value.session_id, transcriptPath, workspacePaths: [value.cwd], tool: "", input: {} };
+}
+
+export function encodeKimiTuiHook(): undefined { return undefined; }
+
+function readBytes(path: string, cap: number, tail = false): Buffer {
+  const link = lstatSync(path);
+  if (!link.isFile() || link.isSymbolicLink() || link.nlink !== 1) throw new Error("not a regular file");
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || (!tail && stat.size > cap)) throw new Error("invalid file");
+    const length = Math.min(stat.size, cap), start = tail ? stat.size - length : 0;
+    const bytes = Buffer.alloc(length);
+    let offset = 0;
+    while (offset < length) {
+      const count = readSync(fd, bytes, offset, length - offset, start + offset);
+      if (count <= 0) throw new Error("short read");
+      offset += count;
+    }
+    return bytes;
+  } finally { closeSync(fd); }
+}
+
+function sessionDirectory(index: string, session: string): string {
+  const home = dirname(index), sessions = realPath(join(home, "sessions"));
+  let listed: string | undefined;
+  for (const line of readBytes(index, INDEX_CAP).toString("utf8").split("\n")) {
+    if (!line.includes(session)) continue;
+    let row: unknown;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (record(row) && row.sessionId === session && typeof row.sessionDir === "string") {
+      if (listed) throw new Error("duplicate session");
+      listed = row.sessionDir;
+    }
+  }
+  if (!listed) throw new Error("session not indexed");
+  const directory = realPath(listed);
+  if (!inside(sessions, directory)) throw new Error("session outside home");
+  return directory;
+}
+
+function taskInventory(agents: string): number {
+  let active = 0;
+  const names = readdirSync(agents, { withFileTypes: true });
+  if (names.length > MAX_AGENTS) throw new Error("too many agents");
+  for (const entry of names) {
+    if (!AGENT.test(entry.name)) continue;
+    if (!entry.isDirectory()) continue;
+    const tasks = join(agents, entry.name, "tasks");
+    const dir = lstatSync(tasks, { throwIfNoEntry: false });
+    if (!dir) continue;
+    if (!dir.isDirectory() || dir.isSymbolicLink()) throw new Error("invalid task directory");
+    const files = readdirSync(tasks).filter(name => name.endsWith(".json")).sort();
+    if (files.length > MAX_TASKS) throw new Error("too many tasks");
+    for (const name of files) {
+      if (!TASK.test(name.slice(0, -5))) throw new Error("invalid task name");
+      const row: unknown = JSON.parse(readBytes(join(tasks, name), TASK_CAP).toString("utf8"));
+      if (!record(row) || row.taskId !== name.slice(0, -5) || typeof row.status !== "string") throw new Error("invalid task");
+      if (row.status === "running" && row.endedAt === null) { active++; continue; }
+      const terminal = ["completed", "failed", "cancelled"].includes(row.status) && integer(row.endedAt);
+      if (!terminal) throw new Error("unknown task state");
+    }
+  }
+  return active;
+}
+
+interface Prompt { turn: number; id: string; origin: string }
+interface End { turn: number; reason: "completed" | "failed" | "cancelled" }
+const empty = (): NativeFactsTranscript => ({ factIds: [] });
+
+export function readKimiTuiTranscript(session: string, index: string): NativeFactsTranscript {
+  if (!SESSION.test(session) || basename(index) !== "session_index.jsonl" || !isAbsolute(index)) return empty();
+  try {
+    const directory = sessionDirectory(index, session);
+    const wire = join(directory, "agents", "main", "wire.jsonl");
+    if (!inside(directory, realPath(wire))) return empty();
+    const bytes = readBytes(wire, WIRE_CAP, true);
+    if (bytes.length === 0 || bytes[bytes.length - 1] !== 10) return empty();
+    const lines = bytes.toString("utf8").split("\n");
+    if (bytes.length === WIRE_CAP && !lines[0]?.startsWith('{"type":"metadata"')) lines.shift();
+    const prompts = new Map<number, Prompt>();
+    const ends = new Map<number, End>();
+    const promptEnds = new Map<string, "completed" | "failed" | "cancelled">();
+    const promptEndTurnIds = new Map<number, string>();
+    let started: Prompt | undefined;
+    for (const line of lines) {
+      if (!line || !/"(?:turn\.prompt|turn\.ended|prompt\.completed|prompt\.aborted)"/.test(line)) continue;
+      let row: unknown;
+      try { row = JSON.parse(line); } catch { return empty(); }
+      if (!record(row)) return empty();
+      if (row.type === "turn.prompt" && integer(row.turnId) && record(row.origin) && typeof row.origin.kind === "string") {
+        const turn = row.turnId, id = typeof row.promptId === "string" ? row.promptId : typeof row.origin.notificationId === "string" ? row.origin.notificationId : `turn-${turn}`;
+        const prompt = { turn, id, origin: row.origin.kind };
+        prompts.set(turn, prompt); started = prompt;
+      } else if (row.type === "turn.ended" && integer(row.turnId) && ["completed", "failed", "cancelled"].includes(String(row.reason))) {
+        const turn = row.turnId;
+        ends.set(turn, { turn, reason: row.reason as End["reason"] });
+      } else if (row.type === "prompt.completed" && typeof row.promptId === "string" && ["completed", "failed"].includes(String(row.reason))) {
+        promptEnds.set(row.promptId, row.reason as "completed" | "failed");
+        if (integer(row.turnId)) promptEndTurnIds.set(row.turnId, row.promptId);
+      } else if (row.type === "prompt.aborted" && typeof row.promptId === "string") {
+        promptEnds.set(row.promptId, "cancelled");
+        if (integer(row.turnId)) promptEndTurnIds.set(row.turnId, row.promptId);
+      } else if (row.type === "turn.prompt" || row.type === "turn.ended") return empty();
+    }
+    let completion: NativeFactsTranscript["completion"];
+    for (const [turn, end] of ends) {
+      const prompt = prompts.get(turn), promptReason = prompt ? promptEnds.get(prompt.id) : undefined, turnPromptId = promptEndTurnIds.get(turn);
+      if (!prompt || promptReason !== undefined && promptReason !== end.reason || turnPromptId !== undefined && turnPromptId !== prompt.id) continue;
+      completion = { id: createHash("sha256").update(`${session}:${turn}:${prompt.id}:${end.reason}`).digest("hex"), index: turn, reason: end.reason };
+    }
+    let background: number | undefined;
+    try { background = taskInventory(join(directory, "agents")); } catch { /* an unknown inventory holds settlement, not the final turn evidence */ }
+    return {
+      factIds: [],
+      ...(completion ? { completion } : {}),
+      ...(started ? { started: { id: createHash("sha256").update(`${session}:${started.turn}:${started.id}`).digest("hex"), index: started.turn, origin: started.origin } } : {}),
+      ...(background === undefined ? {} : { background }),
+    };
+  } catch { return empty(); }
+}
+
+export const KIMI_TUI_FACTS_HOOK: NativeFactsPort = { decode: decodeKimiTuiHook, encode: encodeKimiTuiHook, read: readKimiTuiTranscript };