@faithfulalabi/agent-lens 0.1.0

package/dist/src/db/schema.js

@@ -0,0 +1,312 @@
+export const SCHEMA_VERSION = 2;
+export const SCHEMA_DDL = `-- ~/.agent-lens/cache.db
+--
+-- THIS FILE IS A CACHE. Every byte is a pure function of ~/.agent-lens/archive/**  --
+-- the verbatim append-only mirror of the .jsonl transcripts, sibling agent-*.meta.json,
+-- and tool-results/*.txt. Deleting it loses NOTHING — that is not a claim about care
+-- taken, it is a claim about what is in here.
+--
+-- The ARCHIVE is a different matter: deleting THAT loses data permanently, because
+-- Claude Code expires the originals (measured: nothing older than 41 days survives).
+--
+-- THERE IS NO MIGRATION RUNNER. A schema change bumps SCHEMA_VERSION; db/open.ts unlinks
+-- cache.db (+ -wal/-shm) and re-sweeps (~190 ms for session files today). src/db/migrate.ts
+-- (135 LOC) and src/db/migrations/** (178 LOC) are deleted.
+--
+-- TIER A (sessions rows, index columns) is built by SWEEPING and is persisted forever,
+--   invalidated per file on (mtime,size).
+-- TIER B (turns, events, events_fts) is PER SESSION, LAZY on first open, and DISPOSABLE.
+--   Dropping one session's Tier B is 3 statements. Worst measured rebuild: 45 ms.
+
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous  = NORMAL;
+PRAGMA foreign_keys = OFF;    -- projections are dropped wholesale, per session, by hand
+PRAGMA user_version = 2;      -- SCHEMA_VERSION; mismatch => unlink + recreate
+
+-- =====================================================================  sessions
+-- The file index AND the session-list row AND the projection freshness header,
+-- fused into one table. Sub-agent sidecars live here too (parent_session_id NOT NULL),
+-- which is what makes "expand a sub-agent" a RECURSION into the same endpoint rather
+-- than a second entity, a second projector and a second read path.
+CREATE TABLE sessions (
+  id                    TEXT PRIMARY KEY,   -- sessionId (filename stem), or agentId for a sidecar
+
+  -- SOURCE: ~/.claude/projects. Claude Code DELETES this (measured: dense 0-16 days, then
+  -- 1 file at 25, 5 at 30, 4 at 40, nothing beyond). Present-tense, not hypothetical.
+  source_path           TEXT NOT NULL,
+  source_mtime_ms       INTEGER,            -- NULL once source_state='expired'
+  source_size           INTEGER,
+  source_head_sha256    TEXT,               -- first 4 KB; detects an in-place rewrite
+  source_state          TEXT NOT NULL DEFAULT 'present',  -- present | expired | diverged
+                                            -- MEASURED 2026-09-11 (293 sessions): every row
+                                            -- 'present'. 'expired' and 'diverged' are
+                                            -- UNREACHABLE BY CONSTRUCTION at the SQL level:
+                                            -- mirror.ts:363/:463 compute them, but neither
+                                            -- write.ts UPSERT carries this column — the same
+                                            -- shape as task 0.14's est_cost gap. Keep both
+                                            -- arms; see task 0.12.
+
+  -- ARCHIVE: ~/.agent-lens/archive. THE SYSTEM OF RECORD. Byte-identical, append-only.
+  -- archive_size is ALWAYS derived from statSync at read time, never trusted from here --
+  -- there is no counter to desynchronise, so there is no offset-commit-ordering problem.
+  -- line_ref offsets in \`events\` are ARCHIVE-relative, never source-relative: source-relative
+  -- refs break the moment Claude Code expires the file.
+  archive_path          TEXT NOT NULL,
+  archive_size          INTEGER NOT NULL DEFAULT 0,   -- last observed; advisory only
+  archive_sha256        TEXT,               -- full-content hash, set at seal time
+  archive_state         TEXT NOT NULL DEFAULT 'hot',  -- hot (raw) | sealed (.zst)
+                                            -- MEASURED 2026-09-11 (293 sessions): every row
+                                            -- 'hot'. 'sealed' is UNREACHABLE BY CONSTRUCTION
+                                            -- at the SQL level: mirror.ts:380 computes it,
+                                            -- but neither write.ts UPSERT carries this
+                                            -- column. Keep the arm; see task 0.12.
+  archived_at           TEXT,
+  sealed_at             TEXT,
+
+  -- The Tier-B invalidation key. Compared against the ARCHIVE, because that is what the
+  -- projector reads. Must ALSO fold max(child mtime) + sum(child size) across sidecars:
+  -- measured, a parent went 1,814 s without a write while 11 sidecars grew by 3.76 MB, and
+  -- parent-only invalidation froze every Agent row for 30 minutes.
+  file_mtime_ms         INTEGER NOT NULL,   -- \\
+  file_size             INTEGER NOT NULL,   -- / the invalidation key (archive-derived)
+
+  project_path          TEXT NOT NULL,      -- cwd; the list groups and filters on it
+  git_branch            TEXT,
+  model                 TEXT,               -- the model named on the most lines; NOT the last
+  harness_version       TEXT,               -- \`version\`; transcript-only, groups the drift report
+  title                 TEXT,               -- LAST type:'ai-title' line
+  preview               TEXT,               -- first human prompt, 200 chars
+
+  started_at            TEXT NOT NULL,
+  last_activity_at      TEXT NOT NULL,      -- last TOP-LEVEL timestamp; NOT the last nested one
+                                            -- (trailing file-history-snapshot records carry nested
+                                            --  timestamps up to 8 days later — measured)
+
+  -- OWN rollups: this file only
+  turn_count            INTEGER NOT NULL DEFAULT 0,  -- HUMAN prompts only (101 of 1,934 user lines)
+  tool_call_count       INTEGER NOT NULL DEFAULT 0,
+  error_count           INTEGER NOT NULL DEFAULT 0,  -- is_error === true, never !is_error
+  tokens_in             INTEGER NOT NULL DEFAULT 0,
+  tokens_out            INTEGER NOT NULL DEFAULT 0,  -- per-requestId LAST-line fold
+  tokens_cache_read     INTEGER NOT NULL DEFAULT 0,
+  tokens_cache_write    INTEGER NOT NULL DEFAULT 0,
+  est_cost              REAL,                        -- NULL = unpriceable model, NEVER 0
+
+  -- SUB-AGENT rollups: SUM over child rows. 65% of all transcript bytes are sidecars, so a
+  -- session's cost is 2-6x wrong without these. Filled by the background sweep wave.
+  agent_count           INTEGER NOT NULL DEFAULT 0,
+  sub_tool_call_count   INTEGER NOT NULL DEFAULT 0,
+  sub_error_count       INTEGER NOT NULL DEFAULT 0,
+  sub_tokens_in         INTEGER NOT NULL DEFAULT 0,
+  sub_tokens_out        INTEGER NOT NULL DEFAULT 0,
+  sub_tokens_cache_read INTEGER NOT NULL DEFAULT 0,
+  sub_tokens_cache_write INTEGER NOT NULL DEFAULT 0,
+  sub_est_cost          REAL,
+  rollup_state          TEXT NOT NULL DEFAULT 'own', -- 'own' | 'complete'
+
+  -- sidecar linkage (NULL on a top-level session)
+  parent_session_id     TEXT,
+  spawned_by_event_id   TEXT,               -- the Agent tool_call event id (meta.json toolUseId)
+  agent_type            TEXT,               -- 'approach-critic' | 'Explore' | ...
+  agent_description     TEXT,
+  spawn_depth           INTEGER,
+
+  -- Tier B freshness. ALL THREE must match to count as a cache hit.
+  projected_mtime_ms    INTEGER,            -- NULL => never projected
+  projected_size        INTEGER,
+  projector_version     INTEGER,
+  projected_at          TEXT,
+  projection_state      TEXT NOT NULL DEFAULT 'none',  -- none | ready | failed | empty
+                                            -- 'empty' is the tombstone: the file
+                                            -- projected no header, so it has no turns,
+                                            -- events or FTS rows and must not be re-read
+                                            -- MEASURED 2026-09-11 (293 sessions): every row
+                                            -- 'ready'. 'none', 'failed' and 'empty' have 0
+                                            -- rows, REACHABLE BUT UNOBSERVED — 'none' is
+                                            -- this DEFAULT itself, its only writer;
+                                            -- 'failed' write.ts:344; 'empty' write.ts:280.
+                                            -- Keep all arms; see task 0.12.
+  projection_error      TEXT,
+  drift_json            TEXT NOT NULL DEFAULT '{}'
+);
+
+-- The partial predicate keeps sidecars — 65% of the corpus by bytes — out of every list scan.
+-- The \`, id DESC\` tail makes the ORDER BY total and single-pass, fixing the documented
+-- "no tiebreaker for same-millisecond sessions" wart in today's db/reads.ts.
+CREATE INDEX idx_sessions_recent  ON sessions(last_activity_at DESC, id DESC)
+  WHERE parent_session_id IS NULL;
+CREATE INDEX idx_sessions_project ON sessions(project_path, last_activity_at DESC, id DESC)
+  WHERE parent_session_id IS NULL;
+CREATE INDEX idx_sessions_parent  ON sessions(parent_session_id)
+  WHERE parent_session_id IS NOT NULL;
+
+-- ========================================================================  turns
+-- One row per promptId group. The collapsible header on screen 2.
+CREATE TABLE turns (
+  id                 TEXT PRIMARY KEY,      -- '<session_id>:<seq>'
+  session_id         TEXT NOT NULL,
+  seq                INTEGER NOT NULL,
+  kind               TEXT NOT NULL,         -- human | task_notification | slash_command
+                                            -- | compaction | system | unknown
+                                            -- MEASURED 2026-09-11 (647 turns): 'compaction'
+                                            -- and 'system' have 0 rows, REACHABLE BUT
+                                            -- UNOBSERVED in this corpus — writer
+                                            -- pipeline.ts:329-330, every arm pinned by the
+                                            -- turn-kinds.jsonl fixture
+                                            -- (pipeline.test.ts:227). Keep the arms; see
+                                            -- task 0.12.
+  parent_event_id    TEXT,                  -- BLOCKING FIX #3. When kind='task_notification',
+                                            -- the Agent tool_call event that spawned it (join on
+                                            -- <tool-use-id>), so machinery FOLDS under its Agent
+                                            -- row instead of rendering as a top-level turn.
+                                            -- Measured without it: 15 of 19 turns in one session
+                                            -- and 17 of 28 in another render as raw XML headers.
+  title              TEXT NOT NULL,         -- prompt text, 200 chars
+  started_at         TEXT NOT NULL,
+  ended_at           TEXT,
+  duration_ms        INTEGER,
+  duration_source    TEXT,                  -- 'turn_duration' (system line) | 'derived'
+  tokens_in          INTEGER NOT NULL DEFAULT 0,
+  tokens_out         INTEGER NOT NULL DEFAULT 0,
+  tokens_cache_read  INTEGER NOT NULL DEFAULT 0,
+  tokens_cache_write INTEGER NOT NULL DEFAULT 0,
+  est_cost           REAL,
+  tool_call_count    INTEGER NOT NULL DEFAULT 0,
+  error_count        INTEGER NOT NULL DEFAULT 0,
+  first_seq          INTEGER NOT NULL,      -- the event window this turn owns; also the live cursor
+  last_seq           INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX idx_turns_session_seq ON turns(session_id, seq);
+
+-- =======================================================================  events
+-- THE table. One row per thing the UI draws, in file order. A tool_use and its
+-- tool_result are ONE row, not two — that fold is what deletes both \`spans\` and
+-- \`messages\` from the old model. Content is INLINE up to 64 KB (measured p99 = 31.7 KB),
+-- so the thread renders with ZERO follow-up requests; above that we store an 8 KB head
+-- preview plus a (offset,len,block) REF back into the .jsonl, which honours
+-- "never copy the transcript" and drops the measured 13.0 ms of 15.1 ms payload write.
+CREATE TABLE events (
+  id                 TEXT PRIMARY KEY,      -- 'toolu_...' for a tool_call, else '<uuid>:<blockIndex>'
+                                            -- (0 duplicate uuids across 23,109 corpus-wide)
+  session_id         TEXT NOT NULL,
+  turn_id            TEXT NOT NULL,
+  seq                INTEGER NOT NULL,      -- thread order; deterministic from the file bytes
+  kind               TEXT NOT NULL,         -- prompt | text | thinking | tool_call
+                                            -- | error | compaction | unknown
+                                            -- MEASURED 2026-09-11 (30,286 events): 'error'
+                                            -- has 0 rows, REACHABLE BUT UNOBSERVED — writer
+                                            -- pipeline.ts:306, gated on the harness line
+                                            -- subtype 'api_error'. Keep the arm; see
+                                            -- task 0.12.
+  ts                 TEXT NOT NULL,
+  request_id         TEXT,                  -- groups the N lines of ONE assistant response
+                                            -- (1:1 with message.id; 13,629/13,630 lines = 1 block)
+  block_index        INTEGER,
+
+  name               TEXT,                  -- tool name, for kind='tool_call'
+  status             TEXT,                  -- ok | error | denied | running
+  duration_ms        INTEGER,
+  duration_source    TEXT,                  -- 'elapsed' | 'sidecar_span' | 'reported'
+                                            -- NEVER labelled "execution": a 61 ms Bash reads
+                                            -- 8,063 ms elapsed when a human sat on the approval
+                                            -- MEASURED 2026-09-11 (293 sessions, 30,286
+                                            -- events): 'reported' is UNREACHABLE BY
+                                            -- CONSTRUCTION — pipeline.ts:130 types this
+                                            -- field 'elapsed' | 'sidecar_span' | undefined.
+                                            -- Keep the arm; see task 0.12.
+
+  input              TEXT,                  -- tool_use.input as JSON text (full, or 8 KB preview)
+  input_bytes        INTEGER,               -- TRUE logical size
+  input_storage      TEXT,                  -- inline | line_ref | absent
+                                            -- MEASURED 2026-09-11 (30,286 events): 'absent'
+                                            -- has 0 rows, REACHABLE BUT UNOBSERVED — writer
+                                            -- tools.ts:118, unwitnessed by its own comment.
+                                            -- 'line_ref' is live at exactly 1 row. Keep the
+                                            -- arms; see task 0.12.
+  text               TEXT,                  -- prose / thinking / prompt / tool output
+  text_bytes         INTEGER,
+  output_storage     TEXT,                  -- inline | line_ref | spill | missing | absent
+                                            -- MEASURED 2026-09-11 (30,286 events):
+                                            -- 'line_ref' has 0 rows, REACHABLE BUT RARE —
+                                            -- tools.ts:166 fires above INLINE_MAX (64 KiB),
+                                            -- and the input sibling arm has fired once.
+                                            -- Keep the arm; see task 0.12.
+  spill_path         TEXT,                  -- resolved <session-dir>/tool-results/*.txt
+  spill_bytes        INTEGER,
+
+  -- provenance + the line_ref resolver's coordinates. File path is derivable from
+  -- sessions.file_path, because a sidecar IS a sessions row.
+  src_offset         INTEGER NOT NULL,      -- byte offset of the emitting line
+  src_len            INTEGER NOT NULL,
+  result_offset      INTEGER,               -- byte offset of the tool_result line
+  result_len         INTEGER,
+  result_block       INTEGER,
+
+  model              TEXT,                  -- \\  stamped on the FIRST event of each requestId
+  tokens_in          INTEGER,               --  } group ONLY. Naive summing is 1.51x HIGH,
+  tokens_out         INTEGER,               --  } first-line-only is 2.6x LOW; correct is the
+  tokens_cache_read  INTEGER,               --  } LAST line's output_tokens with input/cache
+  tokens_cache_write INTEGER,               --  } taken once per requestId.
+  est_cost           REAL,                  -- /
+
+  child_session_id   TEXT,                  -- Agent tool_call -> the sidecar's sessions row
+  agent_type         TEXT,
+  agent_status       TEXT,                  -- completed | failed | killed | running
+                                            -- MEASURED 2026-09-11 (30,286 events): 'killed'
+                                            -- has 0 rows, REACHABLE BUT UNOBSERVED — writer
+                                            -- tools.ts:203 copies the notification status
+                                            -- verbatim; parser proof agents.test.ts:104.
+                                            -- Keep the arm; see task 0.12.
+
+  raw_type           TEXT NOT NULL,         -- the harness's own \`type\`, VERBATIM
+  raw_subtype        TEXT,
+  attrs              TEXT NOT NULL DEFAULT '{}'  -- ALLOWLIST ONLY: attributionSkill,
+                                            -- attributionAgent, effort, permissionMode,
+                                            -- compactMetadata, toolDenialKind, unknown_fields[]
+);
+CREATE UNIQUE INDEX idx_events_session_seq ON events(session_id, seq);
+CREATE INDEX        idx_events_turn        ON events(turn_id, seq);
+CREATE INDEX        idx_events_slow        ON events(session_id, kind, duration_ms DESC);
+CREATE INDEX        idx_events_child       ON events(child_session_id)
+  WHERE child_session_id IS NOT NULL;
+
+-- ===================================================================  full text
+-- External-content FTS5 over events(text, input): in-session search on day one and
+-- cross-session search over every projected session, from ONE table. This is the
+-- concrete replacement for today's payloads_fts, which migration 001 creates and
+-- NOTHING populates. Dropping a session's projection MUST run the 'delete' idiom
+-- first; db/write.ts:deleteSessionProjection() is the only place that does it, and a
+-- test asserts INSERT INTO events_fts(events_fts, rank) VALUES('integrity-check', 1)
+-- passes after 3 drop/reproject cycles, and that the inverted order throws
+-- 'database disk image is malformed' on the FIRST cycle.
+-- CORRECTED 2026-08-19 by measurement: this used to ask for fts row count == events
+-- row count, which is vacuous here. count(*) on an external-content table delegates
+-- to the content table, so it reads equal in the inverted order too, and bare
+-- integrity-check answers ok in every broken state. Only the rank=1 form discriminates.
+CREATE VIRTUAL TABLE events_fts USING fts5(
+  text,
+  input,
+  content='events',
+  content_rowid='rowid',
+  tokenize='unicode61 remove_diacritics 2'
+);
+
+-- ========================================================================  meta
+CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+-- seeded: schema_version, projector_version, projects_root, index_built_at
+
+-- ===================================================================  spill_fts
+-- Spilled tool-output bodies, which events_fts cannot see (a spill row keeps text
+-- NULL). PLAIN FTS5, so a plain DELETE is legal here, unlike events_fts. NOT dropped
+-- by deleteSessionProjection: rows are written and reconciled by db/spill-index.ts
+-- alone. input is always NULL; it exists so an input: filter parses on the UNION ALL.
+CREATE VIRTUAL TABLE spill_fts USING fts5(
+  event_id UNINDEXED,
+  session_id UNINDEXED,
+  spill_path UNINDEXED,
+  text,
+  input UNINDEXED,
+  tokenize='unicode61 remove_diacritics 2'
+);
+-- The drain's candidate scan: O(spills) at 1 Hz, not a scan of every event.
+CREATE INDEX idx_events_spill ON events(session_id) WHERE output_storage = 'spill';`;

