@staix/agent-hub 0.12.33 → 0.12.35

package/src/adapters/definitions/native-cli-claude-launch.ts

@@ -0,0 +1,90 @@
+import { mkdirSync, writeFileSync, renameSync, unlinkSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve, join } from "node:path";
+import { CLAUDE_CHANNEL, sessionSettings, UNATTENDED_WARNING, type Launch } from "../../cli/launch.ts";
+import type { LaunchContext, LaunchPlan } from "../registry-types.ts";
+import { nativeLaunchArguments, nativeLaunchPlan } from "./native-cli-launch-common.ts";
+
+export const CLAUDE_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]), unattended: true, passthrough: true });
+
+function claudeChannel(userArgs: string[]): string {
+  const bundle = resolve(import.meta.dir, "../../../plugins/agent-hub/server.js");
+  for (let i = 0; i < userArgs.length; i++) {
+    const arg = userArgs[i]!;
+    const path = arg === "--mcp-config" ? userArgs[i + 1] : arg.startsWith("--mcp-config=") ? arg.slice("--mcp-config=".length) : undefined;
+    if (!path) continue;
+    try {
+      const server = JSON.parse(readFileSync(resolve(path), "utf8")).mcpServers?.["agent-hub"];
+      if (server?.command === "bun" && Array.isArray(server.args) && server.args.some((value: unknown) => typeof value === "string" && resolve(value) === bundle)) return "server:agent-hub";
+    } catch { /* The native CLI reports invalid user-supplied MCP configuration. */ }
+  }
+  return CLAUDE_CHANNEL;
+}
+
+export function claudeNativeLaunch(ctx: LaunchContext): LaunchPlan {
+  const { passthrough, unattended } = nativeLaunchArguments("claude", ctx, CLAUDE_LAUNCH_POLICY);
+  const build = (): Launch => {
+    // `--settings` takes one value, so a user-supplied one wins and Claude has no quota source for that session.
+    const own = passthrough.some((a) => a === "--settings" || a.startsWith("--settings="));
+    let settingsArgs = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
+    let nativeArgs = passthrough;
+    let settingsFile: string | undefined;
+    if (own) {
+      if (passthrough.filter(a => a === "--settings" || a.startsWith("--settings=")).length > 1) throw new Error("pass --settings only once so the hub permission hook stays installed");
+      const index = passthrough.findIndex(a => a === "--settings" || a.startsWith("--settings="));
+      const arg = passthrough[index]!;
+      const value = arg === "--settings" ? passthrough[index + 1] : arg.slice("--settings=".length);
+      if (!value) throw new Error("--settings requires a JSON object or readable file so the hub permission hook can be installed");
+      let caller: Record<string, unknown>;
+      try {
+        caller = JSON.parse(value.trim().startsWith("{") ? value : readFileSync(resolve(value), "utf8"));
+        if (!caller || typeof caller !== "object" || Array.isArray(caller)) throw new Error("not an object");
+      } catch { throw new Error("cannot read --settings as a JSON object; the hub permission hook must be installed"); }
+      if (ctx.facts && caller.disableAllHooks === true) throw new Error("--settings disableAllHooks prevents the required hub permission hook; enable hooks to launch");
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      const callerHooks = caller.hooks;
+      if (callerHooks !== undefined && (!callerHooks || typeof callerHooks !== "object" || Array.isArray(callerHooks))) throw new Error("--settings hooks must be an object");
+      const hooks = { ...(callerHooks as Record<string, unknown> | undefined) };
+      for (const [event, entries] of Object.entries(injected.hooks ?? {})) {
+        const existing = hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) throw new Error(`--settings ${event} hooks must be an array`);
+        hooks[event] = [...(existing as unknown[] | undefined ?? []), ...(entries as unknown[])];
+      }
+      settingsArgs = ["--settings", JSON.stringify({ ...caller, ...(ctx.facts ? { hooks } : {}) })];
+      nativeArgs = passthrough.filter((_, i) => i !== index && (arg !== "--settings" || i !== index + 1));
+    } else if (ctx.facts && !ctx.statusLine) {
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      settingsArgs = ["--settings", JSON.stringify({ hooks: injected.hooks })];
+    }
+    if (settingsArgs.length && !ctx.preview) {
+      const stateDir = ctx.facts?.stateDir ?? ctx.statusLine?.stateDir;
+      if (!stateDir) throw new Error("Claude session settings require the hub state directory");
+      const file = join(stateDir, `claude-settings-${randomUUID()}.json`);
+      try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(`${file}.tmp`, settingsArgs[1]!, { mode: 0o600, flag: "wx" });
+        renameSync(`${file}.tmp`, file);
+      } catch {
+        try { unlinkSync(`${file}.tmp`); } catch { /* no temp file was written */ }
+        throw new Error("cannot write private Claude session settings in the hub state directory");
+      }
+      settingsArgs[1] = file;
+      settingsFile = file;
+    }
+    const notes = [
+      unattended ? UNATTENDED_WARNING : "",
+      ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : "",
+    ].filter(Boolean);
+    return {
+      cmd: "claude",
+      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...settingsArgs, ...nativeArgs],
+      ...(settingsFile ? { settingsFile } : {}),
+      permissionHook: !!ctx.facts,
+      ...(ctx.facts ? { hookPurpose: ctx.facts.purpose ?? "facts" } : {}),
+      unattended,
+      ...(notes.length ? { warning: notes.join("\n") } : {}),
+    };
+
+  };
+  return nativeLaunchPlan(build(), ctx);
+}

