@staix/agent-hub 0.12.43 → 0.12.45

package/src/adapters/conformance/fakes/model-server.ts

@@ -0,0 +1,39 @@
+// Fake OpenAI-compatible gateway (OmniRoute-like): /health, bearer check, x-omniroute-provider, scripted replies.
+import type { ChatMessage } from "../../../omniroute/client.ts";
+
+export type Script = (body: { model: string; messages: ChatMessage[]; tools?: unknown[]; max_tokens?: number }, call: number) => Partial<ChatMessage> | Promise<Partial<ChatMessage>>;
+
+export const toolCall = (name: string, args: unknown, id = `call_${name}_${Math.random().toString(36).slice(2, 8)}`) => ({
+  id,
+  type: "function" as const,
+  function: { name, arguments: typeof args === "string" ? args : JSON.stringify(args) },
+});
+
+export function startFakeModelServer(opts: { key?: string; script?: Script; healthy?: boolean; models?: string[] } = {}) {
+  const requests: { headers: Record<string, string>; body: any }[] = [];
+  const state = { healthy: opts.healthy ?? true, script: opts.script ?? ((b) => ({ content: `echo: ${b.messages.at(-1)?.content}` })) };
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/v1/models") return state.healthy ? Response.json({ data: (opts.models ?? ["m", "vllm/pinned", "vllm/x", "vllm/test", "vllm/next"]).map((id) => ({ id })) }) : new Response("down", { status: 503 });
+      if (url.pathname !== "/v1/chat/completions") return new Response("not found", { status: 404 });
+      const body = (await req.json()) as any;
+      if (opts.key && req.headers.get("authorization") !== `Bearer ${opts.key}`) return new Response("invalid api key", { status: 401 });
+      if (body.messages?.[0]?.content === "agent-hub model availability check: reply OK") {
+        return Response.json({ choices: [{ message: { role: "assistant", content: "OK" } }] });
+      }
+      requests.push({ headers: Object.fromEntries(req.headers), body });
+      let scripted: Partial<ChatMessage>;
+      try {
+        scripted = await state.script(body, requests.length);
+      } catch (e) {
+        return new Response(`upstream error: ${(e as Error).message}`, { status: 500 });
+      }
+      const message = { role: "assistant", content: null, reasoning_content: "private chain of thought", ...scripted };
+      return Response.json({ choices: [{ message }] }, { headers: { "x-omniroute-provider": "vllm" } });
+    },
+  });
+  return { url: `http://127.0.0.1:${server.port}/v1`, requests, state, stop: () => server.stop(true) };
+}

package/src/adapters/conformance/fakes/pi-rpc.ts

@@ -0,0 +1,32 @@
+import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+const option = (flag: string) => process.argv.includes(flag) ? process.argv[process.argv.indexOf(flag) + 1] : undefined;
+const empty = process.argv.includes("--empty-session");
+const dir = option("--session-dir")!;
+mkdirSync(dir, { recursive: true });
+const existing = option("--session");
+const sessionId = option("--session-id") ?? (existing ? JSON.parse(readFileSync(existing, "utf8").split("\n")[0]!).id : "fake-session");
+const sessionFile = existing ?? join(dir, `${sessionId}.jsonl`);
+if (!empty && !existsSync(sessionFile)) writeFileSync(sessionFile, JSON.stringify({ type: "session", id: sessionId, cwd: process.cwd() }) + "\n");
+let messageCount = 0;
+const send = (value: unknown) => process.stdout.write(`${JSON.stringify(value)}\n`);
+createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line) as { id?: string; type?: string };
+  if (request.type === "get_state") send({ type: "response", id: request.id, command: "get_state", success: true, data: { isStreaming: false, isCompacting: false, pendingMessageCount: 0, messageCount, sessionId, sessionFile } });
+  else if (request.type === "set_model") send({ type: "response", id: request.id, command: "set_model", success: true });
+  else if (request.type === "prompt" || request.type === "steer") { messageCount++; send({ type: "response", id: request.id, command: request.type, success: true }); }
+});
+
+const exitTrigger = option("--exit-trigger");
+if (exitTrigger) {
+  const timer = setInterval(() => {
+    if (!existsSync(exitTrigger)) return;
+    clearInterval(timer);
+    if (process.argv.includes("--exit-consume-trigger")) rmSync(exitTrigger);
+    const signal = option("--exit-signal");
+    if (signal) process.kill(process.pid, signal as NodeJS.Signals);
+    else process.exit(Number(option("--exit-code") ?? 0));
+  }, 10);
+  timer.unref();
+}

