@phnx-labs/agents-cli 1.22.24 → 1.22.26

package/dist/lib/session/insights.js

@@ -65,6 +65,7 @@ function emptyFacets() {
         shellCommandsSeen: 0,
         messageHours: new Array(24).fill(0), userTurns: 0, assistantTurns: 0,
         toolCount: 0, errorCount: 0,
+        frictionSignals: {}, correctionSignals: {}, automationSignals: {},
     };
 }
 function bump(map, key, by = 1) {
@@ -145,6 +146,7 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
     // a reply latency. It censors 5.5% of gaps, and `gapsOverCeiling` reports how many so
     // the number is never quietly truncated.
     let lastAssistantTs = null;
+    let lastFailedTool = null;
     for (const e of events) {
         const ts = new Date(e.timestamp).getTime();
         const hasTs = !Number.isNaN(ts);
@@ -153,13 +155,21 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                 f.interruptions++;
                 break;
             case 'usage':
-                // shortenModel so the label matches `agents sessions <id>` and `trends`
+                // shortenModel so the label matches `agents sessions <id>` and `insights mix`
                 // rather than printing the raw id beside their shortened one.
                 if (e.model)
                     bump(f.models, shortenModel(e.model));
                 break;
             case 'error':
                 bump(f.errorCategories, categorizeError(e.content ?? e.output ?? ''));
+                if (e.tool && e.tool === lastFailedTool)
+                    bump(f.frictionSignals, `failed tool loop: ${e.tool}`);
+                lastFailedTool = e.tool ?? null;
+                classifyFriction(e.content ?? e.output ?? '', f.frictionSignals);
+                break;
+            case 'tool_result':
+                if (e.success !== false && e.outcome !== 'error')
+                    lastFailedTool = null;
                 break;
             case 'message':
                 if (e.role === 'assistant') {
@@ -169,6 +179,8 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                 }
                 if (e.role !== 'user')
                     break;
+                if (!e._synthetic)
+                    classifyCorrection(e.content ?? '', f.correctionSignals);
                 if (hasTs) {
                     // Local-time hour. parse.ts falls back to `new Date()` for a record with no
                     // timestamp; those are indistinguishable here, but they are rare and would
@@ -197,6 +209,8 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                     lastAssistantTs = ts;
                 const args = e.args ?? {};
                 const toolName = e.tool ?? '';
+                if (/askuserquestion/i.test(toolName))
+                    classifyAskStall(args, f.correctionSignals);
                 // Keyed on the SHARED cross-harness vocabulary, not Claude's literals. Keying
                 // on 'Edit'|'MultiEdit'|'Write' meant codex (whose vocabulary is exec /
                 // exec_command / write_stdin) reported 5,197 tool calls and exactly zero lines
@@ -218,6 +232,7 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                     f.shellCommandsSeen++;
                     f.gitCommits += countGitOp(e.command, 'commit');
                     f.gitPushes += countGitOp(e.command, 'push');
+                    classifyAutomation(e.command, f.automationSignals);
                 }
                 break;
             }
@@ -228,6 +243,59 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
     }
     return f;
 }