package/src/adapters/definitions/native-cli-claude-setup.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { realPath } from "../../hub/project.ts";
+import { VERSION } from "../../version.ts";
+
+export const PLUGIN = "agent-hub@agent-hub";
+const MARKETPLACE = "agent-hub";
+
+export interface InstalledPlugin {
+  id: string;
+  version?: string;
+  installPath?: string;
+}
+export interface Marketplace {
+  name: string;
+  path?: string;
+}
+
+/** `claude plugin list --json` / `claude plugin marketplace list --json`. Anything that does not parse is an empty list. */
+export function parseList<T>(json: string): T[] {
+  try {
+    const d = JSON.parse(json);
+    return Array.isArray(d) ? d : [];
+  } catch {
+    return [];
+  }
+}
+
+const real = (p: string) => {
+  try {
+    return realPath(p);
+  } catch {
+    return p;
+  }
+};
+const read = (p: string) => {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return undefined;
+  }
+};
+
+export type PluginState = { state: "missing" } | { state: "current"; version: string } | { state: "stale"; version: string; why: string };
+
+/**
+ * Is the installed Claude plugin the one this hub ships? The version is compared, and so is the bundle itself: Claude
+ * Code runs a cached copy, and a copy taken from an earlier build of the same version speaks an older wire protocol.
+ */
+export function pluginState(plugins: InstalledPlugin[], packageRoot: string): PluginState {
+  const mine = plugins.find((p) => p.id === PLUGIN);
+  if (!mine) return { state: "missing" };
+  const version = mine.version ?? "unknown";
+  if (version !== VERSION) return { state: "stale", version, why: `version ${version}, this hub is ${VERSION}` };
+  const shipped = read(join(packageRoot, "plugins", "agent-hub", "server.js"));
+  const cached = mine.installPath ? read(join(mine.installPath, "server.js")) : undefined;
+  if (shipped !== undefined && cached !== undefined && shipped !== cached) return { state: "stale", version, why: "same version, but the cached bundle differs from the one this hub ships" };
+  return { state: "current", version };
+}
+
+export interface SetupStep {
+  why: string;
+  argv: string[];
+}
+
+/**
+ * The next thing `ahub setup` has to do, or nothing. One step at a time: the state is read again after every step,
+ * because what a step leaves behind is Claude Code's business (removing a marketplace may uninstall its plugins).
+ */
+export function nextStep(plugins: InstalledPlugin[], marketplaces: Marketplace[], packageRoot: string): SetupStep | undefined {
+  const root = real(packageRoot);
+  const market = marketplaces.find((m) => m.name === MARKETPLACE);
+  if (market && real(market.path ?? "") !== root) return { why: `the ${MARKETPLACE} marketplace points at ${market.path ?? "another source"}, not at this package`, argv: ["claude", "plugin", "marketplace", "remove", MARKETPLACE] };
+  if (!market) return { why: "register this package as a Claude Code plugin marketplace", argv: ["claude", "plugin", "marketplace", "add", root] };
+  const state = pluginState(plugins, root);
+  if (state.state === "missing") return { why: "install the channel plugin", argv: ["claude", "plugin", "install", PLUGIN] };
+  // Uninstall rather than update: with an unchanged version number an update has nothing to do.
+  if (state.state === "stale") return { why: `replace the installed plugin (${state.why})`, argv: ["claude", "plugin", "uninstall", PLUGIN] };
+  return undefined;
+}

