@volter/supercode-interchange 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-interchange",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "description": "Read-only harness metadata, transcript codecs and session projections for Supercode",
   "license": "MIT OR Apache-2.0",

package/session-append-scan.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+
+export const EDGE_BYTES = 64 * 1024, VERIFY_MS = 10 * 60_000;
+export const shortHash = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 24);
+
+/** What a pass over a file that is only added to keeps of where it read: the file, the bytes it read through (from
+ * `from` to `bytes`, each given to `hashed` as it was read) and how the file stood when it stopped. The next read of
+ * the same file takes only what was written since. */
+export class AppendScan {
+  bytes = 0; from = 0; hashed = createHash('sha256'); stamp = null; edge = null; size = 0; verified = Date.now();
+
+  constructor(reader) { this.device = reader.fingerprint.device; this.inode = reader.fingerprint.inode; }
+
+  /** Whether this is the scan of `reader`'s file: the same file, no shorter, its scanned bytes as they were. A file
+   * whose size and modification time are those last read is as it was. One that grew is an append while the last
+   * EDGE_BYTES the scan read are as they were (a bounded read), and is taken as one for at most VERIFY_MS after its
+   * bytes were last read through. Any other (written without growing, an edge that moved, or a growing file not read
+   * through for that long) is read through to where the scan stopped and compared by the hash of those bytes, no
+   * line decoded: a record rewritten in place, whatever its length, ends the scan and every mark made from it, at
+   * once when the file did not also grow, and within VERIFY_MS when it did. */
+  async holds(reader) {
+    if (reader.fingerprint.device !== this.device || reader.fingerprint.inode !== this.inode || reader.size < this.bytes) return false;
+    if (this.unchanged(reader)) return true;
+    if (reader.size > this.size && Date.now() - this.verified < VERIFY_MS) return this.edge === await this.edgeOf(reader);
+    const hash = createHash('sha256');
+    for (let at = this.from; at < this.bytes;) { const block = await reader.read(at, Math.min(1024 * 1024, this.bytes - at)); hash.update(block); at += block.length; }
+    this.verified = Date.now();
+    return hash.digest('hex') === this.hashed.copy().digest('hex');
+  }
+
+  /** Whether the file's size and modification time are those this scan last read it at. */
+  unchanged(reader) { return this.stamp === `${reader.fingerprint.size}:${reader.fingerprint.mtime_ns}`; }
+
+  async edgeOf(reader) {
+    const from = Math.max(this.from, this.bytes - EDGE_BYTES);
+    return shortHash(await reader.read(from, this.bytes - from));
+  }
+
+  /** The file as a pass that read on from `from` leaves it. */
+  async settle(reader, from) {
+    if (this.bytes !== from || this.edge == null) this.edge = await this.edgeOf(reader);
+    this.size = reader.size; this.stamp = `${reader.fingerprint.size}:${reader.fingerprint.mtime_ns}`;
+  }
+}

package/session-claude-index.mjs

@@ -1,8 +1,10 @@
+import { basename, dirname, extname, join } from 'node:path';
 import { withSessionFile } from './file-io.mjs';
 import { sessionFileLines, decodeSessionUtf8 } from './session-file.mjs';
 import { parseNativeJson, cloneNativeJson } from './native-json.mjs';
-import { createSession } from './session-model.mjs';
-import { messageHasContent } from './session-views.mjs';
+import { createSession, normalizedSessionJson } from './session-model.mjs';
+import { messageJson } from './message.mjs';
+import { messageHasContent, recordedProfileFold, recordedSessionProfile } from './session-views.mjs';
 import { nativeTrim } from './text.mjs';
 import { field, stringField, ensureToolResultsPaired } from './session-codec-utils.mjs';
 import { captureNativeResidue, claudeResidueKind } from './session-native-residue.mjs';
@@ -10,11 +12,65 @@ import { captureClaudeMeta } from './session-claude.mjs';
 import { ClaudeReplayIndex } from './session-claude-graph.mjs';
 import { captureClaudeProvenance, pushClaudeUser, pushClaudeAttachment, pushClaudeSystem, mergeClaudeAssistantChunk, flushClaudeAssistant, reorderClaudeToolResults } from './session-claude-content.mjs';
 import { sourceStat } from './store-registry.mjs';
-import { looksLikeSessionSqlite } from './session-path.mjs';
+import { isCompressedSessionPath, looksLikeSessionSqlite, sessionTextError } from './session-path.mjs';
 import { detectSessionSource } from './session-source.mjs';
+import { AppendScan, shortHash } from './session-append-scan.mjs';
 
 const REFERENCE = 'supercode.internal.read_index';
 
