@staix/agent-hub 0.12.23 → 0.12.24

package/src/cli/identity.ts

@@ -1,3 +1,5 @@
+import { isSupportedPeer } from "../hub/peer-catalog.ts";
+
 export type CliIdentity =
   | { role: "console" }
   | { role: "tools"; peer: string }
@@ -26,8 +28,9 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
-  if (command === "permission" || command === "stop") return "console";
+  if (command === "permission" || command === "stop" || command === "watch") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
+  if (command === "role") return ["list", "show"].includes(args[0] ?? "") ? "allowed" : "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
     if (["assign", "escalate"].includes(args[0] ?? "")) return "conductor";
@@ -36,21 +39,29 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
   // #247: reading the research measures and records is harmless (ids and counts only); writing them is a person's.
   if (command === "research") return args[0] === "backfill" ? "console" : "allowed";
+  // #258: reading hub memory is harmless; promote, demote, forget, supersede and rebuild are a person's.
+  if (command === "memory") { const sub = args.find((arg) => arg !== "--json"); return sub === undefined || sub.startsWith("--") || ["list", "search", "show", "suggestions"].includes(sub) || (sub === "machine" && !args.includes("--label")) ? "allowed" : "console"; } // graph labels are unscreened note text: a person's
+  if (command === "goal") { const sub = args.find((arg) => arg !== "--json"); return sub === undefined || sub.startsWith("--") || ["list", "show"].includes(sub) ? "allowed" : "console"; }
   // #251: a run resets the bench project's tree and proposes work; reading results is harmless.
   // The subcommand is the first argument that is not --json, which the command accepts anywhere.
   if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
   if (command === "budget") return !args.length || args.every((arg) => arg === "--json" || arg === "--full" || arg.startsWith("--color=")) ? "allowed" : "console";
-  if (["claude", "codex", "kimi", "pi", "local", "pause", "resume"].includes(command)) return "conductor";
-  if (["help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
+  if (command === "jcode") return "console"; // the person launcher alone writes its project MCP entry
+  if (isSupportedPeer(command) || ["pause", "resume"].includes(command)) return "conductor";
+  if (command === "board" && args[0] === "import") return "console";
+  if (["help", "version", "--version", "say", "status", "pet", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
   return "console";
 }
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[]): string {
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "stop", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
-  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "bench"].includes(command)) {
-    const sub = command === "bench" ? args.find((arg) => arg !== "--json") : args[0];
-    if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "run", "report", "compare"].includes(sub)) return `${command} ${sub}`;
+  if (command === "backlog") return ["list", "add", "pull", "pull-ready", "split", "return", "plan", "pin", "undo"].includes(args[0] ?? "") ? `backlog ${args[0]}` : "backlog";
+  if (command === "board" && args[0] === "import") return "board import";
+  if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "qwen", "jcode", "pi", "local", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench"].includes(command)) {
+    const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
+    if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take"].includes(sub)) return `${command} ${sub}`;
   }
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }

package/src/cli/init.ts

@@ -1,5 +1,10 @@
+import { initShadow, repoOf } from "../hub/snapshots.ts";
+import { profileName, projectProfile, resolveProfile, mergeProfileOverrides, type ProfileName } from "../hub/profiles.ts";
+import { JCODE_MCP_FILE } from "./jcode-mcp.ts";
 import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { hubGitSync } from "../hub/git.ts";
+import { KIMI_MCP_FILE } from "./kimi-mcp.ts";
 
 const TEMPLATES = join(import.meta.dir, "..", "..", "templates");
 const BEGIN = "<!-- AGENT_HUB:BEGIN (managed by `ahub init`, edits inside are overwritten) -->";
@@ -30,21 +35,51 @@ export interface InitChange {
   managedBlock?: "insert" | "replace" | "remove";
 }
 /** Content is internal to apply, never included in a public preview. */
