@phnx-labs/agents-cli 1.20.8 → 1.20.9

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');

package/dist/lib/daemon.js

@@ -11,7 +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 { isAlive, killTree } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
@@ -437,17 +437,23 @@ export function stopDaemon() {
     }
     const pid = readDaemonPid();
     if (pid) {
-        try {
-            process.kill(pid, 'SIGTERM');
+        if (process.platform === 'win32') {
+            // Windows has no graceful termination signal — terminate the daemon and
+            // its job/browser child tree in one shot (taskkill /T), so stop doesn't
+            // report success while children keep running.
+            killTree(pid);
         }
-        catch { /* process already exited */ }
-        setTimeout(() => {
+        else {
             try {
-                process.kill(pid, 0);
-                process.kill(pid, 'SIGKILL');
+                process.kill(pid, 'SIGTERM');
             }
             catch { /* process already exited */ }
-        }, 5000);
+            // Escalate to a hard tree-kill if it ignored SIGTERM after the grace period.
+            setTimeout(() => {
+                if (isAlive(pid))
+                    killTree(pid);
+            }, 5000);
+        }
     }
     removeDaemonPid();
     return true;
@@ -479,6 +485,12 @@ export function signalDaemonReload() {
     const pid = readDaemonPid();
     if (!pid)
         return false;
+    if (process.platform === 'win32') {
+        // Windows has no SIGHUP, so signal-based live reload isn't available. Sending
+        // it would throw; instead report "not reloaded" so callers tell the user to
+        // restart the daemon to pick up job changes.
+        return false;
+    }
     try {
         process.kill(pid, 'SIGHUP');
         return true;

package/dist/lib/fs-walk.d.ts

@@ -1,2 +1,8 @@
-/** Walk a directory recursively for files with a given extension. */
+/** Walk a directory recursively for files with a given extension, newest first. */
 export declare function walkForFiles(dir: string, ext: string, limit: number): string[];
+/**
+ * Return the newest mtime (ms) among files with the given extension, or null
+ * when none match. Single pass tracking the max — no collection or sort.
+ * Hot-path helper for the `agents run` account-recency probe.
+ */
+export declare function latestFileMtimeMs(dir: string, ext: string): number | null;

package/dist/lib/fs-walk.js

@@ -1,35 +1,69 @@
 import * as fs from 'fs';
 import * as path from 'path';
-/** Walk a directory recursively for files with a given extension. */
-export function walkForFiles(dir, ext, limit) {
-    const results = [];
+/**
+ * Recursively visit files with a given extension, calling onFile with each
+ * match's path and mtime. Uses dirent types from readdir so only matching
+ * files (and symlinks, to preserve follow semantics) pay a stat call —
+ * directories are classified for free. On large session trees this roughly
+ * halves the syscall count versus stat-per-entry.
+ */
+function walkEntries(dir, ext, onFile) {
     function walk(d, depth) {
         if (depth > 5)
             return;
         let entries;
         try {
-            entries = fs.readdirSync(d);
+            entries = fs.readdirSync(d, { withFileTypes: true });
         }
         catch {
             return;
         }
         for (const entry of entries) {
-            const full = path.join(d, entry);
-            const stat = safeStatSync(full);
-            if (!stat)
-                continue;
-            if (stat.isDirectory()) {
+            const full = path.join(d, entry.name);
+            let isDirectory = entry.isDirectory();
+            // Symlinks: dirent reports the link itself, but the previous stat-based
+            // walk followed links into directories and matched linked files. Stat
+            // (which follows) only for symlinks to keep that behavior.
+            if (entry.isSymbolicLink()) {
+                const stat = safeStatSync(full);
+                if (!stat)
+                    continue;
+                isDirectory = stat.isDirectory();
+            }
+            if (isDirectory) {
                 walk(full, depth + 1);
             }
-            else if (entry.endsWith(ext)) {
-                results.push({ path: full, mtime: stat.mtimeMs });
+            else if (entry.name.endsWith(ext)) {
+                const stat = safeStatSync(full);
+                if (stat)
+                    onFile(full, stat.mtimeMs);
             }
         }
     }
     walk(dir, 0);
+}
+/** Walk a directory recursively for files with a given extension, newest first. */
+export function walkForFiles(dir, ext, limit) {
+    const results = [];
+    walkEntries(dir, ext, (filePath, mtimeMs) => {
+        results.push({ path: filePath, mtime: mtimeMs });
+    });
     results.sort((a, b) => b.mtime - a.mtime);
     return results.slice(0, limit).map(r => r.path);
 }
+/**
+ * Return the newest mtime (ms) among files with the given extension, or null
+ * when none match. Single pass tracking the max — no collection or sort.
+ * Hot-path helper for the `agents run` account-recency probe.
+ */
+export function latestFileMtimeMs(dir, ext) {
+    let latest = null;
+    walkEntries(dir, ext, (_filePath, mtimeMs) => {
+        if (latest === null || mtimeMs > latest)
+            latest = mtimeMs;
+    });
+    return latest;
+}
 function safeStatSync(p) {
     try {
         return fs.statSync(p);

package/dist/lib/git.js

@@ -8,6 +8,7 @@
 import simpleGit from 'simple-git';
 import * as fs from 'fs';
 import * as path from 'path';
+import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
 import { getPackageLocalPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
@@ -127,8 +128,10 @@ export function parseSource(source) {
             ref,
         };
     }
-    // Local path (absolute or relative)
-    if (cleanSource.startsWith('/') || cleanSource.startsWith('./') || cleanSource.startsWith('../')) {
+    // Local path (absolute or relative). On Windows also recognize drive-letter
+    // (C:\…) and UNC (\\…) roots, which the POSIX prefixes miss.
+    if (cleanSource.startsWith('/') || cleanSource.startsWith('./') || cleanSource.startsWith('../')
+        || (IS_WINDOWS && isWindowsAbsolutePath(cleanSource))) {
         if (fs.existsSync(cleanSource)) {
             return {
                 type: 'local',

package/dist/lib/log-follow.d.ts

@@ -0,0 +1,7 @@
+export interface FollowOptions {
+    /** Poll interval in milliseconds (default 500). */
+    intervalMs?: number;
+    /** Start at the current end of file (skip existing content). Default false. */
+    fromEnd?: boolean;
+}
+export declare function followFile(filePath: string, onChunk: (text: string) => void, opts?: FollowOptions): () => void;

package/dist/lib/log-follow.js

@@ -0,0 +1,65 @@
+/**
+ * Cross-platform `tail -f`.
+ *
+ * Replaces spawning the POSIX `tail` binary (absent on Windows) with a poll-based
+ * follower that behaves identically on every platform and needs no external
+ * dependency. Reads bytes appended since the last position every `intervalMs`;
+ * resets to 0 if the file shrinks (truncation / log rotation). The active timer
+ * keeps the event loop alive, so callers just register a SIGINT handler that
+ * calls the returned stop().
+ */
+import * as fs from 'fs';
+export function followFile(filePath, onChunk, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 500;
+    let pos = 0;
+    if (opts.fromEnd) {
+        try {
+            pos = fs.statSync(filePath).size;
+        }
+        catch {
+            pos = 0;
+        }
+    }
+    else {
+        try {
+            const initial = fs.readFileSync(filePath);
+            if (initial.length > 0)
+                onChunk(initial.toString('utf-8'));
+            pos = initial.length;
+        }
+        catch { /* file may not exist yet — start at 0 and wait for it to appear */ }
+    }
+    const poll = () => {
+        let size;
+        try {
+            size = fs.statSync(filePath).size;
+        }
+        catch {
+            return; /* gone / not yet created */
+        }
+        if (size < pos)
+            pos = 0; // truncated or rotated — re-read from the top
+        if (size <= pos)
+            return;
+        let fd;
+        try {
+            fd = fs.openSync(filePath, 'r');
+            const buf = Buffer.alloc(size - pos);
+            const bytes = fs.readSync(fd, buf, 0, buf.length, pos);
+            pos += bytes;
+            if (bytes > 0)
+                onChunk(buf.subarray(0, bytes).toString('utf-8'));
+        }
+        catch { /* transient read error — retry next tick */ }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* noop */ }
+            }
+        }
+    };
+    const timer = setInterval(poll, intervalMs);
+    return () => clearInterval(timer);
+}