+/** What one record is to the replay, with where it stands in the file. */
+function recordFacts(line, value) {
+  return { offset: line.offset, length: line.length, assistant: stringField(value, 'type') === 'assistant',
+    error: field(value, 'isApiErrorMessage') === true, messageId: stringField(field(value, 'message'), 'id') };
+}
+
+/** The selected records as the groups that each make messages: the chunks of one assistant message together, any
+ * other record alone. An assistant record that is an API error makes none. */
+function* claudeGroups(lines, recordOf) {
+  let pending = [], pendingId = null;
+  for (const index of lines) {
+    const record = recordOf(index);
+    if (record.assistant && !record.error) {
+      if (pending.length && !(pendingId != null && pendingId === record.messageId)) { yield pending; pending = []; }
+      pendingId = record.messageId; pending.push(index);
+    } else {
+      if (pending.length) yield pending;
+      pending = []; pendingId = null;
+      if (!record.error || !record.assistant) yield [index];
+    }
+  }
+  if (pending.length) yield pending;
+}
+
+/** The messages one group's records make, each record read from where it stands (`raw`). */
+async function decodeClaudeGroup(raw, group) {
+  const messages = []; let pending = null;
+  for (const index of group) {
+    const value = parseNativeJson(await raw(index)), kind = stringField(value, 'type');
+    if (kind === 'assistant') {
+      if (pending == null) pending = value; else mergeClaudeAssistantChunk(pending, value);
+    } else {
+      const before = messages.length;
+      if (kind === 'user') pushClaudeUser(value, messages);
+      else if (kind === 'attachment') pushClaudeAttachment(value, messages);
+      else if (kind === 'system') pushClaudeSystem(value, messages);
+      captureClaudeProvenance(value, messages, before);
+    }
+  }
+  flushClaudeAssistant(pending, messages);
+  return messages;
+}
+
+/** A decoded message with what it says left out: what the passes over the whole transcript read (a tool result
+ * beside its call, a call with no result), and nothing of its size. */
+function skeletonMessage(message) {
+  if (message.content != null) message.content = nativeTrim(message.content) === '' ? '' : 'x';
+  if (message.content_parts != null) message.content_parts = message.content_parts.length ? [null] : [];
+  for (const call of message.tool_calls ?? []) call.function.arguments = '';
+  message.metadata = Object.create(null);
+  return message;
+}
+
 export async function supportsClaudeReadIndex(path, { metrics } = {}) {
   if (!(await sourceStat(path))?.isFile() || await looksLikeSessionSqlite(path, metrics)) return false;
   return (await withSessionFile(path, async (reader) => {
@@ -43,16 +99,14 @@ class ClaudeReadIndex {
     const graph = new ClaudeReplayIndex(), residueRecords = [];
     for await (const line of sessionFileLines(this.#reader)) {
       const index = this.#records.length;
-      const record = { offset: line.offset, length: line.length, assistant: false, error: false, messageId: null };
+      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.assistant = stringField(value, 'type') === 'assistant';
-          record.error = field(value, 'isApiErrorMessage') === true;
-          record.messageId = stringField(field(value, 'message'), 'id');
+          record = recordFacts(line, value);
           if (claudeResidueKind(value) != null) residueRecords.push(index);
         }
       }
@@ -64,18 +118,7 @@ class ClaudeReadIndex {
       const value = parseNativeJson(raw);
       captureNativeResidue(this.#meta, 'claude_code', index, raw, value, claudeResidueKind(value));
     }
-    let pending = [], pendingId = null;
-    for (const index of selection.lines) {
-      const record = this.#records[index];
-      if (record.assistant && !record.error) {
-        if (pending.length && !(pendingId != null && pendingId === record.messageId)) { await this.#addGroup(pending); pending = []; }
-        pendingId = record.messageId; pending.push(index);
-      } else {
-        await this.#addGroup(pending); pending = []; pendingId = null;
-        if (!record.error || !record.assistant) await this.#addGroup([index]);
-      }
-    }
-    await this.#addGroup(pending);
+    for (const group of claudeGroups(selection.lines, (index) => this.#records[index])) await this.#addGroup(group);
     reorderClaudeToolResults(this.#skeleton); ensureToolResultsPaired(this.#skeleton);
   }
 
@@ -84,33 +127,13 @@ class ClaudeReadIndex {
     return decodeSessionUtf8(await this.#reader.read(record.offset, record.length));
   }
 
-  async #decodeGroup(group) {
-    const messages = []; let pending = null;
-    for (const index of group) {
-      const value = parseNativeJson(await this.#raw(index)), kind = stringField(value, 'type');
-      if (kind === 'assistant') {
-        if (pending == null) pending = value; else mergeClaudeAssistantChunk(pending, value);
-      } else {
-        const before = messages.length;
-        if (kind === 'user') pushClaudeUser(value, messages);
-        else if (kind === 'attachment') pushClaudeAttachment(value, messages);
-        else if (kind === 'system') pushClaudeSystem(value, messages);
-        captureClaudeProvenance(value, messages, before);
-      }
-    }
-    flushClaudeAssistant(pending, messages);
-    return messages;
-  }
+  #decodeGroup(group) { return decodeClaudeGroup((index) => this.#raw(index), group); }
 
   async #addGroup(group) {
-    if (!group.length) return;
     const groupId = this.#groups.length, decoded = await this.#decodeGroup(group);
     this.#groups.push(group);
     decoded.forEach((message, ordinal) => {
-      if (message.content != null) message.content = nativeTrim(message.content) === '' ? '' : 'x';
-      if (message.content_parts != null) message.content_parts = message.content_parts.length ? [null] : [];
-      for (const call of message.tool_calls ?? []) call.function.arguments = '';
-      message.metadata = Object.create(null); message.metadata[REFERENCE] = `${groupId}:${ordinal}`;
+      skeletonMessage(message).metadata[REFERENCE] = `${groupId}:${ordinal}`;
       this.#skeleton.push(message);
     });
   }
@@ -171,3 +194,131 @@ export async function withClaudeReadIndex(path, work, { fidelity = 'byte_lossles
     return work(index);
   }, metrics);
 }
+
+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. */
+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);
+  state.graph.observe(index, value);
+  state.profile.record(index, value);
+  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) });
+}
+
+/** 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. */
+class ClaudeRecordScan extends AppendScan {
+  records = new Map(); lines = 0; parseErrors = 0; version = null;
+  graph = new ClaudeReplayIndex(); meta = createSession('claude_code').meta; profile = recordedProfileFold('claude_code');
+  skeletons = new Map(); view = null;
+
+  /** 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;
+    }
+    await this.settle(reader, from);
+  }
+
+  /** 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 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) {
+      const bytes = await reader.read(this.bytes, reader.size - this.bytes); let text = null;
+      try { text = decodeSessionUtf8(bytes); } catch { state.lines++; state.parseErrors++; }
+      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 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();
+    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 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)))),
+      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 };
+  }
+}
+
+// The scans of the files read most recently, at most this many records 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;
+const scans = new Map();
+
+async function scanOf(path, reader) {
+  let scan = scans.get(path); scans.delete(path);
+  if (!scan || !await scan.holds(reader)) scan = new ClaudeRecordScan(reader);
+  await scan.extend(reader);
+  if (scan.bytes < SCAN_KEPT_BYTES) for (const [other, item] of scans) if (item.bytes < SCAN_KEPT_BYTES) scans.delete(other);
+  scans.set(path, scan);
+  let held = 0; for (const item of scans.values()) held += item.lines;
+  for (const [other, item] of scans) { if (held <= SCANNED_RECORDS || item === scan) break; scans.delete(other); held -= item.lines; }
+  return scan;
+}
+
+/**
+ * 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.
+ */
+export async function loadClaudeRecordWindow(locator, { from, bytes = null, messages = null, marks = false }, { 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;
+  return (await withSessionFile(path, async (reader) => {
+    let view;
+    try { view = await (await scanOf(path, reader)).project(reader, fidelity); }
+    catch (error) {
+      scans.delete(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();
+    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];
+      if (reference === undefined) { session.messages.push(cloneNativeJson(message)); continue; }
+      const [group, ordinal] = reference.split(':').map(Number), cost = counted.has(group) ? 0 : view.sizes[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; }
+      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,
+      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] } : {}) } } };
+  }, metrics)).result;
+}

