@phnx-labs/agents-cli 1.20.5 → 1.20.7

package/dist/index.js

@@ -76,6 +76,7 @@ import { registerDaemonCommands } from './commands/daemon.js';
 import { registerRoutinesCommands } from './commands/routines.js';
 import { registerRunCommand } from './commands/exec.js';
 import { registerModelsCommand } from './commands/models.js';
+import { registerDefaultsCommands } from './commands/defaults.js';
 import { registerPruneCommand } from './commands/prune.js';
 import { registerTrashCommands } from './commands/trash.js';
 import { registerDoctorCommand } from './commands/doctor.js';
@@ -102,6 +103,21 @@ import { isInteractiveTerminal, isPromptCancelled } from './commands/utils.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
 import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
+import { IS_WINDOWS } from './lib/platform/index.js';
+// Transparent shim delegate: the generated Windows `.cmd` shims invoke
+// `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
+// parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
+// through completely untouched and we skip registering the full command tree.
+if (process.argv[2] === '__shim') {
+    const spec = process.argv[3] || '';
+    const rawArgs = process.argv.slice(4);
+    const atIndex = spec.indexOf('@');
+    const agent = atIndex === -1 ? spec : spec.slice(0, atIndex);
+    const pinned = atIndex === -1 ? undefined : spec.slice(atIndex + 1);
+    const { execShimPassthrough } = await import('./lib/exec.js');
+    const code = await execShimPassthrough(agent, rawArgs, process.cwd(), pinned || undefined);
+    process.exit(code);
+}
 const program = new Command();
 program
     .name('agents')
@@ -133,7 +149,7 @@ Agent versions:
   prune cleanup [target]          Remove orphan resources and older duplicate version installs
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
-  inspect <agent>[@version]       Deep details for one agent+version — paths, capabilities, resources, drill into any kind
+  inspect <target>                Deep details for one agent+version, or a DotAgents repo (user|system|project|alias|path)
 
 Agent configuration (synced across versions):
   rules                           Instructions given to agents (CLAUDE.md, etc.)
@@ -151,6 +167,7 @@ Packages:
 
 Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
