@volter/supercode-interchange 0.1.22 → 0.1.24

package/session-claude-index.mjs

@@ -15,8 +15,21 @@ import { sourceStat } from './store-registry.mjs';
 import { isCompressedSessionPath, looksLikeSessionSqlite, sessionTextError } from './session-path.mjs';
 import { detectSessionSource } from './session-source.mjs';
 import { AppendScan, shortHash } from './session-append-scan.mjs';
+import { ScanStore } from './session-claude-scan-store.mjs';
+import { claudeBackgroundAgentFold } from './session-claude-runtime.mjs';
 
 const REFERENCE = 'supercode.internal.read_index';
+// A window read takes in at most this much transcript it has not read before: a longer one is read through over
+// several reads, each answering how far it has read (`window.reading`), so that no read takes in a whole long file.
+const SCAN_STEP_BYTES = 32 * 1024 * 1024;
+// The messages a window read replays again as the transcript grows, at least (WindowAnswer's tail), and the prompts
+// tried as the place to settle the replay before it, at most, on each try (#settleFrom, #advance).
+const SETTLE_KEEP = 256, SETTLE_TRIES = 8, TAIL_RECORDS = 4096;
+/** Marks are listed as a chain: the digest of the first n marks is chainMark of the digest of the first n - 1 and the
+ * n-th mark ('' for none), and a reader names the digest at every MARK_CHECKPOINT-th mark it holds. A read that names
+ * the marks it holds this way is answered the marks after the first place they differ (loadClaudeRecordWindow). */
+export const MARK_CHECKPOINT = 1024;
+export const chainMark = (digest, mark) => shortHash(`${digest}:${mark}`);
 
 /** What one record is to the replay, with where it stands in the file. */
 function recordFacts(line, value) {
@@ -84,7 +97,8 @@ export async function supportsClaudeReadIndex(path, { metrics } = {}) {
 
 class ClaudeReadIndex {
   #reader;
-  #records = [];
+  #lines = 0;
+  #rawRecord;
   #groups = [];
   #skeleton = [];
   #meta = createSession('claude_code').meta;
@@ -93,50 +107,24 @@ class ClaudeReadIndex {
 
   constructor(reader) { this.#reader = reader; }
   get length() { return this.#skeleton.length; }
-  get rawRecordCount() { return this.#records.length; }
-
-  async open(fidelity) {
-    const graph = new ClaudeReplayIndex(), residueRecords = [];
-    for await (const line of sessionFileLines(this.#reader)) {
-      const index = this.#records.length;
-      let record = { offset: line.offset, length: line.length, assistant: false, error: false, messageId: null };
-      if (nativeTrim(line.text) !== '') {
-        let value;
-        try { value = parseNativeJson(line.text); } catch { this.#parseErrors++; }
-        if (value !== undefined) {
-          captureClaudeMeta(value, this.#meta, line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text);
-          graph.observe(index, value);
-          record = recordFacts(line, value);
-          if (claudeResidueKind(value) != null) residueRecords.push(index);
-        }
-      }
-      this.#records.push(record);
-    }
-    const selection = graph.selectLines(fidelity); this.#residue = selection.residue;
-    for (const index of residueRecords) {
-      const text = await this.#raw(index), raw = text.endsWith('\n') ? text.slice(0, -1) : text;
-      const value = parseNativeJson(raw);
-      captureNativeResidue(this.#meta, 'claude_code', index, raw, value, claudeResidueKind(value));
-    }
-    for (const group of claudeGroups(selection.lines, (index) => this.#records[index])) await this.#addGroup(group);
-    reorderClaudeToolResults(this.#skeleton); ensureToolResultsPaired(this.#skeleton);
-  }
+  get rawRecordCount() { return this.#lines; }
 
-  async #raw(index) {
-    const record = this.#records[index];
-    return decodeSessionUtf8(await this.#reader.read(record.offset, record.length));
+  async open(fidelity, metrics) {
+    let scan;
+    try {
+      scan = await scanOf(this.#reader.path, this.#reader);
+      const view = await scan.project(this.#reader, fidelity);
+      if (view.decodeError) throw view.decodeError;
+      this.#lines = view.lines; this.#parseErrors = view.parseErrors;
+      this.#groups = view.groups; this.#skeleton = view.skeleton; this.#residue = view.residue;
+      this.#meta = await scan.indexMeta(this.#reader, view);
+      this.#rawRecord = index => view.raw(index, this.#reader);
+      retainScan(this.#reader.path, scan, metrics);
+    } catch (error) { dropScan(this.#reader.path); throw error; }
   }
 
-  #decodeGroup(group) { return decodeClaudeGroup((index) => this.#raw(index), group); }
-
-  async #addGroup(group) {
-    const groupId = this.#groups.length, decoded = await this.#decodeGroup(group);
-    this.#groups.push(group);
-    decoded.forEach((message, ordinal) => {
-      skeletonMessage(message).metadata[REFERENCE] = `${groupId}:${ordinal}`;
-      this.#skeleton.push(message);
-    });
-  }
+  async #raw(index) { return this.#rawRecord(index); }
+  #decodeGroup(group) { return decodeClaudeGroup(index => this.#raw(index), group); }
 
   itemCount(from, end) {
     if (!Number.isSafeInteger(from) || !Number.isSafeInteger(end) || from < 0 || end < from || end > this.length) throw new RangeError('invalid Claude message range');
@@ -189,166 +177,796 @@ class ClaudeReadIndex {
  * are verified before the result leaves the scope; any change refuses it. */
 export async function withClaudeReadIndex(path, work, { fidelity = 'byte_lossless', metrics } = {}) {
   if (!['byte_lossless', 'value_lossless', 'semantic'].includes(fidelity)) throw new TypeError(`unknown session fidelity: ${fidelity}`);
-  return withSessionFile(path, async (reader) => {
-    const index = new ClaudeReadIndex(reader); await index.open(fidelity);
-    return work(index);
-  }, metrics);
+  try {
+    return await withSessionFile(path, async (reader) => {
+      const index = new ClaudeReadIndex(reader); await index.open(fidelity, metrics);
+      return work(index);
+    }, metrics);
+  } catch (error) { dropScan(path); throw error; }
 }
 
 const REPLAYED = new Set(['user', 'assistant', 'attachment', 'system']);
 
 /** One line taken into a scan's state: its place among the file's lines, its header facts, its node in the graph,
  * what it changes of the recorded profile and, for a record the replay can select, where it stands and the hash of
- * its bytes. */
+ * its bytes. A scan (`state.store`) keeps its records, nodes and residue on disk; a line read for one answer alone
+ * keeps them in that answer's state. */
 function observeClaudeLine(state, line) {
   const index = state.lines++;
   if (nativeTrim(line.text) === '') return;
   let value;
   try { value = parseNativeJson(line.text); } catch { state.parseErrors++; return; }
   captureClaudeMeta(value, state.meta, line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text);
+  const nodes = state.graph.nodes.length;
   state.graph.observe(index, value);
+  if (state.store && state.graph.nodes.length > nodes) state.store.addNode(state.graph.nodes.at(-1));
   state.profile.record(index, value);
+  state.agents.observe(value, index + 1);
   if (typeof value?.version === 'string') state.version = value.version;
-  if (REPLAYED.has(stringField(value, 'type'))) state.records.set(index, { ...recordFacts(line, value), hash: shortHash(line.bytes) });
+  if (REPLAYED.has(stringField(value, 'type'))) {
+    const facts = { ...recordFacts(line, value), hash: shortHash(line.bytes) };
+    state.records.set(index, facts); state.store?.addRecord(index, facts);
+  }
+  const kind = claudeResidueKind(value);
+  if (kind != null) {
+    const captured = { native_residue_source: null, native_residue: [] };
+    captureNativeResidue(captured, 'claude_code', index, line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text, value, kind);
+    if (captured.native_residue.length) {
+      // A scan keeps where each residue record stands, not its text: an options load reads it again (indexMeta).
+      const entry = captured.native_residue[0];
+      if (state.store) { delete entry.raw; state.store.addResidue(index, line.offset, line.length, entry); }
+      else state.nativeResidue.set(index, { entry });
+    }
+  }
 }
 
 /** A transcript's complete lines as one pass over them leaves them, kept between reads of the same file: the next
- * read takes only the lines written since (`extend`). Nothing a record says is kept, only where it is and what it is
- * to the replay. */
+ * read takes only the lines written since (`extend`). What it knows of each record is on disk (ScanStore); in memory
+ * it holds the records its next read replays (`graph` and `records`: the settled record and every one after it, or
+ * none while nothing is settled) and facts of a size the transcript's length does not set. */
 class ClaudeRecordScan extends AppendScan {
-  records = new Map(); lines = 0; parseErrors = 0; version = null;
+  // A history scan (loadClaudeHistoryWindow) replays every segment before the latest compaction; any other replays
+  // from the latest compaction on.
+  history = false;
+  store = new ScanStore(); records = new Map(); indexMetaCache = null; lines = 0; parseErrors = 0; version = null;
   graph = new ClaudeReplayIndex(); meta = createSession('claude_code').meta; profile = recordedProfileFold('claude_code');
-  skeletons = new Map(); view = null;
+  // Every record, before any compaction the replay applies: a background agent launched long before is still known.
+  agents = claudeBackgroundAgentFold();
+  // Whether the last pass stopped before the file's last whole line (SCAN_STEP_BYTES): the scan is not read through.
+  behind = false;
+  // The replay's settled prefix (settle), the tail's decoded groups and the last window answer made over it.
+  settled = null; regionMade = new Map(); answer = null;
 
-  /** Charge retained replay records and derived entries, including one entry for the scan itself. Progress and other discarded lines
-   * only advance `lines`: charging them as retained records made two long, mostly-progress transcripts evict one
-   * another on every alternating read, though their replay state together was far below the bound. */
+  /** What the scan holds in memory, counted as entries: the scans kept between reads are bounded by them. */
   get retainedRecords() {
-    // The record's graph node and linear-line index are views of that same retained record, not two more records.
-    // They are bounded by `records.size`; fork anchors and derived profile/message entries are charged separately.
-    return 1 + this.records.size + this.graph.segmentAnchors.size + this.profile.history.length + this.skeletons.size
-      + (this.view?.skeleton.length ?? 0) + (this.view?.groups.length ?? 0);
+    return 1 + this.agents.retainedEntries + this.records.size + this.graph.nodes.length + this.graph.segmentAnchors.size + this.profile.history.length
+      + (this.indexMetaCache?.meta.native_residue.length ?? 0) + this.regionMade.size + (this.settled?.checkpoints.length ?? 0) + (this.settled?.dangling.size ?? 0)
+      + (this.answer?.skeleton.length ?? 0) + (this.answer?.groups.length ?? 0);
   }
 
-  /** The lines completed since the last pass. A last line with no LF yet stays outside the scan: `view` reads it. */
-  async extend(reader) {
-    const from = this.bytes;
-    for await (const line of sessionFileLines(reader, this.bytes)) {
-      if (!line.terminated) break;
-      observeClaudeLine(this, line); this.hashed.update(line.bytes); this.bytes = line.offset + line.length;
+  /** The lines completed since the last pass, at most `budget` bytes of them (a window read takes SCAN_STEP_BYTES a
+   * pass, so a long transcript is read through over several passes and no one pass reads it all). A last line with
+   * no LF yet stays outside the scan: `view` reads it. */
+  async extend(reader, budget = Infinity) {
+    const from = this.bytes; this.behind = false;
+    this.store.begin();
+    let failed = true;
+    try {
+      for await (const line of sessionFileLines(reader, this.bytes)) {
+        if (!line.terminated) break;
+        if (this.bytes - from >= budget) { this.behind = true; break; }
+        observeClaudeLine(this, line); this.took(line.bytes, line.offset + line.length); this.bytes = line.offset + line.length;
+      }
+      failed = false;
+    } finally { this.store.end(failed); }
+    await this.settle(reader, from, this.behind);
+  }
+
+  /** The whole replay's graph and records, read from disk: what a whole replay (project) and settling read, and let go
+   * when it is done. */
+  #whole() {
+    const graph = new ClaudeReplayIndex();
+    for (const node of this.store.allNodes()) { graph.byUuid.set(node.uuid, graph.nodes.length); graph.nodes.push(node); }
+    const records = this.store.allRecords();
+    graph.linearLines = [...records.keys()];
+    graph.segmentAnchors = new Set(this.graph.segmentAnchors); graph.lastPrompt = this.graph.lastPrompt == null ? null : [...this.graph.lastPrompt];
+    return { graph, records };
+  }
+
+  /** A group's decoded skeletons: the tail's, else those on disk, else decoded from its records (and kept on disk). */
+  async #made(mark, group, raw, reader) {
+    let decoded = this.regionMade.get(mark) ?? this.store.madeOf(mark);
+    if (!decoded) {
+      decoded = (await decodeClaudeGroup((index) => raw(index, reader), group)).map((message) => ({ model: Object.hasOwn(message.metadata, 'model') ? message.metadata.model : null, message: skeletonMessage(message) }));
+      this.store.addMade(mark, decoded);
     }
-    await this.settle(reader, from);
+    return decoded;
   }
 
-  /** The replay of the file as `reader` holds it: its messages in order, each as its skeleton with the mark of the
-   * records that make it. A group's skeleton is decoded once and kept while the replay selects it. */
-  async project(reader, fidelity) {
-    const key = `${fidelity}:${this.bytes}:${reader.size}`;
-    if (this.view?.key === key) return this.view;
-    const state = { lines: this.lines, parseErrors: this.parseErrors, version: this.version, records: new Map(),
-      graph: this.graph.clone(), meta: cloneNativeJson(this.meta), profile: this.profile.clone() };
+  /** The replay of the file as `reader` holds it, whole: its messages in order, each as its skeleton with the mark of
+   * the records that make it. Read from disk and let go after use: the scan keeps no whole replay. A scan not read
+   * through (`committed`) is replayed as far as it has read. */
+  async project(reader, fidelity, committed = false) {
+    const key = committed ? `${fidelity}:${this.bytes}:committed` : `${fidelity}:${this.bytes}:${reader.size}:${reader.size > this.bytes ? reader.fingerprint.mtime_ns : "complete"}`;
+    const whole = this.#whole();
+    const state = { lines: this.lines, parseErrors: this.parseErrors, version: this.version, records: new Map(), nativeResidue: new Map(),
+      graph: whole.graph, meta: cloneNativeJson(this.meta), profile: this.profile.clone(), agents: claudeBackgroundAgentFold() };
     // The file's last line while it has no LF yet is read for this answer alone. Cut inside a character, it is a
     // line still being written: counted as one that does not parse, as a cut record is.
-    if (reader.size > this.bytes) {
+    if (!committed && reader.size > this.bytes) {
       const bytes = await reader.read(this.bytes, reader.size - this.bytes); let text = null;
-      try { text = decodeSessionUtf8(bytes); } catch { state.lines++; state.parseErrors++; }
+      try { text = decodeSessionUtf8(bytes); } catch (error) { state.lines++; state.parseErrors++; state.decodeError = error; }
       if (text != null) observeClaudeLine(state, { offset: this.bytes, length: bytes.length, text, bytes });
     }
-    const recordOf = (index) => state.records.get(index) ?? this.records.get(index);
+    const recordOf = (index) => state.records.get(index) ?? whole.records.get(index);
     const raw = async (index, at) => { const record = recordOf(index); return decodeSessionUtf8(await at.read(record.offset, record.length)); };
-    const selection = state.graph.selectLines(fidelity), groups = [], sizes = [], skeleton = [], skeletons = new Map(), marks = new Map(), models = new Map();
+    const selection = state.graph.selectLines(fidelity, { history: this.history }), groups = [], sizes = [], skeleton = [], marks = new Map(), models = new Map(), made = new Map();
     for (const group of claudeGroups(selection.lines, recordOf)) {
       const id = groups.length, records = group.map(recordOf), mark = shortHash(records.map((record) => record.hash).join(','));
-      let made = skeletons.get(mark) ?? this.skeletons.get(mark);
-      if (!made) made = (await decodeClaudeGroup((index) => raw(index, reader), group)).map((message) => ({ model: Object.hasOwn(message.metadata, 'model') ? message.metadata.model : null, message: skeletonMessage(message) }));
-      skeletons.set(mark, made); groups.push(group); sizes.push(records.reduce((sum, record) => sum + record.length, 0));
-      made.forEach(({ message, model }, ordinal) => {
+      const decoded = made.get(mark) ?? await this.#made(mark, group, raw, reader);
+      made.set(mark, decoded); groups.push(group); sizes.push(records.reduce((sum, record) => sum + record.length, 0));
+      decoded.forEach(({ message, model }, ordinal) => {
         const placed = { ...message, metadata: Object.create(null) }; placed.metadata[REFERENCE] = `${id}:${ordinal}`;
         marks.set(placed, shortHash(`${mark}:${ordinal}`)); if (model != null) models.set(placed, model);
         skeleton.push(placed);
       });
     }
-    this.skeletons = skeletons;
     reorderClaudeToolResults(skeleton); ensureToolResultsPaired(skeleton);
     // A result the pairing pass made up has no record: its mark is of what it says.
-    return this.view = { key, raw, groups, sizes, skeleton, marks: skeleton.map((message) => marks.get(message) ?? shortHash(JSON.stringify(messageJson(message)))),
+    return { key, raw, groups, sizes, skeleton, marks: skeleton.map((message) => marks.get(message) ?? shortHash(JSON.stringify(messageJson(message)))),
       model: models.get(skeleton.findLast((message) => models.has(message))) ?? null, residue: selection.residue, meta: state.meta, lines: state.lines,
-      parseErrors: state.parseErrors, version: state.version, history: state.profile.history };
+      parseErrors: state.parseErrors, version: state.version, history: state.profile.history, nativeResidue: [...state.nativeResidue],
+      decodeError: state.decodeError ?? null, agents: this.agents.finish({ also: state.agents }), graph: whole.graph, records: whole.records, made };
+  }
+
+  // Options loads historically include native metadata residue even when they
+  // return no messages. Keep its original post-header ordering, rather than
+  // folding it before a later provenance envelope restores metadata.
+  async indexMeta(reader, view) {
+    const key = view.key;
+    if (this.indexMetaCache?.key === key) return this.indexMetaCache.meta;
+    const meta = cloneNativeJson(view.meta);
+    if (meta.native_residue_source == null || meta.native_residue_source === 'claude_code') {
+      let any = false;
+      for (const [, { entry, offset, length }] of [...this.store.residues(), ...view.nativeResidue]) {
+        const placed = cloneNativeJson(entry); any = true;
+        if (offset != null) { const text = decodeSessionUtf8(await reader.read(offset, length)); placed.raw = text.endsWith('\n') ? text.slice(0, -1) : text; }
+        meta.native_residue.push(placed);
+      }
+      if (any) meta.native_residue_source = 'claude_code';
+    }
+    this.indexMetaCache = { key, meta };
+    return meta;
+  }
+
+  /**
+   * The replay a window read answers from, made without replaying the whole transcript on every read. The replay is
+   * held as a settled prefix (every message up to and including a user record, its places, marks and groups on disk,
+   * the digests of the chain of its marks in memory) and the tail after it, which alone is replayed again as the
+   * transcript grows: the tail's records are replayed as a graph of their own, rooted at that record, and the prefix is
+   * kept as it was. That is the whole replay's answer whenever nothing the tail adds reaches back past the record
+   * (settledAnswer says what is checked); anything that does (a branch from an older message, a compaction, a record
+   * whose parent is not in the tail, a tool result for an older call, a newer chunk of an older message) is replayed
+   * whole (project) and settled anew. In a history replay a compaction reaches back past nothing: the replay keeps the
+   * history before it, and its boundary (a record with no parent) opens a segment after every one before it, so a tail
+   * that holds one replays alone as any other does. The settled prefix moves on as the tail grows (advance), so each
+   * read replays a bounded tail, and the scan holds in memory only that tail.
+   */
+  /** Why this read replays the whole transcript: said in its answer (`window.replay`) and counted. */
+  #whole_(reason) { this.wholeReason = reason; return null; }
+
+  async window(reader, fidelity, committed = false) {
+    if (fidelity !== 'semantic') return wholeAnswer(await this.project(reader, fidelity, committed), this.store, 'a fidelity other than semantic');
+    const key = committed ? `${fidelity}:${this.bytes}:committed` : `${fidelity}:${this.bytes}:${reader.size}:${reader.size > this.bytes ? reader.fingerprint.mtime_ns : "complete"}`;
+    if (this.answer?.key === key) return this.answer;
+    this.wholeReason = this.unsettled ? 'no place to settle the replay' : 'nothing settled yet';
+    let answer = this.settled == null ? null : await this.#settledAnswer(reader, key, committed);
+    if (answer == null) { const reason = this.wholeReason; answer = this.#settleFrom(await this.project(reader, fidelity, committed)); answer.replay = { whole: true, reason }; }
+    else { this.#advance(answer); answer.replay = { whole: false, reason: null }; }
+    // only an answer over a settled prefix is kept: a whole one is let go with its read
+    this.answer = this.settled == null ? null : answer;
+    return answer;
+  }
+
+  /** The tail after the settled prefix replayed alone, with the transcript's unterminated last line for this answer;
+   * null when the whole transcript must be replayed instead. */
+  async #settledAnswer(reader, key, committed) {
+    const settled = this.settled, zone = this.graph, store = this.store;
+    // A fork-context reference written since changes which parents the whole replay finds absent.
+    if (zone.segmentAnchors.size !== settled.anchors) return this.#whole_("fork references written since");
+    // The tail's graph: the settled record as its root, and every record after it.
+    const tail = new ClaudeReplayIndex(), root = zone.nodes[0];
+    tail.segmentAnchors = new Set(zone.segmentAnchors);
+    tail.lastPrompt = zone.lastPrompt == null ? null : [...zone.lastPrompt];
+    tail.byUuid.set(root.uuid, 0); tail.nodes.push({ ...root, parent: null });
+    for (let index = 1; index < zone.nodes.length; index++) {
+      const node = zone.nodes[index];
+      tail.byUuid.set(node.uuid, tail.nodes.length); tail.nodes.push({ ...node });
+    }
+    tail.linearLines = zone.linearLines.slice(firstAbove(zone.linearLines, settled.lineIndex - 1));
+    const state = { lines: this.lines, parseErrors: this.parseErrors, version: this.version, records: new Map(), nativeResidue: new Map(),
+      graph: tail, meta: cloneNativeJson(this.meta), profile: this.profile.clone(), agents: claudeBackgroundAgentFold() };
+    if (!committed && reader.size > this.bytes) {
+      const bytes = await reader.read(this.bytes, reader.size - this.bytes); let text = null;
+      try { text = decodeSessionUtf8(bytes); } catch (error) { state.lines++; state.parseErrors++; state.decodeError = error; }
+      if (text != null) {
+        // A record that repeats a uuid the whole replay holds is refused by it, not by the tail's graph.
+        try { const uuid = stringField(parseNativeJson(text), 'uuid'); if (uuid != null && store.hasUuid(uuid)) return this.#whole_("a record repeats a uuid"); } catch { /* counted below */ }
+        try { observeClaudeLine(state, { offset: this.bytes, length: bytes.length, text, bytes }); } catch { return this.#whole_("a record repeats a uuid"); }
+      }
+    }
+    // What the tail adds must not reach back past the settled record.
+    for (let at = 1; at < tail.nodes.length; at++) {
+      const node = tail.nodes[at];
+      // a record a parent absent from the whole replay was waiting for would join what it anchored as a root
+      if (!this.history && (node.compact != null || node.parent == null || settled.dangling.has(node.uuid))) return this.#whole_("a compaction, a new root or an absent parent in the tail");
+      if (settled.dangling.has(node.uuid)) return this.#whole_("a record an absent parent was waiting for");
+      // in a history replay a compaction's boundary opens the segment after every one before it; any other record with
+      // no parent is a root the whole replay stitches in as a severed segment
+      if (node.parent == null) { if (node.compact == null) return this.#whole_("a new root in the tail"); continue; }
+      if (!tail.byUuid.has(node.parent) && !zone.segmentAnchors.has(node.parent)) return this.#whole_("a record whose parent is older than the settled prefix");
+      if (node.messageId != null && (store.firstLineOf(node.messageId) ?? node.lineIndex) <= settled.lineIndex) return this.#whole_("a message begun before the settled prefix");
+    }
+    if (tail.lastPrompt?.[1] && !tail.byUuid.has(tail.lastPrompt[0]) && store.hasUuid(tail.lastPrompt[0])) return this.#whole_("the last prompt names a record older than the settled prefix");
+    const selection = tail.selectLines('semantic', { history: this.history });
+    if (selection.residue.length) return this.#whole_("the tail does not replay alone");
+    const recordOf = (index) => state.records.get(index) ?? this.records.get(index);
+    const raw = async (index, at) => { const record = recordOf(index) ?? store.recordAt(index); return decodeSessionUtf8(await at.read(record.offset, record.length)); };
+    const made = new Map(), groups = [], sizes = [], skeleton = [], marks = new Map(), models = new Map(), base = settled.groups;
+    // The settled record's group opens the tail's replay, alone: it is the settled prefix's last, already placed.
+    const listed = [...claudeGroups(selection.lines, recordOf)];
+    if (listed[0]?.length !== 1 || listed[0][0] !== root.lineIndex) return this.#whole_("the tail does not replay alone");
+    listed.shift();
+    for (const group of listed) {
+      const id = base + groups.length, records = group.map(recordOf), mark = shortHash(records.map((record) => record.hash).join(','));
+      const decoded = made.get(mark) ?? await this.#made(mark, group, raw, reader);
+      made.set(mark, decoded); groups.push(group); sizes.push(records.reduce((sum, record) => sum + record.length, 0));
+      decoded.forEach(({ message, model }, ordinal) => {
+        const placed = { ...message, metadata: Object.create(null) }; placed.metadata[REFERENCE] = `${id}:${ordinal}`;
+        marks.set(placed, shortHash(`${mark}:${ordinal}`)); if (model != null) models.set(placed, model);
+        skeleton.push(placed);
+      });
+    }
+    // The tail's tool results answer only its own calls, and its calls are none the prefix made or answered: so the
+    // whole replay's pairing and ordering of results changes nothing in the prefix, and in the tail does what it does
+    // to the tail alone.
+    for (const message of skeleton) {
+      if (message.role === 'tool' && message.tool_call_id != null && message.tool_call_id !== '' && store.tool(message.tool_call_id)?.call) return this.#whole_("a tool result for an older call");
+      if (message.role === 'assistant') for (const call of message.tool_calls ?? []) if (call.id !== '' && store.tool(call.id) != null) return this.#whole_("a tool call naming an older one");
+    }
+    reorderClaudeToolResults(skeleton); ensureToolResultsPaired(skeleton);
+    this.regionMade = made;
+    return new WindowAnswer({ key, raw, settled, store, groups, sizes, skeleton, made, tailNodes: tail.nodes.slice(1), committed: zone.nodes.length - 1,
+      marks: skeleton.map((message) => marks.get(message) ?? shortHash(JSON.stringify(messageJson(message)))),
+      model: models.get(skeleton.findLast((message) => models.has(message))) ?? settled.model, residue: [...settled.residue], meta: state.meta, lines_read: state.lines,
+      parseErrors: state.parseErrors, version: state.version, history: state.profile.history, decodeError: state.decodeError ?? null, agents: this.agents.finish({ also: state.agents }) });
+  }
+
+  /** A whole replay (project's view) as a window answer, its prefix settled where it can be: the prefix is written to
+   * disk and the scan keeps in memory only the records after the settled one. */
+  #settleFrom(view) {
+    const graph = view.graph, store = this.store;
+    this.settled = null; this.regionMade = new Map();
+    const groupOf = (message) => { const reference = message.metadata[REFERENCE]; return reference === undefined ? null : Number(reference.split(':')[0]); };
+    const markOf = (group) => shortHash(group.map((index) => view.records.get(index).hash).join(','));
+    // a replay from the latest compaction on settles after it, at no record it keeps; a history replay anywhere
+    const boundary = this.history ? null : graph.nodes.findLast((node) => node.compact != null) ?? null;
+    const kept = new Set(boundary == null ? [] : [boundary.compact.anchor, ...boundary.compact.preserved, ...(boundary.compact.segment ?? [])]);
+    const lastLine = new Map(); view.groups.forEach((group, id) => lastLine.set(id, group.reduce((max, index) => Math.max(max, index), -1)));
+    // The parents the whole replay finds absent (anchored as roots, as its residue says): a record that later brings
+    // one is replayed whole again. Its residue stands for every tail replayed against this prefix.
+    const dangling = new Set();
+    for (const node of graph.nodes) if (node.parent != null && !graph.byUuid.has(node.parent) && !graph.segmentAnchors.has(node.parent)) dangling.add(node.parent);
+    let cut = null;
+    // A replay that fell back to every record in transcript order is not a graph a tail can be replayed against.
+    if (!view.decodeError && !view.residue.some((line) => line.startsWith('the Claude record graph could not be projected'))) {
+      // the last of the skeleton's groups past which SETTLE_KEEP messages stand (half of a shorter replay's) is where
+      // the search starts
+      let position = view.skeleton.length - Math.min(SETTLE_KEEP, Math.floor(view.skeleton.length / 2)), tries = 0;
+      for (; position > 0 && cut == null && tries < SETTLE_TRIES; position--) {
+        const id = groupOf(view.skeleton[position - 1]);
+        if (id == null || view.groups[id].length !== 1) continue;
+        const nodeIndex = nodeAt(graph.nodes, view.groups[id][0]), node = nodeIndex === undefined ? null : graph.nodes[nodeIndex];
+        if (!settles(node, this.lines, boundary, kept)) continue;
+        tries++;
+        if (groupOf(view.skeleton[position] ?? { metadata: {} }) === id) continue; // the record's group ends here
+        if (this.#cutHolds(view.skeleton, view.groups, position, id, node, lastLine, view.records) && this.#rooted(node, graph.nodes.slice(nodeIndex + 1), dangling, graph.segmentAnchors)) cut = { position, id, nodeIndex, node };
+      }
+    }
+    this.unsettled = cut == null;
+    if (cut == null) {
+      // nothing settles: every read replays the whole transcript from disk, and the scan keeps no record in memory
+      this.graph = zoneOf(this.graph, []); this.records = new Map();
+      return wholeAnswer(view, store);
+    }
+    const settled = { lineIndex: cut.node.lineIndex, uuid: cut.node.uuid, length: 0, groups: 0, digest: '', checkpoints: [], model: null,
+      residue: [...view.residue], dangling, anchors: graph.segmentAnchors.size };
+    store.batch(() => {
+      store.clearSettled();
+      for (let id = 0; id <= cut.id; id++) {
+        store.addGroup(id, view.groups[id], view.sizes[id]); settled.groups++;
+        for (const { model } of view.made.get(markOf(view.groups[id])) ?? []) if (model != null) settled.model = model;
+      }
+      appendSettled(settled, store, view.skeleton.slice(0, cut.position), view.marks.slice(0, cut.position));
+    });
+    this.settled = settled;
+    const groups = view.groups.slice(cut.id + 1), skeleton = view.skeleton.slice(cut.position);
+    for (const group of groups) { const mark = markOf(group), decoded = view.made.get(mark); if (decoded) this.regionMade.set(mark, decoded); }
+    // in memory, the settled record and every record after it
+    this.graph = zoneOf(graph, graph.nodes.slice(cut.nodeIndex));
+    this.records = new Map([...view.records].filter(([line]) => line >= cut.node.lineIndex));
+    return new WindowAnswer({ key: view.key, raw: view.raw, settled, store, groups, sizes: view.sizes.slice(cut.id + 1), skeleton, made: this.regionMade,
+      tailNodes: this.graph.nodes.slice(1), committed: this.graph.nodes.length - 1, marks: view.marks.slice(cut.position), model: view.model, residue: view.residue,
+      meta: view.meta, lines_read: view.lines, parseErrors: view.parseErrors, version: view.version, history: view.history, decodeError: view.decodeError, agents: view.agents });
+  }
+
+  /** The tail's prefix up to a later user record, settled when the tail has grown past twice SETTLE_KEEP messages or
+   * TAIL_RECORDS records (records that make no message, as progress records, are replayed too). */
+  #advance(answer) {
+    const settled = this.settled, store = this.store;
+    if (answer.skeleton.length <= 2 * SETTLE_KEEP && answer.tailNodes.length <= TAIL_RECORDS) return;
+    const base = settled.groups, groupOf = (message) => { const reference = message.metadata[REFERENCE]; return reference === undefined ? null : Number(reference.split(':')[0]) - base; };
+    const lastLine = new Map(); answer.groups.forEach((group, id) => lastLine.set(id, group.reduce((max, index) => Math.max(max, index), -1)));
+    let tries = 0;
+    for (let position = answer.skeleton.length - Math.min(SETTLE_KEEP, Math.floor(answer.skeleton.length / 2)); position > 0 && tries < SETTLE_TRIES; position--) {
+      const id = groupOf(answer.skeleton[position - 1]);
+      if (id == null || answer.groups[id].length !== 1) continue;
+      const at = answer.tailNodes.findIndex((node) => node.lineIndex === answer.groups[id][0]);
+      if (at === -1 || at >= answer.committed) continue;
+      const node = answer.tailNodes[at];
+      if (!settles(node, this.lines, null, new Set())) continue;
+      tries++;
+      if (groupOf(answer.skeleton[position] ?? { metadata: {} }) === id) continue;
+      if (!this.#cutHolds(answer.skeleton, answer.groups, position, id, node, lastLine, this.records, base)
+        || !this.#rooted(node, answer.tailNodes.slice(at + 1, answer.committed), settled.dangling, this.graph.segmentAnchors)) continue;
+      store.batch(() => {
+        for (let group = 0; group <= id; group++) {
+          const records = answer.groups[group], mark = shortHash(records.map((index) => this.records.get(index).hash).join(','));
+          store.addGroup(settled.groups++, records, answer.sizes[group]);
+          const decoded = answer.made.get(mark); this.regionMade.delete(mark);
+          for (const { model } of decoded ?? []) if (model != null) settled.model = model;
+        }
+        appendSettled(settled, store, answer.skeleton.slice(0, position), answer.marks.slice(0, position));
+      });
+      settled.lineIndex = node.lineIndex; settled.uuid = node.uuid;
+      // in memory, the newly settled record and every record after it
+      this.graph = zoneOf(this.graph, this.graph.nodes.slice(at + 1));
+      for (const line of this.records.keys()) if (line < node.lineIndex) this.records.delete(line);
+      // the answer already given stands: it is the same replay, its prefix now settled
+      answer.reframe(settled, id + 1, position, at + 1);
+      return;
+    }
+  }
+
+  /** Whether every record after `root` (`after`) is replayed in a tail rooted at it: as the tail replay requires
+   * (settledAnswer), none reaches back past it, none is a root (but a compaction's boundary, in a history replay),
+   * none brings an absent parent, and no assistant message among them began before it. */
+  #rooted(root, after, dangling, anchors) {
+    const inside = new Set([root.uuid]);
+    for (const node of after) {
+      if (!this.history && node.compact != null) return false;
+      if (dangling.has(node.uuid) || node.parent == null && node.compact == null) return false;
+      if (node.parent != null && !inside.has(node.parent) && !anchors.has(node.parent)) return false;
+      if (node.messageId != null && (this.store.firstLineOf(node.messageId) ?? node.lineIndex) <= root.lineIndex) return false;
+      inside.add(node.uuid);
+    }
+    return true;
+  }
+
+  /** Whether the replay `skeleton` (of `groups`) can be settled through the group `id` of the user record `node`, ending
+   * at `position`: every message before it is of a group up to that one and every one after of a later group (or made
+   * up by the pairing pass for a call of its own side), every record before it was written before that record and
+   * every one after after it, no result after it answers a call before it, no call after it repeats one before it,
+   * and no message after it began before it. */
+  #cutHolds(skeleton, groups, position, id, node, lastLine, records, base = 0) {
+    const groupOf = (message) => { const reference = message.metadata[REFERENCE]; return reference === undefined ? null : Number(reference.split(':')[0]) - base; };
+    for (let at = 0; at < skeleton.length; at++) {
+      const group = groupOf(skeleton[at]);
+      if (group != null && (at < position ? group > id : group <= id)) return false;
+    }
+    for (let group = 0; group < groups.length; group++) {
+      if (group <= id ? lastLine.get(group) > node.lineIndex : groups[group].some((index) => index <= node.lineIndex)) return false;
+    }
+    const before = { calls: new Set(), results: new Set() };
+    for (let at = 0; at < position; at++) {
+      const message = skeleton[at];
+      if (message.role === 'assistant') for (const call of message.tool_calls ?? []) if (call.id !== '') before.calls.add(call.id);
+      if (message.role === 'tool' && message.tool_call_id != null) before.results.add(message.tool_call_id);
+    }
+    for (let at = position; at < skeleton.length; at++) {
+      const message = skeleton[at];
+      if (message.role === 'tool' && message.tool_call_id != null && message.tool_call_id !== '' && before.calls.has(message.tool_call_id)) return false;
+      if (message.role === 'assistant') for (const call of message.tool_calls ?? []) if (call.id !== '' && (before.calls.has(call.id) || before.results.has(call.id))) return false;
+    }
+    for (let group = id + 1; group < groups.length; group++) {
+      for (const index of groups[group]) {
+        const record = records.get(index);
+        if (record?.messageId != null && record.assistant && (this.store.firstLineOf(record.messageId) ?? index) <= node.lineIndex) return false;
+      }
+    }
+    return true;
   }
 }
 
-// The scans of the files read most recently, at most this many retained replay entries between them: a transcript read again is
-// read from where its scan stopped, and one read long ago is scanned again. Of the files shorter than
-// SCAN_KEPT_BYTES only the one read last is kept (a pass reads its file more than once): scanning a short file again
-// costs less than keeping the scan of every one read.
-const SCANNED_RECORDS = 400_000, SCAN_KEPT_BYTES = 8 * 1024 * 1024;
+/** The scan's in-memory graph holding `nodes` (the settled record first), with the scan's lastPrompt and fork anchors. */
+function zoneOf(graph, nodes) {
+  const zone = new ClaudeReplayIndex();
+  for (const node of nodes) { zone.byUuid.set(node.uuid, zone.nodes.length); zone.nodes.push(node); }
+  zone.linearLines = graph.linearLines.slice(firstAbove(graph.linearLines, (nodes[0]?.lineIndex ?? Infinity) - 1));
+  zone.segmentAnchors = new Set(graph.segmentAnchors); zone.lastPrompt = graph.lastPrompt == null ? null : [...graph.lastPrompt];
+  return zone;
+}
+
+/** The index of the node of the record on line `line`, or undefined. */
+function nodeAt(nodes, line) {
+  let low = 0, high = nodes.length;
+  while (low < high) { const middle = (low + high) >> 1; if (nodes[middle].lineIndex < line) low = middle + 1; else high = middle; }
+  return nodes[low]?.lineIndex === line ? low : undefined;
+}
+
+/** Whether a replayed record can be where the replay is settled: a user record on the main line (a person's prompt
+ * or a tool's result, a group of its own), a whole line already read, after the latest compaction (`boundary`, null
+ * for a history replay, which prunes nothing at a compaction) and no record it keeps. */
+function settles(node, lines, boundary, kept) {
+  return node != null && node.kind === 'user' && !node.sidechain && node.compact == null && node.lineIndex < lines
+    && (boundary == null || node.lineIndex > boundary.lineIndex) && !kept.has(node.uuid);
+}
+
+/** The first index of a sorted array whose value is above `value`. */
+function firstAbove(sorted, value) {
+  let low = 0, high = sorted.length;
+  while (low < high) { const middle = (low + high) >> 1; if (sorted[middle] <= value) low = middle + 1; else high = middle; }
+  return low;
+}
+
+/** Settled messages appended on disk: their places, their marks and the tool calls they make and answer; and in
+ * memory, the chain of digests over the marks (a checkpoint each MARK_CHECKPOINT messages). */
+function appendSettled(settled, store, messages, marks) {
+  for (let at = 0; at < messages.length; at++) {
+    const message = messages[at], reference = message.metadata[REFERENCE];
+    if (reference === undefined) store.addPosition(settled.length, -1, -1, marks[at], message);
+    else { const [group, ordinal] = reference.split(':').map(Number); store.addPosition(settled.length, group, ordinal, marks[at], null); }
+    settled.length++;
+    settled.digest = chainMark(settled.digest, marks[at]);
+    if (settled.length % MARK_CHECKPOINT === 0) settled.checkpoints.push(settled.digest);
+    if (message.role === 'assistant') for (const call of message.tool_calls ?? []) if (call.id !== '') store.addTool(call.id, true, false);
+    if (message.role === 'tool' && message.tool_call_id != null) store.addTool(message.tool_call_id, false, true);
+  }
+}
+
+/** A replay as a window read answers it: the settled prefix (read from disk) and the tail, read by place. */
+class WindowAnswer {
+  constructor(parts) { Object.assign(this, parts); this.base = this.settled.length; this.baseGroups = this.settled.groups; }
+  get total() { return this.base + this.skeleton.length; }
+  at(position) {
+    if (position >= this.base) return this.skeleton[position - this.base];
+    const { group, ordinal, synthetic } = this.store.positionAt(position);
+    if (synthetic) return synthetic;
+    const metadata = Object.create(null); metadata[REFERENCE] = `${group}:${ordinal}`;
+    return { metadata };
+  }
+  /** The marks from `from` to `to`, in order. */
+  *markRange(from, to) {
+    if (from < this.base) yield* this.store.marksFrom(from, Math.min(to, this.base));
+    for (let at = Math.max(from, this.base); at < to; at++) yield this.marks[at - this.base];
+  }
+  group(id) { return id < this.baseGroups ? this.store.groupAt(id).lines : this.groups[id - this.baseGroups]; }
+  size(id) { return id < this.baseGroups ? this.store.groupAt(id).size : this.sizes[id - this.baseGroups]; }
+  /** The digest of the chain of the first `count` marks. */
+  digestAt(count) {
+    let at, digest;
+    if (count <= this.base) { const checkpoint = Math.floor(count / MARK_CHECKPOINT); at = checkpoint * MARK_CHECKPOINT; digest = checkpoint ? this.settled.checkpoints[checkpoint - 1] : ''; }
+    else { at = this.base; digest = this.settled.digest; }
+    for (const mark of this.markRange(at, count)) digest = chainMark(digest, mark);
+    return digest;
+  }
+  /** The tail's first groups and messages settled since this answer was made: the same replay, read by place. */
+  reframe(settled, groups, messages, nodes) {
+    this.groups = this.groups.slice(groups); this.sizes = this.sizes.slice(groups); this.skeleton = this.skeleton.slice(messages); this.marks = this.marks.slice(messages);
+    this.tailNodes = this.tailNodes.slice(nodes); this.committed -= nodes; this.base = settled.length; this.baseGroups = settled.groups;
+  }
+}
+
+/** A whole replay answered with nothing settled. */
+function wholeAnswer(view, store, reason = null) {
+  return new WindowAnswer({ key: view.key, raw: view.raw, store, replay: { whole: true, reason }, settled: { length: 0, groups: 0, digest: '', checkpoints: [], residue: [], dangling: new Set(), model: null },
+    groups: view.groups, sizes: view.sizes, skeleton: view.skeleton, marks: view.marks, made: new Map(), tailNodes: [], committed: 0, model: view.model,
+    residue: view.residue, meta: view.meta, lines_read: view.lines, parseErrors: view.parseErrors, version: view.version, history: view.history,
+    decodeError: view.decodeError, agents: view.agents });
+}
+
+// The scans of the files read most recently, at most KEPT_SCANS of them and at most this many retained in-memory entries
+// between them (beyond the scans still reading their transcripts through, which are kept): a transcript read again is
+// read from where its scan stopped, and one read long ago is scanned again. A scan keeps on disk what it knows of each
+// record, so what it holds in memory is its tail, not its transcript.
+const SCANNED_RECORDS = 400_000, KEPT_SCANS = 32;
 const scans = new Map();
 
-async function scanOf(path, reader) {
+/** A scan let go: its file on disk with it. */
+function dropScan(path) { const scan = scans.get(path); scans.delete(path); scan?.store.close(); }
+
+async function scanOf(path, reader, budget = Infinity) {
   let scan = scans.get(path); scans.delete(path);
-  if (!scan || !await scan.holds(reader)) scan = new ClaudeRecordScan(reader);
-  await scan.extend(reader);
+  if (scan && !await scan.holds(reader)) { scan.store.close(); scan = null; }
+  scan ??= new ClaudeRecordScan(reader);
+  try { await scan.extend(reader, budget); }
+  catch (error) { scan.store.close(); throw error; }
   return scan;
 }
 
-// Project before admitting the scan: the projection adds skeletons and groups that the same finite bound charges.
-// As before, the current scan is kept even when it alone exceeds the bound; every older scan then goes.
 function retainScan(path, scan, metrics = {}) {
   metrics.claude_scan_physical_lines = scan.lines;
   metrics.claude_scan_record_positions = scan.records.size;
   metrics.claude_scan_graph_nodes = scan.graph.nodes.length;
   metrics.claude_scan_graph_lines = scan.graph.linearLines.length;
   metrics.claude_scan_profile_changes = scan.profile.history.length;
-  metrics.claude_scan_skeletons = scan.skeletons.size;
-  if (scan.bytes < SCAN_KEPT_BYTES) for (const [other, item] of scans) if (item.bytes < SCAN_KEPT_BYTES) scans.delete(other);
+  metrics.claude_scan_skeletons = scan.regionMade.size;
   scans.set(path, scan);
   let held = 0; for (const item of scans.values()) held += item.retainedRecords;
-  for (const [other, item] of scans) {
-    if (held <= SCANNED_RECORDS || item === scan) break;
-    scans.delete(other); held -= item.retainedRecords;
+  for (const [other, item] of [...scans]) {
+    if (held <= SCANNED_RECORDS && scans.size <= KEPT_SCANS) break;
+    // the scan just read is kept, and so is any still reading its transcript through: let go, it would read it from
+    // its first byte again, and a long transcript read in turn with many others might never be read through
+    if (item === scan || item.behind) continue;
+    dropScan(other); held -= item.retainedRecords;
     metrics.claude_scan_evictions = (metrics.claude_scan_evictions ?? 0) + 1;
   }
   metrics.claude_scan_retained_entries = held;
 }
 
+/** A transcript's background-agent fold alone, kept between reads of the same file as ClaudeRecordScan is, but holding
+ * no record positions: a follower of a long session keeps its agents without the replay index a window read needs. */
+class ClaudeAgentScan extends AppendScan {
+  lines = 0; agents = claudeBackgroundAgentFold();
+  async extend(reader) {
+    const from = this.bytes;
+    for await (const line of sessionFileLines(reader, this.bytes)) {
+      if (!line.terminated) break;
+      const index = this.lines++;
+      if (nativeTrim(line.text) !== '') { try { this.agents.observe(parseNativeJson(line.text), index + 1); } catch { /* a malformed line holds no agent */ } }
+      this.took(line.bytes, line.offset + line.length); this.bytes = line.offset + line.length;
+    }
+    await this.settle(reader, from);
+  }
+}
+// Agent scans of the files read most recently. A 343 MB, 95,000-line Claude Code transcript that launched 132 background
+// agents holds about 3,000 records this fold keeps (its Agent and SendMessage calls and results, and some 2,000 task
+// notification records); counted from the file's records with grep, not from a run of the fold. These bounds keep
+// dozens of such followed sessions without one evicting another; a scan above AGENT_SCAN_ENTRIES alone is not kept
+// (its next read scans the file again) rather than evicting every other.
+const AGENT_SCANS = 64, AGENT_SCANNED_ENTRIES = 1_000_000, AGENT_SCAN_ENTRIES = 250_000;
+const agentScans = new Map();
+
+/**
+ * The background agents of a Claude Code transcript (claudeBackgroundAgentFold over every record of the file, kept
+ * between reads: a read takes only what was written since, and a last line still being written is folded for this
+ * answer alone). Null when the locator names anything this index does not read, as loadClaudeRecordWindow.
+ */
+export async function loadClaudeBackgroundAgents(locator, { metrics } = {}) {
+  const { path, kind } = locator.storage;
+  if (locator.harness !== 'claude-code' || kind !== 'file' || isCompressedSessionPath(path)) return null;
+  if ((await sourceStat(join(dirname(path), `${basename(path, extname(path))}.meta.json`)))?.isFile()) return null;
+  if (!await supportsClaudeReadIndex(path, { metrics })) return null;
+  return (await withSessionFile(path, async (reader) => {
+    let scan = agentScans.get(path); agentScans.delete(path);
+    if (!scan || !await scan.holds(reader)) scan = new ClaudeAgentScan(reader);
+    await scan.extend(reader);
+    if (scan.agents.retainedEntries <= AGENT_SCAN_ENTRIES) {
+      agentScans.set(path, scan);
+      let held = 0; for (const item of agentScans.values()) held += item.agents.retainedEntries;
+      for (const [other, item] of agentScans) {
+        if (agentScans.size <= AGENT_SCANS && held <= AGENT_SCANNED_ENTRIES || item === scan) break;
+        agentScans.delete(other); held -= item.agents.retainedEntries;
+      }
+    }
+    let tail = null;
+    if (reader.size > scan.bytes) {
+      try { const value = parseNativeJson(decodeSessionUtf8(await reader.read(scan.bytes, reader.size - scan.bytes))); tail = claudeBackgroundAgentFold(); tail.observe(value, scan.lines + 1); }
+      catch { /* a line still being written */ }
+    }
+    return scan.agents.finish({ also: tail });
+  }, metrics)).result;
+}
+
 /**
  * A window of a Claude Code transcript's messages from the place `from`, read record by record: at most `messages` of
- * them and `bytes` of transcript (one message at least), with each one's mark and, when `marks` is asked, the mark of
- * every message of the session. A mark is of the bytes of the records that make a message: while it stands, so does
- * what a reader took of that message before. Null when the locator names anything else, which is loaded as its
- * document.
+ * them and `bytes` of transcript (one message at least), with each one's mark and, when `marks` is asked, the marks
+ * after the first place where those the reader holds (`known`: their count, the digest of their chain and its
+ * checkpoints, chainMark) differ from these: `marks_from` and `tail_marks` (from the first when nothing is named). A
+ * mark is of the bytes of the records that make a message: while it stands, so does what a reader took of that message
+ * before. A transcript not yet read through answers how far it is read (`reading`) and no messages: each read takes in
+ * at most SCAN_STEP_BYTES more. Each answer says whether its read replayed the whole transcript and why
+ * (`replay: { whole, reason }`, counted in `metrics.claude_whole_replays`): a read over a settled prefix replays its
+ * tail alone. Null when the locator names anything else, which is loaded as its document.
  */
-export async function loadClaudeRecordWindow(locator, { from, bytes = null, messages = null, marks = false }, { fidelity = 'semantic', metrics } = {}) {
+export async function loadClaudeRecordWindow(locator, { from, bytes = null, messages = null, marks = false, known = null }, { fidelity = 'semantic', metrics } = {}) {
   const { path, kind } = locator.storage;
   if (kind !== 'file' || locator.harness === 'hermes' || isCompressedSessionPath(path)) return null;
   if ((await sourceStat(join(dirname(path), `${basename(path, extname(path))}.meta.json`)))?.isFile()) return null;
   if (!await supportsClaudeReadIndex(path, { metrics })) return null;
+  metrics ??= {};
   return (await withSessionFile(path, async (reader) => {
-    let view;
+    let view, scan, replay;
     try {
-      const scan = await scanOf(path, reader);
-      view = await scan.project(reader, fidelity);
+      scan = await scanOf(path, reader, SCAN_STEP_BYTES);
+      // A transcript not read through is replayed as far as it is read, so that its replay is settled as it is read
+      // and the read that reaches its end replays only its last step.
+      const answer = await scan.window(reader, fidelity, scan.behind);
+      replay = answer.replay;
+      if (replay.whole) metrics.claude_whole_replays = (metrics.claude_whole_replays ?? 0) + 1;
+      if (!scan.behind) view = answer;
       retainScan(path, scan, metrics);
     }
     catch (error) {
-      scans.delete(path);
+      dropScan(path);
       throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(path, error) : error;
     }
-    const total = view.skeleton.length, offset = Math.min(from, total), session = createSession('claude_code'), counted = new Set();
+    if (view == null) {
+      const session = createSession('claude_code'); session.meta = cloneNativeJson(scan.meta);
+      return { session: { ...normalizedSessionJson(session), raw_record_count: scan.lines,
+        window: { offset: 0, returned: 0, total_messages: null, marks: [], reading: { bytes: scan.bytes, size: reader.size }, replay } } };
+    }
+    const total = view.total, offset = Math.min(from, total), session = createSession('claude_code'), counted = new Set();
     let end = offset, used = 0, decoded = null, decodedGroup = null;
     for (; end < total && (messages == null || end - offset < messages); end++) {
-      const message = view.skeleton[end], reference = message.metadata[REFERENCE];
+      const message = view.at(end), reference = message.metadata[REFERENCE];
       if (reference === undefined) { session.messages.push(cloneNativeJson(message)); continue; }
-      const [group, ordinal] = reference.split(':').map(Number), cost = counted.has(group) ? 0 : view.sizes[group];
+      const [group, ordinal] = reference.split(':').map(Number), cost = counted.has(group) ? 0 : view.size(group);
       if (bytes != null && end > offset && used + cost > bytes) break;
       counted.add(group); used += cost;
-      if (decodedGroup !== group) { decoded = await decodeClaudeGroup((index) => view.raw(index, reader), view.groups[group]); decodedGroup = group; }
+      if (decodedGroup !== group) { decoded = await decodeClaudeGroup((index) => view.raw(index, reader), view.group(group)); decodedGroup = group; }
       session.messages.push(cloneNativeJson(decoded[ordinal]));
     }
     session.meta = cloneNativeJson(view.meta); session.imported_message_count = total;
     session.parse_error_lines = view.parseErrors; session.load_residue = [...view.residue];
-    return { session: { ...normalizedSessionJson(session), raw_record_count: view.lines,
+    const window = { offset, returned: end - offset, total_messages: total, marks: [...view.markRange(offset, end)], replay };
+    if (marks) { const listed = markedFrom(view, known); window.marks_from = listed; window.tail_marks = [...view.markRange(listed, total)]; }
+    return { session: { ...normalizedSessionJson(session), raw_record_count: view.lines_read, background_agents: view.agents,
       resolved_profile: recordedSessionProfile(session, { model: view.model, version: view.version }), resolved_profile_history: view.history.map(cloneNativeJson),
-      window: { offset, returned: end - offset, total_messages: total, marks: view.marks.slice(offset, end), ...(marks ? { all_marks: [...view.marks] } : {}) } } };
+      window } };
   }, metrics)).result;
 }
+
+// The history scans of the files paged most recently (loadClaudeHistoryWindow), kept apart from the window reads'
+// scans: paging a session's history never evicts the scan its capture reads, nor reads its transcript through again.
+const HISTORY_SCANS = 4, HISTORY_SCANNED_RECORDS = 200_000;
+const historyScans = new Map(), historyReads = new Map();
+/** A page of history is read in steps of SCAN_STEP_BYTES for at most this long before answering how far it has read. */
+const HISTORY_READ_MS = 2000;
+
+/** The lines of the records a compact boundary keeps (its preserved messages, or the chain of its preserved segment). */
+function keptLines(store, compact) {
+  const lines = new Set();
+  for (const uuid of compact.preserved) { const node = store.nodeOf(uuid); if (node) lines.add(node.line); }
+  if (compact.segment != null) {
+    const [head, tail] = compact.segment;
+    for (let uuid = tail, steps = 0; uuid != null && steps < 100_000; steps++) {
+      const node = store.nodeOf(uuid); if (!node) break;
+      lines.add(node.line); if (uuid === head) break; uuid = node.parent;
+    }
+  }
+  return lines;
+}
+
+/** The first line of the records that make the message at `position` of a window answer (one the pairing pass made up
+ * is read at the message after it), or Infinity. */
+function firstLineAt(view, position) {
+  for (let at = position; at < Math.min(view.total, position + 8); at++) {
+    const reference = view.at(at).metadata[REFERENCE];
+    if (reference !== undefined) return Math.min(...view.group(Number(reference.split(':')[0])));
+  }
+  return Infinity;
+}
+
+/**
+ * A page of a Claude Code transcript's history, its segments before every compaction kept (a history read: the graph's
+ * `history` projection, replayed by a scan of its own): the messages of that read before the place `before`, or, with
+ * `before` null, before the first message of its latest segment, which is where a read from the latest compaction on
+ * (the Teams connector's capture, whose first message is its ordinal 0) begins. At most `messages` of them and `bytes`
+ * of transcript (one message at least), the newest of them first to be kept: `window.offset` is where the page starts,
+ * the `before` of the next older page. A transcript not read through is read on, SCAN_STEP_BYTES at a time, for at most
+ * HISTORY_READ_MS; one still not read through answers how far it has read (`window.reading`) and no messages, and the
+ * next read reads on from there. Null when the locator names anything this index does not read, as
+ * loadClaudeRecordWindow.
+ */
+export async function loadClaudeHistoryWindow(locator, page = {}, options = {}) {
+  const { path, kind } = locator.storage;
+  if (locator.harness !== 'claude-code' || kind !== 'file' || isCompressedSessionPath(path)) return null;
+  if ((await sourceStat(join(dirname(path), `${basename(path, extname(path))}.meta.json`)))?.isFile()) return null;
+  if (!await supportsClaudeReadIndex(path, { metrics: options.metrics })) return null;
+  // one read of a file's history scan at a time: a page asked while another reads waits for it, and takes the scan it leaves
+  const read = (historyReads.get(path) ?? Promise.resolve()).catch(() => {}).then(() => historyWindow(path, page, options));
+  historyReads.set(path, read);
+  try { return await read; } finally { if (historyReads.get(path) === read) historyReads.delete(path); }
+}
+
+async function historyWindow(path, { before = null, messages = 50, bytes = null }, { metrics } = {}) {
+  metrics ??= {};
+  return (await withSessionFile(path, async (reader) => {
+    let scan = historyScans.get(path), view; historyScans.delete(path);
+    if (scan && !await scan.holds(reader)) { scan.store.close(); scan = null; }
+    if (!scan) { scan = new ClaudeRecordScan(reader); scan.history = true; scan.boundary = null; }
+    try {
+      const started = Date.now();
+      for (;;) {
+        // the newest compact boundary among the records this step takes in: where the latest segment begins
+        const known = scan.graph.nodes.length;
+        await scan.extend(reader, SCAN_STEP_BYTES);
+        for (let at = scan.graph.nodes.length - 1; at >= known; at--) if (scan.graph.nodes[at].compact != null) { scan.boundary = { line: scan.graph.nodes[at].lineIndex, compact: scan.graph.nodes[at].compact, kept: null }; break; }
+        view = await scan.window(reader, 'semantic', scan.behind);
+        if (!scan.behind || Date.now() - started >= HISTORY_READ_MS) break;
+      }
+      if (view.replay.whole) metrics.claude_whole_replays = (metrics.claude_whole_replays ?? 0) + 1;
+    } catch (error) {
+      scan.store.close();
+      throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(path, error) : error;
+    }
+    const replaced = historyScans.get(path);
+    if (replaced && replaced !== scan) replaced.store.close();
+    historyScans.set(path, scan);
+    // at most HISTORY_SCANS scans and HISTORY_SCANNED_RECORDS in-memory entries between them (ClaudeRecordScan's
+    // retainedRecords), the oldest let go first; the scan just read is kept
+    let held = 0; for (const item of historyScans.values()) held += item.retainedRecords;
+    for (const [other, item] of historyScans) {
+      if (historyScans.size <= HISTORY_SCANS && held <= HISTORY_SCANNED_RECORDS) break;
+      if (item !== scan) { historyScans.delete(other); held -= item.retainedRecords; item.store.close(); }
+    }
+    if (scan.behind) {
+      const session = createSession('claude_code'); session.meta = cloneNativeJson(scan.meta);
+      return { session: { ...normalizedSessionJson(session), raw_record_count: scan.lines,
+        window: { offset: 0, returned: 0, total_messages: null, segment_start: null, marks: [], reading: { bytes: scan.bytes, size: reader.size }, replay: view.replay } } };
+    }
+    const total = view.total;
+    // the first message of the latest segment: the first whose records begin at or after its boundary, and before it
+    // those whose records the boundary keeps (a read from the latest compaction on replays them after its summary)
+    const boundary = scan.boundary;
+    let low = 0, high = boundary == null ? 0 : total;
+    while (low < high) { const middle = (low + high) >> 1; if (firstLineAt(view, middle) < boundary.line) low = middle + 1; else high = middle; }
+    if (boundary != null && low > 0) {
+      boundary.kept ??= keptLines(scan.store, boundary.compact);
+      for (; low > 0; low--) {
+        const reference = view.at(low - 1).metadata[REFERENCE];
+        if (reference === undefined || !view.group(Number(reference.split(':')[0])).every((line) => boundary.kept.has(line))) break;
+      }
+    }
+    const segmentStart = low, end = Math.min(before ?? segmentStart, total);
+    // the page's first place: back from `end`, as many messages and bytes of their records as it may hold
+    let offset = end, used = 0;
+    const counted = new Set();
+    while (offset > 0 && (messages == null || end - offset < messages)) {
+      const reference = view.at(offset - 1).metadata[REFERENCE];
+      if (reference !== undefined) {
+        const group = Number(reference.split(':')[0]), cost = counted.has(group) ? 0 : view.size(group);
+        if (bytes != null && offset < end && used + cost > bytes) break;
+        counted.add(group); used += cost;
+      }
+      offset--;
+    }
+    const session = createSession('claude_code');
+    let decoded = null, decodedGroup = null;
+    for (let at = offset; at < end; at++) {
+      const message = view.at(at), reference = message.metadata[REFERENCE];
+      if (reference === undefined) { session.messages.push(cloneNativeJson(message)); continue; }
+      const [group, ordinal] = reference.split(':').map(Number);
+      if (decodedGroup !== group) { decoded = await decodeClaudeGroup((index) => view.raw(index, reader), view.group(group)); decodedGroup = group; }
+      session.messages.push(cloneNativeJson(decoded[ordinal]));
+    }
+    session.meta = cloneNativeJson(view.meta); session.imported_message_count = total;
+    session.parse_error_lines = view.parseErrors; session.load_residue = [...view.residue];
+    return { session: { ...normalizedSessionJson(session), raw_record_count: view.lines_read,
+      window: { offset, returned: end - offset, total_messages: total, segment_start: segmentStart, marks: [...view.markRange(offset, end)], replay: view.replay } } };
+  }, metrics)).result;
+}
+
+/** The first place whose mark the reader may not hold: the count it names when the chain of its marks there is this
+ * read's (`view.digestAt`), else the last checkpoint both chains share. */
+export function markedFrom(view, known) {
+  if (known == null) return 0;
+  if (known.count <= view.total && view.digestAt(known.count) === known.digest) return known.count;
+  let low = 0, high = Math.min(known.checkpoints.length, Math.floor(view.total / MARK_CHECKPOINT));
+  while (low < high) {
+    const middle = (low + high + 1) >> 1;
+    if (view.digestAt(middle * MARK_CHECKPOINT) === known.checkpoints[middle - 1]) low = middle; else high = middle - 1;
+  }
+  return low * MARK_CHECKPOINT;
+}