memhouse 0.18.12 → 0.20.1

package/editors/normalise/opencode.js

@@ -0,0 +1,633 @@
+'use strict';
+// v4 wave 2: OpenCode → normalised session log records (docs/design/sessions-log.md).
+//
+// Store: <data>/opencode.db (SQLite, WAL), opened through sqlite.js openReadOnly only (a fresh DB keeps
+// its data in the -wal file, so the main file alone is never copied or parsed). <data> is
+// harness-paths' dataFolder('opencode'): $XDG_DATA_HOME/opencode, default ~/.local/share/opencode. The DB is
+// opencode.db for the channels latest/beta/prod, opencode-<channel>.db otherwise; OPENCODE_DB names
+// another file (absolute, or relative to <data>). Spec: docs/design/adapter-specs/opencode.md
+// (repository; OpenCode 1.19.3), sessions-model v0 and its annex.
+//
+// Rules from the spec:
+// - two engines in one DB. v1: `message` rows ordered by (time_created, id), `part` rows by id. v2
+//   (reached through /api/session): `session_message` rows ordered by seq, each assistant content
+//   element a part keyed (message id, content id); `session_input` adds delivery steer|queue;
+// - one tool part holds both the call and its result (v1 `tool` part, v2 `tool` content element);
+// - usage: v1 step-finish parts (else the message's own tokens), v2 the assistant's tokens; basis
+//   net (input = prompt − cache.read, output = completion − reasoning). An all-zero record (aborted,
+//   overflowed, errored step) is unknown, so null; cost 0 (no price table) is null;
+// - held back: an assistant still streaming (no time.completed, no error) and everything after it,
+//   so the log only grows while the session only grows. One with a later assistant after it is a
+//   dead run (killed, abandoned): kept, status interrupted;
+// - `session.revert` hides messages the user can still bring back: state 'reverted' (v1 from the
+//   revert message on, v2 after it; a v1 revert at a part hides that message's later parts only);
+// - prompt-while-reverted hard-deletes rows and writes `message.removed` events: the deleted ids
+//   vanish from the log, and an `edit` lifecycle record names them, placed at the event's time (the
+//   id-embedded time of its evt_ id). A committed v2 revert gives a `rewind` record at its seq;
+// - compaction: the user message's `compaction` part {auto, overflow, tail_start_id} gives a
+//   lifecycle record after it, and the summary assistant's (`summary: true`) text becomes summary
+//   parts replacing {first_kept_id: tail_start_id}. The overflow path re-inserts the original prompt
+//   as a new, non-synthetic user message: kept as it is;
+// - synthetic text and file parts are `source: 'injected'`; a user message made only of them is a
+//   harness-made turn, `source: 'automated'` (compaction continue, subtask summarise), and so is an
+//   automatic compaction's trigger. Shell mode `!cmd` is a synthetic user message plus an assistant
+//   with a bash part and no step parts: the assistant is `source: 'user'` (the user ran it);
+// - subtask parts are the prompt the user's command sends to the sub-agent: a text part;
+// - a tool output cut at the limit keeps the cut text as output, and `output_ref` names the
+//   spilled `tool-output/tool_<id>` file by sha256 and length (hashed, never logged);
+// - links: explicit only. A child names its parent (`session.parent_id`, subagent, at ''); the
+//   parent names its children from the `task` tool part's metadata.sessionId (at = the call id).
+//   Forks store no pointer (new ids, `(fork #N)` title): no link here, inference is the engine's;
+// - `time_archived` → archived;
+// - a `patch` part (the files a step changed) is a notice part, its text the files, one per line;
+// - not conversation, left out: step-start, step-finish (folded into usage), snapshot, retry,
+//   agent mentions (their text is in the user's text part), v2 agent-switched / model-switched;
+// - no MCP `server`: OpenCode names an MCP tool `<server>_<tool>`, which does not split reliably;
+// - volatile fields stay out: time_updated, the session's running token sums, summary_*, model,
+//   agent, metadata, and the tool state's `time.compacted` (prune). `updated` is null;
+// - redaction: no OpenCode field path is declared secret (sessions-model §4). Provider error
+//   payloads (responseHeaders, responseBody, metadata.url) are never copied: an error part keeps the
+//   error name and message only. The credential tables are never queried; only session, message,
+//   part, session_message, session_input and event are read.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { fileURLToPath } = require('url');
+const harnessPaths = require('../harness-paths');
+const { openReadOnly, textOf } = require('../sqlite');
+const { placeChildren } = require('../sessions-log');
+
+const HARNESS = 'opencode';
+const DEFAULT_DB = 'opencode.db';
+const CHANNEL_DB = /^opencode-[A-Za-z0-9._-]+\.db$/;
+const MS_MOD = 2 ** 36;          // ids carry the low 48 bits of ms·4096 + counter: ms modulo 2^36
+const ID_SLACK_MS = 60000;
+const SPILL = /^tool_[0-9A-Za-z]+$/;
+
+// ── store discovery ───────────────────────────────────────────────────────────────────────────
+/** The data folder: harness-paths' dataFolder (it honours XDG_DATA_HOME, default ~/.local/share/opencode). */
+function storeRootDefault(env = process.env) {
+  return harnessPaths.dataFolder(HARNESS, { env });
+}
+
+function isFile(p) { try { return fs.statSync(p).isFile(); } catch { return false; } }
+function readdir(dir) { try { return fs.readdirSync(dir).sort(); } catch { return []; } }
+
+/**
+ * The session DBs of one data folder: OPENCODE_DB when set (absolute, or relative to the folder;
+ * `:memory:` holds nothing), opencode.db, and every opencode-<channel>.db. Every one is a store of
+ * its own, keyed by its file's real path (sessions-model §1), the default DB
+ * included: an import into another channel can repeat a session id, and only a per-file
+ * harness_path keeps the two apart. One file reached two ways resolves to one real path.
+ */
+function dbFiles(storeRoot, env = process.env) {
+  const out = [];
+  const seen = new Set();
+  const folder = harnessPaths.resolveNative(storeRoot);
+  const add = (file) => {
+    if (!isFile(file)) return;
+    const real = harnessPaths.resolveNative(file);
+    if (seen.has(real)) return;
+    seen.add(real);
+    out.push({ file, harness_path: real });
+  };
+  add(path.join(storeRoot, DEFAULT_DB));
+  for (const f of readdir(storeRoot)) if (CHANNEL_DB.test(f)) add(path.join(storeRoot, f));
+  const o = env.OPENCODE_DB;
+  if (o && o !== ':memory:') add(path.isAbsolute(o) ? o : path.join(storeRoot, o));
+  return out;
+}
+
+// Every read error throws (busy, locked, malformed, IOERR, not a database, a locking-protocol
+// failure): fewer rows would rewrite the log as if the missing messages had been removed. list()
+// throwing keeps the runner's index; normalise() throwing is retried. Only a table or column an
+// older schema lacks (v1 versus v2) reads as empty.
+const MISSING = /no such (table|column)/i;
+const BUSY_TIMEOUT_MS = 1000;   // OpenCode's own transactions take milliseconds
+
+function openDb(file) {
+  const db = openReadOnly(file);   // immutable only for a WAL store with no -wal: nothing is created
+  try { db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`); } catch { /* the pragma is optional */ }
+  return db;
+}
+
+// The events that change a session's log without a row of it changing: removals (an edit) and v2
+// reverts, as ranges on `type` ('/' follows '.'). One range per query lets event_aggregate_type_seq_idx
+// find them from the index; OR-ed together, SQLite reads every event row of the session instead.
+const EVENT_RANGES = ['message.removed.', 'message.part.removed.', 'session.next.revert.']
+  .map((t) => `(type >= '${t}' AND type < '${t.slice(0, -1)}/')`);
+
+/**
+ * A table's columns; empty when the table is missing (PRAGMA table_info reads no rows for it). Every
+ * query is built from these, so a column an older or newer schema lacks reads as null instead of
+ * failing the query, and with it every session of the DB.
+ */
+function columnsOf(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((r) => String(r.name)));
+}
+/** The wanted columns, `NULL AS <col>` for each one the table lacks. */
+const pick = (cols, names, alias = '') => names.map((c) => (cols.has(c) ? `${alias}${c}` : `NULL AS ${c}`)).join(', ');
+const SCHEMA = {
+  session: { need: ['id'], opt: ['parent_id', 'directory', 'title', 'version', 'time_created', 'time_archived', 'revert'] },
+  message: { need: ['id', 'session_id', 'data'], opt: ['time_created'] },
+  part: { need: ['id', 'message_id', 'session_id', 'data'], opt: ['time_created'] },
+  session_message: { need: ['id', 'session_id', 'type', 'data'], opt: ['seq', 'time_created'] },
+  session_input: { need: ['id', 'session_id'], opt: ['delivery', 'admitted_seq', 'promoted_seq'] },
+  event: { need: ['id', 'aggregate_id', 'type', 'data'], opt: ['seq'] },
+};
+function schemaOf(db) {
+  const out = {};
+  for (const t of Object.keys(SCHEMA)) out[t] = columnsOf(db, t);
+  return out;
+}
+const usable = (sc, t) => SCHEMA[t].need.every((c) => sc[t].has(c));
+
+/** The per-session change key, as SQL columns of the list query (what an older DB lacks: null). */
+function keyColumns(sc) {
+  const agg = (t, fk, fn, col, as) => (sc[t].has(fk) && sc[t].has(col) ? `(SELECT ${fn}(${col}) FROM ${t} WHERE ${fk} = s.id) AS ${as}` : `NULL AS ${as}`);
+  const ev = sc.event.has('aggregate_id') && sc.event.has('type') && sc.event.has('seq');
+  return [
+    agg('message', 'session_id', 'count', 'id', 'm_n'), agg('message', 'session_id', 'max', 'time_updated', 'm_tu'),
+    agg('part', 'session_id', 'count', 'id', 'p_n'), agg('part', 'session_id', 'max', 'time_updated', 'p_tu'),
+    agg('session_message', 'session_id', 'count', 'id', 'v_n'), agg('session_message', 'session_id', 'max', 'seq', 'v_seq'),
+    agg('session_message', 'session_id', 'max', 'time_updated', 'v_tu'), agg('session_input', 'session_id', 'count', 'id', 'i_n'),
+    ev ? `max(${EVENT_RANGES.map((r) => `coalesce((SELECT max(seq) FROM event WHERE aggregate_id = s.id AND ${r}), -1)`).join(', ')}) AS ev_seq` : 'NULL AS ev_seq',
+  ].join(', ');
+}
+
+/**
+ * Sessions in one data folder: one entry per `session` row of each of its DBs.
+ *
+ * A DB is shared by all of its sessions, so no entry names it by absolute path (the runner would
+ * re-normalise every session on every write). The entry names it relative to harness_path
+ * (`db_rel`; '' when harness_path is the DB file itself), and the spill folder the same way
+ * (`spill_rel`). It carries a per-session change `key`, read in the same query: the count and the
+ * newest time_updated of the session's messages and parts (rows added, upserted, deleted, imported)
+ * and of its v2 messages with their newest seq, its v2 inputs, the newest removal or revert event,
+ * and a hash of the session-record fields (title, directory, version, parent_id, time_archived,
+ * revert). The session's own time_updated is left out: usage updates skip it, and a rename alone
+ * already changes the title.
+ */
+function list(storeRoot = storeRootDefault(), { env = process.env } = {}) {
+  storeRoot = path.resolve(storeRoot);
+  try { if (!fs.statSync(storeRoot).isDirectory()) return []; } catch { return []; }
+  const spills = path.join(harnessPaths.resolveNative(storeRoot), 'tool-output');
+  const out = [];
+  for (const { file, harness_path } of dbFiles(storeRoot, env)) {
+    const rel = { db_rel: path.relative(harness_path, harnessPaths.resolveNative(file)), spill_rel: path.relative(harness_path, spills) };
+    let db = null;
+    try {
+      db = openDb(file);
+      const sc = schemaOf(db);
+      if (!usable(sc, 'session')) continue;   // no session table: not an OpenCode DB
+      const sql = `SELECT s.id, ${pick(sc.session, ['title', 'directory', 'version', 'parent_id', 'time_archived', 'revert'], 's.')}, ${keyColumns(sc)} FROM session s ORDER BY s.id`;
+      for (const r of db.prepare(sql).all()) {
+        const head = sha256(JSON.stringify([r.title, r.directory, r.version, r.parent_id, r.time_archived, textOf(r.revert)])).slice(0, 16);
+        const key = [r.m_n, r.m_tu, r.p_n, r.p_tu, r.v_n, r.v_seq, r.v_tu, r.i_n, r.ev_seq].map((v) => (v == null ? '' : String(v))).join(':');
+        out.push({ harness: HARNESS, harness_path, session_id: String(r.id), ...rel, key: `${key}:${head}` });
+      }
+    } catch (e) {
+      if (!MISSING.test(String(e && e.message))) throw e;   // busy, damaged, unreadable: the runner keeps its index
+    } finally {
+      if (db) try { db.close(); } catch { /* closed */ }
+    }
+  }
+  return out;
+}
+
+/** One session's rows, read in one snapshot of the live WAL DB. */
+function readSession(file, sid) {
+  const db = openDb(file);
+  let began = false;
+  const all = (sql, ...args) => {
+    try { return db.prepare(sql).all(...args); } catch (e) {
+      if (MISSING.test(String(e && e.message))) return [];   // an older schema
+      throw e;
+    }
+  };
+  try {
+    db.exec('BEGIN');   // one snapshot; a failure here is a failure to read
+    began = true;
+    const sc = schemaOf(db);
+    if (!usable(sc, 'session')) return null;
+    const cols = (t) => pick(sc[t], [...SCHEMA[t].need, ...SCHEMA[t].opt]);
+    const rows = (t, sql, ...args) => (usable(sc, t) ? all(sql.replace('<cols>', cols(t)), ...args) : []);
+    const session = db.prepare(`SELECT ${cols('session')} FROM session WHERE id = ?`).get(sid);
+    if (!session) return null;
+    return {
+      session_id: sid,
+      session,
+      messages: rows('message', 'SELECT <cols> FROM message WHERE session_id = ? ORDER BY time_created, id', sid),
+      parts: rows('part', 'SELECT <cols> FROM part WHERE session_id = ? ORDER BY message_id, id', sid),
+      session_messages: rows('session_message', 'SELECT <cols> FROM session_message WHERE session_id = ? ORDER BY seq, id', sid),
+      session_inputs: rows('session_input', 'SELECT <cols> FROM session_input WHERE session_id = ?', sid),
+      events: rows('event', `${EVENT_RANGES.map((r) => `SELECT ${cols('event')} FROM event WHERE aggregate_id = ? AND ${r}`).join(' UNION ALL ')} ORDER BY seq, id`, sid, sid, sid),
+    };
+  } finally {
+    if (began) try { db.exec('COMMIT'); } catch { /* read-only */ }
+    try { db.close(); } catch { /* closed */ }
+  }
+}
+
+// ── small helpers ─────────────────────────────────────────────────────────────────────────────
+/** A stored JSON object (a row's data, an event's data, session.revert): null when empty, a throw when unparsable. */
+function strictJson(v, what) {
+  if (v == null) return null;
+  if (typeof v === 'object' && !(v instanceof Uint8Array)) return v;
+  const t = textOf(v).trim();
+  if (t === '' || t === 'null') return null;
+  let d;
+  try { d = JSON.parse(t); } catch { d = undefined; }
+  if (d == null || typeof d !== 'object') throw new Error(`opencode: unreadable ${what}`);   // a damaged read
+  return d;
+}
+/** A row's `data` column: unparsable is a damaged read, so it throws rather than read as empty. */
+const rowData = (r, table) => strictJson(r.data, `${table}.data for ${r.id}`) || {};
+const eventData = (e) => strictJson(e.data, `event.data for ${e.id}`) || {};
+const num = (v) => { const x = Number(v); return Number.isFinite(x) ? x : null; };
+const ms = (v) => { const x = num(v); return x && x > 0 ? x : null; };
+const sha256 = (b) => crypto.createHash('sha256').update(b).digest('hex');
+const byOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** The ms an ascending OpenCode id (msg_, prt_, evt_, tool_) was minted at, taken at or after `ref`. */
+function idTime(id, ref) {
+  const m = /^[a-z]+_([0-9a-f]{12})/.exec(String(id));
+  if (!m) return null;
+  const x = Math.floor(parseInt(m[1], 16) / 4096) % MS_MOD;
+  const base = Math.max(0, Number(ref) - ID_SLACK_MS);
+  return base + (((x - (base % MS_MOD)) % MS_MOD) + MS_MOD) % MS_MOD;
+}
+
+/** sha256 + length of a spilled tool output, `<data>/tool-output/tool_<id>`. Only that folder. */
+function spilled(spillDir, p) {
+  const ref = path.basename(String(p || ''));
+  if (!SPILL.test(ref)) return null;
+  if (!spillDir) return { ref, sha: null, len: null };
+  try {
+    const file = path.join(spillDir, ref);
+    if (!fs.lstatSync(file).isFile()) return { ref, sha: null, len: null };
+    const buf = fs.readFileSync(file);
+    return { ref, sha: sha256(buf), len: buf.length };
+  } catch { return { ref, sha: null, len: null }; }
+}
+
+/** A non-file URL cut to scheme://host (its path and query may carry a token), else one marker. */
+function hideUrl(v) {
+  try {
+    const u = new URL(String(v));
+    if (u.host) return `${u.protocol}//${u.host}`;
+  } catch { /* not a URL */ }
+  return `<redacted len=${Buffer.byteLength(String(v), 'utf8')}>`;
+}
+
+/** A file part from a v1 FilePart or a v2 attachment: a data: URL by the sha of its bytes, else a ref. */
+function filePart(partId, f, extra = {}) {
+  const url = String(f.url || f.uri || '');
+  let mime = f.mime || f.mediaType || '';
+  let bytes = null;
+  let ref = '';
+  const dm = /^data:([^;,]*)((?:;[^;,]*)*),(.*)$/s.exec(url);
+  if (dm) {
+    if (!mime) mime = dm[1];
+    try { bytes = /;base64/i.test(dm[2]) ? Buffer.from(dm[3], 'base64') : Buffer.from(decodeURIComponent(dm[3]), 'utf-8'); } catch { bytes = null; }
+    ref = f.filename || f.name || '';
+  } else if (url.startsWith('file:')) {
+    try { ref = fileURLToPath(url); } catch { ref = url.split(/[?#]/)[0]; }
+  } else if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^[a-z]:[\\/]/i.test(url)) {   // C:\… or C:/… is a path
+    ref = hideUrl(url);   // http(s), MCP resource and other URLs: a query string may carry a token
+  } else {
+    ref = url || f.filename || f.name || '';
+  }
+  return { part_id: partId, kind: 'file', media_type: mime, att_sha: bytes ? sha256(bytes) : null, att_len: bytes ? bytes.length : null, ref, ...extra };
+}
+
+function usageOf(t, cost) {
+  if (!t) return null;
+  const c = t.cache || {};
+  const u = { basis: 'net', input: num(t.input) || 0, output: num(t.output) || 0, cache_read: num(c.read) || 0, cache_write: num(c.write) || 0, reasoning: num(t.reasoning) || 0 };
+  if (!u.input && !u.output && !u.cache_read && !u.cache_write && !u.reasoning) return null;   // a stored all-zero is unknown
+  return { ...u, cost: num(cost) > 0 ? num(cost) : null };
+}
+function sumUsage(steps) {
+  const acc = { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } };
+  let cost = 0;
+  for (const d of steps) {
+    const t = d.tokens || {};
+    acc.input += num(t.input) || 0; acc.output += num(t.output) || 0; acc.reasoning += num(t.reasoning) || 0;
+    acc.cache.read += num(t.cache && t.cache.read) || 0; acc.cache.write += num(t.cache && t.cache.write) || 0;
+    cost += num(d.cost) || 0;
+  }
+  return usageOf(acc, cost);
+}
+function errorText(e) {
+  if (!e) return '';
+  if (typeof e === 'string') return e;
+  const d = e.data || {};
+  const msg = typeof d.message === 'string' ? d.message : (typeof e.message === 'string' ? e.message : '');
+  const name = e.name || e.type || '';
+  return [name, msg].filter(Boolean).join(': ') || 'error';
+}
+const effortOf = (v) => (v && v !== 'default' ? String(v) : '');
+const toolStatus = (status, error) => (status === 'error' ? (/rejected permission/i.test(String(error || '')) ? 'denied' : 'error') : (status === 'completed' ? 'completed' : 'interrupted'));
+
+// ── v1 engine ─────────────────────────────────────────────────────────────────────────────────
+function v1Tool(p, d, spillDir) {
+  const st = d.state || {};
+  const meta = st.metadata || {};
+  const done = st.status === 'completed' || st.status === 'error';
+  const part = {
+    part_id: p.id, kind: 'tool', call_id: d.callID || '', tool: d.tool || '',
+    args: st.input ?? {},
+    output: st.status === 'completed' ? String(st.output ?? '') : (st.status === 'error' ? String(st.error ?? '') : null),
+    is_error: st.status === 'error', status: toolStatus(st.status, st.error), ts: ms(p.time_created),
+  };
+  if (done && Number.isFinite(meta.exit)) part.exit_code = meta.exit;
+  if (meta.outputPath) { const r = spilled(spillDir, meta.outputPath); if (r) part.output_ref = r; }
+  return part;
+}
+
+/** v1 rows → { items: the message and lifecycle records in native order, children }, held-back cut applied. */
+function v1Records(rows, ctx) {
+  const partsOf = new Map();
+  for (const p of rows.parts || []) {
+    const d = rowData(p, 'part');
+    if (!partsOf.has(p.message_id)) partsOf.set(p.message_id, []);
+    partsOf.get(p.message_id).push({ ...p, d });
+  }
+  for (const l of partsOf.values()) l.sort((a, b) => byOrder(String(a.id), String(b.id)));
+  const msgs = (rows.messages || []).map((m) => ({ ...m, d: rowData(m, 'message'), parts: partsOf.get(m.id) || [] }))
+    .sort((a, b) => (Number(a.time_created) - Number(b.time_created)) || byOrder(String(a.id), String(b.id)));
+  const byId = new Map(msgs.map((m) => [m.id, m]));
+  const isShell = (m) => m.d.role === 'assistant' && !m.d.finish && !m.d.error
+    && m.parts.some((p) => p.d.type === 'tool') && !m.parts.some((p) => p.d.type === 'step-start' || p.d.type === 'step-finish');
+  const shellParents = new Set(msgs.filter(isShell).map((m) => m.d.parentID));
+  const compactionOf = (m) => m.parts.find((p) => p.d.type === 'compaction');
+
+  // Held back: the first assistant still streaming with no later assistant; everything after it waits.
+  let cut = msgs.length;
+  for (let i = 0; i < msgs.length; i++) {
+    const d = msgs[i].d;
+    if (d.role !== 'assistant' || (d.time && d.time.completed) || d.error) continue;
+    if (!msgs.slice(i + 1).some((m) => m.d.role === 'assistant')) { cut = i; break; }
+  }
+
+  // The live revert: v1 hides the revert message and everything after it.
+  const rv = ctx.revert;
+  let revertAt = -1;
+  let revertPart = null;
+  if (rv && rv.messageID) {
+    revertAt = msgs.findIndex((m) => m.id === rv.messageID);
+    if (revertAt >= 0 && rv.partID && msgs[revertAt].parts.some((p) => p.id === rv.partID)) revertPart = rv.partID;
+  }
+
+  const items = [];
+  const children = [];
+  for (let i = 0; i < cut; i++) {
+    const m = msgs[i];
+    const d = m.d;
+    const role = d.role === 'assistant' ? 'assistant' : 'user';
+    const state = revertAt >= 0 && (i > revertAt || (i === revertAt && !revertPart)) ? 'reverted' : 'current';
+    const hideFrom = i === revertAt && revertPart ? revertPart : null;
+    const parts = [];
+    const push = (p, raw) => {
+      if (hideFrom && String(raw.id) >= hideFrom) p.hidden = true;
+      parts.push(p);
+    };
+    const summary = role === 'assistant' && (d.summary === true || d.mode === 'compaction' || d.agent === 'compaction');
+    const trigger = summary && byId.get(d.parentID) ? compactionOf(byId.get(d.parentID)) : null;
+    const replaces = trigger && trigger.d.tail_start_id ? { first_kept_id: trigger.d.tail_start_id } : 'unknown';
+    for (const p of m.parts) {
+      const x = p.d;
+      const ts = ms(p.time_created);
+      const inj = x.synthetic ? { source: 'injected' } : {};
+      if (x.type === 'text') {
+        push(summary ? { part_id: p.id, kind: 'summary', text: String(x.text ?? ''), replaces, ts } : { part_id: p.id, kind: 'text', text: String(x.text ?? ''), ts, ...inj }, p);
+      } else if (x.type === 'reasoning') {
+        push(x.text ? { part_id: p.id, kind: 'reasoning', text: String(x.text), ts } : { part_id: p.id, kind: 'reasoning', text: '', opaque: true, ts }, p);
+      } else if (x.type === 'tool') {
+        const tp = v1Tool(p, x, ctx.spillDir);
+        push(tp, p);
+        const child = x.tool === 'task' && x.state && x.state.metadata ? x.state.metadata.sessionId : null;
+        if (child && !children.some((c) => c.session_id === String(child) && c.at === tp.call_id)) children.push({ kind: 'subagent', session_id: String(child), evidence: 'explicit', after: m.id, at: tp.call_id });
+        const atts = (x.state && x.state.status === 'completed' && Array.isArray(x.state.attachments)) ? x.state.attachments : [];
+        atts.forEach((a, j) => push(filePart(a.id || `${p.id}:att:${j}`, a, { ts }), p));
+      } else if (x.type === 'file') {
+        push(filePart(p.id, x, { ts, ...inj }), p);
+      } else if (x.type === 'subtask') {
+        push({ part_id: p.id, kind: 'text', text: String(x.prompt ?? ''), ts }, p);
+      } else if (x.type === 'patch') {
+        push({ part_id: p.id, kind: 'notice', text: (Array.isArray(x.files) ? x.files : []).map(String).join('\n'), ts }, p);
+      }
+      // compaction (lifecycle below), step-start, step-finish (usage), snapshot, retry, agent: left out
+    }
+    const rec = { k: 'message', message_id: m.id, role, ts: ms(m.time_created), order: 0, state, status: 'complete' };
+    if (d.parentID) rec.parent_id = d.parentID;
+    if (role === 'user') {
+      const comp = compactionOf(m);
+      const content = m.parts.filter((p) => ['text', 'file', 'subtask'].includes(p.d.type));
+      if (comp && comp.d.auto) rec.source = 'automated';
+      else if (!comp && content.length && content.every((p) => p.d.synthetic) && !shellParents.has(m.id)) rec.source = 'automated';
+    } else if (role === 'assistant') {
+      const parent = byId.get(d.parentID);
+      const req = parent && parent.d.model ? parent.d.model : null;
+      rec.model = d.modelID || (d.model && d.model.modelID) || '';
+      if (req && req.modelID && req.modelID !== rec.model) rec.model_requested = req.modelID;
+      rec.effort = effortOf(d.variant || (req && req.variant));
+      if (isShell(m)) rec.source = 'user';
+      if (d.error) {
+        rec.status = d.error.name === 'MessageAbortedError' ? 'interrupted' : 'error';
+        parts.push({ part_id: 'error', kind: 'error', text: errorText(d.error) });
+      } else if (!(d.time && d.time.completed)) {
+        rec.status = 'interrupted';           // a dead run: a later assistant took over
+      } else if (!d.finish && !isShell(m) && !parts.length) {
+        rec.status = 'interrupted';           // overflow: completed with no finish, error or parts
+      }
+      const steps = m.parts.filter((p) => p.d.type === 'step-finish').map((p) => p.d);
+      rec.usage = steps.length ? sumUsage(steps) : usageOf(d.tokens, d.cost);
+    }
+    rec.parts = parts;
+    items.push({ rec, ts: Number(m.time_created) });
+    // Compaction: the trigger's lifecycle record follows it.
+    const comp = role === 'user' ? compactionOf(m) : null;
+    if (comp) {
+      // Replaced: everything before tail_start_id; with none, everything before the trigger.
+      const tail = comp.d.tail_start_id ? msgs.findIndex((x) => x.id === comp.d.tail_start_id) : i;
+      const through = tail > 0 ? msgs[tail - 1].id : null;
+      items.push({ rec: { k: 'lifecycle', event: 'compaction', at: ms(m.time_created), ...(through ? { through } : {}) }, ts: Number(m.time_created), after: true });
+    }
+  }
+
+  // Edits: rows deleted on prompt-while-reverted, as their message.removed events say.
+  const groups = [];
+  for (const e of ctx.events || []) {
+    const t = String(e.type || '');
+    if (!/^message\.(part\.)?removed\./.test(t)) continue;
+    const d = eventData(e);
+    const mid = d.messageID || (d.part && d.part.messageID);
+    if (!mid) continue;
+    const last = groups[groups.length - 1];
+    if (last && Number(e.seq) === last.seq + 1) { last.seq = Number(e.seq); if (!last.ids.includes(mid)) last.ids.push(mid); continue; }
+    groups.push({ seq: Number(e.seq), id: e.id, ids: [mid] });
+  }
+  for (const g of groups) {
+    const at = idTime(g.id, ctx.created);
+    let pos = items.findIndex((x) => x.rec.k === 'message' && !x.after && x.ts >= at);
+    if (pos < 0) pos = items.length;
+    const prev = items.slice(0, pos).filter((x) => x.rec.k === 'message').pop();
+    items.splice(pos, 0, { rec: { k: 'lifecycle', event: 'edit', at, message_ids: g.ids, ...(prev ? { through: prev.rec.message_id } : {}) }, ts: at, after: true });
+  }
+  return { items: items.map((x) => x.rec), children };
+}
+
+// ── v2 engine ─────────────────────────────────────────────────────────────────────────────────
+function v2Content(c, spillDir, ts) {
+  if (c.type === 'text') return [{ part_id: String(c.id), kind: 'text', text: String(c.text ?? ''), ts }];
+  if (c.type === 'reasoning') return [c.text ? { part_id: String(c.id), kind: 'reasoning', text: String(c.text), ts } : { part_id: String(c.id), kind: 'reasoning', text: '', opaque: true, ts }];
+  if (c.type !== 'tool') return [];
+  const st = c.state || {};
+  const time = c.time || {};
+  const done = st.status === 'completed' || st.status === 'error';
+  const text = Array.isArray(st.content) ? st.content.map((x) => (typeof x === 'string' ? x : (x && x.text) || '')).join('') : '';
+  const part = {
+    part_id: String(c.id), kind: 'tool', call_id: String(c.id), tool: c.name || '',
+    args: typeof st.input === 'string' ? { raw: st.input } : (st.input ?? {}),
+    output: st.status === 'completed' ? text : (st.status === 'error' ? (text || errorText(st.error)) : null),
+    is_error: st.status === 'error', status: toolStatus(st.status, errorText(st.error)), ts: ms(time.created) || ts,
+  };
+  const s = st.structured || {};
+  if (done && Number.isFinite(s.exit)) part.exit_code = s.exit;
+  const out = (Array.isArray(st.outputPaths) ? st.outputPaths : []).find((p) => SPILL.test(path.basename(String(p))));
+  if (out) { const r = spilled(spillDir, out); if (r) part.output_ref = r; }
+  const parts = [part];
+  (st.status === 'completed' && Array.isArray(st.attachments) ? st.attachments : []).forEach((a, j) => parts.push(filePart(`${c.id}:att:${j}`, a, { ts })));
+  return parts;
+}
+
+function v2Records(rows, ctx) {
+  const inputs = new Map((rows.session_inputs || []).map((r) => [String(r.id), r]));
+  const msgs = (rows.session_messages || []).map((m) => ({ ...m, d: rowData(m, 'session_message') }))
+    .sort((a, b) => (Number(a.seq) - Number(b.seq)) || byOrder(String(a.id), String(b.id)));
+
+  let cut = msgs.length;
+  for (let i = 0; i < msgs.length; i++) {
+    const m = msgs[i];
+    if (m.type !== 'assistant' || (m.d.time && m.d.time.completed) || m.d.error) continue;
+    if (!msgs.slice(i + 1).some((x) => x.type === 'assistant')) { cut = i; break; }
+  }
+  // The live revert: v2 hides what follows the staged message (a commit deletes that, keeps it).
+  const rv = ctx.revert;
+  const revertAt = rv && rv.messageID ? msgs.findIndex((m) => m.id === rv.messageID) : -1;
+
+  const items = [];
+  const children = [];
+  for (let i = 0; i < cut; i++) {
+    const m = msgs[i];
+    const d = m.d;
+    const ts = ms(m.time_created) || ms(d.time && d.time.created);
+    const rec = { k: 'message', message_id: String(m.id), role: 'user', ts, order: 0, state: revertAt >= 0 && i > revertAt ? 'reverted' : 'current', status: 'complete' };
+    const parts = [];
+    if (m.type === 'user') {
+      if (d.text != null && d.text !== '') parts.push({ part_id: '0', kind: 'text', text: String(d.text) });
+      (Array.isArray(d.files) ? d.files : []).forEach((f, j) => parts.push(filePart(String(j + 1), f)));
+      const inp = inputs.get(String(m.id));
+      if (inp) rec.raw = { session_input: { delivery: inp.delivery, admitted_seq: num(inp.admitted_seq), promoted_seq: num(inp.promoted_seq) } };
+    } else if (m.type === 'synthetic') {
+      rec.source = 'injected';
+      parts.push({ part_id: '0', kind: 'text', text: String(d.text ?? ''), source: 'injected' });
+    } else if (m.type === 'system') {
+      rec.role = 'system';
+      rec.source = 'injected';
+      parts.push({ part_id: '0', kind: 'notice', text: String(d.text ?? '') });
+    } else if (m.type === 'shell') {
+      parts.push({
+        part_id: String(d.callID || 'shell'), kind: 'tool', call_id: String(d.callID || ''), tool: 'bash', args: { command: String(d.command ?? '') },
+        output: d.time && d.time.completed ? String(d.output ?? '') : null, is_error: false, status: d.time && d.time.completed ? 'completed' : 'interrupted',
+      });
+    } else if (m.type === 'compaction') {
+      items.push({ rec: { k: 'lifecycle', event: 'compaction', at: ts, ...(i > 0 ? { through: String(msgs[i - 1].id) } : {}) }, seq: Number(m.seq) });
+      rec.role = 'system';
+      if (d.reason === 'auto') rec.source = 'automated';
+      parts.push({ part_id: '0', kind: 'summary', text: String(d.summary ?? ''), replaces: 'unknown' });
+    } else if (m.type === 'assistant') {
+      rec.role = 'assistant';
+      const model = d.model || {};
+      rec.model = model.id || '';
+      rec.effort = effortOf(model.variant);
+      for (const c of Array.isArray(d.content) ? d.content : []) {
+        parts.push(...v2Content(c, ctx.spillDir, ts));
+        if (c.type === 'tool' && c.name === 'task') {
+          const s = (c.state && (c.state.structured || c.state.metadata)) || {};
+          if (s.sessionId) children.push({ kind: 'subagent', session_id: String(s.sessionId), evidence: 'explicit', after: rec.message_id, at: String(c.id) });
+        }
+      }
+      if (d.error) {
+        rec.status = /abort/i.test(errorText(d.error)) ? 'interrupted' : 'error';
+        parts.push({ part_id: 'error', kind: 'error', text: errorText(d.error) });
+      } else if (!(d.time && d.time.completed)) rec.status = 'interrupted';
+      rec.usage = usageOf(d.tokens, d.cost);
+    } else {
+      continue;   // agent-switched, model-switched: session bookkeeping, not conversation
+    }
+    rec.parts = parts;
+    items.push({ rec, seq: Number(m.seq) });
+  }
+  // A committed revert deleted rows: a rewind at its seq, back to the staged message.
+  for (const e of ctx.events || []) {
+    if (!/^session\.next\.revert\.committed\./.test(String(e.type || ''))) continue;
+    const d = eventData(e);
+    let pos = items.findIndex((x) => x.rec.k === 'message' && x.seq > Number(e.seq));
+    if (pos < 0) pos = items.length;
+    items.splice(pos, 0, { rec: { k: 'lifecycle', event: 'rewind', at: ms(d.timestamp), ...(d.messageID ? { through: String(d.messageID) } : {}) }, seq: Number(e.seq) });
+  }
+  return { items: items.map((x) => x.rec), children };
+}
+
+/** The revert in force: the session's `revert`, else a v2 revert staged and not yet committed or cleared. */
+function liveRevert(session, events) {
+  const r = strictJson(session.revert, `session.revert for ${session.id}`);
+  if (r && r.messageID) return r;
+  let staged = null;
+  for (const e of events || []) {
+    const t = String(e.type || '');
+    if (/^session\.next\.revert\.staged\./.test(t)) staged = eventData(e).revert || null;
+    else if (/^session\.next\.revert\.(committed|cleared)\./.test(t)) staged = null;
+  }
+  return staged && staged.messageID ? staged : null;
+}
+
+/**
+ * Normalise one session: a list() entry (`{ harness_path, session_id, db_rel, spill_rel, key }`: the DB
+ * and the spill folder rebuilt from harness_path), or its rows already loaded (tests):
+ * `{ session_id, session, messages, parts, session_messages, session_inputs, events, data_dir }`,
+ * JSON columns as strings or objects. Returns the log records, the session record first; null when
+ * the session is not in the store.
+ */
+function normalise(session) {
+  const fromStore = typeof session.db_rel === 'string' && session.harness_path;
+  const rows = fromStore ? readSession(path.join(session.harness_path, session.db_rel), session.session_id) : session;
+  if (!rows || !rows.session) return null;
+  const s = rows.session;
+  const events = rows.events || [];
+  const spillDir = fromStore ? path.join(session.harness_path, String(session.spill_rel ?? 'tool-output'))
+    : (rows.data_dir ? path.join(rows.data_dir, 'tool-output') : null);
+  const ctx = { spillDir, revert: liveRevert(s, events), events, created: Number(s.time_created) || 0 };
+  const hasV2 = (rows.session_messages || []).length > 0;
+  const v1 = (rows.messages || []).length || !hasV2 ? v1Records(rows, ctx) : { items: [], children: [] };
+  const v2 = hasV2 ? v2Records(rows, ctx) : { items: [], children: [] };
+  const records = [...v1.items, ...v2.items];   // both engines in one session: not observed; v1 first
+  let order = 0;
+  for (const r of records) if (r.k === 'message') r.order = order++;
+  const children = [...v1.children, ...v2.children];
+  const head = {
+    k: 'session',
+    title: s.title || '', cwd: s.directory || '', version: s.version || '',
+    created: ms(s.time_created), updated: null, archived: ms(s.time_archived),
+    incarnation: '', engine: hasV2 ? 'v2' : 'v1',
+    links: s.parent_id ? [{ kind: 'subagent', origin: String(s.parent_id), evidence: 'explicit', at: '' }] : [],
+    ...(children.length ? { children } : {}),
+  };
+  return placeChildren([head, ...records]);
+}
+
+module.exports = { HARNESS, list, normalise, storeRootDefault, dbFiles, idTime, readSession };