package/src/adapters/conformance/index.ts

@@ -0,0 +1,11 @@
+/** Bun test registration kit. Importing this entry registers no suite and starts no native transport. */
+export { registerConformance, registerExternalChannelConformance, until, type AdapterConformance, type ConformanceFixture } from "./kit.ts";
+export { registerAcpConformance, type AcpConformanceOptions } from "./acp.ts";
+export { registerCodexConformance } from "./codex.ts";
+export { registerOwnedAcpConformance } from "./owned-acp.ts";
+export { registerLocalConformance, registerPiConformance } from "./local-pi.ts";
+export { createFromDefinition, expire } from "./factories.ts";
+export { ACP_LEGS, assertAcpLegEnrollment, assertEnrollment, definitionIdentities, type AcpLeg } from "./enrollment.ts";
+export { fakePaths } from "./fake-paths.ts";
+export { startFakeAppServer } from "./fakes/app-server.ts";
+export { startFakeModelServer, toolCall, type Script } from "./fakes/model-server.ts";

package/src/adapters/conformance/kit.ts

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import type { Envelope } from "../../hub/envelope.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+
+export async function until(condition: () => boolean, label: string): Promise<void> {
+  const deadline = Date.now() + 5000;
+  while (!condition() && Date.now() < deadline) await Bun.sleep(10);
+  expect(condition(), label).toBe(true);
+}
+export interface ConformanceFixture {
+  peer: PeerAdapter;
+  messages: string[];
+  /** Claude's native hooks own busy; channel insertion itself has no native acceptance evidence. */
+  busyOnDeliver: boolean;
+  settle?(): Promise<void>;
+  verifyTransport(): void | Promise<void>;
+  close(): Promise<void>;
+}
+export interface AdapterConformance {
+  kind: string;
+  create(): Promise<ConformanceFixture>;
+}
+
+/** Shared observable contract; every invocation uses the real adapter and its fake native transport. */
+export function registerConformance(adapter: AdapterConformance): void {
+  test(`P4 ${adapter.kind}: transport delivery, synchronous occupancy and owned teardown`, async () => {
+    const f = await adapter.create();
+    try {
+      expect(f.peer.id).toBe(adapter.kind);
+      expect(f.peer.state).toBe("idle");
+      const envelope: Envelope = newEnvelope("user", "conformance ping", { to: [adapter.kind] });
+      const delivering = f.peer.deliver([envelope]);
+      // Attach the rejection observer before teardown, even if an assertion fails while delivery is pending.
+      const outcome = delivering.then(() => undefined, error => error as Error);
+      expect(f.peer.state).toBe(f.busyOnDeliver ? "busy" : "idle");
+      expect(await outcome).toBeUndefined();
+      await f.settle?.();
+      await until(() => f.messages.length === 1 && f.peer.state === "idle", `${adapter.kind} one settled reply`);
+      expect(f.messages[0]).not.toBeEmpty();
+      await f.verifyTransport();
+      const metadata = f.peer.recoveryMetadata?.();
+      expect(JSON.stringify(metadata ?? {})).not.toContain("conformance ping");
+    } finally { await f.close(); }
+    await until(() => f.peer.state === "offline", `${adapter.kind} stop observed offline`);
+  }, 20_000);
+}
+
+/** Host-owned authenticated channel fixtures share the observable delivery contract, not a driven native factory. */
+export function registerExternalChannelConformance(adapter: AdapterConformance): void { registerConformance(adapter); }

package/src/adapters/conformance/local-pi.ts

