@staix/agent-hub 0.12.33 → 0.12.35

package/src/cli/main.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env bun
-import { definitionOf } from "../adapters/registry.ts";
+import { effectiveInstanceRoles } from "../hub/instances.ts";
+import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
+import { readInstanceConfig } from "../hub/instance-config.ts";
+import type { NativeCliEntryContext } from "../adapters/definitions/native-cli-entry-types.ts";
+import { BUILTIN_CLI_ENTRIES, definitionOf, DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.ts";
+import { parsePiFlags } from "../adapters/definitions/native-cli-pi.ts";
 import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board-read.ts";
 import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
@@ -16,7 +21,6 @@ import { configureJcodeMcp } from "./jcode-mcp.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { isPermissionMode } from "../hub/permission-mode.ts";
 import { parseSettingText, settingDef, settingText, type SettingRow } from "../hub/settings.ts";
-import { isSupportedPeer } from "../hub/peer-catalog.ts";
 import { startModeOf } from "../hub/start-mode.ts";
 import { currentRouting } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
@@ -27,7 +31,7 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
-import { hubHome, projectContext, realPath } from "../hub/project.ts";
+import { hubHome, projectContext, projectRoot, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
 import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
@@ -36,7 +40,7 @@ import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
+import { instanceLaunchArguments, requirePeerInstances, cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
 import { configureKimiMcp } from "./kimi-mcp.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
@@ -101,11 +105,6 @@ while (argv[0] === "--project" || argv[0] === "--live-test") {
   }
 }
 const [given = "help", ...rest] = argv;
-// `ahub <command> -h` alone asks for that command's help instead of running it. Elsewhere `-h` may be message text
-// (`ahub say try ls -h`), and claude and codex pass their arguments on to the agent.
-const asksHelp = (a: string | undefined) => a === "--help" || a === "-h";
-const cmd = asksHelp(given) || (given !== "claude" && given !== "codex" && rest.length === 1 && asksHelp(rest[0])) ? "help" : given;
-const args = cmd === "help" && given !== "help" && !asksHelp(given) ? [given] : rest;
 let selected: { root: string; stateDir: string };
 try {
   if (selector) {
@@ -116,9 +115,42 @@ try {
       const registered = known ?? projects.find((p) => p.root === context.root);
       selected = registered ?? context;
     }
-  } else selected = projectContext(process.cwd());
-} catch (error) { fail((error as Error).message); }
+  } else {
+    const markedPeer = process.env.AGENTHUB_PEER_ID, markedRoot = process.env.AGENTHUB_PROJECT_DIR;
+    const declarations = markedPeer && markedRoot && !definitionOf(markedPeer) ? readInstanceConfig(realPath(markedRoot)).instances : undefined;
+    if (markedPeer && markedRoot && declarations && Object.hasOwn(declarations, markedPeer)) {
+      const canonicalRoot = realPath(markedRoot), config = loadConfig(canonicalRoot);
+      const executionCwd = resolveInstanceExecutionCwd(canonicalRoot, markedPeer, declarations, effectiveInstanceRoles(markedPeer, declarations, config.roles));
+      if (realPath(projectRoot(process.cwd())) !== realPath(executionCwd)) fail("native instance workspace does not match its declared checkout");
+      selected = projectContext(canonicalRoot);
+    } else selected = projectContext(process.cwd());
+  }
+} catch (error) { fail(startupDiagnostic(error)); }
 const cwd = selected.root;
