@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/secrets/download-keychain.js

@@ -0,0 +1,70 @@
+/**
+ * On-demand download + verification of the macOS keychain broker helper
+ * ("Agents CLI.app").
+ *
+ * Mirrors the ComputerHelper / MenubarHelper download model
+ * (`../helper-download.ts`): the helper ships as a signed + notarized `.app`
+ * zipped as a GitHub release asset on the helper's own `keychain/v<x.y.z>` tag,
+ * NOT the CLI's tag (see `helper-versions.ts`). A fresh `npm i -g`
+ * machine whose tarball lacks a bundled copy fetches the asset for the running
+ * CLI version, verifies its sha256 + code signature before install.
+ *
+ * Unlike the menu-bar helper, the keychain helper pins NO designated
+ * requirement (no `expectedBundleId`). The menu-bar `expectedBundleId` exists
+ * because macOS keys the Accessibility (TCC) grant to the bundle's designated
+ * requirement, so a substituted bundle whose DR does not pin (id, team) would
+ * silently revoke that upgrade-stable grant. The keychain helper has no such
+ * DR-keyed grant to protect: its items are gated by the access-group
+ * entitlement (`keychain-helper.swift` → `kSecAttrAccessGroup`, the
+ * `keychain-access-groups` entitlement) plus a biometry `SecAccessControl`
+ * (user presence) — NOT a `SecTrustedApplication` ACL keyed to a bundle-id/DR.
+ * The release-time gate `scripts/verify-keychain-helper.sh` correspondingly
+ * pins the executable's sha256, not a designated requirement. So Team +
+ * notarization is the verification boundary here, exactly like ComputerHelper.
+ */
+import { EXPECTED_TEAM_ID, downloadHelperApp, helperAssetUrls, helperCacheDir, verifyHelperApp, } from '../helper-download.js';
+/** The zipped `.app` release asset name (the bundle name has a space). */
+// Underscore, and NOT a space. GitHub rewrites a space in a release-asset name
+// to a dot on upload, so an asset staged as `Agents CLI.app.zip` is SERVED as
+// `Agents.CLI.app.zip` and a client asking for the spaced name 404s forever --
+// which is exactly what shipped. The fix is to CHOOSE a name GitHub leaves
+// alone rather than to mirror its rewrite: `Agents.CLI.app.zip` would work by
+// matching an artifact of that behavior, and would silently break if the
+// normalization rule ever changed. Underscores are preserved verbatim (verified
+// against a real upload).
+//
+// The bundle DIRECTORY inside the zip keeps its space (`appName` below) -- that
+// is the on-disk bundle name macOS and the TCC grant key on, and it is unchanged.
+export const KEYCHAIN_HELPER_ASSET = 'Agents_CLI.app.zip';
+/** The bundle directory name once extracted. */
+export const KEYCHAIN_HELPER_APP_NAME = 'Agents CLI.app';
+/** Keychain-helper identity + verification policy — Team + notarization only,
+ *  no DR pin (see docblock). */
+export const KEYCHAIN_HELPER_SPEC = {
+    helper: 'keychain',
+    assetName: KEYCHAIN_HELPER_ASSET,
+    appName: KEYCHAIN_HELPER_APP_NAME,
+    cacheSubdir: ['secrets', 'mac-helper'],
+    expectedTeamId: EXPECTED_TEAM_ID,
+    localBuildHint: 'cli/scripts/build-keychain-helper.sh',
+};
+/** Release-asset URLs for the keychain helper zip + its checksum at `v<version>`. */
+export function keychainHelperAssetUrls(version) {
+    return helperAssetUrls(KEYCHAIN_HELPER_SPEC, version);
+}
+/** Cache dir for the downloaded keychain helper, one subdir per release tag. */
+export function keychainHelperCacheDir(version) {
+    return helperCacheDir(KEYCHAIN_HELPER_SPEC, version);
+}
+/** Verify a keychain helper `.app`: codesign + Team + notarization (no DR pin). */
+export function verifyKeychainHelper(appPath) {
+    verifyHelperApp(appPath, KEYCHAIN_HELPER_SPEC);
+}
+/**
+ * Download the keychain helper release asset for `version`, verify sha256 +
+ * signature, and return the path to the extracted `Agents CLI.app` in the
+ * cache. A missing asset is a hard error naming the exact tag.
+ */
+export function downloadKeychainHelperApp(version) {
+    return downloadHelperApp(KEYCHAIN_HELPER_SPEC, version);
+}

