@phnx-labs/agents-cli 1.22.26 → 1.22.28

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;
 }

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

@@ -23,6 +23,42 @@ export declare function resolveOwner(pidActor: string | null | undefined, sessio
  * cwds are just gathered at a bounded spawn rate instead of a single burst.
  */
 export declare const LSOF_CONCURRENCY = 4;
+/**
+ * Process-local process-table memo (#2047). One `getActiveSessions` scan can
+ * call `ps -A` from the terminal path, the headless path, and host ancestry —
+ * without this, each is a full process-table snapshot. 5s is well under the
+ * ~10–30s menu-bar / `--active` poll so a quiet re-poll usually reuses the
+ * snapshot; a brand-new agent pid still appears on the next full refresh.
+ */
+export declare const PROCESS_TABLE_FRESH_MS = 5000;
+/**
+ * How long {@link listUnattributedActive} may reuse its last full `ps`+`lsof`
+ * result (#2047). Between full rescans the previous rows are re-emitted after
+ * dropping dead PIDs and PIDs that are now attributed. A *shrinking* attributed
+ * set forces a rescan so a process that just left teams/terminals can reappear
+ * as headless instead of vanishing until the next cold poll.
+ */
+export declare const UNATTRIBUTED_RESCAN_MS = 15000;
+/** Test seam: override the clock used by process-table / unattributed memos. */
+export declare function setActiveScanClockForTest(fn?: () => number): void;
+/** Test seam: drop the process-table + unattributed memos and their counters. */
+export declare function clearActiveScanCachesForTest(): void;
+/** Test seam: how many times the live `ps` / CIM path actually ran. */
+export declare function processTableLiveReadCountForTest(): number;
+/** Test seam: how many full unattributed (ps + lsof) rescans ran. */
+export declare function unattributedFullRescanCountForTest(): number;
+/**
+ * True when any pid in `prev` is absent from `next` — the attributed set
+ * shrank, so a process may need to reappear as unattributed. Pure for tests.
+ */
+export declare function attributedSetLostPids(prev: Set<number>, next: Set<number>): boolean;
+/**
+ * Drop rows whose pid is now attributed or no longer alive. Pure over the
+ * inputs so the unattributed TTL reuse path is unit-testable without a live
+ * process table. `alive` receives the row's `startedAtMs` so callers can apply
+ * the same pid-reuse guard {@link isPidAlive} uses elsewhere.
+ */
+export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /**
  * Every status here is COMPUTED by the framework from observable signals — PID
@@ -348,6 +384,8 @@ export declare function resolveNamesToSessionIds(sessionNames: string[], deps: {
  * the start time can't be read, we keep the existence answer.
  */
 export declare function isPidAlive(pid: number, startedAtMs?: number): boolean;
+/** Test seam: drop the Claude session-file path memo. */
+export declare function clearClaudeSessionFileCacheForTest(): void;
 /**
  * Resolve a Claude transcript for `cwd` across the given project roots, newest
  * mtime winning when the same id/cwd resolves in more than one version home
@@ -431,6 +469,8 @@ interface LiveSignals {
     /** Rolling output-token throughput (tokens/sec). Undefined when no usage in the tail. */
     tokPerSec?: number;
 }
+/** Test seam: drop the in-process live-signals memo. */
+export declare function clearLiveSignalsCacheForTest(): void;
 /**
  * Derive the inferred state (working / waiting / idle + preview/badges) and, for
  * the two harnesses whose raw lines carry it, the output-token throughput.
@@ -444,6 +484,9 @@ interface LiveSignals {
  * `unknown` it used to fall through to. An opaque/untracked kind or an
  * unreadable/empty transcript yields an empty signal set, and the caller's
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
+ *
+ * Unchanged-mtime hits reuse the previous result (see {@link liveSignalsCache})
+ * so a 30s active-session poll does not re-tail every quiet transcript.
  */
 export declare function computeLiveSignals(kind: string, sessionFile: string | undefined, cwd: string | undefined, pidAlive: boolean): LiveSignals;
 /**
@@ -523,6 +566,12 @@ export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppid
  * Classified by walking the ppid chain: any recognised UI ancestor (IDE
  * helper, terminal-app, or multiplexer) means `terminal`; nothing of the
  * sort means `headless` (daemon, launchd-spawned, orphan).
+ *
+ * Full `ps`+`lsof` rescans are throttled to {@link UNATTRIBUTED_RESCAN_MS}
+ * (#2047). Between rescans the previous rows are re-emitted after dropping
+ * dead PIDs and PIDs that are now attributed. A shrinking attributed set
+ * forces a rescan so a process that just left teams/terminals can reappear
+ * as headless.
  */
 export declare function listUnattributedActive(attributed: Set<number>): Promise<ActiveSession[]>;
 /** One tmux pane's resolved agent identity for the authoritative source. */

