@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/audit/log.js

@@ -1,29 +1,12 @@
 /**
- * Cross-agent, tamper-evident audit log of every dispatched run (issue #347).
+ * Run-dispatch recording (issue #347) — now a thin write into the unified
+ * event stream (`emit('run.dispatched', …)`). The historical hash-chained file
+ * at `~/.agents/.history/audit/log.jsonl` is still readable via
+ * `readAuditLog` / `verifyAuditChain` for pre-unification history; new runs do
+ * NOT append there. Operators list run outcomes with:
  *
- * Every run that reaches the single dispatch chokepoint in `agents run`
- * (src/commands/exec.ts) appends ONE record here. Records form a hash chain:
- * each record embeds the previous record's `hash` as `prevHash`, and its own
- * `hash` is `sha256(canonicalJSON(record-without-hash))`. Because `prevHash`
- * is part of the hashed payload, rewriting or reordering any record breaks the
- * chain from that point forward — `verifyAuditChain()` reports the first index
- * that fails to reproduce.
- *
- * Storage is append-only JSONL under the durable-runtime bucket
- * (`~/.agents/.history/audit/log.jsonl`), one record per line. `.history/` is
- * machine-local, gitignored, and NEVER synced by `agents repo push/pull` — so
- * the `repo` field (a git remote url that can embed an access token) never
- * lands in a version-controlled DotAgents repo, and a cross-machine pull can't
- * splice a foreign chain into this one. The write path is deliberately cheap
- * and non-fatal: a logging failure must never crash a run (see
- * `recordDispatchedRun`). Concurrent writers (parallel teams/routines dispatch)
- * are serialized by an advisory lock file so the chain never forks — see
- * `appendAuditRecord`.
- *
- * Governance context: this is the evidence trail an operator needs to answer
- * "which agent, at which version, ran against which repo, and did it succeed?"
- * — the kind of automated-decision logging the EU AI Act (Art. 12) expects of
- * high-risk systems, kept tamper-evident so the log itself can be trusted.
+ *   agents events --include runs
+ *   agents audit                 # alias of the above
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -31,6 +14,7 @@ import { spawnSync } from 'child_process';
 import { sha256 } from '../staleness/fingerprint.js';
 import { getHistoryDir } from '../state.js';
 import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
+import { emit } from '../events.js';
 /** First record's `prevHash` — a fixed anchor so the chain has a root. */
 export const GENESIS_HASH = 'GENESIS';
 /**
@@ -155,23 +139,26 @@ function repoLabel(cwd) {
     }
 }
 /**
- * Record ONE dispatched run at the single exec chokepoint. Non-fatal by
- * contract: any failure is caught and warned, never thrown — an audit-log
- * hiccup must not crash a run that already finished.
+ * Record ONE dispatched run at the single exec chokepoint into the unified
+ * event stream. Non-fatal by contract: any failure is caught and warned, never
+ * thrown — a log hiccup must not crash a run that already finished.
  */
 export function recordDispatchedRun(run) {
     try {
-        appendAuditRecord({
-            ts: new Date().toISOString(),
+        const outcome = run.exitCode === 0 ? 'ok' : 'fail';
+        emit('run.dispatched', {
+            module: 'run',
             agent: run.agent,
             version: run.version,
-            repo: repoLabel(run.cwd),
             mode: run.mode,
-            outcome: run.exitCode === 0 ? 'ok' : 'fail',
-            exit: run.exitCode,
+            repo: repoLabel(run.cwd),
+            cwd: run.cwd,
+            outcome,
+            exitCode: run.exitCode,
+            status: outcome,
         });
     }
     catch (err) {
-        process.stderr.write(`[agents] audit log write failed: ${err.message}\n`);
+        process.stderr.write(`[agents] run.dispatched emit failed: ${err.message}\n`);
     }
 }

package/dist/lib/auth-health.d.ts

@@ -3,10 +3,15 @@ import type { AgentId } from './types.js';
 import { type ProviderProbe } from './usage.js';
 /**
  * - `live`        — completed an authenticated request (200).
- * - `revoked`     — the server rejected the token (401/403).
+ * - `revoked`     — the server rejected the token (401/403), except Claude
+ *                   setup-token `user:profile` scope denials (those are
+ *                   `unverified` via `reason: 'usage_scope'` — RUSH-2392).
  * - `expired`     — locally-detected expiry; not network-verified (no refresh on the read path).
  * - `rate_limited`— token works but is throttled right now (429).
- * - `unverified`  — credential present, not locally expired, but this agent has no in-repo probe endpoint (codex/grok).
+ * - `unverified`  — credential present, not locally expired, but this agent has
+ *                   no in-repo probe endpoint (codex/grok), OR the probe
+ *                   endpoint cannot prove live for a known non-revocation
+ *                   reason (Claude setup-token usage-scope gap — RUSH-2392).
  * - `unconfigured`— no usable credential on disk.
  * - `error`       — network/other failure; verdict indeterminate (keep the last known one).
  */
@@ -129,6 +134,8 @@ export declare function authCacheKey(host: string, agent: AgentId | string, vers
 export declare function readAuthHealthCache(): Record<string, AuthHealth>;
 /** Read one entry, or null. */
 export declare function readAuthHealth(host: string, agent: AgentId | string, version: string): AuthHealth | null;
+/** Reconstruct one host's published probe rows for a lease waiter/CLI reader. */
+export declare function readFleetAuthRows(host: string): AuthProbeRow[];
 /**
  * Merge entries into the cache. An incoming `error` verdict (a network blip,
  * not a server rejection) is indeterminate, so it must NOT clobber a prior

package/dist/lib/auth-health.js

@@ -20,8 +20,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
 import { getCacheDir } from './state.js';
-import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, } from './usage.js';
+import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, } from './usage.js';
 import { getVersionHomePath, listInstalledVersions } from './versions.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 /** Agents with a live network probe wired up today. The rest are best-effort. */
 export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
 // ---------------------------------------------------------------------------
@@ -43,12 +44,20 @@ export function verdictFromProbe(probe) {
         return 'unconfigured';
     if (probe.token === 'expired')
         return 'expired';
+    // Setup-token can run inference but cannot read usage (RUSH-2392). That 403
+    // is NOT a revocation — classifying it as revoked made the best-provisioned
+    // headless accounts look the least healthy on `agents view` / fleet ping.
+    if (probe.reason === 'usage_scope')
+        return 'unverified';
     if (probe.status == null)
         return 'error';
     return classifyHttpStatus(probe.status);
 }
 /** A short human detail line for a probe result (rendered under --verbose). */
 export function probeDetail(probe) {
+    if (probe.reason === 'usage_scope') {
+        return probe.error ?? USAGE_HEADLESS_SCOPE_MARKER;
+    }
     if (probe.status != null && (probe.status < 200 || probe.status >= 300))
         return `HTTP ${probe.status}`;
     if (probe.error)
@@ -226,6 +235,29 @@ export function readAuthHealthCache() {
 export function readAuthHealth(host, agent, version) {
     return readAuthHealthCache()[authCacheKey(host, agent, version)] ?? null;
 }
+/** Reconstruct one host's published probe rows for a lease waiter/CLI reader. */
+export function readFleetAuthRows(host) {
+    const prefix = `${host}:`;
+    const rows = [];
+    for (const [key, health] of Object.entries(readAuthHealthCache())) {
+        if (!key.startsWith(prefix))
+            continue;
+        const identity = key.slice(prefix.length);
+        const separator = identity.indexOf(':');
+        if (separator <= 0)
+            continue;
+        const agent = identity.slice(0, separator);
+        if (!ALL_AGENT_IDS.includes(agent))
+            continue;
+        rows.push({
+            agent: agent,
+            version: identity.slice(separator + 1),
+            account: health.account,
+            health,
+        });
+    }
+    return rows;
+}
 /**
  * Merge entries into the cache. An incoming `error` verdict (a network blip,
  * not a server rejection) is indeterminate, so it must NOT clobber a prior
@@ -245,14 +277,15 @@ export function mergeAuthHealthEntries(current, incoming) {
 /** Merge one or more entries into the cache (best-effort write). */
 export function writeAuthHealthEntries(entries) {
     try {
-        const dir = getCacheDir();
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        const merged = {
-            version: 1,
-            entries: mergeAuthHealthEntries(readAuthHealthCache(), entries),
-        };
-        fs.writeFileSync(cacheFilePath(), JSON.stringify(merged, null, 2));
+        const target = cacheFilePath();
+        ensureLockTarget(target, JSON.stringify({ version: 1, entries: {} }));
+        withFileLock(target, () => {
+            const merged = {
+                version: 1,
+                entries: mergeAuthHealthEntries(readAuthHealthCache(), entries),
+            };
+            atomicWriteFileSync(target, JSON.stringify(merged, null, 2));
+        });
     }
     catch {
         // best-effort; a failed write just means the next reader falls back to heuristics

package/dist/lib/auto-pull-worker.js

@@ -12,8 +12,7 @@ import * as fs from 'fs';
 import { simpleGit } from 'simple-git';
 import { tryAutoPull, isGitRepo } from './git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
-import { lockFilePath, statusFilePath } from './auto-pull.js';
-const LOCK_TTL_MS = 5 * 60 * 1000;
+import { lockFilePath, statusFilePath, markDetachedSyncComplete, SYNC_LOCK_TTL_MS, } from './auto-pull.js';
 /**
  * Background auto-pull of ~/.agents/.system/ is off by default. When enabled it
  * silently fast-forwards a tracked source tree that the CLI then reads as a
@@ -38,7 +37,7 @@ function tryAcquireLock(alias) {
     const lock = lockFilePath(alias);
     try {
         const stat = fs.statSync(lock);
-        if (Date.now() - stat.mtimeMs < LOCK_TTL_MS)
+        if (Date.now() - stat.mtimeMs < SYNC_LOCK_TTL_MS)
             return false;
     }
     catch {
@@ -130,6 +129,11 @@ async function main() {
         }
     }
     await Promise.all(targets.map(processTarget));
+    // Stamp the cycle so the next foreground CLI invocation can skip the ~7ms
+    // detached spawn for SYNC_LOCK_TTL_MS (RUSH-2324). Written even when every
+    // target was lock-skipped or the target list was empty — "nothing to do"
+    // is still a completed cycle.
+    markDetachedSyncComplete();
 }
 main().catch(() => {
     /* swallow — detached worker must never crash the parent's terminal */

package/dist/lib/auto-pull.d.ts

@@ -9,11 +9,26 @@
  * Public API:
  *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
  *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
+ *   shouldSkipDetachedSync() — parent-side recency gate (RUSH-2324).
+ *   markDetachedSyncComplete() — worker stamps a completed cycle for the parent gate.
  */
+/**
+ * Shared 5-minute recency window for per-repo locks (worker) and the parent
+ * spawn gate (RUSH-2324). Worker skips a repo when its lock mtime is younger
+ * than this; the parent skips the entire detached spawn when a recent cycle
+ * completed or every existing lock is still within the window.
+ */
+export declare const SYNC_LOCK_TTL_MS: number;
 /** Per-repo lock file path. mtime acts as a recency check. */
-export declare function lockFilePath(alias: string): string;
+export declare function lockFilePath(alias: string, fetchDir?: string): string;
 /** Per-repo status marker path (for user/extras only). */
-export declare function statusFilePath(alias: string): string;
+export declare function statusFilePath(alias: string, fetchDir?: string): string;
+/**
+ * Stamp written at the end of every detached-worker cycle (including the
+ * no-target / all-locks-skipped path). Parent `spawnDetachedSync` stats this
+ * one file instead of forking a child on every ordinary CLI invocation.
+ */
+export declare function lastSyncStampPath(fetchDir?: string): string;
 export interface FetchStatusMarker {
     alias: string;
     dir: string;
@@ -22,8 +37,34 @@ export interface FetchStatusMarker {
     branch: string;
     fetchedAt: number;
 }
+/**
+ * Whether the parent should skip forking the detached auto-pull worker.
+ *
+ * True when either:
+ *   1. `.last-sync` exists and its mtime is within {@link SYNC_LOCK_TTL_MS}
+ *      (a prior cycle completed recently — the common warm path), or
+ *   2. the fetch dir has at least one `*.lock` and every lock is still within
+ *      the same window (a worker is mid-flight, or a cycle left locks that
+ *      still count as fresh).
+ *
+ * False (spawn) when the stamp is missing/stale and there are no fresh locks
+ * — including a missing fetch dir and an empty one. Cheap: one `stat` or one
+ * `readdir` + a few `stat`s; never spawns and never reads git.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
+ * @param now - Override the clock (for tests).
+ * @param ttlMs - Override the recency window (for tests).
+ */
+export declare function shouldSkipDetachedSync(fetchDir?: string, now?: number, ttlMs?: number): boolean;
+/**
+ * Record that a detached-worker cycle finished (success, empty targets, or
+ * every repo skipped by its lock). Best-effort; a failed write just means the
+ * next foreground invocation will re-spawn the worker.
+ */
+export declare function markDetachedSyncComplete(fetchDir?: string): void;
 /** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
-export declare function spawnDetachedSync(): void;
+export declare function spawnDetachedSync(fetchDir?: string): void;
 /**
  * Read all current status markers and return those where the local repo is
  * behind upstream. Markers are NOT deleted — they persist until the next

package/dist/lib/auto-pull.js

@@ -9,6 +9,8 @@
  * Public API:
  *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
  *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
+ *   shouldSkipDetachedSync() — parent-side recency gate (RUSH-2324).
+ *   markDetachedSyncComplete() — worker stamps a completed cycle for the parent gate.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -16,22 +18,103 @@ import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getFetchCacheDir } from './state.js';
 import { backgroundSpawnOptions } from './platform/process.js';
+/**
+ * Shared 5-minute recency window for per-repo locks (worker) and the parent
+ * spawn gate (RUSH-2324). Worker skips a repo when its lock mtime is younger
+ * than this; the parent skips the entire detached spawn when a recent cycle
+ * completed or every existing lock is still within the window.
+ */
+export const SYNC_LOCK_TTL_MS = 5 * 60 * 1000;
 /** Where lock files and per-repo status markers live. */
 function fetchStateDir() {
     return getFetchCacheDir();
 }
 /** Per-repo lock file path. mtime acts as a recency check. */
-export function lockFilePath(alias) {
-    return path.join(fetchStateDir(), `${alias}.lock`);
+export function lockFilePath(alias, fetchDir) {
+    return path.join(fetchDir ?? fetchStateDir(), `${alias}.lock`);
 }
 /** Per-repo status marker path (for user/extras only). */
-export function statusFilePath(alias) {
-    return path.join(fetchStateDir(), `${alias}.status.json`);
+export function statusFilePath(alias, fetchDir) {
+    return path.join(fetchDir ?? fetchStateDir(), `${alias}.status.json`);
+}
+/**
+ * Stamp written at the end of every detached-worker cycle (including the
+ * no-target / all-locks-skipped path). Parent `spawnDetachedSync` stats this
+ * one file instead of forking a child on every ordinary CLI invocation.
+ */
+export function lastSyncStampPath(fetchDir) {
+    return path.join(fetchDir ?? fetchStateDir(), '.last-sync');
+}
+function isMtimeFresh(filePath, now, ttlMs) {
+    try {
+        return now - fs.statSync(filePath).mtimeMs < ttlMs;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the parent should skip forking the detached auto-pull worker.
+ *
+ * True when either:
+ *   1. `.last-sync` exists and its mtime is within {@link SYNC_LOCK_TTL_MS}
+ *      (a prior cycle completed recently — the common warm path), or
+ *   2. the fetch dir has at least one `*.lock` and every lock is still within
+ *      the same window (a worker is mid-flight, or a cycle left locks that
+ *      still count as fresh).
+ *
+ * False (spawn) when the stamp is missing/stale and there are no fresh locks
+ * — including a missing fetch dir and an empty one. Cheap: one `stat` or one
+ * `readdir` + a few `stat`s; never spawns and never reads git.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
+ * @param now - Override the clock (for tests).
+ * @param ttlMs - Override the recency window (for tests).
+ */
+export function shouldSkipDetachedSync(fetchDir, now = Date.now(), ttlMs = SYNC_LOCK_TTL_MS) {
+    const dir = fetchDir ?? fetchStateDir();
+    if (isMtimeFresh(lastSyncStampPath(dir), now, ttlMs))
+        return true;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return false;
+    }
+    const locks = entries.filter((name) => name.endsWith('.lock'));
+    if (locks.length === 0)
+        return false;
+    return locks.every((name) => isMtimeFresh(path.join(dir, name), now, ttlMs));
+}
+/**
+ * Record that a detached-worker cycle finished (success, empty targets, or
+ * every repo skipped by its lock). Best-effort; a failed write just means the
+ * next foreground invocation will re-spawn the worker.
+ */
+export function markDetachedSyncComplete(fetchDir) {
+    const dir = fetchDir ?? fetchStateDir();
+    const stamp = lastSyncStampPath(dir);
+    try {
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(stamp, String(Date.now()));
+    }
+    catch {
+        /* best-effort */
+    }
 }
 /** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
-export function spawnDetachedSync() {
+export function spawnDetachedSync(fetchDir) {
     if (process.env.AGENTS_NO_AUTOPULL === '1')
         return;
+    // RUSH-2324: the spawn itself costs ~7ms mean on a warm box, and the worker
+    // almost always no-ops when a cycle ran in the last five minutes. Inspect
+    // the last-sync stamp + lock mtimes in the parent and skip the fork when
+    // everything is still fresh.
+    if (shouldSkipDetachedSync(fetchDir))
+        return;
     // Resolve the worker path relative to the compiled location of this module.
     // After `tsc`, both files land in the same directory under dist/lib/.
     const here = path.dirname(fileURLToPath(import.meta.url));

package/dist/lib/binary-shadow.d.ts

@@ -0,0 +1,28 @@
+export interface AgentsBinaryShadow {
+    /** Path of the shadowing binary as it appears to the caller. */
+    path: string;
+    /** Its self-reported version, if we can run it. */
+    version?: string;
+}
+/**
+ * Whether two path spellings identify the same file.
+ *
+ * Two spellings of one file rarely compare equal on Windows: `realpathSync` does
+ * not expand 8.3 short names, so a path rooted at `os.tmpdir()`
+ * (`C:\Users\RUNNER~1\...` on a GitHub runner) never matches the long form
+ * (`C:\Users\runneradmin\...`) that `where` reports. Compare by device+inode
+ * first and fall back to case-insensitive resolved spellings.
+ */
+export declare function sameFile(a: string, b: string): boolean;
+/**
+ * Find `agents` installs that are NOT the currently running binary.
+ *
+ * Checks two sources:
+ *   1. The current PATH: if `which agents` / `where agents` resolves to a
+ *      different real binary than the one executing this code, it is an active
+ *      shadow.
+ *   2. Well-known install directories: any executable `agents` whose realpath
+ *      differs from the current entry is a latent shadow — it may win under a
+ *      different PATH (e.g. the daemon's service-managed PATH).
+ */
+export declare function detectAgentsBinaryShadows(currentBin?: string, extraDirs?: readonly string[]): AgentsBinaryShadow[];

package/dist/lib/binary-shadow.js

@@ -0,0 +1,121 @@
+/**
+ * Detect `agents` binaries that could shadow the currently running CLI.
+ *
+ * Scheduled command routines invoke the bare name `agents`. When an older install
+ * appears earlier on PATH than the current binary, routines silently run stale
+ * code (RUSH-2431). This module finds those shadows so `agents doctor` can warn.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getAgentsBinPath } from './cli-entry.js';
+/** Realpath of `p`, or `p` itself if it cannot be resolved. */
+function safeRealpath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Whether two path spellings identify the same file.
+ *
+ * Two spellings of one file rarely compare equal on Windows: `realpathSync` does
+ * not expand 8.3 short names, so a path rooted at `os.tmpdir()`
+ * (`C:\Users\RUNNER~1\...` on a GitHub runner) never matches the long form
+ * (`C:\Users\runneradmin\...`) that `where` reports. Compare by device+inode
+ * first and fall back to case-insensitive resolved spellings.
+ */
+export function sameFile(a, b) {
+    try {
+        const aStat = fs.statSync(a);
+        const bStat = fs.statSync(b);
+        if (aStat.dev === bStat.dev && aStat.ino === bStat.ino)
+            return true;
+    }
+    catch { /* compare their resolved path spellings below */ }
+    const aReal = safeRealpath(a);
+    const bReal = safeRealpath(b);
+    return process.platform === 'win32'
+        ? aReal.toLowerCase() === bReal.toLowerCase()
+        : aReal === bReal;
+}
+/**
+ * Find `agents` installs that are NOT the currently running binary.
+ *
+ * Checks two sources:
+ *   1. The current PATH: if `which agents` / `where agents` resolves to a
+ *      different real binary than the one executing this code, it is an active
+ *      shadow.
+ *   2. Well-known install directories: any executable `agents` whose realpath
+ *      differs from the current entry is a latent shadow — it may win under a
+ *      different PATH (e.g. the daemon's service-managed PATH).
+ */
+export function detectAgentsBinaryShadows(currentBin = getAgentsBinPath(), extraDirs = defaultWellKnownDirs()) {
+    const currentReal = safeRealpath(currentBin);
+    const seen = new Set();
+    const shadows = [];
+    function addIfShadow(candidate) {
+        if (seen.has(candidate))
+            return;
+        seen.add(candidate);
+        if (sameFile(candidate, currentReal))
+            return;
+        let version;
+        try {
+            version = execFileSync(candidate, ['--version'], { encoding: 'utf-8', env: process.env })
+                .trim()
+                .split('\n')[0];
+        }
+        catch { /* binary may be unreadable/unrunnable — still report it */ }
+        shadows.push({ path: candidate, version });
+    }
+    // Active shadow under the current environment's PATH.
+    try {
+        const resolver = process.platform === 'win32' ? 'where' : 'which';
+        const pathAgents = execFileSync(resolver, ['agents'], { encoding: 'utf-8', env: process.env })
+            .split(/\r?\n/)
+            .map((s) => s.trim())
+            .filter(Boolean)[0];
+        if (pathAgents && !sameFile(pathAgents, currentReal)) {
+            addIfShadow(pathAgents);
+        }
+    }
+    catch { /* no `agents` resolved on PATH */ }
+    // Latent shadows in well-known install locations.
+    for (const dir of extraDirs) {
+        for (const name of agentBinaryNames()) {
+            const candidate = path.join(dir, name);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                addIfShadow(candidate);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return shadows;
+}
+function agentBinaryNames() {
+    return process.platform === 'win32' ? ['agents.exe', 'agents.cmd', 'agents'] : ['agents'];
+}
+function defaultWellKnownDirs() {
+    const home = os.homedir();
+    if (process.platform === 'win32') {
+        const programFiles = process.env.ProgramFiles ?? 'C:\\Program Files';
+        return [
+            path.join(home, 'AppData', 'Roaming', 'npm'),
+            path.join(programFiles, 'nodejs'),
+            path.dirname(process.execPath),
+        ];
+    }
+    return [
+        path.join(home, '.local', 'bin'),
+        '/usr/local/bin',
+        '/opt/homebrew/bin',
+        path.join(home, '.npm-global', 'bin'),
+        path.join(home, '.bun', 'bin'),
+        path.dirname(process.execPath),
+    ];
+}

package/dist/lib/brand.js

@@ -17,7 +17,13 @@
  * where the active profile is resolved brand-first.
  */
 import { readMeta, updateMeta } from './state.js';
-import { ALL_AGENT_IDS, AGENTS } from './agents.js';
+// Leaf list only — do NOT import agents.js here. index.ts imports brand on
+// every invocation (resolveBrandName / disabledCommandsForActiveBrand); a
+// static agents import pulls the full agents.ts → versions.ts graph (~90ms)
+// into --version/--help and the secrets-broker hot path (RUSH-2331).
+// reservedBrandNames is only called when minting a brand; AGENT_CLI_COMMANDS
+// is pinned equal to AGENTS[*].cliCommand by agent-cli-commands.test.ts.
+import { AGENT_CLI_COMMANDS } from './agent-cli-commands.js';
 /** The default (unbranded) program name. */
 export const DEFAULT_CLI_NAME = 'agents';
 /** Valid brand names: a letter, then letters/digits/_/- (matches alias rules). */
@@ -45,8 +51,8 @@ export function isBranded() {
 /** Names that would clobber an agent CLI shim or the `agents`/`ag` binary. */
 export function reservedBrandNames() {
     const reserved = new Set([DEFAULT_CLI_NAME, 'ag']);
-    for (const id of ALL_AGENT_IDS)
-        reserved.add(AGENTS[id].cliCommand);
+    for (const cmd of AGENT_CLI_COMMANDS)
+        reserved.add(cmd);
     return reserved;
 }
 /** Validate a proposed brand name; returns an error string or null when ok. */

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

@@ -34,9 +34,39 @@ export declare class BrowserIPCConnection {
 export declare class BrowserIPCServer {
     private server;
     private service;
+    /** Live client connections, so {@link stop} can end them rather than wait. */
+    private connections;
+    /** In-flight stop, so a second SIGTERM awaits the same close, never skips it. */
+    private stopping;
     constructor(service: BrowserService);
     start(): Promise<void>;
+    /**
+     * Stop accepting, release the binding, and only then resolve.
+     *
+     * RUSH-2421: this used to call `server.close()` and move on. `close()` is
+     * asynchronous — it stops accepting immediately but the binding is not
+     * actually released until the `'close'` event fires — so `stop()` resolved
+     * while the socket (or named pipe) was still held. The daemon's
+     * `handleShutdown` awaits this before it exits, and a successor's
+     * `claimDaemonInstance` waits for that exit as its proof the predecessor's
+     * resources are free (SING-11). Resolving early made that proof false: the
+     * newcomer could bind before the incumbent's binding was gone, which is the
+     * two-servers-on-one-socket orphan the eviction protocol exists to prevent.
+     *
+     * The first version of this waited out a timeout instead, and that made every
+     * graceful daemon stop escalate to `killTree`: `close()` does not complete
+     * while a connection is open, browser clients hold one open on purpose, and
+     * the timeout was set equal to the daemon's own SIGTERM grace window
+     * (`STOP_GRACE_MS`) — so `handleShutdown` was still inside `stop()` when
+     * `stopDaemon` gave up waiting and killed it. So we END the connections
+     * rather than wait for them: `close()` stops accepting, destroying the
+     * tracked sockets lets it complete, and the timeout is only a backstop for a
+     * socket that will not die, deliberately far below `STOP_GRACE_MS`.
+     */
     stop(): Promise<void>;
+    private doStop;
+    /** Release the listening binding, resolving only once it is genuinely gone. */
+    private closeServer;
     private handleRequest;
 }
 /**