package/dist/lib/secrets/install-helper.d.ts

@@ -29,6 +29,20 @@ export declare function setInstallRootForTest(dir: string | null): string | null
 export declare function ensureKeychainHelperInstalled(opts?: {
     forceReinstall?: boolean;
 }): void;
+/**
+ * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
+ * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
+ * locally-built `.app` ships (the common case, and always true this release
+ * stage), it installs that copy with NO network. When the tarball lacks the
+ * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
+ * notarized release asset for the running CLI version — sha256 + codesign +
+ * Team + notarization verified before install — and installs from the cached
+ * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
+ * network-free and fails loud toward this command when no source exists.
+ */
+export declare function ensureKeychainHelperInstalledAsync(opts?: {
+    forceReinstall?: boolean;
+}): Promise<void>;
 /**
  * Return the absolute path to the helper executable. If the installed bundle
  * is missing, or is stale relative to the bundled source helper, performs a
@@ -37,7 +51,12 @@ export declare function ensureKeychainHelperInstalled(opts?: {
  * `npm i -g`, so this call site is the only one every machine is guaranteed to
  * pass through.
  *
- * Throws on non-darwin.
+ * SYNC and network-free by design: this is the secrets hot path, called by
+ * every keychain op. It never downloads. When no bundled/local source exists
+ * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
+ * loud, directing the user to `agents setup secrets` — the explicit, async,
+ * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
+ * non-darwin.
  */
 export declare function getKeychainHelperPath(): string;
 /** Diagnostic snapshot of the installed Keychain helper. */

package/dist/lib/secrets/install-helper.js

