@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/secrets/rc-hygiene.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Detect credentials exported from shell rc files.
+ *
+ * A secret exported from `~/.zshenv`, `~/.zshrc`, `~/.bashrc`, `~/.profile`, …
+ * is inherited by every process the login shell spawns and is readable from
+ * `/proc/<pid>/environ` by any same-user process — the master passphrase leak
+ * behind RUSH-1968. `.zshenv` in particular is sourced by *every* zsh
+ * invocation, including non-interactive `ssh host 'cmd'`, so the value lands in
+ * the environment of essentially everything the box runs.
+ *
+ * The keychain-backed store (`agents secrets`) is the sanctioned home for
+ * credentials; the file-store master passphrase belongs in the off-env 0600 key
+ * file (`~/.agents/.secrets-key/passphrase`), never a shell rc export.
+ *
+ * This scanner powers a warn-level advisory in `agents doctor`. It reads only
+ * the exported variable *name* and its line number — never the value — so a
+ * finding can be printed, logged, or shipped without leaking the secret.
+ */
+/** Shell rc files sourced at login/startup, in the order a report lists them. */
+export declare const RC_FILENAMES: readonly [".zshenv", ".zprofile", ".zshrc", ".zlogin", ".bash_profile", ".bash_login", ".bashrc", ".profile", ".kshrc"];
+/**
+ * A single credential-shaped export found in an rc file. Carries the variable
+ * NAME and location only — the value is never captured.
+ */
+export interface RcSecretFinding {
+    /** Basename of the rc file, e.g. `.zshenv`. */
+    file: string;
+    /** 1-based line number of the export. */
+    line: number;
+    /** The exported variable name (e.g. `AGENTS_SECRETS_PASSPHRASE`). Never the value. */
+    name: string;
+    /** The file-store master passphrase gets called out separately — it is the highest-severity case. */
+    isMasterPassphrase: boolean;
+}
+/** True if a variable name looks like it holds a credential value. */
+export declare function isCredentialName(name: string): boolean;
+/**
+ * Scan one rc file's contents for credential-shaped exports. Pure — takes the
+ * text, returns findings (names + line numbers only, never values). A trailing
+ * `# comment` is stripped before matching so a commented-out export is ignored;
+ * the variable name always precedes any inline `#`, so stripping never loses it.
+ */
+export declare function scanRcExports(basename: string, content: string): RcSecretFinding[];
+/**
+ * Scan the current user's shell rc files. Reads each file that exists under
+ * `homeDir` (default `os.homedir()`) and aggregates the findings. Missing or
+ * unreadable files are skipped silently — an advisory, not a hard requirement.
+ */
+export declare function scanUserRcFiles(homeDir?: string): RcSecretFinding[];
+/**
+ * Build the advisory lines for `agents doctor` from a set of findings. Returns
+ * `[]` when there is nothing to report. The first line is the headline; the
+ * rest are indented detail. Names only — never values.
+ */
+export declare function rcSecretWarningLines(findings: RcSecretFinding[]): string[];

package/dist/lib/secrets/rc-hygiene.js

