@phnx-labs/agents-cli 1.20.7 → 1.20.9

package/dist/index.js

@@ -23,7 +23,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
-const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
+import { NPM_PACKAGE_NAME, deriveGlobalPrefix, installPackageIntoPrefix, verifyInstalledVersion, refreshAliasShims, } from './lib/self-update.js';
 // Detect dev/working-tree builds and default the noisy startup steps off.
 // Three cases trip this:
 //   1. Dev install (scripts/install.sh) — package.json version stamped 0.0.0-dev.<sha>
@@ -268,17 +268,52 @@ async function showWhatsNew(fromVersion, toVersion) {
     }
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir } from './lib/state.js';
+import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
+import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
-/** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
-function readUpdateCache() {
+/**
+ * Warn once when PATH resolves `agents` to a different agents-cli install
+ * than the copy that is currently running (or to several). Divergent installs
+ * are how self-updates "succeed" without changing the command the user types.
+ * The warning re-fires only when the set of install roots changes; dev builds
+ * (0.0.0-dev) are ignored because side-by-side dev installs are a supported
+ * workflow.
+ */
+function maybeWarnMultiInstall() {
+    const sentinel = path.join(getRuntimeStateDir(), 'multi-install-warned');
+    const runningRoot = path.resolve(__dirname, '..');
+    const byRoot = new Map();
+    byRoot.set(runningRoot, { version: VERSION, note: 'running' });
+    for (const install of findAgentsCliInstalls(process.env.PATH || '')) {
+        if (install.version.startsWith('0.0.0-dev'))
+            continue;
+        if (!byRoot.has(install.packageRoot)) {
+            byRoot.set(install.packageRoot, { version: install.version, note: `agents on PATH: ${install.binPath}` });
+        }
+    }
+    if (byRoot.size < 2) {
+        try {
+            fs.unlinkSync(sentinel);
+        }
+        catch { /* nothing recorded */ }
+        return;
+    }
+    const key = [...byRoot.keys()].sort().join('\n');
     try {
-        return JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, 'utf-8'));
+        if (fs.readFileSync(sentinel, 'utf-8') === key)
+            return;
     }
