@phnx-labs/agents-cli 1.22.46 → 1.22.49

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

@@ -1,6 +1,7 @@
 import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
 import { type HookSessionIndex } from './hook-sessions.js';
+import { type UserPromptKind } from './prompt.js';
 import { type SessionState, type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 import { type SessionAgentId, type SessionAttachment, type SessionMeta } from './types.js';
 import { type SessionProvenance } from './provenance.js';
@@ -99,6 +100,15 @@ export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'c
  | 'orphaned'
 /** The host window died and took the agent with it — an unclean exit, not a normal close. */
  | 'crashed' | 'unknown';
+/**
+ * Which rung of the recap ladder produced a row's shown {@link ActiveSession.title}
+ * (RUSH-3011), best-first:
+ *   - `label`  — a `/rename` or harness-set label (incl. an agent-generated
+ *                title, which lands in `label`); always wins.
+ *   - `last`   — the last assistant line from the transcript tail; agent-derived.
+ *   - `prompt` — the first-user-prompt topic; the last-resort fallback.
+ */
+export type RecapSource = 'label' | 'last' | 'prompt';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -115,6 +125,30 @@ export interface ActiveSession {
     name?: string;
     /** First meaningful line of the initial prompt (extracted topic). */
     topic?: string;
+    /**
+     * The row's shown title — WHAT the session is, best-source-wins (RUSH-3011).
+     * The ladder ({@link deriveSessionRecap}): a `/rename` or harness `label` →
+     * the last agent line (`lastAgentLine`) → the first-prompt `topic`. A session
+     * whose agent did work shows an agent-derived line, not the stale first
+     * prompt. Folded on at the end of {@link getActiveSessions}; `recapSource`
+     * names which rung produced it.
+     */
+    title?: string;
+    /** Which ladder rung produced {@link title}. */
+    recapSource?: RecapSource;
+    /**
+     * The first user turn cleaned for a "You" line — a screenshot path folds to
+     * `[image]`, a pasted `$ cmd` to the command, a `/skill` install path to
+     * `/<name>`, so path noise never shows. See {@link classifyUserPrompt}.
+     */
+    userPromptClean?: string;
+    /** What kind of first turn {@link userPromptClean} was. */
+    userPromptKind?: UserPromptKind;
+    /**
+     * The most recent assistant line (from the transcript tail) — the free,
+     * always-current signal of what the agent last said/did. Ladder rung 3.
+     */
+    lastAgentLine?: string;
     /** Live preview: the latest turn (agent message or tool action), from the state engine. */
     preview?: string;
     /** Inferred activity: working / waiting_input / idle (from the transcript tail). */
@@ -787,6 +821,39 @@ export declare function sessionProcessIsLocal(s: Pick<ActiveSession, 'machine' |
  */
 export declare function sessionProcessHost(s: Pick<ActiveSession, 'machine' | 'offloadedFrom'>, self: string): string | undefined;
 export declare function foldHostLink(rows: ActiveSession[]): void;
+/**
+ * The recap ladder (RUSH-3011): compute a row's shown {@link ActiveSession.title}
+ * + {@link RecapSource} from the best available source, plus the cleaned first
+ * prompt (`userPromptClean`/`userPromptKind`) and the `lastAgentLine`. Pure over
+ * one row; exported for tests and folded in by {@link foldRecap}.
+ *
+ * Ladder, best-first: a `/rename`/harness `label` → the last assistant line →
+ * the first-prompt topic. The `last` rung is agent-derived, so a session that
+ * produced work stops showing its stale first prompt as the title. (`topic` is
+ * the row's already-extracted first line, so image detection here is
+ * path-based; a pure-attachment turn with no first-line text stays on `prompt`.)
+ */
+export declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 'topic' | 'tail'>): {
+    title?: string;
+    recapSource?: RecapSource;
+    userPromptClean?: string;
+    userPromptKind?: UserPromptKind;
+    lastAgentLine?: string;
+};
+/** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
+export declare function foldRecap(rows: ActiveSession[]): void;
+/**
+ * True when a crash-leaked orphan is genuinely DEAD and should be reaped from the
+ * reconnectable set rather than shown as resumable forever (RUSH-3011 / issue #3b).
+ *
+ * The gate is `abandoned` (no transcript write in {@link ABANDONED_STALE_MS}) AND
+ * a dead pid — exactly "past the stale threshold whose pid is gone". A live pid
+ * (an idle-but-unfinished session, the highest-risk state) is NEVER reaped, and
+ * neither is a recently-`closed`/`crashed` session that just exited (still
+ * resumable). `pidAlive` absent (a cloud row or an older peer that can't prove
+ * death) also stays un-reaped — reaping is fail-safe, never a guess.
+ */
+export declare function isReapableOrphan(row: Pick<ActiveSession, 'status' | 'pidAlive'>): boolean;
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the

package/dist/lib/session/active.js

@@ -30,7 +30,7 @@ import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord
 import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
 import { latestSessionFileForCwd, findSessionsByShortIds, findSessionMachinesByIds, getSessionById } from './db.js';
-import { extractSessionTopic } from './prompt.js';
+import { extractSessionTopic, classifyUserPrompt } from './prompt.js';
 import { readSessionTailWithRaw } from './tail.js';
 import { parseSession } from './parse.js';
 import { computeTokPerSec } from './throughput.js';
@@ -1831,6 +1831,9 @@ export async function getActiveSessions(opts = {}) {
     // the EXECUTION host rather than the dispatcher (RUSH-2479).
     foldExecutionMachine(merged, recordedMachineLookup(merged), machineId());
     annotateOrchestratorLabels(merged);
+    // Last: derive the shown title (recap ladder) from label/tail/topic now that
+    // every row's live tail + label are resolved (RUSH-3011).
+    foldRecap(merged);
     return merged;
 }
 /**
@@ -2065,15 +2068,96 @@ 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';
         }
     }
 }
+/** One display line, trimmed and capped, or undefined when empty. */
+function recapLine(s, max = 120) {
+    const t = s?.replace(/\s+/g, ' ').trim();
+    if (!t)
+        return undefined;
+    return t.length > max ? t.slice(0, max - 1).trimEnd() + '…' : t;
+}
+/**
+ * The recap ladder (RUSH-3011): compute a row's shown {@link ActiveSession.title}
+ * + {@link RecapSource} from the best available source, plus the cleaned first
+ * prompt (`userPromptClean`/`userPromptKind`) and the `lastAgentLine`. Pure over
+ * one row; exported for tests and folded in by {@link foldRecap}.
+ *
+ * Ladder, best-first: a `/rename`/harness `label` → the last assistant line →
+ * the first-prompt topic. The `last` rung is agent-derived, so a session that
+ * produced work stops showing its stale first prompt as the title. (`topic` is
+ * the row's already-extracted first line, so image detection here is
+ * path-based; a pure-attachment turn with no first-line text stays on `prompt`.)
+ */
+export function deriveSessionRecap(row) {
+    const lastAgentLine = recapLine(row.tail?.length ? row.tail[row.tail.length - 1] : undefined);
+    const { clean: userPromptClean, kind: userPromptKind } = classifyUserPrompt(row.topic ?? '');
+    const label = recapLine(row.label);
+    const prompt = recapLine(userPromptClean || row.topic);
+    let title;
+    let recapSource;
+    if (label) {
+        title = label;
+        recapSource = 'label';
+    }
+    else if (lastAgentLine) {
+        title = lastAgentLine;
+        recapSource = 'last';
+    }
+    else if (prompt) {
+        title = prompt;
+        recapSource = 'prompt';
+    }
+    return { title, recapSource, userPromptClean: recapLine(userPromptClean), userPromptKind, lastAgentLine };
+}
+/** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
+export function foldRecap(rows) {
+    for (const s of rows) {
+        const recap = deriveSessionRecap(s);
+        s.title = recap.title;
+        s.recapSource = recap.recapSource;
+        s.userPromptClean = recap.userPromptClean;
+        s.userPromptKind = recap.userPromptKind;
+        s.lastAgentLine = recap.lastAgentLine;
+    }
+}
+/**
+ * True when a crash-leaked orphan is genuinely DEAD and should be reaped from the
+ * reconnectable set rather than shown as resumable forever (RUSH-3011 / issue #3b).
+ *
+ * The gate is `abandoned` (no transcript write in {@link ABANDONED_STALE_MS}) AND
+ * a dead pid — exactly "past the stale threshold whose pid is gone". A live pid
+ * (an idle-but-unfinished session, the highest-risk state) is NEVER reaped, and
+ * neither is a recently-`closed`/`crashed` session that just exited (still
+ * resumable). `pidAlive` absent (a cloud row or an older peer that can't prove
+ * death) also stays un-reaped — reaping is fail-safe, never a guess.
+ */
+export function isReapableOrphan(row) {
+    return row.status === 'abandoned' && row.pidAlive === false;
+}
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the

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,
@@ -2112,8 +2189,10 @@ export function syncLabels(labelMap) {
             .prepare(`SELECT id, label FROM sessions WHERE id IN (${placeholders})`)
             .all(...chunk);
         for (const row of rows) {
-            const live = labelMap.get(row.id) ?? null;
-            if ((live ?? '') !== (row.label ?? '')) {
+            const live = labelMap.get(row.id)?.trim() || null;
+            // A missing/empty live label means "no refinement yet", not "erase the
+            // generated title or launch handle already stored for this session".
+            if (live && live !== (row.label ?? '')) {
                 updates.push({ id: row.id, label: live });
             }
         }
@@ -2263,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),
@@ -2688,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

@@ -78,6 +78,8 @@ interface ClaudeSessionScan {
     version?: string;
     model?: string;
     topic?: string;
+    /** Harness-owned session name (`/rename` or Claude's generated `ai-title`). */
+    label?: string;
     messageCount: number;
     tokenCount?: number;
     /** Real generated (output) tokens, excluding cache-read/-write context. */
@@ -120,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;
@@ -479,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;
@@ -508,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;