@phnx-labs/agents-cli 1.20.27 → 1.20.28

package/dist/lib/migrate.js

@@ -9,6 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
+import { createLink } from './platform/index.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -57,7 +58,7 @@ export function foldLegacySystemRepo() {
         try {
             fs.renameSync(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
             try {
-                fs.symlinkSync(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
+                createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
             }
             catch { /* best-effort */ }
             console.error('Folded ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
@@ -71,7 +72,7 @@ export function foldLegacySystemRepo() {
         copyDirSkipExisting(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
         fs.rmSync(LEGACY_SYSTEM_DIR, { recursive: true, force: true });
         try {
-            fs.symlinkSync(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
+            createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
         }
         catch { /* best-effort */ }
         console.error('Merged ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
@@ -698,14 +699,14 @@ function repairAgentConfigSymlinks() {
                 continue; // already correct
             try {
                 fs.unlinkSync(symlinkPath);
-                fs.symlinkSync(userTarget, symlinkPath);
+                createLink(userTarget, symlinkPath);
                 repaired++;
             }
             catch { /* best-effort */ }
         }
         else if (!stat) {
             try {
-                fs.symlinkSync(userTarget, symlinkPath);
+                createLink(userTarget, symlinkPath);
                 repaired++;
             }
             catch { /* best-effort */ }
@@ -798,8 +799,11 @@ export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_D
             const realBinary = findInPath(cli);
             try {
                 fs.unlinkSync(binLink);
+                // createLink: a real symlink where the OS allows it (POSIX, and Windows
+                // with the symlink privilege), copy-fallback otherwise — so the repair
+                // lands a working binary on Windows runners without the symlink right.
                 if (realBinary)
-                    fs.symlinkSync(realBinary, binLink);
+                    createLink(realBinary, binLink);
                 repaired++;
             }
             catch { /* best-effort */ }

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

@@ -1,5 +1,15 @@
 /** PATH-search command for the platform: `where` on Windows, else `which`. */
 export declare function whichCommand(platform?: NodeJS.Platform): string;
+/**
+ * Does spawning `binary` require `shell: true` on this platform?
+ *
+ * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
+ * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
+ * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
+ * command name (not an absolute path) needs the same PATHEXT resolution. Both
+ * cases require the shell. Always false off Windows, where direct exec is right.
+ */
+export declare function needsWindowsShell(binary: string, platform?: NodeJS.Platform): boolean;
 /**
  * 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

package/dist/lib/platform/exec.js

@@ -2,10 +2,27 @@
  * Executable resolution, platform-aware.
  */
 import { execFileSync } from 'child_process';
+import * as path from 'path';
 /** PATH-search command for the platform: `where` on Windows, else `which`. */
 export function whichCommand(platform = process.platform) {
     return platform === 'win32' ? 'where' : 'which';
 }
+/**
+ * Does spawning `binary` require `shell: true` on this platform?
+ *
+ * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
+ * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
+ * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
+ * command name (not an absolute path) needs the same PATHEXT resolution. Both
+ * cases require the shell. Always false off Windows, where direct exec is right.
+ */
+export function needsWindowsShell(binary, platform = process.platform) {
+    if (platform !== 'win32')
+        return false;
+    // path.win32.isAbsolute, not path.isAbsolute: the latter uses the HOST's rules,
+    // so a Windows path would read as relative when this runs on a Linux CI host.
+    return !path.win32.isAbsolute(binary) || /\.(cmd|bat)$/i.test(binary);
+}
 /**
  * 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

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

@@ -17,6 +17,7 @@ export declare const IS_MACOS: boolean;
 export declare const IS_LINUX: boolean;
 export * from './paths.js';
 export * from './exec.js';
+export * from './links.js';
 export * from './process.js';
 export * from './ipc.js';
 export * from './winpath.js';

package/dist/lib/platform/index.js

@@ -17,6 +17,7 @@ export const IS_MACOS = process.platform === 'darwin';
 export const IS_LINUX = process.platform === 'linux';
 export * from './paths.js';
 export * from './exec.js';
+export * from './links.js';
 export * from './process.js';
 export * from './ipc.js';
 export * from './winpath.js';

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

@@ -0,0 +1,15 @@
+/**
+ * Create a link at `dst` pointing to `src`, portable across platforms.
+ *
+ * - **Directory** target: junction on Windows (no Developer Mode needed), plain
+ *   symlink on POSIX.
+ * - **File** target: symlink, falling back to `copyFileSync` when Windows
+ *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
+ *   point-in-time snapshot, not a live link; acceptable for the immutable
+ *   targets we link (binaries, config files).
+ *
+ * `dst` must not already exist. Callers that replace atomically should link to a
+ * temp name and `rename` over the destination, exactly as before — the copy
+ * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
+ */
+export declare function createLink(src: string, dst: string): void;

package/dist/lib/platform/links.js

@@ -0,0 +1,42 @@
+/**
+ * Filesystem linking, platform-aware.
+ *
+ * POSIX symlinks have no portable equivalent on Windows: directory symlinks and
+ * file symlinks both require either Administrator or Developer Mode, while
+ * *junctions* (directories only) need no elevation. `createLink` picks the form
+ * that works without privilege — junction for directories — and falls back to a
+ * copy for file links when the OS refuses the symlink.
+ */
+import * as fs from 'fs';
+/**
+ * Create a link at `dst` pointing to `src`, portable across platforms.
+ *
+ * - **Directory** target: junction on Windows (no Developer Mode needed), plain
+ *   symlink on POSIX.
+ * - **File** target: symlink, falling back to `copyFileSync` when Windows
+ *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
+ *   point-in-time snapshot, not a live link; acceptable for the immutable
+ *   targets we link (binaries, config files).
+ *
+ * `dst` must not already exist. Callers that replace atomically should link to a
+ * temp name and `rename` over the destination, exactly as before — the copy
+ * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
+ */
+export function createLink(src, dst) {
+    const win = process.platform === 'win32';
+    const isDir = fs.statSync(src).isDirectory();
+    // Type is ignored on POSIX; on Windows, junction (dir) avoids the elevation a
+    // dir symlink would need, and 'file' is the explicit file-symlink form.
+    const type = win ? (isDir ? 'junction' : 'file') : undefined;
+    try {
+        fs.symlinkSync(src, dst, type);
+    }
+    catch (err) {
+        const code = err.code;
+        if (win && !isDir && (code === 'EPERM' || code === 'ENOSYS')) {
+            fs.copyFileSync(src, dst);
+            return;
+        }
+        throw err;
+    }
+}

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

@@ -27,3 +27,21 @@ export declare function homeDir(): string;
  * whether to apply it (typically gated on win32).
  */
 export declare function isWindowsAbsolutePath(p: string): boolean;
+/**
+ * Fold backslashes to forward slashes. Use when a path is going into a string
+ * that must read the same on every OS — a doc-comparable display path, a regex
+ * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
+ * (no backslashes) it returns the value unchanged.
+ */
+export declare function toPosix(p: string): string;
+/**
+ * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
+ * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
+ * folds path separators and spaces to `_`. For a POSIX path this produces the
+ * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
+ * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
+ *
+ * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
+ *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
+ */
+export declare function toPortableKey(p: string): string;

package/dist/lib/platform/paths.js

@@ -56,3 +56,25 @@ export function homeDir() {
 export function isWindowsAbsolutePath(p) {
     return WIN_DRIVE_RE.test(p) || p.startsWith('\\\\');
 }
+/**
+ * Fold backslashes to forward slashes. Use when a path is going into a string
+ * that must read the same on every OS — a doc-comparable display path, a regex
+ * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
+ * (no backslashes) it returns the value unchanged.
+ */
+export function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
+ * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
+ * folds path separators and spaces to `_`. For a POSIX path this produces the
+ * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
+ * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
+ *
+ * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
+ *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
+ */
+export function toPortableKey(p) {
+    return p.replace(/^([a-zA-Z]):/, '$1').replace(/[\\/ ]/g, '_');
+}

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

@@ -0,0 +1,28 @@
+/** The XDG user-bin dir, `~/.local/bin`. */
+export declare function localBinDir(home?: string): string;
+export interface SymlinkResult {
+    /** A usable symlink to `target` exists at the path after this call. */
+    ok: boolean;
+    /** True only when this call created the symlink (false = already correct, or left untouched). */
+    created: boolean;
+    /** Why an existing entry was left untouched (set only when ok is false). */
+    skippedReason?: string;
+    path: string;
+}
+/**
+ * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
+ * pre-existing real file or a symlink that already points elsewhere — most
+ * importantly a developer's `scripts/install.sh` dev build at
+ * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
+ * `target`, is created/treated as ok. Idempotent.
+ */
+export declare function ensureLocalBinSymlink(name: string, target: string, dir?: string): SymlinkResult;
+/**
+ * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
+ * for the consumers we heal. Best-effort: any probe failure returns false so
+ * the caller heals rather than wrongly assuming success. `command -v` is a
+ * POSIX builtin.
+ */
+export declare function loginShellResolves(cmd: string): boolean;
+/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
+export declare function dirOnLoginPath(dir: string): boolean;

package/dist/lib/platform/posixpath.js

@@ -0,0 +1,153 @@
+/**
+ * POSIX login-PATH primitives for making the `agents` command resolvable.
+ *
+ * The Unix analog of winpath.ts. `agents`/`ag` land on PATH only via npm's
+ * bin symlink into the npm global-bin dir; under nvm (and other per-user node
+ * prefixes) that dir is absent from a *non-interactive login* shell's PATH, so
+ * `bash -lc 'agents …'` fails with command-not-found. That breaks every
+ * consumer that drives a login shell on the box: `agents secrets export --host`
+ * (which runs `bash -lc 'agents secrets import …'` on the remote) and the
+ * routines daemon (`src/lib/daemon.ts`, which falls back to bare `agents`).
+ *
+ * The fix mirrors the Windows postinstall branch (which registers npm's
+ * global-bin dir on the user PATH): symlink the entrypoint into ~/.local/bin —
+ * the XDG user-bin dir that mainstream distros auto-add to the login PATH when
+ * it exists (Debian/Ubuntu via ~/.profile, Fedora via /etc/profile.d) — and,
+ * where it is not yet on PATH, the caller adds it.
+ *
+ * Leaf module — imports only child_process / fs / os / path so it is cheap to
+ * load from the npm lifecycle script without pulling the rest of the CLI.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** The XDG user-bin dir, `~/.local/bin`. */
+export function localBinDir(home = os.homedir()) {
+    return path.join(home, '.local', 'bin');
+}
+/**
+ * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
+ * pre-existing real file or a symlink that already points elsewhere — most
+ * importantly a developer's `scripts/install.sh` dev build at
+ * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
+ * `target`, is created/treated as ok. Idempotent.
+ */
+export function ensureLocalBinSymlink(name, target, dir = localBinDir()) {
+    const linkPath = path.join(dir, name);
+    const want = path.resolve(target);
+    let current = null;
+    try {
+        current = fs.readlinkSync(linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EINVAL') {
+            // The path exists but is not a symlink — a real file/dir. Never clobber.
+            return { ok: false, created: false, skippedReason: 'a non-symlink file already exists here', path: linkPath };
+        }
+        if (code !== 'ENOENT') {
+            return { ok: false, created: false, skippedReason: err.message, path: linkPath };
+        }
+        // ENOENT — nothing there; fall through to create.
+    }
+    if (current !== null) {
+        const resolved = path.isAbsolute(current) ? current : path.resolve(dir, current);
+        if (resolved === want)
+            return { ok: true, created: false, path: linkPath };
+        // Points somewhere else (e.g. a dev build) — the existing link wins.
+        return { ok: false, created: false, skippedReason: `symlink already points to ${current}`, path: linkPath };
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.symlinkSync(target, linkPath);
+    return { ok: true, created: true, path: linkPath };
+}
+/**
+ * Absolute path to `bash`. We probe bash specifically — NOT the user's $SHELL —
+ * because the consumers we are healing run `bash -lc` regardless of login shell:
+ * `secrets export --host` builds `bash -lc 'agents secrets import …'` for the
+ * remote, and the routines daemon resolves `agents` the same way. On a box whose
+ * login shell is zsh, zsh's login PATH may lack ~/.local/bin while bash's
+ * includes it (Debian/Ubuntu ~/.profile) — so probing $SHELL would give the
+ * wrong answer for what the consumer actually sees. Resolve from the *current*
+ * PATH (the install process has one) and fall back to /bin/bash.
+ */
+function bashPath() {
+    const found = (process.env.PATH || '')
+        .split(path.delimiter)
+        .map((d) => (d ? path.join(d, 'bash') : ''))
+        .find((p) => {
+        if (!p)
+            return false;
+        try {
+            fs.accessSync(p, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return found || '/bin/bash';
+}
+/**
+ * Environment for the probe shell that reproduces a *fresh* `bash -lc` — the
+ * PATH that `ssh host 'bash -lc …'` and the routines daemon actually get — and
+ * NOT the nvm/npm-augmented PATH of the install process.
+ *
+ * This is the crux: `npm i -g` (and a dev `bun run`) execute under nvm, so the
+ * caller's PATH already contains nvm's bin. A spawned shell inherits that PATH,
+ * so it would resolve `agents` and the heal would skip — during the very nvm
+ * install it exists to fix. We strip PATH (and nvm's hint vars) so the login
+ * profile rebuilds PATH from scratch, exactly as an incoming SSH command shell
+ * does. Login bash still sources /etc/profile + ~/.profile (which adds
+ * ~/.local/bin) but bails out of ~/.bashrc's nvm block early because it is
+ * non-interactive — which is precisely why bare `agents` is missing there.
+ */
+function loginProbeEnv() {
+    const env = { ...process.env };
+    delete env.PATH;
+    delete env.NVM_BIN;
+    delete env.NVM_INC;
+    for (const k of Object.keys(env))
+        if (k.startsWith('npm_'))
+            delete env[k];
+    return env;
+}
+/**
+ * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
+ * for the consumers we heal. Best-effort: any probe failure returns false so
+ * the caller heals rather than wrongly assuming success. `command -v` is a
+ * POSIX builtin.
+ */
+export function loginShellResolves(cmd) {
+    try {
+        const res = spawnSync(bashPath(), ['-lc', `command -v ${cmd}`], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: loginProbeEnv(),
+        });
+        return res.status === 0 && !!res.stdout && res.stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
+export function dirOnLoginPath(dir) {
+    try {
+        const res = spawnSync(bashPath(), ['-lc', 'printf %s "$PATH"'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: loginProbeEnv(),
+        });
+        if (res.status !== 0 || !res.stdout)
+            return false;
+        const want = path.resolve(dir);
+        return res.stdout.split(':').some((p) => p && path.resolve(p) === want);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/plugins.d.ts

@@ -123,6 +123,16 @@ export declare function saveUserConfig(pluginName: string, config: Record<string
  * Returns names of missing dependencies (warning only — not a hard error).
  */
 export declare function checkPluginDependencies(manifest: PluginManifest): string[];
+/**
+ * Reconstruct a MarketplaceSpec from a marketplace name. The inverse of
+ * marketplaceNameFor(): "agents-cli" → user, "agents-project" → project,
+ * "agents-system" → system, "agents-<alias>" → extra. The per-version
+ * marketplace operations only key off the name (never spec.root), but we
+ * resolve the real source root anyway so the spec is honest for any caller that
+ * inspects it (e.g. descriptionFor, which would otherwise label the system
+ * marketplace as an extra repo named "system").
+ */
+export declare function marketplaceSpecForName(name: string | undefined, cwd?: string): MarketplaceSpec;
 /**
  * Sync a plugin to a specific agent version's home directory.
  *

package/dist/lib/plugins.js

@@ -397,7 +397,7 @@ export function checkPluginDependencies(manifest) {
  * inspects it (e.g. descriptionFor, which would otherwise label the system
  * marketplace as an extra repo named "system").
  */
-function marketplaceSpecForName(name, cwd = process.cwd()) {
+export function marketplaceSpecForName(name, cwd = process.cwd()) {
     if (!name || name === MARKETPLACE_NAME)
         return { kind: 'user' };
     if (name === SYSTEM_MARKETPLACE_NAME) {

package/dist/lib/project-launch.js

@@ -47,6 +47,7 @@ import * as path from 'path';
 import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
 import { getVersionHomePath } from './versions.js';
+import { toPortableKey } from './platform/index.js';
 import { transformSubagentForClaude } from './subagents.js';
 import { compileRulesForProject } from './rules/compile.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
@@ -88,15 +89,17 @@ export function runLaunchSync(opts) {
 }
 /**
  * Path of the shim's skip-fast sentinel for this (agent, version, cwd) tuple.
- * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation):
- *   slug = PWD with `/` → `_` and ` ` → `_`
+ * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation),
+ * which is the canonical `toPortableKey` mapping: drop the Windows drive colon
+ * and fold `\`, `/`, and ` ` → `_`. On POSIX this is byte-identical to the old
+ * `/` and ` ` → `_` slug; on Windows it yields a legal filename (no `C:\`).
  *
  * Cache leak note: this dir accumulates one zero-byte file per
  * (agent, version, project) tuple ever launched. Disk impact is negligible
  * (inodes only). A periodic GC belongs in `agents prune` — follow-up.
  */
 function launchSentinelPath(agent, version, cwd) {
-    const slug = cwd.replace(/\//g, '_').replace(/ /g, '_');
+    const slug = toPortableKey(cwd);
     // Prefer $HOME (respects test overrides + matches bash's $HOME expansion in
     // the shim), fall back to os.homedir() so the lookup never resolves to '/'
     // if HOME is somehow unset.

package/dist/lib/sandbox.js

@@ -11,6 +11,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
+import { createLink } from './platform/index.js';
 function resolveRealHome() {
     const home = os.homedir();
     try {
@@ -126,9 +127,11 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
         fs.mkdirSync(parentDir, { recursive: true });
         if (!fs.existsSync(symlinkTarget)) {
             try {
-                fs.symlinkSync(realPath, symlinkTarget);
+                // createLink uses a junction for directories on Windows (no elevation),
+                // a plain symlink on POSIX — allowed dirs are directories.
+                createLink(realPath, symlinkTarget);
             }
-            catch { /* symlink already exists */ }
+            catch { /* link already exists or refused */ }
         }
     }
 }

package/dist/lib/self-update.js

@@ -16,6 +16,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
+import { needsWindowsShell } from './platform/index.js';
 export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
 /**
  * The directory bun installs global packages into:
@@ -145,7 +146,10 @@ export async function installPackageIntoPrefix(spec, prefix) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
-    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts']);
+    // On Windows `npm` is `npm.cmd`; execFile cannot run it without a shell (ENOENT).
+    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts'], {
+        shell: needsWindowsShell('npm'),
+    });
 }
 /**
  * Install `spec` into bun's global store with `bun add -g`. bun writes to
@@ -159,7 +163,8 @@ export async function installPackageWithBun(spec) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
-    await execFileAsync('bun', ['add', '-g', spec]);
+    // On Windows `bun` resolves to `bun.exe`/`bun.cmd`; force shell for the .cmd case.
+    await execFileAsync('bun', ['add', '-g', spec], { shell: needsWindowsShell('bun') });
 }
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {

package/dist/lib/session/db.d.ts

@@ -45,6 +45,10 @@ export interface QueryOptions {
     /** Match any session whose cwd equals this or is a descendant of it. */
     cwdPrefix?: string;
     project?: string;
+    /** Match the full session id or short id, case-insensitively (exact). */
+    idExact?: string;
+    /** Match sessions whose id or short id begins with this (case-insensitive prefix). */
+    idPrefix?: string;
     sinceMs?: number;
     untilMs?: number;
     limit?: number;
@@ -118,6 +122,16 @@ export declare function upsertSessionsBatch(entries: Array<{
  * Leaves FTS5 content/topic/project untouched — cheap to call every run.
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
+/**
+ * Sync topics (session titles) for a set of sessions, keyed by id. For agents
+ * whose human-readable title lives in a side index that updates independently
+ * of the transcript (Codex `session_index.jsonl`), the per-file scan can't see
+ * a title that lands later. This applies those titles by id, updating both
+ * `sessions.topic` and the FTS5 topic column. Only ever sets a non-empty title
+ * and only when it differs from the stored value — cheap to call every run.
+ * Returns the number of rows updated.
+ */
+export declare function syncTopics(topicMap: Map<string, string>): number;
 /** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
@@ -160,6 +174,15 @@ export declare function getAllFilePaths(): Set<string>;
 export declare function getSessionsByFilePaths(paths: string[]): Map<string, SessionMeta>;
 /** Look up a single session by its unique ID. */
 export declare function getSessionById(id: string): SessionMeta | null;
+/**
+ * Resolve a full-or-partial session id against the index, exact-first then
+ * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
+ * SQLite table instead of a pre-loaded array. Matches both the full id and the
+ * short id. An exact hit short-circuits so a complete id never also drags in its
+ * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
+ * ambiguous prefix disambiguates against the caller's context.
+ */
+export declare function findSessionsById(idQuery: string, scope?: Pick<QueryOptions, 'agent' | 'version' | 'cwd' | 'project'>): SessionMeta[];
 /** A single full-text search result with ranking score. */
 export interface FtsHit {
     sessionId: string;