+const unboundCaller = detectCliIdentity(process.env);
+const markerNeedsDeclaration = unboundCaller.role === "invalid" && unboundCaller.reason === "AGENTHUB_PEER_ID conflicts with native agent marker"
+  && process.env.AGENTHUB_PEER_ID !== undefined && !definitionOf(process.env.AGENTHUB_PEER_ID);
+const needsInstances = definitionOf(given) && rest.some(arg => arg === "--as" || arg.startsWith("--as=")) || markerNeedsDeclaration;
+let declaredInstances: ReturnType<typeof readInstanceConfig>["instances"];
+let nativeSelection: ReturnType<typeof instanceLaunchArguments>;
+try {
+  declaredInstances = needsInstances ? readInstanceConfig(cwd).instances : undefined;
+  nativeSelection = instanceLaunchArguments(given, rest, declaredInstances);
+} catch (error) { fail(startupDiagnostic(error)); }
+const selectedInstance = nativeSelection.instance;
+// `ahub <command> -h` alone asks for that command's help instead of running it. Elsewhere `-h` may be message text
+// (`ahub say try ls -h`), and claude and codex pass their arguments on to the agent.
+const asksHelp = (a: string | undefined) => a === "--help" || a === "-h";
+const cmd = asksHelp(given) || (definitionOf(given)?.start.passthrough !== true && nativeSelection.args.length === 1 && asksHelp(nativeSelection.args[0])) ? "help" : given;
+const args = cmd === "help" && given !== "help" && !asksHelp(given) ? [given] : nativeSelection.args;
+
+/** Resolve a named peer only against this project's current trusted declarations. */
+const peerDefinition = (peer: unknown) => typeof peer === "string"
+  ? definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(cwd).instances) : undefined;
+const requireNamedPeerFeature = (hub: ControlClient, peer: string | undefined) => {
+  if (peer !== undefined && !definitionOf(peer)) requirePeerInstances(hub.features);
+};
+
 /** The project config, saying on stderr which machine-local fields it had to ignore (issue #17). */
 const projectConfig = () => {
   const config = loadConfig(cwd);
@@ -126,7 +158,7 @@ const projectConfig = () => {
   return config;
 };
 const stateDir = selected.stateDir;
-const caller = detectCliIdentity(process.env);
+const caller = declaredInstances ? detectCliIdentity(process.env, declaredInstances) : unboundCaller;
 const commandLabel = cliCommandLabel(cmd, args);
 const commandAccess = classifyPeerCommand(cmd, args);
 // Agent-authored content keeps its peer. Operational starts/holds may borrow console authority for live verification.
@@ -216,49 +248,24 @@ async function healthy(): Promise<boolean> {
   finally { hub?.close(); }
 }
 
-function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi"): never {
-  const env = tool ? nativeLaunchEnv(tool, childEnv()) : childEnv();
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi", executionCwd = cwd): never {
+  const env = tool ? nativeLaunchEnv(selectedInstance ?? tool, childEnv(), declaredInstances) : childEnv();
+  const res = spawnSync(bin, argv, { cwd: executionCwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 
-function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never {
-  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv("pi", extra), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv, executionCwd = cwd): never {
+  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv(selectedInstance ?? "pi", extra, declaredInstances), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_UNATTENDED;
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env });
+  const res = spawnSync(bin, argv, { cwd: executionCwd, stdio: "inherit", env });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 
 /** `mode` is absent when no flag chose one: the caller takes the configured start mode (#269). `--headless` is `--mode headless`. */
-function piFlags(): { mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; model?: string; sessionId?: string; sessionFile?: string; replaceSession?: boolean } {
-  const usage = "usage: ahub pi [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id> | --session-file <path>] [--replace-session --session-file <path>]";
-  if (args.includes("--headless")) {
-    if (args.includes("--mode")) fail(usage);
-    args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
-  }
-  for (const flag of ["--mode", "--backend", "--model", "--session-id", "--session-file"]) {
-    const index = args.indexOf(flag);
-    if (index >= 0 && (!args[index + 1] || args[index + 1]!.startsWith("--"))) fail(`${flag} needs a value`);
-  }
-  const mode = (args.includes("--mode") ? args[args.indexOf("--mode") + 1] : undefined) as string | undefined;
-  const backend = (args.includes("--backend") ? args[args.indexOf("--backend") + 1] : undefined) as string | undefined;
-  const model = args.includes("--model") ? args[args.indexOf("--model") + 1] : undefined;
-  const sessionId = args.includes("--session-id") ? args[args.indexOf("--session-id") + 1] : undefined;
-  const sessionFile = args.includes("--session-file") ? args[args.indexOf("--session-file") + 1] : undefined;
-  const replaceSession = args.includes("--replace-session");
-  if (replaceSession && (!sessionFile || sessionId)) fail("--replace-session requires --session-file, without --session-id");
-  const valueFlags = new Set(["--mode", "--backend", "--model", "--session-id", "--session-file"]);
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--replace-session") continue;
-    if (!valueFlags.has(args[i]!)) fail(`unknown Pi option: ${args[i]}`);
-    i++;
-  }
-  if ((mode !== undefined && !["headless", "tui"].includes(mode)) || (backend !== undefined && !["auto", "dgx", "mlx"].includes(backend)) || (sessionId && sessionFile)) fail(usage);
-  return { ...(replaceSession ? { replaceSession: true } : {}), ...(mode ? { mode: mode as "headless" | "tui" } : {}), ...(backend ? { backend: backend as "auto" | "dgx" | "mlx" } : {}), ...(model ? { model } : {}), ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}) };
-}
+const piFlags = () => parsePiFlags(args, fail);
 
 async function projectRows() {
   const registry = new Registry();
@@ -349,6 +356,12 @@ async function orphanDoctor(kill: boolean, options: ReturnType<typeof outputOpti
   if (failed) fail(`${failed} orphaned hub process(es) could not be stopped`);
 }
 
+/** Startup refusals remain single-line and bounded even for malformed local declarations. */
+function startupDiagnostic(error: unknown): string {
+  const message = error instanceof Error ? error.message : "invalid startup configuration";
+  return message.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 512) || "invalid startup configuration";
+}
+
 function fail(message: string): never {
   console.error(`ahub: ${message}`);
   process.exit(1);
@@ -577,7 +590,10 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
 
 /** Strict person command: recorded identity only, no session or terminal overrides. */
 function parseRecoveryReattach(argv: readonly string[]): { id: string; peer: TerminalPeer } | undefined {
-  if (argv.length !== 3 || argv[0] !== "reattach" || !operationIdPattern.test(argv[1]!) || !["codex", "claude", "pi"].includes(argv[2]!)) return undefined;
+  if (argv.length !== 3 || argv[0] !== "reattach" || !operationIdPattern.test(argv[1]!) || !/^[a-z][a-z0-9-]{0,31}$/.test(argv[2]!)) return undefined;
+  const builtin = definitionOf(argv[2]!);
+  if (builtin && builtin.session.launchRecord !== true) return undefined;
+  // Extra peers are resolved against the operation's canonical project by the recovery core, never by suffix.
   return { id: argv[1]!, peer: argv[2] as TerminalPeer };
 }
 
@@ -827,220 +843,29 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--no-console")) await runConsole({ client: await connect(), cwd, stateDir, liveTest });
   },
 
