@phnx-labs/agents-cli 1.20.29 → 1.20.30

package/dist/commands/sync.js

@@ -30,7 +30,7 @@
 import * as path from 'path';
 import chalk from 'chalk';
 import { agentLabel, resolveAgentName } from '../lib/agents.js';
-import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, } from '../lib/versions.js';
+import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildRepoScopedSelection, listRepoNames, } from '../lib/versions.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -38,11 +38,12 @@ import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
     program
-        .command('sync [agentSpec]')
+        .command('sync [agentSpec] [repo]')
         .summary('Make this machine current, or sync resources into one agent')
-        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", or a selector: @latest / @oldest / @pinned (= @default).\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
+        .option('--repo <name>', 'Scope the sync to a single DotAgent repo: system / user / project / <alias> (also accepted as a positional)')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
         .option('--cwd <path>', 'Working directory for discovering project manifest and resources')
         .option('--launch', 'Hot-path mode (shim only): skip version-home reconciliation, run project-scoped compile + workspace mirror + plugin marketplaces', false)
@@ -55,8 +56,8 @@ export function registerSyncCommand(program) {
         .option('--sessions', 'Umbrella: sync session transcripts across machines', false)
         .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
         .option('--local', "Umbrella: reconcile resources into installed agents only (no fetch)", false)
-        .action(async (agentSpec, opts) => {
-        await runSync(agentSpec, opts);
+        .action(async (agentSpec, repo, opts) => {
+        await runSync(agentSpec, repo, opts);
     });
 }
 /**
@@ -109,7 +110,7 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
         process.exitCode = 1;
     }
 }
-async function runSync(agentSpec, opts) {
+async function runSync(agentSpec, repoArg, opts) {
     const quiet = !!opts.quiet;
     const errLog = (msg) => { if (!quiet)
         console.error(msg); };
@@ -119,16 +120,17 @@ async function runSync(agentSpec, opts) {
     let agentId;
     let version;
     // A positional @selector typed by the user (latest/oldest/pinned/default/
-    // explicit). parseAgentSpec defaults a missing version to 'latest', so a bare
-    // `agents sync claude` and `agents sync claude@latest` are indistinguishable
-    // after parsing — we only treat the version as a selector when an '@' was
-    // actually typed, keeping bare `claude` on the default-version path.
+    // all/explicit). parseAgentSpec defaults a missing version to 'latest', so a
+    // bare `agents sync claude` and `agents sync claude@latest` are
+    // indistinguishable after parsing — we only treat the version as a selector
+    // when an '@' was actually typed, keeping bare `claude` on the
+    // default-version path.
     let selector;
     if (agentSpec) {
         const parsed = parseAgentSpec(agentSpec);
         if (!parsed) {
             errLog(chalk.red(`Invalid agent spec '${agentSpec}'.`));
-            errLog(chalk.gray('Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned'));
+            errLog(chalk.gray('Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned, claude@all'));
             process.exitCode = 1;
             return;
         }
@@ -136,6 +138,18 @@ async function runSync(agentSpec, opts) {
         if (agentSpec.includes('@'))
             selector = parsed.version;
     }
+    // Repo scope: --repo flag wins over the positional. Validate against the
+    // known DotAgent repos so a typo fails loudly instead of syncing nothing.
+    const repoScope = opts.repo || repoArg;
+    if (repoScope !== undefined) {
+        const known = listRepoNames();
+        if (!known.includes(repoScope)) {
+            errLog(chalk.red(`Unknown repo '${repoScope}'.`));
+            errLog(chalk.gray(`Known repos: ${known.join(', ')}`));
+            process.exitCode = 1;
+            return;
+        }
+    }
     if (opts.agent) {
         const resolved = resolveAgentName(opts.agent);
         if (!resolved) {
@@ -156,6 +170,37 @@ async function runSync(agentSpec, opts) {
         await runUmbrella(opts, quiet, outLog, errLog);
         return;
     }
+    const projectDir = opts.projectDir;
+    const cwd = opts.cwd || process.cwd();
+    const force = !!opts.force;
+    // ---------- 2a. @all: reconcile every installed version of this agent ----------
+    // Non-interactive by design — fanning an interactive preview across N
+    // versions is unusable. Honors an optional repo scope.
+    if (selector === 'all') {
+        const installed = listInstalledVersions(agentId);
+        if (installed.length === 0) {
+            errLog(chalk.red(`No ${agentLabel(agentId)} versions installed.`));
+            errLog(chalk.gray(`Install one: agents add ${agentId}@latest`));
+            process.exitCode = 1;
+            return;
+        }
+        let selection;
+        if (repoScope) {
+            selection = buildRepoScopedSelection(repoScope, cwd);
+            if (Object.keys(selection).length === 0) {
+                outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync.`));
+                return;
+            }
+        }
+        const scopeLabel = repoScope ? chalk.gray(` (repo: ${repoScope})`) : '';
+        outLog(chalk.cyan(`Syncing ${installed.length} ${agentLabel(agentId)} version(s)${scopeLabel}.`));
+        for (const v of installed) {
+            const result = syncResourcesToVersion(agentId, v, selection, { projectDir, cwd, force });
+            if (!quiet)
+                printSyncDetail(result, agentId, v, cwd);
+        }
+        return;
+    }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------
     // A positional @selector wins over the default-resolution below.
     //   @latest / @oldest        → newest / oldest installed (process.exit if none)
@@ -197,15 +242,26 @@ async function runSync(agentSpec, opts) {
         process.exitCode = 1;
         return;
     }
-    const projectDir = opts.projectDir;
-    const cwd = opts.cwd || process.cwd();
     // ---------- 3. --launch mode bypasses everything below ----------
     if (opts.launch) {
         runLaunchMode(agentId, version, cwd, quiet);
         return;
     }
+    // ---------- 3b. Repo-scoped single-version sync ----------
+    // An explicit --repo / positional repo is a targeted request, so skip the
+    // interactive preview and reconcile just that repo's resources.
+    if (repoScope) {
+        const scoped = buildRepoScopedSelection(repoScope, cwd);
+        if (Object.keys(scoped).length === 0) {
+            outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync into ${agentLabel(agentId)}@${version}.`));
+            return;
+        }
+        const result = syncResourcesToVersion(agentId, version, scoped, { projectDir, cwd, force });
+        if (!quiet)
+            printSyncDetail(result, agentId, version, cwd);
+        return;
+    }
     // ---------- 4. Decide selection (interactive preview vs auto) ----------
-    const force = !!opts.force;
     const yes = !!opts.yes;
     const interactive = !quiet && !yes && isInteractiveTerminal();
     let selection;

package/dist/lib/agents.d.ts

@@ -111,10 +111,6 @@ export interface AccountInfo {
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
-/**
- * Extract full account information (identity, plan, usage status, credits) from
- * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
- */
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -410,6 +410,7 @@ export const AGENTS = {
         npmPackage: '',
         installScript: 'curl -fsSL https://antigravity.google/cli/install.sh | bash',
         configDir: path.join(HOME, '.gemini', 'antigravity-cli'),
+        authFiles: ['antigravity-oauth-token'],
         commandsDir: path.join(HOME, '.gemini', 'antigravity-cli', 'commands'),
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.gemini', 'antigravity-cli', 'skills'),
@@ -470,6 +471,7 @@ export const AGENTS = {
         npmPackage: '@moonshot-ai/kimi-code',
         installScript: 'curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash',
         configDir: path.join(HOME, '.kimi-code'),
+        authFiles: ['credentials/kimi-code.json'],
         commandsDir: '',
         commandsSubdir: '',
         skillsDir: path.join(HOME, '.kimi-code', 'skills'),
@@ -494,7 +496,8 @@ export const AGENTS = {
     },
     // Factory AI Droid CLI (`droid`) — agentic coding CLI from factory.ai.
     // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
-    // Binary is NOT in node_modules/.bin — resolved via resolveDroidBinary().
+    // Binary is NOT in node_modules/.bin — the shim resolves the fixed install
+    // path ~/.local/bin/droid directly (see the droid branch in shims.ts).
     // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/).
     // Memory: native AGENTS.md. Subagents = custom droids (top-level .md files
     // in ~/.factory/droids/). Config isolation rides the ~/.factory symlink
@@ -508,6 +511,7 @@ export const AGENTS = {
         npmPackage: '',
         installScript: 'curl -fsSL https://app.factory.ai/cli | sh',
         configDir: path.join(HOME, '.factory'),
+        authFiles: ['auth.v2.file', 'auth.v2.key'],
         commandsDir: path.join(HOME, '.factory', 'commands'),
         commandsSubdir: 'commands',
         skillsDir: '', // no skills concept
@@ -707,6 +711,7 @@ export const UNMANAGED_DETECTION_CANDIDATES = [
     'gemini',
     'grok',
     'copilot',
+    'droid',
 ];
 /**
  * Detect existing agent installations that are NOT yet managed by agents-cli.
@@ -770,6 +775,33 @@ export async function getAccountEmail(agentId, home) {
  * Extract full account information (identity, plan, usage status, credits) from
  * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
  */
+/**
+ * Resolve a file-auth agent's credential file. Sign-in is account-global, but
+ * each installed version gets an isolated home; the credential physically lives
+ * only in the home the user logged in under (the one the `~/.<config>` symlink
+ * targets). Check the per-version `base` first, then fall back to the active
+ * config location under the real HOME so every installed version reflects the
+ * true account state (droid/antigravity/kimi all stored login per-version-home
+ * and showed non-active versions as "not signed in"). Returns the first
+ * existing path, or null.
+ */
+function resolveAccountCredentialPath(base, ...segments) {
+    const perVersion = path.join(base, ...segments);
+    try {
+        if (fs.existsSync(perVersion))
+            return perVersion;
+    }
+    catch { /* unreadable */ }
+    const active = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...segments);
+    if (active !== perVersion) {
+        try {
+            if (fs.existsSync(active))
+                return active;
+        }
+        catch { /* unreadable */ }
+    }
+    return null;
+}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -924,8 +956,8 @@ export async function getAccountInfo(agentId, home) {
                 // OAuth grant (access + refresh token, no id_token), so there's no email
                 // claim to read locally — presence of a refresh token is the only
                 // signed-in signal we can derive without a network call.
-                const tokenPath = path.join(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
-                if (!fs.existsSync(tokenPath))
+                const tokenPath = resolveAccountCredentialPath(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
+                if (!tokenPath)
                     return { ...empty, lastActive };
                 const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));
                 const hasToken = typeof data?.token?.refresh_token === 'string' && !!data.token.refresh_token;
@@ -938,8 +970,8 @@ export async function getAccountInfo(agentId, home) {
                 // ~/.kimi-code/credentials/kimi-code.json. The access token is a JWT
                 // whose payload carries an opaque user_id (no email), so we report
                 // signed-in state plus a stable account key for usage dedup.
-                const credPath = path.join(base, '.kimi-code', 'credentials', 'kimi-code.json');
-                if (!fs.existsSync(credPath))
+                const credPath = resolveAccountCredentialPath(base, '.kimi-code', 'credentials', 'kimi-code.json');
+                if (!credPath)
                     return { ...empty, lastActive };
                 const data = JSON.parse(await fs.promises.readFile(credPath, 'utf-8'));
                 const accessToken = data?.access_token;
@@ -950,6 +982,18 @@ export async function getAccountInfo(agentId, home) {
                 const accountKey = buildIdentityKey(agentId, [['user', userId]]);
                 return { ...empty, signedIn: true, accountId: userId, accountKey, lastActive };
             }
+            case 'droid': {
+                // Factory Droid stores auth at ~/.factory/auth.v2.file (+ auth.v2.key,
+                // an encrypted blob). No email/JWT is readable locally, so presence of
+                // the auth file is the only signed-in signal we can derive without a
+                // network call — same pattern as antigravity/kimi. `.factory` is the
+                // config dir on every platform (macOS/Linux ~/.factory, Windows
+                // %USERPROFILE%\.factory), so path.join keeps this cross-platform.
+                const authPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
+                if (!authPath)
+                    return { ...empty, lastActive };
+                return { ...empty, signedIn: true, lastActive };
+            }
             default:
                 return { ...empty, lastActive };
         }
@@ -1051,6 +1095,8 @@ function getSessionDir(agentId, base) {
             // Copilot persists sessions at ~/.copilot/session-state/<id>/events.jsonl.
             // The events.jsonl is the canonical NDJSON event stream per session.
             return path.join(base, '.copilot', 'session-state');
+        case 'droid':
+            return path.join(base, '.factory', 'sessions');
         default:
             return null;
     }
@@ -1061,6 +1107,7 @@ function getSessionExtension(agentId) {
         case 'claude':
         case 'codex':
         case 'copilot':
+        case 'droid':
             return '.jsonl';
         case 'gemini':
             return '.json';
@@ -1661,6 +1708,8 @@ export const AGENT_NAME_ALIASES = {
     gk: 'grok',
     kimi: 'kimi',
     'kimi-code': 'kimi',
+    factory: 'droid',
+    'factory-ai': 'droid',
 };
 /**
  * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.

package/dist/lib/browser/drivers/ssh.js

@@ -8,6 +8,10 @@ import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // so existing importers of `shellQuote` from this module keep working.
 import { shellQuote } from '../../ssh-exec.js';
 export { shellQuote };
+// The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
+// the single ssh-tunnel helper. Calling it with no options preserves this
+// driver's original foreground, stderr-captured behavior exactly.
+import { startSSHTunnel } from '../../ssh-tunnel.js';
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
@@ -102,41 +106,6 @@ export async function connectSSH(endpoint, profile) {
         },
     };
 }
-function startSSHTunnel(user, host, localPort, remotePort) {
-    return new Promise((resolve, reject) => {
-        const args = [
-            '-L',
-            `${localPort}:127.0.0.1:${remotePort}`,
-            `${user}@${host}`,
-            '-N',
-            '-o',
-            'StrictHostKeyChecking=accept-new',
-            '-o',
-            'BatchMode=yes',
-            '-o',
-            'ConnectTimeout=10',
-        ];
-        const tunnel = spawn('ssh', args, {
-            stdio: ['ignore', 'ignore', 'pipe'],
-            detached: false,
-        });
-        let stderr = '';
-        tunnel.stderr?.on('data', (data) => {
-            stderr += data.toString();
-        });
-        tunnel.on('error', (err) => {
-            reject(new Error(`SSH tunnel failed: ${err.message}`));
-        });
-        setTimeout(() => {
-            if (tunnel.killed) {
-                reject(new Error(`SSH tunnel died: ${stderr}`));
-            }
-            else {
-                resolve(tunnel);
-            }
-        }, 500);
-    });
-}
 async function waitForPort(port, timeoutMs) {
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {

package/dist/lib/computer-rpc.d.ts

@@ -20,10 +20,15 @@ export declare function loadDefaultPeers(): string[];
 export declare function writeComputerPeers(allowedExecPaths: string[]): void;
 export declare function resolveHelperExec(): string | null;
 export declare function resolveHelperApp(): string | null;
+export declare function resolveTcpEndpoint(): {
+    host: string;
+    port: number;
+    token: string | null;
+} | null;
 export declare function openComputerClient(): ComputerClient;
 export declare const RPC_TIMEOUT_MS = 30000;
 export declare function resolveRpcTimeoutMs(env: string | undefined): number;
 export declare function describeTransport(): {
-    kind: 'socket' | 'stdio' | 'none';
+    kind: 'socket' | 'stdio' | 'tcp' | 'none';
     path: string | null;
 };

package/dist/lib/computer-rpc.js

@@ -187,9 +187,31 @@ export function resolveHelperApp() {
     // exec = <bundle>/Contents/MacOS/ComputerHelper
     return path.resolve(exec, '..', '..', '..');
 }
-// Pick the best transport. If the socket exists, use it. Otherwise fall
-// back to spawning the helper as a subprocess (legacy path).
+// Resolve the TCP endpoint for the Windows daemon (computer-helper-win), if
+// configured. The Windows helper binds loopback TCP (Program.cs) and the CLI
+// reaches it over an `ssh -L` tunnel, so the endpoint is a local forwarded
+// port. COMPUTER_HELPER_TCP is "host:port" (host defaults to 127.0.0.1);
+// COMPUTER_HELPER_TOKEN is the shared secret sent in the first `auth` frame.
+export function resolveTcpEndpoint() {
+    const raw = process.env.COMPUTER_HELPER_TCP;
+    if (!raw || raw.length === 0)
+        return null;
+    const [hostPart, portPart] = raw.includes(':') ? raw.split(':') : ['127.0.0.1', raw];
+    const port = Number(portPart);
+    if (!Number.isInteger(port) || port <= 0)
+        return null;
+    const token = process.env.COMPUTER_HELPER_TOKEN;
+    return { host: hostPart || '127.0.0.1', port, token: token && token.length > 0 ? token : null };
+}
+// Pick the best transport. Precedence:
+//   1. COMPUTER_HELPER_TCP -> the Windows daemon over a (tunneled) TCP port.
+//   2. the macOS launchd socket if it exists.
+//   3. spawning the helper as a subprocess (legacy/dev fallback).
 export function openComputerClient() {
+    const tcp = resolveTcpEndpoint();
+    if (tcp) {
+        return new TcpClient(tcp.host, tcp.port, tcp.token);
+    }
     const sockPath = resolveSocketPath();
     if (fs.existsSync(sockPath)) {
         return new SocketClient(sockPath);
@@ -297,6 +319,61 @@ class SocketClient extends BaseClient {
         });
     }
 }
+// TCP transport for the Windows daemon (computer-helper-win). The daemon
+// binds loopback only (Program.cs); the CLI reaches it over an `ssh -L`
+// tunnel, so `host` is typically 127.0.0.1 + a forwarded port. When a token
+// is configured the daemon accepts only an `auth` frame until authenticated,
+// so we send that first and gate every other call on it.
+class TcpClient extends BaseClient {
+    sock;
+    authReady;
+    constructor(host, port, token) {
+        super();
+        this.sock = createConnection({ host, port });
+        this.sock.setEncoding('utf8');
+        this.sock.on('data', (chunk) => this.handleChunk(chunk));
+        this.sock.on('error', (err) => {
+            this.closed = true;
+            this.failPending('socket_error', err.message);
+        });
+        this.sock.on('close', () => {
+            this.closed = true;
+            this.failPending('helper_exited', 'tcp connection closed before reply');
+        });
+        // Kick off the auth handshake synchronously so its frame (id 1) is the
+        // first thing written. No token → daemon is open (tunnel-gated).
+        this.authReady = token ? this.authenticate(token) : Promise.resolve();
+    }
+    async authenticate(token) {
+        const res = await super.call('auth', { token });
+        if (res.error)
+            throw new Error(`computer-helper auth failed: ${res.error.code}`);
+    }
+    async call(method, params) {
+        if (method !== 'auth') {
+            try {
+                await this.authReady;
+            }
+            catch (e) {
+                return { id: null, error: { code: 'auth_failed', message: e.message } };
+            }
+        }
+        return super.call(method, params);
+    }
+    send(payload) {
+        this.sock.write(payload);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.sock.end();
+        await new Promise((resolve) => {
+            if (this.closed)
+                return resolve();
+            this.sock.on('close', () => resolve());
+        });
+    }
+}
 class StdioClient extends BaseClient {
     proc;
     constructor(helperPath) {
@@ -324,8 +401,14 @@ class StdioClient extends BaseClient {
     }
 }
 // Describe which transport is currently in use. Useful for diagnostics
-// like `agents computer status`.
+// like `agents computer status`. TCP takes precedence to match
+// openComputerClient() — when COMPUTER_HELPER_TCP is set we drive a remote
+// (Windows) daemon over a tunnel, so callers off macOS (no socket, no local
+// .app) must not be told "no transport". `path` is null: the endpoint is an
+// env-configured host:port, not an on-disk path.
 export function describeTransport() {
+    if (resolveTcpEndpoint())
+        return { kind: 'tcp', path: null };
     const sockPath = resolveSocketPath();
     if (fs.existsSync(sockPath))
         return { kind: 'socket', path: sockPath };

package/dist/lib/exec.js

@@ -534,6 +534,20 @@ export function buildExecCommand(options) {
             cmd.push('--dangerously-bypass-approvals-and-sandbox');
         }
     }
+    else if (options.agent === 'kimi' && !interactive) {
+        // kimi's headless prompt mode (`-p`/`--prompt`) is self-contained and REFUSES
+        // to be combined with any startup-mode flag: `--plan`, `--auto`, and `--yolo`
+        // all abort with "Cannot combine --prompt with --X" (verified against the live
+        // kimi CLI). The write-capable modes (edit/auto/skip) all collapse to kimi's
+        // default `-p` behavior, which already auto-approves tool calls, so we emit no
+        // mode flag. Plan (read-only) has no headless equivalent, so fail closed rather
+        // than silently letting a plan-mode run mutate the workspace.
+        if (resolvedMode === 'plan') {
+            throw new Error('kimi has no headless read-only mode: `--prompt` cannot be combined with `--plan`. ' +
+                'Run kimi in plan mode interactively (omit the prompt), or use --mode edit, auto, or skip.');
+        }
+        // edit/auto/skip: emit no mode flag — `kimi -p` auto-runs.
+    }
     else {
         cmd.push(...modeFlags);
     }