package/dist/lib/session/active.js

@@ -71,6 +71,74 @@ const LSOF_STAGGER_MS = 10;
  */
 const LSOF_TIMEOUT_MS = 5_000;
 const PS_SNAPSHOT_TIMEOUT_MS = 10_000;
+/**
+ * Process-local process-table memo (#2047). One `getActiveSessions` scan can
+ * call `ps -A` from the terminal path, the headless path, and host ancestry —
+ * without this, each is a full process-table snapshot. 5s is well under the
+ * ~10–30s menu-bar / `--active` poll so a quiet re-poll usually reuses the
+ * snapshot; a brand-new agent pid still appears on the next full refresh.
+ */
+export const PROCESS_TABLE_FRESH_MS = 5_000;
+/**
+ * How long {@link listUnattributedActive} may reuse its last full `ps`+`lsof`
+ * result (#2047). Between full rescans the previous rows are re-emitted after
+ * dropping dead PIDs and PIDs that are now attributed. A *shrinking* attributed
+ * set forces a rescan so a process that just left teams/terminals can reappear
+ * as headless instead of vanishing until the next cold poll.
+ */
+export const UNATTRIBUTED_RESCAN_MS = 15_000;
+/** Injectable clock for the active-scan memos (tests only). */
+let activeScanNow = () => Date.now();
+/** Test seam: override the clock used by process-table / unattributed memos. */
+export function setActiveScanClockForTest(fn) {
+    activeScanNow = fn ?? (() => Date.now());
+}
+let processTableCache;
+let processTableLiveReads = 0;
+let unattributedCache;
+let unattributedFullRescans = 0;
+/** Test seam: drop the process-table + unattributed memos and their counters. */
+export function clearActiveScanCachesForTest() {
+    processTableCache = undefined;
+    processTableLiveReads = 0;
+    unattributedCache = undefined;
+    unattributedFullRescans = 0;
+    activeScanNow = () => Date.now();
+}
+/** Test seam: how many times the live `ps` / CIM path actually ran. */
+export function processTableLiveReadCountForTest() {
+    return processTableLiveReads;
+}
+/** Test seam: how many full unattributed (ps + lsof) rescans ran. */
+export function unattributedFullRescanCountForTest() {
+    return unattributedFullRescans;
+}
+/**
+ * True when any pid in `prev` is absent from `next` — the attributed set
+ * shrank, so a process may need to reappear as unattributed. Pure for tests.
+ */
+export function attributedSetLostPids(prev, next) {
+    for (const p of prev) {
+        if (!next.has(p))
+            return true;
+    }
+    return false;
+}
+/**
+ * Drop rows whose pid is now attributed or no longer alive. Pure over the
+ * inputs so the unattributed TTL reuse path is unit-testable without a live
+ * process table. `alive` receives the row's `startedAtMs` so callers can apply
+ * the same pid-reuse guard {@link isPidAlive} uses elsewhere.
+ */
+export function filterCachedUnattributed(sessions, attributed, alive) {
+    return sessions.filter((s) => {
+        if (s.pid == null)
+            return false;
+        if (attributed.has(s.pid))
+            return false;
+        return alive(s.pid, s.startedAtMs);
+    });
+}
 export function activeStatusFromCloudStatus(status) {
     switch (status) {
         case 'running':
@@ -373,6 +441,19 @@ function readLiveTerminals() {
 function claudeProjectDirName(cwd) {
     return cwd.replace(/[/.]/g, '-');
 }
+/**
+ * Process-local memo for Claude transcript path resolution. Each active-session
+ * poll re-walks every Claude version-home `projects/` tree for every live pid
+ * (#2047). A resolved path is sticky while the file still exists; a miss or a
+ * vanished file re-walks. Cap size so a long-lived process cannot retain every
+ * cwd it has ever seen.
+ */
+const CLAUDE_SESSION_FILE_CACHE_MAX = 256;
+const claudeSessionFileCache = new Map();
+/** Test seam: drop the Claude session-file path memo. */
+export function clearClaudeSessionFileCacheForTest() {
+    claudeSessionFileCache.clear();
+}
 /**
  * Locate the active Claude session file for a process. If we know the session
  * UUID (from terminal env or team parent), prefer the exact match. Otherwise
@@ -390,6 +471,28 @@ function claudeProjectDirName(cwd) {
  * the rest of the CLI uses, so this stays in lockstep with discovery.
  */
 function findClaudeSessionFile(cwd, sessionId) {
+    // Only memoize when the exact session UUID is known. Without an id the
+    // resolver picks newest-by-mtime under the project dir; caching that path
+    // would stick to an old transcript after a new session starts in the same cwd.
+    if (sessionId) {
+        const cacheKey = `${cwd}\0${sessionId}`;
+        const hit = claudeSessionFileCache.get(cacheKey);
+        if (hit !== undefined) {
+            try {
+                if (fs.existsSync(hit))
+                    return hit;
+            }
+            catch { /* re-resolve */ }
+            claudeSessionFileCache.delete(cacheKey);
+        }
+        const resolved = pickClaudeSessionFileAcrossRoots(getAgentSessionDirs('claude', 'projects'), cwd, sessionId);
+        if (resolved) {
+            if (claudeSessionFileCache.size >= CLAUDE_SESSION_FILE_CACHE_MAX)
+                claudeSessionFileCache.clear();
+            claudeSessionFileCache.set(cacheKey, resolved);
+        }
+        return resolved;
+    }
     return pickClaudeSessionFileAcrossRoots(getAgentSessionDirs('claude', 'projects'), cwd, sessionId);
 }
 /**
@@ -562,6 +665,19 @@ function parseTailEventsForKind(agent, sessionFile) {
     }
     return events.length > LIVE_STATE_MAX_EVENTS ? events.slice(-LIVE_STATE_MAX_EVENTS) : events;
 }
+/**
+ * Process-local memo for {@link computeLiveSignals}. The menu-bar / `--active`
+ * poll re-reads every live session on a ~30s tick (#2047). When a transcript's
+ * mtime (and pidAlive / kind / cwd) are unchanged, re-parsing the tail yields
+ * the same signals — skip the parse. Bound the map so a long-lived daemon that
+ * sees thousands of sessions over its life cannot retain them forever.
+ */
+const LIVE_SIGNALS_CACHE_MAX = 512;
+const liveSignalsCache = new Map();
+/** Test seam: drop the in-process live-signals memo. */
+export function clearLiveSignalsCacheForTest() {
+    liveSignalsCache.clear();
+}
 /**
  * Derive the inferred state (working / waiting / idle + preview/badges) and, for
  * the two harnesses whose raw lines carry it, the output-token throughput.
@@ -575,6 +691,9 @@ function parseTailEventsForKind(agent, sessionFile) {
  * `unknown` it used to fall through to. An opaque/untracked kind or an
  * unreadable/empty transcript yields an empty signal set, and the caller's
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
+ *
+ * Unchanged-mtime hits reuse the previous result (see {@link liveSignalsCache})
+ * so a 30s active-session poll does not re-tail every quiet transcript.
  */
 export function computeLiveSignals(kind, sessionFile, cwd, pidAlive) {
     if (!sessionFile)
@@ -584,21 +703,31 @@ export function computeLiveSignals(kind, sessionFile, cwd, pidAlive) {
         mtimeMs = fs.statSync(sessionFile).mtimeMs;
     }
     catch { /* vanished between calls */ }
+    const cacheKey = `${kind}\0${sessionFile}\0${cwd ?? ''}`;
+    const cached = liveSignalsCache.get(cacheKey);
+    if (cached && cached.mtimeMs === mtimeMs && cached.pidAlive === pidAlive) {
+        return cached.signals;
+    }
     const ctx = { cwd, pidAlive, mtimeMs, activeWindowMs: ACTIVE_MTIME_WINDOW_MS };
+    let signals = {};
     if (kind === 'claude' || kind === 'codex') {
         const { events, content } = readSessionTailWithRaw(sessionFile, kind);
-        if (events.length === 0)
-            return {};
-        const state = inferSessionState(events, ctx);
-        const tokPerSec = computeTokPerSec(content, kind);
-        return { state, tokPerSec: tokPerSec > 0 ? tokPerSec : undefined };
+        if (events.length > 0) {
+            const state = inferSessionState(events, ctx);
+            const tokPerSec = computeTokPerSec(content, kind);
+            signals = { state, tokPerSec: tokPerSec > 0 ? tokPerSec : undefined };
+        }
     }
-    if (!isSessionTrackedAgent(kind))
-        return {};
-    const events = parseTailEventsForKind(kind, sessionFile);
-    if (events.length === 0)
-        return {};
-    return { state: inferSessionState(events, ctx) };
+    else if (isSessionTrackedAgent(kind)) {
+        const events = parseTailEventsForKind(kind, sessionFile);
+        if (events.length > 0) {
+            signals = { state: inferSessionState(events, ctx) };
+        }
+    }
+    if (liveSignalsCache.size >= LIVE_SIGNALS_CACHE_MAX)
+        liveSignalsCache.clear();
+    liveSignalsCache.set(cacheKey, { mtimeMs, pidAlive, signals });
+    return signals;
 }
 /** Map inferred activity onto the coarse ActiveStatus used by the renderer and counts. */
 function statusFromActivity(activity) {
@@ -880,8 +1009,24 @@ const HOST_MATCHERS = [
  * walk ancestry chains to attribute child processes to their terminal hosts.
  * `comm` may be an absolute path for shim-launched agents, so basename before
  * matching against AGENT_CLI_NAMES.
+ *
+ * Memoized for {@link PROCESS_TABLE_FRESH_MS} so one active-session scan (and a
+ * quiet re-poll within the window) does not re-shell `ps -A` / CIM for every
+ * caller — terminal host detection, headless attribution, and `hostFromPid`
+ * all share the same snapshot (#2047).
  */
 async function readProcessTable() {
+    const now = activeScanNow();
+    if (processTableCache && now - processTableCache.at < PROCESS_TABLE_FRESH_MS) {
+        return processTableCache.rows;
+    }
+    const rows = await readProcessTableLive();
+    processTableCache = { at: now, rows };
+    return rows;
+}
+/** Uncached process-table snapshot (the live `ps` / CIM path). */
+async function readProcessTableLive() {
+    processTableLiveReads += 1;
     if (process.platform === 'win32')
         return readProcessTableWin32();
     let out;
@@ -1138,8 +1283,27 @@ export function foldSubordinateAgents(candidates, ppidMap, readEntry) {
  * Classified by walking the ppid chain: any recognised UI ancestor (IDE
  * helper, terminal-app, or multiplexer) means `terminal`; nothing of the
  * sort means `headless` (daemon, launchd-spawned, orphan).
+ *
+ * Full `ps`+`lsof` rescans are throttled to {@link UNATTRIBUTED_RESCAN_MS}
+ * (#2047). Between rescans the previous rows are re-emitted after dropping
+ * dead PIDs and PIDs that are now attributed. A shrinking attributed set
+ * forces a rescan so a process that just left teams/terminals can reappear
+ * as headless.
  */
 export async function listUnattributedActive(attributed) {
+    const now = activeScanNow();
+    if (unattributedCache &&
+        now - unattributedCache.at < UNATTRIBUTED_RESCAN_MS &&
+        !attributedSetLostPids(unattributedCache.attributed, attributed)) {
+        return filterCachedUnattributed(unattributedCache.sessions, attributed, isPidAlive);
+    }
+    const out = await listUnattributedActiveLive(attributed);
+    unattributedCache = { at: now, attributed: new Set(attributed), sessions: out };
+    return out;
+}
+/** Unthrottled headless scan (live process table + cwd probes). */
+async function listUnattributedActiveLive(attributed) {
+    unattributedFullRescans += 1;
     const table = await readProcessTable();
     const procByPid = new Map();
     const ppidMap = new Map();

package/dist/lib/session/bash-command.d.ts

@@ -19,6 +19,22 @@ export interface BashCommandInfo {
     summary: string;
     signal: 'high' | 'mid' | 'low';
 }
+/**
+ * TOOL_REGISTRY (category + action, aliases flattened to their own keys)
+ * serialized as the body of a Python dict literal. The embedded activity-log
+ * hook script (`ACTIVITY_LOG_HOOK_SCRIPT` in `activity.ts`) runs standalone
+ * under `python3` and can't import this module, so its taxonomy is generated
+ * from this single source instead of hand-duplicated (#1889 — the two had
+ * already drifted: the hand-authored copy was missing `rmdir`).
+ */
+export declare function pythonToolRegistryLiteral(indent?: string): string;
+/**
+ * VALUE_FLAGS serialized as the body of a Python dict of sets. Same reason as
+ * {@link pythonToolRegistryLiteral}: the activity-log hook script embeds this
+ * table and must not hand-drift from the TypeScript source (#1889 — the Python
+ * copy was missing `agents`/`linear` two-level tools).
+ */
+export declare function pythonValueFlagsLiteral(indent?: string): string;
 export declare function unwrapCommand(cmd: string): string;
 /**
  * Split a possibly-compound Bash command into simple commands, then tokenize each

package/dist/lib/session/bash-command.js

@@ -95,6 +95,25 @@ const TOOL_REGISTRY = {
     sleep: { category: 'wait', signal: 'low', action: 'sleeping' },
     wait: { category: 'wait', signal: 'low', action: 'waiting' },
 };
+/**
+ * TOOL_REGISTRY (category + action, aliases flattened to their own keys)
+ * serialized as the body of a Python dict literal. The embedded activity-log
+ * hook script (`ACTIVITY_LOG_HOOK_SCRIPT` in `activity.ts`) runs standalone
+ * under `python3` and can't import this module, so its taxonomy is generated
+ * from this single source instead of hand-duplicated (#1889 — the two had
+ * already drifted: the hand-authored copy was missing `rmdir`).
+ */
+export function pythonToolRegistryLiteral(indent = '    ') {
+    const lines = [];
+    for (const [name, info] of Object.entries(TOOL_REGISTRY)) {
+        const entry = `{"category": ${JSON.stringify(info.category)}, "action": ${JSON.stringify(info.action)}}`;
+        lines.push(`${indent}${JSON.stringify(name)}: ${entry},`);
+        for (const alias of info.aliases ?? []) {
+            lines.push(`${indent}${JSON.stringify(alias)}: ${entry},`);
+        }
+    }
+    return lines.join('\n');
+}
 /**
  * Two-level tools (bucket key includes the subcommand) mapped to the flags that
  * consume the *following* token as their value, per tool. The subcommand scan
@@ -124,6 +143,25 @@ const VALUE_FLAGS = {
     agents: new Set(['-H', '--host', '--device']),
     linear: new Set(),
 };
+/**
+ * VALUE_FLAGS serialized as the body of a Python dict of sets. Same reason as
+ * {@link pythonToolRegistryLiteral}: the activity-log hook script embeds this
+ * table and must not hand-drift from the TypeScript source (#1889 — the Python
+ * copy was missing `agents`/`linear` two-level tools).
+ */
+export function pythonValueFlagsLiteral(indent = '    ') {
+    const lines = [];
+    for (const [name, flags] of Object.entries(VALUE_FLAGS)) {
+        if (flags.size === 0) {
+            lines.push(`${indent}${JSON.stringify(name)}: set(),`);
+            continue;
+        }
+        // Stable order for golden-string equality (install/write checks).
+        const items = [...flags].sort().map((f) => JSON.stringify(f)).join(', ');
+        lines.push(`${indent}${JSON.stringify(name)}: {${items}},`);
+    }
+    return lines.join('\n');
+}
 /** Tools whose bucket key includes the second token (subcommand). */
 const TWO_LEVEL_TOOLS = new Set(Object.keys(VALUE_FLAGS));
 /** Remote wrappers whose bucket key carries an `ssh→` prefix on the inner command. */
@@ -145,10 +183,20 @@ export function unwrapCommand(cmd) {
     const env = s.match(/^([A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)+(.+)$/);
     if (env)
         return unwrapCommand(env[2]);
+    // export VAR=value prefix, same shape as the bare env-var prefix above (#1889)
+    const exportPrefix = s.match(/^export\s+(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)*[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;|\n)\s*([\s\S]+)$/);
+    if (exportPrefix)
+        return unwrapCommand(exportPrefix[1]);
     // sudo / time prefix (value-taking flags like `-u user` consume their argument)
     const prefix = s.match(/^(?:sudo|time)(?:\s+(?:-[uUgGhpCrtDR]\s+\S+|-\S+))*\s+(.+)$/);
     if (prefix)
         return unwrapCommand(prefix[1]);
+    // set -euo pipefail && command / set -x; command (shell-option prefix; `-o`
+    // mode names like `pipefail` trail a flag without their own `-`, so consume
+    // everything up to the first operator rather than itemizing flag shapes)
+    const setPrefix = s.match(/^set\s+[^&;\n]+?(?:&&|;|\n)\s*([\s\S]+)$/);
+    if (setPrefix)
+        return unwrapCommand(setPrefix[1]);
     // cd foo && command  (also `cd foo; command` and newline-separated `cd foo\ncommand`)
     const cd = s.match(/^cd\s+\S+\s*(?:&&|;|\n)\s*([\s\S]+)$/);
     if (cd)
@@ -157,6 +205,23 @@ export function unwrapCommand(cmd) {
     const npx = s.match(/^(?:npx|bunx)\s+(?:-\S+\s+)*(.+)$/);
     if (npx)
         return unwrapCommand(npx[1]);
+    // for X in ...; do command; done — unwrap to the loop body, not the `for` keyword
+    const forLoop = s.match(/^for\s+[\s\S]+?\bdo\b\s*([\s\S]+?)\s*;?\s*done\b[\s\S]*$/);
+    if (forLoop)
+        return unwrapCommand(forLoop[1]);
+    // until condition; do command; done
+    const untilLoop = s.match(/^until\s+[\s\S]+?\bdo\b\s*([\s\S]+?)\s*;?\s*done\b[\s\S]*$/);
+    if (untilLoop)
+        return unwrapCommand(untilLoop[1]);
+    // if condition; then command; fi — unwrap to the `then` branch, the real work;
+    // the condition itself is usually a test/comparison, not the command of interest
+    const ifCond = s.match(/^if\s+[\s\S]+?\bthen\b\s*([\s\S]+?)\s*;?\s*(?:elif\b|else\b|fi\b)[\s\S]*$/);
+    if (ifCond)
+        return unwrapCommand(ifCond[1]);
+    // (command) subshell, e.g. `(gh pr create --title x)` or `(cd /repo && npm i)`
+    const subshell = s.match(/^\(\s*([\s\S]+?)\s*\)\s*(?:&&|;|\|\|)[\s\S]*$/) ?? s.match(/^\(\s*([\s\S]+?)\s*\)\s*$/);
+    if (subshell)
+        return unwrapCommand(subshell[1]);
     return s;
 }
 function splitOnOperators(cmd) {

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

@@ -12,7 +12,7 @@ import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 36;
+export declare const SCHEMA_VERSION = 37;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -26,7 +26,8 @@ export declare const RESOURCE_INDEX_VERSION = 1;
  * re-derives on the next `agents insights` instead of silently reporting stale
  * numbers alongside fresh ones. Same role as RESOURCE_INDEX_VERSION.
  */
-export declare const INSIGHTS_EXTRACTOR_VERSION = 4;
+/** Bump when facet extraction changes so cached rows recompute (stalls-by-model v6). */
+export declare const INSIGHTS_EXTRACTOR_VERSION = 6;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -50,7 +51,11 @@ export interface SessionRow {
     message_count: number | null;
     token_count: number | null;
     output_tokens: number | null;
+    input_tokens: number | null;
+    cache_read_tokens: number | null;
+    cache_write_tokens: number | null;
     cost_usd: number | null;
+    cost_usd_nocache: number | null;
     duration_ms: number | null;
     model: string | null;
     tool_call_count: number | null;
@@ -318,6 +323,10 @@ export declare function latestSessionFileForCwd(agent: SessionAgentId, cwd: stri
     maxAgeMs?: number;
     nowMs?: number;
 }): string | undefined;
+/** Process-local diagnostics for the real-filesystem existence-cache tests. */
+export declare function getSessionExistenceCacheStats(): {
+    sweeps: number;
+};
 /** Query sessions from the database, applying filters and ordering by last-activity descending (default). */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
@@ -335,11 +344,23 @@ export interface UsageRollupRow {
      */
     label?: string;
     costUsd: number;
+    /**
+     * USD cost priced as if caching were off (cache read/write at the input rate),
+     * summed from `cost_usd_nocache`. Backs `agents output --pricing no-cache`.
+     * Equals `costUsd` for rows whose sessions record no cache split (RUSH-2287).
+     */
+    costUsdNoCache: number;
     durationMs: number;
     sessionCount: number;
     tokenCount: number;
     /** Real generated (output) tokens — excludes cache-read/-write context. */
     outputTokens: number;
+    /** Uncached input tokens summed across the group (0 where no harness recorded a split). */
+    inputTokens: number;
+    /** Cache-read tokens summed across the group. */
+    cacheReadTokens: number;
+    /** Cache-write (cache-creation) tokens summed across the group. */
+    cacheWriteTokens: number;
 }
 /** What to group a usage rollup by. */
 /**