-  claude: async () => {
-    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)"); }
-    }
-    assertLifecycleAvailable();
-    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(import.meta.dir, "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(import.meta.dir, "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);
-  },
-
-  codex: async () => {
-    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)"); }
-    }
-    assertLifecycleAvailable();
-    const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, 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);
-    if (recovering && before?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, before.instanceId);
-    const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "codex", args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
-    hub.close();
-    if (!res.ok) fail(res.error);
-    const control = readControl(stateDir);
-    if (!recovering && control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
-    const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
-    if (launch0.warning) console.error(launch0.warning);
-    exec(launch.cmd, launch.args, "codex");
-  },
-
-  jcode: async () => {
-    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)"); }
-    }
-    assertLifecycleAvailable();
-    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;
-      if (snapshot?.roster?.find((row: any) => row.peer === "jcode")?.on !== true) fail("jcode is off roster; add it with ahub roster add jcode");
-      const written = configureJcodeMcp(cwd, stateDir, resolve(import.meta.dir, "../../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(); }
-  },
-
-  qwen: async () => {
-    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)"); }
-    }
-    assertLifecycleAvailable();
-    const { one, rest } = takeFlags(args, ["--mode", "--model", "--session-id"], []);
-    const adapter = definitionOf("qwen")!;
-    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: "qwen", 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 ? "qwen is already attached" : "qwen attached (headless); use ahub say @qwen and the console for approvals");
-    } finally { hub.close(); }
-  },
-  kimi: async () => {
-    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)"); }
-    }
-    assertLifecycleAvailable();
-    const { one, rest } = takeFlags(args, ["--mode", "--model"], []);
-    const mode = one["--mode"] ?? startModeOf(projectConfig().peers, "kimi"), model = one["--model"];
-    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: "kimi" }, 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;
-        if (snapshot?.roster?.find((row: any) => row.peer === "kimi")?.on === false) fail("kimi is off roster; add it with ahub roster add kimi");
-        const peer = snapshot?.peers?.kimi;
-        if (peer && !["offline"].includes(peer.state) && !peer.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
-        const admission = await hub.request({ t: "start", peer: "kimi", 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(import.meta.dir, "../../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 peer = (await hub.request({ t: "status" })).status?.peers?.kimi;
-      if (peer?.pullOnly && peer.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
-      configureKimiMcp(cwd, stateDir, resolve(import.meta.dir, "../../plugins/agent-hub/server.js"), "headless");
-      const res = await hub.request({ t: "start", peer: "kimi", args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
-      if (!res.ok) fail(res.error);
-      console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
-    } finally { hub.close(); }
-  },
-
-  pi: async () => {
-    // --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 = piFlags();
-    // #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 ?? startModeOf(projectConfig().peers, "pi") };
-    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");
+  ...Object.fromEntries(BUILTIN_CLI_ENTRIES.map(entry => [entry.command, async () => {
+    // Preserve the original guard before native effects; previews remain read-only and precede this guard.
+    if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable();
+    const nativeConnect = async () => {
       const hub = await connect();
-      try {
-        const reply = await hub.request({ t: "peer_start", peer: "pi" }, 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("pi", cwd, stateDir, before.instanceId);
-    const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "pi", 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("pi", cwd, stateDir, control.instanceId);
-      return execWithEnv(launch.cmd, launch.args, launchEnv);
-    }
-    console.log(res.already ? "pi is already attached" : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
-  },
-
-  local: async () => {
-    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: "local", 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 ? "local is already attached" : `local attached on ${res.model}. Give it work with: ahub say @local "..."`);
-  },
+      try { if (selectedInstance) requirePeerInstances(hub.features); return hub; }
+      catch (error) { hub.close(); throw error; }
+    };
+    if (selectedInstance && !args.includes("--print-command") && !args.includes("--dry-run")) {
+      const hub = await nativeConnect(); hub.close();
+    }
+    const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, definition: entry.definition,
+      ...(selectedInstance ? { instance: selectedInstance } : {}),
+      projectConfig, connect: nativeConnect, fail,
+      exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
+      execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, context.executionCwd), takeFlags,
+      helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, recoveryLock, processSignature,
+        buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
+        nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,
+        buildKimiTuiLaunch, startModeOf },
+    };
+    return entry.execute(context);
+  }])),
 
   models: async () => {
     const action = outputArguments()[0] ?? "status";
@@ -1125,7 +950,7 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   watch: async () => {
     const peer = args[0];
-    if (typeof peer !== "string" || !definitionOf(peer)?.capabilities?.watch) fail("usage: ahub watch kimi|qwen [--no-thoughts] [--color=auto|always|never]");
+    if (typeof peer !== "string" || !peerDefinition(peer)?.capabilities?.watch) fail("usage: ahub watch kimi|qwen [--no-thoughts] [--color=auto|always|never]");
     if (args.slice(1).some(arg => arg !== "--no-thoughts" && !/^--color=(auto|always|never)$/.test(arg))) fail("unsupported watch option");
     const color = resolveColor(args.find(arg => arg.startsWith("--color="))?.slice(8), { isTTY: !!process.stdout.isTTY, ...process.env });
     if (color instanceof Error) fail(color.message);
@@ -1430,9 +1255,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   roster: async () => {
     const options = outputOptions(), flags = args.filter(arg => arg.startsWith("--")), positional = outputArguments().filter(arg => arg !== "--yes" && arg !== "--now");
     const [sub = "list", peer, ...extra] = positional;
-    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !isSupportedPeer(peer)) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
+    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !peerDefinition(peer)) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
     const hub = await connect();
     try {
+      requireNamedPeerFeature(hub, peer);
       const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused")); return reply; };
       if (sub === "list") {
         const view = await request({ t: "settings_get" });
@@ -1793,7 +1619,22 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (!turn.ended) fail(`turn ${id} is still running`);
     const { start_tree: startTree, end_tree: endTree } = turn;
     if (!startTree || !endTree) fail(`turn ${id} has no ${startTree ? "end" : "start"} snapshot: the hub stopped during it, or a snapshot failed (see hub.log)`);
-    const repo = repoOf(cwd) ?? fail(`${cwd} is not in a git work tree`);
+    const recordedWorkspace = turnRecords(t => t.workspace(id), undefined);
+    const undoWorkspace = (): string => {
+      // Old turns, including external peers and ids declared only later, belong to the canonical checkout.
+      if (recordedWorkspace === undefined) return cwd;
+      const declarations = readInstanceConfig(cwd).instances;
+      if (!declarations || !Object.hasOwn(declarations, turn.peer)) fail(`turn ${id}'s recorded instance is no longer declared; nothing was restored`);
+      const config = projectConfig();
+      const current = resolveInstanceExecutionCwd(cwd, turn.peer, declarations, effectiveInstanceRoles(turn.peer, declarations, config.roles));
+      if (realPath(current) !== realPath(recordedWorkspace)) fail(`turn ${id}'s recorded execution workspace changed; nothing was restored`);
+      return current;
+    };
+    const undoCwd = undoWorkspace();
+    const requireUndoWorkspace = () => {
+      if (realPath(undoWorkspace()) !== realPath(undoCwd)) fail(`turn ${id}'s execution workspace changed; nothing was restored`);
+    };
+    const repo = repoOf(undoCwd) ?? fail(`${undoCwd} is not in a git work tree`);
     if (!hasTree(repo, startTree) || !hasTree(repo, endTree)) fail(`turn ${id}'s snapshots are gone from the git object store (git gc prunes them after two weeks)`);
     // Another peer's turn that overlapped this one in time has its changes in this turn's diff as well.
     const undoConfig = projectConfig();
@@ -1815,11 +1656,12 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (first.undone) return console.log(`turn ${id} is already undone: its files are as they were before it started`);
     console.log(first.restore.length ? `turn ${id} changed:\n  ${first.restore.join("\n  ")}` : `turn ${id} changed no files`);
     console.log("(every change made in the project during the turn counts as its own, including any by Claude or by you)");
-    const projections = new TextProjections({ cwd, stateDir, config: undoConfig.text_projection ?? {}, deny: undoConfig.local.deny, readAllow: undoConfig.local.read_allow, log: line => console.error(line) });
-    const preview = projectedDiff({ repo, from: endTree, to: startTree, paths: first.restore, projections, deny: undoConfig.local.deny, privatePath: path => matchesPolicy(cwd, join(repo.top, path), undoConfig.pii?.paths ?? []) });
+    const projections = new TextProjections({ cwd: undoCwd, stateDir, config: undoConfig.text_projection ?? {}, deny: undoConfig.local.deny, readAllow: undoConfig.local.read_allow, log: line => console.error(line) });
+    const preview = projectedDiff({ repo, from: endTree, to: startTree, paths: first.restore, projections, deny: undoConfig.local.deny, privatePath: path => matchesPolicy(undoCwd, join(repo.top, path), undoConfig.pii?.paths ?? []) });
     if (preview) console.log(terminalText("Undo preview (end snapshot to start snapshot):\n" + preview));
 
     if (!args.includes("--yes")) return console.log("nothing was changed; add --yes to restore these files");
+    requireUndoWorkspace();
     if (args.includes("--context")) {
       console.log(await taskOp("turn_revert", { turn: id }));
       reverted = true;
@@ -1827,6 +1669,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     // A peer may have written meanwhile (the revert alone can take seconds): plan again right before restoring.
     const second = plan();
     if (second.restore.join("\0") !== first.restore.join("\0")) fail(`the project changed while undoing; nothing was restored, run ahub undo again${reverted ? " without --context (Codex's conversation was already reverted)" : ""}`);
+    requireUndoWorkspace();
     restore(repo, startTree, second.restore);
     if (second.restore.length) console.log(`restored to their state before ${id}`);
   },
@@ -1934,9 +1777,10 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (["assign", "clear"].includes(args[0] ?? "")) {
       const [op, peer, id] = args;
-      if (!peer || !isSupportedPeer(peer) || !id && op === "assign" || args.length > 3) fail("usage: ahub role assign <peer> <id> | clear <peer> [<id>]");
+      if (!peer || !peerDefinition(peer) || !id && op === "assign" || args.length > 3) fail("usage: ahub role assign <peer> <id> | clear <peer> [<id>]");
       const hub = await connect();
       try {
+        requireNamedPeerFeature(hub, peer);
         const view = await hub.request({ t: "settings_get" }); if (!view.ok) fail(view.error);
         const row = (view.rows as SettingRow[]).find(row => row.key === `catalog_roles.${peer}`); if (!row) fail("this hub does not support catalog role settings");
         const current = Array.isArray(row!.pending) ? row!.pending : Array.isArray(row!.value) ? row!.value : [];
@@ -1955,15 +1799,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       return res.status === 0 ? res.stdout.trim().split("\n")[0]! : undefined;
     };
     const checks: DoctorCheck[] = [];
-    const row = (ok: boolean | undefined, name: string, detail: string) => {
-      const section: DoctorCheck["section"] = ["bun", "claude", "codex", "kimi", "qwen", "jcode"].includes(name) ? "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 = ["claude", "codex", "kimi", "qwen", "jcode", "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";
-      checks.push({ section, level, name, detail });
-    };
+    const row = (ok: boolean | undefined, name: string, detail: string) => { checks.push(nativeDoctorCheck(ok, name, detail)); };
 
     try {
       const catalog = loadRoleCatalog(cwd);
@@ -1972,7 +1808,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         const config = loadConfig(cwd), assigned = catalogAssignments(config.catalog_roles);
         for (const peer of Object.keys(assigned)) selectedRoles(peer, config.roles, assigned, catalog);
       } catch { row(false, "catalog roles", "invalid assignment id, shape or flow base"); }
-      for (const bin of ["bun", "claude", "codex", "kimi"]) {
+      for (const bin of DOCTOR_TOOL_PROBES) {
         const v = version(bin);
         row(!!v, bin, v ?? "not found on PATH");
       }
@@ -1986,26 +1822,24 @@ const commands: Record<string, () => Promise<void> | void> = {
           row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
           const observed = await hub.request({ t: "recovery", op: "inspect", expectedInstanceId: status.instanceId });
           for (const peer of Object.values(observed.recovery?.peers ?? {}) as { id: string; state: string; sessionId?: string; threadId?: string }[]) {
-            if (!["claude", "codex"].includes(peer.id) || peer.state === "offline") continue;
-            const identity = peer.id === "claude" ? peer.sessionId : peer.threadId;
-            row(!!identity, `${peer.id} recovery ID`, identity ? "recorded" : `missing; verify the current conversation and reconnect with ahub ${peer.id} before upgrading`);
+            const check = nativeDoctorRecoveryIdentity(peer);
+            if (check) row(check.ok, check.name, check.detail);
           }
         } finally { hub.close(); }
       }
-      const plugin = pluginState(parseList<InstalledPlugin>(spawnSync("claude", ["plugin", "list", "--json"], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
-      row(plugin.state === "current", "claude plugin", plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
+      const plugin = pluginState(parseList<InstalledPlugin>(spawnSync(DOCTOR_PLUGIN_PROBE.command, [...DOCTOR_PLUGIN_PROBE.argv], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
+      row(plugin.state === "current", DOCTOR_PLUGIN_PROBE.name, plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
 
       const config = loadConfig(cwd);
       row(!config.ignored, "config", config.ignored ? `${config.ignored.join("; ")} (move them to .agenthub/config.local.json)` : "no machine-local field ignored");
       for (const line of config.retired ?? []) row(false, "retired setting", line);
-      if (config.roster.jcode === true) {
-        row(verifiedJcodeCommand(config.jcode_cmd, cwd), "jcode", "CLI/source identity only; provider, project MCP and native teardown require separate receipts; native policy unmanaged");
+      for (const probe of nativeDoctorOptionalProbes(config)) {
+        if (probe.kind === "source-identity") row(verifiedJcodeCommand(probe.command, cwd), probe.name, probe.detail);
+        else {
+          const v = version(probe.command[0]!);
+          row(v === probe.expected, probe.name, v === probe.expected ? probe.confirmed : probe.unconfirmed);
+        }
       }
-      if (config.roster.qwen === true) {
-        // ponytail: keep this bounded CLI-version probe and 0.25.0 pin in the A1 guard baseline; A2 moves every version probe together when VersionContext gains its observed input.
-        const v = version(config.qwen_cmd[0]!);
-        row(v === "0.25.0", "qwen", v === "0.25.0" ? "CLI reports 0.25.0; native ACP identity/modes and provider access require a separate live check" : "Qwen Code 0.25.0 executable not confirmed; provider and ACP readiness unknown");
-      } // issue #83
       const omni = new OmniRoute(config.omniroute);
       const gateway = await omni.base();
       row(gateway ? true : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? false : undefined, "omniroute", gateway ? `${new URL(gateway).host} healthy` : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? "no candidate reachable (VPN off?); ahub local cannot run" : "not configured: set omniroute.urls in .agenthub/config.local.json (any OpenAI-compatible gateway); ahub local cannot run");
@@ -2031,7 +1865,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       row(mem.ok, "memory worker", mem.ok ? `claude-mem ${mem.version ?? ""} at ${memory.url}` : `unavailable at ${memory.url} (the hub works without it)`);
       const bridge = spawnSync("dot", ["ai", "memory", "status"], { encoding: "utf8" });
       const out = bridge.error ? "" : bridge.stdout.replace(/\x1b\[[0-9;]*m/g, "");
-      for (const tool of ["codex", "kimi"]) {
+      for (const tool of DOCTOR_MEMORY_CAPTURE_PEERS) {
         const ready = new RegExp(`✓\\s+${tool} ready`).test(out);
         row(bridge.error ? undefined : ready, `memory capture: ${tool}`, bridge.error ? "unknown (`dot ai memory status` not available)" : `${ready ? "ready" : "not ready"}, per ` + "`dot ai memory status`");
       }
@@ -2058,12 +1892,14 @@ async function runConductorCommand(): Promise<void> {
     input = { peer: args[0] };
   } else {
     // Native TUIs return a human launch command through the daemon; an agent shell never executes it.
-    if (cmd === "pi" && args.length === 1 && args[0] === "--headless") args.splice(0, 1, "--mode", "headless");
-    if (args.length && !(cmd === "pi" && args.length === 2 && args[0] === "--mode" && ["headless", "tui"].includes(args[1] ?? ""))) fail(`conductor starts accept no launch overrides; use ahub ${cmd}${cmd === "pi" ? " [--mode headless|tui]" : ""}`);
+    const parseStart = definitionOf(cmd)?.start.conductorStartArgs;
+    const parsed = parseStart ? parseStart(args) : args.length ? new Error(`conductor starts accept no launch overrides; use ahub ${cmd}`) : {};
+    if (parsed instanceof Error) fail(parsed.message);
     op = "hub_peer_start";
     // #269: a mode may only repeat the peer's start mode, which a person sets; without one the hub takes that mode.
-    input = { peer: cmd, ...(cmd === "pi" && args[1] ? { mode: args[1] } : {}) };
+    input = { peer: selectedInstance ?? cmd, ...parsed };
   }
+  if (selectedInstance) { const hub = await connect(); try { requirePeerInstances(hub.features); } finally { hub.close(); } }
   console.log(await taskOp(op, input));
 }
 const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? (() => fail(`unknown command "${cmd}"; run ahub help`));