@volter/supercode-interchange 0.1.22 → 0.1.24

package/session-claude-runtime.d.ts

@@ -33,3 +33,31 @@ export interface ClaudeRuntimeManifest {
 }
 /** A pure strict fold. It never executes scheduled work or launches a child. */
 export function claudeRuntimeManifest(session: Session): ClaudeRuntimeManifest;
+
+/** One background agent of a Claude Code session, as its records say it (claudeBackgroundAgentFold). `running` means
+ * no notification has ended its latest run; whether its session still runs is the reader's to say. */
+export interface ClaudeBackgroundAgent {
+  /** The agent id Claude Code gave it (`toolUseResult.agentId`), which its notifications and `SendMessage` name. */
+  id: string;
+  /** The `Agent` call that launched it. */
+  tool_use_id: string;
+  description: string | null; agent_type: string | null;
+  state: 'running' | 'completed' | 'failed' | 'stopped';
+  /** The first lines of the latest run's notification `<summary>` and `<result>`. */
+  summary: string | null; result: string | null;
+  /** When its launch was recorded; `started_at` is its latest run's start (a resume's, when one resumed it). */
+  launched_at: string | null; started_at: string | null; finished_at: string | null;
+}
+export interface ClaudeTaskNotification {
+  task_ids: string[]; tool_use_id: string | null; status: string | null; summary: string | null; result: string | null;
+}
+export function claudeTaskNotifications(text: string): ClaudeTaskNotification[];
+export interface ClaudeBackgroundAgentFold {
+  observe(value: unknown, line: number): void;
+  clone(): ClaudeBackgroundAgentFold;
+  readonly retainedEntries: number;
+  /** Every running agent, then at most `settled` (default 20) that ended, the latest-started first. `also` is a fold of
+   * records not yet in this one (a line still being written), read beside it without copying either. */
+  finish(options?: { settled?: number; also?: ClaudeBackgroundAgentFold | null }): ClaudeBackgroundAgent[];
+}
+export function claudeBackgroundAgentFold(): ClaudeBackgroundAgentFold;

package/session-claude-runtime.mjs

@@ -151,18 +151,171 @@ function applyNotification({ notification: note, timestamp, line }, children) {
   child.finished_at = timestamp; child.summary = note.summary;
 }
 
+// ---- Background agents --------------------------------------------------------------------------------------------
+// Claude Code's background agents as its own records say them, for a reader that shows what the terminal shows under
+// its prompt. Lenient where the manifest is strict: an unrelated malformed record never hides an agent, and the facts
+// are joined only at `finish`, so the fold is the same whatever order the records arrive in.
+const NOTIFICATION_OPEN = '<task-notification>';
+const AGENT_TEXT = 200, AGENT_LINE = 300;
+const opens = text => typeof text === 'string' && text.trimStart().startsWith(NOTIFICATION_OPEN);
+const firstLine = (text, max = AGENT_LINE) => {
+  const line = typeof text === 'string' ? text.trim().split('\n', 1)[0].trim() : '';
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+const blockText = content => typeof content === 'string' ? content
+  : Array.isArray(content) ? content.filter(block => stringField(block, 'type') === 'text').map(block => stringField(block, 'text') ?? '').join('') : null;
+const allTags = (block, name) => [...block.matchAll(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`, 'g'))].map(match => nativeTrim(match[1])).filter(Boolean);
+/** Every task notification a text holds, each with all the tasks it names (an end-of-session summary names several). */
+export function claudeTaskNotifications(text) {
+  if (typeof text !== 'string' || !text.includes(NOTIFICATION_OPEN)) return [];
+  return [...text.matchAll(/<task-notification>([\s\S]*?)<\/task-notification>/g)].map(([, block]) => ({
+    task_ids: allTags(block, 'task-id'), tool_use_id: allTags(block, 'tool-use-id')[0] ?? null, status: allTags(block, 'status')[0] ?? null,
+    summary: firstLine(allTags(block, 'summary')[0]) || null, result: firstLine(allTags(block, 'result')[0]) || null,
+  }));
+}
+const agentState = status => status === 'completed' ? 'completed' : status === 'failed' || status === 'error' ? 'failed' : 'stopped';
+// A queue entry carries no stamp: only one that is notifications and nothing else is the runtime's own.
+const onlyNotifications = text => text.replace(/<task-notification>[\s\S]*?<\/task-notification>/g, '').trim() === '';
+const emptyAgentState = () => ({ launches: new Map(), sends: new Map(), results: new Map(), notes: [], queued: [] });
+
+/**
+ * Claude Code's background agents, folded from a transcript's records (`observe` each parsed record with its 1-based
+ * line, in any order; `finish` answers):
+ * - an `Agent` (or `Task`) call starts an agent when it asked `run_in_background` or its result is async
+ *   (`toolUseResult.isAsync`); the result's structured `agentId` names it;
+ * - a `SendMessage` whose result names the agent it resumed (`toolUseResult.resumedAgentId`) starts it again;
+ * - a task notification ends the run its `<tool-use-id>` names (else the agent's latest run before it), for every
+ *   `<task-id>` it lists: `completed`, `failed`, or `stopped` (killed, stopped, or not finished when the session
+ *   before it ended). Only the runtime's own notifications count: a user record Claude Code stamped
+ *   `origin.kind: task-notification`, a queued command of `commandMode: task-notification`, or a queue entry that is
+ *   notifications and nothing else, each naming by `<tool-use-id>` a run of the agent it names. A notification quoted
+ *   in a tool result or written in anyone's message is text, not an ending.
+ * Sidechain records (a subagent's own transcript lines) are not the session's. An agent whose latest run has no ending
+ * is `running` as far as the transcript knows; whether its session still runs is the reader's to say.
+ */
+// What the fold keeps is copied out of the record it was read from: a part cut from a record's text holds the whole
+// text in memory for as long as the part is kept, and the fold keeps its parts for as long as its transcript is read.
+const detach = value => typeof value === 'string' ? JSON.parse(JSON.stringify(value)) : Array.isArray(value) ? value.map(detach) : value;
+const owned = entry => Object.fromEntries(Object.entries(entry).map(([key, value]) => [key, detach(value)]));
+
+export function claudeBackgroundAgentFold(saved = null) {
+  const state = saved ?? emptyAgentState();
+  const notes = (text, at, line, into = state.notes) => { for (const note of claudeTaskNotifications(text)) into.push(owned({ ...note, at, line })); };
+  return {
+    get state() { return state; },
+    get retainedEntries() { return state.launches.size + state.sends.size + state.results.size + state.notes.length + state.queued.length; },
+    clone() {
+      return claudeBackgroundAgentFold({ launches: new Map(state.launches), sends: new Map(state.sends), results: new Map(state.results),
+        notes: [...state.notes], queued: [...state.queued] });
+    },
+    observe(value, line) {
+      if (field(value, 'isSidechain') === true) return;
+      const kind = stringField(value, 'type'), at = stringField(value, 'timestamp');
+      const content = field(field(value, 'message'), 'content');
+      if (kind === 'assistant' && Array.isArray(content)) {
+        for (const block of content) {
+          if (stringField(block, 'type') !== 'tool_use') continue;
+          const name = stringField(block, 'name'), id = stringField(block, 'id');
+          if (id == null || !['Agent', 'Task', 'SendMessage'].includes(name)) continue;
+          const input = field(block, 'input');
+          if (name === 'SendMessage') state.sends.set(detach(id), { line });
+          else state.launches.set(detach(id), owned({ description: firstLine(stringField(input, 'description'), AGENT_TEXT) || null,
+            agent_type: firstLine(stringField(input, 'subagent_type'), AGENT_TEXT) || null, background: bool(input, 'run_in_background'), at, line }));
+        }
+      } else if (kind === 'user') {
+        const results = Array.isArray(content) ? content.filter(block => stringField(block, 'type') === 'tool_result') : [];
+        if (results.length) {
+          // Each tool result's own structured result: the record's one, or its place in a list of them.
+          const native = field(value, 'toolUseResult');
+          results.forEach((block, index) => {
+            const id = stringField(block, 'tool_use_id'), own = Array.isArray(native) ? (native.length === results.length ? native[index] : null) : results.length === 1 ? native : null;
+            if (id == null || own == null || typeof own !== 'object') return;
+            const agentId = stringField(own, 'agentId'), resumed = stringField(own, 'resumedAgentId');
+            if (agentId != null || resumed != null || bool(own, 'isAsync'))
+              state.results.set(detach(id), owned({ agent_id: agentId, resumed, async: bool(own, 'isAsync'), error: bool(block, 'is_error'), at, line }));
+          });
+          return;
+        }
+        if (stringField(field(value, 'origin'), 'kind') === 'task-notification') notes(blockText(content), at, line);
+      } else if (kind === 'attachment') {
+        const attachment = field(value, 'attachment');
+        if (stringField(attachment, 'type') === 'queued_command' && stringField(attachment, 'commandMode') === 'task-notification')
+          notes(stringField(attachment, 'prompt'), at, line);
+      } else if (kind === 'queue-operation' && stringField(value, 'operation') === 'enqueue') {
+        const text = stringField(value, 'content');
+        if (opens(text) && onlyNotifications(text)) notes(text, at, line, state.queued);
+      }
+    },
+    /** The agents, the latest-started first: every one running, then at most `settled` that ended. `also` is a fold of
+     * records not yet in this one (a line still being written), read beside it without copying either. */
+    finish({ settled = 20, also = null } = {}) {
+      const states = also ? [state, also.state] : [state];
+      const each = function* (key) { for (const held of states) yield* held[key]; };
+      const results = id => states.map(held => held.results.get(id)).find(Boolean);
+      const agents = new Map(), runs = new Map();
+      for (const [call, launch] of each('launches')) {
+        const result = results(call);
+        if (!result || result.error || result.agent_id == null || !(launch.background || result.async)) continue;
+        const run = { call, line: result.line, started_at: launch.at ?? result.at, outcome: null, summary: null, result: null, finished_at: null };
+        const known = agents.get(result.agent_id);
+        if (known) { known.runs.push(run); runs.set(call, { agent: known, run }); continue; }
+        const agent = { id: result.agent_id, tool_use_id: call, description: launch.description, agent_type: launch.agent_type, launched_at: run.started_at, runs: [run] };
+        agents.set(agent.id, agent); runs.set(call, { agent, run });
+      }
+      for (const [call] of each('sends')) {
+        const result = results(call), agent = result?.resumed == null || result.error ? null : agents.get(result.resumed);
+        if (!agent) continue;
+        const run = { call, line: result.line, started_at: result.at, outcome: null, summary: null, result: null, finished_at: null };
+        agent.runs.push(run); runs.set(call, { agent, run });
+      }
+      for (const agent of agents.values()) agent.runs.sort((left, right) => left.line - right.line);
+      const all = [...[...each('notes')].map(note => ({ note, stamped: true })), ...[...each('queued')].map(note => ({ note, stamped: false }))]
+        .sort((left, right) => left.note.line - right.note.line);
+      for (const { note, stamped } of all) for (const task of note.task_ids) {
+        const agent = agents.get(task); if (!agent) continue;
+        const named = note.tool_use_id == null ? null : runs.get(note.tool_use_id);
+        // An unstamped queue entry counts only for a run of this agent it names.
+        if (!stamped && named?.agent !== agent) continue;
+        const run = named?.agent === agent ? named.run : agent.runs.findLast(candidate => candidate.line < note.line) ?? agent.runs.at(-1);
+        // The first notice of a run ends it; the same notice written again (queued, then delivered) changes nothing.
+        if (run.outcome) continue;
+        Object.assign(run, { outcome: agentState(note.status), summary: note.summary, result: note.result, finished_at: note.at });
+      }
+      const answer = [...agents.values()].map(agent => {
+        const latest = agent.runs.at(-1);
+        return { id: agent.id, tool_use_id: agent.tool_use_id, description: agent.description, agent_type: agent.agent_type,
+          state: latest.outcome ?? 'running', summary: latest.summary, result: latest.result, launched_at: agent.launched_at, started_at: latest.started_at,
+          finished_at: latest.finished_at, line: latest.line };
+      }).sort((left, right) => right.line - left.line);
+      const running = answer.filter(agent => agent.state === 'running'), ended = answer.filter(agent => agent.state !== 'running').slice(0, settled);
+      return [...running, ...ended].map(({ line: _line, ...agent }) => agent);
+    },
+  };
+}
+
 /** 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;
+export function claudeRuntimeFold(saved = null) {
+  const state = saved?.state ?? { crons: new Map(), pending: new Map(), children: new Map(), wakeups: new Map(), notifications: [], residue: [] };
+  const posture = saved?.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 = saved?.queue ?? { enqueued: 0, dequeued: 0, removed: 0, pending: [] };
+  let incoming = saved?.incoming ?? [], outgoing = saved?.outgoing ?? [];
+  let reported = saved?.reported ?? null;
+  let permissionChecked = saved?.permissionChecked ?? 0;
+  // The background agents ride the same records, leniently: a refusal of the manifest never loses them.
+  const agents = claudeBackgroundAgentFold(saved?.agents ?? null);
   return {
+    /** The session's background agents (claudeBackgroundAgentFold), from every record this fold has seen. */
+    backgroundAgents(options) { return agents.finish(options); },
+    // Runtime state contains strings, booleans, native big integers and maps,
+    // never decoded transcript objects. A snapshot's finish cannot consume the
+    // retained queue or apply its notifications twice on the next append.
+    get retainedEntries() { return agents.retainedEntries + state.crons.size + state.pending.size + state.children.size + state.wakeups.size + state.notifications.length + state.residue.length + incoming.length + outgoing.length; },
+    clone() { return claudeRuntimeFold(structuredClone({ state, posture, queue, incoming, outgoing, reported, permissionChecked, agents: agents.state })); },
     call(value, line, raw) { if (stringField(value, 'type') === 'assistant') assistantCalls(value, line, raw, state); },
     record(value, line, raw) {
+      agents.observe(value, line);
       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;
       }
@@ -191,6 +344,18 @@ export function claudeRuntimeFold() {
         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);
     },
+    // Finishing the manifest changes child summaries and materializes queue
+    // output, but none of those changes affects the permission reading. Its
+    // only deferred refusal is a notification with neither reference id.
+    // Validate new notifications once without consuming retained fold state.
+    permissionMode() {
+      for (; permissionChecked < state.notifications.length; permissionChecked++) {
+        const { notification: note, line } = state.notifications[permissionChecked];
+        if (note.tool_use_id == null && note.task_id == null)
+          fail(`malformed Claude task notification at line ${line}: missing tool-use-id and task-id`);
+      }
+      return posture.permission_mode;
+    },
     finish() {
       for (const notification of state.notifications) applyNotification(notification, state.children);
       queue.pending = outgoing.reverse().concat(incoming);

package/session-claude-scan-store.mjs

@@ -0,0 +1,164 @@
+// What a Claude Code transcript's scan knows of each of its records, kept on disk rather than in the process: one
+// SQLite file per scan, private to this process (a directory under the system's temporary directory, removed when the
+// process exits, swept by the next process when it did not; a scan let go removes its own). The scan holds in memory only what its next read replays (the tail
+// after its settled prefix) and the facts that do not grow with the transcript; everything per record, per message
+// and per group is read from here when a read needs it.
+import { DatabaseSync } from 'node:sqlite';
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { threadId } from 'node:worker_threads';
+import { parseNativeJson, stringifyNativeJson } from './native-json.mjs';
+
+// A scan directory is named for the process and the thread that made it: `supercode-claude-scans-<pid>-<thread>-…`.
+const SCANS = /^supercode-claude-scans-(\d+)-(\d+)-/;
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+
+/**
+ * The scan directories of processes and threads that are gone, removed: every one whose process no longer runs (a
+ * process killed, aborted or crashed leaves its directory), or, named, those of one thread of this process (a reader
+ * worker stopped without running its exit hooks: its owner removes them, `session-read-client.mjs`).
+ */
+export function sweepScanDirectories({ thread = null } = {}) {
+  let names = [];
+  try { names = readdirSync(tmpdir()); } catch { return; }
+  for (const name of names) {
+    const owner = SCANS.exec(name);
+    if (!owner) continue;
+    const pid = Number(owner[1]), of = Number(owner[2]);
+    if (thread == null ? alive(pid) : pid !== process.pid || of !== thread) continue;
+    try { rmSync(join(tmpdir(), name), { recursive: true, force: true }); } catch { /* another sweep took it */ }
+  }
+}
+
+let directory = null;
+function storeDirectory() {
+  if (directory != null) return directory;
+  sweepScanDirectories();
+  directory = mkdtempSync(join(tmpdir(), `supercode-claude-scans-${process.pid}-${threadId}-`));
+  process.once('exit', () => { try { rmSync(directory, { recursive: true, force: true }); } catch { /* the next sweep takes it */ } });
+  return directory;
+}
+
+const SCHEMA = `
+  PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA locking_mode=EXCLUSIVE; PRAGMA temp_store=FILE; PRAGMA cache_size=-1024;
+  CREATE TABLE records(line INTEGER PRIMARY KEY, offset INTEGER NOT NULL, length INTEGER NOT NULL, assistant INTEGER NOT NULL,
+    error INTEGER NOT NULL, message_id TEXT, hash TEXT NOT NULL) STRICT;
+  CREATE TABLE nodes(line INTEGER PRIMARY KEY, uuid TEXT NOT NULL UNIQUE, kind TEXT NOT NULL, parent TEXT, sidechain INTEGER NOT NULL,
+    message_id TEXT, tool_result INTEGER NOT NULL, compact TEXT) STRICT;
+  CREATE TABLE first_lines(message_id TEXT PRIMARY KEY, line INTEGER NOT NULL) STRICT, WITHOUT ROWID;
+  CREATE TABLE residue(line INTEGER PRIMARY KEY, offset INTEGER NOT NULL, length INTEGER NOT NULL, entry TEXT NOT NULL) STRICT;
+  CREATE TABLE made(mark TEXT PRIMARY KEY, body TEXT NOT NULL) STRICT, WITHOUT ROWID;
+  CREATE TABLE positions(position INTEGER PRIMARY KEY, grp INTEGER NOT NULL, ordinal INTEGER NOT NULL, mark TEXT NOT NULL, synthetic TEXT) STRICT;
+  CREATE TABLE groups(grp INTEGER PRIMARY KEY, lines TEXT NOT NULL, size INTEGER NOT NULL) STRICT;
+  CREATE TABLE tools(id TEXT PRIMARY KEY, call INTEGER NOT NULL, result INTEGER NOT NULL) STRICT, WITHOUT ROWID;`;
+
+/** A duplicate uuid, as the replay graph names it (ClaudeReplayIndex.observe). */
+const duplicate = (uuid) => Object.assign(new Error(`cannot reconstruct lossless Claude continuation: duplicate uuid \`${uuid}\` in Claude transcript`), { code: 'invalid_session' });
+
+export class ScanStore {
+  constructor() {
+    this.path = join(storeDirectory(), `${randomUUID()}.sqlite`);
+    this.db = new DatabaseSync(this.path);
+    this.db.exec(SCHEMA);
+    const prepare = (sql) => this.db.prepare(sql);
+    this.statements = {
+      record: prepare('INSERT INTO records VALUES (?,?,?,?,?,?,?)'),
+      recordAt: prepare('SELECT offset,length,assistant,error,message_id,hash FROM records WHERE line=?'),
+      records: prepare('SELECT line,offset,length,assistant,error,message_id,hash FROM records ORDER BY line'),
+      node: prepare('INSERT INTO nodes VALUES (?,?,?,?,?,?,?,?)'),
+      nodeByUuid: prepare('SELECT line FROM nodes WHERE uuid=?'),
+      nodeLine: prepare('SELECT line,parent FROM nodes WHERE uuid=?'),
+      nodes: prepare('SELECT line,uuid,kind,parent,sidechain,message_id,tool_result,compact FROM nodes ORDER BY line'),
+      firstLine: prepare('INSERT OR IGNORE INTO first_lines VALUES (?,?)'),
+      firstLineOf: prepare('SELECT line FROM first_lines WHERE message_id=?'),
+      residue: prepare('INSERT INTO residue VALUES (?,?,?,?)'),
+      residues: prepare('SELECT line,offset,length,entry FROM residue ORDER BY line'),
+      residueCount: prepare('SELECT count(*) AS count FROM residue'),
+      made: prepare('INSERT OR REPLACE INTO made VALUES (?,?)'),
+      madeOf: prepare('SELECT body FROM made WHERE mark=?'),
+      position: prepare('INSERT INTO positions VALUES (?,?,?,?,?)'),
+      positionAt: prepare('SELECT grp,ordinal,mark,synthetic FROM positions WHERE position=?'),
+      marksFrom: prepare('SELECT mark FROM positions WHERE position>=? AND position<? ORDER BY position'),
+      group: prepare('INSERT INTO groups VALUES (?,?,?)'),
+      groupAt: prepare('SELECT lines,size FROM groups WHERE grp=?'),
+      tool: prepare('INSERT INTO tools VALUES (?,?,?) ON CONFLICT(id) DO UPDATE SET call=max(call,excluded.call),result=max(result,excluded.result)'),
+      toolOf: prepare('SELECT call,result FROM tools WHERE id=?'),
+    };
+    this.depth = 0;
+  }
+
+  /** A transaction across a pass's awaited reads: `end` commits it, or rolls it back when the pass failed. */
+  begin() { if (this.depth++ === 0) this.db.exec('BEGIN'); }
+  end(failed) { if (--this.depth === 0) this.db.exec(failed ? 'ROLLBACK' : 'COMMIT'); }
+
+  /** `work` in one transaction (nested calls join the outer one). */
+  batch(work) {
+    if (this.depth++ === 0) this.db.exec('BEGIN');
+    let failed = false;
+    try { return work(); } catch (error) { failed = true; throw error; }
+    finally { if (--this.depth === 0) this.db.exec(failed ? 'ROLLBACK' : 'COMMIT'); }
+  }
+
+  addRecord(line, facts) {
+    this.statements.record.run(line, facts.offset, facts.length, facts.assistant ? 1 : 0, facts.error ? 1 : 0, facts.messageId ?? null, facts.hash);
+    if (facts.assistant && facts.messageId != null) this.statements.firstLine.run(facts.messageId, line);
+  }
+  recordAt(line) {
+    const row = this.statements.recordAt.get(line);
+    return row == null ? undefined : { offset: row.offset, length: row.length, assistant: row.assistant === 1, error: row.error === 1, messageId: row.message_id, hash: row.hash };
+  }
+  /** Every record, by line: what a whole replay reads. */
+  allRecords() {
+    const records = new Map();
+    for (const row of this.statements.records.iterate()) records.set(row.line, { offset: row.offset, length: row.length, assistant: row.assistant === 1, error: row.error === 1, messageId: row.message_id, hash: row.hash });
+    return records;
+  }
+  addNode(node) {
+    try { this.statements.node.run(node.lineIndex, node.uuid, node.kind, node.parent ?? null, node.sidechain ? 1 : 0, node.messageId ?? null, node.toolResult ? 1 : 0, node.compact == null ? null : JSON.stringify(node.compact)); }
+    catch (error) { if (/UNIQUE/.test(error.message)) throw duplicate(node.uuid); throw error; }
+  }
+  hasUuid(uuid) { return this.statements.nodeByUuid.get(uuid) != null; }
+  /** The line of the record `uuid` names, and its parent's uuid, or null. */
+  nodeOf(uuid) { const row = this.statements.nodeLine.get(uuid); return row == null ? null : { line: row.line, parent: row.parent }; }
+  /** Every replayed node, by line: what a whole replay's graph is built from. */
+  *allNodes() {
+    for (const row of this.statements.nodes.iterate()) {
+      yield { lineIndex: row.line, uuid: row.uuid, kind: row.kind, parent: row.parent, sidechain: row.sidechain === 1, messageId: row.message_id,
+        toolResult: row.tool_result === 1, compact: row.compact == null ? null : JSON.parse(row.compact) };
+    }
+  }
+  firstLineOf(messageId) { return this.statements.firstLineOf.get(messageId)?.line; }
+  addResidue(line, offset, length, entry) { this.statements.residue.run(line, offset, length, stringifyNativeJson(entry)); }
+  *residues() { for (const row of this.statements.residues.iterate()) yield [row.line, { entry: parseNativeJson(row.entry), offset: row.offset, length: row.length }]; }
+  get residueCount() { return this.statements.residueCount.get().count; }
+
+  /** A group's decoded skeletons, kept by the group's mark. */
+  addMade(mark, decoded) { this.statements.made.run(mark, stringifyNativeJson(decoded)); }
+  madeOf(mark) {
+    const row = this.statements.madeOf.get(mark);
+    if (row == null) return undefined;
+    // a skeleton's metadata is a null-prototype object, as decoding leaves it
+    return parseNativeJson(row.body).map(({ model, message }) => ({ model, message: { ...message, metadata: Object.create(null) } }));
+  }
+
+  /** The settled prefix: each message's place (its group and its place in it, or the message itself), its mark, each
+   * group's records and size, and the tool calls made and answered. */
+  clearSettled() { this.db.exec('DELETE FROM positions; DELETE FROM groups; DELETE FROM tools;'); }
+  addPosition(position, group, ordinal, mark, synthetic) { this.statements.position.run(position, group, ordinal, mark, synthetic == null ? null : stringifyNativeJson(synthetic)); }
+  positionAt(position) {
+    const row = this.statements.positionAt.get(position);
+    return { group: row.grp, ordinal: row.ordinal, mark: row.mark, synthetic: row.synthetic == null ? null : parseNativeJson(row.synthetic) };
+  }
+  *marksFrom(from, to) { for (const row of this.statements.marksFrom.iterate(from, to)) yield row.mark; }
+  addGroup(group, lines, size) { this.statements.group.run(group, JSON.stringify(lines), size); }
+  groupAt(group) { const row = this.statements.groupAt.get(group); return { lines: JSON.parse(row.lines), size: row.size }; }
+  addTool(id, call, result) { this.statements.tool.run(id, call ? 1 : 0, result ? 1 : 0); }
+  tool(id) { const row = this.statements.toolOf.get(id); return row == null ? null : { call: row.call === 1, result: row.result === 1 }; }
+
+  close() {
+    try { this.db.close(); } catch { /* already closed */ }
+    try { rmSync(this.path, { force: true }); } catch { /* the directory goes with the process */ }
+  }
+}

package/session-claude.mjs

@@ -12,6 +12,15 @@ export function captureClaudeMeta(value, meta, rawLine) {
   meta.session_id ??= stringField(value, 'sessionId');
   meta.cwd ??= stringField(value, 'cwd');
   meta.model ??= stringField(field(value, 'message'), 'model');
+  // The native API-error assistant is deliberately absent from normalized
+  // conversation messages. Retain its bounded outcome separately: a live
+  // terminal is not evidence that its first request could run.
+  if (meta.first_response == null && stringField(value, 'type') === 'assistant' && field(value, 'isSidechain') === false
+    && stringField(value, 'sessionId') === meta.session_id) {
+    const failed = field(value, 'isApiErrorMessage') === true, code = stringField(value, 'error');
+    meta.first_response = { outcome: failed ? 'error' : 'response', at: stringField(value, 'timestamp'),
+      record_id: stringField(value, 'uuid'), error_code: failed && /^[a-z][a-z0-9_]{0,79}$/.test(code ?? '') ? code : null };
+  }
   if (stringField(value, 'type') === 'fork-context-ref' && !Object.hasOwn(meta.lineage, 'claude_fork_context_ref_raw')) meta.lineage.claude_fork_context_ref_raw = rawLine;
 }
 

package/session-codex-activity.d.ts

@@ -0,0 +1,6 @@
+export type CodexActivityStatus = 'running' | 'idle' | 'busy' | 'waiting';
+export class CodexLifecycleCursor {
+  read(path: string): 'busy' | 'idle' | null;
+  turnStart(): { trigger: string | null; started_at_ms: number | null } | null;
+}
+export function reconcileCodexOwnership(previous: Iterable<string>, observed: Iterable<string>, misses: Map<string, number>): string[];

package/session-codex-activity.mjs

@@ -0,0 +1,120 @@
+// Incremental Codex lifecycle evidence. A cursor owns no process or file:
+// every sample opens its named rollout read-only and closes it before return.
+// A kept cursor reads only what was appended since its last sample, and answers
+// what a fresh scan of the whole file answers: its offset stops at the end of the
+// last complete line, so a record still being written is read whole next time; a
+// replaced file (another identity) or one shorter than, or rewritten before, the
+// offset is scanned again from its start.
+import { openSync, fstatSync, readSync, closeSync } from 'node:fs';
+import { parseNativeJson, nativeInteger, setNativeInteger, cloneNativeJson } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+
+const BLOCK_BYTES = 1024n * 1024n, OVERLAP_BYTES = 64n * 1024n, TAIL_BYTES = 64n * 1024n, MARK_BYTES = 64n;
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const boundaries = ['"type":"task_started"', '"type":"task_complete"', '"type":"turn_aborted"'];
+
+function lifecycleInTail(bytes, startsAtBoundary) {
+  const newline = bytes.indexOf(10), offset = startsAtBoundary ? 0 : newline < 0 ? bytes.length : newline + 1;
+  let text; try { text = decoder.decode(bytes.subarray(offset)); } catch { return null; }
+  let searchEnd = text.length;
+  while (searchEnd > 0) {
+    const before = text.slice(0, searchEnd), candidate = Math.max(...boundaries.map(boundary => before.lastIndexOf(boundary)));
+    if (candidate < 0) break;
+    const start = text.lastIndexOf('\n', candidate) + 1, next = text.indexOf('\n', candidate), end = next < 0 ? text.length : next;
+    try {
+      const event = parseNativeJson(text.slice(start, end));
+      if (stringField(event, 'type') === 'event_msg') {
+        const payload = field(event, 'payload'), kind = stringField(payload, 'type');
+        if (kind === 'task_started') {
+          const turn = { trigger: stringField(field(payload, 'turn_attribution'), 'turn_trigger'), started_at_ms: null };
+          const seconds = nativeInteger(payload, 'started_at');
+          if (seconds != null && seconds <= 0xffffffffffffffffn / 1000n) setNativeInteger(turn, 'started_at_ms', seconds * 1000n);
+          return { status: 'busy', turn };
+        }
+        if (kind === 'task_complete' || kind === 'turn_aborted') return { status: 'idle', turn: null };
+      }
+    } catch { /* malformed candidates establish no lifecycle boundary */ }
+    searchEnd = candidate;
+  }
+  return null;
+}
+
+function readExact(fd, bytes, position) {
+  let read = 0;
+  while (read < bytes.length) {
+    const count = readSync(fd, bytes, read, bytes.length - read, position + BigInt(read));
+    // a file cut short under the read establishes nothing this sample
+    if (!count) throw new Error('rollout ended before its stated length');
+    read += count;
+  }
+  return bytes;
+}
+
+function latestBetween(fd, floor, upper) {
+  let end = upper;
+  while (end > floor) {
+    const start = end - floor > BLOCK_BYTES ? end - BLOCK_BYTES : floor;
+    const status = lifecycleInTail(readExact(fd, Buffer.alloc(Number(end - start)), start), start === floor);
+    if (status != null) return status;
+    if (start === floor) break;
+    end = start + OVERLAP_BYTES;
+  }
+  return null;
+}
+
+/** The end of the last complete line in [floor, upper), or `floor` when it holds none. */
+function completeEnd(fd, floor, upper) {
+  let end = upper;
+  while (end > floor) {
+    const start = end - floor > TAIL_BYTES ? end - TAIL_BYTES : floor, bytes = readExact(fd, Buffer.alloc(Number(end - start)), start);
+    const newline = bytes.lastIndexOf(10);
+    if (newline >= 0) return start + BigInt(newline) + 1n;
+    end = start;
+  }
+  return floor;
+}
+
+/** Keep a proven boundary through appends without re-reading earlier records. */
+export class CodexLifecycleCursor {
+  #identity = null; #offset = 0n; #mark = null; #status = null; #turn = null; #tail = null;
+  #reset() { this.#offset = 0n; this.#mark = null; this.#status = null; this.#turn = null; }
+  /** The latest boundary's open turn, from the same incremental read. */
+  turnStart() { return cloneNativeJson(this.#tail ? this.#tail.turn : this.#turn); }
+  read(path) {
+    let fd;
+    try {
+      fd = openSync(path, 'r'); const stat = fstatSync(fd, { bigint: true }), length = stat.size, identity = `${stat.dev}:${stat.ino}`;
+      if (identity !== this.#identity || length < this.#offset) { this.#reset(); this.#identity = identity; }
+      // the bytes just before the offset, read again: a file rewritten in place (same identity, as long or longer) differs there
+      if (this.#mark != null && !readExact(fd, Buffer.alloc(this.#mark.length), this.#offset - BigInt(this.#mark.length)).equals(this.#mark)) this.#reset();
+      this.#tail = null;
+      if (length > this.#offset) {
+        const complete = completeEnd(fd, this.#offset, length);
+        const found = complete > this.#offset ? latestBetween(fd, this.#offset, complete) : null;
+        // a line not yet ended is read with the next sample too: its boundary answers this one but is not kept
+        const tail = complete < length ? lifecycleInTail(readExact(fd, Buffer.alloc(Number(length - complete)), complete), true) : null;
+        if (found != null) { this.#status = found.status; this.#turn = found.turn; }
+        if (complete > this.#offset) {
+          const kept = complete < MARK_BYTES ? complete : MARK_BYTES;
+          this.#mark = readExact(fd, Buffer.alloc(Number(kept)), complete - kept); this.#offset = complete;
+        }
+        this.#tail = tail;
+      }
+      return this.#tail ? this.#tail.status : this.#status;
+    } catch { this.#tail = null; return null; }
+    finally { if (fd != null) { try { closeSync(fd); } catch { /* the cursor keeps no descriptor */ } } }
+  }
+}
+
+/** One missed process snapshot retains ownership; the second retires it. */
+export function reconcileCodexOwnership(previous, observed, misses) {
+  const current = new Set(observed), before = new Set(previous), retained = new Set(current);
+  for (const path of current) misses.delete(path);
+  for (const path of before) {
+    if (current.has(path)) continue;
+    const count = Math.min(255, (misses.get(path) ?? 0) + 1);
+    if (count < 2) { misses.set(path, count); retained.add(path); } else misses.delete(path);
+  }
+  for (const path of misses.keys()) if (!before.has(path) || current.has(path)) misses.delete(path);
+  return [...retained].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+}

package/session-codex-window.mjs

@@ -11,6 +11,7 @@ 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';
+import { MARK_CHECKPOINT, chainMark, markedFrom } from './session-claude-index.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
@@ -129,7 +130,7 @@ class CodexDisplayScan extends AppendScan {
     }
     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.#take(this.state, line, reader); this.took(line.bytes, line.offset + line.length); this.bytes = line.offset + line.length;
     }
     await this.settle(reader, from);
   }
@@ -168,15 +169,34 @@ async function scanOf(path, reader, anchor, first) {
   return scan;
 }
 
+/** The marks a read lists after the first place the reader's (`known`) may differ: all of them when it names none. */
+function listed(marks, known) {
+  const from = known == null ? 0 : markedFrom(markChainOf(marks), known);
+  return { marks_from: from, tail_marks: from ? marks.slice(from) : marks };
+}
+
+/** A read's marks as their chain (chainMark), for markedFrom: how many, and the digest of the first `count`. */
+function markChainOf(marks) {
+  const checkpoints = []; let digest = '';
+  for (let at = 0; at < marks.length; at++) { digest = chainMark(digest, marks[at]); if ((at + 1) % MARK_CHECKPOINT === 0) checkpoints.push(digest); }
+  return { total: marks.length, digestAt(count) {
+    let at = Math.floor(count / MARK_CHECKPOINT) * MARK_CHECKPOINT, chain = at ? checkpoints[at / MARK_CHECKPOINT - 1] : '';
+    for (; at < count; at++) chain = chainMark(chain, marks[at]);
+    return chain;
+  } };
+}
+
 /**
  * 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
+ * mark and, when `marks` is asked, the marks after the first place where those the reader holds (`known`, as
+ * loadClaudeRecordWindow names them) differ from these: `marks_from` and `tail_marks` (from the first when nothing is
+ * named), so a pass over a long rollout lists what changed, not every message. 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 } = {}) {
+export async function loadCodexRecordWindow(locator, anchor, { from, bytes = null, messages = null, marks = false, known = null }, { 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;
@@ -206,7 +226,7 @@ export async function loadCodexRecordWindow(locator, anchor, { from, bytes = nul
       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 } : {}) } } };
+        window: { offset, returned: end - offset, total_messages: total, marks: view.marks.slice(offset, end), ...(marks ? listed(view.marks, known) : {}) } } };
     } catch (error) { scans.delete(path); throw error; }
   }, metrics)).result;
 }