package/session-codex-display.mjs

@@ -9,68 +9,89 @@ import { codexUserContext } from './session-codex-context.mjs';
 import { pushCodexDisplayItem } from './session-codex-display-items.mjs';
 import { nativeTrim } from './text.mjs';
 
+/** The display fold of a Codex rollout, one record at a time over the messages made so far (`session.messages`).
+ * Of a message made by an earlier record it reads only its display item, whether it is an event message of a text
+ * (`eventKey`), and, of the last one, all of it (a call joins its open turn): a reader that keeps the earlier ones
+ * without what they say (session-codex-window.mjs) folds the same way. `textKey` names a text the fold remembers
+ * (itself, or a digest for a reader that keeps none). `observe` answers where a display item's messages were placed
+ * when they were not appended. */
+export function codexDisplayFold(session, textKey = (text) => text, held = null) {
+  const { meta, messages } = session, canonicalTexts = new Set(held?.canonicalTexts);
+  // The item ids and event texts the kept messages may hold: a record that names neither replaces nothing and looks
+  // through no message, so a read with no bound on its messages (a display anchor's) is linear in what it reads.
+  const displayItems = new Set(held?.displayItems), eventTexts = new Set(held?.eventTexts), events = held?.events ?? new WeakMap();
+  const eventKey = (message) => events.has(message) ? events.get(message) : typeof message.content === 'string' ? textKey(message.content) : undefined;
+  const fold = {
+    paginated: held?.paginated ?? false, recordCount: held?.recordCount ?? 0, total: held?.total ?? 0, events, eventKey,
+    clone: (other) => codexDisplayFold(other, textKey, { canonicalTexts, displayItems, eventTexts, events, paginated: fold.paginated, recordCount: fold.recordCount, total: fold.total }),
+    observe(line) {
+      fold.recordCount++;
+      let value; try { value = parseNativeJson(line); } catch { session.parse_error_lines++; return null; }
+      const kind = stringField(value, 'type'), payload = field(value, 'payload'), type = stringField(payload, 'type'), timestamp = stringField(value, 'timestamp');
+      if (kind === 'session_meta') { fold.paginated = stringField(payload, 'history_mode') === 'paginated'; captureCodexMeta(payload, meta); }
+      else if (kind === 'event_msg' && fold.paginated && type === 'item_completed') {
+        const item = field(payload, 'item'), id = stringField(item, 'id');
+        if (id != null) {
+          const held = displayItems.has(id), position = held ? messages.findIndex((message) => message.metadata.codex_display_item === id) : -1, projected = [];
+          pushCodexDisplayItem(item, projected);
+          for (const message of projected) message.metadata.codex_display_item = id;
+          if (projected.length) displayItems.add(id);
+          stampCodexMessages(projected, 0, timestamp);
+          let removed = 0;
+          if (held) for (let index = messages.length - 1; index >= 0; index--) if (messages[index].metadata.codex_display_item === id) { messages.splice(index, 1); removed++; }
+          fold.total = Math.max(0, fold.total - removed) + projected.length;
+          const at = Math.min(position === -1 ? messages.length : position, messages.length);
+          for (let index = 0; index < projected.length; index++) messages.splice(at + index, 0, projected[index]);
+          return { at, count: projected.length };
+        }
+      } else if (['response_item', 'event_msg'].includes(kind) && fold.paginated) { /* Model stream is separate from display history. */ }
+      else if (kind === 'turn_context' && meta.model == null) meta.model = stringField(payload, 'model');
+      else if (kind === 'event_msg' && type === 'user_message') {
+        const urls = [];
+        for (const key of ['images', 'local_images']) {
+          const images = field(payload, key); if (Array.isArray(images)) for (const image of images) if (typeof image === 'string') urls.push(image);
+        }
+        const text = stringField(payload, 'message') ?? '';
+        messages.push(urls.length ? codexUserWithImages(text, urls) : createMessage('user', text)); fold.total++;
+      } else if (kind === 'response_item' && type !== 'reasoning') {
+        const isAssistant = type === 'message' && stringField(payload, 'role') === 'assistant';
+        const assistantText = isAssistant ? extractTextContent(payload, 'content') : null;
+        if (assistantText != null && nativeTrim(assistantText) !== '') {
+          const key = textKey(assistantText);
+          const duplicate = eventTexts.has(key) ? messages.findLastIndex((message) => Object.hasOwn(message.metadata, 'codex_event_message') && eventKey(message) === key) : -1;
+          if (duplicate !== -1) { messages.splice(duplicate, 1); fold.total = Math.max(0, fold.total - 1); }
+          canonicalTexts.add(textKey(nativeTrim(assistantText)));
+        }
+        const before = messages.length;
+        if (type === 'message' && stringField(payload, 'role') === 'user') {
+          const context = codexUserContext(payload);
+          if (context.kind === 'hook_prompt') pushCodexDisplayItem(context.item, messages);
+        } else pushCodexItem(payload, messages);
+        fold.total += Math.max(0, messages.length - before); stampCodexMessages(messages, before, timestamp);
+        if (messages.length === before + 1) restoreGrokMessageExtension(payload, messages[before]);
+      } else if (kind === 'event_msg' && type === 'agent_message') {
+        const text = extractTextContent(payload, 'message');
+        if (nativeTrim(text) !== '' && !canonicalTexts.has(textKey(nativeTrim(text)))) {
+          const before = messages.length; pushCodexAssistant(messages, text); fold.total++;
+          messages.at(-1).metadata.codex_event_message = 'true'; eventTexts.add(textKey(messages.at(-1).content));
+          const phase = stringField(payload, 'phase'); if (phase != null) messages.at(-1).metadata.phase = phase;
+          stampCodexMessages(messages, before, timestamp);
+        }
+      }
+      return null;
+    },
+  };
+  return fold;
+}
+
 /** Bounded human-visible history, never a continuation or export artifact.
  * Durable TurnItems and legacy typed-user events retain their distinct paths. */
 export function fromCodexDisplayStr(text, messageLimit) {
   if (!Number.isSafeInteger(messageLimit) || messageLimit < 0) throw new RangeError('invalid Codex display message limit');
-  const session = createSession('codex'), { meta, messages } = session, precedingUsers = [], canonicalTexts = new Set();
+  const session = createSession('codex'), { messages } = session, precedingUsers = [], fold = codexDisplayFold(session);
   const retain = Math.min(Number.MAX_SAFE_INTEGER, Math.max(messageLimit, 1) + 64);
-  // The item ids and event texts the kept messages may hold: a record that names neither replaces nothing and looks
-  // through no message, so a read with no bound on its messages (a display anchor's) is linear in what it reads.
-  const displayItems = new Set(), eventTexts = new Set();
-  let paginated = false, recordCount = 0, total = 0;
   for (const line of nonEmptyLines(text)) {
-    recordCount++;
-    let value; try { value = parseNativeJson(line); } catch { session.parse_error_lines++; continue; }
-    const kind = stringField(value, 'type'), payload = field(value, 'payload'), type = stringField(payload, 'type'), timestamp = stringField(value, 'timestamp');
-    if (kind === 'session_meta') { paginated = stringField(payload, 'history_mode') === 'paginated'; captureCodexMeta(payload, meta); }
-    else if (kind === 'event_msg' && paginated && type === 'item_completed') {
-      const item = field(payload, 'item'), id = stringField(item, 'id');
-      if (id != null) {
-        const held = displayItems.has(id), position = held ? messages.findIndex((message) => message.metadata.codex_display_item === id) : -1, projected = [];
-        pushCodexDisplayItem(item, projected);
-        for (const message of projected) message.metadata.codex_display_item = id;
-        if (projected.length) displayItems.add(id);
-        stampCodexMessages(projected, 0, timestamp);
-        let removed = 0;
-        if (held) for (let index = messages.length - 1; index >= 0; index--) if (messages[index].metadata.codex_display_item === id) { messages.splice(index, 1); removed++; }
-        total = Math.max(0, total - removed) + projected.length;
-        const at = Math.min(position === -1 ? messages.length : position, messages.length);
-        for (let index = 0; index < projected.length; index++) messages.splice(at + index, 0, projected[index]);
-      }
-    } else if (['response_item', 'event_msg'].includes(kind) && paginated) { /* Model stream is separate from display history. */ }
-    else if (kind === 'turn_context' && meta.model == null) meta.model = stringField(payload, 'model');
-    else if (kind === 'event_msg' && type === 'user_message') {
-      const urls = [];
-      for (const key of ['images', 'local_images']) {
-        const images = field(payload, key); if (Array.isArray(images)) for (const image of images) if (typeof image === 'string') urls.push(image);
-      }
-      const text = stringField(payload, 'message') ?? '';
-      messages.push(urls.length ? codexUserWithImages(text, urls) : createMessage('user', text)); total++;
-    } else if (kind === 'response_item' && type !== 'reasoning') {
-      const isAssistant = type === 'message' && stringField(payload, 'role') === 'assistant';
-      const assistantText = isAssistant ? extractTextContent(payload, 'content') : null;
-      if (assistantText != null && nativeTrim(assistantText) !== '') {
-        const duplicate = eventTexts.has(assistantText) ? messages.findLastIndex((message) => Object.hasOwn(message.metadata, 'codex_event_message') && message.content === assistantText) : -1;
-        if (duplicate !== -1) { messages.splice(duplicate, 1); total = Math.max(0, total - 1); }
-        canonicalTexts.add(nativeTrim(assistantText));
-      }
-      const before = messages.length;
-      if (type === 'message' && stringField(payload, 'role') === 'user') {
-        const context = codexUserContext(payload);
-        if (context.kind === 'hook_prompt') pushCodexDisplayItem(context.item, messages);
-      } else pushCodexItem(payload, messages);
-      total += Math.max(0, messages.length - before); stampCodexMessages(messages, before, timestamp);
-      if (messages.length === before + 1) restoreGrokMessageExtension(payload, messages[before]);
-    } else if (kind === 'event_msg' && type === 'agent_message') {
-      const text = extractTextContent(payload, 'message');
-      if (nativeTrim(text) !== '' && !canonicalTexts.has(nativeTrim(text))) {
-        const before = messages.length; pushCodexAssistant(messages, text); total++;
-        messages.at(-1).metadata.codex_event_message = 'true'; eventTexts.add(messages.at(-1).content);
-        const phase = stringField(payload, 'phase'); if (phase != null) messages.at(-1).metadata.phase = phase;
-        stampCodexMessages(messages, before, timestamp);
-      }
-    }
+    fold.observe(line);
     if (messages.length > retain) {
       for (const message of messages.splice(0, messages.length - retain)) {
         if (message.role !== 'user') continue;
@@ -79,7 +100,7 @@ export function fromCodexDisplayStr(text, messageLimit) {
     }
   }
   clearCodexBookkeeping(messages, { display: true }); truncateMessagesWithAnchor(messages, messageLimit, precedingUsers);
-  session.raw = Array(recordCount).fill(''); session.raw_trailing_newline = text.endsWith('\n'); session.imported_message_count = total;
+  session.raw = Array(fold.recordCount).fill(''); session.raw_trailing_newline = text.endsWith('\n'); session.imported_message_count = fold.total;
   session.load_residue = ['display history is a bounded native-record projection, not resumable model context'];
   return session;
 }

package/session-codex-window.mjs

@@ -0,0 +1,212 @@
+import { withSessionFile } from './file-io.mjs';
+import { sessionFileLines, decodeSessionUtf8 } from './session-file.mjs';
+import { cloneNativeJson } from './native-json.mjs';
+import { createSession, normalizedSessionJson } from './session-model.mjs';
+import { messageJson } from './message.mjs';
+import { recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
+import { nativeTrim } from './text.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { isCompressedSessionPath, looksLikeSessionSqlite } from './session-path.mjs';
+import { detectSessionSource } from './session-source.mjs';
+import { codexDisplayFold } from './session-codex-display.mjs';
+import { clearCodexBookkeeping } from './session-codex-items.mjs';
+import { AppendScan, shortHash } from './session-append-scan.mjs';
+
+// What a message of the fold is made of, for a message held whole and for one kept without what it says: the records
+// that made it (where each stands: the one that made it, then each whose call joined its open turn), its place among
+// the messages its first record made, whether the rollout was paginated there, and, once kept, its mark: the digest
+// of the message as a read answers it.
+const made = new WeakMap();
+// All the fold reads of a message an earlier record made (codexDisplayFold), and the model a profile reads.
+const FOLDED = ['codex_display_item', 'codex_event_message', '__codex_open_turn', 'turn_id', 'model'];
+
+/** A message as a read answers it: the fold's own notes on it cleared, as they are when a whole read ends. */
+function answered(message) {
+  const sent = { ...message, metadata: cloneNativeJson(message.metadata) };
+  clearCodexBookkeeping([sent], { display: true });
+  return sent;
+}
+const markOf = (message) => shortHash(JSON.stringify(messageJson(answered(message))));
+
+/** The messages an entry's records make, as the fold made them: read again from where the records stand. */
+async function replay(entry, reader) {
+  const session = createSession('codex'), fold = codexDisplayFold(session, shortHash);
+  fold.paginated = entry.paginated;
+  for (const record of entry.records) fold.observe(nativeTrim(decodeSessionUtf8(await reader.read(record.offset, record.length))));
+  return session.messages;
+}
+
+/** The display fold over records taken one at a time, its messages kept without what they say: every message but
+ * the last (a call may still join its open turn) is replaced, once a later one follows it, by its role, the notes the
+ * fold reads and its mark. What a kept message says is read again from its records (`replay`). */
+class CodexDisplayState {
+  constructor(session = createSession('codex'), fold = codexDisplayFold(session, shortHash), modelled = false) {
+    this.session = session; this.fold = fold; this.modelled = modelled;
+  }
+
+  /** A state a record can be taken into without this one changing: for a last line that is still being written. */
+  fork() {
+    const messages = this.session.messages.slice(), last = messages.at(-1), entry = last && made.get(last);
+    if (entry && entry.mark == null) {
+      const copy = cloneNativeJson(last); made.set(copy, { ...entry, records: entry.records.slice() }); messages[messages.length - 1] = copy;
+    }
+    const session = { ...this.session, meta: cloneNativeJson(this.session.meta), messages };
+    return new CodexDisplayState(session, this.fold.clone(session), this.modelled);
+  }
+
+  async observe(record, text, reader) {
+    const { messages } = this.session; let live = messages.at(-1);
+    // A kept message that is last again (those after it were replaced) with its turn open is made again whole
+    // before a call may join it.
+    if (live && made.get(live).mark != null && live.role === 'assistant' && Object.hasOwn(live.metadata, '__codex_open_turn')) {
+      const entry = made.get(live); live = (await replay(entry, reader))[entry.ordinal];
+      made.set(live, { ...entry, mark: null }); messages[messages.length - 1] = live;
+    }
+    const calls = live?.tool_calls?.length ?? 0, placed = this.fold.observe(text);
+    if (live && messages.at(-1) === live && (live.tool_calls?.length ?? 0) !== calls) { const entry = made.get(live); entry.records.push(record); entry.bytes += record.length; }
+    let from = placed ? placed.at : messages.length; const end = placed ? placed.at + placed.count : messages.length;
+    if (!placed) while (from > 0 && !made.has(messages[from - 1])) from--;
+    for (let at = from; at < end; at++) made.set(messages[at], { records: [record], ordinal: at - from, paginated: this.fold.paginated, bytes: record.length, mark: null });
+    // The message that was last, where it stands now if it was not replaced: before what this record appended.
+    const before = end === messages.length ? from - 1 : messages.length - 1;
+    if (live && before >= 0 && before < messages.length - 1 && messages[before] === live && made.get(live).mark == null) this.#keep(before);
+    for (let at = from; at < end && at < messages.length - 1; at++) this.#keep(at);
+  }
+
+  #keep(at) {
+    const { messages } = this.session, whole = messages[at], metadata = Object.create(null);
+    for (const key of FOLDED) if (Object.hasOwn(whole.metadata, key)) metadata[key] = whole.metadata[key];
+    const kept = { role: whole.role, metadata };
+    if (Object.hasOwn(metadata, 'codex_event_message')) this.fold.events.set(kept, this.fold.eventKey(whole));
+    if (Object.hasOwn(metadata, 'model')) this.modelled = true;
+    made.set(kept, { ...made.get(whole), mark: markOf(whole) }); messages[at] = kept;
+  }
+
+  /** The mark of every message, and the model the session's profile reads: that of the last message naming one. */
+  view() {
+    const { messages } = this.session, last = messages.at(-1);
+    const modelled = this.modelled || (last != null && Object.hasOwn(last.metadata, 'model'));
+    return { state: this, messages, marks: messages.map((message) => made.get(message).mark ?? markOf(message)),
+      model: modelled ? messages.findLast((message) => Object.hasOwn(message.metadata, 'model'))?.metadata.model ?? null : null };
+  }
+}
+
+/** A rollout's complete lines from its display anchor as one pass over them leaves them, kept between reads of the
+ * same file: the next read takes only the lines written since (`extend`). The anchor's read is the header and every
+ * line after the record the anchor cuts (session-display.mjs loadSessionDisplayFrom): `head` is the header as it was
+ * read, and the bytes read through start after the cut record. */
+class CodexDisplayScan extends AppendScan {
+  state = new CodexDisplayState(); head = null; kept = null;
+
+  constructor(reader, anchor) { super(reader); this.anchor = anchor; }
+
+  async holds(reader) {
+    if (this.head == null || !await super.holds(reader)) return false;
+    return this.unchanged(reader) || this.head.hash === shortHash(await reader.read(0, this.head.length));
+  }
+
+  async #take(state, line, reader) {
+    let text;
+    try { text = line.text; } catch (error) { throw new Error(`${reader.path} contains non-UTF-8 data after its display anchor`, { cause: error }); }
+    const trimmed = nativeTrim(text);
+    if (trimmed !== '') await state.observe({ offset: line.offset, length: line.length }, trimmed, reader);
+  }
+
+  /** The lines completed since the last pass. A last line with no LF yet stays outside the scan: `project` reads it. */
+  async extend(reader, first) {
+    const from = this.bytes;
+    if (this.head == null) {
+      if (!first.terminated) return;
+      let start = null;
+      for (let at = this.anchor; at < reader.size && start == null;) {
+        const block = await reader.read(at, Math.min(64 * 1024, reader.size - at)), newline = block.indexOf(10);
+        if (newline !== -1) start = at + newline + 1;
+        at += block.length;
+      }
+      if (start == null) return;
+      await this.#take(this.state, first, reader);
+      this.head = { length: first.length, hash: shortHash(first.bytes) }; this.from = this.bytes = start;
+    }
+    for await (const line of sessionFileLines(reader, this.bytes)) {
+      if (!line.terminated) break;
+      await this.#take(this.state, line, reader); this.hashed.update(line.bytes); this.bytes = line.offset + line.length;
+    }
+    await this.settle(reader, from);
+  }
+
+  /** The fold of the file as `reader` holds it. A last line with no LF yet is taken 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. */
+  async project(reader, first) {
+    if (this.head != null && reader.size === this.bytes) return this.kept?.bytes === this.bytes ? this.kept.view : (this.kept = { bytes: this.bytes, view: this.state.view() }).view;
+    const state = this.head == null ? new CodexDisplayState() : this.state.fork();
+    if (this.head == null) await this.#take(state, first, reader);
+    else {
+      const bytes = await reader.read(this.bytes, reader.size - this.bytes); let text = null;
+      try { text = decodeSessionUtf8(bytes); } catch { state.fold.recordCount++; state.session.parse_error_lines++; }
+      if (text != null && nativeTrim(text) !== '') await state.observe({ offset: this.bytes, length: bytes.length }, nativeTrim(text), reader);
+    }
+    return state.view();
+  }
+}
+
+// The scans of the rollouts read most recently, at most this many messages between them (about 630 bytes a message
+// kept: 126 MB): a rollout read again is read from where its scan stopped, and one read long ago is scanned again.
+// Of the files whose scan read less than SCAN_KEPT_BYTES only the one read last is kept: scanning a short file again
+// costs less than keeping every one read.
+const SCANNED_MESSAGES = 200_000, SCAN_KEPT_BYTES = 8 * 1024 * 1024;
+const scans = new Map();
+const scanned = (scan) => scan.bytes - scan.from;
+
+async function scanOf(path, reader, anchor, first) {
+  let scan = scans.get(path); scans.delete(path);
+  if (scan?.anchor !== anchor || !await scan.holds(reader)) scan = new CodexDisplayScan(reader, anchor);
+  await scan.extend(reader, first);
+  if (scanned(scan) < SCAN_KEPT_BYTES) for (const [other, item] of scans) if (scanned(item) < SCAN_KEPT_BYTES) scans.delete(other);
+  scans.set(path, scan);
+  let held = 0; for (const item of scans.values()) held += item.state.session.messages.length;
+  for (const [other, item] of scans) { if (held <= SCANNED_MESSAGES || item === scan) break; scans.delete(other); held -= item.state.session.messages.length; }
+  return scan;
+}
+
+/**
+ * A window of a Codex rollout's display history as read from the byte `anchor` (loadSessionDisplayFrom), from the
+ * message at place `from`: at most `messages` of them and `bytes` of rollout (one message at least), with each one's
+ * mark and, when `marks` is asked, the mark of every message of that read. The rollout is read a line at a time and
+ * only as far as it was not read before; a message is the same one the whole read answers at that place, and its
+ * mark is the digest of it: while it stands at a place, so does what a reader took of that message there. Null when
+ * the locator names anything else, which is loaded as its document.
+ */
+export async function loadCodexRecordWindow(locator, anchor, { from, bytes = null, messages = null, marks = false }, { metrics } = {}) {
+  const { path, kind } = locator.storage;
+  if (kind !== 'file' || locator.harness === 'hermes' || anchor === 0 || isCompressedSessionPath(path)) return null;
+  if ((await sourceStat(path))?.isDirectory() || await looksLikeSessionSqlite(path, metrics)) return null;
+  return (await withSessionFile(path, async (reader) => {
+    let first = null;
+    for await (const line of sessionFileLines(reader)) { first = line; break; }
+    if (first == null || detectSessionSource(first.text) !== 'codex') return null;
+    if (anchor >= reader.size) throw new Error(`${path} is shorter than its display anchor (${anchor})`);
+    try {
+      const view = await (await scanOf(path, reader, anchor, first)).project(reader, first);
+      const total = view.messages.length, offset = Math.min(from, total), session = createSession('codex'), counted = new Set();
+      let end = offset, used = 0, again = null, againOf = null;
+      for (; end < total && (messages == null || end - offset < messages); end++) {
+        const message = view.messages[end], entry = made.get(message), record = entry.records[0].offset;
+        const cost = counted.has(record) ? 0 : entry.bytes;
+        if (bytes != null && end > offset && used + cost > bytes) break;
+        counted.add(record); used += cost;
+        if (entry.mark == null) { session.messages.push(answered(message)); continue; }
+        const key = `${record}:${entry.records.length}`;
+        if (againOf !== key) { again = await replay(entry, reader); againOf = key; }
+        const whole = again[entry.ordinal];
+        if (whole == null || markOf(whole) !== entry.mark) throw new Error(`${path} is no longer the rollout its scan read`);
+        session.messages.push(answered(whole));
+      }
+      const { state } = view;
+      session.meta = cloneNativeJson(state.session.meta); session.imported_message_count = total; session.parse_error_lines = state.session.parse_error_lines;
+      session.load_residue = ['display history is a bounded native-record projection, not resumable model context', `older native records remain before this display anchor (${anchor})`];
+      return { session: { ...normalizedSessionJson(session), raw_record_count: state.fold.recordCount,
+        resolved_profile: recordedSessionProfile(session, { model: view.model, version: null }), resolved_profile_history: recordedSessionProfileHistory(session),
+        window: { offset, returned: end - offset, total_messages: total, marks: view.marks.slice(offset, end), ...(marks ? { all_marks: view.marks } : {}) } } };
+    } catch (error) { scans.delete(path); throw error; }
+  }, metrics)).result;
+}

package/session-file.mjs

@@ -26,23 +26,30 @@ export async function sessionFileBytes(reader, from = 0) {
 }
 export const sessionFileText = async (reader) => decodeSessionUtf8(await sessionFileBytes(reader));
 
-/** One physical line at a time, including an unterminated final line. LF and
- * CR remain in the bytes; offsets always address the verified open file. */
-export async function* sessionFileLines(reader) {
-  let pieces = [], pending = 0, start = 0;
-  for (let offset = 0; offset < reader.size;) {
+/** A line where it stands: its text is decoded when first read, so a reader that only places a line (a last one
+ * still being written) is not refused for bytes it never reads as text. */
+function fileLine(offset, bytes, terminated) {
+  let text;
+  return { offset, length: bytes.length, bytes, terminated, get text() { return text ??= decodeSessionUtf8(bytes); } };
+}
+
+/** One physical line at a time from `from` (the start of a line), including an unterminated final line. LF and
+ * CR remain in the bytes; offsets always address the verified open file. `bytes` is the line as it is stored and
+ * `terminated` says its LF was read: a last line without one may still be being written. */
+export async function* sessionFileLines(reader, from = 0) {
+  let pieces = [], pending = 0, start = from;
+  for (let offset = from; offset < reader.size;) {
     const chunk = await reader.read(offset, Math.min(64 * 1024, reader.size - offset));
     const chunkStart = offset; offset += chunk.length;
-    let from = 0, end;
-    while ((end = chunk.indexOf(10, from)) !== -1) {
-      pieces.push(chunk.subarray(from, end + 1)); pending += end + 1 - from;
-      const bytes = pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pending);
-      yield { offset: start, length: pending, text: decodeSessionUtf8(bytes) };
-      start = chunkStart + end + 1; from = end + 1; pieces = []; pending = 0;
+    let at = 0, end;
+    while ((end = chunk.indexOf(10, at)) !== -1) {
+      pieces.push(chunk.subarray(at, end + 1)); pending += end + 1 - at;
+      yield fileLine(start, pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pending), true);
+      start = chunkStart + end + 1; at = end + 1; pieces = []; pending = 0;
     }
-    if (from < chunk.length) { pieces.push(chunk.subarray(from)); pending += chunk.length - from; }
+    if (at < chunk.length) { pieces.push(chunk.subarray(at)); pending += chunk.length - at; }
   }
-  if (pending) yield { offset: start, length: pending, text: decodeSessionUtf8(Buffer.concat(pieces, pending)) };
+  if (pending) yield fileLine(start, Buffer.concat(pieces, pending), false);
 }
 
 export async function readSessionText(path, metrics) {

package/session-model.d.ts

@@ -108,7 +108,7 @@ export function normalizedItemCount(messages: readonly ChatMessage[]): number;
 export function projectedMessageWindow(total: number, options: SessionLoadOptions): [number, number];
 export function projectInlineMedia(message: MessageJson, options: SessionLoadOptions): MessageJson;
 export function projectedSessionSummary(session: Session, options: SessionLoadOptions): SessionSummary;
-export function recordedSessionProfile(session: Session): RecordedSessionProfile;
+export function recordedSessionProfile(session: Session, read?: { model: string | null; version: string | null } | null): RecordedSessionProfile;
 export function recordedSessionProfileHistory(session: Session): RecordedSessionProfileChange[];
 export function projectedSessionJson(session: Session, options: SessionLoadOptions): ProjectedSession;
 export function projectedSessionResult(session: Session, options: SessionLoadOptions): ProjectedSessionResult;

package/session-read.d.ts

@@ -10,8 +10,8 @@ export interface SessionReadContext { cwd?: string; env?: Record<string, string
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
 export function prettySessionWire(value: unknown): string;
-export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null }) | null; options: import('./session-model.js').SessionLoadOptions | null };
-export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[] } }>;
+export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null; fromMessage: number | null; windowBytes: number | null; windowMessages: number | null; marks: boolean }) | null; options: import('./session-model.js').SessionLoadOptions | null };
+export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[]; window?: { offset: number; returned: number; total_messages: number; marks: string[]; all_marks?: string[] } } }>;
 export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;
 /** Recorded values only; malformed complete Claude runtime state leaves mode unknown. */
 export function loadRecordedSessionConfiguration(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; cwd: unknown; model: unknown; approval_policy: unknown; sandbox_policy: unknown; permission_mode: string | null }>;

