@phnx-labs/agents-cli 1.20.6 → 1.20.7

package/dist/commands/inspect.js

@@ -1,13 +1,17 @@
 /**
- * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ * `agents inspect <target>` — detail view for one agent+version or one DotAgents repo.
  *
- * Summary mode shows the per-version header (paths, shim, capabilities, resource
- * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
- * one resource kind; passing a positional query to the same flag fuzzy-searches
- * for a single resource and prints its detail. Resource names render as OSC-8
- * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
- * itself) so users can click straight to the source.
+ * Agent targets (`claude`, `claude@2.1.170`) show the per-version header (paths,
+ * shim, capabilities, resource counts, sessions). Repo targets (`user`, `system`,
+ * `project`, a registered extra-repo alias, or a filesystem path to a repo with a
+ * `.agents/` dir or to a DotAgents root itself) show the repo root, git state, and
+ * per-kind resource counts. Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...)
+ * list one resource kind for either target form; passing a positional query to the
+ * same flag fuzzy-searches for a single resource and prints its detail. Resource
+ * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
+ * AGENT.md / the file itself) so users can click straight to the source.
  */
+import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -15,7 +19,7 @@ import chalk from 'chalk';
 import * as yaml from 'yaml';
 import { AGENTS, getCliState } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
-import { readMeta } from '../lib/state.js';
+import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
@@ -39,8 +43,8 @@ const CAPABILITY_NAMES = [
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = program
-        .command('inspect <agent>')
-        .description('Inspect one installed agent at one version — paths, capabilities, resources, drill into any kind.')
+        .command('inspect <target>')
+        .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
     for (const kind of DRILLABLE_KINDS) {
@@ -52,6 +56,20 @@ export function registerInspectCommand(program) {
 }
 // ─── Main dispatcher ─────────────────────────────────────────────────────────
 export async function inspectAction(target, options) {
+    const agentKey = target.split('@')[0].toLowerCase();
+    if (!(agentKey in AGENTS)) {
+        const repo = resolveRepoTarget(target);
+        if (repo) {
+            await inspectRepo(repo, options);
+            return;
+        }
+        const extras = getEnabledExtraRepos();
+        console.error(chalk.red(`Unknown target: ${target}`));
+        console.error(chalk.gray(`Agents: ${Object.keys(AGENTS).join(', ')}`));
+        const aliases = extras.length > 0 ? `, ${extras.map(e => e.alias).join(', ')}` : '';
+        console.error(chalk.gray(`Repos:  user, system, project${aliases} — or a path to a repo with a .agents/ dir`));
+        process.exit(1);
+    }
     const { agent, version } = parseTarget(target);
     const versionHome = getVersionHomePath(agent, version);
     if (!fs.existsSync(versionHome)) {
@@ -75,13 +93,7 @@ export async function inspectAction(target, options) {
 }
 function parseTarget(target) {
     const [rawAgent, rawVersion] = target.split('@');
-    const agentKey = (rawAgent || '').toLowerCase();
-    if (!(agentKey in AGENTS)) {
-        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
-        process.exit(1);
-    }
-    const agent = agentKey;
+    const agent = (rawAgent || '').toLowerCase();
     let version = rawVersion;
     if (!version || version === 'default') {
         const meta = readMeta();
@@ -110,6 +122,160 @@ function pickDrillKind(options) {
     }
     return active[0];
 }
+/** Files at a DotAgents root that mark it as one, beyond the per-kind dirs. */
+const REPO_MARKER_FILES = ['agents.yaml', 'hooks.yaml'];
+/**
+ * Resolve a non-agent target as a DotAgents repo: the built-in layer names,
+ * a registered extra-repo alias, or a filesystem path. Paths accept either a
+ * DotAgents root itself or a repo whose `.agents/` dir should be inspected.
+ * Returns null when the target is none of these.
+ */
+export function resolveRepoTarget(target, cwd) {
+    if (target === 'user')
+        return { label: 'user', root: getUserAgentsDir() };
+    if (target === 'system')
+        return { label: 'system', root: getSystemAgentsDir() };
+    if (target === 'project') {
+        const dir = getProjectAgentsDir(cwd);
+        if (!dir) {
+            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
+            process.exit(1);
+        }
+        return { label: 'project', root: dir };
+    }
+    for (const extra of getEnabledExtraRepos()) {
+        if (extra.alias === target)
+            return { label: extra.alias, root: extra.dir };
+    }
+    const expanded = target.startsWith('~/') ? path.join(os.homedir(), target.slice(2)) : target;
+    const abs = path.resolve(cwd ?? process.cwd(), expanded);
+    const stat = safeStat(abs);
+    if (!stat || !stat.isDirectory())
+        return null;
+    // A dir that is itself a DotAgents root wins over its nested .agents/ —
+    // extra repos like ~/.agents-extras keep resources at the top level and use
+    // .agents/ only for worktrees.
+    if (isDotAgentsRoot(abs)) {
+        const label = path.basename(abs) === '.agents' ? path.basename(path.dirname(abs)) : path.basename(abs);
+        return { label, root: abs };
+    }
+    if (path.basename(abs) !== '.agents') {
+        const nested = path.join(abs, '.agents');
+        if (safeStat(nested)?.isDirectory()) {
+            return { label: path.basename(abs), root: nested };
+        }
+    }
+    return null;
+}
+function isDotAgentsRoot(dir) {
+    for (const marker of REPO_MARKER_FILES) {
+        if (fs.existsSync(path.join(dir, marker)))
+            return true;
+    }
+    for (const kind of DRILLABLE_KINDS) {
+        if (safeStat(path.join(dir, kind))?.isDirectory())
+            return true;
+    }
+    return false;
+}
+async function inspectRepo(repo, options) {
+    const drill = pickDrillKind(options);
+    const jsonHead = { repo: repo.label, root: repo.root };
+    if (drill) {
+        const items = collectRepoKind(repo, drill.kind);
+        if (drill.query === true || drill.query === undefined) {
+            renderItemList(repo.label, jsonHead, drill.kind, items, options);
+        }
+        else {
+            renderItemDetail(repo.label, jsonHead, drill.kind, String(drill.query), items, options);
+        }
+        return;
+    }
+    renderRepoSummary(repo, options);
+}
+/** List one resource kind from a single repo root — no layering, no overrides. */
+export function collectRepoKind(repo, kind) {
+    const dir = path.join(repo.root, kind);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const p = path.join(dir, entry.name);
+        items.push({
+            name: entry.name.replace(/\.(md|yaml|yml|toml|json)$/, ''),
+            source: repo.label,
+            path: p,
+            linkTarget: linkTarget(p),
+            description: readDescription(p),
+        });
+    }
+    return items.sort((a, b) => a.name.localeCompare(b.name));
+}
+function renderRepoSummary(repo, options) {
+    const git = repoGitInfo(repo.root);
+    const manifests = REPO_MARKER_FILES.filter(m => fs.existsSync(path.join(repo.root, m)));
+    const counts = {};
+    if (!options.brief) {
+        for (const kind of DRILLABLE_KINDS) {
+            const items = collectRepoKind(repo, kind);
+            counts[kind] = { total: items.length, bySource: { [repo.label]: items.length } };
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            repo: repo.label,
+            root: repo.root,
+            git,
+            manifests,
+            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => [kind, counts[kind].total])),
+        }, null, 2));
+        return;
+    }
+    console.log('\n' + chalk.bold(repo.label) + '  ' + chalk.gray('[dotagents repo]') + '\n');
+    const rows = [['root', termLink(repo.root, repo.root)]];
+    if (git) {
+        const dirty = git.dirty > 0 ? ` ${chalk.gray('·')} ${chalk.yellow(`${git.dirty} dirty`)}` : '';
+        const url = git.url ? ` ${chalk.gray('·')} ${chalk.gray(git.url)}` : '';
+        rows.push(['git', `${git.branch}${dirty}${url}`]);
+    }
+    if (manifests.length > 0)
+        rows.push(['manifests', manifests.join(', ')]);
+    for (const [k, v] of rows)
+        console.log(`  ${k.padEnd(10)} ${v}`);
+    if (!options.brief) {
+        console.log('\n' + chalk.bold('Resources'));
+        for (const kind of DRILLABLE_KINDS) {
+            console.log(`  ${kind.padEnd(10)} ${String(counts[kind].total).padStart(4)}`);
+        }
+    }
+    console.log('');
+    console.log(chalk.gray(`Drill in:   agents inspect ${repo.label} --skills <query>`));
+    console.log('');
+}
+function repoGitInfo(root) {
+    const git = (args) => {
+        try {
+            return execSync(`git -C ${JSON.stringify(root)} ${args}`, { stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString().trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    const branch = git('rev-parse --abbrev-ref HEAD');
+    if (branch === null)
+        return null;
+    const status = git('status --porcelain');
+    const dirty = status ? status.split('\n').filter(Boolean).length : 0;
+    return { branch, dirty, url: git('remote get-url origin') };
+}
 // ─── Summary mode ────────────────────────────────────────────────────────────
 async function renderSummary(agent, version, versionHome, options) {
     const meta = readMeta();
@@ -184,17 +350,19 @@ async function renderSummary(agent, version, versionHome, options) {
 // ─── List mode ───────────────────────────────────────────────────────────────
 async function renderList(agent, version, versionHome, kind, options) {
     const items = collectKind(agent, versionHome, kind);
+    renderItemList(`${agent}@${version}`, { agent, version }, kind, items, options);
+}
+function renderItemList(header, jsonHead, kind, items, options) {
     if (options.json) {
         console.log(JSON.stringify({
-            agent,
-            version,
+            ...jsonHead,
             kind,
             count: items.length,
             items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description })),
         }, null, 2));
         return;
     }
-    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
+    console.log('\n' + chalk.bold(header) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
     if (items.length === 0) {
         console.log(chalk.gray(`  (none installed)`));
         console.log('');
@@ -212,11 +380,14 @@ async function renderList(agent, version, versionHome, kind, options) {
 // ─── Detail mode (fuzzy) ─────────────────────────────────────────────────────
 async function renderDetail(agent, version, versionHome, kind, query, options) {
     const items = collectKind(agent, versionHome, kind);
+    renderItemDetail(`${agent}@${version}`, { agent, version }, kind, query, items, options);
+}
+function renderItemDetail(header, jsonHead, kind, query, items, options) {
     const matches = findMatches(items, query);
     if (matches.length === 0) {
         const suggestions = suggestClosest(items, query, 3);
         if (options.json) {
-            console.log(JSON.stringify({ agent, version, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
+            console.log(JSON.stringify({ ...jsonHead, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
         }
         else {
             console.error(chalk.red(`No ${kind} matching '${query}'.`));
@@ -231,8 +402,7 @@ async function renderDetail(agent, version, versionHome, kind, query, options) {
     if (options.json) {
         const detail = buildDetail(best.item, kind);
         console.log(JSON.stringify({
-            agent,
-            version,
+            ...jsonHead,
             kind,
             query,
             match: { ...detail, matchKind: best.matchKind },
@@ -240,7 +410,7 @@ async function renderDetail(agent, version, versionHome, kind, query, options) {
         }, null, 2));
         return;
     }
-    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
+    console.log('\n' + chalk.bold(header) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
     const matchTag = best.matchKind === 'exact' ? 'exact' : best.matchKind === 'substring' ? 'substring' : `~${best.distance}`;
     console.log(`  ${chalk.green('✓')}  ${termLink(chalk.bold.cyan(best.item.name), best.item.linkTarget)}  ${chalk.gray(`[${matchTag}, ${best.item.source}]`)}`);
     if (best.item.description) {

package/dist/commands/sessions.js

@@ -15,6 +15,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
+import { looksLikePath, toComparablePath, homeDir } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
@@ -69,15 +70,6 @@ function createScanProgressTracker(verbs, suffix, spinner) {
 }
 const PICKER_RECENT_COUNT = 15;
 const PICKER_POOL_LIMIT = 200;
-/**
- * Detect whether a positional argument looks like a filesystem path.
- * Naked paths (., ./, ../, /, ~) filter sessions by project directory.
- * Everything else is treated as a search query string.
- */
-function isPathLike(query) {
-    return query === '.' || query.startsWith('./') || query.startsWith('../')
-        || query.startsWith('/') || query.startsWith('~');
-}
 /**
  * Resolve a path-like query to an absolute directory path.
  */
@@ -153,8 +145,13 @@ function contextColor(context) {
 function shortCwd(cwd) {
     if (!cwd)
         return '-';
-    const home = os.homedir();
-    return cwd.startsWith(home) ? '~' + cwd.slice(home.length) : cwd;
+    const home = homeDir();
+    // Compare in normalized form so the `~` shorthand also lands on Windows
+    // (case-insensitive, backslash paths); on POSIX this is byte-identical to the
+    // previous `cwd.startsWith(home)`. The displayed tail keeps original casing.
+    return toComparablePath(cwd).startsWith(toComparablePath(home))
+        ? '~' + cwd.slice(home.length)
+        : cwd;
 }
 function formatStartedAt(startedAtMs) {
     if (!startedAtMs)
@@ -334,7 +331,7 @@ async function sessionsAction(query, options) {
     // Path-like queries filter by project directory instead of text search.
     let pathFilter;
     let searchQuery;
-    if (query && isPathLike(query)) {
+    if (query && looksLikePath(query)) {
         const resolved = resolvePathFilter(query);
         if (!fs.existsSync(resolved)) {
             console.log(chalk.yellow(`Path not found: ${resolved}`));

package/dist/index.js

@@ -103,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')
@@ -134,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.)
@@ -461,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) }))

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';
@@ -367,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
@@ -458,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.
  *
@@ -495,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/platform/exec.d.ts

@@ -0,0 +1,9 @@
+/** PATH-search command for the platform: `where` on Windows, else `which`. */
+export declare function whichCommand(platform?: NodeJS.Platform): string;
+/**
+ * Resolve an executable name to its absolute path via the OS PATH search, or
+ * `null` if not found. On Windows `where` can return several lines (one per
+ * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
+ * shell would actually run, matching `which` semantics on POSIX.
+ */
+export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;

package/dist/lib/platform/exec.js

@@ -0,0 +1,24 @@
+/**
+ * Executable resolution, platform-aware.
+ */
+import { execFileSync } from 'child_process';
+/** PATH-search command for the platform: `where` on Windows, else `which`. */
+export function whichCommand(platform = process.platform) {
+    return platform === 'win32' ? 'where' : 'which';
+}
+/**
+ * Resolve an executable name to its absolute path via the OS PATH search, or
+ * `null` if not found. On Windows `where` can return several lines (one per
+ * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
+ * shell would actually run, matching `which` semantics on POSIX.
+ */
+export function findExecutable(name, platform = process.platform) {
+    try {
+        const out = execFileSync(whichCommand(platform), [name], { encoding: 'utf-8' });
+        const first = out.trim().split(/\r?\n/)[0]?.trim();
+        return first || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/platform/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Platform abstraction — the ONE place OS-divergent behavior is decided.
+ *
+ * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
+ * of scattering `process.platform === 'win32'` checks. Each helper that has an
+ * observable branch accepts an explicit `platform` argument (defaulting to
+ * `process.platform`), so all three OSes are unit-testable on any host.
+ *
+ * Modules grow per concern as features land:
+ *   paths   — path classification + normalization
+ *   exec    — executable resolution
+ *   process — process liveness / control
+ * (ipc + shell follow when their consumers migrate off inline branches.)
+ */
+export declare const IS_WINDOWS: boolean;
+export declare const IS_MACOS: boolean;
+export declare const IS_LINUX: boolean;
+export * from './paths.js';
+export * from './exec.js';
+export * from './process.js';

package/dist/lib/platform/index.js

@@ -0,0 +1,20 @@
+/**
+ * Platform abstraction — the ONE place OS-divergent behavior is decided.
+ *
+ * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
+ * of scattering `process.platform === 'win32'` checks. Each helper that has an
+ * observable branch accepts an explicit `platform` argument (defaulting to
+ * `process.platform`), so all three OSes are unit-testable on any host.
+ *
+ * Modules grow per concern as features land:
+ *   paths   — path classification + normalization
+ *   exec    — executable resolution
+ *   process — process liveness / control
+ * (ipc + shell follow when their consumers migrate off inline branches.)
+ */
+export const IS_WINDOWS = process.platform === 'win32';
+export const IS_MACOS = process.platform === 'darwin';
+export const IS_LINUX = process.platform === 'linux';
+export * from './paths.js';
+export * from './exec.js';
+export * from './process.js';

package/dist/lib/platform/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Does this positional argument look like a filesystem path (vs a search term)?
+ *
+ * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
+ * identical to the long-standing behavior. Windows-only shapes (drive-letter
+ * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
+ * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
+ * term — i.e. no behavior change off Windows.
+ */
+export declare function looksLikePath(query: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Normalize a path for comparison/prefix-matching: backslashes folded to forward
+ * slashes and lowercased on Windows (its filesystem is case-insensitive). On
+ * POSIX the input is returned unchanged, so callers behave exactly as before.
+ */
+export declare function toComparablePath(p: string, platform?: NodeJS.Platform): string;
+/**
+ * Canonical home directory. Use this instead of `process.env.HOME`, which is
+ * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
+ * correctly on all three platforms.
+ */
+export declare function homeDir(): string;