@phnx-labs/agents-cli 1.22.47 → 1.22.50

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

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

@@ -10,7 +10,7 @@
  * bounded `.git` walk over a handful of candidate dirs) and is the only
  * non-pure function here.
  */
-import type { SessionEvent } from './types.js';
+import type { SessionAgentId, SessionEvent } from './types.js';
 import { type FileChange } from './digest.js';
 export interface SkillUse {
     name: string;
@@ -100,3 +100,51 @@ export declare function extractArtifacts(changes: FileChange[]): ProducedArtifac
  * happens to run in, which is a wrong answer, not a degraded one.
  */
 export declare function extractRepos(events: SessionEvent[], cwd?: string): string[];
+/**
+ * True when this harness records backgrounded shells at all. Callers MUST gate
+ * on this before rendering a count: for a harness that cannot report it, "0" is
+ * a lie ("none running") where the truth is "unknown", so the segment is omitted
+ * entirely — the same way the Hooks line renders for Claude only.
+ */
+export declare function harnessTracksBackgroundShells(agent: SessionAgentId): boolean;
+/**
+ * True for a tool_use event that starts a background shell. Exported for the
+ * same reason {@link isSkillInvocation} is: the incremental parser can select
+ * matching events while streaming instead of re-reading the transcript.
+ */
+export declare function isBackgroundShellStart(e: SessionEvent): boolean;
+export interface BackgroundShell {
+    /** The command line as invoked, trimmed for display. */
+    command: string;
+    timestamp: string;
+}
+/**
+ * Shells the session started in the background, oldest first.
+ *
+ * This is "started", NOT "still running". A transcript records the start and
+ * never the death, and inferring liveness from its absence is the same trap
+ * `agents devices ps` documents — a killed process leaves no marker, so a naive
+ * reader reports "running" forever. Live status belongs to `sessions --active`,
+ * which resolves real pids.
+ */
+export declare function extractBackgroundShells(events: SessionEvent[]): BackgroundShell[];
+/**
+ * True for a tool call that spawns another agent. Deliberately counts BOTH
+ * shapes, because both are fan-out the operator needs to see:
+ *
+ *   in-process   an `Agent` / `Task` tool call inside this transcript
+ *   shelled-out  a Bash command that invokes `agents run`, `agents cloud run`,
+ *                or `agents teams add|start`
+ *
+ * Moved here from `commands/sessions-picker.ts` so BOTH preview body paths (the
+ * digest body and `formatMetaOnlyBody`) share one definition instead of
+ * drifting apart. Semantics are unchanged: session f045b577 counts 23
+ * in-process + 30 shelled-out = 53.
+ *
+ * The full summary's `Subagents (N)` section (`render.ts`) deliberately does NOT
+ * use this. It builds a described ROSTER, so it needs `args.description` /
+ * `args.prompt` and is necessarily limited to in-process `Agent`/`Task` calls —
+ * a shelled-out `agents run` carries no such description. Different question,
+ * different answer; do not "unify" them.
+ */
+export declare function isSubAgentTool(tool: string, command: string): boolean;

package/dist/lib/session/highlights.js

@@ -294,3 +294,98 @@ export function extractRepos(events, cwd) {
     }
     return repos;
 }