package/session-read.mjs

@@ -4,7 +4,8 @@ import { resolve } from 'node:path';
 import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJson, stringifyNativeJsonPretty } from './native-json.mjs';
 import { loadSessionLocator } from './session-path.mjs';
 import { loadSessionDisplayLocator, loadSessionDisplayFrom } from './session-display.mjs';
-import { withClaudeReadIndex, supportsClaudeReadIndex } from './session-claude-index.mjs';
+import { withClaudeReadIndex, supportsClaudeReadIndex, loadClaudeRecordWindow } from './session-claude-index.mjs';
+import { loadCodexRecordWindow } from './session-codex-window.mjs';
 import { SessionFollower } from './session-follower.mjs';
 import { normalizedSessionJson } from './session-model.mjs';
 import { boundSessionView, projectedMessageWindow, projectedSessionJson, projectedSessionResult, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
@@ -58,7 +59,8 @@ export function parseSessionReadParams(params, { cwd = process.cwd() } = {}) {
     const suppliedView = object(params.view, 'view');
     view = { includeSubagents: boolean(suppliedView, 'include_subagents', false), displayHistory: boolean(suppliedView, 'display_history', false),
       messageLimit: unsigned(suppliedView, 'tail_messages', 5000), maxMessageChars: unsigned(suppliedView, 'max_message_chars', 64000),
-      fromByte: unsigned(suppliedView, 'from_byte') };
+      fromByte: unsigned(suppliedView, 'from_byte'), fromMessage: unsigned(suppliedView, 'from_message'),
+      windowBytes: unsigned(suppliedView, 'window_bytes'), windowMessages: unsigned(suppliedView, 'window_messages'), marks: boolean(suppliedView, 'marks', false) };
     if (view.messageLimit != null) view.messageLimit = Math.max(1, view.messageLimit);
     if (view.maxMessageChars != null) view.maxMessageChars = Math.max(256, view.maxMessageChars);
   }
@@ -97,6 +99,16 @@ export async function loadSessionRead(params, context = {}) {
     return projectedSessionResult(await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless' }), options);
   }
   const readOptions = { ...context, fidelity, includeSubagents: view?.includeSubagents ?? true };
+  // A view from a message on is a window of the session read record by record, where its reader has one.
+  if (view?.fromMessage != null && !view.includeSubagents && !view.displayHistory) {
+    const windowed = await loadClaudeRecordWindow(locator, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks }, readOptions);
+    if (windowed != null) return windowed;
+  }
+  // So is a view from a message on of a Codex rollout's display history read from an anchor.
+  if (view?.fromMessage != null && !view.includeSubagents && view.displayHistory && view.fromByte != null) {
+    const windowed = await loadCodexRecordWindow(locator, view.fromByte, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks }, readOptions);
+    if (windowed != null) return windowed;
+  }
   const session = view?.displayHistory
     ? view.fromByte != null ? await loadSessionDisplayFrom(locator, view.fromByte, readOptions)
       : await loadSessionDisplayLocator(locator, view.messageLimit ?? 500, readOptions)

package/session-records.mjs

@@ -17,7 +17,8 @@ import { restoreTopLevelResidue } from './session-native-residue.mjs';
 import { isCompressedSessionPath, looksLikeSessionSqlite, sessionTextError } from './session-path.mjs';
 
 async function* lines(reader) {
-  try { yield* sessionFileLines(reader); }
+  // a line's text is decoded when first read: here, so that what cannot be decoded is said as this file's
+  try { for await (const line of sessionFileLines(reader)) { void line.text; yield line; } }
   catch (error) { throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(reader.path, error) : error; }
 }
 

package/session-views.mjs

@@ -94,10 +94,12 @@ const payloadFor = (record) => has(record, 'payload') ? record.payload : record;
 function parsedRecord(line) { try { return parseNativeJson(line); } catch { return null; } }
 
 /** Only recorded facts. Current configuration and the reader's executable
- * never fill unknown historical fields. */
-export function recordedSessionProfile(session) {
+ * never fill unknown historical fields. `read` gives what a reader that holds
+ * neither every message nor the raw lines found in them: the last recorded
+ * model and Claude Code version. */
+export function recordedSessionProfile(session, read = null) {
   const { meta } = session;
-  let model = session.messages.findLast((message) => has(message.metadata, 'model'))?.metadata.model ?? meta.model;
+  let model = (read ? read.model : session.messages.findLast((message) => has(message.metadata, 'model'))?.metadata.model) ?? meta.model;
   let cwd = meta.cwd, version = null, approval = null, sandbox = null;
   for (const header of meta.codex_headers) {
     const payload = payloadFor(header);
@@ -108,7 +110,8 @@ export function recordedSessionProfile(session) {
     if (has(payload, 'sandbox_policy')) sandbox = cloneNativeJson(payload.sandbox_policy);
   }
   if (meta.source === 'claude_code') {
-    for (let at = session.raw.length - 1; at >= 0; at--) {
+    if (read) version = read.version;
+    else for (let at = session.raw.length - 1; at >= 0; at--) {
       const recorded = string(parsedRecord(session.raw[at])?.version);
       if (recorded != null) { version = recorded; break; }
     }
@@ -119,30 +122,37 @@ export function recordedSessionProfile(session) {
   };
 }
 
+/** The recorded profile as each record changes it, one record at a time: `history` names every record that changed it. */
+export function recordedProfileFold(source, profile = {
+  worker: { harness: source === 'codex' ? 'codex' : 'claude-code', model: null, cwd: null, binary: { version: null } },
+  permissions: { native: { approval: null, sandbox: null } }, source: 'native-session',
+}, history = []) {
+  return {
+    history,
+    clone: () => recordedProfileFold(source, cloneNativeJson(profile), [...history]),
+    record(index, record) {
+      if (record == null) return;
+      const before = cloneNativeJson(profile), payload = payloadFor(record);
+      for (const key of ['cwd', 'model']) {
+        if (typeof payload?.[key] === 'string') profile.worker[key] = payload[key];
+      }
+      const version = string(has(payload, 'cli_version') ? payload.cli_version : record?.version);
+      if (version != null) profile.worker.binary.version = version;
+      if (typeof record?.message?.model === 'string') profile.worker.model = record.message.model;
+      for (const [key, target] of [['approval_policy', 'approval'], ['sandbox_policy', 'sandbox']]) {
+        if (has(payload, key)) profile.permissions.native[target] = cloneNativeJson(payload[key]);
+      }
+      if (!isDeepStrictEqual(before, profile)) history.push({ native_key: `profile-record:${index}`, at: string(record?.timestamp), profile: cloneNativeJson(profile) });
+    },
+  };
+}
+
 export function recordedSessionProfileHistory(session) {
   if (!['codex', 'claude_code'].includes(session.meta.source)) return [];
-  const profile = {
-    worker: { harness: session.meta.source === 'codex' ? 'codex' : 'claude-code', model: null, cwd: null, binary: { version: null } },
-    permissions: { native: { approval: null, sandbox: null } }, source: 'native-session',
-  };
+  const fold = recordedProfileFold(session.meta.source);
   const records = session.meta.source === 'codex' ? session.meta.codex_headers : session.raw;
-  const history = [];
-  for (let index = 0; index < records.length; index++) {
-    const record = session.meta.source === 'codex' ? records[index] : parsedRecord(records[index]);
-    if (record == null) continue;
-    const before = cloneNativeJson(profile), payload = payloadFor(record);
-    for (const key of ['cwd', 'model']) {
-      if (typeof payload?.[key] === 'string') profile.worker[key] = payload[key];
-    }
-    const version = string(has(payload, 'cli_version') ? payload.cli_version : record?.version);
-    if (version != null) profile.worker.binary.version = version;
-    if (typeof record?.message?.model === 'string') profile.worker.model = record.message.model;
-    for (const [key, target] of [['approval_policy', 'approval'], ['sandbox_policy', 'sandbox']]) {
-      if (has(payload, key)) profile.permissions.native[target] = cloneNativeJson(payload[key]);
-    }
-    if (!isDeepStrictEqual(before, profile)) history.push({ native_key: `profile-record:${index}`, at: string(record?.timestamp), profile: cloneNativeJson(profile) });
-  }
-  return history;
+  for (let index = 0; index < records.length; index++) fold.record(index, session.meta.source === 'codex' ? records[index] : parsedRecord(records[index]));
+  return fold.history;
 }
 
 export function projectedSessionJson(session, options) {