package/dist/src/db/sidecars.js

@@ -0,0 +1,216 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createArchiveReader } from '../archive/read.js';
+import { parseAgentMeta } from '../transcript/agents.js';
+import { DriftCounter } from '../transcript/drift.js';
+import { classifyLine, foldSessionEnvelope } from '../transcript/line.js';
+import { foldArchive } from './freshness.js';
+const SUBAGENTS_DIR = 'subagents';
+const TRANSCRIPT_EXT = '.jsonl';
+const META_EXT = '.meta.json';
+const AGENT_PREFIX = 'agent-';
+const SEALED_SUFFIX = '.zst';
+const NEWLINE = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+const START_WINDOW = 16 * 1024;
+const MAX_WINDOW = 1024 * 1024;
+export function enclosingSubagentsDir(path) {
+    const marker = `${SUBAGENTS_DIR}/`;
+    const at = path.split('\\').join('/').lastIndexOf(`/${marker}`);
+    if (at !== -1)
+        return path.slice(0, at + marker.length);
+    if (!path.endsWith(TRANSCRIPT_EXT))
+        return undefined;
+    return join(path.slice(0, -TRANSCRIPT_EXT.length), SUBAGENTS_DIR);
+}
+function metaEntries(dir) {
+    let names;
+    try {
+        names = readdirSync(dir, { recursive: true, encoding: 'utf8' });
+    }
+    catch {
+        return [];
+    }
+    const logical = new Set();
+    for (const raw of names) {
+        const name = raw.split('\\').join('/');
+        const stripped = name.endsWith(SEALED_SUFFIX) ? name.slice(0, -SEALED_SUFFIX.length) : name;
+        const leaf = stripped.slice(stripped.lastIndexOf('/') + 1);
+        if (leaf.startsWith(AGENT_PREFIX) && leaf.endsWith(META_EXT))
+            logical.add(stripped);
+    }
+    return [...logical].sort();
+}
+function firstLine(buf, whole) {
+    const at = buf.indexOf(NEWLINE);
+    if (at !== -1)
+        return { text: buf.subarray(0, at).toString('utf8'), byteOffset: 0 };
+    return whole ? { text: buf.toString('utf8'), byteOffset: 0 } : undefined;
+}
+function lastLine(buf, base, whole) {
+    let end = buf.length;
+    while (end > 0 && (buf[end - 1] === NEWLINE || buf[end - 1] === CARRIAGE_RETURN))
+        end -= 1;
+    const at = buf.subarray(0, end).lastIndexOf(NEWLINE);
+    if (at !== -1) {
+        return { text: buf.subarray(at + 1, end).toString('utf8'), byteOffset: base + at + 1 };
+    }
+    return whole ? { text: buf.subarray(0, end).toString('utf8'), byteOffset: base } : undefined;
+}
+function windows(reader, path, size, window) {
+    const span = window >= size ? size : window;
+    const base = size - span;
+    return {
+        head: reader.read(path, 0, span),
+        tail: reader.read(path, base, span),
+        base,
+        whole: span === size,
+    };
+}
+function headTail(reader, path, size) {
+    if (size === 0)
+        return undefined;
+    for (let window = START_WINDOW;; window *= 2) {
+        const at = windows(reader, path, size, window);
+        const head = firstLine(at.head, at.whole);
+        const tail = lastLine(at.tail, at.base, at.whole);
+        if (head !== undefined && tail !== undefined)
+            return [head, tail];
+        if (at.whole || window >= MAX_WINDOW)
+            return undefined;
+    }
+}
+function wholeLines(buf, base, atEof) {
+    const lines = [];
+    const push = (from, to) => {
+        let end = to;
+        while (end > from && (buf[end - 1] === NEWLINE || buf[end - 1] === CARRIAGE_RETURN))
+            end -= 1;
+        if (end > from) {
+            lines.push({ text: buf.subarray(from, end).toString('utf8'), byteOffset: base + from });
+        }
+    };
+    let start = 0;
+    if (base > 0) {
+        const at = buf.indexOf(NEWLINE);
+        if (at === -1)
+            return lines;
+        start = at + 1;
+    }
+    for (;;) {
+        const at = buf.indexOf(NEWLINE, start);
+        if (at === -1)
+            break;
+        push(start, at);
+        start = at + 1;
+    }
+    if (atEof)
+        push(start, buf.length);
+    return lines;
+}
+export function readSessionEnvelope(reader, path, projectPathSeed) {
+    try {
+        const size = reader.size(path);
+        if (size === 0)
+            return undefined;
+        for (let window = START_WINDOW;; window *= 2) {
+            const at = windows(reader, path, size, window);
+            const lines = at.whole
+                ? wholeLines(at.head, 0, true)
+                : [...wholeLines(at.head, 0, false), ...wholeLines(at.tail, at.base, true)];
+            const { project_path, started_at, last_activity_at } = foldSessionEnvelope(parseWindow(lines));
+            const atCap = at.whole || window >= MAX_WINDOW;
+            if (started_at !== undefined && last_activity_at !== undefined) {
+                if (project_path !== undefined)
+                    return { project_path, started_at, last_activity_at };
+                if (atCap && projectPathSeed !== undefined) {
+                    return { project_path: projectPathSeed, started_at, last_activity_at };
+                }
+            }
+            if (atCap)
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseWindow(lines) {
+    const drift = new DriftCounter();
+    const parsed = [];
+    for (const line of lines) {
+        try {
+            parsed.push(classifyLine(JSON.parse(line.text), {
+                byteOffset: line.byteOffset,
+                byteLength: Buffer.byteLength(line.text, 'utf8'),
+                drift,
+            }));
+        }
+        catch {
+            continue;
+        }
+    }
+    return parsed;
+}
+function readEnvelope(reader, path) {
+    try {
+        const ends = headTail(reader, path, reader.size(path));
+        if (ends === undefined)
+            return undefined;
+        const drift = new DriftCounter();
+        const envelope = foldSessionEnvelope(ends.map((end) => classifyLine(JSON.parse(end.text), {
+            byteOffset: end.byteOffset,
+            byteLength: Buffer.byteLength(end.text, 'utf8'),
+            drift,
+        })));
+        const { project_path, started_at, last_activity_at } = envelope;
+        if (project_path === undefined)
+            return undefined;
+        if (started_at === undefined || last_activity_at === undefined)
+            return undefined;
+        return { project_path, started_at, last_activity_at };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readSidecars(archivePath, sourcePath, toolUseIds, reader = createArchiveReader()) {
+    if (toolUseIds.size === 0)
+        return [];
+    const archiveDir = enclosingSubagentsDir(archivePath);
+    const sourceDir = enclosingSubagentsDir(sourcePath);
+    if (archiveDir === undefined || sourceDir === undefined)
+        return [];
+    const descriptors = [];
+    for (const rel of metaEntries(archiveDir)) {
+        const metaPath = join(archiveDir, rel);
+        let meta;
+        try {
+            meta = parseAgentMeta(JSON.parse(reader.read(metaPath, 0, reader.size(metaPath)).toString()));
+        }
+        catch {
+            continue;
+        }
+        if (meta?.toolUseId === undefined || !toolUseIds.has(meta.toolUseId))
+            continue;
+        const stem = rel.slice(0, -META_EXT.length);
+        const transcript = `${stem}${TRANSCRIPT_EXT}`;
+        const childArchivePath = join(archiveDir, transcript);
+        const fold = foldArchive(childArchivePath);
+        if (fold === undefined)
+            continue;
+        const envelope = readEnvelope(reader, childArchivePath);
+        if (envelope === undefined)
+            continue;
+        descriptors.push({
+            agent_id: stem.slice(stem.lastIndexOf('/') + 1 + AGENT_PREFIX.length),
+            archive_path: childArchivePath,
+            source_path: join(sourceDir, transcript),
+            mtime_ms: fold.mtime_ms,
+            size: fold.size,
+            meta,
+            envelope,
+        });
+    }
+    return descriptors;
+}

package/dist/src/db/spill-index.js

@@ -0,0 +1,68 @@
+import { EVENT_CONTENT_COLUMNS } from './read.js';
+export const SPILL_INDEX_MAX_BYTES = 8 * 1024 * 1024;
+const INDEXED_SQL = `SELECT f.rowid AS rowid, f.event_id AS event_id, f.spill_path AS spill_path,
+    e.output_storage AS current_storage, e.spill_path AS current_path
+  FROM spill_fts f LEFT JOIN events e ON e.id = f.event_id
+  ORDER BY f.rowid`;
+const CANDIDATES_SQL = `SELECT ${EVENT_CONTENT_COLUMNS} FROM events
+  WHERE output_storage = 'spill' AND spill_path IS NOT NULL
+  ORDER BY session_id, seq`;
+const CONTENT_ROW_SQL = `SELECT ${EVENT_CONTENT_COLUMNS} FROM events WHERE id = ?`;
+const DELETE_SQL = `DELETE FROM spill_fts WHERE rowid = ?`;
+const INSERT_SQL = `INSERT INTO spill_fts(event_id, session_id, spill_path, text, input)
+  VALUES (?, ?, ?, ?, NULL)`;
+const keyOf = (event_id, spill_path) => `${event_id}\u0000${spill_path}`;
+export function indexSpills(db, env, options = {}) {
+    const report = { indexed: 0, removed: 0, skipped: [] };
+    const indexed = new Set();
+    const remove = db.prepare(DELETE_SQL);
+    const contentRow = db.prepare(CONTENT_ROW_SQL);
+    for (const row of db.prepare(INDEXED_SQL).all()) {
+        const content = row.current_storage === 'spill' && row.current_path === row.spill_path
+            ? contentRow.get(row.event_id)
+            : undefined;
+        if (content === undefined || env.locate(content) === undefined) {
+            remove.run(row.rowid);
+            report.removed += 1;
+        }
+        else {
+            indexed.add(keyOf(row.event_id, row.spill_path));
+        }
+    }
+    const { now, startedAt, deadlineMs } = options;
+    const budgeted = now !== undefined && startedAt !== undefined && deadlineMs !== undefined;
+    const insert = db.prepare(INSERT_SQL);
+    let bodies = 0;
+    for (const row of db.prepare(CANDIDATES_SQL).all()) {
+        const path = row.spill_path;
+        if (indexed.has(keyOf(row.id, path)))
+            continue;
+        if (budgeted && bodies > 0 && now() - startedAt >= deadlineMs)
+            break;
+        if (row.spill_bytes !== null && row.spill_bytes > SPILL_INDEX_MAX_BYTES) {
+            report.skipped.push(path);
+            continue;
+        }
+        let body;
+        try {
+            body = env.resolve(row, 'text');
+        }
+        catch {
+            report.skipped.push(path);
+            continue;
+        }
+        if (body.storage !== 'spill') {
+            report.skipped.push(path);
+            continue;
+        }
+        bodies += 1;
+        if (body.byte_size > SPILL_INDEX_MAX_BYTES) {
+            report.skipped.push(path);
+            continue;
+        }
+        insert.run(row.id, row.session_id, path, body.content);
+        indexed.add(keyOf(row.id, path));
+        report.indexed += 1;
+    }
+    return report;
+}