-interface PlannedWrite extends InitChange { next?: string; }
-function changes(cwd: string): PlannedWrite[] {
+interface PlannedWrite extends InitChange { next?: string; shadow?: true; }
+function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedWrite[] {
+  const repository = shadow ? repoOf(cwd) : undefined;
+  if (shadow && repository && !repository.shadow) throw new Error("project already has a Git work tree; shadow mode is for non-git folders");
+  if (shadow) {
+    const parent = lstatSync(join(cwd, ".agenthub"), { throwIfNoEntry: false });
+    if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error(".agenthub must be a project directory, not a link");
+    const own = lstatSync(join(cwd, ".agenthub/shadow.git"), { throwIfNoEntry: false });
+    if (own && !repository?.shadow) throw new Error("existing shadow metadata is invalid; nothing was replaced");
+    const ignore = lstatSync(join(cwd, ".agenthub/ignore"), { throwIfNoEntry: false });
+    if (ignore && (!ignore.isFile() || ignore.isSymbolicLink() || ignore.nlink !== 1)) throw new Error("shadow ignore must be a regular project file, not a link");
+  }
+  const configPath = join(cwd, ".agenthub", "config.json");
+  const existingProfile = existsSync(configPath) ? profileName(JSON.parse(readFileSync(configPath, "utf8")).profile) : undefined;
+  let overrides: unknown, activeProfile = existingProfile;
+  for (const name of ["config.json", "config.local.json"]) {
+    const path = join(cwd, ".agenthub", name);
+    if (existsSync(path)) {
+      const layer = JSON.parse(readFileSync(path, "utf8"));
+      if (layer.profile !== undefined) activeProfile = profileName(layer.profile);
+      resolveProfile(activeProfile, layer.profile_overrides);
+      overrides = mergeProfileOverrides(overrides, layer.profile_overrides);
+    }
+  }
+  if (requested !== undefined && activeProfile !== undefined && requested !== activeProfile) throw new Error("init profile differs from existing config; edit the project profile explicitly before refreshing instructions");
+  const profile = resolveProfile(requested ?? activeProfile, overrides);
   const changed: PlannedWrite[] = [];
+  if (shadow && !repository?.shadow) changed.push({ action: "create", path: join(cwd, ".agenthub/shadow.git"), reason: "create opt-in shadow Git metadata without .git", shadow: true });
   const write = (path: string, next: string, reason: string, managedBlock?: InitChange["managedBlock"]) => {
     const exists = existsSync(path);
     if (exists && readFileSync(path, "utf8") === next) return;
     changed.push({ action: exists ? "modify" : "create", path, next, reason, ...(managedBlock ? { managedBlock } : {}) });
   };
+  if (shadow && !existsSync(join(cwd, ".agenthub/ignore"))) write(join(cwd, ".agenthub/ignore"), "# Paths excluded from shadow snapshots and facts\ndata/raw/\n", "create editable large/raw data ignore policy");
   for (const name of ["config.json", "routing.toml"]) {
     const path = join(cwd, ".agenthub", name);
-    if (!existsSync(path)) write(path, readFileSync(join(TEMPLATES, name), "utf8"), "create missing project defaults");
+    if (!existsSync(path)) {
+      const template = readFileSync(join(TEMPLATES, name), "utf8");
+      const next = name === "config.json" && profile.name !== "dev" ? JSON.stringify({ ...JSON.parse(template), profile: profile.name }, null, 2) + "\n" : template;
+      write(path, next, "create missing project defaults");
+    }
   }
   const agents = join(cwd, "AGENTS.md");
   const existing = existsSync(agents) ? readFileSync(agents, "utf8") : "";
-  write(agents, upsertBlock(existing, readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")), "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
+  write(agents, upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")), "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
   const claude = join(cwd, "CLAUDE.md");
   const own = lstatSync(claude, { throwIfNoEntry: false });
   // The write preserves an existing inode, including AGENTS.md -> CLAUDE.md and hard links.
@@ -57,22 +92,25 @@ function changes(cwd: string): PlannedWrite[] {
   }
   const ignore = join(cwd, ".gitignore");
   let lines = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
-  for (const entry of [".agenthub/state/", ".agenthub/config.local.json", ".agenthub/routing.local.toml"]) {
+  for (const entry of [".agenthub/state/", ".agenthub/config.local.json", ".agenthub/routing.local.toml", ...(shadow ? [".agenthub/shadow.git/"] : [])]) {
     if (!lines.split("\n").includes(entry)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${entry}\n`;
   }
+  if (existsSync(join(cwd, KIMI_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", KIMI_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(KIMI_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${KIMI_MCP_FILE}\n`;
+  if (existsSync(join(cwd, JCODE_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(JCODE_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${JCODE_MCP_FILE}\n`;
   write(ignore, lines, "ignore runtime state and machine-local configuration");
   return changed;
 }
 /** Read-only metadata, deliberately omitting project/user file contents. */
-export function planInit(cwd: string): InitChange[] {
-  return changes(cwd).map(({ next, ...change }) => change);
+export function planInit(cwd: string, profile?: ProfileName, shadow = false): InitChange[] {
+  return changes(cwd, profile, shadow).map(({ next, shadow: _shadow, ...change }) => change);
 }
 /** Returns the paths it changed, applying the same plan as the preview. */
-export function init(cwd: string): string[] {
-  const plan = changes(cwd);
+export function init(cwd: string, profile?: ProfileName, shadow = false): string[] {
+  const plan = changes(cwd, profile, shadow);
   mkdirSync(join(cwd, ".agenthub"), { recursive: true });
   for (const change of plan) {
-    if (change.action === "delete") unlinkSync(change.path);
+    if (change.shadow) initShadow(cwd);
+    else if (change.action === "delete") unlinkSync(change.path);
     else writeFileSync(change.path, change.next!);
   }
   return plan.map(change => change.path);

package/src/cli/jcode-mcp.ts

@@ -0,0 +1,58 @@
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { hubGitSync } from "../hub/git.ts";
+
+export const JCODE_MCP_FILE = ".jcode/mcp.json", JCODE_MCP_NAME = "agent-hub-jcode";
+type Document = Record<string, unknown>;
+const object = (value: unknown): value is Document => !!value && typeof value === "object" && !Array.isArray(value);
+
+function document(file: string): Document {
+  const stat = lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) return {};
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 256 * 1024) throw new Error("Jcode MCP configuration must be a bounded regular file, not a link");
+  let value: unknown; try { value = JSON.parse(readFileSync(file, "utf8")); } catch { throw new Error("Jcode MCP configuration is invalid JSON"); }
+  if (!object(value)) throw new Error("Jcode MCP configuration must be an object");
+  if (value.servers !== undefined && value.mcpServers !== undefined) throw new Error("Jcode MCP configuration has ambiguous server maps");
+  for (const key of ["servers", "mcpServers"]) if (value[key] !== undefined && !object(value[key])) throw new Error("Jcode MCP server map must be an object");
+  return value;
+}
+const map = (doc: Document): Document => (doc.mcpServers ?? doc.servers ?? {}) as Document;
+const owned = (entry: unknown, cwd: string): entry is Document => object(entry) && object(entry.env) && entry.env.AGENTHUB_MODE === "tools" && entry.env.AGENTHUB_PEER_ID === "jcode" && entry.env.AGENTHUB_PROJECT_DIR === cwd;
+
+export function jcodeMcpEntry(cwd: string, stateDir: string, bundle: string) {
+  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_PEER_ID: "jcode", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
+}
+/** The native loader reads later project files last. Never shadow a foreign definition. */
+function inspect(cwd: string): Document {
+  const directory = lstatSync(join(cwd, ".jcode"), { throwIfNoEntry: false });
+  if (directory && (!directory.isDirectory() || directory.isSymbolicLink())) throw new Error(".jcode must be a project directory, not a link");
+  for (const relative of [".mcp.json", ".claude/mcp.json"]) {
+    const parent = relative.startsWith(".claude/") ? lstatSync(join(cwd, ".claude"), { throwIfNoEntry: false }) : undefined;
+    if (parent?.isSymbolicLink()) throw new Error("Jcode MCP override layer is a link; inspect it before launching");
+    if (Object.hasOwn(map(document(join(cwd, relative))), JCODE_MCP_NAME)) throw new Error("a later project MCP layer overrides agent-hub-jcode; resolve it in your editor");
+  }
+  return document(join(cwd, JCODE_MCP_FILE));
+}
+export function jcodeMcpReady(cwd: string, stateDir: string, bundle: string): boolean {
+  const entry = map(inspect(cwd))[JCODE_MCP_NAME];
+  return JSON.stringify(entry) === JSON.stringify(jcodeMcpEntry(cwd, stateDir, bundle));
+}
+/** Only the console launcher calls this; daemon starts use jcodeMcpReady read-only. */
+export function configureJcodeMcp(cwd: string, stateDir: string, bundle: string, remove = false): { changed: boolean; tracked: boolean } {
+  const current = inspect(cwd), servers = { ...map(current) }, existing = servers[JCODE_MCP_NAME];
+  if (existing !== undefined && !owned(existing, cwd)) throw new Error("agent-hub-jcode is a foreign MCP entry; it was not changed");
+  if (remove) delete servers[JCODE_MCP_NAME]; else servers[JCODE_MCP_NAME] = jcodeMcpEntry(cwd, stateDir, bundle);
+  const key = current.servers !== undefined ? "servers" : "mcpServers";
+  const next = { ...current, ...(current[key] !== undefined || !remove ? { [key]: servers } : {}) };
+  const tracked = hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status === 0;
+  if (JSON.stringify(next) === JSON.stringify(current)) return { changed: false, tracked };
+  mkdirSync(join(cwd, ".jcode"), { recursive: true });
+  const file = join(cwd, JCODE_MCP_FILE), temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    const fd = openSync(temporary, "wx", 0o600);
+    try { writeFileSync(fd, `${JSON.stringify(next, null, 2)}\n`); } finally { closeSync(fd); }
+    renameSync(temporary, file);
+  } finally { if (existsSync(temporary)) unlinkSync(temporary); }
+  return { changed: true, tracked };
+}

package/src/cli/kimi-mcp.ts

@@ -0,0 +1,53 @@
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { hubGitSync } from "../hub/git.ts";
+
+export const KIMI_MCP_FILE = ".kimi-code/mcp.json";
+type Document = Record<string, unknown> & { mcpServers?: Record<string, unknown> };
+
+/** No writes: the daemon uses this check before an ACP launch to avoid a second hub connection. */
+export function kimiMcpDocument(cwd: string): Document {
+  const directory = join(cwd, ".kimi-code"), file = join(cwd, KIMI_MCP_FILE);
+  const dir = lstatSync(directory, { throwIfNoEntry: false });
+  if (dir && (!dir.isDirectory() || dir.isSymbolicLink())) throw new Error(".kimi-code must be a project directory, not a link");
+  const stat = lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) return {};
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error(".kimi-code/mcp.json must be a regular file, not a link");
+  let document: unknown;
+  try { document = JSON.parse(readFileSync(file, "utf8")); }
+  catch { throw new Error(".kimi-code/mcp.json is not valid JSON; correct it before launching Kimi"); }
+  if (!document || typeof document !== "object" || Array.isArray(document)) throw new Error(".kimi-code/mcp.json must be an object");
+  const servers = (document as Document).mcpServers;
+  if (servers !== undefined && (!servers || typeof servers !== "object" || Array.isArray(servers))) throw new Error(".kimi-code/mcp.json mcpServers must be an object");
+  return document as Document;
+}
+
+export function hasKimiHubMcp(cwd: string): boolean {
+  return Object.hasOwn(kimiMcpDocument(cwd).mcpServers ?? {}, "agent-hub");
+}
+
+/** Only the person's launcher applies this plan; a preview inspects it without writing or displaying foreign data. */
+export function kimiMcpPlan(cwd: string, stateDir: string, bundle: string, mode: "tui" | "headless") {
+  const current = kimiMcpDocument(cwd);
+  const servers = { ...current.mcpServers };
+  if (mode === "tui") servers["agent-hub"] = { command: "bun", args: ["run", bundle], env: { AGENTHUB_PEER_ID: "kimi", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
+  else delete servers["agent-hub"];
+  const next = { ...current, ...(current.mcpServers !== undefined || mode === "tui" ? { mcpServers: servers } : {}) };
+  const tracked = hubGitSync(["ls-files", "--error-unmatch", "--", KIMI_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status === 0;
+  return { file: join(cwd, KIMI_MCP_FILE), action: mode === "tui" ? "merge agent-hub entry" : "remove agent-hub entry", tracked,
+    changed: JSON.stringify(current) !== JSON.stringify(next), next };
+}
+
+export function configureKimiMcp(cwd: string, stateDir: string, bundle: string, mode: "tui" | "headless"): { changed: boolean; tracked: boolean } {
+  const plan = kimiMcpPlan(cwd, stateDir, bundle, mode);
+  if (!plan.changed) return { changed: false, tracked: plan.tracked };
+  mkdirSync(join(cwd, ".kimi-code"), { recursive: true });
+  const temporary = `${plan.file}.${randomUUID()}.tmp`;
+  try {
+    const fd = openSync(temporary, "wx", 0o600);
+    try { writeFileSync(fd, `${JSON.stringify(plan.next, null, 2)}\n`); } finally { closeSync(fd); }
+    renameSync(temporary, plan.file);
+  } finally { try { unlinkSync(temporary); } catch { /* rename consumed our temporary file */ } }
+  return { changed: true, tracked: plan.tracked };
+}

package/src/cli/launch.ts

@@ -9,11 +9,12 @@ import { peerChildEnv, processTable } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
-export function nativeLaunchEnv(tool: "claude" | "codex" | "pi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+export function nativeLaunchEnv(tool: "claude" | "codex" | "pi" | "kimi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   const env = peerChildEnv(tool, source);
   delete env.AGENTHUB_UNATTENDED;
   // Channel evidence for the plugin (issue #205): set beside the development-channel flag `buildLaunch` always passes.
   if (tool === "claude") env.AGENTHUB_CHANNEL = "1";
+  if (tool === "kimi") delete env.AGENTHUB_MODE; // its MCP child must attach pull-only, never as a tools socket
   return env;
 }
 
@@ -391,3 +392,17 @@ export function buildKimiLaunch(command: string[], model?: string): Launch {
   const [cmd, ...args] = command;
   return { cmd: cmd!, args: model ? ["--model", model, ...args] : args };
 }
+
+/** Qwen flags follow the configured executable argv, including wrapper/script arguments. */
+export function buildQwenLaunch(command: string[], model?: string): Launch {
+  const [cmd, ...args] = command;
+  if (!cmd) throw new Error("qwen_cmd must name an executable");
+  return { cmd, args: [...args, ...(model ? ["--model", model] : [])] };
+}
+
+/** The configured ACP argv has a TUI form only when its exact final word is the ACP subcommand. */
+export function buildKimiTuiLaunch(command: string[], model?: string): Launch {
+  if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("kimi_cmd must name an executable");
+  if (command.length > 1 && command.at(-1) !== "acp") throw new Error("kimi_cmd has no derivable TUI form; use a single executable or an argv ending in acp, or run ahub kimi --mode headless");
+  return buildKimiLaunch(command.length > 1 ? command.slice(0, -1) : command, model);
+}