+// ── Background shells ─────────────────────────────────────────────────────────
+/**
+ * Per-harness shape of "start this shell command in the background", keyed the
+ * same way {@link SKILL_TOOL_NAME_BY_AGENT} is: one table entry per harness that
+ * has the capability, so adding a harness is a row and never another `else if`.
+ *
+ * An absent entry means "this harness cannot report it", which the renders must
+ * show as ABSENCE, never as a count of zero. Every absence below was probed
+ * against that harness's real transcripts on this fleet rather than assumed:
+ *
+ *   codex        0 of 176 session files carry any background marker; its `exec` /
+ *                `exec_command` record only `cmd` + `workdir`, no shell handle.
+ *   droid        0 of 126 session files.
+ *   antigravity  0 of 54 session files.
+ *   opencode     0 of 79 session files.
+ *   cursor       stores no tool calls locally at all — only `meta.json` and
+ *                `prompt_history.json`; the calls live server-side.
+ *
+ * Not probed, because no version home is installed on this fleet to probe:
+ * `muse`, `rush`, `hermes`, `openclaw`, `gemini`. They are absent for lack of
+ * evidence, NOT on a verified negative — add a row once one is confirmed, and
+ * until then absence renders as "unknown", which is the safe direction.
+ */
+const BACKGROUND_SHELL_BY_AGENT = {
+    claude: { tool: 'Bash', flag: 'run_in_background' },
+    kimi: { tool: 'Bash', flag: 'run_in_background' },
+    grok: { tool: 'run_terminal_command', flag: 'background' },
+};
+/**
+ * True when this harness records backgrounded shells at all. Callers MUST gate
+ * on this before rendering a count: for a harness that cannot report it, "0" is
+ * a lie ("none running") where the truth is "unknown", so the segment is omitted
+ * entirely — the same way the Hooks line renders for Claude only.
+ */
+export function harnessTracksBackgroundShells(agent) {
+    return BACKGROUND_SHELL_BY_AGENT[agent] !== undefined;
+}
+/**
+ * True for a tool_use event that starts a background shell. Exported for the
+ * same reason {@link isSkillInvocation} is: the incremental parser can select
+ * matching events while streaming instead of re-reading the transcript.
+ */
+export function isBackgroundShellStart(e) {
+    if (e.type !== 'tool_use' || e._local)
+        return false;
+    const spec = BACKGROUND_SHELL_BY_AGENT[e.agent];
+    return !!spec && e.tool === spec.tool && e.args?.[spec.flag] === true;
+}
+/**
+ * Shells the session started in the background, oldest first.
+ *
+ * This is "started", NOT "still running". A transcript records the start and
+ * never the death, and inferring liveness from its absence is the same trap
+ * `agents devices ps` documents — a killed process leaves no marker, so a naive
+ * reader reports "running" forever. Live status belongs to `sessions --active`,
+ * which resolves real pids.
+ */
+export function extractBackgroundShells(events) {
+    const out = [];
+    for (const e of events) {
+        if (!isBackgroundShellStart(e))
+            continue;
+        const raw = e.command ?? e.args?.command;
+        out.push({
+            command: typeof raw === 'string' ? raw.trim() : '',
+            timestamp: e.timestamp,
+        });
+    }
+    return out;
+}
+// ── Sub-agents ────────────────────────────────────────────────────────────────
+/**
+ * True for a tool call that spawns another agent. Deliberately counts BOTH
+ * shapes, because both are fan-out the operator needs to see:
+ *
+ *   in-process   an `Agent` / `Task` tool call inside this transcript
+ *   shelled-out  a Bash command that invokes `agents run`, `agents cloud run`,
+ *                or `agents teams add|start`
+ *
+ * Moved here from `commands/sessions-picker.ts` so BOTH preview body paths (the
+ * digest body and `formatMetaOnlyBody`) share one definition instead of
+ * drifting apart. Semantics are unchanged: session f045b577 counts 23
+ * in-process + 30 shelled-out = 53.
+ *
+ * The full summary's `Subagents (N)` section (`render.ts`) deliberately does NOT
+ * use this. It builds a described ROSTER, so it needs `args.description` /
+ * `args.prompt` and is necessarily limited to in-process `Agent`/`Task` calls —
+ * a shelled-out `agents run` carries no such description. Different question,
+ * different answer; do not "unify" them.
+ */
+export function isSubAgentTool(tool, command) {
+    if (/^(Agent|Task)$/i.test(tool))
+        return true;
+    return /\b(?:agents|ag)\b[^\n;&|]*\b(?:run|cloud\s+run|teams\s+(?:add|start))\b/.test(command);
+}

package/dist/lib/session/host-link.d.ts

@@ -25,12 +25,26 @@
  */
 /** How a session is connected to the client that should be driving it. */
 export type HostLink = 
-/** A client is attached, or nothing indicates otherwise. The normal case. */
+/** A client is attached — positively established, not assumed. */
 'connected'
 /** Alive, but nothing is viewing it — the host window is gone and the agent outlived it. */
  | 'no-client'
 /** The host window is gone AND the agent process died with it — an unclean exit. */
- | 'host-gone';
+ | 'host-gone'
+/**
+ * Alive, and we have NO usable signal either way — no window owns it and it is
+ * not tmux-hosted, so neither input this function keys on exists.
+ *
+ * This case used to return `connected`, which reads as "verified fine" when the
+ * truth is "nobody looked". That is the wrong default for a detector: the rows
+ * it silently blesses are precisely the ones with no observer — a bare terminal,
+ * a team spawn, a cloud task, or any session whose pane lives on another
+ * machine (this function's inputs are all local, so a `--device` session is
+ * structurally unobservable from the launching box).
+ *
+ * Callers MUST NOT render this as healthy. It means the question is open.
+ */
+ | 'unknown';
 /**
  * How long an IDE window's registry slice may go without a refresh before we
  * treat that window as gone. AGI EXT force-republishes its slice

package/dist/lib/session/host-link.js

@@ -60,5 +60,11 @@ export function classifyHostLink(input) {
     // that owned it is gone. The agent outlived its editor.
     if (windowGone)
         return 'no-client';
-    return 'connected';
+    // Positive evidence of a client: tmux counted at least one attached client, or
+    // a window is refreshing its registry slice. Either is a real observation.
+    if (input.tmuxClients !== undefined || input.windowHeartbeatMs !== undefined)
+        return 'connected';
+    // Neither input exists, so nothing here observed anything. Say so rather than
+    // reporting the healthy answer by default — see {@link HostLink}'s `unknown`.
+    return 'unknown';
 }