+const FRICTION_PATTERNS = [
+    [/blocked by|guard(?:rail)? (?:blocked|denied)|permission denied/i, 'blocked guard'],
+    [/\b(?:ci|check|workflow)\b.*\b(?:red|fail(?:ed|ure)?)\b|\b(?:red|failed)\b.*\bci\b/i, 'CI red loop'],
+    [/merge conflict|conflict in |CONFLICT \(/i, 'merge conflict'],
+];
+const CORRECTION_PATTERNS = [
+    [/\b(?:continue|keep going|don'?t stop)\b/i, 'continue / keep going'],
+    [/\b(?:yes|go ahead|do it|merge it)\b/i, 'approval repeated'],
+    [/\b(?:are we done|done end.to.end|what(?:'s| is) left)\b/i, 'done end-to-end?'],
+    [/\b(?:did you merge|merged\??)\b/i, 'did you merge?'],
+    [/\bwhat(?:'s| is) next\??\b/i, "what's next?"],
+    [/\b(?:check now|check again|try now|did it work)\b/i, 'check now'],
+    [/\b(?:don'?t ask|just do it|run what)\b/i, "don't ask / just do it"],
+];
+const AUTOMATION_PATTERNS = [
+    [/\bgh pr (?:checks|view|merge)\b/i, 'PR babysitting'],
+    [/\bagents secrets (?:list|exec|unlock|export)\b/i, 'secrets unlock dance'],
+    [/\bgit (?:fetch|rebase|merge|push)\b/i, 'git reconcile recipe'],
+    [/\b(?:scp|rsync|agents ssh)\b/i, 'fleet file transfer'],
+    [/\b(?:release\.sh|deploy\.sh|npm publish)\b/i, 'release / deploy recipe'],
+];
+function classifyFriction(text, counts) {
+    for (const [pattern, label] of FRICTION_PATTERNS)
+        if (pattern.test(text))
+            bump(counts, label);
+}
+function classifyCorrection(text, counts) {
+    const normalized = text.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    for (const [pattern, label] of CORRECTION_PATTERNS)
+        if (pattern.test(normalized))
+            bump(counts, label);
+}
+function classifyAskStall(args, counts) {
+    const text = JSON.stringify(args).toLowerCase();
+    const categories = [
+        [/release|ship|deploy|publish/, 'Ask stall: release / ship / deploy'],
+        [/what'?s next|next step|next move/, "Ask stall: what's next?"],
+        [/merge|reconcile|rebase/, 'Ask stall: merge / reconcile'],
+        [/direction|approach|implementation/, 'Ask stall: direction / approach'],
+    ];
+    for (const [pattern, label] of categories) {
+        if (pattern.test(text)) {
+            bump(counts, label);
+            return;
+        }
+    }
+    bump(counts, 'AskUserQuestion');
+}
+function classifyAutomation(command, counts) {
+    for (const [pattern, label] of AUTOMATION_PATTERNS)
+        if (pattern.test(command))
+            bump(counts, label);
+}
 /** Percentile of a numeric sample, nearest-rank. Returns 0 for an empty sample. */
 export function percentile(values, p) {
     if (values.length === 0)
@@ -298,6 +366,12 @@ export function mergeFacets(into, add) {
         bump(into.slashCommands, k, v);
     for (const [k, v] of Object.entries(add.errorCategories))
         bump(into.errorCategories, k, v);
+    for (const [k, v] of Object.entries(add.frictionSignals ?? {}))
+        bump(into.frictionSignals, k, v);
+    for (const [k, v] of Object.entries(add.correctionSignals ?? {}))
+        bump(into.correctionSignals, k, v);
+    for (const [k, v] of Object.entries(add.automationSignals ?? {}))
+        bump(into.automationSignals, k, v);
     into.interruptions += add.interruptions;
     into.responseGaps.push(...add.responseGaps);
     into.gapsOverCeiling += add.gapsOverCeiling;
@@ -328,3 +402,71 @@ export function topEntries(counts, limit) {
         .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
         .slice(0, limit);
 }
+/** Build a stable, evidence-backed action list without exposing transcript text. */
+export function buildInsightActions(sessions) {
+    const specs = [
+        { source: 'correctionSignals', label: 'continue / keep going', category: 'rule', action: 'Keep working through the delivery chain without waiting for another “continue”.' },
+        { source: 'correctionSignals', label: 'approval repeated', category: 'rule', action: 'Treat the original build or ship request as authorization for routine follow-through.' },
+        { source: 'correctionSignals', label: 'done end-to-end?', category: 'rule', action: 'Verify the user-visible outcome before declaring the task complete.' },
+        { source: 'correctionSignals', label: 'did you merge?', category: 'automation', action: 'Automate PR review, CI watching, and merge-on-green as one durable workflow.' },
+        { source: 'correctionSignals', label: "what's next?", category: 'rule', action: 'State and execute the next in-scope step instead of asking the owner to steer implementation.' },
+        { source: 'correctionSignals', label: 'check now', category: 'automation', action: 'Add bounded status polling with a terminal success or failure signal.' },
+        { source: 'correctionSignals', label: "don't ask / just do it", category: 'rule', action: 'Reserve questions for genuine product or scope choices.' },
+        { source: 'correctionSignals', label: 'Ask stall: release / ship / deploy', category: 'skill', action: 'Teach release workflows to carry publish, tag, rollout, and live verification as one chain.' },
+        { source: 'correctionSignals', label: "Ask stall: what's next?", category: 'rule', action: 'Remove workflow-stall “what next?” prompts from agent guidance.' },
+        { source: 'correctionSignals', label: 'Ask stall: merge / reconcile', category: 'skill', action: 'Encode the safe merge and reconcile path in the git workflow skill.' },
+        { source: 'correctionSignals', label: 'Ask stall: direction / approach', category: 'rule', action: 'Let agents choose implementation details after scope is clear.' },
+        { source: 'frictionSignals', label: 'blocked guard', category: 'product', action: 'Make guard failures return the safe next command and exact blocked operation.' },
+        { source: 'frictionSignals', label: 'CI red loop', category: 'automation', action: 'Deduplicate CI watchers and turn repeated red checks into one stateful wait.' },
+        { source: 'frictionSignals', label: 'merge conflict', category: 'skill', action: 'Standardize conflict diagnosis and fix-forward reconciliation.' },
+        { source: 'automationSignals', label: 'PR babysitting', category: 'automation', action: 'Bundle PR checks, review collection, comment handling, and merge-on-green.' },
+        { source: 'automationSignals', label: 'secrets unlock dance', category: 'product', action: 'Provide one headless secrets-backed command path for repeated credential operations.' },
+        { source: 'automationSignals', label: 'git reconcile recipe', category: 'skill', action: 'Promote repeated git reconciliation commands into the canonical workflow.' },
+        { source: 'automationSignals', label: 'fleet file transfer', category: 'product', action: 'Add a first-class fleet file transfer command with host/path validation.' },
+        { source: 'automationSignals', label: 'release / deploy recipe', category: 'automation', action: 'Turn repeated release shell recipes into a checked-in release script.' },
+    ];
+    const actions = [];
+    for (const spec of specs) {
+        let evidenceCount = 0;
+        const ids = [];
+        for (const session of sessions) {
+            const count = session.facets[spec.source]?.[spec.label] ?? 0;
+            if (count <= 0)
+                continue;
+            evidenceCount += count;
+            if (ids.length < 3)
+                ids.push(session.id.slice(0, 8));
+        }
+        if (evidenceCount === 0)
+            continue;
+        actions.push({
+            priority: evidenceCount >= 10 ? 'high' : evidenceCount >= 3 ? 'medium' : 'low',
+            category: spec.category,
+            action: spec.action,
+            evidenceCount,
+            sampleSessionIds: ids,
+        });
+    }
+    let failedLoopCount = 0;
+    const failedLoopIds = [];
+    for (const session of sessions) {
+        const count = Object.entries(session.facets.frictionSignals ?? {})
+            .filter(([label]) => label.startsWith('failed tool loop:'))
+            .reduce((sum, [, value]) => sum + value, 0);
+        if (count <= 0)
+            continue;
+        failedLoopCount += count;
+        if (failedLoopIds.length < 3)
+            failedLoopIds.push(session.id.slice(0, 8));
+    }
+    if (failedLoopCount > 0) {
+        actions.push({
+            priority: failedLoopCount >= 10 ? 'high' : failedLoopCount >= 3 ? 'medium' : 'low',
+            category: 'automation',
+            action: 'Detect repeated failures of the same tool and stop the retry loop with a different recovery path.',
+            evidenceCount: failedLoopCount,
+            sampleSessionIds: failedLoopIds,
+        });
+    }
+    return actions.sort((a, b) => b.evidenceCount - a.evidenceCount || a.action.localeCompare(b.action));
+}

package/dist/lib/session/remote-list.d.ts

@@ -81,6 +81,8 @@ export interface GatherRemoteListOptions {
      * know whether the match is unique or conflicting.
      */
     isDefinitive?: (session: SessionMeta, machine: string) => boolean;
+    /** Per-peer deadline for slower indexed browse queries. */
+    timeoutMs?: number;
 }
 export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[], opts?: GatherRemoteListOptions): Promise<RemoteListResult>;
 export interface RemoteToolSearchResult {

package/dist/lib/session/remote-list.js

@@ -197,6 +197,7 @@ export async function gatherRemoteList(forwardedArgs, hosts, opts) {
         args: forwardedArgs,
         noFanoutEnv: NO_FANOUT_ENV,
         hosts,
+        timeoutMs: opts?.timeoutMs,
         earlyExit: opts?.isDefinitive ? { isDefinitive: opts.isDefinitive } : undefined,
         parse: (stdout, machine) => parseRemoteListPayload(stdout, machine, safeResolver),
     });

package/dist/lib/session/session-cache.d.ts

@@ -4,11 +4,11 @@ import type { ActiveSession } from './active.js';
  * Short on purpose: live status (running/idle/waiting) must not go stale.
  * The daemon warm tick uses the same cadence (see {@link SESSION_CACHE_WARM_INTERVAL_MS}).
  */
-export declare const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15000;
+export declare const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS: number;
 /** Daemon warm interval — keep in sync with the setInterval in `lib/daemon.ts`. */
-export declare const SESSION_CACHE_WARM_INTERVAL_MS = 15000;
-/** Kick off the first warm ~25s after daemon start (staggered off other ticks). */
-export declare const SESSION_CACHE_WARM_KICKOFF_MS = 25000;
+export declare const SESSION_CACHE_WARM_INTERVAL_MS: number;
+/** Kick off the first warm 30s after daemon start (staggered off other ticks). */
+export declare const SESSION_CACHE_WARM_KICKOFF_MS = 30000;
 /** Snapshot scope: this host only, or a fleet-wide merge written by a reader. */
 export type ActiveCacheScope = 'local' | 'fleet';
 export interface ActiveSessionsSnapshot {

package/dist/lib/session/session-cache.js

@@ -34,11 +34,11 @@ const IMMUTABLE_FILE = '.active-session-immutable.json';
  * Short on purpose: live status (running/idle/waiting) must not go stale.
  * The daemon warm tick uses the same cadence (see {@link SESSION_CACHE_WARM_INTERVAL_MS}).
  */
-export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15_000;
+export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 4 * 60_000;
 /** Daemon warm interval — keep in sync with the setInterval in `lib/daemon.ts`. */
-export const SESSION_CACHE_WARM_INTERVAL_MS = 15_000;
-/** Kick off the first warm ~25s after daemon start (staggered off other ticks). */
-export const SESSION_CACHE_WARM_KICKOFF_MS = 25_000;
+export const SESSION_CACHE_WARM_INTERVAL_MS = 3 * 60_000;
+/** Kick off the first warm 30s after daemon start (staggered off other ticks). */
+export const SESSION_CACHE_WARM_KICKOFF_MS = 30_000;
 /** Keys stored in the immutable memo (transcript-stable). */
 export const IMMUTABLE_FIELD_KEYS = [
     'topic',

package/dist/lib/session/tool-index.js

@@ -1,9 +1,9 @@
 import * as fs from 'fs';
 import { StringDecoder } from 'string_decoder';
-import { getDB } from './db.js';
+import { getDB, maintainSessionSearchIndex } from './db.js';
 import { parseSession } from './parse.js';
 import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, ToolCallCollector, collectClaudeToolCalls, collectCodexToolCalls, toolCallEvidenceBytes, toolCallsFromEvents, } from './tool-calls.js';
-import { persistToolCalls, purgeToolCalls, toolEvidenceSourcePath, } from './tool-store.js';
+import { canonicalToolLedgerPath, persistToolCalls, purgeToolCalls, toolEvidenceSourcePath, } from './tool-store.js';
 const BACKFILL_MAX_FILES = 25;
 const BACKFILL_MAX_BYTES = 16 * 1024 * 1024;
 const BACKFILL_MAX_IN_MEMORY_SOURCE_BYTES = 16 * 1024 * 1024;
@@ -39,16 +39,71 @@ export function toolSearchRemoteReceiveBudget(envelope) {
     const localBytes = serializedToolSearchEnvelopeBytes(envelope);
     return Math.max(0, TOOL_QUERY_MAX_SERIALIZED_BYTES - TOOL_QUERY_MERGE_OVERHEAD_BYTES - localBytes);
 }
-function needsIndex(db, sessionId, stamp) {
-    const row = db.prepare(`
-    SELECT file_mtime_ms, file_size, extractor_version
+/**
+ * The ledger columns every candidate session is judged on. Deliberately NOT
+ * `parser_state`: this runs once per session in the scan's warm path, and that
+ * column holds a serialized collector snapshot that can reach a megabyte. It is
+ * read separately, only for the sessions that turn out to need indexing.
+ */
+function readToolLedger(db, sessionId) {
+    return db.prepare(`
+    SELECT file_path, file_mtime_ms, file_size, extractor_version, parsed_offset
     FROM tool_scan_ledger WHERE session_id = ?
   `).get(sessionId);
+}
+function readToolParserState(db, sessionId) {
+    const row = db.prepare(`SELECT parser_state FROM tool_scan_ledger WHERE session_id = ?`)
+        .get(sessionId);
+    return row?.parser_state ?? null;
+}
+function needsIndex(row, stamp) {
     return !row
         || row.file_mtime_ms !== stamp.fileMtimeMs
         || row.file_size !== stamp.fileSize
         || row.extractor_version !== TOOL_INDEX_VERSION;
 }
+/**
+ * Where to start reading a session whose transcript changed.
+ *
+ * A live session's transcript is append-only, so re-reading it from byte 0 on
+ * every scan re-parses the entire history to discover the handful of records
+ * that are new — the cost that makes a large session's tool index quadratic in
+ * the number of scans. When the ledger carries a resume point that the current
+ * file still agrees with, the scan reads only the appended bytes and merges the
+ * result (`append`); anything else re-reads the whole file (`replace`).
+ *
+ * Each check below rejects a case where the stored prefix may no longer describe
+ * the file: a harness the streaming parser cannot resume, a different extractor,
+ * no recorded resume point, a source path the ledger row does not describe, a
+ * file that shrank below what was already parsed (a rewrite or truncation, not
+ * an append), or a snapshot that does not read back.
+ */
+function planToolScan(db, sessionId, row, sourcePath, stamp, resumable) {
+    const full = { mode: 'replace', startOffset: 0 };
+    if (!resumable || !row)
+        return full;
+    if (row.extractor_version !== TOOL_INDEX_VERSION)
+        return full;
+    if (row.parsed_offset === null)
+        return full;
+    if (row.file_path !== canonicalToolLedgerPath(sourcePath))
+        return full;
+    if (stamp.fileSize < row.file_size || stamp.fileSize < row.parsed_offset)
+        return full;
+    const parserState = readToolParserState(db, sessionId);
+    if (parserState === null)
+        return full;
+    let snapshot;
+    try {
+        snapshot = JSON.parse(parserState);
+    }
+    catch {
+        return full;
+    }
+    if (snapshot?.v !== 1 || !Number.isSafeInteger(snapshot.nextOrdinal))
+        return full;
+    return { mode: 'append', startOffset: row.parsed_offset, snapshot };
+}
 /** Read index completeness from SQLite only; never stat or parse transcripts. */
 export function readToolIndexCoverage(sessions) {
     const db = getDB();
@@ -90,14 +145,23 @@ function backfillLimitCall(session, reason) {
     };
 }
 /** Stream Claude/Codex JSONL without ever retaining an oversized record. */
-async function streamJsonlToolCalls(session) {
-    const collector = new ToolCallCollector();
-    const stream = fs.createReadStream(session.filePath, { highWaterMark: 64 * 1024 });
+async function streamJsonlToolCalls(session, from = { startOffset: 0 }) {
+    const collector = new ToolCallCollector(from.snapshot);
+    const stream = fs.createReadStream(session.filePath, {
+        highWaterMark: 64 * 1024,
+        start: from.startOffset,
+    });
     const decoder = new StringDecoder('utf8');
     let pending = '';
     let pendingBytes = 0;
     let droppingOversizedLine = false;
     let skippedOversizedLine = false;
+    // Byte offset just past the last complete record applied. Only a complete,
+    // newline-terminated record advances it, so resuming here can never re-apply a
+    // record (which would mint a second ordinal for it) nor skip a partial tail.
+    let parsedOffset = from.startOffset;
+    /** Bytes of the record currently being assembled, across chunk boundaries. */
+    let lineBytes = 0;
     const applyLine = (line) => {
         if (!line.trim())
             return;
@@ -119,8 +183,14 @@ async function streamJsonlToolCalls(session) {
             const newline = text.indexOf('\n', start);
             const end = newline >= 0 ? newline : text.length;
             const segment = text.slice(start, end);
+            const segmentBytes = Buffer.byteLength(segment);
+            // Counted outside the drop guard and across chunk boundaries: this is the
+            // record's true size on disk, which is what the resume offset is measured
+            // in. `pendingBytes` cannot stand in for it — that one resets when an
+            // oversized record is dropped, and a record split over two 64 KiB reads
+            // would lose the part carried in from the previous chunk.
+            lineBytes += segmentBytes;
             if (!droppingOversizedLine) {
-                const segmentBytes = Buffer.byteLength(segment);
                 if (pendingBytes + segmentBytes <= BACKFILL_MAX_JSONL_RECORD_BYTES) {
                     pending += segment;
                     pendingBytes += segmentBytes;
@@ -136,6 +206,8 @@ async function streamJsonlToolCalls(session) {
                 break;
             if (!droppingOversizedLine)
                 applyLine(pending);
+            parsedOffset += lineBytes + 1; // + the newline itself
+            lineBytes = 0;
             pending = '';
             pendingBytes = 0;
             droppingOversizedLine = false;
@@ -145,25 +217,48 @@ async function streamJsonlToolCalls(session) {
     for await (const chunk of stream)
         consume(decoder.write(chunk));
     consume(decoder.end());
+    // Snapshot BEFORE the unterminated trailing record, and pair it with an offset
+    // that stops short of that record. The writer may be mid-append, so the record
+    // is indexed now (its evidence is real) but is re-read by the next scan — which
+    // resumes with the same next-ordinal and so re-derives the same ordinals,
+    // making the re-read an idempotent upsert rather than a duplicate.
+    const resume = skippedOversizedLine
+        // A dropped oversized record left the ordinals and the pending map out of
+        // step with the file; nothing here can be resumed from.
+        ? null
+        : { parserState: JSON.stringify(collector.snapshot()), parsedOffset };
     if (!droppingOversizedLine && pending.length > 0)
         applyLine(pending);
     const calls = collector.drainChanged();
     if (skippedOversizedLine && !calls.some((call) => call.ordinal === TOOL_INDEX_LIMIT_ORDINAL)) {
         calls.push(backfillLimitCall(session, 'At least one JSONL record exceeded the 1 MiB tool-backfill parser limit.'));
     }
-    return calls;
+    return { calls, resume };
+}
+/** True for the harnesses whose transcript the streaming parser can resume. */
+function isResumableToolSource(agent) {
+    return agent === 'claude' || agent === 'codex';
 }
-async function toolCallsForBackfill(session, sourceBytes) {
-    if (session.agent === 'claude' || session.agent === 'codex') {
+async function toolCallsForBackfill(session, sourceBytes, from = { startOffset: 0 }) {
+    if (isResumableToolSource(session.agent)) {
         if (sourceBytes > BACKFILL_MAX_STREAM_SOURCE_BYTES) {
-            return [backfillLimitCall(session, 'Transcript exceeds the 64 MiB safe streaming tool-backfill limit.')];
+            return {
+                calls: [backfillLimitCall(session, 'Transcript exceeds the 64 MiB safe streaming tool-backfill limit.')],
+                resume: null,
+            };
         }
-        return streamJsonlToolCalls(session);
+        return streamJsonlToolCalls(session, from);
     }
     if (sourceBytes > BACKFILL_MAX_IN_MEMORY_SOURCE_BYTES) {
-        return [backfillLimitCall(session, 'Transcript exceeds the 16 MiB safe in-memory tool-backfill parser limit.')];
+        return {
+            calls: [backfillLimitCall(session, 'Transcript exceeds the 16 MiB safe in-memory tool-backfill parser limit.')],
+            resume: null,
+        };
     }
-    return toolCallsFromEvents(parseSession(session.filePath, session.agent));
+    // Every other harness is parsed whole into memory by parseSession, which
+    // exposes no byte offset to resume from — so these stay full replaces and
+    // record no resume point, rather than storing one this path cannot honour.
+    return { calls: toolCallsFromEvents(parseSession(session.filePath, session.agent)), resume: null };
 }
 /**
  * Fill one bounded chunk of the independent tool index. A warm call performs
@@ -179,6 +274,7 @@ export async function ensureToolIndex(sessions, limits = {}) {
         if (!session.filePath)
             continue;
         const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
+        const ledger = readToolLedger(db, session.id);
         const mustStatSource = limits.verifySourceStamps || sourcePath !== session.filePath;
         const indexed = !mustStatSource
             ? db.prepare(`
@@ -199,8 +295,15 @@ export async function ensureToolIndex(sessions, limits = {}) {
                 continue;
             }
         }
-        if (needsIndex(db, session.id, stamp))
-            pending.push({ session, stamp });
+        if (!needsIndex(ledger, stamp))
+            continue;
+        const plan = planToolScan(db, session.id, ledger, sourcePath, stamp, isResumableToolSource(session.agent));
+        pending.push({
+            session,
+            stamp,
+            plan,
+            readBytes: Math.max(0, stamp.fileSize - plan.startOffset),
+        });
     }
     let indexedFiles = 0;
     let indexedCalls = 0;
@@ -212,13 +315,16 @@ export async function ensureToolIndex(sessions, limits = {}) {
         // The byte budget is a batch boundary, not a correctness boundary. Admit
         // one oversized transcript by itself so it can never wedge the ledger or
         // silently disappear from results; the next invocation resumes afterward.
-        if (attemptedFiles > 0 && consumedBytes + item.stamp.fileSize > maxBytes)
+        // Budgeted on the bytes this scan reads, not the file's size: a resumed
+        // session costs only its appended tail, so a batch can cover far more
+        // growing sessions than it could when every one was re-read whole.
+        if (attemptedFiles > 0 && consumedBytes + item.readBytes > maxBytes)
             break;
         attemptedFiles++;
-        consumedBytes += item.stamp.fileSize;
+        consumedBytes += item.readBytes;
         try {
-            const calls = await toolCallsForBackfill(item.session, item.stamp.fileSize);
-            persistToolCalls(db, item.session, calls, item.stamp);
+            const { calls, resume } = await toolCallsForBackfill(item.session, item.stamp.fileSize, item.plan);
+            persistToolCalls(db, item.session, calls, item.stamp, { mode: item.plan.mode, resume });
             indexedFiles++;
             indexedCalls += calls.length;
         }
@@ -226,6 +332,11 @@ export async function ensureToolIndex(sessions, limits = {}) {
             skippedFiles++;
         }
     }
+    // The scan just wrote a batch of FTS segments; pay a bounded slice of the
+    // merge they need so the index converges here instead of degrading until
+    // someone runs `agents sessions optimize` by hand (RUSH-2208).
+    if (indexedFiles > 0)
+        maintainSessionSearchIndex(db);
     const remainingFiles = Math.max(0, pending.length - attemptedFiles);
     const limitedSessionIds = new Set();
     const sessionIds = sessions.map((session) => session.id);

package/dist/lib/session/tool-store.d.ts

@@ -8,8 +8,32 @@ export declare function toolEvidenceSourcePath(filePath: string, agent: string):
 export declare function purgeToolCalls(db: Database.Database, sessionId: string): void;
 /** Purge deleted direct children when a transcript directory's stamp changes. */
 export declare function purgeMissingToolCallsInDirectory(db: Database.Database, dirPath: string, currentFilePaths: string[]): number;
-/** Persist one parser batch and its file stamp atomically. */
+/** The resume point a later incremental scan starts from. */
+export interface ToolScanResumePoint {
+    /** Serialized ToolCallCollector snapshot at `parsedOffset`. */
+    parserState: string;
+    /** Byte offset just past the last complete record consumed. */
+    parsedOffset: number;
+}
+export interface PersistToolCallsOptions {
+    /**
+     * `replace` drops the session's stored evidence first — correct for a parse
+     * that started at byte 0. `append` merges the batch into what is already
+     * stored and requires an existing ledger row; use it only for a parse that
+     * resumed from that row's `parsedOffset`.
+     */
+    mode?: 'replace' | 'append';
+    /**
+     * Where a later scan may resume. Omitted (or null) clears any stored resume
+     * point, which forces the next scan of this session to re-read from byte 0 —
+     * the correct outcome whenever the parse could not cover the whole prefix
+     * (an oversized record, a size-capped transcript, a non-streaming harness).
+     */
+    resume?: ToolScanResumePoint | null;
+    maxSessionBytes?: number;
+}
+/** Persist one parser batch, its file stamp, and its resume point atomically. */
 export declare function persistToolCalls(db: Database.Database, session: SessionMeta, calls: IndexedToolCall[], sourceStamp: {
     fileMtimeMs: number;
     fileSize: number;
-}, mode?: 'replace' | 'append', maxSessionBytes?: number): void;
+}, options?: PersistToolCallsOptions): void;