@@ -0,0 +1,100 @@
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { LocalPeer } from "../local-worker.ts";
+import type { PiPeer } from "../pi.ts";
+import { OmniRoute } from "../../omniroute/client.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import { startFakeModelServer, toolCall } from "./fakes/model-server.ts";
+import { until } from "./kit.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+
+
+export function registerLocalConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "local-worker") throw new Error(definition.kind + ": conformance requires local-worker transport factory");
+  test(`P4 ${label}: a consumed model result from an expired generation cannot publish into the next turn`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-local-late-"));
+    let release = () => {}, observed = false, parsed = () => {};
+    const parsedLate = new Promise<void>(resolve => { parsed = resolve; });
+    const server = startFakeModelServer({ key: "conformance-key", script: async body => {
+      const text = String(body.messages.at(-1)?.content);
+      if (text.includes("OLD_GENERATION")) await new Promise<void>(resolve => { release = resolve; observed = true; });
+      return { content: text.includes("OLD_GENERATION") ? "stale answer" : "current answer" };
+    } });
+    const oldUrl = process.env.AGENTHUB_OMNIROUTE_URL, oldKey = process.env.OMNIROUTE_API_KEY;
+    process.env.AGENTHUB_OMNIROUTE_URL = server.url; process.env.OMNIROUTE_API_KEY = "conformance-key";
+    const omni = new OmniRoute({ urls: [server.url], access_hosts: [] }), chat = omni.chat.bind(omni);
+    omni.chat = async (body, options = {}) => {
+      const old = String(body.messages.at(-1)?.content).includes("OLD_GENERATION");
+      const result = await chat(body, old ? { ...options, signal: undefined } : options);
+      if (old) parsed(); return result;
+    };
+    const messages: string[] = [];
+    const peer = createFromDefinition<LocalPeer>(definition, { local: { cwd: dir, omni, fixedModel: "vllm/fixed", tools: { deny: [], permit: async () => false } } });
+    peer.onMessage = text => { messages.push(text); };
+    let oldTurn: Promise<void> | undefined;
+    try {
+      await peer.start(); oldTurn = peer.deliver([newEnvelope("user", "OLD_GENERATION")]); oldTurn.catch(() => {});
+      await until(() => observed, "old gateway call held"); expire(peer);
+      expect(peer.state).toBe("idle");
+      await peer.deliver([newEnvelope("user", "CURRENT_GENERATION")]);
+      await until(() => messages.length === 1, "new generation publishes");
+      release(); await parsedLate; await oldTurn; await new Promise<void>(resolve => setImmediate(resolve));
+      expect(messages).toEqual(["current answer"]); expect(peer.state).toBe("idle");
+    } finally { release(); await peer.stop(); await oldTurn?.catch(() => {}); server.stop();
+      if (oldUrl === undefined) delete process.env.AGENTHUB_OMNIROUTE_URL; else process.env.AGENTHUB_OMNIROUTE_URL = oldUrl;
+      if (oldKey === undefined) delete process.env.OMNIROUTE_API_KEY; else process.env.OMNIROUTE_API_KEY = oldKey;
+      rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  test(`P4 ${label}: tool approval refusal prevents the write and hub tools use the host callback`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-local-approval-")), path = join(dir, "a.txt"); writeFileSync(path, "before");
+    const asked: string[] = [], called: string[] = [];
+    const server = startFakeModelServer({ key: "conformance-key", script: body => {
+      const tools = body.messages.filter(message => message.role === "tool").length;
+      return tools === 0 ? { tool_calls: [toolCall("write", { path: "a.txt", content: "after" })] }
+        : tools === 1 ? { tool_calls: [toolCall("hub_task_list", {})] } : { content: "done" };
+    } });
+    const oldUrl = process.env.AGENTHUB_OMNIROUTE_URL, oldKey = process.env.OMNIROUTE_API_KEY;
+    process.env.AGENTHUB_OMNIROUTE_URL = server.url; process.env.OMNIROUTE_API_KEY = "conformance-key";
+    const peer = createFromDefinition<LocalPeer>(definition, { local: { cwd: dir, omni: new OmniRoute({ urls: [server.url], access_hosts: [] }), fixedModel: "vllm/fixed",
+      tools: { deny: [], permit: async title => { asked.push(title); return false; } }, taskTool: async name => { called.push(name); return "[]"; } } });
+    try {
+      await peer.start(); await peer.deliver([newEnvelope("user", "edit and list tasks")]);
+      await until(() => peer.state === "idle", "local tools settled");
+      expect(readFileSync(path, "utf8")).toBe("before"); expect(asked).toHaveLength(1); expect(called).toEqual(["hub_task_list"]);
+    } finally { await peer.stop(); server.stop(); if (oldUrl === undefined) delete process.env.AGENTHUB_OMNIROUTE_URL; else process.env.AGENTHUB_OMNIROUTE_URL = oldUrl;
+      if (oldKey === undefined) delete process.env.OMNIROUTE_API_KEY; else process.env.OMNIROUTE_API_KEY = oldKey;
+      rmSync(dir, { recursive: true, force: true }); }
+  });
+
+}
+
+export function registerPiConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "pi-rpc") throw new Error(definition.kind + ": conformance requires pi-rpc transport factory");
+  test(`P4 ${label}: recovery resumes its exact persisted session and rejects a stale bridge generation`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-pi-resume-")), stateDir = join(dir, "state"), sessions = join(stateDir, "pi-sessions");
+    mkdirSync(sessions, { recursive: true });
+    const sessionFile = join(sessions, "saved-session.jsonl"); writeFileSync(sessionFile, JSON.stringify({ type: "session", id: "saved-session", cwd: dir }) + "\n");
+    const peer = createFromDefinition<PiPeer>(definition, { pi: { cwd: dir, stateDir, sessionFile, mode: "headless", backend: "dgx", cmd: [process.execPath, fakePaths.piRpc],
+      relay: { url: "http://127.0.0.1:9/v1", token: "fixture", models: [{ id: "dgx/coding" }] }, tools: [], executeTool: async () => "fixture" } });
+    const messages: string[] = []; peer.onMessage = text => { messages.push(text); };
+    try {
+      await peer.start(); expect(peer.recoveryMetadata()).toMatchObject({ sessionId: "saved-session", sessionFile });
+      const launch = peer.tuiLaunch!;
+      const event = async (body: unknown) => fetch(`${launch.env.AGENTHUB_PI_BRIDGE_URL}/event`, { method: "POST", headers: { authorization: `Bearer ${launch.env.AGENTHUB_PI_BRIDGE_TOKEN}`, "content-type": "application/json" }, body: JSON.stringify(body) });
+      await peer.deliver([newEnvelope("user", "resumed turn")]);
+      expect((await event({ type: "agent_start", generation: 3, sessionId: "saved-session" })).status).toBe(200);
+      await event({ type: "agent_end", generation: 2, text: "stale answer" });
+      await event({ type: "agent_settled", generation: 2 });
+      expect(peer.state).toBe("busy"); expect(messages).toEqual([]);
+      await event({ type: "agent_end", generation: 3, text: "current answer" });
+      await event({ type: "agent_settled", generation: 3 });
+      expect(peer.state).toBe("idle"); expect(messages).toEqual(["current answer"]);
+    } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+  });
+
+}

