@phnx-labs/agents-cli 1.22.25 → 1.22.27

package/dist/lib/sandbox.js

@@ -9,7 +9,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
 import { safeJoin } from './paths.js';
 import { createLink } from './platform/index.js';
@@ -91,15 +90,14 @@ export function prepareJobHome(config) {
     const overlayHome = getJobHomePath(config.name);
     cleanJobHome(config.name);
     fs.mkdirSync(overlayHome, { recursive: true });
+    // gemini is hard-deprecated: runner.ts rejects a gemini routine before it
+    // ever reaches prepareJobHome, so there is deliberately no branch here.
     if (config.agent === 'claude') {
         generateClaudeConfig(overlayHome, config);
     }
     else if (config.agent === 'codex') {
         generateCodexConfig(overlayHome, config);
     }
-    else if (config.agent === 'gemini') {
-        generateGeminiConfig(overlayHome, config);
-    }
     else if (config.agent === 'cursor') {
         generateCursorConfig(overlayHome);
     }
@@ -270,18 +268,3 @@ export function generateCodexConfig(overlayHome, config) {
     }
     fs.writeFileSync(path.join(codexDir, 'config.toml'), lines.join('\n') + '\n', 'utf-8');
 }
-/** Generate a Gemini settings.json in the overlay from the job's config block. */
-export function generateGeminiConfig(overlayHome, config) {
-    const settingsPath = path.join(overlayHome, '.gemini', 'settings.json');
-    updateGeminiSettings(settingsPath, (settings) => {
-        if (config.config?.model) {
-            settings.model = config.config.model;
-        }
-        if (config.config) {
-            for (const [key, value] of Object.entries(config.config)) {
-                settings[key] = value;
-            }
-        }
-        setGeminiAutoUpdateDisabled(settings);
-    });
-}

package/dist/lib/secrets/agent.js

@@ -37,6 +37,7 @@ import { getCliLaunch } from '../cli-entry.js';
 import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
 import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
+import { MAX_LEASE_MS, MIN_LEASE_MS } from './lease.js';
 // Re-exported so callers already reaching for agent.js keep one obvious home for
 // the scope vocabulary; the definitions live in the leaf module scope.ts because
 // agent.ts and session-store.ts import each other and a cyclic `const` read can