package/src/adapters/definitions/native-cli-codex-launch.ts

@@ -0,0 +1,14 @@
+import type { LaunchContext, LaunchPlan } from "../registry-types.ts";
+import { nativeLaunchArguments, nativeLaunchPlan } from "./native-cli-launch-common.ts";
+
+export const CODEX_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]), unattended: true, passthrough: true });
+export function codexNativeLaunch(ctx: LaunchContext): LaunchPlan {
+  const { passthrough, unattended, warning } = nativeLaunchArguments("codex", ctx, CODEX_LAUNCH_POLICY);
+  if (!ctx.proxyUrl) throw new Error("codex proxy url is missing");
+  return nativeLaunchPlan({
+    cmd: ctx.codexBin ?? "codex",
+    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
+    unattended,
+    ...warning,
+  }, ctx);
+}

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

@@ -0,0 +1,46 @@
+import type { DoctorCheck } from "../../cli/output.ts";
+
+// Fixed builtin doctor policy only. These projections neither execute probes nor extend AdapterDefinition.
+const nativeTools = [
+  { id: "claude", initial: true }, { id: "codex", initial: true }, { id: "kimi", initial: true },
+  { id: "qwen", initial: false }, { id: "jcode", initial: false },
+] as const;
+export const DOCTOR_TOOL_PROBES: readonly string[] = Object.freeze(["bun", ...nativeTools.filter(tool => tool.initial).map(tool => tool.id)]);
+export const DOCTOR_MEMORY_CAPTURE_PEERS = Object.freeze(["codex", "kimi"] as const);
+export const DOCTOR_PLUGIN_PROBE = Object.freeze({ command: "claude", argv: Object.freeze(["plugin", "list", "--json"] as const), name: "claude plugin" });
+
+/** Exact legacy section and severity classification, including non-native and unknown diagnostic names. */
+export function nativeDoctorCheck(ok: boolean | undefined, name: string, detail: string): DoctorCheck {
+  const nativeTool = nativeTools.some(tool => tool.id === name);
+  const section: DoctorCheck["section"] = name === "bun" || nativeTool ? "Tools"
+    : name === "config" || name === "retired setting" ? "Config"
+    : name.startsWith("memory") ? "Memory"
+    : ["omniroute", "omniroute key", "local fixed_model", "switchyard", "pi mlx"].includes(name) ? "Models" : "Hub";
+  const optional = nativeTool || ["ahub daemon", "switchyard", "pi mlx"].includes(name) || section === "Memory";
+  const level: DoctorCheck["level"] = ok === undefined ? (["switchyard", "omniroute"].includes(name) ? "warn" : "unknown") : ok ? "ok" : optional ? "warn" : "fail";
+  return { section, level, name, detail };
+}
+
+/** Recovery IDs are checked only for the two legacy native conversation surfaces. */
+export function nativeDoctorRecoveryIdentity(peer: { id: string; state: string; sessionId?: string; threadId?: string }): { ok: boolean; name: string; detail: string } | undefined {
+  const fields = { claude: "sessionId", codex: "threadId" } as const;
+  const field = Object.hasOwn(fields, peer.id) ? fields[peer.id as keyof typeof fields] : undefined;
+  if (!field || peer.state === "offline") return undefined;
+  const identity = peer[field];
+  return { ok: !!identity, name: `${peer.id} recovery ID`, detail: identity ? "recorded" : `missing; verify the current conversation and reconnect with ahub ${peer.id} before upgrading` };
+}
+
+export type NativeDoctorOptionalProbe =
+  | { kind: "source-identity"; name: string; command: string[]; detail: string }
+  | { kind: "pinned-version"; name: string; command: string[]; expected: string; confirmed: string; unconfirmed: string };
+
+/** The host runs these existing checks in order; no process, filesystem or caller callback enters this planner. */
+export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[] }): NativeDoctorOptionalProbe[] {
+  const probes: NativeDoctorOptionalProbe[] = [];
+  if (config.roster.jcode === true) probes.push({ kind: "source-identity", name: "jcode", command: config.jcode_cmd,
+    detail: "CLI/source identity only; provider, project MCP and native teardown require separate receipts; native policy unmanaged" });
+  if (config.roster.qwen === true) probes.push({ kind: "pinned-version", name: "qwen", command: config.qwen_cmd, expected: "0.25.0",
+    confirmed: "CLI reports 0.25.0; native ACP identity/modes and provider access require a separate live check",
+    unconfirmed: "Qwen Code 0.25.0 executable not confirmed; provider and ACP readiness unknown" });
+  return probes;
+}

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

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ClaudeLaunchRecord } from "../../cli/launch.ts";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, fail } = ctx;
+  const { launcherPreview, readControl, recordTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("claude", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const control = readControl(stateDir);
+  if (control?.instanceId) {
+    process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
+    const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+    if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
+  }
+  // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
+  // project local, then project, then user.
+  let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
+  for (const file of [join(cwd, ".claude", "settings.local.json"), join(cwd, ".claude", "settings.json"), join(process.env.HOME ?? "", ".claude", "settings.json")]) {
+    try {
+      original ??= JSON.parse(readFileSync(file, "utf8")).statusLine;
+    } catch {
+      // no such file, or no status line in it
+    }
+  }
+  // Turn-free facts and opted-in task sweeps share native PreToolUse/PostToolUse/Stop observations.
+  const facts = claudeObservationHooks(projectConfig(), { script: join(cliDir, "facts-hook.ts"), stateDir });
+  let previousLaunch: unknown;
+  try { previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")); } catch { /* no previous managed launch */ }
+  const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(cliDir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
+  let result: Awaited<ReturnType<typeof runClaudeLaunch>>;
+  try {
+    let launchRecord: ClaudeLaunchRecord | undefined;
+    if (control?.instanceId) {
+      // Publish only the final launch's installed hook and effective permission flags.
+      launchRecord = { instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
+      recordClaudeLaunch(stateDir, launchRecord);
+      cleanupStaleClaudeSettings(stateDir, previousLaunch);
+    }
+    if (launch.warning) console.error(launch.warning);
+    const env = nativeLaunchEnv("claude", childEnv());
+    result = await runClaudeLaunch(launch, { cwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
+  } finally {
+    cleanupClaudeSettings(stateDir, launch.settingsFile);
+  }
+  if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
+  process.exit(result.status ?? 1);
+}

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

@@ -0,0 +1,34 @@
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "codex";
+  const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, exec } = ctx;
+  const { launcherPreview, buildLaunch, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: "pending" }); // refuse bad flags before starting anything
+  // #215: a launch by a recovery operation records itself before the hub round trip, so the coordinator never takes
+  // a launcher still starting for one that never ran. An ordinary launch records only once the hub accepted it: a
+  // refused start must not replace the record of a Codex already running here (one row per peer and instance).
+  const recovering = !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock(); // not an id a restored session inherited
+  const before = readControl(stateDir);
+  // ponytail: recovering extras have no authenticated execution-root binding before start replies, so their row
+  // is recorded afterward. The coordinator retains its pending creation/wait evidence; add pre-start recording
+  // only when a future recovery receipt supplies independently verified exact-instance execution-root evidence.
+  if (recovering && !ctx.instance && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
+  const hub = await connect();
+  const res = await hub.request({ t: "start", peer, args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  hub.close();
+  if (!res.ok) fail(res.error);
+  if (ctx.instance) {
+    if (typeof res.executionCwd !== "string" || !res.executionCwd.startsWith("/")) fail("instance execution directory was not verified");
+    ctx.executionCwd = res.executionCwd;
+  }
+  const control = readControl(stateDir);
+  if ((!recovering || ctx.instance) && control?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: ctx.executionCwd } : undefined);
+  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
+  if (launch0.warning) console.error(launch0.warning);
+  exec(launch.cmd, launch.args, "codex");
+}

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

@@ -0,0 +1,27 @@
+import { resolve } from "node:path";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+import { rosterInStatus } from "../../hub/status-roster.ts";
+
+export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, cliDir, unattendedEnv, connect, fail, takeFlags } = ctx;
+  const { launcherPreview, qwenSessionId, configureJcodeMcp } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
+  }
+  const { one, rest } = takeFlags(args, ["--mode", "--model", "--provider-profile", "--session-id"], []);
+  if (rest.length || (one["--mode"] !== undefined && one["--mode"] !== "headless")) fail("usage: ahub jcode [--mode headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
+  if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Jcode session identity");
+  const hub = await connect();
+  try {
+    const snapshot = (await hub.request({ t: "status" })).status;
+    const rostered = rosterInStatus(snapshot, "jcode");
+    if (rostered === undefined) fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
+    if (!rostered) fail("jcode is off roster; add it with ahub roster add jcode");
+    const written = configureJcodeMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"));
+    if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
+    const reply = await hub.request({ t: "start", peer: "jcode", args: { mode: "headless", model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+    if (!reply.ok) fail(reply.error);
+    console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox");
+  } finally { hub.close(); }
+}

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

@@ -0,0 +1,57 @@
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+import { 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;
+  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"];
+  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 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`);
+    } finally { hub.close(); }
+  }
+  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 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);
+      let result: ReturnType<typeof spawnSync>;
+      try {
+        const written = configureKimiMcp(cwd, stateDir, 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.");
+        result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+      } finally {
+        if (admission.admissionId) await hub.request({ t: "kimi_launch_end", admissionId: admission.admissionId }).catch(() => {});
+      }
+      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];
+    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 });
+    if (!res.ok) fail(res.error);
+    console.log(res.already ? `${peer} is already attached` : `${peer} attached (headless). Talk to it with: ahub say @${peer} "..."`);
+  } finally { hub.close(); }
+}

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

@@ -0,0 +1,15 @@
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "local";
+  const { args, connect, fail } = ctx;
+  const opt = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] ?? fail(`${flag} needs a value`) : undefined);
+  for (const flag of ["--route", "--model"]) if (args.includes(flag) && (!opt(flag) || opt(flag)!.startsWith("--"))) fail(`${flag} needs a value`);
+  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 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);
+  console.log(res.already ? `${peer} is already attached` : `${peer} attached on ${res.model}. Give it work with: ahub say @${peer} "..."`);
+}

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

@@ -0,0 +1,53 @@
+import { parsePiFlags } from "./native-cli-pi.ts";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "pi";
+  const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, execWithEnv } = ctx;
+  const { launcherPreview, startModeOf, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
+  // --headless is --mode headless everywhere this command goes: the preview, the hub and the conductor path.
+  if (args.includes("--headless") && !args.includes("--mode")) args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("pi", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const flags = parsePiFlags(args, fail);
+  // #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")) };
+  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
+    // opens one, or says how to. It is never downgraded to headless. The fixed command carries no option, so one
+    // that was given needs a terminal of its own. An explicit --mode tui is taken at its word, as before.
+    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 reply = await hub.request({ t: "peer_start", peer }, 35_000);
+      if (reply.ok !== true) {
+        const error = String(reply.error ?? "pi start refused");
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_start"/i.test(error) ? `${error}; upgrade the running hub, or run ahub pi --mode headless` : error);
+      }
+      return console.log(reply.already ? "pi is already attached" : reply.opened ? `pi: opened a terminal running ${reply.command}; it attaches when its TUI is ready` : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
+    } finally { hub.close(); }
+  }
+  // #215: as for Codex, a TUI launch by the recovery operation holding the lock records itself before the hub round
+  // trip, so a resume in that window never reads it as gone; an ordinary launch records only after the hub accepted it.
+  const recovering = options.mode === "tui" && !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock();
+  const before = readControl(stateDir);
+  if (recovering && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
+  const hub = await connect();
+  const res = await hub.request({ t: "start", peer, args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  hub.close();
+  if (!res.ok) fail(res.error);
+  if (options.mode === "tui") {
+    const launch = res.launch;
+    if (!launch || typeof launch.cmd !== "string" || !Array.isArray(launch.args) || !launch.args.every((a: unknown) => typeof a === "string") || !launch.env || typeof launch.env !== "object") fail("Pi TUI launch metadata was not verified");
+    const launchEnv = { ...(launch.env as NodeJS.ProcessEnv) };
+    delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
+    delete launchEnv.AGENTHUB_UNATTENDED;
+    const control = readControl(stateDir);
+    if (!recovering && control?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId);
+    return execWithEnv(launch.cmd, launch.args, launchEnv);
+  }
+  console.log(res.already ? `${peer} is already attached` : `${peer} attached (headless). Talk to it with: ahub say @${peer} "..."`);
+}

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

@@ -0,0 +1,21 @@
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "qwen";
+  const { args, cwd, stateDir, unattendedEnv, connect, fail, takeFlags } = ctx;
+  const { launcherPreview } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("qwen", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview Qwen launch: invalid arguments or configuration (details withheld)"); }
+  }
+  const { one, rest } = takeFlags(args, ["--mode", "--model", "--session-id"], []);
+  const adapter = ctx.definition;
+  if (one["--session-id"] !== undefined && !adapter.session.crashIdentity?.({ sessionId: one["--session-id"] }).sessionId) fail("invalid Qwen session identity");
+  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 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`);
+  } finally { hub.close(); }
+}

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

@@ -0,0 +1,41 @@
+import type { HubConfig } from "../../hub/daemon.ts";
+import type { ControlClient } from "../../hub/control-client.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+
+/** Private static builtin relocation ports. The CLI binds identity, project and authority before invocation. */
+export interface NativeCliEntryContext {
+  instance?: string; executionCwd?: string;
+  args: string[]; cwd: string; stateDir: string; cliDir: string; unattendedEnv: boolean; definition: AdapterDefinition;
+  projectConfig(): HubConfig;
+  connect(): Promise<ControlClient>;
+  fail(message: string): never;
+  exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi"): never;
+  execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never;
+  takeFlags(argv: string[], single: string[], repeated: string[]): { one: Record<string, string>; many: Record<string, string[]>; rest: string[] };
+  helpers: {
+    launcherPreview: typeof import("../../cli/preview.ts").launcherPreview;
+    readControl: typeof import("../../hub/control-client.ts").readControl;
+    recordTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").recordTerminalLaunch;
+    recoveryLock: typeof import("../../hub/recovery-store.ts").recoveryLock;
+    processSignature: typeof import("../../pi/process-signature.ts").processSignature;
+    buildLaunch: typeof import("../../cli/launch.ts").buildLaunch;
+    claudeObservationHooks: typeof import("../../cli/launch.ts").claudeObservationHooks;
+    recordClaudeLaunch: typeof import("../../cli/launch.ts").recordClaudeLaunch;
+    cleanupStaleClaudeSettings: typeof import("../../cli/launch.ts").cleanupStaleClaudeSettings;
+    cleanupClaudeSettings: typeof import("../../cli/launch.ts").cleanupClaudeSettings;
+    nativeLaunchEnv: typeof import("../../cli/launch.ts").nativeLaunchEnv;
+    runClaudeLaunch: typeof import("../../cli/launch.ts").runClaudeLaunch;
+    childEnv: typeof import("../../hub/child-process.ts").childEnv;
+    qwenSessionId: typeof import("../../hub/crash.ts").qwenSessionId;
+    configureJcodeMcp: typeof import("../../cli/jcode-mcp.ts").configureJcodeMcp;
+    configureKimiMcp: typeof import("../../cli/kimi-mcp.ts").configureKimiMcp;
+    buildKimiTuiLaunch: typeof import("../../cli/launch.ts").buildKimiTuiLaunch;
+    startModeOf: typeof import("../../hub/start-mode.ts").startModeOf;
+  };
+}
+export interface BuiltinCliEntry {
+  command: string;
+  /** Original CLI guard timing: previews precede it; Pi/local retain their daemon-enforced start admission. */
+  lifecycleAdmission: boolean;
+  execute(context: NativeCliEntryContext): Promise<void>;
+}

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

@@ -0,0 +1,19 @@
+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: "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 },
+]);