package/src/adapters/conformance/owned-acp.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { JcodePeer } from "../jcode.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+import { until } from "./kit.ts";
+
+
+/** The owned-ACP protocol flavor and its unmanaged mode ceiling are supplied explicitly. */
+export function registerOwnedAcpConformance(definition: AdapterDefinition, { label = definition.displayName, unmanagedReason }: { label?: string; unmanagedReason?: string } = {}): void {
+  if (definition.start.daemonPort !== "owned-acp") throw new Error(definition.kind + ": conformance requires owned-acp transport factory");
+  if (!unmanagedReason?.trim()) throw new Error(definition.kind + ": owned-ACP unmanaged mode reason must be explicit");
+  test(`P4 ${label}: watchdog waits for the consumed late native result without publishing it into a successor`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-jcode-watchdog-")), home = join(dir, "home"), release = join(dir, "release");
+    mkdirSync(home); writeFileSync(join(home, "mcp.json"), "{}");
+    const messages: string[] = [], failed: unknown[] = [];
+    const peer = createFromDefinition<JcodePeer>(definition, { jcode: { cwd: dir, home,
+      command: [process.execPath, fakePaths.jcodeAgent, "--steer-file", release],
+    } });
+    peer.onMessage = text => { messages.push(text); }; peer.onFailed = envelopes => { failed.push(envelopes); };
+    try {
+      await peer.start();
+      expect(unmanagedReason).toContain("no verified native permission-mode mapping");
+      expect(peer.permissionModeState).toBe("unmanaged");
+      await expect(peer.setPermissionMode("ask")).rejects.toThrow("no verified mode mapping");
+      await peer.deliver([newEnvelope("user", "old Jcode turn")]);
+      await until(() => existsSync(`${release}.busy`), "native Jcode consumed the held prompt");
+      expire(peer);
+      expect(peer.state).toBe("busy"); expect(messages).toEqual([]);
+      writeFileSync(release, "release");
+      // Returning idle proves the old prompt settled, not merely that a cancel notification was written.
+      await until(() => peer.state === "idle", "Jcode late prompt result consumed after watchdog cancellation");
+      expect(messages).toEqual([]); expect(failed).toEqual([]);
+      await peer.deliver([newEnvelope("user", "successor Jcode turn")]);
+      await until(() => messages.length === 1 && peer.state === "idle", "only the successor Jcode answer publishes");
+      expect(messages).toEqual(["JCODE_REPLY"]);
+    } finally { writeFileSync(release, "release"); await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+  }, 20_000);
+
+}

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

