@staix/agent-hub 0.12.37 → 0.12.39

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
@@ -6,19 +7,22 @@ import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "kimi";
   const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, connect, fail, takeFlags } = ctx;
-  const { launcherPreview, startModeOf, buildKimiTuiLaunch, configureKimiMcp, nativeLaunchEnv, childEnv } = ctx.helpers;
+  const { launcherPreview, readControl, startModeOf, buildKimiTuiLaunch, configureKimiMcp, nativeLaunchEnv, childEnv } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("kimi", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
   const { one, rest } = takeFlags(args, ["--mode", "--model"], []);
-  const mode = one["--mode"] ?? (ctx.instance ? "headless" : startModeOf(projectConfig().peers, "kimi")), model = one["--model"];
+  const acceptedMode = readControl(stateDir)?.startModes?.[peer];
+  const mode = one["--mode"] ?? (ctx.instance ? "headless" : acceptedMode ?? startModeOf(projectConfig().peers, "kimi")), model = one["--model"];
   if (ctx.instance && mode !== "headless") fail("extra Kimi instances require headless mode");
   if (rest.length || !["tui", "headless"].includes(mode)) fail("usage: ahub kimi [--mode tui|headless] [--model <alias>]");
   if (mode === "tui" && one["--mode"] === undefined && !(process.stdin.isTTY && process.stdout.isTTY)) {
     if (model) fail("Kimi's TUI needs a terminal for these options; run in a terminal or add --mode headless");
     const hub = await connect();
     try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const reply = await hub.request({ t: "peer_start", peer }, 35_000);
       if (!reply.ok) fail(reply.error);
       return console.log(reply.already ? "kimi is already attached" : `kimi: opened a terminal running ${reply.command}; it attaches pull-only when its TUI is ready`);
@@ -27,15 +31,17 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const hub = await connect();
   try {
     if (mode === "tui") {
-      const launch = buildKimiTuiLaunch(projectConfig().kimi_cmd, model);
       const snapshot = (await hub.request({ t: "status" })).status;
       const rostered = rosterInStatus(snapshot, peer);
       if (rostered === undefined) fail("cannot read kimi's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
       if (!rostered) fail("kimi is off roster; add it with ahub roster add kimi");
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const owner = snapshot?.peers?.[peer];
       if (owner && !["offline"].includes(owner.state) && !owner.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
       const admission = await hub.request({ t: "start", peer, args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       if (!admission.ok) fail(admission.error);
+      const runningCommand = admission.retainedLaunchConfig?.kimi_cmd;
+      const launch = buildKimiTuiLaunch(Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string") ? runningCommand : projectConfig().kimi_cmd, model);
       let result: ReturnType<typeof spawnSync>;
       try {
         // 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.
@@ -48,7 +54,9 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
       process.exit(result.status ?? 1);
     }
-    const owner = (await hub.request({ t: "status" })).status?.peers?.[peer];
+    const snapshot = (await hub.request({ t: "status" })).status;
+    const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
+    const owner = snapshot?.peers?.[peer];
     if (owner?.pullOnly && owner.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
     if (!ctx.instance) configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "headless");
     const res = await hub.request({ t: "start", peer, args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
@@ -8,6 +9,8 @@ export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (args.includes("--route") && args.includes("--model")) fail("use --route or --model, not both");
   if (args.some((a, i) => i % 2 === 0 && !["--route", "--model"].includes(a))) fail("usage: ahub local [--route <id> | --model <id>]");
   const hub = await connect();
+  const snapshot = (await hub.request({ t: "status" })).status;
+  const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
   const res = await hub.request({ t: "start", peer, args: { route: opt("--route"), model: opt("--model") }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { parsePiFlags } from "./native-cli-pi.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
@@ -12,8 +13,9 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
   const flags = parsePiFlags(args, fail);
+  const acceptedMode = ctx.helpers.readControl(stateDir)?.startModes?.[peer];
   // #269: with no flag, Pi's start mode decides, and that is its TUI unless a person set headless.
-  const options = { ...flags, mode: flags.mode ?? (ctx.instance ? "headless" : startModeOf(projectConfig().peers, "pi")) };
+  const options = { ...flags, mode: flags.mode ?? (ctx.instance ? "headless" : acceptedMode ?? startModeOf(projectConfig().peers, "pi")) };
   if (ctx.instance && options.mode !== "headless") fail("extra Pi instances require headless mode");
   if (flags.mode === undefined && options.mode === "tui" && !(process.stdin.isTTY && process.stdout.isTTY)) {
     // The default asked for the TUI and there is no terminal here (the console's command line, a script): the hub
@@ -22,6 +24,8 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     if (Object.keys(flags).length) fail("Pi's TUI needs a terminal, and these options are not passed to one the hub opens: run this in a terminal, or add --mode headless");
     const hub = await connect();
     try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const reply = await hub.request({ t: "peer_start", peer }, 35_000);
       if (reply.ok !== true) {
         const error = String(reply.error ?? "pi start refused");
@@ -36,6 +40,8 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const before = readControl(stateDir);
   if (recovering && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
   const hub = await connect();
+  const snapshot = (await hub.request({ t: "status" })).status;
+  const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
   const res = await hub.request({ t: "start", peer, args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
@@ -14,6 +15,8 @@ export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (rest.length || (one["--mode"] !== undefined && !(adapter.start.forms as readonly string[]).includes(one["--mode"]))) fail("Qwen TUI is not offered before verification; usage: ahub qwen [--mode headless] [--model <alias>] [--session-id <id>]");
   const hub = await connect();
   try {
+    const snapshot = (await hub.request({ t: "status" })).status;
+    const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
     const reply = await hub.request({ t: "start", peer, args: { mode: "headless", ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
     if (!reply.ok) fail(reply.error);
     console.log(reply.already ? `${peer} is already attached` : `${peer} attached (headless); use ahub say @${peer} and the console for approvals`);

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

@@ -7,6 +7,7 @@ export interface NativeCliEntryContext {
   instance?: string; executionCwd?: string;
   /** #223: the selected instance is started by the hub (a headless reviewer), never as a terminal launch. */
   hubStarted?: true;
+  person?: boolean;
   args: string[]; cwd: string; stateDir: string; cliDir: string; unattendedEnv: boolean; definition: AdapterDefinition;
   projectConfig(): HubConfig;
   connect(): Promise<ControlClient>;

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

@@ -1,3 +1,4 @@
+import { runAgyEntry } from "../agy/entry.ts";
 import type { BuiltinCliEntry } from "./native-cli-entry-types.ts";
 import { runClaudeEntry } from "./native-cli-entry-claude.ts";
 import { runCodexEntry } from "./native-cli-entry-codex.ts";
@@ -9,6 +10,7 @@ import { runLocalEntry } from "./native-cli-entry-local.ts";
 
 // Fixed trusted builtins only. No project configuration, caller payload or external module can register an entry.
 export const builtinCliEntries: readonly BuiltinCliEntry[] = Object.freeze([
+  { command: "agy", lifecycleAdmission: true, execute: runAgyEntry },
   { command: "claude", lifecycleAdmission: true, execute: runClaudeEntry },
   { command: "codex", lifecycleAdmission: true, execute: runCodexEntry },
   { command: "jcode", lifecycleAdmission: true, execute: runJcodeEntry },

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

@@ -14,6 +14,7 @@ export interface NativePreviewHelpers {
   childEnv: typeof import("../../hub/child-process.ts").childEnv;
   startModeOf: typeof import("../../hub/start-mode.ts").startModeOf;
   kimiMcpPlan: typeof import("../../cli/kimi-mcp.ts").kimiMcpPlan;
+  jcodeTuiCommand: typeof import("../jcode.ts").jcodeTuiCommand;
   jcodeCommand: typeof import("../jcode.ts").jcodeCommand;
   qwenSessionId: typeof import("../../hub/crash.ts").qwenSessionId;
   relayModelIds: typeof import("../../models/relay.ts").relayModelIds;

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

@@ -1,20 +1,20 @@
 import type { Launch } from "../../cli/launch.ts";
-import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext, type NativePreview } from "./native-cli-preview-common.ts";
 
-export function previewJcode(ctx: NativePreviewContext) {
+export function previewJcode(ctx: NativePreviewContext): NativePreview {
   const { args, config } = ctx;
-  const { jcodeCommand, qwenSessionId } = ctx.helpers;
+  const { jcodeCommand, jcodeTuiCommand, qwenSessionId, startModeOf } = ctx.helpers;
   const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
   let envNames = state.envNames;
   let launch: Launch;
-  const mode = value("--mode") ?? "headless", model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
-  if (mode !== "headless") throw new Error("Jcode TUI driving is unverified");
+  const mode = value("--mode") ?? startModeOf(config.peers, "jcode"), model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
+  if (mode !== "headless" && mode !== "tui") throw new Error("invalid Jcode start mode");
   for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--provider-profile", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Jcode option");
   if (session !== undefined && !qwenSessionId(session)) throw new Error("invalid Jcode session identity");
-  const cmd = jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
+  const cmd = mode === "tui" ? jcodeTuiCommand(nativeCommand(config.jcode_cmd, ["jcode"]), UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined) : jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
   launch = { cmd: cmd[0]!, args: cmd.slice(1) };
   unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
   unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });
 
-  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+  return { ...finishPreview(ctx, launch, envNames, unresolved), mode };
 }

package/src/adapters/definitions/native-cli-retained.ts

@@ -0,0 +1,15 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+
+/** Explain a retained launch setting using only metadata from the selected adapter definition. */
+export function retainedLaunchWarning(status: unknown, peer: string, definition: AdapterDefinition): string | undefined {
+  const keys = definition.cli.launchConfigKeys;
+  const retained = (status as { retainedConfig?: unknown } | undefined)?.retainedConfig;
+  if (!keys?.length || !Array.isArray(retained)) return;
+  const pending = retained.flatMap(row => {
+    if (!row || typeof row !== "object") return [];
+    const key = (row as { key?: unknown }).key;
+    return typeof key === "string" && keys.some(candidate => key === candidate || key.startsWith(`${candidate}.`)) ? [key] : [];
+  });
+  const unique = [...new Set(pending)];
+  return unique.length ? `ahub: config retained: ${unique.join(", ")}; starting ${peer} with the running value; run ahub settings reload to apply the file's value` : undefined;
+}

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

@@ -12,7 +12,7 @@ export const codexRetainedTerminalNotice = (_instance: string, _form: StartForm
 export const codexRosterReturnNotice = (resumeCommand: string): string =>
   `Codex 0.146.0 needs a manual return: resume the previous native session with ${resumeCommand}.`;
 export const jcodeStartPreflight = (request: StartRequest): string | undefined =>
-  request.form !== undefined && request.form !== "headless" ? "Jcode native TUI driving is unverified; use headless" : undefined;
+  request.form !== undefined && request.form !== "headless" && request.form !== "tui" ? "invalid Jcode start mode" : undefined;
 export const claudeObservedVersion = (context: VersionContext): string | undefined => context.observedVersion;
 export const codexObservedVersion = (context: VersionContext): string | undefined =>
   (context.peer as { version?: string } | undefined)?.version ?? context.observedVersion;

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

@@ -1,6 +1,7 @@
 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";
 
@@ -24,9 +25,9 @@ function reviewerVariant(kind: string, displayName: string, reviewer: NonNullabl
 }
 const codexVariant = reviewerVariant("codex", "Codex reviewer", { backend: codexReviewerBackend, defaultPool: true, declaration: "explicit" }, CODEX_DISPLAY);
 export const CODEX_REVIEWER_VARIANT: AdapterDefinition = { ...codexVariant, start: { ...codexVariant.start, create: createCodexReviewer } };
-export const KIMI_REVIEWER_VARIANT = reviewerVariant("kimi", "Kimi reviewer", { defaultPool: false, declaration: "explicit", unavailable: "Kimi reviewer unavailable: runtime and isolation verification deferred to #533" }, KIMI_DISPLAY);
+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_DEFINITION: AdapterDefinition = {
-  ...reviewerVariant("agy", "agy reviewer", { defaultPool: false, declaration: "automatic", unavailable: "agy reviewer unavailable: native adapter and isolation verification deferred to #533" }, { palette: { fg: "#6558a6", bg: "#f1effa" } }),
+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

@@ -1,5 +1,5 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
-import { existsSync, lstatSync, mkdtempSync, rmSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import type { Readable } from "node:stream";
@@ -17,6 +17,45 @@ 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"])];
 }
+export interface JcodeTuiBinding { launchId: string; sessionId: string }
+export type JcodeTuiState = { state: "waiting"; binding: JcodeTuiBinding } |
+  { state: "ready"; binding: JcodeTuiBinding; launch: { cmd: string; args: string[]; env: NodeJS.ProcessEnv } };
+
+export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string): string[] {
+  if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
+  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev",
+    ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : [])];
+}
+
+/** Read native persistence only. Never synthesize a native session or send a save-inducing prompt. */
+function savedSession(home: string, id: string): boolean {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(id)) throw new Error("invalid native session identity");
+  const directory = join(home, "sessions"), info = lstatSync(directory, { throwIfNoEntry: false });
+  if (!info) return false;
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("unsafe native session directory");
+  const file = join(directory, `${id}.json`), entry = lstatSync(file, { throwIfNoEntry: false });
+  if (!entry) return false;
+  if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("unsafe native session proof");
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+  try {
+    const before = fstatSync(fd);
+    // ponytail: bound native persistence proof to 32 MiB; larger conversations need a native saved-session API.
+    if (!before.isFile() || before.nlink !== 1 || before.size > 32 * 1024 * 1024) throw new Error("unsafe native session proof");
+    if (!before.size) return false;
+    const bytes = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < bytes.length) { const n = readSync(fd, bytes, offset, bytes.length - offset, offset); if (!n) return false; offset += n; }
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) return false;
+    let data: unknown;
+    try { data = JSON.parse(bytes.toString("utf8")); } catch { return false; }
+    if (!data || typeof data !== "object" || (data as { id?: unknown }).id !== id || !Array.isArray((data as { messages?: unknown }).messages)) throw new Error("native saved session identity is unproven");
+    return true;
+  } finally { closeSync(fd); }
+}
+
 /** 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). */
@@ -45,6 +84,8 @@ export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
 
 /** Both processes are ours. The user's global daemon and its sockets are never stopped. */
 export class JcodePeer extends AcpPeer {
+  private readonly launchId = crypto.randomUUID();
+  private socketIdentity: { dev: number; ino: number } | undefined;
   private readonly root: string;
   private readonly socket: string;
   private server: ChildProcess | undefined;
@@ -79,6 +120,8 @@ export class JcodePeer extends AcpPeer {
         ready.once("data", () => { clearTimeout(timer); server.off("exit", fail); if (lstatSync(this.socket, { throwIfNoEntry: false })?.isSocket()) resolve(); else reject(new Error("Jcode readiness has no private socket")); });
       });
       server.once("exit", () => { if (!this.ending && this.server === server) void this.stop("Jcode owned daemon disconnected").catch(() => {}); });
+      const identity = lstatSync(this.socket);
+      this.socketIdentity = { dev: identity.dev, ino: identity.ino };
       await super.start();
     } catch (error) { await this.stop().catch(() => {}); throw error; }
   }
@@ -119,6 +162,20 @@ export class JcodePeer extends AcpPeer {
     }
     if (failure) throw failure;
   }
+  tuiLaunch(expected?: JcodeTuiBinding, options: { model?: string; providerProfile?: string; sessionId?: string } = {}): JcodeTuiState {
+    const sessionId = super.recoveryMetadata().sessionId;
+    const socket = lstatSync(this.socket, { throwIfNoEntry: false });
+    if (this.ending || !this.server || this.server.exitCode !== null || this.server.signalCode !== null || this.state === "offline" ||
+      !socket?.isSocket() || socket.dev !== this.socketIdentity?.dev || socket.ino !== this.socketIdentity.ino || typeof sessionId !== "string") throw new Error("owned Jcode launch is unavailable");
+    const binding = { launchId: this.launchId, sessionId };
+    if (expected && (expected.launchId !== binding.launchId || expected.sessionId !== binding.sessionId)) throw new Error("Jcode launch changed");
+    if ((options.sessionId !== undefined && options.sessionId !== sessionId) ||
+      (options.model !== undefined && options.model !== this.jcode.launchModel) ||
+      (options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile)) throw new Error("Jcode launch options differ from its running session");
+    if (!savedSession(this.jcode.home, sessionId)) return { state: "waiting", binding };
+    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile);
+    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, ...JCODE_OWNED_ENV } } };
+  }
   override recoveryMetadata(): Record<string, unknown> {
     return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
   }

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[];