-    catch {
-        /* cache file missing or corrupt */
-        return null;
+    catch { /* not warned for this set yet */ }
+    console.error(chalk.yellow('Multiple agents-cli installs detected:'));
+    for (const [root, info] of byRoot) {
+        console.error(chalk.gray(`  ${root}  ${info.version}  (${info.note})`));
+    }
+    console.error(chalk.gray('Upgrades apply to the running copy. Remove a stale copy with: npm uninstall -g --prefix <prefix> @phnx-labs/agents-cli'));
+    try {
+        fs.mkdirSync(path.dirname(sentinel), { recursive: true });
+        fs.writeFileSync(sentinel, key);
     }
+    catch { /* best-effort; worst case the warning repeats */ }
 }
 /** Determine whether enough time has elapsed since the last registry fetch. */
 function shouldFetchLatest(cache) {
@@ -286,18 +321,6 @@ function shouldFetchLatest(cache) {
         return true;
     return Date.now() - cache.lastCheck > UPDATE_CHECK_INTERVAL_MS;
 }
-/** Persist the latest known version and current timestamp to the update-check cache. */
-function saveUpdateCheck(latestVersion) {
-    try {
-        const dir = path.dirname(UPDATE_CHECK_FILE);
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify({ lastCheck: Date.now(), latestVersion }));
-    }
-    catch {
-        /* best-effort cache update */
-    }
-}
 /** Fetch the exact latest npm version plus its registry integrity hash. */
 async function fetchNpmPackageMetadata(versionOrTag = 'latest', timeoutMs = 5000) {
     const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/${versionOrTag}`, {
@@ -320,12 +343,11 @@ function printResolvedPackage(metadata) {
     console.log(chalk.gray(`Integrity: ${metadata.integrity}`));
 }
 async function installResolvedPackage(metadata) {
-    const { execFile } = await import('child_process');
-    const { promisify } = await import('util');
-    const execFileAsync = promisify(execFile);
-    const installArgs = ['install', '-g', '@phnx-labs/agents-cli', '--ignore-scripts'];
-    installArgs[2] = `${NPM_PACKAGE_NAME}@${metadata.version}`;
-    await execFileAsync('npm', installArgs);
+    const packageRoot = path.resolve(__dirname, '..');
+    const prefix = deriveGlobalPrefix(packageRoot);
+    await installPackageIntoPrefix(`${NPM_PACKAGE_NAME}@${metadata.version}`, prefix);
+    verifyInstalledVersion(packageRoot, metadata.version);
+    refreshAliasShims(packageRoot);
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
@@ -342,19 +364,7 @@ async function promptUpgrade(latestVersion) {
         ],
     });
     if (answer === 'dismiss') {
-        try {
-            const dir = path.dirname(UPDATE_CHECK_FILE);
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
-            const existing = readUpdateCache();
-            fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify({
-                ...existing,
-                lastCheck: existing?.lastCheck ?? Date.now(),
-                latestVersion,
-                dismissed: latestVersion,
-            }));
-        }
-        catch { /* best-effort */ }
+        dismissUpdateVersion(UPDATE_CHECK_FILE, latestVersion);
         return;
     }
     if (answer === 'now') {
@@ -362,6 +372,10 @@ async function promptUpgrade(latestVersion) {
         let spinner = ora('Resolving package metadata...').start();
         try {
             const metadata = await fetchNpmPackageMetadata();
+            // The prompt showed the cached latest, which can lag the registry (the
+            // 24h window) — sync the cache to what was actually resolved so later
+            // prompts and the install agree on the same version.
+            saveUpdateCheck(UPDATE_CHECK_FILE, metadata.version);
             spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${metadata.version}`);
             printResolvedPackage(metadata);
             const approved = await confirm({
@@ -377,15 +391,20 @@ async function promptUpgrade(latestVersion) {
             spinner.succeed(`Upgraded to ${metadata.version}`);
             await showWhatsNew(VERSION, metadata.version);
             console.log();
-            // Re-exec with new version and exit
-            const result = spawnSync('agents', process.argv.slice(2), {
+            // Re-exec the verified install's entrypoint and exit. PATH lookup of
+            // `agents` could resolve a different copy (dev build, another prefix)
+            // than the one that was just upgraded.
+            const entrypoint = path.resolve(__dirname, '..', 'dist', 'index.js');
+            const result = spawnSync(process.execPath, [entrypoint, ...process.argv.slice(2)], {
                 stdio: 'inherit',
                 shell: false,
             });
             process.exit(result.status ?? 0);
         }
-        catch {
-            spinner.fail('Upgrade failed');
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
             console.log(chalk.gray('Run manually: agents upgrade --yes'));
         }
         console.log();
@@ -405,7 +424,7 @@ function refreshUpdateCacheInBackground() {
         .then((response) => (response.ok ? response.json() : null))
         .then((data) => {
         if (data && typeof data.version === 'string') {
-            saveUpdateCheck(data.version);
+            saveUpdateCheck(UPDATE_CHECK_FILE, data.version);
         }
     })
         .catch(() => {
@@ -416,7 +435,8 @@ function refreshUpdateCacheInBackground() {
 async function checkForUpdates() {
     if (process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE)
         return;
-    const cache = readUpdateCache();
+    maybeWarnMultiInstall();
+    const cache = readUpdateCache(UPDATE_CHECK_FILE);
     // Kick off network refresh in background if stale. Does not block.
     if (shouldFetchLatest(cache)) {
         refreshUpdateCacheInBackground();
@@ -424,7 +444,7 @@ async function checkForUpdates() {
     // Prompt based on current cache (may be from a previous run's background refresh).
     // Skip if the user dismissed this exact version — they'll be prompted again when
     // a newer version appears.
-    if (cache?.latestVersion && cache.latestVersion !== VERSION && compareVersions(cache.latestVersion, VERSION) > 0 && cache.latestVersion !== cache.dismissed) {
+    if (shouldPromptUpgrade(cache, VERSION)) {
         try {
             await promptUpgrade(cache.latestVersion);
         }
@@ -699,7 +719,9 @@ program
         }
     }
     catch (err) {
-        spinner.fail('Upgrade failed');
+        if (isPromptCancelled(err))
+            return;
+        spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
         console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
     }
 });

package/dist/lib/agents.d.ts

@@ -104,6 +104,17 @@ export declare function getAccountEmail(agentId: AgentId, home?: string): Promis
  * 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,
+ * falling back to config mtime.
+ *
+ * The session walk stats every transcript under the home's session dir —
+ * thousands of files on long-lived installs — and `agents run` rotation calls
+ * this once per installed version on every launch. The walk result is cached
+ * on disk for a short window so back-to-back launches skip it entirely.
+ * Cache read/write is best-effort: any failure falls back to walking.
+ */
+export declare function resolveLastActive(agentId: AgentId, base: string, configPath?: string, cachePath?: string, now?: Date): Date | null;
 /**
  * Quick count of session files for an agent (without full DB scan).
  * Used during init to show approximate session count to user.
@@ -190,7 +201,13 @@ export declare function listInstalledMcpsWithScope(agentId: AgentId, cwd?: strin
 }): InstalledMcp[];
 /** Map of agent name aliases and shorthand identifiers to canonical AgentId values. */
 export declare const AGENT_NAME_ALIASES: Record<string, AgentId>;
-/** Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId. */
+/**
+ * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.
+ * Tolerates a single typo (insertion/deletion/substitution/transposition) against
+ * canonical ids and aliases — `cladue` -> claude, `kim` -> kimi, `codx` -> codex —
+ * but only when the correction is unambiguous (all distance-1 candidates agree on
+ * one agent). Two-letter shorthands are excluded as fuzzy candidates.
+ */
 export declare function resolveAgentName(input: string): AgentId | null;
 /** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;

package/dist/lib/agents.js

@@ -15,8 +15,9 @@ import * as path from 'path';
 import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
-import { walkForFiles } from './fs-walk.js';
-import { getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
+import { latestFileMtimeMs } from './fs-walk.js';
+import { damerauLevenshtein } from './fuzzy.js';
+import { getCacheDir, getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
@@ -869,14 +870,50 @@ export async function getAccountInfo(agentId, home) {
         return { ...empty, lastActive };
     }
 }
-/** Determine when the agent was last used by checking session file mtimes, falling back to config mtime. */
-function resolveLastActive(agentId, base, configPath) {
+// Fresh window for the cached session walk. Matches USAGE_CACHE_FRESH_MS in
+// usage.ts so a launch storm reuses both probes for the same period.
+const LAST_ACTIVE_CACHE_FRESH_MS = 2 * 60 * 1000;
+const getLastActiveCachePath = () => path.join(getCacheDir(), 'last-active.json');
+/**
+ * Determine when the agent was last used by checking session file mtimes,
+ * falling back to config mtime.
+ *
+ * The session walk stats every transcript under the home's session dir —
+ * thousands of files on long-lived installs — and `agents run` rotation calls
+ * this once per installed version on every launch. The walk result is cached
+ * on disk for a short window so back-to-back launches skip it entirely.
+ * Cache read/write is best-effort: any failure falls back to walking.
+ */
+export function resolveLastActive(agentId, base, configPath, cachePath = getLastActiveCachePath(), now = new Date()) {
     const sessionDir = getSessionDir(agentId, base);
     const sessionExt = getSessionExtension(agentId);
     if (sessionDir && sessionExt) {
-        const latestSession = getLatestFileMtime(sessionDir, sessionExt);
-        if (latestSession) {
-            return latestSession;
+        const key = `${agentId}:${base}`;
+        const cache = readLastActiveCacheFile(cachePath);
+        const entry = cache[key];
+        const fresh = entry &&
+            typeof entry.computedAt === 'number' &&
+            now.getTime() - entry.computedAt >= 0 &&
+            now.getTime() - entry.computedAt < LAST_ACTIVE_CACHE_FRESH_MS;
+        if (fresh) {
+            if (entry.mtimeMs !== null)
+                return new Date(entry.mtimeMs);
+            // Fresh entry with no sessions: fall through to the config mtime below.
+        }
+        else {
+            const mtimeMs = latestFileMtimeMs(sessionDir, sessionExt);
+            cache[key] = { mtimeMs, computedAt: now.getTime() };
+            // Stale entries are never served, so drop them on write — keeps homes
+            // that no longer exist (removed versions, test temp dirs) from
+            // accumulating in the file.
+            for (const [k, v] of Object.entries(cache)) {
+                if (k !== key && !(typeof v?.computedAt === 'number' && now.getTime() - v.computedAt < LAST_ACTIVE_CACHE_FRESH_MS)) {
+                    delete cache[k];
+                }
+            }
+            writeLastActiveCacheFile(cache, cachePath);
+            if (mtimeMs !== null)
+                return new Date(mtimeMs);
         }
     }
     if (!configPath)
@@ -888,6 +925,28 @@ function resolveLastActive(agentId, base, configPath) {
         return null;
     }
 }
+/** Read the entire last-active cache file. Missing or corrupt file reads as empty. */
+function readLastActiveCacheFile(cachePath) {
+    if (!fs.existsSync(cachePath))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Write the entire last-active cache. Best-effort; a failed write just means the next call walks again. */
+function writeLastActiveCacheFile(cache, cachePath) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify(cache), 'utf-8');
+    }
+    catch {
+        /* best-effort */
+    }
+}
 /** Return the root directory where the agent stores session files, or null if unknown. */
 function getSessionDir(agentId, base) {
     switch (agentId) {
@@ -951,20 +1010,6 @@ export function countSessionFiles(agentId) {
     walk(sessionDir);
     return count;
 }
-/** Walk a directory for files matching the extension and return the mtime of the most recent one. */
-function getLatestFileMtime(dir, ext) {
-    if (!fs.existsSync(dir))
-        return null;
-    const [latest] = walkForFiles(dir, ext, 1);
-    if (!latest)
-        return null;
-    try {
-        return fs.statSync(latest).mtime;
-    }
-    catch {
-        return null;
-    }
-}
 /** Decode the payload section of a JWT token without verifying its signature. */
 function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
@@ -1515,10 +1560,31 @@ export const AGENT_NAME_ALIASES = {
     'grok-build': 'grok',
     'xai-grok': 'grok',
     gk: 'grok',
+    kimi: 'kimi',
+    'kimi-code': 'kimi',
 };
-/** Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId. */
+/**
+ * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.
+ * Tolerates a single typo (insertion/deletion/substitution/transposition) against
+ * canonical ids and aliases — `cladue` -> claude, `kim` -> kimi, `codx` -> codex —
+ * but only when the correction is unambiguous (all distance-1 candidates agree on
+ * one agent). Two-letter shorthands are excluded as fuzzy candidates.
+ */
 export function resolveAgentName(input) {
-    return AGENT_NAME_ALIASES[input.toLowerCase()] || null;
+    const lower = input.toLowerCase();
+    const exact = AGENT_NAME_ALIASES[lower] ?? (AGENTS[lower] ? lower : null);
+    if (exact || lower.length < 3)
+        return exact;
+    const hits = new Set();
+    for (const id of ALL_AGENT_IDS) {
+        if (damerauLevenshtein(lower, id) === 1)
+            hits.add(id);
+    }
+    for (const [key, id] of Object.entries(AGENT_NAME_ALIASES)) {
+        if (key.length >= 3 && damerauLevenshtein(lower, key) === 1)
+            hits.add(id);
+    }
+    return hits.size === 1 ? hits.values().next().value : null;
 }
 /** Check whether the input string matches any known agent name or alias. */
 export function isAgentName(input) {

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

@@ -42,8 +42,9 @@ export interface PortOccupant {
     command: string;
 }
 /**
- * Identify the process listening on a TCP port via lsof. Returns null when nothing is bound.
- * Used for clearer error messages when a profile's configured port is taken by a non-debug
- * process (e.g. Comet running without --remote-debugging-port).
+ * Identify the process listening on a TCP port. Returns null when nothing is bound.
+ * Used for clearer error messages when a profile's configured port is taken by a
+ * non-debug process (e.g. Comet running without --remote-debugging-port).
+ * `lsof` on POSIX; `netstat -ano` + `tasklist` on Windows.
  */
 export declare function getPortOccupant(port: number): PortOccupant | null;

package/dist/lib/browser/chrome.js

@@ -6,6 +6,13 @@ import { getProfileRuntimeDir } from './profiles.js';
 import { discoverBrowserWsUrl, registerPipeTransport } from './cdp.js';
 import { readAndResolveBundleEnv, bundleExists } from '../secrets/bundles.js';
 import { writeProfileRuntime, readProfileRuntime } from './runtime-state.js';
+// Windows install roots. Resolve from the environment (fall back to the usual
+// defaults) so per-user installs under %LOCALAPPDATA% and 64-bit Program Files
+// are found, not just the hardcoded x86 path. Only the `win32` entries below use
+// these; on other platforms they compute unused placeholder strings.
+const WIN_PROGRAMFILES = process.env.ProgramFiles || 'C:\\Program Files';
+const WIN_PROGRAMFILES_X86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+const WIN_LOCALAPPDATA = process.env.LOCALAPPDATA || `${os.homedir()}\\AppData\\Local`;
 const BROWSER_PATHS = {
     darwin: {
         chrome: [
@@ -28,16 +35,22 @@ const BROWSER_PATHS = {
     },
     win32: {
         chrome: [
-            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
-            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+            `${WIN_PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe`,
+            `${WIN_PROGRAMFILES_X86}\\Google\\Chrome\\Application\\chrome.exe`,
+            `${WIN_LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
         ],
         comet: [],
-        chromium: [],
+        chromium: [
+            `${WIN_LOCALAPPDATA}\\Chromium\\Application\\chrome.exe`,
+        ],
         brave: [
-            'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+            `${WIN_PROGRAMFILES}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
+            `${WIN_PROGRAMFILES_X86}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
+            `${WIN_LOCALAPPDATA}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
         ],
         edge: [
-            'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+            `${WIN_PROGRAMFILES}\\Microsoft\\Edge\\Application\\msedge.exe`,
+            `${WIN_PROGRAMFILES_X86}\\Microsoft\\Edge\\Application\\msedge.exe`,
         ],
         custom: [],
     },
@@ -308,25 +321,87 @@ function seedDefaultProfileName(userDataDir, profileName) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
+ * (lsof doesn't exist there). Returns false on any tooling error so port
+ * allocation degrades to "assume free" rather than throwing.
+ */
+function isPortInUse(port) {
+    if (process.platform === 'win32') {
+        try {
+            const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            // Lines look like: "  TCP    0.0.0.0:9200    0.0.0.0:0    LISTENING    1234"
+            return out.split('\n').some((line) => {
+                const f = line.trim().split(/\s+/);
+                return f[0] === 'TCP' && f[3] === 'LISTENING' && !!f[1]?.endsWith(`:${port}`);
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        execFileSync('lsof', ['-i', `:${port}`], { stdio: 'ignore' });
+        return true; // lsof found a binding
+    }
+    catch {
+        return false; // nothing on the port
+    }
+}
 export function allocatePort() {
     const base = 9200;
     const max = 9300;
     for (let port = base; port < max; port++) {
-        try {
-            execFileSync('lsof', ['-i', `:${port}`], { stdio: 'ignore' });
-        }
-        catch {
+        if (!isPortInUse(port)) {
             return port;
         }
     }
     throw new Error('No available ports in range 9200-9300');
 }
 /**
- * Identify the process listening on a TCP port via lsof. Returns null when nothing is bound.
- * Used for clearer error messages when a profile's configured port is taken by a non-debug
- * process (e.g. Comet running without --remote-debugging-port).
+ * Identify the process listening on a TCP port. Returns null when nothing is bound.
+ * Used for clearer error messages when a profile's configured port is taken by a
+ * non-debug process (e.g. Comet running without --remote-debugging-port).
+ * `lsof` on POSIX; `netstat -ano` + `tasklist` on Windows.
  */
 export function getPortOccupant(port) {
+    if (process.platform === 'win32') {
+        try {
+            const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            let pid = 0;
+            for (const line of out.split('\n')) {
+                const f = line.trim().split(/\s+/);
+                if (f[0] === 'TCP' && f[3] === 'LISTENING' && f[1]?.endsWith(`:${port}`)) {
+                    pid = parseInt(f[4], 10) || 0;
+                    break;
+                }
+            }
+            if (!pid)
+                return null;
+            let command = 'unknown';
+            try {
+                // tasklist CSV row: "image.exe","1234","Console","1","12,345 K"
+                const tl = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                });
+                const m = tl.match(/^"([^"]+)"/);
+                if (m)
+                    command = m[1];
+            }
+            catch { /* keep 'unknown' */ }
+            return { pid, command };
+        }
+        catch {
+            return null;
+        }
+    }
     try {
         const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpcn'], {
             encoding: 'utf8',

package/dist/lib/browser/ipc.js

@@ -1,6 +1,7 @@
 import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
+import { IS_WINDOWS, ipcEndpoint } from '../platform/index.js';
 import { getHelpersDir } from '../state.js';
 import { startDaemon } from '../daemon.js';
 import { getCliVersion } from '../version.js';
@@ -22,10 +23,38 @@ export function formatBrowserDaemonNotRunningError() {
 export function getSocketPath() {
     return path.join(getHelpersDir(), 'browser', SOCKET_NAME);
 }
+/**
+ * The address the daemon actually listens on / clients connect to: the unix
+ * socket file on POSIX, a `\\.\pipe\` named pipe on Windows. `getSocketPath`
+ * stays the canonical key (and the POSIX socket path); on Windows it's only used
+ * to derive a stable pipe name, never touched on disk.
+ */
+function getIpcEndpoint() {
+    return ipcEndpoint(getSocketPath());
+}
+/** Can we open a connection to the daemon right now? Used on Windows where a
+ * named pipe can't be probed with fs.existsSync. Resolves false on any error. */
+function probeDaemon(endpoint, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const sock = net.createConnection(endpoint);
+        let done = false;
+        const finish = (ok) => { if (done)
+            return; done = true; sock.destroy(); resolve(ok); };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        sock.on('connect', () => { clearTimeout(timer); finish(true); });
+        sock.on('error', () => { clearTimeout(timer); finish(false); });
+    });
+}
+/** Is the daemon reachable? existsSync probe on POSIX, connect probe on Windows. */
+async function isDaemonReachable() {
+    if (IS_WINDOWS)
+        return probeDaemon(getIpcEndpoint());
+    return fs.existsSync(getSocketPath());
+}
 async function waitForSocket(socketPath, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (fs.existsSync(socketPath))
+        if (IS_WINDOWS ? await probeDaemon(getIpcEndpoint()) : fs.existsSync(socketPath))
             return;
         await new Promise((resolve) => setTimeout(resolve, 100));
     }
@@ -39,11 +68,16 @@ export class BrowserIPCServer {
     }
     async start() {
         const socketPath = getSocketPath();
+        const endpoint = getIpcEndpoint();
         const socketDir = path.dirname(socketPath);
         fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
-        fs.chmodSync(socketDir, 0o700);
-        if (fs.existsSync(socketPath)) {
-            fs.unlinkSync(socketPath);
+        if (!IS_WINDOWS) {
+            fs.chmodSync(socketDir, 0o700);
+            // Remove a stale unix socket from a prior crash. (Named pipes are not
+            // filesystem objects and vanish with their owning process.)
+            if (fs.existsSync(socketPath)) {
+                fs.unlinkSync(socketPath);
+            }
         }
         this.server = net.createServer((socket) => {
             let buffer = '';
@@ -70,6 +104,13 @@ export class BrowserIPCServer {
             });
         });
         return new Promise((resolve, reject) => {
+            if (IS_WINDOWS) {
+                // Windows named pipe: no umask/chmod — filesystem perms don't apply and
+                // pipe ACLs default to the creating user.
+                this.server.listen(endpoint, () => resolve());
+                this.server.on('error', (err) => reject(err));
+                return;
+            }
             // Lock down the browser socket dir before opening the socket; on macOS
             // the parent dir is the real local-user boundary for AF_UNIX sockets.
             const prevUmask = process.umask(0o077);
@@ -103,9 +144,11 @@ export class BrowserIPCServer {
             this.server.close();
             this.server = null;
         }
-        const socketPath = getSocketPath();
-        if (fs.existsSync(socketPath)) {
-            fs.unlinkSync(socketPath);
+        if (!IS_WINDOWS) {
+            const socketPath = getSocketPath();
+            if (fs.existsSync(socketPath)) {
+                fs.unlinkSync(socketPath);
+            }
         }
         await this.service.shutdown();
     }
@@ -448,24 +491,27 @@ export async function sendIPCRequest(request, opts = {}) {
 }
 async function sendRawIPCRequest(request, opts = {}) {
     const socketPath = getSocketPath();
+    const endpoint = getIpcEndpoint();
     const autoStartDaemon = opts.autoStartDaemon ?? true;
-    if (!fs.existsSync(socketPath)) {
+    if (!(await isDaemonReachable())) {
         if (!autoStartDaemon) {
             throw new BrowserDaemonNotRunningError();
         }
-        await fs.promises.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
-        await fs.promises.chmod(path.dirname(socketPath), 0o700);
+        if (!IS_WINDOWS) {
+            await fs.promises.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+            await fs.promises.chmod(path.dirname(socketPath), 0o700);
+        }
         startDaemon();
-        if (!fs.existsSync(socketPath)) {
+        if (!(await isDaemonReachable())) {
             await waitForSocket(socketPath, 6000);
         }
-        if (!fs.existsSync(socketPath)) {
+        if (!(await isDaemonReachable())) {
             throw new Error('Failed to start browser daemon');
         }
         await new Promise((r) => setTimeout(r, 300));
     }
     return new Promise((resolve, reject) => {
-        const socket = net.createConnection(socketPath);
+        const socket = net.createConnection(endpoint);
         let buffer = '';
         socket.on('connect', () => {
             socket.write(JSON.stringify(request) + '\n');