@@ -1,3 +1,15 @@
+import { runClaudeEntry } from "./native-cli-entry-claude.ts";
+import { runCodexEntry } from "./native-cli-entry-codex.ts";
+import { runKimiEntry } from "./native-cli-entry-kimi.ts";
+import { runPiEntry } from "./native-cli-entry-pi.ts";
+import { runLocalEntry } from "./native-cli-entry-local.ts";
+import { runJcodeEntry } from "./native-cli-entry-jcode.ts";
+import { previewClaude } from "./native-cli-preview-claude.ts";
+import { previewCodex } from "./native-cli-preview-codex.ts";
+import { previewKimi } from "./native-cli-preview-kimi.ts";
+import { previewPi } from "./native-cli-preview-pi.ts";
+import { previewJcode } from "./native-cli-preview-jcode.ts";
+import type { PermissionMode } from "../../hub/permission-mode.ts";
 import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
 import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
@@ -12,14 +24,14 @@ import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY,
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
 import { claudeContext, codexContext, acpContextValue } from "./native-context.ts";
-import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm } from "../registry-types.ts";
+import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm, NativeModeSpec } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
 import { shellQuote } from "../../cli/shell-quote.ts";
 
 type CompatibilityKind = "claude" | "codex" | "kimi" | "pi" | "local" | "jcode";
 
 /**
- * Preserve CLI-wrapper argv plans for definitions that still declare them and the frozen A1 compatibility export.
+ * Preserve CLI-wrapper argv plans only for the frozen A1 compatibility export.
  * Native startup and daemon factories are supplied separately by the runtime definitions.
  */
 function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext, explicitMode = false): LaunchPlan {
@@ -43,8 +55,6 @@ function sessionId(field: "sessionId" | "threadId"): (peer: PeerAdapter) => stri
     return typeof value === "string" && value ? value : undefined;
   };
 }
-const terminal = (form: StartForm) => form === "tui";
-const headless = () => false;
 const switches = Object.freeze(["--unattended", "--safe", "--new"]);
 const implementerRoles = Object.freeze(["implementer", "verifier"]);
 const dualForms = Object.freeze(["tui", "headless"] as const);