@@ -0,0 +1,154 @@
+/**
+ * Detect credentials exported from shell rc files.
+ *
+ * A secret exported from `~/.zshenv`, `~/.zshrc`, `~/.bashrc`, `~/.profile`, …
+ * is inherited by every process the login shell spawns and is readable from
+ * `/proc/<pid>/environ` by any same-user process — the master passphrase leak
+ * behind RUSH-1968. `.zshenv` in particular is sourced by *every* zsh
+ * invocation, including non-interactive `ssh host 'cmd'`, so the value lands in
+ * the environment of essentially everything the box runs.
+ *
+ * The keychain-backed store (`agents secrets`) is the sanctioned home for
+ * credentials; the file-store master passphrase belongs in the off-env 0600 key
+ * file (`~/.agents/.secrets-key/passphrase`), never a shell rc export.
+ *
+ * This scanner powers a warn-level advisory in `agents doctor`. It reads only
+ * the exported variable *name* and its line number — never the value — so a
+ * finding can be printed, logged, or shipped without leaking the secret.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** Shell rc files sourced at login/startup, in the order a report lists them. */
+export const RC_FILENAMES = [
+    '.zshenv',
+    '.zprofile',
+    '.zshrc',
+    '.zlogin',
+    '.bash_profile',
+    '.bash_login',
+    '.bashrc',
+    '.profile',
+    '.kshrc',
+];
+/** The file-store master key. Its own resolution prefers an off-env 0600 file, so
+ *  a shell-rc export is always wrong once the store exists (RUSH-1968). */
+const MASTER_PASSPHRASE = 'AGENTS_SECRETS_PASSPHRASE';
+/**
+ * Last `_`-delimited segment values that mark a variable as credential-shaped.
+ * Matched against the FINAL segment (segment equality, not substring) so
+ * `X_API_KEY` fires on `KEY` while `SOME_KEY_PATH` (ends `PATH`) and `MONKEY`
+ * (single segment, not equal to `KEY`) do not.
+ */
+const CREDENTIAL_SEGMENTS = new Set([
+    'PASSPHRASE',
+    'PASSWORD',
+    'PASSWD',
+    'SECRET',
+    'SECRETS',
+    'TOKEN',
+    'KEY',
+    'APIKEY',
+    'PAT',
+    'CREDENTIAL',
+    'CREDENTIALS',
+]);
+/**
+ * Final segments that look credential-shaped but name a file path, socket, or
+ * config knob rather than a secret value — excluded to cut false positives.
+ * Applied to the whole name's final segment before the credential check.
+ */
+const BENIGN_FINAL_SEGMENTS = new Set([
+    'PATH',
+    'FILE',
+    'DIR',
+    'SOCK',
+    'SOCKET',
+    'ID',
+    'NAME',
+    'PARALLELISM', // TOKENIZERS_PARALLELISM and friends
+]);
+/** True if a variable name looks like it holds a credential value. */
+export function isCredentialName(name) {
+    if (name === MASTER_PASSPHRASE)
+        return true;
+    const segments = name.toUpperCase().split('_');
+    const last = segments[segments.length - 1];
+    if (BENIGN_FINAL_SEGMENTS.has(last))
+        return false;
+    return CREDENTIAL_SEGMENTS.has(last);
+}
+// Matches an env assignment that puts a value in the environment:
+//   export NAME=...            (sh/bash/zsh)
+//   typeset -x NAME=... / declare -x NAME=...   (bash/zsh export-attribute form)
+const EXPORT_RE = /^\s*(?:export\s+|(?:typeset|declare)\s+-[A-Za-z]*x[A-Za-z]*\s+)([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * Scan one rc file's contents for credential-shaped exports. Pure — takes the
+ * text, returns findings (names + line numbers only, never values). A trailing
+ * `# comment` is stripped before matching so a commented-out export is ignored;
+ * the variable name always precedes any inline `#`, so stripping never loses it.
+ */
+export function scanRcExports(basename, content) {
+    const out = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const code = lines[i].replace(/#.*$/, '');
+        const m = EXPORT_RE.exec(code);
+        if (!m)
+            continue;
+        const name = m[1];
+        if (!isCredentialName(name))
+            continue;
+        out.push({
+            file: basename,
+            line: i + 1,
+            name,
+            isMasterPassphrase: name === MASTER_PASSPHRASE,
+        });
+    }
+    return out;
+}
+/**
+ * Scan the current user's shell rc files. Reads each file that exists under
+ * `homeDir` (default `os.homedir()`) and aggregates the findings. Missing or
+ * unreadable files are skipped silently — an advisory, not a hard requirement.
+ */
+export function scanUserRcFiles(homeDir = os.homedir()) {
+    const out = [];
+    for (const name of RC_FILENAMES) {
+        const fp = path.join(homeDir, name);
+        let content;
+        try {
+            content = fs.readFileSync(fp, 'utf8');
+        }
+        catch {
+            continue; // absent or unreadable — nothing to report
+        }
+        out.push(...scanRcExports(name, content));
+    }
+    return out;
+}
+/**
+ * Build the advisory lines for `agents doctor` from a set of findings. Returns
+ * `[]` when there is nothing to report. The first line is the headline; the
+ * rest are indented detail. Names only — never values.
+ */
+export function rcSecretWarningLines(findings) {
+    if (findings.length === 0)
+        return [];
+    const lines = [];
+    const master = findings.filter((f) => f.isMasterPassphrase);
+    const others = findings.filter((f) => !f.isMasterPassphrase);
+    const total = findings.length;
+    lines.push(`${total} credential-shaped export${total === 1 ? '' : 's'} found in shell rc files — ` +
+        `readable from /proc/<pid>/environ by any same-user process.`);
+    for (const f of master) {
+        lines.push(`${f.file}:${f.line} ${f.name} — the file-store master key. Move it off-env to ` +
+            `~/.agents/.secrets-key/passphrase (chmod 600) and delete the export.`);
+    }
+    for (const f of others) {
+        lines.push(`${f.file}:${f.line} ${f.name} — move to \`agents secrets\` and inject via \`agents secrets exec\`.`);
+    }
+    lines.push('Rule: no credentials in env vars or shell config. Use the keychain-backed store.');
+    return lines;
+}

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

@@ -34,11 +34,14 @@ import { type SshExecResult } from '../ssh-exec.js';
  */
 export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
- * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
- * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
- * treats the value as a raw ssh target and validates it against injection.
+ * Resolve a `--host` value to an ssh target STRING for the remote-secrets path.
+ * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
+ * name here dials the exact same box `run --host` does; on a miss, treats the
+ * value as a raw ssh target and validates it against injection. Named distinctly
+ * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
+ * the wrong one can't silently change which machine you dial.
  */
-export declare function resolveSshTarget(nameOrAlias: string): Promise<string>;
+export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
 /**
  * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
  * list. Both flags compose; either alone works. Empty when neither is set.

package/dist/lib/secrets/remote.js

@@ -59,11 +59,14 @@ function osForTarget(target, lookupName) {
     return byName ?? resolveRemoteOsSync(target.split('@').pop() ?? target);
 }
 /**
- * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
- * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
- * treats the value as a raw ssh target and validates it against injection.
+ * Resolve a `--host` value to an ssh target STRING for the remote-secrets path.
+ * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
+ * name here dials the exact same box `run --host` does; on a miss, treats the
+ * value as a raw ssh target and validates it against injection. Named distinctly
+ * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
+ * the wrong one can't silently change which machine you dial.
  */
-export async function resolveSshTarget(nameOrAlias) {
+export async function resolveHostSshTarget(nameOrAlias) {
     const host = await resolveHost(nameOrAlias);
     if (host)
         return sshTargetFor(host);

package/dist/lib/secrets/session-store.d.ts

@@ -38,12 +38,14 @@ export interface SessionEntry {
     expiresAt: number;
     /** true only for `--durable` unlocks — survives SLEEP. */
     sleepPersist: boolean;
+    harness?: string;
 }
 /** Metadata for one held bundle, kept in the index so we can rehydrate / prune
  * without reading every blob. */
 export interface SessionIndexMeta {
     expiresAt: number;
     sleepPersist: boolean;
+    harness?: string;
 }
 export interface SessionIndex {
     bundles: Record<string, SessionIndexMeta>;
@@ -73,9 +75,11 @@ export declare function writeIndex(index: SessionIndex): void;
 /** Persist one unlocked bundle: write its blob no-ACL and record it in the index. */
 export declare function saveSession(name: string, entry: SessionEntry): void;
 /** Read one session blob by known name. Null when absent/expired/malformed. */
-export declare function loadSession(name: string, now?: number): SessionEntry | null;
+export declare function loadSession(name: string, now?: number, harness?: string): SessionEntry | null;
+/** Remove every persisted harness grant for one bundle. */
+export declare function deleteBundleSessions(name: string): void;
 /** Delete one bundle's session blob and prune it from the index. */
-export declare function deleteSession(name: string): void;
+export declare function deleteSession(name: string, harness?: string): void;
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export declare function deleteAllSessions(): void;
 /** Rehydrate every unexpired session into `[name, entry]` pairs for the broker to

package/dist/lib/secrets/session-store.js

@@ -82,8 +82,8 @@ export function removeEntry(index, name) {
 function shouldPersist() {
     return process.platform === 'darwin' || isKeychainBackendOverridden();
 }
-function sessionBlobItem(name) {
-    return `${SESSION_ITEM_PREFIX}${name}`;
+function sessionBlobItem(name, harness) {
+    return `${SESSION_ITEM_PREFIX}${harness}.${name}`;
 }
 /** Read the session index by its fixed name. `{bundles:{}}` when absent/unreadable. */
 export function readIndex() {
@@ -116,24 +116,26 @@ export function saveSession(name, entry) {
     if (!shouldPersist())
         return;
     try {
-        setKeychainToken(sessionBlobItem(name), JSON.stringify(entry), { noAcl: true });
-        writeIndex(upsertEntry(readIndex(), name, { expiresAt: entry.expiresAt, sleepPersist: entry.sleepPersist }));
+        const harness = entry.harness || 'cli';
+        const key = `${harness}:${name}`;
+        setKeychainToken(sessionBlobItem(name, harness), JSON.stringify({ ...entry, harness }), { noAcl: true });
+        writeIndex(upsertEntry(readIndex(), key, { expiresAt: entry.expiresAt, sleepPersist: entry.sleepPersist, harness }));
     }
     catch {
         /* best-effort — persistence is an optimization */
     }
 }
 /** Read one session blob by known name. Null when absent/expired/malformed. */
-export function loadSession(name, now = Date.now()) {
+export function loadSession(name, now = Date.now(), harness = 'cli') {
     if (!shouldPersist())
         return null;
     try {
-        const raw = getKeychainToken(sessionBlobItem(name));
+        const raw = getKeychainToken(sessionBlobItem(name, harness));
         const entry = JSON.parse(raw);
         if (!entry || typeof entry !== 'object' || !entry.bundle || !entry.env)
             return null;
         if (now >= entry.expiresAt) {
-            deleteSession(name); // drop expired on read, mirroring the broker's get handler
+            deleteSession(name, harness); // drop expired on read
             return null;
         }
         return entry;
@@ -142,13 +144,32 @@ export function loadSession(name, now = Date.now()) {
         return null;
     }
 }
+/** Remove every persisted harness grant for one bundle. */
+export function deleteBundleSessions(name) {
+    if (!shouldPersist())
+        return;
+    const index = readIndex();
+    let next = index;
+    for (const [key, meta] of Object.entries(index.bundles)) {
+        const scopedName = key.includes(':') ? key.split(':').slice(1).join(':') : key;
+        if (scopedName !== name)
+            continue;
+        const harness = meta.harness || 'cli';
+        try {
+            deleteKeychainToken(key.includes(':') ? sessionBlobItem(name, harness) : `${SESSION_ITEM_PREFIX}${name}`);
+        }
+        catch { /* keep going */ }
+        next = removeEntry(next, key);
+    }
+    writeIndex(next);
+}
 /** Delete one bundle's session blob and prune it from the index. */
-export function deleteSession(name) {
+export function deleteSession(name, harness = 'cli') {
     if (!shouldPersist())
         return;
     try {
-        deleteKeychainToken(sessionBlobItem(name));
-        writeIndex(removeEntry(readIndex(), name));
+        deleteKeychainToken(sessionBlobItem(name, harness));
+        writeIndex(removeEntry(readIndex(), `${harness}:${name}`));
     }
     catch {
         /* best-effort */
@@ -160,8 +181,12 @@ export function deleteAllSessions() {
         return;
     try {
         for (const name of Object.keys(readIndex().bundles)) {
+            const meta = readIndex().bundles[name];
+            const bundleName = name.includes(':') ? name.split(':').slice(1).join(':') : name;
             try {
-                deleteKeychainToken(sessionBlobItem(name));
+                deleteKeychainToken(name.includes(':')
+                    ? sessionBlobItem(bundleName, meta.harness || 'cli')
+                    : `${SESSION_ITEM_PREFIX}${bundleName}`);
             }
             catch { /* keep going */ }
         }
@@ -180,19 +205,43 @@ export function rehydrateSessions(now = Date.now()) {
     const out = [];
     try {
         const index = readIndex();
+        // One-time source migration from the pre-harness layout. Move each legacy
+        // bundle-name index/blob to the explicit cli scope, then delete the old blob.
+        let migratedIndex = index;
+        for (const [key, meta] of Object.entries(index.bundles)) {
+            if (key.includes(':'))
+                continue;
+            try {
+                const raw = getKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
+                const legacy = JSON.parse(raw);
+                setKeychainToken(sessionBlobItem(key, 'cli'), JSON.stringify({ ...legacy, harness: 'cli' }), { noAcl: true });
+                deleteKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
+                migratedIndex = upsertEntry(removeEntry(migratedIndex, key), `cli:${key}`, {
+                    expiresAt: meta.expiresAt,
+                    sleepPersist: meta.sleepPersist,
+                    harness: 'cli',
+                });
+            }
+            catch { /* malformed/absent legacy entry is pruned below */ }
+        }
+        writeIndex(migratedIndex);
+        index.bundles = migratedIndex.bundles;
         const { survivors, expiredNames } = pruneExpired(index, now);
         for (const name of expiredNames) {
+            const meta = index.bundles[name];
             try {
-                deleteKeychainToken(sessionBlobItem(name));
+                deleteKeychainToken(sessionBlobItem(name.split(':').slice(1).join(':'), meta.harness || 'cli'));
             }
             catch { /* keep going */ }
         }
         if (expiredNames.length)
             writeIndex(survivors);
         for (const name of selectRehydratable(survivors, now)) {
-            const entry = loadSession(name, now);
+            const meta = survivors.bundles[name];
+            const bundleName = name.split(':').slice(1).join(':');
+            const entry = loadSession(bundleName, now, meta.harness || 'cli');
             if (entry)
-                out.push({ name, entry });
+                out.push({ name: bundleName, entry });
         }
     }
     catch {
@@ -208,8 +257,9 @@ export function pruneSessionsOnSleep() {
     try {
         const { survivors, deletedNames } = pruneOnSleep(readIndex());
         for (const name of deletedNames) {
+            const meta = readIndex().bundles[name];
             try {
-                deleteKeychainToken(sessionBlobItem(name));
+                deleteKeychainToken(sessionBlobItem(name.split(':').slice(1).join(':'), meta.harness || 'cli'));
             }
             catch { /* keep going */ }
         }

package/dist/lib/secrets/sync-commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The argv tokens for the synchronous secrets-broker clients: the tokens
+ * `agentGetSync`/`agentReachableSync`/`agentEvictSync` spawn, and the tokens
+ * `index.ts` dispatches on before commander.
+ *
+ * This is a LEAF module — it imports nothing, so the CLI entrypoint can bind
+ * these statically without dragging the secrets graph (and its `state.js` /
+ * `install-helper.js` / `session-store.js` imports) into every invocation. That
+ * is the whole reason the file exists: with the tokens in `agent.ts`, `index.ts`
+ * had to repeat them as string literals, and the two could silently drift —
+ * a drift with no visible failure mode, because the CLI answers "unknown
+ * command", the client reads the non-zero exit as "broker down", and every
+ * secret read falls back to a Touch ID prompt. Exactly the bug this subsystem
+ * was fixed for. Sharing one binding makes that divergence a type error rather
+ * than something a test has to notice.
+ *
+ * Same leaf discipline, and same motivation, as `lib/cli-entry.ts`.
+ */
+export declare const SYNC_GET_CMD = "__secrets-get";
+export declare const SYNC_PING_CMD = "__secrets-ping";
+export declare const SYNC_LOCK_CMD = "__secrets-lock";

package/dist/lib/secrets/sync-commands.js

@@ -0,0 +1,21 @@
+/**
+ * The argv tokens for the synchronous secrets-broker clients: the tokens
+ * `agentGetSync`/`agentReachableSync`/`agentEvictSync` spawn, and the tokens
+ * `index.ts` dispatches on before commander.
+ *
+ * This is a LEAF module — it imports nothing, so the CLI entrypoint can bind
+ * these statically without dragging the secrets graph (and its `state.js` /
+ * `install-helper.js` / `session-store.js` imports) into every invocation. That
+ * is the whole reason the file exists: with the tokens in `agent.ts`, `index.ts`
+ * had to repeat them as string literals, and the two could silently drift —
+ * a drift with no visible failure mode, because the CLI answers "unknown
+ * command", the client reads the non-zero exit as "broker down", and every
+ * secret read falls back to a Touch ID prompt. Exactly the bug this subsystem
+ * was fixed for. Sharing one binding makes that divergence a type error rather
+ * than something a test has to notice.
+ *
+ * Same leaf discipline, and same motivation, as `lib/cli-entry.ts`.
+ */
+export const SYNC_GET_CMD = '__secrets-get';
+export const SYNC_PING_CMD = '__secrets-ping';
+export const SYNC_LOCK_CMD = '__secrets-lock';

package/dist/lib/secrets/unlock-hints.d.ts

@@ -0,0 +1,27 @@
+/** The subset of a `secrets.get` event this heuristic reads. */
+export interface SecretGetRecord {
+    /** Bundle name the read targeted. */
+    bundle?: string;
+    /** Where the value came from: `agent` (broker hit) / `session` (durable
+     *  unlock) are SILENT; anything else hit the keychain and thus prompted. */
+    source?: string;
+}
+export interface PromptedBundle {
+    name: string;
+    /** Number of prompting (keychain) reads in the window. */
+    count: number;
+}
+/**
+ * From recent `secrets.get` records, find bundles read often enough via the
+ * keychain (i.e. NOT served silently by the broker or a durable session) to be
+ * worth unlocking once. A bundle currently `held` is already silent, so it is
+ * excluded; the caller further drops `never`/no-ACL bundles (which never prompt,
+ * so unlocking them is a no-op).
+ *
+ * @param records recent `secrets.get` events (any order)
+ * @param held    bundle names the broker currently holds (silent reads)
+ * @param opts.minReads minimum prompting reads to surface a bundle (default 3)
+ */
+export declare function frequentlyPromptedBundles(records: SecretGetRecord[], held: Set<string>, opts?: {
+    minReads?: number;
+}): PromptedBundle[];

package/dist/lib/secrets/unlock-hints.js

@@ -0,0 +1,36 @@
+// Usage-based unlock hints: surface bundles you keep getting a Touch ID prompt
+// for, so `agents secrets status` can suggest unlocking them once instead of
+// prompting on every read. Built on the existing `secrets.get` audit events
+// (events.jsonl) — no new tracking. Pure + exported so the threshold/filter
+// logic is unit-testable without the events sink or the keychain.
+/**
+ * From recent `secrets.get` records, find bundles read often enough via the
+ * keychain (i.e. NOT served silently by the broker or a durable session) to be
+ * worth unlocking once. A bundle currently `held` is already silent, so it is
+ * excluded; the caller further drops `never`/no-ACL bundles (which never prompt,
+ * so unlocking them is a no-op).
+ *
+ * @param records recent `secrets.get` events (any order)
+ * @param held    bundle names the broker currently holds (silent reads)
+ * @param opts.minReads minimum prompting reads to surface a bundle (default 3)
+ */
+export function frequentlyPromptedBundles(records, held, opts = {}) {
+    const minReads = opts.minReads ?? 3;
+    const counts = new Map();
+    for (const r of records) {
+        if (!r.bundle)
+            continue;
+        // A broker hit or a durable-session read raised no Touch ID sheet — only a
+        // read that fell through to the keychain did. Count those; they are the ones
+        // an unlock would silence.
+        if (r.source === 'agent' || r.source === 'session')
+            continue;
+        if (held.has(r.bundle))
+            continue;
+        counts.set(r.bundle, (counts.get(r.bundle) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, n]) => n >= minReads)
+        .map(([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}

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

@@ -55,6 +55,23 @@ export declare function saveUpdateCheck(file: string, latestVersion: string): vo
 export declare function dismissUpdateVersion(file: string, version: string): void;
 /** Whether the cached state warrants an upgrade prompt for a copy running `currentVersion`. */
 export declare function shouldPromptUpgrade(cache: UpdateCheckCache | null, currentVersion: string): boolean;
+/**
+ * The on-disk package root of the copy that is currently running.
+ *
+ * For a plain JS install this is just `<__dirname>/..`. Under the compiled
+ * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
+ * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
+ * exists nowhere. That phantom value was reported as a second install by the
+ * multi-install check, and rejected by deriveGlobalPrefix as "not an
+ * npm-managed install", so every self-upgrade from a compiled copy failed.
+ *
+ * The physical executable is `process.execPath`, which ships inside the
+ * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
+ * whose package.json actually names this package rather than assuming a fixed
+ * depth, so a change to the dist layout surfaces as a clear throw here instead
+ * of a wrong prefix that npm would happily install into.
+ */
+export declare function resolveRunningPackageRoot(dirname: string, execPath?: string): string;
 /**
  * Derive the npm global prefix that owns the install at `packageRoot`.
  *
@@ -133,8 +150,12 @@ export interface AgentsCliInstall {
  *
  * npm bin entries are symlinks that resolve to `<packageRoot>/dist/index.js`
  * (the dev install's `~/.local/bin/agents` chains through the dev prefix to
- * the same shape). Anything that doesn't resolve to a dist/index.js inside a
- * package named @phnx-labs/agents-cli is some other tool and is skipped.
+ * the same shape). A shim pointed at the compiled standalone binary resolves
+ * to `<packageRoot>/dist/bin/agents` instead; that shape counts too, otherwise
+ * the copy that actually runs — the compiled one is typically first on PATH —
+ * is invisible to this scan and its root looks like a separate install.
+ * Anything that resolves to neither shape inside a package named
+ * @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[];