+  defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
@@ -217,9 +234,12 @@ async function showWhatsNew(fromVersion, toVersion) {
             const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
             if (versionMatch) {
                 currentVersion = versionMatch[1];
-                const isNewer = currentVersion !== fromVersion &&
-                    compareVersions(currentVersion, fromVersion) > 0;
-                inRelevantSection = isNewer;
+                // Only the range the user actually moved through: (fromVersion, toVersion].
+                // Bounding the top end matters when upgrading to a specific older
+                // version, and guards against a changelog that lists unreleased entries.
+                const inRange = compareVersions(currentVersion, fromVersion) > 0 &&
+                    compareVersions(currentVersion, toVersion) <= 0;
+                inRelevantSection = inRange;
                 if (inRelevantSection) {
                     relevantChanges.push('');
                     relevantChanges.push(chalk.bold(`v${currentVersion}`));
@@ -279,11 +299,14 @@ function saveUpdateCheck(latestVersion) {
     }
 }
 /** Fetch the exact latest npm version plus its registry integrity hash. */
-async function fetchLatestNpmPackageMetadata(timeoutMs = 5000) {
-    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, {
+async function fetchNpmPackageMetadata(versionOrTag = 'latest', timeoutMs = 5000) {
+    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/${versionOrTag}`, {
         signal: AbortSignal.timeout(timeoutMs),
     });
     if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`${NPM_PACKAGE_NAME}@${versionOrTag} not found on npm`);
+        }
         throw new Error('Could not reach npm registry');
     }
     const data = await response.json();
@@ -338,7 +361,7 @@ async function promptUpgrade(latestVersion) {
         const { spawnSync } = await import('child_process');
         let spinner = ora('Resolving package metadata...').start();
         try {
-            const metadata = await fetchLatestNpmPackageMetadata();
+            const metadata = await fetchNpmPackageMetadata();
             spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${metadata.version}`);
             printResolvedPackage(metadata);
             const approved = await confirm({
@@ -453,6 +476,13 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     for (const agent of installedAgents) {
         removeLegacyUserShim(agent);
     }
+    // The remaining flow is rc-file PATH repair, which is POSIX-only. On Windows
+    // the shims were just regenerated (incl. `.cmd` companions) above; PATH setup
+    // is covered by the install-time guidance, so stop here rather than printing
+    // shell-rc instructions that don't apply.
+    if (IS_WINDOWS) {
+        return;
+    }
     const defaultAgents = installedAgents.filter((agent) => getGlobalDefault(agent));
     const shadowed = defaultAgents
         .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
@@ -583,6 +613,7 @@ registerPackagesCommands(program);
 registerDaemonCommands(program);
 registerRoutinesCommands(program);
 registerRunCommand(program);
+registerDefaultsCommands(program);
 registerModelsCommand(program);
 registerPruneCommand(program);
 registerTrashCommands(program);
@@ -627,26 +658,31 @@ for (const alias of ['jobs', 'cron']) {
 }
 program
     .command('upgrade')
-    .description('Upgrade agents-cli to the latest version')
+    .description('Upgrade agents-cli to the latest version (or a specific [version])')
+    .argument('[version]', 'Target version or dist-tag to install (default: latest)')
     .option('-y, --yes', 'Install without an interactive confirmation prompt')
-    .action(async (options) => {
-    let spinner = ora('Checking for updates...').start();
+    .action(async (version, options) => {
+    const target = version ?? 'latest';
+    let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
     try {
-        const metadata = await fetchLatestNpmPackageMetadata();
-        const latestVersion = metadata.version;
-        if (latestVersion === VERSION) {
-            spinner.succeed(`Already on latest version (${VERSION})`);
+        const metadata = await fetchNpmPackageMetadata(target);
+        const resolvedVersion = metadata.version;
+        if (resolvedVersion === VERSION) {
+            spinner.succeed(`Already on ${VERSION}`);
             return;
         }
-        if (compareVersions(latestVersion, VERSION) <= 0) {
-            spinner.succeed(`Already ahead of latest (${VERSION} >= ${latestVersion})`);
+        // For `latest` (no explicit version) skip when already ahead. When a
+        // version is named explicitly, honor it even if it's a downgrade.
+        if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
+            spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
             return;
         }
-        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${latestVersion}`);
+        const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
+        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
         printResolvedPackage(metadata);
         if (isInteractiveTerminal() && !options.yes) {
             const approved = await confirm({
-                message: `Install ${NPM_PACKAGE_NAME}@${latestVersion}?`,
+                message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
                 default: false,
             });
             if (!approved) {
@@ -654,14 +690,17 @@ program
                 return;
             }
         }
-        spinner = ora(`Upgrading ${VERSION} -> ${latestVersion}...`).start();
+        spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
         await installResolvedPackage(metadata);
-        spinner.succeed(`Upgraded to ${latestVersion}`);
-        await showWhatsNew(VERSION, latestVersion);
+        spinner.succeed(`${direction}d to ${resolvedVersion}`);
+        // Only show the changelog for a genuine upgrade range.
+        if (compareVersions(resolvedVersion, VERSION) > 0) {
+            await showWhatsNew(VERSION, resolvedVersion);
+        }
     }
     catch (err) {
         spinner.fail('Upgrade failed');
-        console.log(chalk.gray('Run manually: agents upgrade --yes'));
+        console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
     }
 });
 registerPullCommand(program);

package/dist/lib/agents.d.ts

@@ -69,12 +69,16 @@ export declare function ensureSkillsDir(agentId: AgentId): void;
  * The agent's config-dir name relative to $HOME — e.g. '.claude',
  * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
  *
- * This is the path segment to join onto a (version) home root when locating an
- * agent's commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong
- * for every agent whose config dir is nested or lives under ~/.config —
- * antigravity (~/.gemini/antigravity-cli), amp (~/.config/amp),
- * goose (~/.config/goose), kimi (~/.kimi-code). Mirrors the shim `configDirName`
- * derivation in shims.ts.
+ * Path segment to join onto a (version) home root when locating an agent's
+ * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
+ * every agent whose config dir is nested or under ~/.config — antigravity
+ * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
+ * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
+ *
+ * Relativized against the module-level HOME constant (the same value used to
+ * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
+ * clean relative name even when HOME is overridden after module load (tests,
+ * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
  */
 export declare function agentConfigDirName(agentId: AgentId): string;
 /** Account identity and billing information extracted from an agent's auth config. */

package/dist/lib/agents.js

@@ -446,13 +446,18 @@ export const AGENTS = {
             rulesImports: true,
         },
     },
+    // Kimi Code CLI (`kimi`) — Moonshot AI coding agent.
+    // Install: `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash`
+    //    or: `npm install -g @moonshot-ai/kimi-code`
+    // Config: `~/.kimi-code/config.toml`, `~/.kimi-code/mcp.json`,
+    //         `~/.kimi-code/skills/`, `~/.kimi-code/hooks/`
     kimi: {
         id: 'kimi',
         name: 'Kimi',
         color: 'magentaBright',
-        cliCommand: 'kimi-code',
-        npmPackage: '',
-        installScript: '',
+        cliCommand: 'kimi',
+        npmPackage: '@moonshot-ai/kimi-code',
+        installScript: 'curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash',
         configDir: path.join(HOME, '.kimi-code'),
         commandsDir: '',
         commandsSubdir: '',
@@ -465,14 +470,14 @@ export const AGENTS = {
         capabilities: {
             hooks: true,
             mcp: true,
-            allowlist: false,
-            skills: false,
+            allowlist: true,
+            skills: true,
             commands: false,
-            plugins: false,
+            plugins: true,
             subagents: false,
             rules: { file: 'AGENTS.md' },
             workflows: false,
-            modes: ['plan', 'edit', 'skip'],
+            modes: ['plan', 'edit', 'auto', 'skip'],
             rulesImports: false,
         },
     },
@@ -690,15 +695,19 @@ export function ensureSkillsDir(agentId) {
  * The agent's config-dir name relative to $HOME — e.g. '.claude',
  * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
  *
- * This is the path segment to join onto a (version) home root when locating an
- * agent's commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong
- * for every agent whose config dir is nested or lives under ~/.config —
- * antigravity (~/.gemini/antigravity-cli), amp (~/.config/amp),
- * goose (~/.config/goose), kimi (~/.kimi-code). Mirrors the shim `configDirName`
- * derivation in shims.ts.
+ * Path segment to join onto a (version) home root when locating an agent's
+ * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
+ * every agent whose config dir is nested or under ~/.config — antigravity
+ * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
+ * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
+ *
+ * Relativized against the module-level HOME constant (the same value used to
+ * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
+ * clean relative name even when HOME is overridden after module load (tests,
+ * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
  */
 export function agentConfigDirName(agentId) {
-    return path.relative(os.homedir(), AGENTS[agentId].configDir);
+    return path.relative(HOME, AGENTS[agentId].configDir);
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {

package/dist/lib/browser/chrome.d.ts

@@ -1,5 +1,15 @@
 import type { ChromeOptions } from './types.js';
 import type { BrowserType } from './types.js';
+/**
+ * True when `binaryPath` is a shebang script rather than a native browser
+ * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
+ * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
+ * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
+ * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
+ * Linux/Unix concept — returns false on Windows/macOS app bundles.
+ */
+export declare function isLauncherScript(binaryPath: string): boolean;
+export declare function resolveBrowserBinary(binaryPath: string): string;
 export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
 /**
  * Walk the per-platform priority list and return the first browser that's

package/dist/lib/browser/chrome.js

@@ -42,12 +42,90 @@ const BROWSER_PATHS = {
         custom: [],
     },
 };
+/**
+ * On Debian/Ubuntu the canonical launchers under `/usr/bin`
+ * (`brave-browser`, `google-chrome`, `chromium`) are not the browser ELF —
+ * they're `#!/bin/bash` wrapper scripts (the upstream Chromium wrapper) that,
+ * as their final step, run the real binary as a NON-exec child:
+ *
+ *     exec < /dev/null
+ *     exec > >(exec cat)
+ *     exec 2> >(exec cat >&2)
+ *     "$HERE/brave" "$@" || true
+ *
+ * That breaks `launchBrowser`'s `--remote-debugging-pipe` transport two ways:
+ * the std-fd sanitization (and the extra `cat` process-substitution children)
+ * disturbs the inherited CDP pipe on fd 3/4, and the pid we record is the
+ * wrapper's, not the browser's. The symptom is `read ECONNRESET` /
+ * `CDP connection closed` right after spawn (issue #229).
+ *
+ * Follow the wrapper to the ELF it execs. The wrapper sets
+ * `HERE="dirname(readlink -f "$0")"` and invokes `"$HERE/<name>"`, so we
+ * resolve the script path, scan for that invocation line, and join the two.
+ * Returns the original path untouched when it's already an ELF, when it's not
+ * a resolvable wrapper, or on any non-Linux platform.
+ */
+function readsAsShebangScript(binaryPath) {
+    let fd;
+    try {
+        fd = fs.openSync(binaryPath, 'r');
+    }
+    catch {
+        return false;
+    }
+    try {
+        const head = Buffer.alloc(2);
+        fs.readSync(fd, head, 0, 2, 0);
+        // ELF binaries start with 0x7f 'E'; shebang scripts with '#!'.
+        return head[0] === 0x23 && head[1] === 0x21;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * True when `binaryPath` is a shebang script rather than a native browser
+ * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
+ * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
+ * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
+ * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
+ * Linux/Unix concept — returns false on Windows/macOS app bundles.
+ */
+export function isLauncherScript(binaryPath) {
+    if (os.platform() === 'win32')
+        return false;
+    return readsAsShebangScript(binaryPath);
+}
+export function resolveBrowserBinary(binaryPath) {
+    if (os.platform() !== 'linux')
+        return binaryPath;
+    // Only shebang scripts need unwrapping; a real ELF passes straight through.
+    if (!readsAsShebangScript(binaryPath))
+        return binaryPath;
+    let script;
+    let realScriptPath;
+    try {
+        realScriptPath = fs.realpathSync(binaryPath);
+        script = fs.readFileSync(realScriptPath, 'utf8');
+    }
+    catch {
+        return binaryPath;
+    }
+    // Match the Chromium wrapper's launch line: `"$HERE/<name>" "$@"`, optionally
+    // prefixed with `exec -a "$0"`. The captured name is the real ELF, sitting in
+    // the same directory as the resolved wrapper.
+    const match = script.match(/"\$HERE\/([A-Za-z0-9._-]+)"\s+"\$@"/);
+    if (!match)
+        return binaryPath;
+    const realBinary = path.join(path.dirname(realScriptPath), match[1]);
+    return fs.existsSync(realBinary) ? realBinary : binaryPath;
+}
 export function findBrowserPath(browserType, customBinary) {
     if (customBinary) {
         if (!fs.existsSync(customBinary)) {
             throw new Error(`Custom binary not found: ${customBinary}`);
         }
-        return customBinary;
+        return resolveBrowserBinary(customBinary);
     }
     if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
@@ -60,9 +138,12 @@ export function findBrowserPath(browserType, customBinary) {
     const candidates = platformPaths[browserType] || [];
     for (const p of candidates) {
         if (fs.existsSync(p)) {
-            return p;
+            return resolveBrowserBinary(p);
         }
     }
+    if (browserType === 'comet' && platform !== 'darwin') {
+        throw new Error('Browser "comet" is macOS-only (Comet is a macOS Chromium fork). Use chrome, chromium, brave, or edge on this platform.');
+    }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
 // Per-platform Chromium-family priority list for "no --profile" auto-pick.
@@ -98,7 +179,7 @@ export function findFirstInstalledBrowser(platform = os.platform()) {
         const candidates = platformPaths[browserType] || [];
         for (const p of candidates) {
             if (fs.existsSync(p)) {
-                return { browserType, binary: p };
+                return { browserType, binary: resolveBrowserBinary(p) };
             }
         }
     }

package/dist/lib/daemon.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { getDaemonDir as getDaemonDirRoot } from './state.js';
+import { isAlive } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
@@ -114,14 +115,10 @@ export function isDaemonRunning() {
     const pid = readDaemonPid();
     if (!pid)
         return false;
-    try {
-        process.kill(pid, 0);
+    if (isAlive(pid))
         return true;
-    }
-    catch {
-        removeDaemonPid();
-        return false;
-    }
+    removeDaemonPid();
+    return false;
 }
 /** Redact values that look like tokens or credentials in a log message. */
 function redactSecrets(message) {

package/dist/lib/exec.d.ts

@@ -95,6 +95,15 @@ export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
+/**
+ * Transparent passthrough exec for generated shims — the node-side delegate that
+ * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
+ * project/default) and execs the real binary with the user's RAW args and the
+ * per-version env isolation, WITHOUT injecting mode/model/reasoning flags. This
+ * mirrors what the POSIX bash shim does inline (`exec $BINARY $launchArgs "$@"`),
+ * keeping version resolution in one place instead of reimplementing it in batch.
+ */
+export declare function execShimPassthrough(agent: AgentId, rawArgs: string[], cwd: string, pinnedVersion?: string): Promise<number>;
 /**
  * Patterns that indicate a rate/usage limit. Matching is intentionally broad
  * because providers phrase these differently -- Anthropic uses "5-hour limit"

package/dist/lib/exec.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import { ALL_MODES } from './types.js';
 import { AGENTS } from './agents.js';
 import { parseTimeout } from './routines.js';
-import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
+import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
@@ -118,6 +118,7 @@ export function buildExecEnv(options) {
         }
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
     }
     else if (options.agent === 'codex') {
         const cwd = options.cwd || process.cwd();
@@ -130,6 +131,7 @@ export function buildExecEnv(options) {
         }
         delete result.CLAUDE_CONFIG_DIR;
         delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
     }
     else if (options.agent === 'copilot') {
         // Copilot honors COPILOT_HOME (relocates ~/.copilot, including settings,
@@ -145,11 +147,28 @@ export function buildExecEnv(options) {
         }
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
+        delete result.KIMI_CODE_HOME;
+    }
+    else if (options.agent === 'kimi') {
+        // Kimi honors KIMI_CODE_HOME (relocates ~/.kimi-code, including config,
+        // skills, hooks, sessions). Pin it at the per-version home.
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('kimi', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('kimi', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            result.KIMI_CODE_HOME = path.join(getVersionHomePath('kimi', version), '.kimi-code');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
     }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
     }
     return {
         ...result,
@@ -322,14 +341,15 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
     },
     kimi: {
-        base: ['kimi-code'],
+        base: ['kimi'],
         promptFlag: '-p',
         modeFlags: {
-            plan: [],
+            plan: ['--plan'],
             edit: [],
-            skip: [],
+            auto: ['--auto'],
+            skip: ['--yolo'],
         },
-        jsonFlags: [],
+        jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
 };
@@ -347,10 +367,27 @@ export function buildExecCommand(options) {
     // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
     // on Linux installs where the shims dir isn't on PATH, spawning the bare
     // versioned name fails with ENOENT even though `agents view` shows the agent.
+    //
+    // On Windows, shims are bash scripts and cannot be executed by spawn() directly.
+    // buildExecEnv() already sets the isolation env vars (CLAUDE_CONFIG_DIR, CODEX_HOME,
+    // etc.) that the bash shim would set, so we can skip the shim entirely and resolve
+    // straight to the real binary via getBinaryPath.
     if (options.version && cmd.length > 0) {
-        const versionedName = `${cmd[0]}@${options.version}`;
-        const absPath = path.join(getShimsDir(), versionedName);
-        cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
+        if (process.platform === 'win32') {
+            const binaryPath = getBinaryPath(options.agent, options.version);
+            const binaryPathCmd = binaryPath + '.cmd';
+            if (fs.existsSync(binaryPathCmd)) {
+                cmd[0] = binaryPathCmd;
+            }
+            else if (fs.existsSync(binaryPath)) {
+                cmd[0] = binaryPath;
+            }
+        }
+        else {
+            const versionedName = `${cmd[0]}@${options.version}`;
+            const absPath = path.join(getShimsDir(), versionedName);
+            cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
+        }
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
     // For codex, -c must come before 'exec' subcommand, so we insert at position 1
@@ -438,6 +475,42 @@ export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
 }
+/**
+ * Transparent passthrough exec for generated shims — the node-side delegate that
+ * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
+ * project/default) and execs the real binary with the user's RAW args and the
+ * per-version env isolation, WITHOUT injecting mode/model/reasoning flags. This
+ * mirrors what the POSIX bash shim does inline (`exec $BINARY $launchArgs "$@"`),
+ * keeping version resolution in one place instead of reimplementing it in batch.
+ */
+export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
+    const version = pinnedVersion ?? resolveVersion(agent, cwd) ?? undefined;
+    if (!version || !isVersionInstalled(agent, version)) {
+        process.stderr.write(`agents: no installed default for ${agent}. Set one with: agents use ${agent} <version>\n`);
+        return 127;
+    }
+    let binary = getBinaryPath(agent, version);
+    if (process.platform === 'win32') {
+        // npm ships <cmd>.cmd alongside the bare script on Windows; that's the runnable form.
+        const cmdPath = binary + '.cmd';
+        if (fs.existsSync(cmdPath))
+            binary = cmdPath;
+    }
+    // The only flag the bash shim injects (codex); everything else is transparent.
+    const launchArgs = agent === 'codex' ? ['-c', 'check_for_update_on_startup=false'] : [];
+    // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
+    // derives the per-version config-dir env); pass the agent's default to satisfy the type.
+    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
+    const useShell = process.platform === 'win32' && (!path.isAbsolute(binary) || binary.endsWith('.cmd'));
+    return new Promise((resolve) => {
+        const child = spawn(binary, [...launchArgs, ...rawArgs], { cwd, stdio: 'inherit', env, shell: useShell });
+        child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+        child.on('error', (err) => {
+            process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\n`);
+            resolve(127);
+        });
+    });
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -475,11 +548,14 @@ async function spawnAgent(options) {
         const stdio = interactive
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', piped ? 'pipe' : 'inherit', 'pipe'];
+        // On Windows, .cmd batch wrappers (npm-installed CLIs) require shell:true
+        // whether addressed by name or absolute path.
+        const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
         const child = spawn(executable, args, {
             cwd: options.cwd || process.cwd(),
             stdio,
             env: buildExecEnv(options),
-            shell: false,
+            shell: useShell,
         });
         // Mark startup time (time from function call to process spawn)
         timer.mark('startup');

package/dist/lib/migrate.js

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { AGENTS, agentConfigDirName } from './agents.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -672,12 +673,13 @@ function repairAgentConfigSymlinks() {
     }
     let repaired = 0;
     for (const { agent, version } of defaults) {
-        const userTarget = fs.existsSync(path.join(HISTORY_DIR, 'versions', agent, version, 'home', `.${agent}`))
-            ? path.join(HISTORY_DIR, 'versions', agent, version, 'home', `.${agent}`)
-            : path.join(USER_DIR, 'versions', agent, version, 'home', `.${agent}`);
+        const configDirName = agent in AGENTS ? agentConfigDirName(agent) : `.${agent}`;
+        const userTarget = fs.existsSync(path.join(HISTORY_DIR, 'versions', agent, version, 'home', configDirName))
+            ? path.join(HISTORY_DIR, 'versions', agent, version, 'home', configDirName)
+            : path.join(USER_DIR, 'versions', agent, version, 'home', configDirName);
         if (!fs.existsSync(userTarget))
             continue;
-        const symlinkPath = path.join(HOME, `.${agent}`);
+        const symlinkPath = path.join(HOME, configDirName);
         let stat = null;
         try {
             stat = fs.lstatSync(symlinkPath);