@@ -19,6 +19,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
+import { downloadKeychainHelperApp } from './download-keychain.js';
+import { helperFloor } from '../helper-versions.js';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 let installRootOverride = null;
@@ -60,7 +62,18 @@ function sourceAppPath() {
             return c;
     }
     throw new Error(`Source ${APP_BUNDLE_NAME} not found. Looked in:\n  ${candidates.join('\n  ')}\n` +
-        'The npm package may have been built without the signed helper bundle. Reinstall agents-cli.');
+        'The npm package shipped without the bundled keychain helper. Run `agents setup secrets` to ' +
+        'download the signed helper for this version, or reinstall agents-cli.');
+}
+/** The bundled/local source `.app`, or null when absent (no throw) — the async
+ *  download path resolves the missing bundle instead of failing. */
+function bundledSourceAppPathOrNull() {
+    try {
+        return sourceAppPath();
+    }
+    catch {
+        return null;
+    }
 }
 function assertDarwin() {
     if (process.platform !== 'darwin') {
@@ -122,6 +135,30 @@ function spctlAssess(appPath) {
  */
 export function ensureKeychainHelperInstalled(opts = {}) {
     assertDarwin();
+    installKeychainHelperFromSource(sourceAppPath(), opts);
+}
+/**
+ * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
+ * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
+ * locally-built `.app` ships (the common case, and always true this release
+ * stage), it installs that copy with NO network. When the tarball lacks the
+ * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
+ * notarized release asset for the running CLI version — sha256 + codesign +
+ * Team + notarization verified before install — and installs from the cached
+ * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
+ * network-free and fails loud toward this command when no source exists.
+ */
+export async function ensureKeychainHelperInstalledAsync(opts = {}) {
+    assertDarwin();
+    const bundled = bundledSourceAppPathOrNull();
+    const src = bundled ?? (await downloadKeychainHelperApp(helperFloor('keychain')));
+    installKeychainHelperFromSource(src, opts);
+}
+/**
+ * Copy `src` (a verified `.app` bundle) to the stable user path, then verify.
+ * Shared by the sync (bundled-source) and async (download-capable) installers.
+ */
+function installKeychainHelperFromSource(src, opts = {}) {
     const dest = installedAppPath();
     const upToDate = () => fs.existsSync(dest) && codesignVerify(dest).ok && !installedHelperIsStale();
     // Fast path: already installed, valid, and current — no lock, no copy.
@@ -134,7 +171,6 @@ export function ensureKeychainHelperInstalled(opts = {}) {
     withInstallLock(dest, (heartbeat) => {
         if (!opts.forceReinstall && upToDate())
             return;
-        const src = sourceAppPath();
         copyAppBundle(src, dest);
         heartbeat(); // cp -R done; keep the lock fresh across the codesign/spctl spawns
         const verify = codesignVerify(dest);
@@ -160,7 +196,12 @@ export function ensureKeychainHelperInstalled(opts = {}) {
  * `npm i -g`, so this call site is the only one every machine is guaranteed to
  * pass through.
  *
- * Throws on non-darwin.
+ * SYNC and network-free by design: this is the secrets hot path, called by
+ * every keychain op. It never downloads. When no bundled/local source exists
+ * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
+ * loud, directing the user to `agents setup secrets` — the explicit, async,
+ * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
+ * non-darwin.
  */
 export function getKeychainHelperPath() {
     assertDarwin();

package/dist/lib/session/active.js

@@ -2068,10 +2068,26 @@ export function foldHostLink(rows) {
         // disproves. A stored record never yields `attached` (it is background or
         // parked), so clearing only that value drops the derived lie and leaves a
         // real detach record untouched.
-        if (link !== 'connected' && s.presence === 'attached')
+        // Only a POSITIVE loss signal disproves a derived `attached`. `unknown` means
+        // we never looked — a bare terminal with no IDE window and no tmux has
+        // neither input — so it must not clear presence, or every plain-terminal
+        // session the user is sitting in would lose its `attached` marker.
+        if ((link === 'no-client' || link === 'host-gone') && s.presence === 'attached') {
             s.presence = undefined;
+        }
         if (link === 'host-gone' && s.status === 'closed')
             s.status = 'crashed';
+        // Only idle/input_required are promoted — a `running` session keeps its
+        // status (SES-18a). Extending this to a running agent with no client was
+        // tried and reverted: since RUSH-3125 wraps every remote interactive run in
+        // a detached tmux pane, "running with zero attached clients" is the NORMAL
+        // steady state between check-ins, and that path writes no detach record, so
+        // `deliberatelyDetached` is false for it. Promoting it would relabel every
+        // remote agent as orphaned whenever nobody is looking — the over-reporting
+        // this file's header calls worthless. Telling a stranded agent from a
+        // healthy unattended one needs to know a client was EXPECTED and LOST, which
+        // no signal available here carries; that belongs with the peer-side pane
+        // ownership work, not this function.
         else if (link === 'no-client' && (s.status === 'idle' || s.status === 'input_required')) {
             s.status = 'orphaned';
         }

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/sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 39;
+export declare const SCHEMA_VERSION = 40;
 /**
  * Bumping this invalidates every cached facet row without touching the schema
  * version, so a change to the extraction logic (a new metric, a corrected bucket)
@@ -21,6 +21,7 @@ export declare const SCHEMA_VERSION = 39;
  */
 /** Bump when facet extraction changes so cached rows recompute (stalls-by-model v6). */
 export declare const INSIGHTS_EXTRACTOR_VERSION = 6;
+export declare const SESSION_TOPIC_EXTRACTOR_VERSION = 1;
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
     fileMtimeMs: number;
@@ -338,6 +339,15 @@ export declare function writeSessionInsights<T>(entries: Array<{
 }>): void;
 /** Drop every cached facet row. Backs `agents insights --refresh`. */
 export declare function clearSessionInsights(): void;
+/** Read cached trace topics only when their transcript byte stamps still match. */
+export declare function readSessionTopics<T>(ids: string[]): Map<string, T>;
+/** Persist trace topics against the exact transcript bytes used to classify them. */
+export declare function writeSessionTopics<T>(entries: Array<{
+    id: string;
+    fileMtimeMs: number | null;
+    fileSize: number | null;
+    topic: T;
+}>): void;
 /** Read one derived preview only when it matches the transcript bytes on disk. */
 export declare function readSessionPreviewCache<T>(id: string, sourceStamp: {
     fileMtimeMs: number | null;

package/dist/lib/session/db.js

@@ -18,7 +18,7 @@ import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.j
 import { toolCallsFromEvents } from './tool-calls.js';
 import { persistToolCalls, toolEvidenceSourcePath } from './tool-store.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
-import { extractSkills, extractSlashCommands } from './highlights.js';
+import { extractBackgroundShells, extractSkills, extractSlashCommands, harnessTracksBackgroundShells, isSubAgentTool, } from './highlights.js';
 import { resolveResource } from '../resources.js';
 import { discoverPlugins } from '../plugins/plugins.js';
 import { machineId } from '../machine-id.js';
@@ -27,7 +27,7 @@ const DB_PATH = getSessionsDbPath();
 /** 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/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 39;
+export const SCHEMA_VERSION = 40;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -100,6 +100,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   worktree_slug TEXT,
   ticket_id TEXT,
   spawned_team TEXT,
+  sub_agent_count INTEGER,
+  background_shell_count INTEGER,
   plan TEXT,
   machine TEXT,
   todos TEXT,
@@ -314,6 +316,17 @@ CREATE TABLE IF NOT EXISTS session_insights (
   facets TEXT NOT NULL
 );
 
+-- Derived topic classification for traces sync. Like session_insights, this is
+-- a lazy, stamp-validated cache and is intentionally independent of SCHEMA_VERSION.
+CREATE TABLE IF NOT EXISTS session_topics (
+  session_id TEXT PRIMARY KEY,
+  file_mtime_ms INTEGER,
+  file_size INTEGER,
+  extractor_version INTEGER NOT NULL,
+  computed_at INTEGER NOT NULL,
+  topic_json TEXT NOT NULL
+);
+
 -- Normalized data behind sessions preview. Like session_insights this is a
 -- lazy, stamp-validated cache: opening one session parses only that transcript,
 -- while subsequent processes reuse the derived preview until its bytes change.
@@ -397,6 +410,7 @@ CREATE INDEX IF NOT EXISTS idx_computer_sessions_started ON computer_sessions(st
  */
 /** Bump when facet extraction changes so cached rows recompute (stalls-by-model v6). */
 export const INSIGHTS_EXTRACTOR_VERSION = 6;
+export const SESSION_TOPIC_EXTRACTOR_VERSION = 1;
 const PREVIEW_EXTRACTOR_VERSION = 1;
 let dbInstance = null;
 /**
@@ -1037,6 +1051,27 @@ function migrateSchema(db, fromVersion) {
       CREATE INDEX IF NOT EXISTS idx_computer_sessions_started ON computer_sessions(started_at DESC);
     `);
     }
+    if (fromVersion < 40) {
+        // v39 -> v40: persist the fan-out a session left behind — sub-agents spawned
+        // and shells backgrounded (RUSH-3091/3095). Both were recomputed per render
+        // from the transcript, so a REMOTE or unindexed row (rendered from
+        // SessionMeta alone by sessions-picker's formatMetaOnlyBody, which has no
+        // events to derive from) showed neither. Columns are what make them
+        // renderable there.
+        //
+        // New nullable columns, so no ledger flush — the v33->v34 contract that
+        // adding a column keeps warm session ledgers warm. Pre-upgrade rows stay
+        // NULL until re-scanned, and NULL is deliberately distinct from 0: NULL is
+        // "not computed / harness cannot report it", 0 is "scanned, none found".
+        // The renders omit the segment for both, so neither can be misread as a
+        // positive "nothing is running" claim.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
+        if (!cols.has('sub_agent_count'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN sub_agent_count INTEGER`);
+        if (!cols.has('background_shell_count')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN background_shell_count INTEGER`);
+        }
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -1554,7 +1589,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     output_tokens, input_tokens, cache_read_tokens, cache_write_tokens,
     cost_usd, cost_usd_nocache, duration_ms, model, tool_call_count,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
-    pr_url, pr_number, worktree_slug, ticket_id, spawned_team, plan, todos,
+    pr_url, pr_number, worktree_slug, ticket_id, spawned_team,
+    sub_agent_count, background_shell_count, plan, todos,
     recent_directories_touched, linear_project, linear_project_url, machine,
     actor, initiated_by, used_browser, used_computer
   ) VALUES (
@@ -1564,7 +1600,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     @output_tokens, @input_tokens, @cache_read_tokens, @cache_write_tokens,
     @cost_usd, @cost_usd_nocache, @duration_ms, @model, @tool_call_count,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
-    @pr_url, @pr_number, @worktree_slug, @ticket_id, @spawned_team, @plan, @todos,
+    @pr_url, @pr_number, @worktree_slug, @ticket_id, @spawned_team,
+    @sub_agent_count, @background_shell_count, @plan, @todos,
     @recent_directories_touched, @linear_project, @linear_project_url, @machine,
     @actor, @initiated_by, @used_browser, @used_computer
   )
@@ -1615,6 +1652,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     worktree_slug = excluded.worktree_slug,
     ticket_id = excluded.ticket_id,
     spawned_team = excluded.spawned_team,
+    sub_agent_count = COALESCE(excluded.sub_agent_count, sessions.sub_agent_count),
+    background_shell_count = COALESCE(excluded.background_shell_count, sessions.background_shell_count),
     plan = excluded.plan,
     todos = excluded.todos,
     recent_directories_touched = excluded.recent_directories_touched,
@@ -1752,6 +1791,30 @@ function writeResourceUsageFromTallies(sessionId, skills, commands, cwd) {
 function writeResourceUsage(sessionId, events, cwd) {
     writeResourceUsageFromTallies(sessionId, extractSkills(events), extractSlashCommands(events), cwd);
 }
+/**
+ * Fan-out the session left behind, from an ALREADY-parsed transcript (never a
+ * re-parse — every caller here has `events` in hand).
+ *
+ * `backgroundShellCount` is `undefined`, not 0, for a harness that cannot report
+ * backgrounded shells. That distinction is the whole point: 0 asserts "none were
+ * started", while undefined says "this harness does not record it" — and the
+ * renders omit the segment for both, so neither can read as "nothing is running".
+ */
+function fanOutCounts(events, agent) {
+    let subAgentCount = 0;
+    for (const e of events) {
+        if (e.type !== 'tool_use' || e._local)
+            continue;
+        if (isSubAgentTool(e.tool || '', e.command || ''))
+            subAgentCount++;
+    }
+    return {
+        subAgentCount,
+        backgroundShellCount: harnessTracksBackgroundShells(agent)
+            ? extractBackgroundShells(events).length
+            : undefined,
+    };
+}
 function enrichCachedSessionMeta(meta) {
     if (!meta.filePath)
         return meta;
@@ -1762,6 +1825,7 @@ function enrichCachedSessionMeta(meta) {
             ...meta,
             todos: extractTodoProgressFromEvents(events),
             recentDirectoriesTouched: extractRecentDirectoriesTouched(events, meta.cwd),
+            ...fanOutCounts(events, meta.agent),
         };
     }
     catch {
@@ -1858,6 +1922,8 @@ export function upsertSession(meta, content, scan) {
         worktree_slug: meta.worktreeSlug ?? null,
         ticket_id: meta.ticketId ?? null,
         spawned_team: meta.spawnedTeam ?? null,
+        sub_agent_count: meta.subAgentCount ?? null,
+        background_shell_count: meta.backgroundShellCount ?? null,
         plan: meta.plan ?? null,
         todos: meta.todos ? JSON.stringify(meta.todos) : null,
         recent_directories_touched: meta.recentDirectoriesTouched ? JSON.stringify(meta.recentDirectoriesTouched) : null,
@@ -1917,8 +1983,16 @@ export function upsertSessionsBatch(entries) {
         .filter(e => e.scan && e.meta.filePath)
         .map(e => [canonicalLedgerKey(e.meta.filePath), e]));
     const enrichedEntries = entries.map(entry => {
-        if (entry.meta.agent === 'claude' || entry.meta.agent === 'codex' || !entry.meta.filePath)
-            return entry;
+        if (entry.meta.agent === 'claude' || entry.meta.agent === 'codex' || !entry.meta.filePath) {
+            // claude/codex keep their resumable-parse optimization (no transcript read
+            // here). When their scanner already handed us normalized events, the counts
+            // are free — take them. Otherwise leave them undefined, which persists NULL
+            // and means "not computed yet", and the next scan that carries events fills
+            // it. Never collapse that to 0: see fanOutCounts.
+            return entry.events
+                ? { ...entry, meta: { ...entry.meta, ...fanOutCounts(entry.events, entry.meta.agent) } }
+                : entry;
+        }
         try {
             const toolSourcePath = toolEvidenceSourcePath(entry.meta.filePath, entry.meta.agent);
             const toolScan = toolSourcePath === entry.meta.filePath
@@ -1938,6 +2012,7 @@ export function upsertSessionsBatch(entries) {
                     ...entry.meta,
                     todos: extractTodoProgressFromEvents(events),
                     recentDirectoriesTouched: extractRecentDirectoriesTouched(events, entry.meta.cwd),
+                    ...fanOutCounts(events, entry.meta.agent),
                 },
                 toolCalls: toolCallsFromEvents(events),
                 toolScan,
@@ -2042,6 +2117,8 @@ export function upsertSessionsBatch(entries) {
                     worktree_slug: meta.worktreeSlug ?? null,
                     ticket_id: meta.ticketId ?? null,
                     spawned_team: meta.spawnedTeam ?? null,
+                    sub_agent_count: meta.subAgentCount ?? null,
+                    background_shell_count: meta.backgroundShellCount ?? null,
                     plan: meta.plan ?? null,
                     todos: meta.todos ? JSON.stringify(meta.todos) : null,
                     recent_directories_touched: meta.recentDirectoriesTouched ? JSON.stringify(meta.recentDirectoriesTouched) : null,
@@ -2265,6 +2342,8 @@ function rowToMeta(row) {
         worktreeSlug: row.worktree_slug ?? undefined,
         ticketId: row.ticket_id ?? undefined,
         spawnedTeam: row.spawned_team ?? undefined,
+        subAgentCount: row.sub_agent_count ?? undefined,
+        backgroundShellCount: row.background_shell_count ?? undefined,
         plan: row.plan ?? undefined,
         todos: parseJsonColumn(row.todos),
         recentDirectoriesTouched: parseJsonColumn(row.recent_directories_touched),
@@ -2690,6 +2769,59 @@ export function writeSessionInsights(entries) {
 export function clearSessionInsights() {
     getDB().exec(`DELETE FROM session_insights`);
 }
+/** Read cached trace topics only when their transcript byte stamps still match. */
+export function readSessionTopics(ids) {
+    const db = getDB();
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    const CHUNK = 400;
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db.prepare(`
+      SELECT st.session_id AS id, st.topic_json AS topicJson
+      FROM session_topics st
+      JOIN sessions s ON s.id = st.session_id
+      WHERE st.session_id IN (${placeholders})
+        AND st.extractor_version = ?
+        AND st.file_mtime_ms IS s.file_mtime_ms
+        AND st.file_size IS s.file_size
+    `).all(...chunk, SESSION_TOPIC_EXTRACTOR_VERSION);
+        for (const row of rows) {
+            try {
+                out.set(row.id, JSON.parse(row.topicJson));
+            }
+            catch {
+                // Invalid derived cache data is a miss and self-heals on the next write.
+            }
+        }
+    }
+    return out;
+}
+/** Persist trace topics against the exact transcript bytes used to classify them. */
+export function writeSessionTopics(entries) {
+    if (entries.length === 0)
+        return;
+    const db = getDB();
+    const stmt = db.prepare(`
+    INSERT INTO session_topics
+      (session_id, file_mtime_ms, file_size, extractor_version, computed_at, topic_json)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      computed_at = excluded.computed_at,
+      topic_json = excluded.topic_json
+  `);
+    const now = Date.now();
+    db.transaction(() => {
+        for (const entry of entries) {
+            stmt.run(entry.id, entry.fileMtimeMs, entry.fileSize, SESSION_TOPIC_EXTRACTOR_VERSION, now, JSON.stringify(entry.topic));
+        }
+    })();
+}
 /** Read one derived preview only when it matches the transcript bytes on disk. */
 export function readSessionPreviewCache(id, sourceStamp) {
     const row = getDB().prepare(`

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

@@ -122,6 +122,9 @@ interface ClaudeSessionScan {
         name: string;
         count: number;
     }>;
+    /** Fan-out left behind (RUSH-3091/3095) — see SessionMeta.subAgentCount. */
+    subAgentCount?: number;
+    backgroundShellCount?: number;
     /** Slash commands invoked (#12) — see SessionMeta.slashCommandsUsed. */
     slashCommandsUsed?: Array<{
         name: string;
@@ -481,6 +484,14 @@ interface ClaudeParseState {
     /** Slash-command events (user-typed <command-name> wrapper OR a SlashCommand
      *  tool_use), held for extractSlashCommands() at finalize (#12). */
     slashCommandEvents: SessionEvent[];
+    /**
+     * Fan-out tallies (RUSH-3091/3095). Counted as we stream rather than held as
+     * events — unlike skills we need only the count, and a busy session can spawn
+     * hundreds. `backgroundShells` stays undefined for a harness with no
+     * background-shell concept, which must render as absence, never as 0.
+     */
+    subAgents: number;
+    backgroundShells: number | undefined;
 }
 /** Zero-value accumulator for a fresh (from-byte-0) Claude parse. */
 export declare function initClaudeParseState(): ClaudeParseState;
@@ -510,7 +521,16 @@ export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessi
  * exact even when the recent window is smaller than the true count.
  */
 export interface ClaudeParserState {
-    v: 3;
+    v: 4;
+    /**
+     * Fan-out tallies carried across a RESUMED parse (RUSH-3091/3095). They must
+     * live in the durable blob: the resumable parser reads only new bytes, so
+     * re-initialising them on hydrate would report a session's tail, not its
+     * total. Adding them is why `v` moved 3 -> 4 — an older blob is rejected and
+     * the session re-parses from byte 0 with correct totals.
+     */
+    subAgents: number;
+    backgroundShells: number | undefined;
     offset: number;
     jsonlDroppingOversizedLine?: boolean;
     timestamp?: string;

package/dist/lib/session/discover.js

@@ -26,8 +26,8 @@ import { getConfigSymlinkVersion } from '../installations/shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { deriveShortId } from './short-id.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
-import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput } from './prompt.js';
-import { isSkillInvocation, extractSkills, extractSlashCommands } from './highlights.js';
+import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, classifyUserPrompt } from './prompt.js';
+import { isBackgroundShellStart, isSkillInvocation, extractSkills, extractSlashCommands, isSubAgentTool } from './highlights.js';
 import { parseAntigravity, parseCursor, splitSessionFilePath } from './parse.js';
 import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket, extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { costOfUsage, costOfUsageNoCache } from '../pricing/index.js';
@@ -1239,6 +1239,8 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, label) {
             todos: scan.todos,
             recentDirectoriesTouched: scan.recentDirectoriesTouched,
             skillsUsed: scan.skillsUsed,
+            subAgentCount: scan.subAgentCount,
+            backgroundShellCount: scan.backgroundShellCount,
             slashCommandsUsed: scan.slashCommandsUsed,
         };
     }
@@ -1280,6 +1282,8 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, label) {
             todos: scan.todos,
             recentDirectoriesTouched: scan.recentDirectoriesTouched,
             skillsUsed: scan.skillsUsed,
+            subAgentCount: scan.subAgentCount,
+            backgroundShellCount: scan.backgroundShellCount,
             slashCommandsUsed: scan.slashCommandsUsed,
         };
     }
@@ -2996,6 +3000,8 @@ function extractDroidMessageText(content) {
 /** Zero-value accumulator for a fresh (from-byte-0) Claude parse. */
 export function initClaudeParseState() {
     return {
+        subAgents: 0,
+        backgroundShells: 0,
         timestamp: undefined,
         cwd: undefined,
         gitBranch: undefined,
@@ -3044,6 +3050,14 @@ function foldDerivedToolState(state, event) {
     // from a full re-parse (see session/db.ts's writeResourceUsage doc comment).
     if (isSkillInvocation(event))
         state.skillEvents.push(event);
+    // Fan-out tallies (RUSH-3091/3095): counted, not held — we need the number,
+    // and a heavy orchestrator session can spawn hundreds of each.
+    if (state.subAgents !== undefined && isSubAgentTool(event.tool ?? '', event.command ?? '')) {
+        state.subAgents += 1;
+    }
+    if (state.backgroundShells !== undefined && isBackgroundShellStart(event)) {
+        state.backgroundShells += 1;
+    }
     if (event.tool === 'SlashCommand') {
         const slashCommand = extractSlashCommandFromToolInput(event.args);
         if (slashCommand)
@@ -3254,7 +3268,15 @@ export function finalizeClaudeScan(state) {
     // A topic is the first meaningful prompt. Harness-owned names travel in the
     // separate label field so consumers can replace an early topic once Claude's
     // generated title (or a later `/rename`) arrives.
-    const label = state.customTitle || state.aiTitle;
+    // Claude's generated `ai-title` is derived from the first turn, so a session
+    // opened with a skill gets named after the injected "Base directory for this
+    // skill: …" line instead of its task — and that name then wins on every
+    // surface for the session's whole life. `classifyUserPrompt` reports `skill`
+    // only for that injected line, so collapse it to `/<skill>`. A `/rename`
+    // (`custom-title`) is the user's own words and is never rewritten.
+    const generated = classifyUserPrompt(state.aiTitle ?? '');
+    const label = state.customTitle
+        || (generated.kind === 'skill' ? generated.clean : state.aiTitle);
     const worktree = detectWorktree(state.cwd, state.gitBranch);
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
@@ -3289,6 +3311,8 @@ export function finalizeClaudeScan(state) {
         recentDirectoriesTouched: state.recentDirectoriesTouched.length ? state.recentDirectoriesTouched : undefined,
         skillsUsed: state.skillEvents.length ? extractSkills(state.skillEvents) : undefined,
         slashCommandsUsed: state.slashCommandEvents.length ? extractSlashCommands(state.slashCommandEvents) : undefined,
+        subAgentCount: state.subAgents,
+        backgroundShellCount: state.backgroundShells,
     };
 }
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
@@ -3330,7 +3354,9 @@ export function serializeClaudeParserState(state, offset, jsonlDroppingOversized
         : allIds;
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
-        v: 3,
+        v: 4,
+        subAgents: state.subAgents,
+        backgroundShells: state.backgroundShells,
         offset,
         jsonlDroppingOversizedLine: jsonlDroppingOversizedLine || undefined,
         timestamp: state.timestamp,
@@ -3402,6 +3428,8 @@ export function hydrateClaudeParseState(prior) {
         seen.add(`pad:${pad++}`);
     }
     return {
+        subAgents: prior.subAgents,
+        backgroundShells: prior.backgroundShells,
         timestamp: prior.timestamp,
         cwd: prior.cwd,
         gitBranch: prior.gitBranch,
@@ -3569,7 +3597,7 @@ function parsePriorClaudeState(row) {
         return null;
     try {
         const parsed = JSON.parse(row.parserState);
-        if (parsed?.v !== 3 || typeof parsed.offset !== 'number' || parsed.toolCalls?.v !== 1)
+        if (parsed?.v !== 4 || typeof parsed.offset !== 'number' || parsed.toolCalls?.v !== 1)
             return null;
         return parsed;
     }