@@ -62,9 +72,9 @@ const hubGrants = {
 const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
   api: 1, kind: "claude", displayName: "Claude Code reviewer", family: "claude", transport: "hub-native",
   roles: Object.freeze(["reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-  start: { create: createClaudeReviewer, daemonPort: "claude-print", forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-  identity: { mcp: "env" },
-  permission: { modes: {}, unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
+  start: { create: createClaudeReviewer, daemonPort: "claude-print", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+  identity: { mcp: "env" }, instances: { mode: "headless" },
+  permission: { unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
   session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "claude-print", crashPlan: () => ({ resume: {}, how: "claude reviewer: starts again; every review runs in a new session" }) },
   turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true }, reviewer: { backend: claudeReviewerBackend, defaultPool: true, declaration: "automatic" },
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
@@ -74,87 +84,98 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
 // daemon.ts runtime mappings/stop policy, budget.ts exemptions, and ui/peer-palette.ts CSS foregrounds.
 export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
   {
+    projection: { roleRank: 0, helpRank: 0, plannerEligible: true },
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", ownsTerminal: terminal, launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
+    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
-    identity: { mcp: "channel-plugin" }, attach: { recoveryLaunch: claudeRecoveryLaunch },
-    // Existing daemon permission hooks enforce these grants; an empty native mode map is neither unmanaged nor a refusal.
-    permission: { modes: {}, grants: { ask: "Claude's own permission rules decide",
+    identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["reviewer", "planner"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
+    // Approval enforcement belongs to the verified native transport and host permission gate.
+    permission: { grants: { ask: "Claude's own permission rules decide",
       "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",
       "never-ask": "every tool runs without asking" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true, ...CLAUDE_RECOVERY_SESSION, crashPlan: claudeCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "native-hook", budget: { account: "claude", checkpoint: true, reader: { source: "claude status line", read: claudeWindows }, context: { source: "claude_statusline", read: claudeContext } },
-    cli: { command: "claude", retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
+    cli: { command: "claude", entry: { lifecycleAdmission: true, execute: runClaudeEntry }, preview: previewClaude, usage: [["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"]], retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
     reviewerVariant: CLAUDE_REVIEWER_VARIANT,
   },
   {
     reviewerVariant: CODEX_REVIEWER_VARIANT,
+    projection: { roleRank: 1, startRank: 1, helpRank: 1, plannerEligible: true },
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
+    start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
-    identity: { mcp: "env" },
-    permission: { trackUnattended: true, modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
-      "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },
-      grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    permission: { trackUnattended: true, grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
     session: { nativeRevert: true, idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true, ...CODEX_RECOVERY_SESSION, crashPlan: codexCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "adapter", budget: { account: "codex", checkpoint: true, reader: { source: "codex rateLimits", read: codexWindows }, context: { source: "codex_token_usage", read: codexContext } },
-    cli: { command: "codex", launchConfigKeys: ["codex_bin"], retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
+    cli: { command: "codex", entry: { lifecycleAdmission: true, execute: runCodexEntry }, preview: previewCodex, usage: [["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"]], launchConfigKeys: ["codex_bin"], retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
   },
   {
     reviewerVariant: KIMI_REVIEWER_VARIANT,
+    projection: { roleRank: 2, startRank: 2, helpRank: 2, plannerEligible: true },
     api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
     // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
-    identity: { mcp: "acp-session" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const), recoveryLaunch: kimiRecoveryLaunch,
+    identity: { mcp: "acp-session" }, instances: { mode: "headless" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const), recoveryLaunch: kimiRecoveryLaunch,
       pullOnlyNotice: "pull-only: messages wait for hub_inbox; no push, steer, watchdog or automatic quota handoff",
       admission: { reservedRefusal: "Kimi attaches pull-only in TUI mode; run ahub kimi", watchRefusal: "Kimi is in pull-only TUI mode; use its native terminal or start headless" } },
-    permission: { modes: { ask: { kind: "acp-mode", modeId: "default" }, "ask-when-needed": { kind: "acp-mode", modeId: "yolo" }, "never-ask": { kind: "acp-mode", modeId: "auto" } },
-      grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
+    permission: { grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
       unmanagedForms: Object.freeze(["tui"] as const), unmanagedStatusNote: "Kimi approves tools in its own TUI; no hub permission mode", unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp", ...KIMI_RECOVERY_SESSION, crashPlan: kimiCrashPlan },
-    turnEnd: "adapter", budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, init: { mcpFile: ".kimi-code/mcp.json" }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
-    cli: { command: "kimi", launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
+    turnEnd: "adapter", budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
+    cli: { command: "kimi", entry: { lifecycleAdmission: true, execute: runKimiEntry }, preview: previewKimi, usage: [["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"]], launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
   },
   {
+    projection: { roleRank: 4, startRank: 0, helpRank: 6, plannerEligible: false },
     api: 1, kind: "pi", enabledSwitchStartOnly: true, displayName: "Pi", family: "pi", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
-    start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("pi", ctx), conductorStartable: true, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    // Existing daemon permission hooks enforce these grants; an empty native mode map is neither unmanaged nor a refusal.
-    permission: { modes: {}, grants: { ...hubGrants } },
+    start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", conductorStartable: true, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    // Approval enforcement belongs to the verified native transport and host permission gate.
+    permission: { grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), restoreOnStart: true, launchKind: "pi", launchRecord: true, ...PI_RECOVERY_SESSION, crashPlan: piCrashPlan, unrecordedTerminal: "tui", continuityBookmark: piRecoveryContinuity, continuity: { key: "pi", parse: parsePiContinuity } },
     turnEnd: "adapter", budget: { account: "pi", instrumented: true }, reporting: { tokensNotReported: true }, configuration: { schema: piConfigSchema, routingSchema: piRoutingSchema, settings: PI_SETTINGS, restartReasons: PI_RESTART_REASONS, validateEffective: piEffectiveConfig },
     routing: { localAllowedRefusal: "local_allowed = false also excludes pi for this class", longContext: "backend-limit", preferredTier: true, handoffPriority: 0, trace: "backend", backendLabel: "pi" },
-    cli: { command: "pi", launchConfigKeys: ["pi.cmd", "pi.backend", "pi.dgx_coding", "pi.dgx_fast", "pi.max_steps", "routing.pi", "peers.pi.start_mode"], previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
+    cli: { command: "pi", entry: { lifecycleAdmission: false, execute: runPiEntry }, preview: previewPi, usage: [["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"]], launchConfigKeys: ["pi.cmd", "pi.backend", "pi.dgx_coding", "pi.dgx_fast", "pi.max_steps", "routing.pi", "peers.pi.start_mode"], previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
   },
   {
+    projection: { roleRank: 3, helpRank: 7, plannerEligible: false },
     api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
-    start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("local", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    // Existing daemon permission hooks enforce these grants; an empty native mode map is neither unmanaged nor a refusal.
-    permission: { modes: {}, grants: { ...hubGrants } },
+    start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    // Approval enforcement belongs to the verified native transport and host permission gate.
+    permission: { grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local", ...LOCAL_RECOVERY_SESSION, crashPlan: localCrashPlan },
     turnEnd: "adapter", budget: { account: "local", quotaExempt: true, instrumented: true }, configuration: { schema: localConfigSchema, routingSchema: localRoutingSchema, restartReasons: LOCAL_RESTART_REASONS },
     routing: { localAllowedRefusal: "local_allowed = false for this class", longContext: "skip-owner", preferredTier: true, handoffPriority: 1, trace: "route" },
-    cli: { command: "local", launchConfigKeys: ["local.deny", "local.bash_network", "local.network_allow", "local.max_steps", "local.read_allow", "routing.local"], startWords: () => ["local"] }, display: LOCAL_DISPLAY,
+    cli: { command: "local", entry: { lifecycleAdmission: false, execute: runLocalEntry }, usage: [["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"]], launchConfigKeys: ["local.deny", "local.bash_network", "local.network_allow", "local.max_steps", "local.read_allow", "routing.local"], startWords: () => ["local"] }, display: LOCAL_DISPLAY,
   },
   {
+    projection: { roleRank: 6, startRank: 3, helpRank: 3, plannerEligible: true },
     api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
     roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, explicitHeadlessMode: true, launch: ctx => compatibilityLaunch("jcode", ctx, true), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", explicitHeadlessMode: true, conductorStartable: true, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "project-file" },
-    permission: { modes: {}, unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
+    permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
-    cli: { command: "jcode", authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
+    cli: { command: "jcode", entry: { lifecycleAdmission: true, execute: runJcodeEntry }, preview: previewJcode, usage: [["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"]], authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
   },
 ] satisfies AdapterDefinition[]);
 
+// Frozen A1 metadata is a compatibility snapshot, not the runtime definition contract.
+export type LegacyAdapterDefinition = AdapterDefinition & {
+  init?: { templateFragment?: string; mcpFile?: string };
+  start: AdapterDefinition["start"] & { ownsTerminal(form: StartForm): boolean; launch(ctx: LaunchContext): LaunchPlan };
+  permission: AdapterDefinition["permission"] & { modes: Partial<Record<PermissionMode, NativeModeSpec>>; readOnly?: NativeModeSpec };
+};
+const terminal = (form: StartForm) => form === "tui";
+const headless = () => false;
 /**
  * ponytail: retain the released A1 metadata export for source/library compatibility until A4 retires it.
  * Core runtime consumers use NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN through the registry exclusively.
@@ -162,7 +183,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
  * resolves to the TUI (#464, #559). Callers of this export must pass `--mode headless` themselves.
  */
 const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
-export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
+export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly LegacyAdapterDefinition[] = Object.freeze([
   {
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
@@ -233,4 +254,4 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Ob
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
     cli: { command: "jcode", startWords: () => ["jcode"] }, display: palette("#8a8f99"),
   },
-] satisfies AdapterDefinition[]);
+] satisfies LegacyAdapterDefinition[]);

package/src/adapters/definitions/native-channel-state.ts

@@ -0,0 +1,41 @@
+// No imports: the statusline tee and the CLI load this without the daemon (#450 I3).
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** The peer a Claude process writes for: its AGENTHUB_PEER_ID when well formed, otherwise the builtin claude peer. */
+export function claudePeer(value: string | undefined): string {
+  return value !== undefined && PEER.test(value) ? value : "claude";
+}
+
+// Instance ids are always <kind>-<name>, so a Claude peer is the builtin id or a claude-<name> instance.
+const CLAUDE_PEER = /^claude(?:-[a-z0-9-]+)?$/;
+
+/** Per-peer Claude state file names. The builtin claude peer keeps its original names, so nothing migrates. */
+export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context", peer: string): string {
+  // #624: another kind (agy is a hyphen-free builtin too) must never resolve to Claude's own files.
+  if (!CLAUDE_PEER.test(peer) || !PEER.test(peer)) throw new Error(`${peer} is not a Claude peer; Claude state files belong to Claude peers only`);
+  return peer.includes("-") ? `${base}.${peer}.json` : `${base}.json`;
+}
+
+/** A Claude peer's own row in terminal-recovery.json for this daemon, never a sibling instance's (row order is arbitrary). */
+export function ownTerminalRow(records: unknown, peer: string, projectRoot: string, instanceId: string): { launchId?: unknown } | undefined {
+  if (!Array.isArray(records)) return undefined;
+  return records.find((row) => row?.peer === peer && row?.projectRoot === projectRoot && row?.instanceId === instanceId);
+}
+
+/**
+ * Whether a Claude session's transcript exists: the path the peer's own status line reported for that session, else
+ * the builtin's default location. An instance may run under its own CLAUDE_CONFIG_DIR, which the hub cannot see:
+ * without its reported path the answer is unknown, and unknown counts as persisted (it never waives session identity).
+ */
+export function transcriptPersisted(reported: { sessionId?: string; transcriptPath?: string }, sessionId: string, instance: boolean, fallbackPath: string, exists: (path: string) => boolean | "unknown"): boolean {
+  // Only a positive "missing" (ENOENT) is not persisted; an unreadable path is unknown and keeps the identity strict.
+  const found = (path: string) => exists(path) !== false;
+  if (reported.sessionId === sessionId && reported.transcriptPath) return found(reported.transcriptPath);
+  return instance || found(fallbackPath);
+}
+
+/** lstat evidence: true when present, false only on ENOENT/ENOTDIR, "unknown" for any other failure (EACCES included). */
+export function pathEvidence(path: string, lstat: (path: string) => unknown): boolean | "unknown" {
+  try { lstat(path); return true; }
+  catch (error) { const code = (error as { code?: string }).code; return code === "ENOENT" || code === "ENOTDIR" ? false : "unknown"; }
+}

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

@@ -41,9 +41,17 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       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 launch: ReturnType<typeof buildKimiTuiLaunch>;
       let result: ReturnType<typeof spawnSync>;
       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); }
+        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");
         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.");

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

@@ -1,21 +1,9 @@
-import { runAgyEntry } from "../agy/entry.ts";
+import type { AdapterDefinition } from "../registry-types.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";
-import { runJcodeEntry } from "./native-cli-entry-jcode.ts";
-import { runQwenEntry } from "./native-cli-entry-qwen.ts";
-import { runKimiEntry } from "./native-cli-entry-kimi.ts";
-import { runPiEntry } from "./native-cli-entry-pi.ts";
-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 },
-  { command: "qwen", lifecycleAdmission: true, execute: runQwenEntry },
-  { command: "kimi", lifecycleAdmission: true, execute: runKimiEntry },
-  { command: "pi", lifecycleAdmission: false, execute: runPiEntry },
-  { command: "local", lifecycleAdmission: false, execute: runLocalEntry },
-]);
+/** Project only the trusted definitions supplied by the host, preserving their order. */
+export function builtinCliEntries(definitions: readonly AdapterDefinition[]): readonly BuiltinCliEntry[] {
+  return Object.freeze(definitions.flatMap(definition => definition.cli.entry
+    ? [Object.freeze({ ...definition.cli.entry, command: definition.cli.command })]
+    : []));
+}

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

@@ -14,7 +14,7 @@ export function previewQwen(ctx: NativePreviewContext) {
   const sessionId = value("--session-id");
   if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
   if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
-  launch = adapter.start.launch({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
+  launch = adapter.start.launch!({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
     userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
   unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });