@volter/supercode-interchange 0.1.11 → 0.1.13

package/file-io.mjs

@@ -3,6 +3,10 @@ import { parseNativeJson } from './native-json.mjs';
 
 const stale = (path) => Object.assign(new Error(`${path} changed during its metadata read; previous index rows are retained`), { code: 'ESTALE' });
 const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs;
+// A file its writer appended to while it was read is the same file with more after the bytes read: the facts read are
+// those of the open's size, and the next read takes the rest. A live transcript is written more often than a large
+// read takes, so refusing an append would refuse every read of it.
+const sameOrAppended = (before, now) => same(before, now) || before.dev === now.dev && before.ino === now.ino && now.size > before.size;
 
 export function fileFingerprint(info) {
   return { device: String(info.dev), inode: String(info.ino), size: String(info.size), mtime_ns: String(info.mtimeNs) };
@@ -19,7 +23,9 @@ export function appendableFingerprint(previous, current) {
 
 /** Read one open identity; verify both the handle and its current path before
  * returning facts for a transaction. A changed path never commits new offsets
- * beside facts read from its predecessor. The caller owns failure retry. */
+ * beside facts read from its predecessor: a file replaced, truncated or rewritten
+ * in place is stale, while one only appended to answers for the size it was
+ * opened at. The caller owns failure retry. */
 export async function withSessionFile(path, work, metrics = {}) {
   const handle = await open(path, 'r');
   metrics.files_opened = (metrics.files_opened ?? 0) + 1;
@@ -51,7 +57,7 @@ export async function withSessionFile(path, work, metrics = {}) {
     const after = await handle.stat({ bigint: true });
     let current;
     try { current = await stat(path, { bigint: true }); } catch { throw stale(path); }
-    if (!same(before, after) || !same(after, current)) throw stale(path);
+    if (!sameOrAppended(before, after) || !sameOrAppended(before, current) || current.size < after.size) throw stale(path);
     return { result, fingerprint: reader.fingerprint, size, modified_ms: reader.modified_ms };
   } finally { await handle.close(); }
 }

package/package.json

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

package/session-claude-files.mjs

@@ -2,7 +2,7 @@ import { readdir } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { withSessionFile } from './file-io.mjs';
 import { sourceStat } from './store-registry.mjs';
-import { decodeSessionUtf8, readSessionText } from './session-file.mjs';
+import { sessionFileText, readSessionText } from './session-file.mjs';
 import { parseNativeJson, stringifyNativeJson } from './native-json.mjs';
 import { fromClaudeCodeStr } from './session-claude.mjs';
 import { nonEmptyLines } from './session-lines.mjs';
@@ -70,7 +70,7 @@ export async function attachClaudeSubagents(session, mainPath, mainText, fidelit
  * reconstruction can degrade only in a semantic view, never an export. */
 export async function readClaudeCodeFile(path, { fidelity = 'byte_lossless', metrics } = {}) {
   return withSessionFile(path, async (reader) => {
-    const text = decodeSessionUtf8(await reader.read(0, reader.size));
+    const text = await sessionFileText(reader);
     const session = fromClaudeCodeStr(text, { fidelity });
     await attachClaudeSubagents(session, path, text, fidelity, metrics);
     return session;

package/session-claude-runtime.mjs

@@ -151,63 +151,75 @@ function applyNotification({ notification: note, timestamp, line }, children) {
   child.finished_at = timestamp; child.summary = note.summary;
 }
 
-/** Reconstruct all runtime-affecting records before exposing any posture.
- * Invalid unrelated queue/tool/notification references refuse the manifest. */
-export function claudeRuntimeManifest(session) {
-  if (session.meta.source !== 'claude_code') fail('Claude runtime state can only be extracted from a Claude Code session');
-  if (session.parse_error_lines !== 0) fail(`cannot reconstruct Claude runtime state: ${session.parse_error_lines} malformed JSONL line(s)`);
+/** The manifest's fold, one parsed record at a time: every record's calls
+ * first, then every record again in order, so physically earlier async
+ * results can resolve their origins. `raw` is kept only in the residue. */
+export function claudeRuntimeFold() {
   const state = { crons: new Map(), pending: new Map(), children: new Map(), wakeups: new Map(), notifications: [], residue: [] };
   const posture = { permission_mode: null, last_prompt_leaf_uuid: null, last_prompt: null, timestamp: null, entrypoint: null, user_type: null, version: null, cwd: null };
   const queue = { enqueued: 0, dequeued: 0, removed: 0, pending: [] };
   let incoming = [], outgoing = [];
   let reported = null;
+  return {
+    call(value, line, raw) { if (stringField(value, 'type') === 'assistant') assistantCalls(value, line, raw, state); },
+    record(value, line, raw) {
+      for (const [key, target] of [['timestamp', 'timestamp'], ['entrypoint', 'entrypoint'], ['userType', 'user_type'], ['version', 'version'], ['cwd', 'cwd']]) {
+        const text = stringField(value, key); if (text != null) posture[target] = text;
+      }
+      const kind = stringField(value, 'type') ?? '';
+      if (kind === 'permission-mode') { posture.permission_mode = required(value, 'permissionMode', line, 'permission-mode'); residue(state, line, kind, raw); }
+      else if (kind === 'last-prompt') {
+        posture.last_prompt_leaf_uuid = stringField(value, 'leafUuid'); posture.last_prompt = stringField(value, 'lastPrompt'); residue(state, line, kind, raw);
+      } else if (kind === 'queue-operation') {
+        const operation = required(value, 'operation', line, kind);
+        if (operation === 'enqueue') {
+          const content = required(value, 'content', line, 'queue enqueue'); queue.enqueued++; incoming.push(content);
+          const fired = [...state.wakeups.keys()].sort(order).find(id => { const held = state.wakeups.get(id); return (held.prompt ?? held.reason) === content; });
+          if (fired !== undefined) state.wakeups.delete(fired);
+          const notification = taskNotification(content); if (notification != null) state.notifications.push({ notification, timestamp: stringField(value, 'timestamp'), line });
+        } else if (operation === 'dequeue' || operation === 'remove') {
+          queue[operation === 'dequeue' ? 'dequeued' : 'removed']++;
+          if (!outgoing.length) { outgoing = incoming.reverse(); incoming = []; }
+          if (!outgoing.length) fail(`malformed Claude queue reference at line ${line}: ${operation} with an empty queue`);
+          outgoing.pop();
+        } else { residue(state, line, `unknown-queue-operation:${operation}`, raw); return; }
+        residue(state, line, kind, raw);
+      } else if (kind === 'user') toolResults(value, line, raw, state);
+      else if (kind === 'system') {
+        const count = nativeInteger(value, 'pendingBackgroundAgentCount');
+        if (count != null) { reported = count; residue(state, line, 'background-count', raw); }
+        else if (stringField(value, 'subtype') === 'scheduled_task_fire') residue(state, line, 'scheduled-task-fire', raw);
+      } else if (kind !== 'assistant' && runtimeType(kind)) residue(state, line, 'unknown-runtime-record', raw);
+    },
+    finish() {
+      for (const notification of state.notifications) applyNotification(notification, state.children);
+      queue.pending = outgoing.reverse().concat(incoming);
+      state.residue.sort((left, right) => left.line - right.line);
+      const manifest = { schema_version: CLAUDE_RUNTIME_MANIFEST_VERSION, posture, active_crons: sorted(state.crons), pending_wakeups: sorted(state.wakeups), queue,
+        background_children: sorted(state.children), reported_pending_background_children: null, residue: state.residue };
+      if (reported != null) setNativeInteger(manifest, 'reported_pending_background_children', reported);
+      return manifest;
+    },
+  };
+}
+
+/** Reconstruct all runtime-affecting records before exposing any posture.
+ * Invalid unrelated queue/tool/notification references refuse the manifest. */
+export function claudeRuntimeManifest(session) {
+  if (session.meta.source !== 'claude_code') fail('Claude runtime state can only be extracted from a Claude Code session');
+  if (session.parse_error_lines !== 0) fail(`cannot reconstruct Claude runtime state: ${session.parse_error_lines} malformed JSONL line(s)`);
+  const fold = claudeRuntimeFold();
   const decode = (raw, line) => {
     if (nativeTrim(raw) === '') return null;
     try { return { value: parseNativeJson(raw) }; }
     catch (error) { fail(`cannot reconstruct Claude runtime state: malformed JSON at line ${line}: ${error.message}`); }
   };
-  // Calls precede the ordered fold so physically earlier async results can
-  // resolve their origins. Each pass releases one parsed record at a time.
+  // Each pass releases one parsed record at a time.
   for (let offset = 0; offset < session.raw.length; offset++) {
-    const raw = session.raw[offset], line = offset + 1, decoded = decode(raw, line); if (decoded == null) continue;
-    if (stringField(decoded.value, 'type') === 'assistant') assistantCalls(decoded.value, line, raw, state);
+    const raw = session.raw[offset], line = offset + 1, decoded = decode(raw, line); if (decoded != null) fold.call(decoded.value, line, raw);
   }
   for (let offset = 0; offset < session.raw.length; offset++) {
-    const raw = session.raw[offset], line = offset + 1, decoded = decode(raw, line); if (decoded == null) continue;
-    const { value } = decoded;
-    for (const [key, target] of [['timestamp', 'timestamp'], ['entrypoint', 'entrypoint'], ['userType', 'user_type'], ['version', 'version'], ['cwd', 'cwd']]) {
-      const text = stringField(value, key); if (text != null) posture[target] = text;
-    }
-    const kind = stringField(value, 'type') ?? '';
-    if (kind === 'permission-mode') { posture.permission_mode = required(value, 'permissionMode', line, 'permission-mode'); residue(state, line, kind, raw); }
-    else if (kind === 'last-prompt') {
-      posture.last_prompt_leaf_uuid = stringField(value, 'leafUuid'); posture.last_prompt = stringField(value, 'lastPrompt'); residue(state, line, kind, raw);
-    } else if (kind === 'queue-operation') {
-      const operation = required(value, 'operation', line, kind);
-      if (operation === 'enqueue') {
-        const content = required(value, 'content', line, 'queue enqueue'); queue.enqueued++; incoming.push(content);
-        const fired = [...state.wakeups.keys()].sort(order).find(id => { const held = state.wakeups.get(id); return (held.prompt ?? held.reason) === content; });
-        if (fired !== undefined) state.wakeups.delete(fired);
-        const notification = taskNotification(content); if (notification != null) state.notifications.push({ notification, timestamp: stringField(value, 'timestamp'), line });
-      } else if (operation === 'dequeue' || operation === 'remove') {
-        queue[operation === 'dequeue' ? 'dequeued' : 'removed']++;
-        if (!outgoing.length) { outgoing = incoming.reverse(); incoming = []; }
-        if (!outgoing.length) fail(`malformed Claude queue reference at line ${line}: ${operation} with an empty queue`);
-        outgoing.pop();
-      } else { residue(state, line, `unknown-queue-operation:${operation}`, raw); continue; }
-      residue(state, line, kind, raw);
-    } else if (kind === 'user') toolResults(value, line, raw, state);
-    else if (kind === 'system') {
-      const count = nativeInteger(value, 'pendingBackgroundAgentCount');
-      if (count != null) { reported = count; residue(state, line, 'background-count', raw); }
-      else if (stringField(value, 'subtype') === 'scheduled_task_fire') residue(state, line, 'scheduled-task-fire', raw);
-    } else if (kind !== 'assistant' && runtimeType(kind)) residue(state, line, 'unknown-runtime-record', raw);
+    const raw = session.raw[offset], line = offset + 1, decoded = decode(raw, line); if (decoded != null) fold.record(decoded.value, line, raw);
   }
-  for (const notification of state.notifications) applyNotification(notification, state.children);
-  queue.pending = outgoing.reverse().concat(incoming);
-  state.residue.sort((left, right) => left.line - right.line);
-  const manifest = { schema_version: CLAUDE_RUNTIME_MANIFEST_VERSION, posture, active_crons: sorted(state.crons), pending_wakeups: sorted(state.wakeups), queue,
-    background_children: sorted(state.children), reported_pending_background_children: null, residue: state.residue };
-  if (reported != null) setNativeInteger(manifest, 'reported_pending_background_children', reported);
-  return manifest;
+  return fold.finish();
 }

package/session-display.mjs

@@ -1,7 +1,7 @@
 import { withSessionFile } from './file-io.mjs';
 import { sourceStat } from './store-registry.mjs';
 import { verifySources } from './source-files.mjs';
-import { sessionFileLines, decodeSessionUtf8 } from './session-file.mjs';
+import { sessionFileLines, sessionFileBytes, decodeSessionUtf8 } from './session-file.mjs';
 import { field, stringField, truncateMessagesWithAnchor } from './session-codec-utils.mjs';
 import { parseNativeJson } from './native-json.mjs';
 import { nativeTrim } from './text.mjs';
@@ -125,7 +125,7 @@ export async function loadSessionDisplayFrom(locator, fromByte, options = {}) {
   const captured = await withSessionFile(path, async (reader) => {
     const first = await firstLine(reader); if (detectSessionSource(first) !== 'codex') return null;
     if (fromByte >= reader.size) throw new Error(`${path} is shorter than its display anchor (${fromByte})`);
-    let bytes = await reader.read(fromByte, reader.size - fromByte);
+    let bytes = await sessionFileBytes(reader, fromByte);
     const newline = bytes.indexOf(10); bytes = newline === -1 ? Buffer.alloc(0) : bytes.subarray(newline + 1);
     let tail; try { tail = decodeSessionUtf8(bytes); } catch (error) { throw new Error(`${path} contains non-UTF-8 data after its display anchor`, { cause: error }); }
     const session = fromCodexDisplayStr(first + tail, unbounded);

package/session-file.mjs

@@ -1,7 +1,31 @@
+import { constants } from 'node:buffer';
 import { withSessionFile } from './file-io.mjs';
 
+const MAX_TEXT = constants.MAX_STRING_LENGTH;
+/** The session-read doors' answer for a file this reader cannot read for what is in it (text that is not UTF-8,
+ * or too long to hold): the same bytes get the same answer from the same reader. Any other failure of a read (the
+ * disk, a file changed under it, a fault in the reader) answers the generic code and says nothing of the file. */
+export const SESSION_UNREADABLE = -32050;
+export const textTooLong = (path, cause) => Object.assign(new Error(`${path} holds more text than this runtime keeps in one string (${MAX_TEXT} UTF-16 units); it can be read record by record, never as one document`, { cause }), { code: 'EFBIG', rpcCode: SESSION_UNREADABLE });
 export const decodeSessionUtf8 = (bytes) => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
 
+/** The file from `from` to its end, for a reader that needs it as one text.
+ * Bytes whose text cannot be one string are refused as that before they are
+ * held: their UTF-16 length is counted a bounded block at a time. A compressed
+ * file's bytes are not its text, which is measured where it is decoded. */
+export async function sessionFileBytes(reader, from = 0) {
+  if (reader.size - from > MAX_TEXT && !reader.path.endsWith('.zst')) {
+    let units = 0;
+    for (let offset = from; offset < reader.size && units <= MAX_TEXT;) {
+      const block = await reader.read(offset, Math.min(1024 * 1024, reader.size - offset)); offset += block.length;
+      for (let at = 0; at < block.length; at++) { const byte = block[at]; if ((byte & 0xc0) !== 0x80) units += byte >= 0xf0 ? 2 : 1; }
+    }
+    if (units > MAX_TEXT) throw textTooLong(reader.path);
+  }
+  return reader.read(from, reader.size - from);
+}
+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) {
@@ -22,6 +46,6 @@ export async function* sessionFileLines(reader) {
 }
 
 export async function readSessionText(path, metrics) {
-  const capture = await withSessionFile(path, async (reader) => decodeSessionUtf8(await reader.read(0, reader.size)), metrics);
+  const capture = await withSessionFile(path, sessionFileText, metrics);
   return capture.result;
 }

package/session-opencode-store.mjs

@@ -2,7 +2,7 @@ import { dirname, join } from 'node:path';
 import { readStore, statement, tableColumns, text, integer } from './sqlite-reader.mjs';
 import { sourceStat } from './store-registry.mjs';
 import { optionalFile, verifySources } from './source-files.mjs';
-import { decodeSessionUtf8 } from './session-file.mjs';
+import { sessionFileText } from './session-file.mjs';
 import { parseNativeJson, setNativeInteger, setNativeFloat } from './native-json.mjs';
 import { isObject, stringField } from './session-codec-utils.mjs';
 import { fromOpenCodeStr, opencodeEnvelope } from './session-opencode.mjs';
@@ -90,7 +90,7 @@ export async function readOpenCodeSqlite(path, sessionId = null, options = {}) {
   }, options.metrics);
   const { id, lines } = captured.result, sidecarPath = join(dirname(path), 'storage', 'session_diff', `${id}.json`);
   const sidecar = await optionalFile(sidecarPath, async (reader) => {
-    const source = decodeSessionUtf8(await reader.read(0, reader.size));
+    const source = await sessionFileText(reader);
     try { return { parsed: true, value: parseNativeJson(source) }; }
     catch (error) { diagnostic(options, { message: 'opencode session_diff sidecar failed to parse as JSON — skipping', path: sidecarPath, error: error.message }); return { parsed: false }; }
   }, options.metrics);

package/session-path.mjs

@@ -6,7 +6,7 @@ import { withSessionFile, fileFingerprint } from './file-io.mjs';
 import { sourceStat } from './store-registry.mjs';
 import { optionalFile, verifySources, decodeWorkspaceFolder } from './source-files.mjs';
 import { readStore, statement } from './sqlite-reader.mjs';
-import { decodeSessionUtf8 } from './session-file.mjs';
+import { decodeSessionUtf8, sessionFileBytes, sessionFileText, textTooLong, SESSION_UNREADABLE } from './session-file.mjs';
 import { field, stringField, valueString } from './session-codec-utils.mjs';
 import { parseNativeJson } from './native-json.mjs';
 import { nonEmptyLines } from './session-lines.mjs';
@@ -19,15 +19,17 @@ import { readGooseSqlite } from './session-goose.mjs';
 import { readHermesSqlite } from './session-hermes.mjs';
 
 export const isCompressedSessionPath = (path) => extname(path) === '.zst';
+/** Text too long for one string is said to be that; any other undecodable text is not session text. */
+export const sessionTextError = (path, cause) => cause?.code === 'ERR_STRING_TOO_LONG' ? textTooLong(path, cause)
+  : Object.assign(new Error(`${path} is not valid UTF-8 text, and is not a recognized OpenCode SQLite store (no \`SQLite format 3\` header) — supercode reads session logs as UTF-8 JSONL, or an OpenCode \`opencode*.db\` SQLite file`, { cause }), { rpcCode: SESSION_UNREADABLE });
 export async function sessionReaderText(reader) {
-  let bytes = await reader.read(0, reader.size);
+  let bytes = await sessionFileBytes(reader);
   if (isCompressedSessionPath(reader.path)) {
     if (typeof zlib.zstdDecompress !== 'function') throw new Error('compressed transcripts require Node 22.15 or later with zstdDecompress');
     try { bytes = await promisify(zlib.zstdDecompress)(bytes); }
     catch (error) { throw new Error(`${reader.path} is not a readable zstd stream: ${error.message}`, { cause: error }); }
   }
-  try { return decodeSessionUtf8(bytes); }
-  catch (error) { throw new Error(`${reader.path} is not valid UTF-8 text, and is not a recognized OpenCode SQLite store (no \`SQLite format 3\` header) — supercode reads session logs as UTF-8 JSONL, or an OpenCode \`opencode*.db\` SQLite file`, { cause: error }); }
+  try { return decodeSessionUtf8(bytes); } catch (error) { throw sessionTextError(reader.path, error); }
 }
 
 export async function looksLikeSessionSqlite(path, metrics) {
@@ -55,7 +57,7 @@ export async function captureGrokPathMetadata(session, path, metrics) {
   const workspace = dirname(directory);
   session.meta.cwd = workspace === '.' || workspace === sep ? null : decodeWorkspaceFolder(basename(workspace));
   const summary = await optionalFile(join(directory, 'summary.json'), async (reader) => {
-    const source = decodeSessionUtf8(await reader.read(0, reader.size));
+    const source = await sessionFileText(reader);
     try { return parseNativeJson(source); } catch { return null; }
   }, metrics);
   const model = stringField(summary.result, 'current_model_id'); if (model != null) session.meta.model = model;
@@ -73,7 +75,7 @@ export async function loadNativeStoreFamily(path, { metrics } = {}) {
   const sidecar = await sourceStat(sidecarPath), sources = [{ path: metaPath, fingerprint: fileFingerprint(meta) }];
   sources.push(sidecar ? { path: sidecarPath, fingerprint: fileFingerprint(sidecar) } : { path: sidecarPath, missing: true });
   const session = (await withSessionFile(sidecar?.isFile() ? sidecarPath : path, async (reader) => {
-    const text = decodeSessionUtf8(await reader.read(0, reader.size));
+    const text = await sessionFileText(reader);
     return sidecar?.isFile() ? fromSidecarStr(text) : fromNativeMessages([...nonEmptyLines(text)].map((line) => deserializeMessage(parseNativeJson(line))));
   }, metrics)).result;
   await verifySources(sources); session.meta.session_id = name; return session;

package/session-read.d.ts

@@ -3,6 +3,8 @@ import { SessionFollower } from './session-codecs.js';
 import type { ProjectedSessionResult, NormalizedSession, RecordedSessionProfile, RecordedSessionProfileChange } from './session-model.js';
 export const SESSION_READ_METHODS: readonly string[];
 export const SESSION_READ_EVENT: 'harness.v1.sessions.event';
+/** The read doors' error code for a file this reader cannot read for what is in it. */
+export const SESSION_UNREADABLE: -32050;
 export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true; usage: true; spend: true; resume_instructions: true }>;
 export interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
 export function parseSessionWire(text: string): unknown;

package/session-read.mjs

@@ -8,9 +8,11 @@ import { withClaudeReadIndex, supportsClaudeReadIndex } from './session-claude-i
 import { SessionFollower } from './session-follower.mjs';
 import { normalizedSessionJson } from './session-model.mjs';
 import { boundSessionView, projectedMessageWindow, projectedSessionJson, projectedSessionResult, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
-import { recordedSessionConfiguration } from './session-recorded-config.mjs';
+import { recordedConfigurationFold, recordedSessionConfiguration } from './session-recorded-config.mjs';
+import { claudeRuntimeFold } from './session-claude-runtime.mjs';
+import { withSessionRecords, sessionMetaFold } from './session-records.mjs';
 import { recordedLaunchAgent } from './session-launch-agent.mjs';
-import { recordedSessionUsage } from './session-usage.mjs';
+import { recordedSessionUsage, sessionUsageFold } from './session-usage.mjs';
 import { loadMachineSpend } from './session-spend.mjs';
 import { sessionResumeLaunch } from './session-resume-instructions.mjs';
 import { parseUsageSince, usageMoment } from './session-usage-time.mjs';
@@ -20,6 +22,7 @@ export const SESSION_READ_EVENT = 'harness.v1.sessions.event';
 export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true, usage: true, spend: true, resume_instructions: true });
 export { loadMachineSpend as loadSessionSpend };
 export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
+export { SESSION_UNREADABLE } from './session-file.mjs';
 export { stringifyNativeJsonPretty as prettySessionWire };
 const invalid = (message) => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
 const object = (value, name) => {
@@ -116,6 +119,25 @@ export async function loadRecordedSessionConfiguration(params, context = {}) {
   // LocatorParams ignores unrelated fields. This door always reads the full
   // lossless source, independent of any supplied display/load-view knobs.
   const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  const folded = await withSessionRecords(locator, async (source, records) => {
+    const fold = recordedConfigurationFold(), meta = sessionMetaFold(source, fold);
+    // The runtime fold takes every record's calls before any record: the file is read once more for it.
+    const runtime = source === 'claude_code' ? claudeRuntimeFold() : null;
+    let posture = runtime != null;
+    for await (const record of records()) {
+      meta.observe(record);
+      if (record.value === undefined) posture = false;
+      else if (posture) try { runtime.call(record.value, record.index + 1, null); } catch { posture = false; }
+    }
+    // Only the manifest's own refusal leaves the posture unknown: a read that fails fails the door.
+    if (posture) for await (const record of records()) {
+      try { runtime.record(record.value, record.index + 1, null); } catch { posture = false; break; }
+    }
+    let mode = null;
+    if (posture) try { mode = runtime.finish().posture.permission_mode; } catch { /* unsupported or malformed complete manifest */ }
+    return fold.finish(meta.meta, locator.harness, mode);
+  }, context);
+  if (folded != null) return folded.result;
   return recordedSessionConfiguration(await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true }), locator.harness);
 }
 
@@ -132,10 +154,19 @@ export async function loadSessionUsage(params, context = {}) {
   object(params, 'session usage params');
   const { locator } = parseSessionReadParams({ locator: params.locator }, context);
   const since = params.since == null ? null : parseUsageSince(string(params.since, 'since'));
-  // This door reads the complete lossless session, including child records,
-  // and ignores unrelated load/view options rather than applying a window.
-  const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
-  const answer = { harness: locator.harness, session_id: session.meta.session_id, usage: recordedSessionUsage(session, since) };
+  // This door reads every record of the session and ignores unrelated
+  // load/view options rather than applying a window.
+  const folded = await withSessionRecords(locator, async (source, records) => {
+    const meta = sessionMetaFold(source), usage = sessionUsageFold(source, since);
+    for await (const record of records()) { meta.observe(record); if (record.value !== undefined) usage.record(record.value, meta.meta.model); }
+    return { session_id: meta.meta.session_id, usage: usage.finish() };
+  }, context);
+  let recorded = folded?.result;
+  if (recorded == null) {
+    const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
+    recorded = { session_id: session.meta.session_id, usage: recordedSessionUsage(session, since) };
+  }
+  const answer = { harness: locator.harness, ...recorded };
   if (since != null) answer.since = usageMoment(since);
   return answer;
 }
@@ -148,6 +179,11 @@ export async function loadSessionResumeInstructions(params, context = {}) {
   if (!['default', 'yolo'].includes(policy)) invalid(`unknown resume policy: ${String(policy)}`);
   // Native admission loads the source even when cwd is explicit, and its
   // launch identity comes from the locator rather than a transcript header.
-  const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
-  return { launch: sessionResumeLaunch(locator.harness, locator.session_id, cwd ?? session.meta.cwd ?? '.', policy, context) };
+  const folded = await withSessionRecords(locator, async (source, records) => {
+    const meta = sessionMetaFold(source);
+    for await (const record of records()) meta.observe(record);
+    return meta.meta;
+  }, context);
+  const meta = folded?.result ?? (await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true })).meta;
+  return { launch: sessionResumeLaunch(locator.harness, locator.session_id, cwd ?? meta.cwd ?? '.', policy, context) };
 }

package/session-recorded-config.mjs

@@ -4,21 +4,36 @@ import { parseNativeJson, stringifyNativeJson, stringifyNativeJsonMember } from
 import { field } from './session-codec-utils.mjs';
 import { claudeRuntimeManifest } from './session-claude-runtime.mjs';
 
+const HEADER_KEYS = ['cwd', 'model', 'approval_policy', 'sandbox_policy'];
+
+/** Codex headers in recorded order, the last value of each key standing. */
+export function recordedConfigurationFold() {
+  let recorded = new Map();
+  return {
+    clear() { recorded = new Map(); },
+    header(header) {
+      const payload = field(header, 'payload') === undefined ? header : header.payload;
+      for (const key of HEADER_KEYS) if (field(payload, key) !== undefined) recorded.set(key, stringifyNativeJsonMember(payload, key));
+    },
+    // Member serialization preserves integer-versus-float facts and opaque
+    // policy values, including records whose values have unexpected JSON types.
+    finish(meta, harness, permissionMode = null) {
+      const values = new Map([
+        ['harness', stringifyNativeJson(harness)], ['session_id', stringifyNativeJson(meta.session_id)],
+        ['cwd', stringifyNativeJson(meta.cwd)], ['model', stringifyNativeJson(meta.model)],
+        ['approval_policy', 'null'], ['sandbox_policy', 'null'], ['permission_mode', stringifyNativeJson(permissionMode)],
+      ]);
+      for (const [key, value] of recorded) values.set(key, value);
+      return parseNativeJson(`{${[...values].map(([key, value]) => `${JSON.stringify(key)}:${value}`).join(',')}}`);
+    },
+  };
+}
+
 export function recordedSessionConfiguration(session, harness) {
-  const values = new Map([
-    ['harness', stringifyNativeJson(harness)], ['session_id', stringifyNativeJson(session.meta.session_id)],
-    ['cwd', stringifyNativeJson(session.meta.cwd)], ['model', stringifyNativeJson(session.meta.model)],
-    ['approval_policy', 'null'], ['sandbox_policy', 'null'], ['permission_mode', 'null'],
-  ]);
-  for (const header of session.meta.codex_headers) {
-    const payload = field(header, 'payload') === undefined ? header : header.payload;
-    for (const key of ['cwd', 'model', 'approval_policy', 'sandbox_policy']) {
-      if (field(payload, key) !== undefined) values.set(key, stringifyNativeJsonMember(payload, key));
-    }
-  }
-  try { values.set('permission_mode', stringifyNativeJson(claudeRuntimeManifest(session).posture.permission_mode)); }
+  const fold = recordedConfigurationFold();
+  for (const header of session.meta.codex_headers) fold.header(header);
+  let permissionMode = null;
+  try { permissionMode = claudeRuntimeManifest(session).posture.permission_mode; }
   catch { /* unsupported or malformed complete manifest leaves posture unknown */ }
-  // Member serialization preserves integer-versus-float facts and opaque
-  // policy values, including records whose values have unexpected JSON types.
-  return parseNativeJson(`{${[...values].map(([key, value]) => `${JSON.stringify(key)}:${value}`).join(',')}}`);
+  return fold.finish(session.meta, harness, permissionMode);
 }

package/session-records.mjs

@@ -0,0 +1,88 @@
+// A door that folds over a transcript's records reads them one at a time: the
+// file is never held as one buffer or one string, so its size bounds nothing.
+// Only a plain Claude Code or Codex JSONL file is read this way. Every other
+// thing a locator names answers null here and is loaded as its document.
+import { basename, dirname, extname, join } from 'node:path';
+import { withSessionFile } from './file-io.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { sessionFileLines } from './session-file.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { nativeTrim } from './text.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { createSession } from './session-model.mjs';
+import { sessionRecordSource } from './session-source.mjs';
+import { captureClaudeMeta } from './session-claude.mjs';
+import { captureCodexMeta } from './session-codex.mjs';
+import { restoreTopLevelResidue } from './session-native-residue.mjs';
+import { isCompressedSessionPath, looksLikeSessionSqlite, sessionTextError } from './session-path.mjs';
+
+async function* lines(reader) {
+  try { yield* sessionFileLines(reader); }
+  catch (error) { throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(reader.path, error) : error; }
+}
+
+/** The document reader tries the whole text as one JSON value before its
+ * lines. A first line that is no complete value may open such a document,
+ * so only a file whose first line parses is decided from its records. */
+async function recordedSource(reader) {
+  let first = true;
+  for await (const { text } of lines(reader)) {
+    const line = nativeTrim(text); if (line === '') continue;
+    let value; try { value = parseNativeJson(line); } catch { if (first) return null; continue; }
+    first = false;
+    const source = sessionRecordSource(value); if (source != null) return source;
+  }
+  return null;
+}
+
+/** Each non-blank line with its index among the file's lines: `value` is
+ * absent when the line is not JSON. Every call reads the file from its start. */
+async function* records(reader) {
+  let index = 0;
+  for await (const { text } of lines(reader)) {
+    const raw = text.endsWith('\n') ? text.slice(0, -1) : text, at = index++;
+    if (nativeTrim(raw) === '') continue;
+    let value; try { value = parseNativeJson(raw); } catch { /* malformed */ }
+    yield { index: at, raw, value };
+  }
+}
+
+/** `work(source, records)` over the transcript a locator names, or null when
+ * it is not a plain Claude Code or Codex JSONL file. */
+export async function withSessionRecords(locator, work, { 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 sourceStat(path))?.isFile() || await looksLikeSessionSqlite(path, metrics)) return null;
+  return (await withSessionFile(path, async (reader) => {
+    const source = await recordedSource(reader);
+    return ['claude_code', 'codex'].includes(source) ? { result: await work(source, () => records(reader)) } : null;
+  }, metrics)).result;
+}
+
+/** The header facts the document codecs keep in `meta`, from the same records
+ * in the same order. `headers` takes each Codex header as it stands, and is
+ * cleared when a restored provenance (in a record of either dialect)
+ * replaces those read before it. */
+export function sessionMetaFold(source, headers = null) {
+  const { meta } = createSession(source);
+  let restored = false, held = meta.codex_headers;
+  const replaced = () => {
+    if (meta.codex_headers === held) return;
+    held = meta.codex_headers; headers?.clear(); for (const header of held) headers?.header(header);
+  };
+  return {
+    meta,
+    observe({ raw, value }) {
+      if (source === 'claude_code') { if (value !== undefined) { captureClaudeMeta(value, meta, raw); replaced(); } return; }
+      // The Codex codec parses its trimmed line.
+      if (value === undefined) { try { value = parseNativeJson(nativeTrim(raw)); } catch { return; } }
+      const kind = stringField(value, 'type'), payload = field(value, 'payload');
+      if (!restored && kind === 'session_meta' && restoreTopLevelResidue(payload, meta)) { restored = true; replaced(); }
+      if (kind === 'session_meta') captureCodexMeta(payload, meta);
+      else if (kind === 'turn_context') meta.model ??= stringField(payload, 'model');
+      else return;
+      if (!restored) headers?.header(value);
+    },
+  };
+}

package/session-source.mjs

@@ -3,28 +3,45 @@ import { field, stringField } from './session-codec-utils.mjs';
 import { nonEmptyLines } from './session-lines.mjs';
 import { nativeTrim } from './text.mjs';
 
+function documentSource(document) {
+  if (Array.isArray(field(document, 'conversation')) && (field(document, 'working_dir') !== undefined || field(document, 'workingDir') !== undefined)) return 'goose';
+  if (field(document, 'info') !== undefined && Array.isArray(field(document, 'messages'))) return 'opencode';
+  return null;
+}
+
+/** `pi` is a session header: its file's body decides between Pi and OpenClaw. */
+function recordSource(value) {
+  if (Array.isArray(field(value, 'key')) && field(value, 'value') !== undefined) return 'opencode';
+  if (field(value, 'payload') !== undefined) return 'codex';
+  const kind = stringField(value, 'type');
+  if (stringField(value, 'sessionId') != null && ['projectHash', 'startTime', 'lastUpdated'].some((key) => field(value, key) !== undefined) && field(value, 'type') === undefined) return 'gemini';
+  if (kind === 'gemini' && field(value, 'content') !== undefined) return 'gemini';
+  if (['message', 'uuid', 'sessionId'].every((key) => field(value, key) === undefined) && ['system', 'user', 'assistant', 'tool_result', 'reasoning', 'backend_tool_call'].includes(kind) && ['content', 'tool_calls', 'tool_call_id', 'encrypted_content', 'kind'].some((key) => field(value, key) !== undefined)) return 'grok';
+  if (kind === 'session' && stringField(value, 'id') != null && field(value, 'message') === undefined && field(value, 'uuid') === undefined) return 'pi';
+  if (field(value, 'type') !== undefined || field(value, 'message') !== undefined) return 'claude_code';
+  return null;
+}
+
+/** The dialect one record proves when it is read apart from the rest of its
+ * file, a whole-document store's included; null when it proves none. */
+export const sessionRecordSource = (value) => documentSource(value) ?? recordSource(value);
+
 /** Source provenance is recovered structurally; discussing a harness never
  * selects its dialect. Corrupt lines are tolerated by the native detector. */
 export function detectSessionSource(text) {
   let document; try { document = parseNativeJson(nativeTrim(text)); } catch { /* JSONL is considered below. */ }
-  if (Array.isArray(field(document, 'conversation')) && (field(document, 'working_dir') !== undefined || field(document, 'workingDir') !== undefined)) return 'goose';
-  if (field(document, 'info') !== undefined && Array.isArray(field(document, 'messages'))) return 'opencode';
+  const whole = documentSource(document); if (whole != null) return whole;
   for (const line of nonEmptyLines(text)) {
     let value; try { value = parseNativeJson(line); } catch { continue; }
-    if (Array.isArray(field(value, 'key')) && field(value, 'value') !== undefined) return 'opencode';
-    if (field(value, 'payload') !== undefined) return 'codex';
-    const kind = stringField(value, 'type');
-    if (stringField(value, 'sessionId') != null && ['projectHash', 'startTime', 'lastUpdated'].some((key) => field(value, key) !== undefined) && field(value, 'type') === undefined) return 'gemini';
-    if (kind === 'gemini' && field(value, 'content') !== undefined) return 'gemini';
-    if (['message', 'uuid', 'sessionId'].every((key) => field(value, key) === undefined) && ['system', 'user', 'assistant', 'tool_result', 'reasoning', 'backend_tool_call'].includes(kind) && ['content', 'tool_calls', 'tool_call_id', 'encrypted_content', 'kind'].some((key) => field(value, key) !== undefined)) return 'grok';
-    if (kind === 'session' && stringField(value, 'id') != null && field(value, 'message') === undefined && field(value, 'uuid') === undefined) {
+    const source = recordSource(value);
+    if (source === 'pi') {
       for (const body of nonEmptyLines(text)) {
         let entry; try { entry = parseNativeJson(body); } catch { continue; }
         if ((stringField(entry, 'type') === 'leaf' && field(entry, 'targetId') !== undefined) || (stringField(entry, 'type') === 'message' && field(field(entry, 'message'), '__openclaw') !== undefined)) return 'openclaw';
       }
       return 'pi';
     }
-    if (field(value, 'type') !== undefined || field(value, 'message') !== undefined) return 'claude_code';
+    if (source != null) return source;
   }
   return null;
 }

package/session-usage.mjs

@@ -69,7 +69,10 @@ function* records(raw) {
   for (const line of raw) { let record; try { record = parseNativeJson(line); } catch { continue; } yield record; }
 }
 
-export function recordedSessionUsage(session, since = null) {
+/** A session's usage folded from its parsed records in recorded order.
+ * `model` is the session's recorded model where one is known by that record:
+ * a Codex count read before any model is priced once the first is recorded. */
+export function sessionUsageFold(source, since = null) {
   const days = new Map();
   const count = (record) => {
     if (since != null && (record.atMs == null || record.atMs < since)) return;
@@ -85,29 +88,41 @@ export function recordedSessionUsage(session, since = null) {
       sum.cost += cost * (record.fast ? rate[5] : 1) * (record.usOnly ? rate[6] : 1); sum.priced = true;
     }
   };
-  if (session.meta.source === 'claude_code') {
-    const responses = new Map();
-    for (const record of records(session.raw)) { const response = claudeUse(record); if (response) responses.set(...response); }
-    for (const id of [...responses.keys()].sort(sorted)) count(responses.get(id));
-  } else if (session.meta.source === 'codex') {
-    let model = session.meta.model ?? 'unknown', previous = [0n, 0n, 0n];
-    for (const record of records(session.raw)) {
+  const responses = new Map();
+  let turnModel = null, previous = [0n, 0n, 0n], unnamed = [];
+  const named = (model) => { for (const use of unnamed) count({ ...use, model }); unnamed = []; };
+  return {
+    record(record, model = null) {
+      if (source === 'claude_code') { const response = claudeUse(record); if (response) responses.set(...response); return; }
+      if (source !== 'codex') return;
+      if (model != null && unnamed.length) named(model);
       const payload = field(record, 'payload');
-      if (stringField(record, 'type') === 'turn_context') { model = stringField(payload, 'model') ?? model; continue; }
-      if (stringField(payload, 'type') !== 'token_count') continue;
-      const total = field(field(payload, 'info'), 'total_token_usage'); if (total === undefined) continue;
+      if (stringField(record, 'type') === 'turn_context') { turnModel = stringField(payload, 'model') ?? turnModel; return; }
+      if (stringField(payload, 'type') !== 'token_count') return;
+      const total = field(field(payload, 'info'), 'total_token_usage'); if (total === undefined) return;
       const now = ['input_tokens', 'output_tokens', 'cached_input_tokens'].map((key) => tokens(total, key));
-      if (now.every((n, i) => n === previous[i])) continue;
+      if (now.every((n, i) => n === previous[i])) return;
       const [input, output, cached] = now.map((n, i) => sub(n, previous[i])); previous = now;
-      count(recorded(record, model, [sub(input, cached), output, cached, 0n, 0n]));
-    }
-  }
-  return [...days.values()].sort((a, b) => sorted(a.day, b.day) || sorted(a.model, b.model)).map((sum) => {
-    const row = { at: `${sum.day}T00:00:00Z`, model: sum.model };
-    for (const [key, count] of [['input_tokens', sum.counts[0]], ['output_tokens', sum.counts[1]], ['cache_read_tokens', sum.counts[2]],
-      ['cache_write_tokens', wrap(sum.counts[3] + sum.counts[4])], ['cache_write_5m_tokens', sum.counts[3]], ['cache_write_1h_tokens', sum.counts[4]]]) setNativeInteger(row, key, count);
-    if (sum.priced) { row.cost = { currency: 'USD', source: 'rate_table' }; setNativeFloat(row.cost, 'amount', Math.round(sum.cost * 1e6) / 1e6); }
-    if (sum.unpriced) row.cost_unrecorded = true;
-    return row;
-  });
+      const use = recorded(record, turnModel ?? model, [sub(input, cached), output, cached, 0n, 0n]);
+      if (use.model == null) unnamed.push(use); else count(use);
+    },
+    finish() {
+      named('unknown');
+      for (const id of [...responses.keys()].sort(sorted)) count(responses.get(id));
+      return [...days.values()].sort((a, b) => sorted(a.day, b.day) || sorted(a.model, b.model)).map((sum) => {
+        const row = { at: `${sum.day}T00:00:00Z`, model: sum.model };
+        for (const [key, count] of [['input_tokens', sum.counts[0]], ['output_tokens', sum.counts[1]], ['cache_read_tokens', sum.counts[2]],
+          ['cache_write_tokens', wrap(sum.counts[3] + sum.counts[4])], ['cache_write_5m_tokens', sum.counts[3]], ['cache_write_1h_tokens', sum.counts[4]]]) setNativeInteger(row, key, count);
+        if (sum.priced) { row.cost = { currency: 'USD', source: 'rate_table' }; setNativeFloat(row.cost, 'amount', Math.round(sum.cost * 1e6) / 1e6); }
+        if (sum.unpriced) row.cost_unrecorded = true;
+        return row;
+      });
+    },
+  };
+}
+
+export function recordedSessionUsage(session, since = null) {
+  const fold = sessionUsageFold(session.meta.source, since);
+  for (const record of records(session.raw)) fold.record(record, session.meta.model);
+  return fold.finish();
 }