@@ -1120,8 +1121,8 @@ export function secretsAgentDurable() {
 /** Minimum / maximum bounds for the configurable hold window. A too-small value
  * would defeat the broker (constant re-prompts); a too-large one pins secrets in
  * memory far longer than intended. */
-export const MIN_HOLD_MS = 60 * 1000; // 1m
-export const MAX_HOLD_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+export const MIN_HOLD_MS = MIN_LEASE_MS;
+export const MAX_HOLD_MS = MAX_LEASE_MS;
 /**
  * How long an unlocked / auto-cached bundle is held before the next read
  * re-prompts. Defaults to DEFAULT_TTL_MS (7d); override with

package/dist/lib/secrets/lease.d.ts

@@ -0,0 +1,25 @@
+export declare const MIN_LEASE_MS: number;
+export declare const MAX_LEASE_MS: number;
+export interface SecretLease {
+    id: string;
+    bundle: string;
+    keys: string[];
+    createdAt: number;
+    expiresAt: number;
+    harness: string;
+    sleepPersist: boolean;
+}
+export declare function clampLeaseTtlMs(ttlMs: number): number;
+export declare function normalizeLeaseKeys(keys: readonly string[], availableKeys: readonly string[]): string[];
+export declare function createSecretLease(input: {
+    bundle: string;
+    keys: readonly string[];
+    availableKeys: readonly string[];
+    ttlMs: number;
+    now?: number;
+    id?: string;
+    harness?: string;
+    sleepPersist?: boolean;
+}): SecretLease;
+export declare function leaseIsActive(lease: SecretLease, now?: number): boolean;
+export declare function selectLeasedEnv(lease: SecretLease, env: Record<string, string>, now?: number): Record<string, string>;

package/dist/lib/secrets/lease.js

@@ -0,0 +1,44 @@
+import { randomBytes } from 'crypto';
+import { GLOBAL_HARNESS } from './scope.js';
+export const MIN_LEASE_MS = 60 * 1000;
+export const MAX_LEASE_MS = 30 * 24 * 60 * 60 * 1000;
+export function clampLeaseTtlMs(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new Error('Lease duration must be a positive finite number.');
+    }
+    return Math.min(Math.max(Math.floor(ttlMs), MIN_LEASE_MS), MAX_LEASE_MS);
+}
+export function normalizeLeaseKeys(keys, availableKeys) {
+    const requested = [...new Set(keys.map((key) => key.trim()).filter(Boolean))].sort();
+    if (requested.length === 0)
+        throw new Error('A secret lease requires at least one key.');
+    const available = new Set(availableKeys);
+    const missing = requested.filter((key) => !available.has(key));
+    if (missing.length > 0)
+        throw new Error(`Unknown secret lease key(s): ${missing.join(', ')}`);
+    return requested;
+}
+export function createSecretLease(input) {
+    const createdAt = input.now ?? Date.now();
+    const ttlMs = clampLeaseTtlMs(input.ttlMs);
+    return {
+        id: input.id ?? randomBytes(12).toString('hex'),
+        bundle: input.bundle,
+        keys: normalizeLeaseKeys(input.keys, input.availableKeys),
+        createdAt,
+        expiresAt: createdAt + ttlMs,
+        harness: input.harness ?? GLOBAL_HARNESS,
+        sleepPersist: input.sleepPersist ?? false,
+    };
+}
+export function leaseIsActive(lease, now = Date.now()) {
+    return now < lease.expiresAt;
+}
+export function selectLeasedEnv(lease, env, now = Date.now()) {
+    if (!leaseIsActive(lease, now))
+        throw new Error(`Secret lease '${lease.id}' has expired.`);
+    const missing = lease.keys.filter((key) => typeof env[key] !== 'string');
+    if (missing.length > 0)
+        throw new Error(`Secret lease '${lease.id}' is missing value(s): ${missing.join(', ')}`);
+    return Object.fromEntries(lease.keys.map((key) => [key, env[key]]));
+}

package/dist/lib/secrets/push.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Serialize a resolved env map to `.env` lines that round-trip losslessly through
+ * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
+ * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
+ * value survives unchanged with no escaping. Newlines would break its line-based
+ * parse, so multi-line values are rejected rather than silently corrupted.
+ */
+export declare function bundleEnvToDotenv(env: Record<string, string>): string;
+/** Where the bundle should live ON THE REMOTE. */
+export type RemoteBackend = 'keychain' | 'file';
+/** A bundle read once, ready to push to any number of hosts. */
+export interface ResolvedBundleForPush {
+    /** key -> value. Never logged; only its KEY NAMES are ever surfaced. */
+    env: Record<string, string>;
+    /** The same values as a dotenv blob, shipped over ssh stdin (never argv). */
+    dotenv: string;
+    keyCount: number;
+}
+export interface PushBundleOptions {
+    remoteBackend: RemoteBackend;
+    /** Overwrite a key that already exists on the remote. */
+    force?: boolean;
+    /**
+     * Forwarded to the remote as the FIRST stdin line for the FILE backend only,
+     * and only when non-empty.
+     *
+     * Empty is the DEFAULT and the good path: the remote's file store then
+     * auto-provisions its own machine-local key (0600, `~/.agents/.secrets-key/`)
+     * and reads headlessly. Setting this keys the remote bundle under a shared
+     * off-disk secret instead — an opt-in, never a requirement. Requiring one is
+     * what pushed operators toward exporting the master key fleet-wide (RUSH-1968).
+     */
+    passphrase?: string;
+    /** Label for the audit trail — `export --host` vs `fleet apply`. */
+    operation: string;
+}
+export interface PushBundleResult {
+    ok: boolean;
+    host: string;
+    bundle: string;
+    keyCount: number;
+    /** One line for the caller to render. Never contains a secret value. */
+    message: string;
+}
+/**
+ * Read and resolve a bundle once, for pushing to one or more hosts.
+ *
+ * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
+ * passed: storage-shaped values, and the headless guard that fails fast rather
+ * than popping Touch ID inside an automated run.
+ */
+export declare function resolveBundleForPush(bundle: string, caller: string): ResolvedBundleForPush;
+/**
+ * WHICH transport a (backend, target-OS) pair selects, and the exact bytes it
+ * will send. One of four outcomes, and picking the wrong one is silent: a
+ * Windows target handed a POSIX `bash -lc` produces garbage, and a Windows
+ * target handed `--from -` hangs forever on a stdin the `agents.ps1` shim never
+ * forwards. Neither shows up as a failed ssh, so the selection is the thing
+ * worth pinning.
+ *
+ * Separated from execution so it is decidable without a network: the branch is
+ * chosen from the device registry alone, and `pushResolvedBundleToHost` below
+ * does nothing but run what this returns.
+ */
+export type PushTransport = 
+/** No supported command exists for this pair — fail loud, never a wrong path. */
+{
+    kind: 'refuse';
+    message: string;
+}
+/** A command sent over the raw ssh engine, with the .env on stdin. */
+ | {
+    kind: 'ssh';
+    remoteCmd: string;
+    input: string;
+}
+/** The OS-aware `agents secrets` wrapper, the READ inverse's own path. */
+ | {
+    kind: 'remote-secrets';
+    args: string[];
+    input: string;
+};
+/** Choose the transport for one push. Pure: registry read in, plan out. */
+export declare function planPushTransport(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushTransport;
+/**
+ * Push an already-resolved bundle to ONE host.
+ *
+ * Drives the remote's own `agents secrets import --from -`, so the values land
+ * in the remote's chosen backend and the .env is read off ssh stdin rather than
+ * parsed by a remote shell. `import` auto-creates the bundle.
+ */
+export declare function pushResolvedBundleToHost(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;
+/** Resolve and push in one call — for a single host. */
+export declare function pushBundleToHost(bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;

package/dist/lib/secrets/push.js

@@ -0,0 +1,145 @@
+/**
+ * Push one bundle's values to a remote host over SSH — the provisioning
+ * primitive behind `agents secrets export --host` and, from RUSH-1968, behind
+ * `agents fleet apply --provision-secrets`.
+ *
+ * This logic used to live inline in the `export --host` command action. It moved
+ * here because `lib/fleet/apply.ts` needs it and a lib MUST NOT import a command
+ * module — and because the absence of a callable primitive is part of why
+ * `fleet apply` never provisioned secrets at all, leaving an operator to
+ * hand-export the file store's master key across the fleet.
+ *
+ * Two rules shape the shape of this module:
+ *
+ * - **It never prints.** The lib layer stays `console.*`-free (SEC-14/SEC-16), so
+ *   every outcome is returned as data and the CALLER renders it. That is also
+ *   what lets `fleet apply` fold a push into its own per-device report instead of
+ *   interleaving stray lines into it.
+ * - **Resolve once, push N times.** `resolveBundleForPush` is separate because
+ *   reading a bundle can prompt (Touch ID); doing it per host would prompt per
+ *   host. `export --host a,b,c` resolves once and pushes three times.
+ */
+import { sshExec } from '../ssh-exec.js';
+import { remoteShellFor, buildWindowsStdinImportCommand } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { remoteSecretsRaw, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, } from './remote.js';
+import { readAndResolveBundleEnv } from './bundles.js';
+/**
+ * Serialize a resolved env map to `.env` lines that round-trip losslessly through
+ * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
+ * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
+ * value survives unchanged with no escaping. Newlines would break its line-based
+ * parse, so multi-line values are rejected rather than silently corrupted.
+ */
+export function bundleEnvToDotenv(env) {
+    const lines = [];
+    for (const [k, v] of Object.entries(env)) {
+        if (/[\r\n]/.test(v)) {
+            throw new Error(`Key '${k}' has a multi-line value; the SSH .env transport can't carry newlines. ` +
+                `Set it directly on the remote with 'agents secrets add ${k} --value-stdin'.`);
+        }
+        lines.push(`${k}="${v}"`);
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Read and resolve a bundle once, for pushing to one or more hosts.
+ *
+ * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
+ * passed: storage-shaped values, and the headless guard that fails fast rather
+ * than popping Touch ID inside an automated run.
+ */
+export function resolveBundleForPush(bundle, caller) {
+    const { env } = readAndResolveBundleEnv(bundle, { caller, keyMode: 'storage', agentOnly: true });
+    return { env, dotenv: bundleEnvToDotenv(env), keyCount: Object.keys(env).length };
+}
+function isPowershellTarget(host) {
+    return remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell';
+}
+/** Choose the transport for one push. Pure: registry read in, plan out. */
+export function planPushTransport(resolved, bundle, host, opts) {
+    const powershell = isPowershellTarget(host);
+    if (opts.remoteBackend === 'file') {
+        // Both file-backend paths build a POSIX `bash -lc` command. Refuse a Windows
+        // target cleanly rather than emit broken PowerShell (fail loud at the
+        // boundary, never a silent wrong path).
+        if (powershell) {
+            return { kind: 'refuse', message: 'file backend export to a Windows target is not yet supported' };
+        }
+        const { remoteCmd, input } = buildRemoteFileImportCommand(bundle, resolved.dotenv, {
+            passphrase: opts.passphrase ?? '',
+            force: opts.force,
+        });
+        return { kind: 'ssh', remoteCmd, input };
+    }
+    if (powershell) {
+        // Keychain on a Windows target: the `agents.ps1` shim doesn't forward
+        // ssh-piped stdin to node, so `--from -` would hang. Bridge the piped .env
+        // through PowerShell into a temp file and import `--from <file>` (deleted
+        // afterwards). Same hardened ssh engine; the .env still only ever crosses
+        // the wire over ssh stdin.
+        return {
+            kind: 'ssh',
+            remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force }),
+            input: resolved.dotenv,
+        };
+    }
+    // Keychain on a POSIX target: OS-aware wrapping + the hardened ssh engine
+    // (BatchMode, ConnectTimeout, keepalive, control-socket reuse) via the same
+    // path the READ inverse (`remoteResolveEnv`) uses.
+    return {
+        kind: 'remote-secrets',
+        args: ['import', bundle, '--from', '-', ...(opts.force ? ['--force'] : [])],
+        input: resolved.dotenv,
+    };
+}
+/**
+ * Push an already-resolved bundle to ONE host.
+ *
+ * Drives the remote's own `agents secrets import --from -`, so the values land
+ * in the remote's chosen backend and the .env is read off ssh stdin rather than
+ * parsed by a remote shell. `import` auto-creates the bundle.
+ */
+export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
+    const fail = (message) => ({ ok: false, host, bundle, keyCount: resolved.keyCount, message });
+    const plan = planPushTransport(resolved, bundle, host, opts);
+    if (plan.kind === 'refuse')
+        return fail(plan.message);
+    const res = plan.kind === 'ssh'
+        ? sshExec(host, plan.remoteCmd, { input: plan.input })
+        : remoteSecretsRaw(host, plan.args, { input: plan.input, osLookupName: host });
+    if (res.code === null) {
+        return fail(res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed'));
+    }
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        return fail(`remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`);
+    }
+    // A keychain-backed push to a macOS remote over headless SSH can land the
+    // bundle metadata but no READABLE value items: the remote login keychain is
+    // locked in the non-interactive SSH context, so Security accepts the write but
+    // the biometry-ACL'd item is unreadable — and the remote `import` still exits
+    // 0. Read it back the way a release will and FAIL LOUDLY, rather than leave a
+    // metadata-only bundle that breaks later with "stored item not found". The
+    // file backend is headless-readable by construction, so it is skipped.
+    if (opts.remoteBackend === 'keychain') {
+        const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host });
+        if (!verdict.ok) {
+            return fail(verdict.kind === 'locked-keychain'
+                ? keychainWriteFailureMessage(host, bundle, verdict.reason)
+                : `pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
+        }
+    }
+    const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
+    return {
+        ok: true,
+        host,
+        bundle,
+        keyCount: resolved.keyCount,
+        message: remoteMsg || `${resolved.keyCount} key(s) exported`,
+    };
+}
+/** Resolve and push in one call — for a single host. */
+export function pushBundleToHost(bundle, host, opts) {
+    return pushResolvedBundleToHost(resolveBundleForPush(bundle, opts.operation), bundle, host, opts);
+}

package/dist/lib/secrets/reaper.d.ts

@@ -27,7 +27,12 @@ export interface KeychainProcessSnapshot {
      * `null` means "could not capture" — the planner must fail closed.
      */
     startTime: string | null;
-    /** True when this process's executable path matches the installed helper. */
+    /**
+     * True when this process is a REAP-ELIGIBLE helper invocation — the installed
+     * helper binary running a short-lived keychain verb. False for a non-helper
+     * process AND for the long-lived `watch-lock` watcher (see
+     * {@link isReapableHelperCommand}), which must never be reaped.
+     */
     isHelper: boolean;
 }
 /**
@@ -78,6 +83,15 @@ export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], n
  * Returns null for an unparseable value so the caller drops the row.
  */
 export declare function parseEtimeToSeconds(raw: string): number | null;
+/**
+ * Whether a `ps` command line is a REAP-ELIGIBLE helper invocation: the installed
+ * helper binary running a short-lived keychain verb (get/has/list/set/delete/
+ * migrate-*) that a wedged `coreauthd` can hang. Returns false for a non-helper
+ * command AND for the deliberately long-lived `watch-lock` watcher — matching by
+ * the full argv (`ps … command=`), so a live-parent `watch-lock` child is never
+ * mistaken for a stuck read and killed. Pure; unit-tested.
+ */
+export declare function isReapableHelperCommand(command: string, helperPath: string): boolean;
 /** Test seam: reset the persisted candidate state. */
 export declare function resetKeychainReaperCandidatesForTest(): void;
 /**

package/dist/lib/secrets/reaper.js

@@ -134,6 +134,31 @@ function parsePsLine(line) {
         return null;
     return { pid, ppid, elapsedSec, command };
 }
+/**
+ * The one helper verb that is DELIBERATELY long-lived: the broker's auto-lock
+ * sleep/lock watcher (`spawn(getKeychainHelperPath(), ['watch-lock'], …)` in
+ * `agent.ts`). It lives for the broker's whole hold — potentially days — as a
+ * healthy child of the live broker/daemon, emitting LOCK/SLEEP lines that wipe
+ * the in-memory secret store on sleep. It is NOT a stuck keychain read, so the
+ * reaper must never target it: killing it silently disables auto-lock-on-sleep.
+ */
+const HELPER_WATCH_LOCK_VERB = 'watch-lock';
+/**
+ * Whether a `ps` command line is a REAP-ELIGIBLE helper invocation: the installed
+ * helper binary running a short-lived keychain verb (get/has/list/set/delete/
+ * migrate-*) that a wedged `coreauthd` can hang. Returns false for a non-helper
+ * command AND for the deliberately long-lived `watch-lock` watcher — matching by
+ * the full argv (`ps … command=`), so a live-parent `watch-lock` child is never
+ * mistaken for a stuck read and killed. Pure; unit-tested.
+ */
+export function isReapableHelperCommand(command, helperPath) {
+    if (command === helperPath)
+        return true; // bare exec, no verb — never watch-lock
+    if (!command.startsWith(`${helperPath} `))
+        return false; // not our helper
+    const firstArg = command.slice(helperPath.length + 1).trimStart().split(/\s+/)[0];
+    return firstArg !== HELPER_WATCH_LOCK_VERB;
+}
 /** Module-state for the two-sweep stuck-parent debounce. */
 let stuckParentCandidates = new Map();
 /** Test seam: reset the persisted candidate state. */
@@ -178,9 +203,11 @@ export function reapOrphanedKeychainProcesses() {
         if (!parsed)
             continue;
         const { pid, ppid, elapsedSec, command } = parsed;
-        // Exact path-match: the helper invocation's command line begins with the
-        // absolute helper path, followed by a space and its arguments (or nothing).
-        const isHelper = command === helperPath || command.startsWith(`${helperPath} `);
+        // Reap-eligible = the helper binary running a short-lived keychain verb. The
+        // full-argv match excludes the deliberately long-lived `watch-lock` watcher,
+        // whose live-parent child would otherwise be killed as if it were stuck
+        // (RUSH-2232 — that silently disabled auto-lock-on-sleep).
+        const isHelper = isReapableHelperCommand(command, helperPath);
         rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
     }
     const rowByPid = new Map(rows.map((r) => [r.pid, r]));

package/dist/lib/self-update.d.ts

@@ -136,15 +136,30 @@ export declare function verifyInstalledVersion(packageRoot: string, expectedVers
  */
 export declare function refreshAliasShims(packageRoot: string): void;
 export interface AgentsCliInstall {
-    /** The PATH entry (`<dir>/agents`) that resolves to this install. */
-    binPath: string;
+    /** The PATH entry (`<dir>/agents`) that resolves to this install, when found through PATH. */
+    binPath?: string;
     /** Package root containing package.json and dist/. */
     packageRoot: string;
     version: string;
+    /** Whether this copy uses the serialized, atomic helper-bundle installer. */
+    atomicHelperInstall: boolean;
 }
+export interface FindAgentsCliInstallsOptions {
+    homeDir?: string;
+    fnmDir?: string;
+    npmCacheDir?: string;
+    globalNodeModulesDirs?: string[];
+}
+export interface MultiInstallInventoryEntry {
+    packageRoot: string;
+    version: string;
+    note: string;
+}
+export declare function buildMultiInstallInventory(runningRoot: string, runningVersion: string, installs: AgentsCliInstall[]): MultiInstallInventoryEntry[];
 /**
- * Scan PATH for `agents` entrypoints and resolve each to the agents-cli
- * package root it executes. More than one distinct root means upgrades,
+ * Resolve every `agents` entrypoint on PATH, then inspect the bounded global
+ * install layouts used by NVM, fnm, Volta, Bun, npm, and npx. More than one
+ * distinct package root means upgrades,
  * shims, and the command the user types can act on different copies — the
  * divergence behind silently-failing self-updates.
  *
@@ -158,4 +173,4 @@ export interface AgentsCliInstall {
  * @phnx-labs/agents-cli is some other tool and is skipped.
  * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
  */
-export declare function findAgentsCliInstalls(pathEnv: string): AgentsCliInstall[];
+export declare function findAgentsCliInstalls(pathEnv: string, opts?: FindAgentsCliInstallsOptions): AgentsCliInstall[];

package/dist/lib/self-update.js

@@ -327,9 +327,89 @@ function packageRootForEntry(real) {
     }
     return null;
 }
+export function buildMultiInstallInventory(runningRoot, runningVersion, installs) {
+    const byRoot = new Map();
+    byRoot.set(runningRoot, { packageRoot: runningRoot, version: runningVersion, note: 'running' });
+    for (const install of installs) {
+        const notes = [install.packageRoot === runningRoot
+                ? 'running'
+                : install.binPath
+                    ? `agents on PATH: ${install.binPath}`
+                    : 'discovered install'];
+        if (!install.atomicHelperInstall)
+            notes.push('unsafe legacy helper installer — remove this copy');
+        byRoot.set(install.packageRoot, {
+            packageRoot: install.packageRoot,
+            version: install.version,
+            note: notes.join('; '),
+        });
+    }
+    return [...byRoot.values()];
+}
+function childDirectories(parent) {
+    try {
+        return fs.readdirSync(parent, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(parent, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+function knownPackageRoots(opts) {
+    const homeDir = opts.homeDir ?? os.homedir();
+    const fnmRoots = opts.fnmDir !== undefined
+        ? [opts.fnmDir]
+        : [process.env.FNM_DIR, path.join(homeDir, '.local', 'share', 'fnm')]
+            .filter((value) => Boolean(value));
+    const roots = [];
+    const packageTail = path.join('lib', 'node_modules', ...NPM_PACKAGE_NAME.split('/'));
+    for (const nodeDir of childDirectories(path.join(homeDir, '.nvm', 'versions', 'node'))) {
+        roots.push(path.join(nodeDir, packageTail));
+    }
+    for (const fnmRoot of fnmRoots) {
+        for (const versionDir of childDirectories(path.join(fnmRoot, 'node-versions'))) {
+            roots.push(path.join(versionDir, 'installation', packageTail));
+        }
+    }
+    roots.push(path.join(homeDir, '.volta', 'tools', 'image', 'packages', ...NPM_PACKAGE_NAME.split('/'), packageTail), path.join(homeDir, '.local', packageTail), path.join(homeDir, '.bun', 'install', 'global', 'node_modules', ...NPM_PACKAGE_NAME.split('/')));
+    const npmCacheDir = opts.npmCacheDir ?? process.env.npm_config_cache ?? path.join(homeDir, '.npm');
+    for (const npxRunDir of childDirectories(path.join(npmCacheDir, '_npx'))) {
+        roots.push(path.join(npxRunDir, 'node_modules', ...NPM_PACKAGE_NAME.split('/')));
+    }
+    const globalNodeModulesDirs = opts.globalNodeModulesDirs ?? [
+        '/opt/homebrew/lib/node_modules',
+        '/usr/local/lib/node_modules',
+        '/usr/lib/node_modules',
+    ];
+    for (const nodeModulesDir of globalNodeModulesDirs) {
+        roots.push(path.join(nodeModulesDir, ...NPM_PACKAGE_NAME.split('/')));
+    }
+    return roots;
+}
+function readAgentsCliInstall(packageRoot, binPath) {
+    let canonicalRoot;
+    let pkg;
+    try {
+        canonicalRoot = fs.realpathSync(packageRoot);
+        pkg = JSON.parse(fs.readFileSync(path.join(canonicalRoot, 'package.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (pkg.name !== NPM_PACKAGE_NAME || typeof pkg.version !== 'string')
+        return null;
+    return {
+        ...(binPath ? { binPath } : {}),
+        packageRoot: canonicalRoot,
+        version: pkg.version,
+        atomicHelperInstall: fs.existsSync(path.join(canonicalRoot, 'dist', 'lib', 'app-bundle-install.js')),
+    };
+}
 /**
- * Scan PATH for `agents` entrypoints and resolve each to the agents-cli
- * package root it executes. More than one distinct root means upgrades,
+ * Resolve every `agents` entrypoint on PATH, then inspect the bounded global
+ * install layouts used by NVM, fnm, Volta, Bun, npm, and npx. More than one
+ * distinct package root means upgrades,
  * shims, and the command the user types can act on different copies — the
  * divergence behind silently-failing self-updates.
  *
@@ -343,11 +423,17 @@ function packageRootForEntry(real) {
  * @phnx-labs/agents-cli is some other tool and is skipped.
  * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
  */
-export function findAgentsCliInstalls(pathEnv) {
+export function findAgentsCliInstalls(pathEnv, opts = {}) {
     if (process.platform === 'win32')
         return [];
     const installs = [];
     const seenRoots = new Set();
+    const addInstall = (install) => {
+        if (!install || seenRoots.has(install.packageRoot))
+            return;
+        seenRoots.add(install.packageRoot);
+        installs.push(install);
+    };
     for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
         const candidate = path.join(dir, 'agents');
         let real;
@@ -360,19 +446,10 @@ export function findAgentsCliInstalls(pathEnv) {
         const packageRoot = packageRootForEntry(real);
         if (!packageRoot)
             continue;
-        if (seenRoots.has(packageRoot))
-            continue;
-        let pkg;
-        try {
-            pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
-        }
-        catch {
-            continue;
-        }
-        if (pkg.name !== NPM_PACKAGE_NAME || typeof pkg.version !== 'string')
-            continue;
-        seenRoots.add(packageRoot);
-        installs.push({ binPath: candidate, packageRoot, version: pkg.version });
+        addInstall(readAgentsCliInstall(packageRoot, candidate));
+    }
+    for (const packageRoot of knownPackageRoots(opts)) {
+        addInstall(readAgentsCliInstall(packageRoot));
     }
     return installs;
 }