memhouse 0.18.12 → 0.20.1

package/editors/normalise/devin.js

@@ -0,0 +1,575 @@
+'use strict';
+// v4 wave 2: Devin Local → normalised session log records (docs/design/sessions-log.md).
+//
+// Devin Local is the Rust CLI (`devin acp`) that Devin Desktop (the Windsurf app) runs over ACP. It
+// keeps its sessions in ~/.local/share/devin/cli/sessions.db: a second store of harness `devin`, with
+// harness_path = resolveNative(<home>/.local/share/devin/cli). dataFolder('devin') is Devin Desktop's
+// app-support folder, which stays on the 0.18 bridge as a separate store of the same harness.
+// Spec: the Windsurf / Devin section of docs/design/editor-shapes.md (repository),
+// fixtures misc/fixtures/editors/windsurf-devin/; sessions-model v0 §1, §2, §4 and its annex (devin).
+// The tree rules below were checked read-only against a lab store (5 sessions, 1,028 nodes).
+//
+// Store (SQLite, WAL):
+//   - sessions(id = a two-word slug, working_directory, title, created_at (s), main_chain_id, hidden);
+//   - message_nodes(node_id, parent_node_id, chat_message JSON, metadata JSON): a node tree.
+//     chat_message = {message_id, role, content, tool_calls[{id, name, arguments}], tool_call_id,
+//     thinking{thinking, signature}, images[], metadata{created_at (RFC 3339), generation_model,
+//     finish_reason, metrics, extensions, telemetry}};
+//   - tool_call_state(tool_call_id, tool_call_update_json): the final ACP status of each call.
+//
+// Rules:
+// - every turn deletes and re-inserts all of the session's nodes, so row_id and the row's created_at
+//   are useless. A message is chat_message.message_id; its ts is chat_message.metadata.created_at;
+// - the current line is the chain from sessions.main_chain_id up the parent_node_id pointers. Each
+//   message_id is emitted once: streaming twins (two sibling nodes, the chain through the second) and
+//   prefix copies (`compact/prior_node_ids`: the chain re-rooted under a new system prefix, at the
+//   first turns and on every mode switch) repeat it. Order is the walk, root first;
+// - left out: the system prefix (node metadata `is_system_prefix`: the system prompt, the sub-agent
+//   profiles, the Ask/Plan mode prompts), cache keepalive "continue" nodes (telemetry source
+//   cache_keepalive), and tool nodes, which are folded into their call;
+// - injected context on the line (system_info, rules, skills, editor context, mode transitions,
+//   user-edit reports, the compaction continuation) is a system message, source 'injected', hidden.
+//   "[Response interrupted by user]" is a visible notice, and the reply before it is `interrupted`;
+// - tool parts: call_id = tool_calls[].id = the tool node's tool_call_id. The tool node's content is
+//   the output; its chisel/tool_result_meta, chisel/tool_failure and the tool_call_state update give
+//   the status: rejected → denied, canceled → cancelled, failed → error, else completed (a non-zero
+//   exit stays completed, with is_error false and exit_code from chisel/terminal_output);
+// - sub-agents live in the same tree: the parent's tool result names subagent/agent_id and
+//   subagent/chain_node_id. Their chain follows the calling message, with agent_id set; the task
+//   prompt is source 'automated';
+// - compaction: a node on the line with `summarized_from: X` continues a compacted history. The chain
+//   ending at X comes first (so the log only appends), then a compaction lifecycle record, then the
+//   compactor's reply (the assistant node with summarized_from X, kept off the line) as a summary
+//   part replacing through X's message. The continuation node stays as injected context;
+// - revert moves main_chain_id back and the abandoned branch stays in the table. Only the line is
+//   emitted: messages that leave it vanish (the engine keeps them as removed). Each abandoned subtree
+//   still in the store (an edit is a revert plus a new branch) gives a `rewind` lifecycle record
+//   after the message it hangs off: message_ids = its messages, through = that message, at = null
+//   (the store keeps no revert time);
+// - held back: the tail of the line while a tool call has no result, and a tail reply with no
+//   finish_reason (streaming). A later node releases it; a call that never got a result is
+//   `interrupted`;
+// - usage: chat_message.metadata.metrics per reply, basis unknown (the fixtures fit net, nothing
+//   establishes it). Model: generation_model per message. No effort, no cost. The session-level
+//   sessions.metadata total_credit_cost / total_acu_cost are running totals the turn path writes
+//   (a session saved before its first turn has none; seen on a test machine), so they would change the session
+//   record every turn: no usage_total;
+// - user text: `content` is what the model saw (a slash skill's expanded body, an image placeholder
+//   before the prompt). What the user typed, kept apart in chisel/acp-content-blocks, is the text
+//   part's display_text when it differs. An image's model-written caption is the file part's caption;
+// - sessions: hidden=1 (the summary agent a fork spawns, cwd /) gets kind 'hidden', and its prompts
+//   are source 'automated'. Slugs: reuse is undetectable, incarnation ''. A fork copies the chain with
+//   the same ids and names no origin, so there is no explicit link. Archive state lives in Devin
+//   Desktop's globalStorage, not here: archived null. agent_mode, last_activity_at: volatile, left out;
+// - redaction by field path: only the projection above is read. tool_call_state.tool_call_json
+//   (rawInput), sessions.cogs_json and metadata, chisel/undo (original file content) and
+//   chisel/conversation_history are never selected or emitted; image bytes become a sha and a
+//   length; a reasoning signature becomes signature_len. No auth store is opened;
+// - list(): one entry per sessions row. The DB is shared by every session, so the entry names it
+//   relative to harness_path (db_rel) and carries a per-session change key read in the list query:
+//   main_chain_id (moves on every save that grows the line, and back on a revert), max(node_id) and
+//   the node count (every new node: a turn, a tool result, a mode-switch copy, a compactor or
+//   sub-agent chain; nodes keep their ids when re-inserted), count(*) and max(rowid) of the session's
+//   tool_call_state and subagent_heads rows, hidden, and a hash of the title (a rename or
+//   auto-retitle changes the session record). Nothing volatile (last_activity_at, the
+//   credit totals). normalise() is deterministic and works from the entry alone;
+// - reading: openReadOnly (editors/sqlite.js), which never creates -wal/-shm, then one read
+//   transaction for a consistent snapshot. A pointer that dangles (in the main chain, a compacted
+//   history or a sub-agent chain) means a torn read: normalise returns null and the pass skips. Every other error throws (module contract): a busy or locked
+//   store, a damaged page, a JSON column that does not parse; list() throwing keeps the runner's
+//   index. Only a missing table or column reads as empty.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { openReadOnly, textOf } = require('../sqlite');
+const harnessPaths = require('../harness-paths');
+
+const HARNESS = 'devin';
+const DB_FILE = 'sessions.db';
+const INTERRUPTED = /^\s*\[Response interrupted by user\]\s*$/;
+
+/** Devin Local's store folder. Not dataFolder('devin'): that is Devin Desktop's. */
+function storeRootDefault(home = os.homedir()) {
+  return path.join(home, '.local', 'share', 'devin', 'cli');
+}
+
+// The per-session change key, in the list query itself; every subquery SEARCHes a session index
+// (the test checks the plan). Every change normalise() can emit moves one of these columns:
+// message_nodes for the conversation, tool_call_state for a call's final status (count, max(rowid),
+// and the bytes of the final updates, which an in-place UPDATE changes), subagent_heads for a
+// sub-agent's head. A table an older store lacks reads as null.
+function listSql(tables) {
+  const agg = (t, alias) => (tables.has(t)
+    ? `(SELECT count(*) FROM ${t} x WHERE x.session_id = s.id) AS ${alias}_count, (SELECT max(x.rowid) FROM ${t} x WHERE x.session_id = s.id) AS ${alias}_max_rowid`
+    : `NULL AS ${alias}_count, NULL AS ${alias}_max_rowid`);
+  const bytes = tables.has('tool_call_state')
+    ? '(SELECT sum(octet_length(x.tool_call_update_json)) FROM tool_call_state x WHERE x.session_id = s.id) AS tool_state_bytes'
+    : 'NULL AS tool_state_bytes';
+  return `SELECT s.id, s.title, s.hidden, s.main_chain_id,
+  (SELECT max(m.node_id) FROM message_nodes m WHERE m.session_id = s.id) AS max_node_id,
+  (SELECT count(*) FROM message_nodes m WHERE m.session_id = s.id) AS node_count,
+  ${agg('tool_call_state', 'tool_state')}, ${bytes},
+  ${agg('subagent_heads', 'subagent_head')}
+  FROM sessions s ORDER BY s.created_at, s.id`;
+}
+const intOrNull = (v) => (v == null ? null : Number(v));
+/** A store older than a table or column: the one error that may read as empty. */
+const isMissing = (e) => /no such (table|column)/i.test(String((e && e.message) || e));
+
+/**
+ * Sessions in one store: every row of sessions.db's sessions table, hidden ones included. The DB is
+ * shared, so an entry names it relative to harness_path (a relative string is never stat'ed) and
+ * carries its own change key; a write to another session leaves this entry unchanged.
+ */
+function list(storeRoot = storeRootDefault()) {
+  const harnessPath = harnessPaths.resolveNative(storeRoot);
+  const file = path.join(harnessPath, DB_FILE);
+  try { if (!fs.statSync(file).isFile()) return []; } catch { return []; }   // no store
+  // A store that is busy or locked mid-save must not read as "no sessions": an open or a query that
+  // fails throws, and the runner keeps its index. Only a missing table or column reads as empty.
+  const db = openReadOnly(file);
+  try {
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((t) => String(t.name)));
+    return db.prepare(listSql(tables)).all().map((r) => ({
+      harness: HARNESS, harness_path: harnessPath, session_id: String(r.id), db_rel: DB_FILE,
+      main_chain_id: intOrNull(r.main_chain_id), max_node_id: intOrNull(r.max_node_id), node_count: Number(r.node_count) || 0,
+      tool_state_count: intOrNull(r.tool_state_count), tool_state_max_rowid: intOrNull(r.tool_state_max_rowid), tool_state_bytes: intOrNull(r.tool_state_bytes),
+      subagent_head_count: intOrNull(r.subagent_head_count), subagent_head_max_rowid: intOrNull(r.subagent_head_max_rowid),
+      hidden: Number(r.hidden) === 1, title_sha: sha256(String(r.title ?? '')).slice(0, 16),
+    }));
+  } catch (e) {
+    if (isMissing(e)) return [];
+    throw e;
+  } finally { db.close(); }
+}
+
+/**
+ * Normalise one session. `session` is a list() entry, or `{ session_id, session, nodes, tool_states,
+ * subagent_heads }` already loaded (tests): `session` the sessions row, `nodes` message_nodes rows,
+ * `tool_states` tool_call_state rows (JSON columns as strings or objects). Returns the log records;
+ * null when the session is gone or a pointer dangles (a torn read); throws on every other failure.
+ */
+function normalise(session) {
+  const sid = String(session.session_id);
+  if (Array.isArray(session.nodes)) return build(sid, session.session || null, session.nodes, session.tool_states || [], session.subagent_heads || []);
+  const file = path.join(String(session.harness_path || storeRootDefault()), String(session.db_rel || DB_FILE));
+  // Every error but a missing table propagates (module contract, docs/design/sessions-log.md): a busy
+  // or locked store, a damaged page. A throw shows in the runner's errors and is retried.
+  const db = openReadOnly(file);
+  let row;
+  let nodes;
+  let states = [];
+  let heads = [];
+  try {
+    db.exec('BEGIN');
+    row = db.prepare('SELECT id, working_directory, title, created_at, main_chain_id, hidden FROM sessions WHERE id = ?').get(sid);
+    if (!row) return null;
+    nodes = db.prepare('SELECT node_id, parent_node_id, chat_message, metadata FROM message_nodes WHERE session_id = ? ORDER BY node_id').all(sid);
+    // Only an older store's missing table reads as empty; anything else (busy, locked) fails the
+    // whole read below, so a session is never written with fewer statuses or sub-agents than it has.
+    try { states = db.prepare('SELECT tool_call_id, tool_call_update_json FROM tool_call_state WHERE session_id = ?').all(sid); } catch (e) { if (!isMissing(e)) throw e; states = []; }
+    try { heads = db.prepare('SELECT agent_id, chain_node_id FROM subagent_heads WHERE session_id = ?').all(sid); } catch (e) { if (!isMissing(e)) throw e; heads = []; }
+  } catch (e) {
+    if (isMissing(e)) return null;
+    throw e;
+  } finally {
+    try { db.exec('COMMIT'); } catch { /* nothing to end */ }
+    db.close();
+  }
+  return build(sid, row, nodes, states, heads);
+}
+
+// ── field helpers ─────────────────────────────────────────────────────────────────────────────
+/**
+ * A stored JSON column. Devin writes them with serde, so one that does not parse is a damaged read
+ * (a page overwritten in place): it throws rather than drop a node, which would emit fewer messages.
+ */
+function jsonCol(v, what, { nullable = true } = {}) {
+  if (v == null) { if (nullable) return null; throw new Error(`devin: ${what} is missing`); }
+  if (typeof v === 'object' && !(v instanceof Uint8Array)) return v;
+  let o;
+  try { o = JSON.parse(textOf(v)); } catch { throw new Error(`devin: ${what} does not parse (a damaged read)`); }
+  if (o != null && typeof o !== 'object') throw new Error(`devin: ${what} is not an object (a damaged read)`);
+  if (o == null && !nullable) throw new Error(`devin: ${what} is null`);
+  return o;
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : (typeof v === 'bigint' ? Number(v) : null));
+function ms(iso) {
+  if (typeof iso !== 'string' || !iso) return null;
+  let t = Date.parse(iso);
+  if (!Number.isFinite(t)) t = Date.parse(iso.replace(/(\.\d{3})\d+/, '$1'));   // nanosecond fractions
+  return Number.isFinite(t) ? t : null;
+}
+/** sessions.created_at is in seconds. */
+function epochMs(v) {
+  const n = num(typeof v === 'string' ? Number(v) : v);
+  if (n == null || n <= 0) return null;
+  return n < 1e11 ? n * 1000 : n;
+}
+const sha256 = (b) => crypto.createHash('sha256').update(b).digest('hex');
+function textOfContent(c) {
+  if (c == null) return '';
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) return c.map((b) => (typeof b === 'string' ? b : (b && typeof b.text === 'string' ? b.text : ''))).join('');
+  return '';
+}
+function argsOf(a) {
+  if (a == null) return {};
+  if (typeof a === 'string') { try { return JSON.parse(a); } catch { return { raw: a }; } }
+  return a;
+}
+
+function toNode(r) {
+  if (r.node_id == null) throw new Error('devin: a node without node_id (a damaged read)');
+  const cm = jsonCol(r.chat_message, `chat_message of node ${r.node_id}`, { nullable: false });
+  const md = cm.metadata && typeof cm.metadata === 'object' ? cm.metadata : {};
+  return {
+    id: Number(r.node_id),
+    parent: r.parent_node_id == null ? null : Number(r.parent_node_id),
+    mid: cm.message_id == null ? '' : String(cm.message_id),
+    role: String(cm.role || ''),
+    cm,
+    md,
+    ext: md.extensions && typeof md.extensions === 'object' ? md.extensions : {},
+    nm: jsonCol(r.metadata, `metadata of node ${r.node_id}`) || {},
+  };
+}
+const isPrefix = (n) => n.nm.is_system_prefix === true;
+const isKeepalive = (n) => (n.md.telemetry || {}).source === 'cache_keepalive' || n.ext['barista/prompt_cache_footer'] === true;
+const sumFrom = (n) => (n.nm.summarized_from == null ? null : Number(n.nm.summarized_from));
+const isContent = (n) => n.role !== 'tool' && !isPrefix(n) && !isKeepalive(n);
+const isInterrupt = (n) => n.role === 'system' && INTERRUPTED.test(textOfContent(n.cm.content));
+
+function imageParts(images) {
+  return (Array.isArray(images) ? images : []).map((im, i) => {
+    const b64 = im && typeof im.base64_data === 'string' ? im.base64_data : '';
+    const bytes = b64 ? Buffer.from(b64, 'base64') : null;
+    const caption = im && typeof im.caption === 'string' && im.caption ? { caption: im.caption } : {};
+    return {
+      part_id: `image:${i}`, kind: 'file', media_type: String((im && im.mime_type) || ''),
+      att_sha: bytes ? sha256(bytes) : null, att_len: bytes ? bytes.length : null, ref: String((im && im.source_path) || ''),
+      ...caption,
+    };
+  });
+}
+
+/** What the user typed, where the store keeps it apart from the content the model saw. */
+function typedText(n) {
+  const blocks = n.ext['chisel/acp-content-blocks'];
+  if (!Array.isArray(blocks)) return '';
+  return blocks.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('');
+}
+
+function reasoningPart(th) {
+  if (typeof th === 'string') return th ? { part_id: 'thinking', kind: 'reasoning', text: th } : null;
+  if (!th || typeof th !== 'object') return null;
+  const sig = typeof th.signature === 'string' ? th.signature : '';
+  const sigLen = sig ? { signature_len: Buffer.byteLength(sig) } : {};
+  if (typeof th.thinking === 'string' && th.thinking) return { part_id: 'thinking', kind: 'reasoning', text: th.thinking, ...sigLen };
+  if (sig) return { part_id: 'thinking', kind: 'reasoning', opaque: true, ...sigLen };
+  return null;
+}
+
+function usageOf(md) {
+  const m = md.metrics;
+  if (!m || typeof m !== 'object') return null;
+  const u = {
+    basis: 'unknown', input: num(m.input_tokens), output: num(m.output_tokens),
+    cache_read: num(m.cache_read_tokens), cache_write: num(m.cache_creation_tokens), reasoning: null, cost: null,
+  };
+  return u.input == null && u.output == null && u.cache_read == null && u.cache_write == null ? null : u;
+}
+
+/** One call and its result (the tool node on the same line), folded into one part. */
+function toolPart(call, res, st) {
+  const id = String(call.id);
+  const part = {
+    part_id: `tool:${id}`, kind: 'tool', call_id: id, tool: String(call.name || ''), args: argsOf(call.arguments),
+    output: null, is_error: false, status: 'interrupted',
+  };
+  if (!res) return part;
+  const x = res.ext;
+  const meta = x['chisel/tool_result_meta'] && typeof x['chisel/tool_result_meta'] === 'object' ? x['chisel/tool_result_meta'] : {};
+  const failure = (x['chisel/tool_failure'] && x['chisel/tool_failure'].reason) ?? meta.failure_reason ?? null;
+  const has = (k) => failure === k || (!!failure && typeof failure === 'object' && Object.prototype.hasOwnProperty.call(failure, k));
+  const u = st || {};
+  const um = u._meta && typeof u._meta === 'object' ? u._meta : {};
+  const rejected = um['cognition.ai/rejected'] === true || has('Rejected');
+  const canceled = um['cognition.ai/canceled'] === true || has('Canceled');
+  const failed = meta.success === false || u.status === 'failed';
+  part.output = textOfContent(res.cm.content);
+  part.is_error = !!(failed || rejected || canceled);
+  part.status = rejected ? 'denied' : (canceled ? 'cancelled' : (failed ? 'error' : 'completed'));
+  const term = x['chisel/terminal_output'];
+  const ec = num(term && term.exit && term.exit.exit_code) ?? num(um.terminal_exit && um.terminal_exit.exit_code);
+  if (ec != null) part.exit_code = ec;
+  const ts = ms(res.md.created_at);
+  if (ts != null) part.ts = ts;
+  return part;
+}
+
+/** A pointer that dangles inside the line: a torn read. normalise returns null, never fewer messages. */
+class TornRead extends Error {}
+
+function build(sid, row, rawNodes, rawStates, rawHeads) {
+  try { return derive(sid, row, rawNodes, rawStates, rawHeads); } catch (e) {
+    if (e instanceof TornRead) return null;
+    throw e;
+  }
+}
+
+function derive(sid, row, rawNodes, rawStates, rawHeads) {
+  if (!row) return null;
+  const nodes = new Map();
+  for (const r of rawNodes || []) {
+    const n = toNode(r);
+    if (!Number.isFinite(n.id)) throw new Error('devin: a node id that is not a number (a damaged read)');
+    nodes.set(n.id, n);
+  }
+  const states = new Map();
+  for (const r of rawStates || []) if (r && r.tool_call_id != null) states.set(String(r.tool_call_id), jsonCol(r.tool_call_update_json, `tool_call_state ${r.tool_call_id}`) || {});
+
+  /** The chain ending at `id`, root first; null when a pointer dangles or loops (a torn read). */
+  const walk = (id) => {
+    const out = [];
+    const seen = new Set();
+    let n = nodes.get(id);
+    if (!n) return null;
+    while (n) {
+      if (seen.has(n.id)) return null;
+      seen.add(n.id);
+      out.push(n);
+      if (n.parent == null) break;
+      n = nodes.get(n.parent);
+      if (!n) return null;
+    }
+    return out.reverse();
+  };
+
+  const hidden = Number(row.hidden) === 1 || row.hidden === true;
+  const head = {
+    k: 'session',
+    title: row.title == null ? '' : String(row.title),
+    cwd: row.working_directory == null ? '' : String(row.working_directory),
+    created: epochMs(row.created_at),
+    updated: null, archived: null,
+    version: '',
+    incarnation: '',
+    ...(hidden ? { kind: 'hidden' } : {}),
+    links: [],
+  };
+  if (row.main_chain_id == null) return [head];   // no turn saved yet
+  const chain = walk(Number(row.main_chain_id));
+  if (!chain) return null;
+
+  // ── the current line: compacted histories first, then the chain ──────────────────────────────
+  const expanded = new Set();
+  const lineOf = (ch) => {
+    const out = [];
+    let hoisted = false;
+    for (const n of ch) {
+      const x = sumFrom(n);
+      if (x != null && !expanded.has(x)) {
+        expanded.add(x);
+        // The compacted history must read whole: a dangling pointer would log all of it as removed.
+        const prior = walk(x);
+        if (!prior) throw new TornRead(`compacted history ending at node ${x}`);
+        const piece = [...lineOf(prior), { compaction: x, trigger: n }];
+        // The first compaction's history goes before the whole chain: the log before the compaction
+        // stays an exact prefix, so it appends.
+        if (!hoisted) { out.unshift(...piece); hoisted = true; } else out.push(...piece);
+      }
+      out.push({ node: n });
+    }
+    return out;
+  };
+  const line = lineOf(chain);
+
+  const records = [];
+  const emitted = new Map();   // message_id of a node → the log message that carries it
+  const owner = new Map();     // call id → the assistant message that made the call
+  const seenNodes = new Set(); // nodes the line and its sub-agent chains went through
+  const subChains = new Set();
+  let order = 0;
+  let held = false;
+
+  const pushMessage = (n, m) => { records.push(m); emitted.set(n.mid, m.message_id); };
+  const base = (n, role, agent) => ({ k: 'message', message_id: n.mid, role, ts: ms(n.md.created_at), order: order++, agent_id: agent });
+
+  const emitSummary = (n, agent, through) => {
+    const parts = [];
+    const r = reasoningPart(n.cm.thinking);
+    if (r) parts.push(r);
+    parts.push({ part_id: 'summary', kind: 'summary', text: textOfContent(n.cm.content), replaces: through ? { through_id: through } : 'unknown' });
+    const asst = n.role === 'assistant';
+    pushMessage(n, {
+      ...base(n, asst ? 'assistant' : 'system', agent), state: 'current', status: 'complete',
+      ...(asst ? { model: String(n.md.generation_model || ''), effort: '', usage: usageOf(n.md) } : { source: 'injected', hidden: true }),
+      parts,
+    });
+  };
+
+  const emitCompaction = (e, agent) => {
+    const xNode = nodes.get(e.compaction);
+    const through = xNode ? (emitted.get(xNode.mid) || null) : null;
+    // The compactor's reply: an assistant node with summarized_from X, usually off the line.
+    const sums = [];
+    const sumIds = new Set();
+    for (const n of [...nodes.values()].sort((a, b) => b.id - a.id)) {
+      if (n.role !== 'assistant' || sumFrom(n) !== e.compaction || !n.mid || sumIds.has(n.mid) || emitted.has(n.mid)) continue;
+      sumIds.add(n.mid);
+      sums.unshift(n);
+    }
+    const carrier = sums.length ? null : (e.trigger.role === 'system' && !emitted.has(e.trigger.mid) ? e.trigger : null);
+    const first = sums[0] || carrier;
+    records.push({ k: 'lifecycle', event: 'compaction', at: first ? ms(first.md.created_at) : ms(e.trigger.md.created_at), ...(through ? { through } : {}) });
+    for (const n of sums) { seenNodes.add(n.id); emitSummary(n, agent, through); }
+    if (carrier) emitSummary(carrier, agent, through);
+  };
+
+  const emitEntries = (entries, agent, canHold) => {
+    const results = new Map();
+    for (const e of entries) {
+      if (!e.node) continue;
+      seenNodes.add(e.node.id);
+      const c = e.node.role === 'tool' && e.node.cm.tool_call_id != null ? String(e.node.cm.tool_call_id) : null;
+      if (c && !results.has(c)) results.set(c, e.node);
+    }
+    // For each entry: whether real content follows it, and which entry comes next.
+    const follows = new Array(entries.length).fill(false);
+    const nextOf = new Array(entries.length).fill(null);
+    let seen = false;
+    let next = null;
+    for (let i = entries.length - 1; i >= 0; i--) {
+      follows[i] = seen;
+      nextOf[i] = next;
+      const e = entries[i];
+      if (e.compaction != null || isContent(e.node)) { seen = true; next = e; }
+    }
+
+    for (let i = 0; i < entries.length && !held; i++) {
+      const e = entries[i];
+      if (e.compaction != null) { emitCompaction(e, agent); continue; }
+      const n = e.node;
+      if (!n.mid || isPrefix(n) || isKeepalive(n) || emitted.has(n.mid)) continue;
+
+      if (n.role === 'tool') {
+        const c = n.cm.tool_call_id == null ? '' : String(n.cm.tool_call_id);
+        if (owner.has(c)) { emitted.set(n.mid, owner.get(c)); continue; }   // folded into its call
+        // A result whose call is not on the line: a tool message of its own.
+        const st = states.get(c);
+        const name = (st && st._meta && st._meta['cognition.ai/inferenceToolName']) || (n.md.telemetry || {}).operation || '';
+        pushMessage(n, { ...base(n, 'tool', agent), state: 'current', status: 'complete', parts: [toolPart({ id: c, name, arguments: null }, n, st)] });
+        continue;
+      }
+
+      if (n.role === 'assistant') {
+        const calls = Array.isArray(n.cm.tool_calls) ? n.cm.tool_calls.filter((c) => c && c.id != null) : [];
+        const missing = calls.some((c) => !results.has(String(c.id)));
+        const inference = (n.md.telemetry || {}).operation === 'inference' || !!n.md.request_id;
+        if (canHold && !follows[i] && (missing || (inference && n.md.finish_reason == null))) { held = true; break; }
+        const parts = [];
+        const r = reasoningPart(n.cm.thinking);
+        if (r) parts.push(r);
+        const text = textOfContent(n.cm.content);
+        if (text) parts.push({ part_id: 'text', kind: 'text', text });
+        parts.push(...imageParts(n.cm.images));
+        for (const c of calls) parts.push(toolPart(c, results.get(String(c.id)), states.get(String(c.id))));
+        const nx = nextOf[i];
+        const interrupted = (nx && nx.node && isInterrupt(nx.node)) || parts.some((p) => p.kind === 'tool' && (p.status === 'interrupted' || p.status === 'cancelled'));
+        pushMessage(n, {
+          ...base(n, 'assistant', agent), state: 'current', status: interrupted ? 'interrupted' : 'complete',
+          model: String(n.md.generation_model || ''), effort: '', usage: usageOf(n.md), parts,
+        });
+        for (const c of calls) owner.set(String(c.id), n.mid);
+        // Sub-agents this message started: their chains live in the same tree.
+        for (const c of calls) {
+          const res = results.get(String(c.id));
+          const x = res ? res.ext : null;
+          if (!x || x['subagent/agent_id'] == null || x['subagent/chain_node_id'] == null) continue;
+          const head2 = Number(x['subagent/chain_node_id']);
+          if (subChains.has(head2)) continue;
+          subChains.add(head2);
+          const sub = walk(head2);
+          if (!sub) throw new TornRead(`sub-agent chain ending at node ${head2}`);
+          emitEntries(lineOf(sub), String(x['subagent/agent_id']), false);
+        }
+        continue;
+      }
+
+      if (n.role === 'user') {
+        const parts = [];
+        const text = textOfContent(n.cm.content);
+        const typed = typedText(n);
+        if (text) parts.push({ part_id: 'text', kind: 'text', text, ...(typed && typed !== text ? { display_text: typed } : {}) });
+        parts.push(...imageParts(n.cm.images));
+        const automated = hidden || agent !== '' || n.md.is_user_input !== true;
+        pushMessage(n, { ...base(n, 'user', agent), state: 'current', status: 'complete', ...(automated ? { source: 'automated' } : {}), parts });
+        continue;
+      }
+
+      // system (and any other role): the interrupt notice, else injected context.
+      const text = textOfContent(n.cm.content);
+      if (isInterrupt(n)) {
+        pushMessage(n, { ...base(n, 'system', agent), state: 'current', status: 'complete', parts: [{ part_id: 'notice', kind: 'notice', text: text.trim() }] });
+        continue;
+      }
+      pushMessage(n, {
+        ...base(n, 'system', agent), state: 'current', status: 'complete', source: 'injected', hidden: true,
+        parts: text ? [{ part_id: 'text', kind: 'text', text }] : [],
+      });
+    }
+  };
+  emitEntries(line, '', true);
+
+  // ── reverts: abandoned subtrees still in the table ───────────────────────────────────────────
+  // Not on the line, not a sub-agent or compactor chain, not the prefix or a keepalive, and a
+  // message id the line does not carry (streaming twins and prefix copies share the line's ids).
+  const aux = new Set();
+  const markUp = (id) => {
+    for (let n = nodes.get(id), k = 0; n && !aux.has(n.id) && k <= nodes.size; n = n.parent == null ? null : nodes.get(n.parent), k++) aux.add(n.id);
+  };
+  for (const n of nodes.values()) {
+    if (n.role === 'assistant' && sumFrom(n) != null) markUp(n.id);
+    if (n.ext['subagent/chain_node_id'] != null) markUp(Number(n.ext['subagent/chain_node_id']));
+  }
+  for (const h of rawHeads || []) if (h && h.chain_node_id != null) markUp(Number(h.chain_node_id));
+  const known = new Set();
+  for (const id of seenNodes) known.add(nodes.get(id).mid);
+  const cand = new Map();
+  for (const n of nodes.values()) {
+    if (seenNodes.has(n.id) || aux.has(n.id) || isPrefix(n) || isKeepalive(n) || !n.mid || known.has(n.mid)) continue;
+    cand.set(n.id, n);
+  }
+  const groups = new Map();   // top of an abandoned subtree → { base, ids }
+  for (const n of [...cand.values()].sort((a, b) => a.id - b.id)) {
+    let top = n;
+    for (let k = 0; top.parent != null && cand.has(top.parent) && k <= nodes.size; k++) top = cand.get(top.parent);
+    if (!groups.has(top.id)) groups.set(top.id, { base: top.parent == null ? null : nodes.get(top.parent) || null, ids: [] });
+    const g = groups.get(top.id);
+    if (n.role !== 'tool' && !g.ids.includes(n.mid)) g.ids.push(n.mid);
+  }
+  let atStart = 1;
+  for (const [, g] of [...groups.entries()].sort((a, b) => a[0] - b[0])) {
+    if (!g.ids.length) continue;
+    const through = g.base ? (emitted.get(g.base.mid) || null) : null;
+    const rec = { k: 'lifecycle', event: 'rewind', at: null, message_ids: g.ids, through };
+    if (!through) {
+      if (g.base && known.has(g.base.mid) && !isPrefix(g.base)) continue;   // hangs off a held-back message
+      records.splice(atStart - 1, 0, rec);
+      atStart++;
+      continue;
+    }
+    let at = records.findIndex((m) => m.k === 'message' && m.message_id === through);
+    if (at < 0) continue;   // its message is held back: the record comes with it
+    at++;
+    while (at < records.length && records[at].k === 'lifecycle' && records[at].event === 'rewind') at++;
+    records.splice(at, 0, rec);
+  }
+
+  return [head, ...records];
+}
+
+module.exports = { HARNESS, list, normalise, storeRootDefault, listSql };