@volter/supercode-orchestrator 0.4.148 → 0.4.149

package/board/ztrack.mjs

@@ -1,40 +1,53 @@
-// The document is card state; SQLite here is only a runtime journal and Hermes projection.
-// ADR 0001. All markdown interpretation belongs to ztrack's public codec and kanban preset.
+// The document is card state. One SQLite file beside it keeps the runtime tables the engine speaks
+// (Hermes's, with supercode's own) and an index of the document's card spans. ADR 0001 and 0003.
+// All markdown interpretation belongs to ztrack's public codec and kanban preset.
+//
+// A write is SQLite's own deferred transaction, retried whole when another writer committed first
+// (no file lock, no BEGIN IMMEDIATE, no busy timeout). The engine writes the tables in place;
+// triggers name the rows it touched. Only the cards whose text changed are rendered, and each is
+// spliced into the document at its indexed span. A document edited by hand is re-read only in the
+// region the edit touched. So a write costs what it changes, not the size of the board.
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { RuntimeRows } from './rows.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { actorOf, event, json, now, setActor } from './store.mjs';
-import { fire, projectStatus, statusOf, workflowFor } from './workflow.mjs';
+import { fire, statusOf, storedStatus, workflowFor } from './workflow.mjs';
 import { completionPhase, inspectCompletionEvidence, withCompletionEvidence } from './ci.mjs';
 
 const require = createRequire(import.meta.url);
 const hash = (text) => createHash('sha256').update(text).digest('hex');
 const read = (path) => existsSync(path) ? readFileSync(path, 'utf8') : '';
-const quote = (s) => `"${s.replaceAll('"', '""')}"`;
+const lf = (text) => text.replace(/\r\n?/g, '\n');
+const quote = (s) => `"${String(s).replaceAll('"', '""')}"`;
 const nativeId = (id) => /^t-[a-f0-9]+$/.test(id) ? id.replace('t-', 't_') : id;
 const RUNTIME = new Set(['claim_lock', 'claim_expires', 'worker_pid', 'last_heartbeat_at', 'current_run_id', 'consecutive_failures', 'last_failure_error', 'block_recurrences', 'session_id', 'workspace_path']);
 const CARD_MAIN = new Set(['id', 'title', 'body', 'status', 'assignee', 'priority', 'workspace_kind', 'workspace_path', 'branch_name']);
-const EPHEMERAL = new Set(['tasks', 'supercode_cards', 'task_links', 'sqlite_sequence']);
+const CLOCKS = new Set(['since', 'after_fired', 'next_run_at', 'workspace_root']);
 const atomic = (path, text) => { const tmp = `${path}.${process.pid}.tmp`; writeFileSync(tmp, text, { mode: 0o600 }); renameSync(tmp, path); };
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const backoff = (attempt) => sleep(Math.min(40, 2 ** Math.min(attempt, 5)) * (0.5 + Math.random()));
 
-// Only SQLite's actual contention codes retry. Rule refusals can contain words
-// such as "blocked" or "busy" and must reach the caller unchanged.
+// Only SQLite's actual contention codes retry (BUSY, BUSY_SNAPSHOT, LOCKED). Rule refusals can
+// contain words such as "blocked" or "busy" and must reach the caller unchanged.
 const sqliteContention = error => [5, 6].includes(Number(error?.errcode) & 255)
   || ['SQLITE_BUSY', 'SQLITE_LOCKED'].includes(error?.code)
   || /^database (?:table |schema )?is locked$/i.test(error?.message ?? '');
-const exportConflict = error => error?.message === 'Hermes wrote during board export; retained its events for the next read';
-const recoveryConflict = error => error?.message === 'document changed during recovery; retry';
-// One-shot verbs open the same board several times. Share byte-keyed codec
-// work across those instances and cap retention for long-running dispatchers.
-const documentCache = new Map(), renderCache = new Map();
-function remember(cache, path, value) {
-  cache.delete(path);
-  cache.set(path, value);
-  while (cache.size > 8) cache.delete(cache.keys().next().value);
-}
+const RETRY = new Error('board changed while this operation read it; retry');
+
+const BOARD_TABLES = `
+CREATE TABLE IF NOT EXISTS board_state (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS board_chunks (cid INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS board_tasks (id TEXT PRIMARY KEY, key TEXT NOT NULL, sources TEXT);
+CREATE INDEX IF NOT EXISTS board_tasks_key ON board_tasks(key);
+CREATE TABLE IF NOT EXISTS board_errors (id TEXT PRIMARY KEY, reason TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS board_export (name TEXT NOT NULL, key TEXT NOT NULL, rev INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (name, key));`;
+// board_state: `published` (each document's hash as the tables describe it), `chunks:<role>` (the
+// document's spans in order: chunk id, card id, heading level, length, and the hash of the card
+// record the span reads as), `pending` and `pending_hashes` (a publication committed but not yet
+// written to the document), `hermes_cursor`. board_tasks: a subtask's key on its arc's Tasks list
+// (`<arc>:c3`) and its `source:` lines, which live only in the document.
 
 export function openZtrackBoard(marker, { create = false, document = null, seed = null, init, root, slug, compatPath }) {
   if (!existsSync(marker)) {
@@ -44,6 +57,8 @@ export function openZtrackBoard(marker, { create = false, document = null, seed
   }
   const config = JSON.parse(read(marker));
   const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, compatPath });
+  // A board made here is in Hermes's kanban.db at once, not after its first write.
+  if (create) backing.exportFollowing();
   return { db: backing.db, tx: (fn) => backing.tx(fn), close: () => backing.close(), document: backing.path };
 }
 
@@ -51,549 +66,731 @@ class ZtrackBoard {
   constructor({ document, seed, marker, init, root, slug, compatPath }) {
     this.path = resolve(dirname(marker), document);
     this.archive = `${this.path}.archive.md`;
-    this.seed = seed;
-    this.root = root; this.slug = slug; this.init = init; this.compatPath = compatPath;
-    this.runtimePath = `${marker}.runtime.db`;
-    this.runtime = new DatabaseSync(this.runtimePath);
-    this.readOnly(()=>{ if (!this.runtime.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='state'").get()) this.runtime.exec('CREATE TABLE IF NOT EXISTS state (key TEXT PRIMARY KEY, value TEXT NOT NULL)'); });
-    this.errors = new Map(); this.preserve = new Map();
-    // Codec projections depend on document bytes, not runtime revisions. Keep one
-    // entry per document across optimistic retries; run/event churn must not
-    // repeatedly parse an unchanged board before reaching its version check.
-    this.mem = null; this.active = false; this.rows = new RuntimeRows(this.runtime);
+    this.docs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
+    this.seed = seed; this.root = root; this.slug = slug; this.init = init; this.compatPath = compatPath;
+    this.file = `${marker}.board.db`;
     mkdirSync(dirname(this.path), { recursive: true });
+    if (!existsSync(this.file)) this.create(`${marker}.runtime.db`);
+    this.conn = new DatabaseSync(this.file);
+    this.errors = new Map(); this.statements = new Map(); this.hashes = new Map();
+    this.active = false; this.overlay = false; this.seen = null;
+    this.prepareConnection();
+    this.loadErrors();
     const self = this;
     this.db = {
       boardErrors: self.errors,
-      prepare(sql) { return Object.fromEntries(['get', 'all', 'run', 'iterate'].map((method) => [method, (...args) => self.access(() => method === 'iterate' ? self.mem.prepare(sql).all(...args)[Symbol.iterator]() : self.mem.prepare(sql)[method](...args), method !== 'run')])); },
-      exec(sql) { return self.access(() => self.mem.exec(sql)); },
+      prepare(sql) {
+        return {
+          get: (...args) => self.read(() => self.statement(sql).get(...args)),
+          all: (...args) => self.read(() => self.statement(sql).all(...args)),
+          iterate: (...args) => self.read(() => self.statement(sql).all(...args))[Symbol.iterator](),
+          run: (...args) => self.active ? self.statement(sql).run(...args) : self.tx(() => self.statement(sql).run(...args)),
+        };
+      },
+      exec(sql) { return self.active ? self.conn.exec(sql) : self.tx(() => self.conn.exec(sql)); },
       close() { self.close(); },
     };
     if (seed) this.tx(() => {});
-    else this.readOnly(()=>{ this.load(); this.loadedStamp = this.stamp(); });
   }
   get codec() { return this._codec ??= require('@volter/ztrack/board-document'); }
   get preset() { return this._preset ??= require('@volter/ztrack/kanban-preset'); }
-  get(key, fallback = null) { return this.computing && this.pendingValues.has(key) ? this.pendingValues.get(key) : json(this.runtime.prepare('SELECT value FROM state WHERE key = ?').get(key)?.value, fallback); }
-  put(key, value) { if (this.computing) { this.pendingValues.set(key, value); return; } this.runtime.prepare('INSERT INTO state VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, JSON.stringify(value)); }
-  stamp() {
-    const fileStamp = (path) => { try { const s = statSync(path); return `${s.ino}:${s.size}:${s.mtimeMs}`; } catch { return 'missing'; } };
-    return [fileStamp(this.path), fileStamp(this.archive), fileStamp(this.compatPath), this.get('version', '')].join('|');
-  }
-  readOnly(fn) { for (;;) { try { return fn(); } catch(error) { if(!sqliteContention(error))throw error; } } }
-  access(fn, reading = false) {
-    if (reading && !this.reading) { this.reading=true; try {return this.readOnly(()=>this.access(fn,true));}finally{this.reading=false;} }
-    if (this.active || (reading && this.mem && this.loadedStamp === this.stamp())) return fn();
-    if (reading) { this.load(); this.loadedStamp = this.stamp(); return fn(); }
-    return this.tx(fn);
-  }
-  close() { this.mem?.close(); this.runtime.close(); }
   board() { return { root: this.root, slug: this.slug, label: this.slug, db: this.db }; }
-  recover() {
-    const pending = this.get('pending');
-    if (!pending) return;
-    const conflicts = new Set(), documentConflicts = new Set();
-    const observed = pending.files.map(file=>({...file,current:read(file.path)}));
-    for (const file of observed) {
-      const current=hash(file.current);
-      if(current===hash(file.text)||current===file.before)continue;
-      const ids=file.base!=null?this.codec.mergeBoardDocument(file.base,file.current,file.text,file.path).conflicts:this.codec.inspectBoardDocument(file.text,file.path).records.map(r=>r.id);
-      for(const id of ids){conflicts.add(nativeId(id));documentConflicts.add(id);}
-    }
-    for (const file of observed) {
-      const merged=file.base!=null?this.codec.mergeBoardDocument(file.base,file.current,file.text,file.path,[...documentConflicts]).text:(hash(file.current)===file.before?file.text:file.current);
-      if (hash(read(file.path))!==hash(file.current)) throw new Error('document changed during recovery; retry');
-      if (merged!==file.current)atomic(file.path,merged);
-    }
-    const changes = (pending.changes ?? []).filter(c => !conflicts.has(c.source?.row?.task_id ?? c.source?.row?.id ?? c.key));
-    if (pending.changes) { this.rows.write(changes); this.put('export_pending', [...this.get('export_pending', []), ...changes]); }
-    if (conflicts.size) {
-      const issues = this.get('recovery_conflicts', {});
-      for (const id of conflicts) issues[id] = {intent:pending.intent,reason:'A concurrent document edit superseded an unfinished operation on this card.'};
-      this.put('recovery_conflicts', issues);
-      const old = this.get('snapshot', {});
-      for (const id of conflicts) {
-        if (old.fingerprints?.[id]) pending.snapshot.fingerprints[id] = old.fingerprints[id];
-        else delete pending.snapshot.fingerprints?.[id];
+  close() { this.dropOverlay(); this.conn.close(); }
+
+  statement(sql) {
+    let statement = this.statements.get(sql);
+    if (!statement) { statement = this.conn.prepare(sql); this.statements.set(sql, statement); }
+    return statement;
+  }
+  one(sql, ...args) { return this.statement(sql).get(...args); }
+  stateText(key) { return this.one('SELECT value FROM main.board_state WHERE key = ?', key)?.value ?? null; }
+  get(key, fallback = null) { return json(this.stateText(key), fallback); }
+  put(key, value) { this.statement('INSERT INTO main.board_state VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, JSON.stringify(value)); }
+  drop(key) { this.statement('DELETE FROM main.board_state WHERE key = ?').run(key); }
+  loadErrors() {
+    this.errors.clear();
+    for (const row of this.statement('SELECT id, reason FROM main.board_errors').all()) this.errors.set(row.id, row.reason);
+  }
+
+  // ------------------------------------------------------------------ the connection
+
+  prepareConnection() {
+    this.conn.exec('PRAGMA foreign_keys = OFF');
+    for (let attempt = 0; ; attempt++) {
+      try { this.init(this.conn, { fresh: true }); this.conn.exec(BOARD_TABLES); break; }
+      catch (error) { if (!sqliteContention(error)) throw error; backoff(attempt); }
+    }
+    // What a transaction touched, for the Hermes export (every row) and the renderer (cards whose
+    // text may change: anything beyond run fields and scheduling clocks). Plain inserts: a trigger's
+    // own conflict clause yields to the outer statement's, so duplicates are removed when read.
+    this.conn.exec('CREATE TEMP TABLE IF NOT EXISTS board_dirty (name TEXT NOT NULL, key TEXT NOT NULL); CREATE TEMP TABLE IF NOT EXISTS board_touched (id TEXT)');
+    this.tables = new Map();
+    const names = this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all().map((row) => row.name);
+    const trigger = (name, when, body) => this.conn.exec(`CREATE TEMP TRIGGER IF NOT EXISTS ${quote(name)} ${when} BEGIN ${body} END`);
+    for (const name of names) {
+      const columns = this.conn.prepare(`PRAGMA main.table_info(${quote(name)})`).all();
+      const keys = columns.filter((c) => c.pk).sort((a, b) => a.pk - b.pk).map((c) => c.name);
+      if (!keys.length) keys.push('rowid');
+      this.tables.set(name, { name, keys, columns: columns.map((c) => c.name) });
+      const key = (row) => `json_array(${keys.map((k) => `${row}.${quote(k)}`).join(',')})`;
+      const mark = (row) => `INSERT INTO board_dirty VALUES ('${name}', ${key(row)});`;
+      trigger(`board_i_${name}`, `AFTER INSERT ON main.${quote(name)}`, mark('NEW'));
+      trigger(`board_u_${name}`, `AFTER UPDATE ON main.${quote(name)}`, mark('NEW') + mark('OLD'));
+      trigger(`board_d_${name}`, `AFTER DELETE ON main.${quote(name)}`, mark('OLD'));
+    }
+    for (const [name, id, skip] of [['tasks', 'id', RUNTIME], ['supercode_cards', 'task_id', CLOCKS]]) {
+      const changed = this.tables.get(name).columns.filter((c) => !skip.has(c)).map((c) => `OLD.${quote(c)} IS NOT NEW.${quote(c)}`).join(' OR ');
+      trigger(`board_ti_${name}`, `AFTER INSERT ON main.${quote(name)}`, `INSERT INTO board_touched VALUES (NEW.${id});`);
+      trigger(`board_tu_${name}`, `AFTER UPDATE ON main.${quote(name)} WHEN ${changed}`, `INSERT INTO board_touched VALUES (NEW.${id}); INSERT INTO board_touched VALUES (OLD.${id});`);
+      trigger(`board_td_${name}`, `AFTER DELETE ON main.${quote(name)}`, `INSERT INTO board_touched VALUES (OLD.${id});`);
+    }
+  }
+
+  // A board created from the previous runtime store imports its rows once; the old file stays as it was.
+  create(legacy) {
+    const tmp = `${this.file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    const db = new DatabaseSync(tmp);
+    try {
+      db.exec('PRAGMA journal_mode = WAL');
+      const old = existsSync(legacy) ? new DatabaseSync(legacy, { readOnly: true }) : null;
+      try {
+        const has = (name) => old?.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+        if (has('runtime_schema')) for (const row of old.prepare('SELECT sql FROM runtime_schema').all()) db.exec(row.sql.replace(/^CREATE TABLE (?!IF NOT EXISTS )/, 'CREATE TABLE IF NOT EXISTS '));
+        this.init(db, { fresh: true });
+        db.exec(BOARD_TABLES);
+        if (has('runtime_rows')) this.importRuntime(db, old, legacy);
+      } finally { old?.close(); }
+      db.close();
+    } catch (error) {
+      try { db.close(); } catch { /* closed */ }
+      for (const suffix of ['', '-wal', '-shm']) try { unlinkSync(tmp + suffix); } catch { /* absent */ }
+      throw error;
+    }
+    try { linkSync(tmp, this.file); } catch (error) { if (error.code !== 'EEXIST') throw error; } // a concurrent opener created it first
+    finally { unlinkSync(tmp); }
+  }
+
+  importRuntime(db, old, legacy) {
+    const state = (key) => json(old.prepare('SELECT value FROM state WHERE key = ?').get(key)?.value, null);
+    if (state('pending')) throw new Error(`${legacy} holds an unfinished board write; let the previous release finish it before this one opens the board`);
+    const columns = new Map();
+    const insert = (name, row) => {
+      if (!columns.has(name)) columns.set(name, new Set(db.prepare(`PRAGMA table_info(${quote(name)})`).all().map((c) => c.name)));
+      const keys = Object.keys(row).filter((k) => columns.get(name).has(k));
+      if (keys.length) db.prepare(`INSERT OR REPLACE INTO ${quote(name)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
+    };
+    db.exec('BEGIN');
+    const runtime = {}, clocks = {}, sequences = [];
+    for (const row of old.prepare('SELECT name, key, value FROM runtime_rows WHERE value IS NOT NULL').all()) {
+      const value = JSON.parse(row.value);
+      if (row.name === '@task_cache') insert('tasks', value);
+      else if (row.name === '@card_cache') insert('supercode_cards', value);
+      else if (row.name === '@runtime') runtime[row.key] = value;
+      else if (row.name === '@clock') clocks[row.key] = value;
+      else if (row.name === '@sequence') sequences.push(value);
+      else if (!row.name.startsWith('@') && !['tasks', 'supercode_cards', 'task_links', 'sqlite_sequence'].includes(row.name)) insert(row.name, value);
+    }
+    for (const [id, row] of Object.entries(runtime)) {
+      const keys = Object.keys(row).filter((k) => RUNTIME.has(k));
+      if (keys.length) db.prepare(`UPDATE tasks SET ${keys.map((k) => `${quote(k)} = ?`).join(',')} WHERE id = ?`).run(...keys.map((k) => row[k] ?? null), id);
+    }
+    for (const [id, row] of Object.entries(clocks)) db.prepare('UPDATE supercode_cards SET since = ?, after_fired = ?, next_run_at = ?, workspace_root = ? WHERE task_id = ?').run(row.since ?? null, row.after_fired ?? null, row.next_run_at ?? null, row.workspace_root ?? null, id);
+    for (const row of db.prepare('SELECT task_id, blocked_by FROM supercode_cards').all()) {
+      for (const b of json(row.blocked_by, []).filter((b) => b.kind === 'card')) db.prepare('INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)').run(b.id, row.task_id);
+    }
+    for (const { name, seq } of sequences) {
+      if (db.prepare('SELECT 1 FROM sqlite_sequence WHERE name = ?').get(name)) db.prepare('UPDATE sqlite_sequence SET seq = MAX(seq, ?) WHERE name = ?').run(seq, name);
+      else db.prepare('INSERT INTO sqlite_sequence (name, seq) VALUES (?, ?)').run(name, seq);
+    }
+    const snapshot = state('snapshot') ?? {};
+    for (const [key, id] of Object.entries(snapshot.taskIds ?? {})) db.prepare('INSERT OR REPLACE INTO board_tasks (id, key) VALUES (?, ?)').run(id, key);
+    for (const [id, reason] of snapshot.errors ?? []) db.prepare('INSERT OR REPLACE INTO board_errors VALUES (?, ?)').run(id, reason);
+    for (const change of state('export_pending') ?? []) if (change.source) db.prepare('INSERT OR IGNORE INTO board_export (name, key) VALUES (?, ?)').run(change.source.name, change.source.key);
+    const put = (key, value) => db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run(key, JSON.stringify(value));
+    put('hermes_cursor', state('hermes_cursor') ?? 0);
+    // The document as the tables last described it is indexed now, with each task's sources. A
+    // document edited since is left unindexed, so the first write reads all of it as an edit.
+    const published = {};
+    for (const { role, path } of this.docs) {
+      const raw = read(path);
+      const expected = snapshot.documentHashes?.[role === 'open' ? 'open' : 'archived'];
+      if (!expected) continue;
+      published[role] = expected;
+      if (hash(raw) !== expected) continue;
+      const entries = [];
+      for (const chunk of this.codec.chunkBoardDocument(lf(raw), path)) {
+        const cid = Number(db.prepare('INSERT INTO board_chunks (text) VALUES (?)').run(chunk.text).lastInsertRowid);
+        let rec = null;
+        if (chunk.id) {
+          const { records, errors } = this.codec.inspectBoardDocument(chunk.text, path);
+          if (!errors.length && records.length === 1) {
+            rec = hash(JSON.stringify(records[0]));
+            try {
+              const card = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([records[0]])).issues[0];
+              for (const task of card.acceptanceCriteria) {
+                if (!task.sources?.length) continue;
+                const key = `${nativeId(card.id)}:${task.id}`;
+                const id = task.metadata?.id ?? snapshot.taskIds?.[key];
+                if (id) db.prepare('INSERT INTO board_tasks (id, key, sources) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET sources = excluded.sources').run(id, key, JSON.stringify(task.sources));
+              }
+            } catch { /* its verbs refuse through the recorded error */ }
+          }
+        }
+        entries.push({ cid, id: chunk.id, level: chunk.level, len: chunk.text.length, rec });
       }
+      put(`chunks:${role}`, entries);
     }
-    this.put('snapshot', pending.snapshot);
-    if (pending.intent) this.put(`applied:${pending.intent}`, {conflicts:[...conflicts]});
-    this.put('version', randomBytes(8).toString('hex'));
-    this.runtime.prepare("DELETE FROM state WHERE key = 'pending'").run();
+    put('published', published);
+    db.exec('COMMIT');
+  }
+
+  // ------------------------------------------------------------------ reads
+
+  read(fn) {
+    if (this.active) return fn();
+    this.observeForRead();
+    for (let attempt = 0; ; attempt++) {
+      try { return fn(); } catch (error) { if (!sqliteContention(error)) throw error; backoff(attempt); }
+    }
+  }
+
+  fileHash(path) {
+    let stamp;
+    try { const s = statSync(path); stamp = `${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`; } catch { stamp = 'missing'; }
+    const known = this.hashes.get(path);
+    if (known?.stamp === stamp) return known;
+    const raw = read(path);
+    const value = { stamp, raw, hash: hash(raw) };
+    this.hashes.set(path, value);
+    return value;
   }
+
+  // A document whose hash is neither the published one nor the one a pending publication replaces
+  // was edited by hand.
+  staleDocuments({ pending }) {
+    const published = this.get('published', {});
+    const inFlight = pending ? this.get('pending_hashes', null) : null;
+    return this.docs.map((doc) => ({ ...doc, ...this.fileHash(doc.path) }))
+      .filter((doc) => doc.hash !== published[doc.role] && !(inFlight?.[doc.role] && doc.hash === inFlight[doc.role].before))
+      .map((doc) => ({ ...doc, text: lf(doc.raw) }));
+  }
+
+  // A reader sees a hand edit at once, through connection-local copies of the card tables, and
+  // writes nothing: the next write records the edit.
+  observeForRead() {
+    const stamp = [...this.docs.map((doc) => this.fileHash(doc.path).stamp), this.stateText('published'), this.stateText('pending_hashes')].join('|');
+    if (stamp === this.seen) return;
+    this.seen = stamp;
+    this.loadErrors();
+    const stale = this.staleDocuments({ pending: true });
+    if (!stale.length) { this.dropOverlay(); return; }
+    let plan;
+    try { plan = this.observe(stale); } catch { this.dropOverlay(); return; } // the next write reports it
+    this.applyPlan(plan, { overlay: true });
+  }
+
+  dropOverlay() {
+    if (!this.overlay) return;
+    this.conn.exec('DROP TABLE IF EXISTS temp.tasks; DROP TABLE IF EXISTS temp.supercode_cards; DROP TABLE IF EXISTS temp.task_links');
+    this.overlay = false; this.statements.clear();
+  }
+
+  // ------------------------------------------------------------------ writes
+
   tx(fn) {
     if (this.active) return fn(this.db);
-    return this.transaction(fn);
-  }
-
-  transaction(fn) {
-    this.readOnly(()=>{ if(this.runtime.prepare('PRAGMA journal_mode').get().journal_mode!=='wal')this.runtime.exec('PRAGMA journal_mode=WAL'); });
-    for (;;) {
-      const incoming = this.readOnly(() => this.prepareHermes());
-      if (this.cachedReader) this.invalidate();
-      try { this.runtime.exec('BEGIN'); }
-      catch (error) { if (!sqliteContention(error)) throw error; continue; }
-      this.active = true;
-      let committed = false;
+    for (let attempt = 0; ; attempt++) {
+      const hermes = this.seed ? null : this.prepareHermes();
+      this.dropOverlay();
+      let outcome;
       try {
+        this.conn.exec('BEGIN');
+        this.active = true;
+        this.conn.exec('DELETE FROM temp.board_dirty; DELETE FROM temp.board_touched');
+        this.loadErrors();
         this.recover();
-        const version = this.get('version');
-        this.runtime.exec('COMMIT');
-        // Parsing, rules and rendering run against a snapshot, without a runtime writer transaction.
-        this.pendingValues = new Map(); this.computing = true;
-        this.load({ observe: true });
-        if (incoming && (incoming.version !== version || incoming.open !== hash(this.text) || incoming.archived !== hash(this.archiveText))) {
-          this.invalidate(); continue;
+        if (this.seed) this.indexForSeed();
+        else {
+          const stale = this.staleDocuments({ pending: false });
+          if (stale.length) this.applyPlan(this.observe(stale), { overlay: false });
         }
-        if (this.seed) this.seedIntoMemory();
-        else this.lift(incoming);
+        if (hermes && hermes.cursor !== this.get('hermes_cursor', 0)) throw RETRY;
+        if (this.seed) this.seedRows(); else this.lift(hermes);
         const result = fn(this.db);
-        const changes = this.rows.changes(this.mem, { all: !this.rows.normalized() });
-        const canonical = (row, omitted) => row && Object.fromEntries(Object.entries(row).filter(([key])=>!omitted.has(key)));
-        const documentChanges = changes.filter(({source})=>{
-          if(source.name==='tasks') {
-            const before=this.rows.cachedTasks[JSON.parse(source.key)[0]];
-            if(source.row?.workspace_kind==='dir' && !this.rows.cachedCards[JSON.parse(source.key)[0]]?.workspace_anchor && source.row?.workspace_path!==before?.workspace_path)return true;
-            return JSON.stringify(canonical(source.row,new Set([...RUNTIME,'status'])))!==JSON.stringify(canonical(before,new Set([...RUNTIME,'status'])));
-          }
-          if(source.name==='supercode_cards')return JSON.stringify(canonical(source.row,new Set(['since','after_fired','next_run_at','workspace_root'])))!==JSON.stringify(canonical(this.rows.cachedCards[JSON.parse(source.key)[0]],new Set(['since','after_fired','next_run_at','workspace_root'])));
-          return false;
-        });
-        this.publishedFingerprints = {};
-        const documents = this.seed || documentChanges.length ? this.documents(this.seed ? null : documentChanges) : {open:this.text, archived:this.archiveText};
-        const files = [{ path: this.path, before: hash(this.text), base: this.text, text: documents.open }, { path: this.archive, before: hash(this.archiveText), base: this.archiveText, text: documents.archived }];
-        const snapshot = this.snapshot(documents);
-        this.computing = false;
-        const pendingValues=[...this.pendingValues].filter(([key,value])=>JSON.stringify(this.get(key))!==JSON.stringify(value));
-        if(!changes.length && !pendingValues.length && files.every(f=>hash(f.text)===f.before)) {
-          this.loadedStamp=this.stamp();return result;
-        }
-        this.runtime.exec('BEGIN');
-        this.recover();
-        if (this.get('version') !== version || files.some((f) => hash(read(f.path)) !== f.before)) { this.runtime.exec('ROLLBACK'); this.invalidate(); continue; }
-        for (const [key, value] of pendingValues) this.put(key, value);
-        // A durable intent precedes filesystem writes; recovery completes exactly this version.
-        const intent = randomBytes(16).toString('hex');
-        this.put('pending', { intent, files, snapshot, changes });
-        this.runtime.exec('COMMIT'); committed = true;
-        // A concurrent writer may recover this intent and advance the runtime. Re-read
-        // its identity before touching documents, retrying from any newer version.
-        this.runtime.exec('BEGIN');
-        if (this.get('pending')?.intent !== intent) {
-          const applied = this.get(`applied:${intent}`, false);
-          this.runtime.exec('ROLLBACK');
-          if (applied) { this.loadedStamp = null; this.seed = null; if (applied.conflicts?.length) throw new Error(`Concurrent edits superseded this operation on ${applied.conflicts.join(', ')}`); return result; }
-          this.invalidate(); continue;
+        const files = this.render();
+        this.statement('INSERT INTO main.board_export (name, key) SELECT DISTINCT name, key FROM temp.board_dirty WHERE true ON CONFLICT(name, key) DO UPDATE SET rev = rev + 1').run();
+        const intent = files.length ? randomBytes(16).toString('hex') : null;
+        if (intent) {
+          this.put('pending', { intent, files });
+          this.put('pending_hashes', Object.fromEntries(files.map((f) => [f.role, { before: f.before, after: f.after }])));
         }
-        // Detect an editor racing the journal commit before replacing either document.
-        if (files.some((f) => hash(read(f.path)) !== f.before)) {
-          this.runtime.prepare("DELETE FROM state WHERE key = 'pending'").run(); this.runtime.exec('COMMIT');
-          this.invalidate(); continue;
-        }
-        for (const f of files) if (hash(f.text) !== f.before) atomic(f.path, f.text);
-        this.rows.write(changes);
-        this.put('snapshot', snapshot); this.put(`applied:${intent}`, true); this.runtime.prepare("DELETE FROM state WHERE key = 'pending'").run();
-        this.put('export_pending', [...this.get('export_pending', []), ...changes]);
-        this.put('version', randomBytes(8).toString('hex'));
-        this.runtime.exec('COMMIT');
-        try { this.flushExport(); } catch (error) { if (!sqliteContention(error) && !exportConflict(error)) throw error; }
-        this.loadedStamp = this.stamp();
-        this.seed = null;
-        return result;
+        this.conn.exec('COMMIT');
+        outcome = { result, files, intent };
       } catch (error) {
-        try { this.runtime.exec('ROLLBACK'); } catch { /* intent already durable */ }
-        this.invalidate();
-        if (sqliteContention(error) || exportConflict(error) || recoveryConflict(error)) continue;
-        if (committed) error.message += ' (the operation reached its durable intent; inspect its recorded outcome before retrying)';
+        try { this.conn.exec('ROLLBACK'); } catch { /* not begun */ }
+        this.active = false; this.seen = null; this.loadErrors();
+        if (error === RETRY || sqliteContention(error)) { backoff(attempt); continue; }
         throw error;
-      } finally { this.active = false; this.computing = false; this.pendingValues = null; }
+      } finally { this.active = false; }
+      this.seed = null;
+      if (outcome.intent) this.publish(outcome);
+      this.exportFollowing();
+      return outcome.result;
     }
   }
-  invalidate() { this.mem?.close(); this.mem = null; this.rows = new RuntimeRows(this.runtime); this.loadedStamp = null; this.cachedReader=false; }
-  seedIntoMemory() {
-    const source = this.seed;
-    for (const table of this.mem.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) this.mem.exec(`DELETE FROM ${quote(table.name)}`);
-    for (const table of source.db.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
-      if (!this.mem.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table.name)) this.mem.exec(table.sql);
-      for (const row of source.db.prepare(`SELECT * FROM ${quote(table.name)}`).all()) this.insert(table.name, row);
+
+  // Replace each document with its committed text. A document edited in the meantime is merged
+  // by the next transaction's recovery instead of being overwritten.
+  publish({ files, intent }) {
+    let raced = false;
+    for (const file of files) {
+      const current = this.fileHash(file.path).hash;
+      if (current === file.after) continue;
+      if (current !== file.before) { raced = true; continue; }
+      atomic(file.path, file.text);
     }
-    for (const task of this.mem.prepare('SELECT * FROM tasks').all()) {
-      const old = this.mem.prepare('SELECT * FROM supercode_cards WHERE task_id = ?').get(task.id) ?? {};
-      if (old.subtask_of) { const key = /^([a-z]+\d+)\s/.exec(task.title)?.[1]; if (key) this.taskKeys.set(task.id, `${old.subtask_of}:${key}`); }
-      const status = old.stage ?? task.status;
-      const mapped = source.mapping[status];
-      if (!mapped) throw new Error(`migration needs an explicit mapping for ${status} (${task.id})`);
-      let stage = typeof mapped === 'string' ? mapped : mapped.status;
-      if (mapped.preserve_completed && task.completed_at) stage = 'done';
-      const parents = this.mem.prepare('SELECT parent_id FROM task_links WHERE child_id = ?').all(task.id).map((p) => ({ id: p.parent_id, kind: 'card' }));
-      const last = this.mem.prepare("SELECT kind, payload FROM task_events WHERE task_id = ? AND kind IN ('blocked','unblocked') ORDER BY id DESC LIMIT 1").get(task.id);
-      const wait = last?.kind === 'blocked' ? json(last.payload, {})?.waiting_on : null;
-      if (wait) parents.push({ id: wait, kind: 'message' });
-      this.insert('supercode_cards', { ...old, task_id: task.id, stage, archived: Number(Boolean(mapped.archived) || stage === 'cancelled'), blocked_by: JSON.stringify(parents),
-        every: mapped.every ?? old.every ?? null, next_run_at: mapped.every ? now() : old.next_run_at,
-        paused: mapped.paused ? JSON.stringify({ by: actorOf() ?? 'migration', reason: `migrated ${status}: ${json(last?.payload, {})?.reason ?? 'held by previous workflow'}` }) : null });
-      this.mem.prepare('UPDATE tasks SET status = ? WHERE id = ?').run(stage, task.id);
-      if (task.current_run_id && ['done','cancelled'].includes(stage)) {
-        this.mem.prepare("UPDATE task_runs SET ended_at = COALESCE(ended_at, ?), status = 'reclaimed', outcome = COALESCE(outcome, 'reclaimed') WHERE id = ?").run(now(), task.current_run_id);
-        this.mem.prepare('UPDATE tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL WHERE id = ?').run(task.id);
-      } else if (task.current_run_id) {
-        const run = this.mem.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(task.current_run_id);
-        const meta = json(run?.metadata, {}) ?? {}; meta.supercode = { ...meta.supercode, state: 'active' };
-        this.mem.prepare('UPDATE task_runs SET metadata = ? WHERE id = ?').run(JSON.stringify(meta), task.current_run_id);
-      }
+    if (raced) { this.tx(() => {}); return; }
+    this.small(() => {
+      if (this.get('pending')?.intent !== intent) return; // another writer finished it
+      this.drop('pending'); this.drop('pending_hashes');
+    });
+  }
+
+  // A short write of board state alone, retried on contention.
+  small(fn) {
+    for (let attempt = 0; ; attempt++) {
+      try { this.conn.exec('BEGIN'); fn(); this.conn.exec('COMMIT'); return; }
+      catch (error) { try { this.conn.exec('ROLLBACK'); } catch { /* not begun */ } if (!sqliteContention(error)) throw error; backoff(attempt); }
     }
-    this.rows.watch(this.mem);
-    this.put('hermes_cursor', Number(source.db.prepare('SELECT COALESCE(MAX(id),0) AS id FROM task_events').get().id));
   }
-  insert(table, row) {
-    const columns = new Set(this.mem.prepare(`PRAGMA table_info(${quote(table)})`).all().map((c) => c.name));
-    const keys = Object.keys(row).filter((k) => columns.has(k));
-    if (!keys.length) return;
-    this.mem.prepare(`INSERT OR REPLACE INTO ${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
-  }
-  openCachedReader(saved) {
-    const native = this.get('read_revision',-1)===this.get('rows_revision',0);
-    if(this.cachedReader && native!==this.nativeReader)this.invalidate();
-    if (!this.cachedReader) {
-      this.mem?.close(); this.mem=new DatabaseSync(':memory:'); this.init(this.mem,{fresh:true});
-      for(const row of this.runtime.prepare('SELECT name,sql FROM runtime_schema').all())this.mem.exec(row.sql.replace('CREATE TABLE ','CREATE TABLE IF NOT EXISTS '));
-      this.mem.prepare('ATTACH DATABASE ? AS source').run(this.runtimePath);
-      const tables=this.mem.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
-      for(const {name} of tables) {
-        if (native && name==='tasks') {
-          const fields=this.mem.prepare('PRAGMA main.table_info(tasks)').all().map(({name:column})=>column==='status'?'COALESCE(c.stage,t.status) AS status':`t.${quote(column)}`);
-          this.mem.exec(`CREATE TEMP VIEW tasks AS SELECT ${fields.join(',')} FROM source.read_tasks t LEFT JOIN source.read_supercode_cards c ON c.task_id=t.id`);
-          continue;
-        }
-        if(native && name==='supercode_cards') {
-          const have=new Set(this.mem.prepare('PRAGMA source.table_info(read_supercode_cards)').all().map(c=>c.name));
-          const fields=this.mem.prepare('PRAGMA main.table_info(supercode_cards)').all().map(c=>have.has(c.name)?quote(c.name):`${c.dflt_value??'NULL'} AS ${quote(c.name)}`);
-          this.mem.exec(`CREATE TEMP VIEW supercode_cards AS SELECT ${fields.join(',')} FROM source.read_supercode_cards`);continue;
-        }
-        if(native && name==='task_links') {this.mem.exec("CREATE TEMP VIEW task_links AS SELECT json_extract(b.value,'$.id') parent_id,r.task_id child_id FROM source.read_supercode_cards r,json_each(r.blocked_by) b WHERE json_extract(b.value,'$.kind')='card'");continue;}
-        if(name==='task_links') {
-          this.mem.exec(`CREATE TEMP VIEW task_links AS SELECT json_extract(b.value,'$.id') parent_id,r.key child_id FROM source.runtime_rows r,json_each(json_extract(r.value,'$.blocked_by')) b WHERE r.name='@card_cache' AND json_extract(b.value,'$.kind')='card'`);
-          continue;
-        }
-        const columns=this.mem.prepare(`PRAGMA main.table_info(${quote(name)})`).all();
-        const recordName=name==='tasks'?'@task_cache':name==='supercode_cards'?'@card_cache':name;
-        const fields=columns.map(({name:column})=>name==='tasks'&&column==='status'?`COALESCE(json_extract(c.value,'$.stage'),json_extract(r.value,'$.status')) AS status`:`json_extract(r.value,'$.${column}') AS ${quote(column)}`);
-        const join=name==='tasks'?" LEFT JOIN source.runtime_rows c ON c.name='@card_cache' AND c.key=r.key":'';
-        this.mem.exec(`CREATE TEMP VIEW ${quote(name)} AS SELECT ${fields.join(',')} FROM source.runtime_rows r${join} WHERE r.name='${recordName}' AND r.value IS NOT NULL`);
-      }
-      this.mem.exec('PRAGMA query_only=ON');
-      this.cachedReader=true;this.nativeReader=native;
-    }
-    this.saved=saved; this.errors.clear();
-    for(const [id,reason] of saved.errors??[])this.errors.set(id,reason);
-    this.mem.boardErrors=this.errors;
-  }
-  load({ observe = false } = {}) {
-    const text = read(this.path), archiveText = read(this.archive);
-    const saved=this.get('snapshot', {});
-    let cached=saved.bodyProjection===2&&saved.documentHashes?.open===hash(text)&&saved.documentHashes?.archived===hash(archiveText);
-    if(!observe && !cached && saved.bodyProjection===2 && saved.documentHashes) {
-      // The durable intent may have replaced the documents while its runtime commit
-      // is still pending. Readers keep the previous committed projection, never parse
-      // an intermediate pair of files. A real hand edit does not match these hashes.
-      const pending=this.get('pending');
-      cached=Boolean(pending?.files?.length===2 && pending.files.every(file=>{
-        const expected=file.path===this.path?saved.documentHashes.open:saved.documentHashes.archived;
-        const current=hash(file.path===this.path?text:archiveText);
-        return file.before===expected&&(current===file.before||current===hash(file.text));
-      }));
+
+  // Finish a publication another writer committed but did not write: write its text over the
+  // document it replaced; merge it into a document edited since (the hand edit wins its cards).
+  recover() {
+    const pending = this.get('pending');
+    if (!pending) return;
+    for (const file of pending.files) {
+      const current = this.fileHash(file.path);
+      if (current.hash === file.after) continue;
+      if (current.hash === file.before) { atomic(file.path, file.text); continue; }
+      // A hand edit wins: a merge that cannot be made leaves the editor's text, which the next write reads.
+      let merged = null;
+      try { merged = this.codec.mergeBoardDocument(file.base, lf(current.raw), file.text, file.path); } catch { /* keep the edit */ }
+      if (this.fileHash(file.path).hash !== current.hash) throw RETRY;
+      if (merged) atomic(file.path, merged.text);
     }
-    if (!observe && cached && this.rows.normalized()) {
-      this.openCachedReader(saved);
-      this.text=text;this.archiveText=archiveText;
-      return;
-    }
-    if (this.cachedReader)this.invalidate();
-    const fresh = !this.mem;
-    const changed = fresh || text !== this.text || archiveText !== this.archiveText;
-    this.text = text; this.archiveText = archiveText;
-    if (fresh) { this.mem = new DatabaseSync(':memory:'); this.init(this.mem, { fresh: true }); this.mem.boardErrors=this.errors; }
-    this.saved = this.get('snapshot', { tables: {}, runtime: {}, clocks: {}, fingerprints: {} });
-    const normalized = this.rows.load(this.mem, { fresh });
-    if (normalized) { this.saved.runtime = this.rows.runtime; this.saved.clocks = this.rows.clocks; }
-    for (const item of Object.values(!normalized && fresh ? this.saved.tables ?? {} : {})) {
-      if (item.sql) this.mem.exec(item.sql.replace('CREATE TABLE ', 'CREATE TABLE IF NOT EXISTS '));
-      for (const row of item.rows ?? []) this.insert(item.name, row);
-    }
-    if (!fresh && !changed) {
-      for (const [id, row] of Object.entries(this.saved.runtime ?? {})) {
-        const keys = Object.keys(row);
-        if (keys.length) this.mem.prepare(`UPDATE tasks SET ${keys.map(k => `${quote(k)}=?`).join(',')} WHERE id=?`).run(...keys.map(k => row[k]), id);
-      }
-      for (const [id, row] of Object.entries(this.saved.clocks ?? {})) this.mem.prepare('UPDATE supercode_cards SET since=?,after_fired=?,next_run_at=?,workspace_root=? WHERE task_id=?').run(row.since??null,row.after_fired??null,row.next_run_at??null,row.workspace_root??null,id);
-      this.rows.watch(this.mem);
-      if (observe) this.documentEvents();
-      return;
-    }
-    this.rows.watch(this.mem);
-    this.mem.exec('DELETE FROM tasks; DELETE FROM supercode_cards; DELETE FROM task_links');
-    this.errors.clear(); this.preserve.clear();
-    const records = []; this.documentRecords=new Map();
-    for (const [text,path] of [[this.text,this.path],[this.archiveText,this.archive]]) {
-      const result = this.inspectDocument(text,path);
-      const kept = new Set(result.errors.map(e=>e.id));
-      for(const error of result.errors)this.errors.set(nativeId(error.id),error.reason);
-      for(const record of result.records) {
-        this.documentRecords.set(nativeId(record.id),{record,path});
-        try { records.push(this.preset.KanbanRootSchema.parse(this.preset.parseKanban([record])).issues[0]); }
-        catch(error) { this.errors.set(nativeId(record.id),error.message); kept.add(record.id); }
-      }
-      this.preserve.set(path,kept);
-    }
-    const counts=new Map(); for(const card of records)counts.set(nativeId(card.id),(counts.get(nativeId(card.id))??0)+1);
-    const parsed = {issues:records.filter(card=>{
-      const id=nativeId(card.id); if(counts.get(id)===1)return true;
-      this.errors.set(id,'Duplicate card identity across board documents');
-      for(const kept of this.preserve.values())kept.add(card.id);
-      return false;
-    })};
-    this.originals = new Map(); this.fileIds = new Map(); this.taskKeys = new Map();
-    for (const card of parsed.issues) {
-      const id = nativeId(card.id);
-      if (this.originals.has(id)) throw new Error(`duplicate board card ${id}`);
-      this.originals.set(id, card); this.fileIds.set(id, card.id);
-      this.loadCard(id, card);
-      for (const [tid, taskCard] of this.taskCards(id, card)) this.loadCard(tid, taskCard, id);
-    }
-    // Keep the last readable projection only for the affected malformed cards.
-    // Their raw document spans remain untouched and their verbs refuse with this reason.
-    for (const [id] of this.errors) {
-      for (const [tid,row] of Object.entries(this.rows.cachedTasks)) {
-        const state=this.rows.cachedCards[tid];
-        if (tid!==id && state?.subtask_of!==id)continue;
-        this.insert('tasks',row); if(state)this.insert('supercode_cards',state);
-        if(tid!==id)this.errors.set(tid,`Parent ${id} has an invalid document edit`);
+    this.drop('pending'); this.drop('pending_hashes');
+  }
+
+  // ------------------------------------------------------------------ the document index
+
+  entries(role) { return this.get(`chunks:${role}`, []); }
+  texts(entries) {
+    const cids = entries.filter((e) => e.text === undefined).map((e) => e.cid);
+    const found = new Map(cids.length ? this.statement('SELECT c.cid, c.text FROM main.board_chunks c JOIN json_each(?) j ON c.cid = j.value').all(JSON.stringify(cids)).map((r) => [r.cid, r.text]) : []);
+    return entries.map((e) => ({ id: e.id, level: e.level, text: e.text ?? found.get(e.cid) ?? '' }));
+  }
+  docOf(role) { return this.docs.find((doc) => doc.role === role); }
+
+  // What the edited documents now say, as a plan of rows; applied to the tables by a write, to
+  // connection-local copies by a read. Only the spans the edit touched are parsed.
+  observe(stale) {
+    const plan = { layout: new Map(), dropped: [], published: {}, cards: new Map(), rows: new Map(), subtasks: new Map(), tasks: new Map(), remove: new Set(), errors: new Map(), checked: new Set() };
+    const changed = new Set();
+    for (const doc of this.docs) {
+      const entries = this.entries(doc.role);
+      const edit = stale.find((s) => s.role === doc.role);
+      if (!edit) { plan.layout.set(doc.role, entries); continue; }
+      let base = this.get('published', {})[doc.role] !== undefined && entries.length ? entries : [];
+      let result;
+      // A region that cannot be re-read on its own is read with the whole document.
+      try { result = this.codec.rechunkBoardDocument(this.texts(base), edit.text, doc.path); }
+      catch { base = []; result = this.codec.rechunkBoardDocument([], edit.text, doc.path); }
+      const added = result.chunks.slice(result.from, result.to).map((c) => ({ cid: null, id: c.id, level: c.level, len: c.text.length, rec: null, text: c.text }));
+      plan.layout.set(doc.role, [...base.slice(0, result.from), ...added, ...base.slice(result.oldTo)]);
+      // The spans an edit replaced: every indexed one when the document was read whole. Each card they held is checked.
+      const replaced = base.length ? base.slice(result.from, result.oldTo) : entries;
+      plan.dropped.push(...replaced.map((e) => e.cid));
+      plan.published[doc.role] = edit.hash;
+      for (const c of [...added, ...replaced]) if (c.id) changed.add(nativeId(c.id));
+    }
+    const places = new Map();
+    for (const [role, entries] of plan.layout) for (const entry of entries) if (entry.id) places.set(nativeId(entry.id), [...(places.get(nativeId(entry.id)) ?? []), { role, entry }]);
+    for (const id of changed) {
+      plan.checked.add(id);
+      const at = places.get(id) ?? [];
+      if (at.length > 1) { plan.errors.set(id, 'Duplicate card identity across board documents'); continue; }
+      if (!at.length) { this.planRemoval(plan, id); continue; }
+      const { role, entry } = at[0];
+      const text = entry.text ?? this.texts([entry])[0].text;
+      const { records, errors } = this.codec.inspectBoardDocument(text, this.docOf(role).path);
+      if (errors.length || records.length !== 1) { plan.errors.set(id, errors.find((e) => nativeId(e.id) === id)?.reason ?? errors[0]?.reason ?? 'A card section holds another card; give each card its own section'); continue; }
+      let card;
+      try { card = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([records[0]])).issues[0]; }
+      catch (error) { plan.errors.set(id, error.message); continue; }
+      entry.rec = hash(JSON.stringify(records[0]));
+      plan.cards.set(id, card);
+    }
+    for (const [id, card] of plan.cards) {
+      plan.rows.set(id, this.cardRows(id, card, null));
+      const subtasks = [];
+      for (const [tid, taskCard, key, sources] of this.taskCards(id, card)) {
+        plan.rows.set(tid, this.cardRows(tid, taskCard, id));
+        plan.tasks.set(tid, { key, sources });
+        subtasks.push(tid);
       }
+      plan.subtasks.set(id, subtasks);
+      for (const old of this.statement('SELECT task_id FROM main.supercode_cards WHERE subtask_of = ?').all(id)) if (!subtasks.includes(old.task_id)) this.planRemoval(plan, old.task_id);
     }
-    for (const [id,runtime] of Object.entries(this.saved.runtime??{})) {
-      if (!runtime.current_run_id || this.mem.prepare('SELECT 1 FROM tasks WHERE id=?').get(id))continue;
-      const task=this.rows.cachedTasks[id], state=this.rows.cachedCards[id];
-      if (task) {this.insert('tasks',task);if(state)this.insert('supercode_cards',state);}
-      this.errors.set(id,'Document removed a card with a live run; restore it and cancel its run through the workflow.');
+    // A task ref (`<arc>:c3`) names a subtask by its key; resolve it once every key is known.
+    const keyed = new Map([...plan.tasks].map(([tid, { key }]) => [key, tid]));
+    const resolveRef = (ref) => keyed.get(ref) ?? this.one('SELECT id FROM main.board_tasks WHERE key = ?', ref)?.id ?? ref;
+    for (const rows of plan.rows.values()) rows.state.blocked_by = JSON.stringify(json(rows.state.blocked_by, []).map((b) => ({ ...b, id: resolveRef(b.id) })));
+    this.checkControls(plan);
+    // A refused task line refuses its card's edit: the hand text stays in the document with the reason, never
+    // re-rendered without the line.
+    for (const [id, subtasks] of plan.subtasks) {
+      const bad = plan.errors.has(id) ? null : subtasks.find((tid) => plan.errors.has(tid));
+      if (bad) plan.errors.set(id, `Task ${plan.tasks.get(bad)?.key ?? bad}: ${plan.errors.get(bad)}`);
     }
-    // Resolve local task refs only after all subtask identities are available.
-    const taskIds = new Map([...this.taskKeys].map(([id, key]) => [key, id]));
-    for (const row of this.mem.prepare('SELECT task_id, blocked_by FROM supercode_cards').all()) {
-      const blocks = json(row.blocked_by, []).map((b) => ({ ...b, id: taskIds.get(b.id) ?? b.id }));
-      this.mem.prepare('UPDATE supercode_cards SET blocked_by = ? WHERE task_id = ?').run(JSON.stringify(blocks), row.task_id);
-      for (const b of blocks.filter((b) => b.kind === 'card')) this.insert('task_links', { parent_id: b.id, child_id: row.task_id });
+    // A card whose own edit is refused keeps its subtasks as they were.
+    for (const [id, subtasks] of plan.subtasks) if (plan.errors.has(id)) for (const tid of subtasks) { plan.rows.delete(tid); plan.tasks.delete(tid); }
+    for (const id of plan.errors.keys()) {
+      plan.rows.delete(id);
+      for (const row of this.statement('SELECT task_id FROM main.supercode_cards WHERE subtask_of = ?').all(id)) { plan.remove.delete(row.task_id); if (!plan.errors.has(row.task_id)) plan.errors.set(row.task_id, `Parent ${id} has an invalid document edit`); }
     }
-    this.checkDocumentControls();
-    if (observe) this.documentEvents();
+    return plan;
   }
-  taskCards(id, card) {
-    return card.acceptanceCriteria.map((task) => {
-      const tid = task.metadata?.id ?? this.saved.taskIds?.[`${id}:${task.id}`] ?? `t_${randomBytes(4).toString('hex')}`;
-      this.taskKeys.set(tid, `${id}:${task.id}`);
-      const taskCard = { ...task.metadata?.card, id: tid, title: `${task.id} ${task.text}`, body: task.metadata?.body ?? '',
-        status: task.status === 'passed' ? (task.metadata?.status === 'cancelled' ? 'cancelled' : 'done') : (['done','cancelled'].includes(task.metadata?.status) ? 'todo' : task.metadata?.status ?? 'todo'),
-        metadata: task.metadata?.properties ?? {}, assignee: task.metadata?.assignee ?? card.assignee,
-        machine: task.metadata?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
-        relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac && /^(?:[ma]-[0-9a-f]{6,}|t_[0-9a-f]+)$/.test(b.ac) ? b.ac : b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
-      if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
-      return [tid, taskCard];
-    });
-  }
-  loadCard(id, card, parent = null) {
-    const rows = this.cardRows(id, card, parent);
-    this.insert('tasks', rows.task); this.insert('supercode_cards', rows.state);
+
+  planRemoval(plan, id) {
+    const task = this.one('SELECT current_run_id FROM main.tasks WHERE id = ?', id);
+    if (!task) return;
+    if (task.current_run_id) { plan.errors.set(id, 'Document removed a card with a live run; restore it and cancel its run through the workflow.'); return; }
+    plan.remove.add(id);
+    for (const row of this.statement('SELECT task_id FROM main.supercode_cards WHERE subtask_of = ?').all(id)) plan.remove.add(row.task_id);
   }
-  checkDocumentControls() {
-    // A raw edit cannot authenticate its author. Trusted engine writes already
-    // have matching publication hashes; check only external edits, after local
-    // subtask references have been resolved to canonical card identities.
-    if (this.seed || (this.saved.documentHashes?.open === hash(this.text) && this.saved.documentHashes?.archived === hash(this.archiveText))) return;
+
+  // A raw edit cannot authenticate its author: the workflow's controlled fields change only through
+  // role-checked verbs. The first import of a document has nothing to compare with.
+  checkControls(plan) {
+    if (!this.one('SELECT 1 FROM main.tasks LIMIT 1')) return;
     let fields = [];
     try { fields = workflowFor(this.root).params.document_control_fields ?? []; } catch { /* no home policy */ }
     if (!fields.length) return;
-    const tasks = new Map(this.mem.prepare('SELECT * FROM tasks').all().map(t => [t.id, t]));
-    const states = new Map(this.mem.prepare('SELECT * FROM supercode_cards').all().map(c => [c.task_id, c]));
     const value = (task, state, field) => field === 'status' ? state?.stage ?? task?.status ?? 'todo'
-      : field === 'blocked_by' ? json(state?.blocked_by, []).map(b => [b.kind, b.id]).sort()
+      : field === 'blocked_by' ? json(state?.blocked_by, []).map((b) => [b.kind, b.id]).sort()
       : field === 'paused' ? json(state?.paused, null)
-      : field === 'archived' ? Boolean(state?.archived) : field === 'review_only' ? Boolean(state?.review_only) : task?.[field] ?? null;
-    for (const id of new Set([...tasks.keys(), ...Object.keys(this.rows.cachedTasks)])) {
-      if (this.errors.has(id)) continue;
-      const oldTask = this.rows.cachedTasks[id], oldState = this.rows.cachedCards[id];
-      const task = tasks.get(id), state = states.get(id);
-      const forbidden = !task ? ['card removal'] : fields.filter(field =>
-        // A new display author is not an authenticated creator.
-        (oldTask || field !== 'created_by') && JSON.stringify(value(task, state, field)) !== JSON.stringify(value(oldTask, oldState, field)));
-      if (!forbidden.length) continue;
-      this.errors.set(id, `Document edit cannot change ${forbidden.join(', ')}; use this card's role-checked workflow verbs or request-state.`);
-      const source = this.documentRecords.get(state?.subtask_of ?? oldState?.subtask_of ?? id);
-      if (source) this.preserve.get(source.path)?.add(source.record.id);
-      this.mem.prepare('DELETE FROM tasks WHERE id=?').run(id);
-      this.mem.prepare('DELETE FROM supercode_cards WHERE task_id=?').run(id);
-      this.mem.prepare('DELETE FROM task_links WHERE child_id=?').run(id);
-      if (oldTask) this.insert('tasks', oldTask);
-      if (oldState) {
-        this.insert('supercode_cards', oldState);
-        for (const b of json(oldState.blocked_by, []).filter(b => b.kind === 'card')) this.insert('task_links', { parent_id: b.id, child_id: id });
+      : field === 'archived' ? Boolean(state?.archived) : task?.[field] ?? null;
+    for (const [id, rows] of plan.rows) {
+      const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id), state = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', id);
+      // A new display author is not an authenticated creator.
+      const forbidden = fields.filter((field) => (task || field !== 'created_by') && JSON.stringify(value(rows.task, rows.state, field)) !== JSON.stringify(value(task, state, field)));
+      if (forbidden.length) plan.errors.set(id, `Document edit cannot change ${forbidden.join(', ')}; use this card's role-checked workflow verbs or request-state.`);
+    }
+    for (const id of plan.remove) {
+      plan.errors.set(id, "Document edit cannot change card removal; use this card's role-checked workflow verbs or request-state.");
+    }
+    for (const id of plan.errors.keys()) plan.remove.delete(id);
+  }
+
+  applyPlan(plan, { overlay }) {
+    const schema = overlay ? 'temp' : 'main';
+    if (overlay) {
+      this.dropOverlay();
+      this.conn.exec('CREATE TEMP TABLE tasks AS SELECT * FROM main.tasks; CREATE TEMP TABLE supercode_cards AS SELECT * FROM main.supercode_cards; CREATE TEMP TABLE task_links AS SELECT * FROM main.task_links');
+      this.overlay = true; this.statements.clear();
+    }
+    const initial = !overlay && !this.one('SELECT 1 FROM main.tasks LIMIT 1');
+    const by = 'document-editor';
+    const events = [];
+    const fingerprintOf = (id) => {
+      const t = this.one(`SELECT * FROM ${schema}.tasks WHERE id = ?`, id);
+      return t ? this.fingerprint(t, this.one(`SELECT * FROM ${schema}.supercode_cards WHERE task_id = ?`, id) ?? {}) : null;
+    };
+    for (const id of plan.remove) {
+      this.statement(`DELETE FROM ${schema}.tasks WHERE id = ?`).run(id);
+      this.statement(`DELETE FROM ${schema}.supercode_cards WHERE task_id = ?`).run(id);
+      this.statement(`DELETE FROM ${schema}.task_links WHERE child_id = ?`).run(id);
+      if (!overlay) { this.statement('DELETE FROM main.board_tasks WHERE id = ?').run(id); if (!initial) events.push({ id, kind: 'removed', payload: { by, source: 'document' } }); }
+    }
+    for (const [id, rows] of plan.rows) {
+      const before = fingerprintOf(id);
+      const oldTask = this.one(`SELECT * FROM ${schema}.tasks WHERE id = ?`, id) ?? {};
+      const oldState = this.one(`SELECT * FROM ${schema}.supercode_cards WHERE task_id = ?`, id) ?? {};
+      this.replace(schema, 'tasks', { ...oldTask, ...rows.task }, 'id');
+      this.replace(schema, 'supercode_cards', { ...oldState, ...rows.state }, 'task_id');
+      this.statement(`DELETE FROM ${schema}.task_links WHERE child_id = ?`).run(id);
+      for (const b of json(rows.state.blocked_by, []).filter((b) => b.kind === 'card')) this.statement(`INSERT OR IGNORE INTO ${schema}.task_links (parent_id, child_id) VALUES (?, ?)`).run(b.id, id);
+      const after = fingerprintOf(id);
+      if (!overlay && !initial && before?.hash !== after.hash) {
+        const kind = !before ? 'created' : before.status !== after.status ? 'status' : before.assignee !== after.assignee ? 'assigned' : 'specified';
+        events.push({ id, kind, payload: { by, source: 'document', status: after.status, assignee: after.assignee, author: by }, before, after });
       }
     }
+    for (const id of plan.checked) this.errors.delete(id);
+    for (const [id, reason] of plan.errors) this.errors.set(id, reason);
+    if (overlay) return;
+    for (const [tid, { key, sources }] of plan.tasks) this.statement('INSERT OR REPLACE INTO main.board_tasks (id, key, sources) VALUES (?, ?, ?)').run(tid, key, sources?.length ? JSON.stringify(sources) : null);
+    for (const id of [...plan.checked, ...plan.rows.keys()]) if (!plan.errors.has(id)) this.statement('DELETE FROM main.board_errors WHERE id = ?').run(id);
+    for (const [id, reason] of plan.errors) this.statement('INSERT OR REPLACE INTO main.board_errors VALUES (?, ?)').run(id, reason);
+    for (const [role, entries] of plan.layout) {
+      if (!(role in plan.published)) continue;
+      this.put(`chunks:${role}`, entries.map((entry) => {
+        const cid = entry.cid ?? Number(this.statement('INSERT INTO main.board_chunks (text) VALUES (?)').run(entry.text).lastInsertRowid);
+        return { cid, id: entry.id, level: entry.level, len: entry.len, rec: entry.rec };
+      }));
+    }
+    for (const cid of plan.dropped) this.statement('DELETE FROM main.board_chunks WHERE cid = ?').run(cid);
+    this.put('published', { ...this.get('published', {}), ...plan.published });
+    let entry = null;
+    try { entry = workflowFor(this.root); } catch { /* no home workflow */ }
+    for (const e of events) {
+      if (e.kind !== 'removed' && e.kind !== 'created' && entry?.workflow.verbs?.document_changed) {
+        const change = fire(this.db, this.board(), entry, e.id, 'document_changed', { roles: ['platform'], payload: { previous_status: e.before.status, by, source: 'document' } });
+        for (const effect of change.effects) this.statement('INSERT INTO main.supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+      }
+      event(this.db, e.id, e.kind, e.payload);
+      if (e.kind === 'created' && e.after.parent) event(this.db, e.after.parent, 'subtask_added', { by, subtask: e.id, title: this.one('SELECT title FROM main.tasks WHERE id = ?', e.id).title });
+    }
+  }
+
+  replace(schema, table, row, idColumn) {
+    const columns = this.tables.get(table).columns;
+    const keys = columns.filter((c) => c in row);
+    this.statement(`DELETE FROM ${schema}.${quote(table)} WHERE ${quote(idColumn)} = ?`).run(row[idColumn]);
+    this.statement(`INSERT INTO ${schema}.${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
+  }
+
+  fingerprint(t, c) {
+    const status = c.stage ?? t.status;
+    return { hash: hash(JSON.stringify([t.title, t.body, status, t.assignee, c.machine, c.blocked_by, c.paused, c.every])), status, assignee: t.assignee, parent: c.subtask_of };
   }
+
+  // A card's rows from its parsed document form. Run fields and clocks stay the table's.
   cardRows(id, card, parent = null) {
     const meta = card.metadata ?? {};
     const stored = this.preset.serializeKanbanCard({ ...card, acceptanceCriteria: [], relations: [], metadata: undefined, paused: undefined, every: undefined, workspace: undefined, branch: undefined, machine: undefined, priority: undefined });
     const workspace = /^(scratch|dir|worktree)(?::(.*))?$/.exec(card.workspace ?? 'scratch');
-    const task = { ...meta, ...this.saved.runtime?.[id], id, title: card.title, body: stored.body,
-      status: card.status, assignee: card.assignee ?? null, created_at: meta.created_at ?? now(), priority: card.priority ?? 0,
-      workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: this.saved.runtime?.[id]?.workspace_path ?? (/^(\/|~|[A-Za-z]:[\\/])/.test(workspace?.[2] ?? '') ? workspace[2] : null), branch_name: card.branch ?? null };
-    const state = { ...this.saved.clocks?.[id], task_id: id, workspace_anchor: workspace?.[2] ?? null, review_only: meta.review_only === true ? 1 : 0, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
+    const old = this.one('SELECT * FROM main.tasks WHERE id = ?', id) ?? {};
+    const runtime = Object.fromEntries(Object.entries(old).filter(([k]) => RUNTIME.has(k)));
+    const task = { ...meta, ...runtime, id, title: card.title, body: stored.body,
+      status: card.status, assignee: card.assignee ?? null, created_at: meta.created_at ?? old.created_at ?? now(), priority: card.priority ?? 0,
+      workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: runtime.workspace_path ?? (/^(\/|~|[A-Za-z]:[\\/])/.test(workspace?.[2] ?? '') ? workspace[2] : null), branch_name: card.branch ?? null };
+    const state = { task_id: id, workspace_anchor: workspace?.[2] ?? null, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
       blocked_by: JSON.stringify((card.relations ?? []).map((r) => ({ ...(meta.blocked_by ?? []).find((b) => b.id === nativeId(r.issueId)), id: nativeId(r.issueId), kind: /^[ma]-/.test(r.issueId) ? 'message' : 'card' }))),
       paused: card.paused ? JSON.stringify(card.paused) : null, archived: meta.archived ? 1 : 0, every: card.every ?? null };
     return { task, state };
   }
-  fingerprint(t, c) {
-    const status = c.stage ?? t.status;
-    return { hash: hash(JSON.stringify([t.title, t.body, status, t.assignee, c.machine, c.blocked_by, c.paused, c.every])), title: hash(t.title), body: hash(t.body ?? ''), status, assignee: t.assignee, machine: c.machine, parent: c.subtask_of };
-  }
-  fingerprints() {
-    return Object.fromEntries(this.mem.prepare('SELECT * FROM tasks').all().map((t) => {
-      const c = this.mem.prepare('SELECT * FROM supercode_cards WHERE task_id = ?').get(t.id) ?? {};
-      return [t.id, this.fingerprint(t, c)];
-    }));
-  }
-  documentEvents() {
-    // A published native document is already represented by its authored events.
-    if (this.saved.documentHashes?.open === hash(this.text) && this.saved.documentHashes?.archived === hash(this.archiveText)) return;
-    const previous = this.saved.fingerprints ?? {};
-    const current = this.fingerprints();
-    if (!Object.keys(previous).length) return;
-    const by = this.committer();
-    for (const [id, value] of Object.entries(current)) {
-      if (this.errors.has(id)) continue;
-      const old = previous[id];
-      if (old?.hash === value.hash) continue;
-      let entry; try { entry = workflowFor(this.root); } catch {}
-      if (old && entry?.workflow.verbs?.document_changed) {
-        const change = fire(this.mem, this.board(), entry, id, 'document_changed', { roles: ['platform'], payload: { previous_status: old.status, by, source: 'document' } });
-        for (const effect of change.effects) this.mem.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+
+  // A card's Tasks as subtask cards: [id, card, key, sources].
+  taskCards(id, card) {
+    return card.acceptanceCriteria.map((task) => {
+      const key = `${id}:${task.id}`;
+      const tid = task.metadata?.id ?? this.one('SELECT id FROM main.board_tasks WHERE key = ?', key)?.id ?? `t_${randomBytes(4).toString('hex')}`;
+      const taskCard = { ...task.metadata?.card, id: tid, title: `${task.id} ${task.text}`, body: task.metadata?.body ?? '',
+        status: task.status === 'passed' ? (task.metadata?.status === 'cancelled' ? 'cancelled' : 'done') : (['done', 'cancelled'].includes(task.metadata?.status) ? 'todo' : task.metadata?.status ?? 'todo'),
+        metadata: task.metadata?.properties ?? {}, assignee: task.metadata?.assignee ?? card.assignee,
+        machine: task.metadata?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
+        relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac && /^(?:[ma]-[0-9a-f]{6,}|t_[0-9a-f]+)$/.test(b.ac) ? b.ac : b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
+      if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
+      return [tid, taskCard, key, task.sources];
+    });
+  }
+
+  // ------------------------------------------------------------------ rendering
+
+  // Cards whose text may have changed in this transaction are rendered from their rows and spliced
+  // into their documents; a card whose record is unchanged keeps its exact bytes. Answers the
+  // documents to publish.
+  render() {
+    const touched = new Set(this.statement('SELECT DISTINCT id FROM temp.board_touched WHERE id IS NOT NULL').all().map((r) => r.id));
+    if (!touched.size) return [];
+    const layout = { open: this.entries('open'), archived: this.entries('archived') };
+    const where = new Map();
+    for (const role of ['open', 'archived']) layout[role].forEach((entry, index) => { if (entry.id) where.set(nativeId(entry.id), { role, index, entry }); });
+    const parents = new Set();
+    for (const id of touched) {
+      const parent = this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of;
+      const key = parent ? null : this.one('SELECT key FROM main.board_tasks WHERE id = ?', id)?.key;
+      parents.add(parent ?? (key && !this.one('SELECT 1 FROM main.tasks WHERE id = ?', id) ? key.slice(0, key.lastIndexOf(':')) : id));
+    }
+    if (this.seedIds) for (const id of this.seedIds) parents.add(id);
+    const edits = { open: [], archived: [] };
+    for (const id of parents) {
+      if (this.errors.has(id) || this.one('SELECT 1 FROM main.supercode_cards WHERE subtask_of = ? AND task_id IN (SELECT id FROM main.board_errors)', id)) continue;
+      const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id);
+      const state = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', id) ?? {};
+      if (task && state.subtask_of) continue;
+      const at = where.get(id);
+      if (!task) { if (at) edits[at.role].push({ index: at.index, remove: true }); continue; }
+      const role = state.archived || ['done', 'cancelled'].includes(state.stage ?? task.status) ? 'archived' : 'open';
+      const record = this.recordOf(id, task, state, where);
+      const rec = hash(JSON.stringify(record));
+      if (at?.role === role && at.entry.rec === rec) continue;
+      const level = at?.role === role ? at.entry.level : 2;
+      let text;
+      try { text = this.codec.renderBoardCard(record, level, this.docOf(role).path); }
+      catch (error) {
+        this.errors.set(id, error.message);
+        this.statement('INSERT OR REPLACE INTO main.board_errors VALUES (?, ?)').run(id, error.message);
+        continue;
+      }
+      const entry = { cid: null, id: record.id, level, len: text.length, rec, text };
+      if (at?.role === role) edits[role].push({ index: at.index, entry });
+      else { if (at) edits[at.role].push({ index: at.index, remove: true }); edits[role].push({ entry }); }
+    }
+    const files = [];
+    const published = this.get('published', {});
+    for (const role of ['open', 'archived']) {
+      if (!edits[role].length) continue;
+      const doc = this.docOf(role);
+      const current = this.fileHash(doc.path);
+      let text = lf(current.raw);
+      const entries = [...layout[role]];
+      if (entries.reduce((sum, e) => sum + e.len, 0) !== text.length) {
+        if (current.hash !== published[role]) throw RETRY; // edited during this transaction
+        throw new Error(`${doc.path} does not match its board index`);
       }
-      const kind = !old ? 'created' : old.status !== value.status ? 'status' : old.assignee !== value.assignee ? 'assigned' : 'specified';
-      event(this.mem, id, kind, { by, source: 'document', status: value.status, assignee: value.assignee, author: by });
-      if (!old && value.parent) event(this.mem, value.parent, 'subtask_added', { by, subtask: id, title: this.mem.prepare('SELECT title FROM tasks WHERE id = ?').get(id).title });
-    }
-    for (const id of Object.keys(previous)) if (!current[id] && !this.errors.has(id)) {
-      if (this.saved.runtime?.[id]?.current_run_id) { this.errors.set(id,`Document removed a card with a live run; restore it and cancel it through its workflow first`); continue; }
-      event(this.mem, id, 'removed', { by, source: 'document' });
-    }
-  }
-  committer() {
-    return 'document-editor';
-  }
-  inspectDocument(text, path) {
-    const previous = documentCache.get(path);
-    if (previous?.text === text) return previous.result;
-    const result = this.codec.inspectBoardDocument(text, path);
-    remember(documentCache, path, { text, result });
-    return result;
-  }
-  renderDocument(text, records, path, preserve) {
-    const projection = JSON.stringify([records, preserve]);
-    const previous = renderCache.get(path);
-    if (previous?.text === text && previous.projection === projection) return previous.result;
-    const result = this.codec.renderBoardDocument(text, records, path, preserve);
-    remember(renderCache, path, { text, projection, result });
-    return result;
-  }
-  documents(changes=null) {
-    this.publishedFingerprints = {};
-    const allRows = this.mem.prepare('SELECT * FROM tasks ORDER BY created_at, id').all();
-    const states = new Map(this.mem.prepare('SELECT * FROM supercode_cards').all().map((c) => [c.task_id, c]));
-    const affected=changes?new Set(changes.map(({source})=>{const id=JSON.parse(source.key)[0];return states.get(id)?.subtask_of??this.rows.cachedCards[id]?.subtask_of??id;})):null;
-    const rows=affected?allRows.filter(row=>affected.has(states.get(row.id)?.subtask_of??row.id)):allRows;
-    const cards = new Map();
-    for (const row of rows.filter((r) => !states.get(r.id)?.subtask_of && !this.errors.has(r.id))) {
-      const c = states.get(row.id) ?? {};
-      const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([{ id: this.fileIds.get(row.id) ?? row.id, title: row.title, status: c.stage ?? row.status, assignee: row.assignee || undefined, body: row.body ?? '' }])).issues[0];
-      const metadata = Object.fromEntries(Object.entries(row).filter(([k, v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null));
-      if (c.archived) metadata.archived = true;
-      if (c.review_only) metadata.review_only = true;
-      if (json(c.blocked_by, []).length) metadata.blocked_by = json(c.blocked_by, []);
-      cards.set(row.id, { ...parsed, metadata, priority: row.priority ?? 0, workspace: row.workspace_kind + (row.workspace_kind !== 'scratch' && (c.workspace_anchor ?? row.workspace_path) ? `:${c.workspace_anchor ?? row.workspace_path}` : ''),
-        branch: row.branch_name || undefined, machine: c.machine || undefined, paused: json(c.paused, null) ?? undefined, every: c.every || undefined,
-        relations: json(c.blocked_by, []).map((b) => ({ type: 'blocked-by', issueId: this.fileIds.get(b.id) ?? b.id })), acceptanceCriteria: [] });
-    }
-    const occupied = new Map();
-    for (const row of rows) {
-      const parent = states.get(row.id)?.subtask_of;
-      if (!parent) continue;
-      const key = this.taskKeys.get(row.id)?.split(':').at(-1) ?? /^([a-z]+\d+)\s/.exec(row.title)?.[1];
-      if (key) { const set = occupied.get(parent) ?? new Set(); set.add(key); occupied.set(parent, set); }
-    }
-    const renderedKeys = new Set();
-    for (const row of rows.filter((r) => states.get(r.id)?.subtask_of && !this.errors.has(r.id))) {
-      const c = states.get(row.id);
-      if (!cards.has(c.subtask_of)) throw new Error(`subtask ${row.id} has no arc ${c.subtask_of}`);
-      const taken = occupied.get(c.subtask_of) ?? new Set(); occupied.set(c.subtask_of, taken);
-      const match = /^([a-z]+\d+)\s+(.+)$/.exec(row.title);
-      let key = this.taskKeys.get(row.id)?.split(':').at(-1) ?? match?.[1];
-      if (!key || renderedKeys.has(`${c.subtask_of}:${key}`)) { let n = 1; while (taken.has(`c${n}`)) n++; key = `c${n}`; }
-      taken.add(key); renderedKeys.add(`${c.subtask_of}:${key}`); this.taskKeys.set(row.id, `${c.subtask_of}:${key}`);
-    }
-    for (const row of rows.filter((r) => states.get(r.id)?.subtask_of && !this.errors.has(r.id))) {
-      const c = states.get(row.id); const parent = cards.get(c.subtask_of);
-      const key = this.taskKeys.get(row.id).split(':').at(-1);
-      const match = /^([a-z]+\d+)\s+(.+)$/.exec(row.title);
-      const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([{ id: row.id, title: row.title, status: c.stage ?? row.status, body: row.body ?? '' }])).issues[0];
-      const originalTask = this.originals.get(c.subtask_of)?.acceptanceCriteria.find((t) => t.id === key);
-      const blocks = json(c.blocked_by, []);
-      const messages = blocks.filter(block => block.kind === 'message');
-      parent.acceptanceCriteria.push({ sources: originalTask?.sources, id: key, status: ['done', 'cancelled'].includes(c.stage ?? row.status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? row.title,
-        metadata: { id: row.id, status: c.stage ?? row.status, body: parsed.body, assignee: row.assignee, machine: c.machine,
-          properties: Object.fromEntries(Object.entries(row).filter(([k,v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null)),
-          card: { paused: json(c.paused, null) ?? undefined, every: c.every || undefined } }, lines: parsed.acceptance,
+      const offsets = []; let offset = 0;
+      for (const e of entries) { offsets.push(offset); offset += e.len; }
+      const dropped = [];
+      for (const edit of edits[role].filter((e) => e.index !== undefined).sort((a, b) => b.index - a.index)) {
+        const old = entries[edit.index];
+        text = text.slice(0, offsets[edit.index]) + (edit.remove ? '' : edit.entry.text) + text.slice(offsets[edit.index] + old.len);
+        dropped.push(old.cid);
+        if (edit.remove) entries.splice(edit.index, 1); else entries[edit.index] = edit.entry;
+      }
+      for (const edit of edits[role].filter((e) => e.index === undefined)) {
+        if (text && !text.endsWith('\n\n')) {
+          // the blank line before a new section belongs to the span above it
+          const last = entries.at(-1), separator = text.endsWith('\n') ? '\n' : '\n\n';
+          const lastText = last.text ?? this.texts([last])[0].text;
+          if (last.cid !== null) dropped.push(last.cid);
+          entries[entries.length - 1] = { ...last, cid: null, len: last.len + separator.length, text: lastText + separator };
+          text += separator;
+        }
+        text += edit.entry.text;
+        entries.push(edit.entry);
+      }
+      for (const cid of dropped) if (cid !== null) this.statement('DELETE FROM main.board_chunks WHERE cid = ?').run(cid);
+      this.put(`chunks:${role}`, entries.map((e) => ({ cid: e.cid ?? Number(this.statement('INSERT INTO main.board_chunks (text) VALUES (?)').run(e.text).lastInsertRowid), id: e.id, level: e.level, len: e.len, rec: e.rec })));
+      files.push({ role, path: doc.path, before: current.hash, after: hash(text), base: lf(current.raw), text });
+      published[role] = hash(text);
+    }
+    if (files.length) this.put('published', published);
+    return files;
+  }
+
+  // The document record of card `id`, from its rows and its subtasks' rows.
+  recordOf(id, row, c, where) {
+    const fileId = (x) => where.get(x)?.entry.id ?? x;
+    const keyOf = (x) => this.one('SELECT key FROM main.board_tasks WHERE id = ?', x)?.key ?? null;
+    const parse = (record) => this.preset.KanbanRootSchema.parse(this.preset.parseKanban([record])).issues[0];
+    const parsed = parse({ id: fileId(id), title: row.title, status: c.stage ?? row.status, assignee: row.assignee || undefined, body: row.body ?? '' });
+    const metadata = Object.fromEntries(Object.entries(row).filter(([k, v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null));
+    if (c.archived) metadata.archived = true;
+    if (json(c.blocked_by, []).length) metadata.blocked_by = json(c.blocked_by, []);
+    const card = { ...parsed, metadata, priority: row.priority ?? 0, workspace: row.workspace_kind + (row.workspace_kind !== 'scratch' && (c.workspace_anchor ?? row.workspace_path) ? `:${c.workspace_anchor ?? row.workspace_path}` : ''),
+      branch: row.branch_name || undefined, machine: c.machine || undefined, paused: json(c.paused, null) ?? undefined, every: c.every || undefined,
+      // Task lines left in a stored body (create and specify file them as subtasks) stay in its Tasks, before its subtasks.
+      relations: json(c.blocked_by, []).map((b) => ({ type: 'blocked-by', issueId: fileId(b.id) })), acceptanceCriteria: [...(parsed.acceptanceCriteria ?? [])] };
+    const rows = this.statement('SELECT t.* FROM main.tasks t JOIN main.supercode_cards s ON s.task_id = t.id WHERE s.subtask_of = ? ORDER BY t.created_at, t.id').all(id);
+    const states = new Map(rows.map((r) => [r.id, this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', r.id)]));
+    const keys = new Map(), taken = new Set(card.acceptanceCriteria.map((task) => task.id));
+    for (const r of rows) { const key = keyOf(r.id)?.split(':').at(-1) ?? /^([a-z]+\d+)\s/.exec(r.title)?.[1]; if (key && !taken.has(key)) { keys.set(r.id, key); taken.add(key); } }
+    for (const r of rows) {
+      if (keys.has(r.id)) continue;
+      let n = 1; while (taken.has(`c${n}`)) n++;
+      keys.set(r.id, `c${n}`); taken.add(`c${n}`);
+    }
+    for (const r of rows) {
+      const s = states.get(r.id), key = keys.get(r.id), status = s.stage ?? r.status;
+      const stored = this.one('SELECT key, sources FROM main.board_tasks WHERE id = ?', r.id);
+      if (stored?.key !== `${id}:${key}`) this.statement('INSERT INTO main.board_tasks (id, key, sources) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET key = excluded.key').run(r.id, `${id}:${key}`, stored?.sources ?? null);
+      const match = /^([a-z]+\d+)\s+(.+)$/.exec(r.title);
+      const task = parse({ id: r.id, title: r.title, status, body: r.body ?? '' });
+      const blocks = json(s.blocked_by, []);
+      const messages = blocks.filter((block) => block.kind === 'message');
+      card.acceptanceCriteria.push({ sources: json(stored?.sources, undefined) ?? undefined, id: key, status: ['done', 'cancelled'].includes(status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? r.title,
+        metadata: { id: r.id, status, body: task.body, assignee: r.assignee, machine: s.machine,
+          properties: Object.fromEntries(Object.entries(r).filter(([k, v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null)),
+          card: { paused: json(s.paused, null) ?? undefined, every: s.every || undefined } }, lines: task.acceptance,
         waitingOn: messages[0]?.id,
-        blockedBy: blocks.filter(block => block !== messages[0]).map(block => {
-          const target = this.taskKeys.get(block.id);
-          if (!target) return { issue: this.fileIds.get(block.id) ?? block.id };
-          const [arcId, taskKey] = target.split(':');
-          return { issue: this.fileIds.get(arcId) ?? arcId, ac: taskKey };
+        blockedBy: blocks.filter((block) => block !== messages[0]).map((block) => {
+          const target = keyOf(block.id);
+          if (!target) return { issue: fileId(block.id) };
+          const at = target.lastIndexOf(':');
+          return { issue: fileId(target.slice(0, at)), ac: target.slice(at + 1) };
         }) });
     }
-    const open = [], archived = [];
-    if(affected)for(const [id,{record,path}] of this.documentRecords??[])if(!affected.has(id)&&!this.errors.has(id))(path===this.path?open:archived).push(record);
-    for (const [id, card] of cards) {
-      const serialized = this.preset.serializeKanbanCard(card);
-      const record = { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
-      // Fingerprint the codec's persisted projection, not the pre-serialization input.
-      // The codec normalizes bodies (including their trailing newline) and subtask titles.
-      const persisted = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([record])).issues[0];
-      const rows = this.cardRows(id, persisted);
-      this.publishedFingerprints[id] = this.fingerprint(rows.task, rows.state);
-      for (const [tid, taskCard] of this.taskCards(id, persisted)) {
-        const rows = this.cardRows(tid, taskCard, id);
-        this.publishedFingerprints[tid] = this.fingerprint(rows.task, rows.state);
-      }
-      (states.get(id)?.archived || ['done', 'cancelled'].includes(card.status) ? archived : open).push(record);
+    const serialized = this.preset.serializeKanbanCard(card);
+    return { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+  }
+
+  // ------------------------------------------------------------------ migration from a SQLite board
+
+  indexForSeed() {
+    const published = {};
+    for (const doc of this.docs) {
+      const current = this.fileHash(doc.path);
+      for (const e of this.entries(doc.role)) this.statement('DELETE FROM main.board_chunks WHERE cid = ?').run(e.cid);
+      this.put(`chunks:${doc.role}`, this.codec.chunkBoardDocument(lf(current.raw), doc.path).map((chunk) => ({
+        cid: Number(this.statement('INSERT INTO main.board_chunks (text) VALUES (?)').run(chunk.text).lastInsertRowid), id: chunk.id, level: chunk.level, len: chunk.text.length, rec: null })));
+      published[doc.role] = current.hash;
     }
-    const original=this.documentRecords;
-    const changedPath=path=>!affected||[...affected].some(id=>original?.get(id)?.path===path||cards.has(id)&&((states.get(id)?.archived||['done','cancelled'].includes(cards.get(id).status))?this.archive:this.path)===path);
-    return { open: !changedPath(this.path)?this.text:this.renderDocument(this.text, open, this.path, [...(this.preserve.get(this.path)??[])]), archived: !changedPath(this.archive)?this.archiveText:this.renderDocument(this.archiveText, archived, this.archive, [...(this.preserve.get(this.archive)??[])]) };
+    this.put('published', published);
+    this.seedIds = new Set(this.docs.flatMap((doc) => this.entries(doc.role).filter((e) => e.id).map((e) => nativeId(e.id))));
   }
-  snapshot(documents) {
-    const fingerprints = this.fingerprints();
-    if (this.saved.documentHashes?.open === hash(this.text) && this.saved.documentHashes?.archived === hash(this.archiveText)) {
-      for (const id of Object.keys(fingerprints)) if (this.saved.fingerprints?.[id]) fingerprints[id] = this.saved.fingerprints[id];
+
+  seedRows() {
+    const source = this.seed;
+    const insert = (table, row) => {
+      const columns = new Set(this.conn.prepare(`PRAGMA main.table_info(${quote(table)})`).all().map((c) => c.name));
+      const keys = Object.keys(row).filter((k) => columns.has(k));
+      if (keys.length) this.statement(`INSERT OR REPLACE INTO main.${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
+    };
+    for (const table of this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all()) this.conn.exec(`DELETE FROM main.${quote(table.name)}`);
+    for (const table of source.db.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
+      if (!this.tables.has(table.name)) continue;
+      for (const row of source.db.prepare(`SELECT * FROM ${quote(table.name)}`).all()) insert(table.name, row);
     }
-    return { bodyProjection:2, documentHashes:{open:hash(documents.open),archived:hash(documents.archived)}, errors:[...this.errors], fingerprints: { ...fingerprints, ...this.publishedFingerprints }, taskIds: Object.fromEntries([...this.taskKeys].map(([id, key]) => [key, id])) };
+    for (const task of this.conn.prepare('SELECT * FROM main.tasks').all()) {
+      const old = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', task.id) ?? {};
+      if (old.subtask_of) { const key = /^([a-z]+\d+)\s/.exec(task.title)?.[1]; if (key) this.statement('INSERT OR REPLACE INTO main.board_tasks (id, key) VALUES (?, ?)').run(task.id, `${old.subtask_of}:${key}`); }
+      const status = old.stage ?? task.status;
+      const mapped = source.mapping[status];
+      if (!mapped) throw new Error(`migration needs an explicit mapping for ${status} (${task.id})`);
+      let stage = typeof mapped === 'string' ? mapped : mapped.status;
+      if (mapped.preserve_completed && task.completed_at) stage = 'done';
+      const parents = this.conn.prepare('SELECT parent_id FROM main.task_links WHERE child_id = ?').all(task.id).map((p) => ({ id: p.parent_id, kind: 'card' }));
+      const last = this.one("SELECT kind, payload FROM main.task_events WHERE task_id = ? AND kind IN ('blocked','unblocked') ORDER BY id DESC LIMIT 1", task.id);
+      const wait = last?.kind === 'blocked' ? json(last.payload, {})?.waiting_on : null;
+      if (wait) parents.push({ id: wait, kind: 'message' });
+      insert('supercode_cards', { ...old, task_id: task.id, stage, archived: Number(Boolean(mapped.archived) || stage === 'cancelled'), blocked_by: JSON.stringify(parents),
+        every: mapped.every ?? old.every ?? null, next_run_at: mapped.every ? now() : old.next_run_at,
+        paused: mapped.paused ? JSON.stringify({ by: actorOf() ?? 'migration', reason: `migrated ${status}: ${json(last?.payload, {})?.reason ?? 'held by previous workflow'}` }) : null });
+      this.statement('UPDATE main.tasks SET status = ? WHERE id = ?').run(stage, task.id);
+      if (task.current_run_id && ['done', 'cancelled'].includes(stage)) {
+        this.statement("UPDATE main.task_runs SET ended_at = COALESCE(ended_at, ?), status = 'reclaimed', outcome = COALESCE(outcome, 'reclaimed') WHERE id = ?").run(now(), task.current_run_id);
+        this.statement('UPDATE main.tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL WHERE id = ?').run(task.id);
+      } else if (task.current_run_id) {
+        const run = this.one('SELECT metadata FROM main.task_runs WHERE id = ?', task.current_run_id);
+        const meta = json(run?.metadata, {}) ?? {}; meta.supercode = { ...meta.supercode, state: 'active' };
+        this.statement('UPDATE main.task_runs SET metadata = ? WHERE id = ?').run(JSON.stringify(meta), task.current_run_id);
+      }
+    }
+    this.put('hermes_cursor', Number(source.db.prepare('SELECT COALESCE(MAX(id),0) AS id FROM task_events').get().id));
   }
 
+  // ------------------------------------------------------------------ Hermes compatibility
+
   prepareHermes() {
-    if (this.seed || !existsSync(this.compatPath)) return null;
+    if (!this.compatLaidOut()) return null;
     let entry; try { entry = workflowFor(this.root); } catch { return null; }
     const compat = new DatabaseSync(this.compatPath, { readOnly: true });
     try {
-      const prepared = { entry, evidence: new Map(), version: this.get('version'), open: hash(read(this.path)), archived: hash(read(this.archive)) };
       const cursor = this.get('hermes_cursor', 0);
+      const prepared = { entry, evidence: new Map(), cursor };
       prepared.rows = compat.prepare('SELECT * FROM task_events WHERE id > ? ORDER BY id').all(cursor);
       for (const row of prepared.rows) {
         const payload = json(row.payload, {}) ?? {};
@@ -603,17 +800,18 @@ class ZtrackBoard {
       return prepared;
     } finally { compat.close(); }
   }
+
   lift(prepared) {
-    if (!prepared) return;
+    if (!prepared?.rows.length) return;
     const { entry, rows, evidence } = prepared;
     const before = actorOf();
     try {
       for (const row of rows) {
         const payload = json(row.payload, {}) ?? {};
         if (payload.__supercode_export) continue;
-        const task = this.mem.prepare('SELECT * FROM tasks WHERE id = ?').get(row.task_id);
+        const task = this.one('SELECT * FROM main.tasks WHERE id = ?', row.task_id);
         if (!task) continue;
-        this.mem.exec('SAVEPOINT hermes_card');
+        this.conn.exec('SAVEPOINT hermes_card');
         try {
           const roles = ['manager', 'reviewer', 'platform', 'hermes'];
           setActor(payload.by ?? 'hermes');
@@ -621,70 +819,108 @@ class ZtrackBoard {
           if (row.kind === 'unblocked') { name = 'unblock'; words = { ...words, reason: 'unblocked in Hermes', hermes: true }; }
           else if (row.kind === 'completed') { name = 'complete'; words.summary = payload.summary ?? task.result; words.ci = evidence.get(row.id); }
           else if (row.kind === 'blocked' || row.kind === 'dependency_wait') { name = 'block'; words.on = payload.on ?? payload.parent ?? null; words.hermes = true; }
-          else if (row.kind === 'archived' && statusOf(this.mem, task) !== 'done') name = 'cancel';
+          else if (row.kind === 'archived' && statusOf(this.db, task) !== 'done') name = 'cancel';
           if (row.kind === 'unblocked' && entry.workflow.verbs?.hermes_unpause) {
-            const resumed = fire(this.mem, this.board(), entry, task.id, 'hermes_unpause', { roles, payload: { hermes: true, reason: 'unblocked in Hermes' } });
-            for (const effect of resumed.effects) this.mem.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+            const resumed = fire(this.db, this.board(), entry, task.id, 'hermes_unpause', { roles, payload: { hermes: true, reason: 'unblocked in Hermes' } });
+            for (const effect of resumed.effects) this.statement('INSERT INTO main.supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
           }
           if (name) {
-            const apply = () => fire(this.mem, this.board(), entry, task.id, name, { roles, payload: words });
+            const apply = () => fire(this.db, this.board(), entry, task.id, name, { roles, payload: words });
             const result = name === 'complete' ? withCompletionEvidence(this.board(), task.id, words.ci, apply) : apply();
-            for (const effect of result.effects) this.mem.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+            for (const effect of result.effects) this.statement('INSERT INTO main.supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
           }
-          event(this.mem, task.id, 'hermes_lifted', { by: 'hermes', source_event: row.id, verb: name, kind: row.kind });
-          this.mem.exec('RELEASE hermes_card');
-        } catch(error) {
-          this.mem.exec('ROLLBACK TO hermes_card; RELEASE hermes_card');
-          event(this.mem, task.id, 'hermes_refused', {by:'hermes',source_event:row.id,kind:row.kind,reason:error.message});
+          event(this.db, task.id, 'hermes_lifted', { by: 'hermes', source_event: row.id, verb: name, kind: row.kind });
+          this.conn.exec('RELEASE hermes_card');
+        } catch (error) {
+          this.conn.exec('ROLLBACK TO hermes_card; RELEASE hermes_card');
+          event(this.db, task.id, 'hermes_refused', { by: 'hermes', source_event: row.id, kind: row.kind, reason: error.message });
         }
       }
     } finally { setActor(before); }
-    if (rows.length) this.put('hermes_cursor', rows.at(-1).id);
+    this.put('hermes_cursor', rows.at(-1).id);
+  }
+
+  // Changed rows reach kanban.db after their commit; a key stays queued until an export consumed
+  // the revision it read.
+  // The Hermes projection follows a committed write and never fails it. A failure keeps the queue for the next
+  // write and is recorded as `export_error` (with a line on stderr) until an export succeeds.
+  exportFollowing() {
+    try {
+      this.flushExport();
+      if (this.get('export_error', null)) this.small(() => this.drop('export_error'));
+    } catch (error) {
+      process.stderr.write(`supercode workflow: kanban.db export deferred: ${error.message}\n`);
+      try { this.small(() => this.put('export_error', { at: Date.now(), message: error.message })); } catch { /* the board itself is busy; the next write retries */ }
+    }
   }
+
   flushExport() {
-    const changes = this.get('export_pending', []);
-    if (!changes.length) return;
-    this.export(changes);
-    // Remove only the prefix this export consumed; another writer may append meanwhile.
-    this.runtime.exec('BEGIN');
+    if (!this.compatPath) return;
+    const queued = this.statement('SELECT name, key, rev FROM main.board_export').all();
+    // A kanban.db that does not exist yet, or that Hermes has not laid out, is written whole: every card and row.
+    const whole = !this.compatLaidOut();
+    if (!whole && !queued.length) return;
+    this.export(whole ? this.everyRow() : queued);
+    if (queued.length) this.small(() => { for (const q of queued) this.statement('DELETE FROM main.board_export WHERE name = ? AND key = ? AND rev = ?').run(q.name, q.key, q.rev); });
+  }
+
+  // Whether kanban.db exists with Hermes's tables.
+  compatLaidOut() {
+    if (!this.compatPath || !existsSync(this.compatPath)) return false;
+    let compat;
     try {
-      const pending = this.get('export_pending', []);
-      if (JSON.stringify(pending.slice(0, changes.length)) === JSON.stringify(changes)) this.put('export_pending', pending.slice(changes.length));
-      this.runtime.exec('COMMIT');
-    } catch (error) { this.runtime.exec('ROLLBACK'); throw error; }
+      compat = new DatabaseSync(this.compatPath, { readOnly: true });
+      return compat.prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN ('tasks', 'task_events')").get().n === 2;
+    } catch { return false; } finally { compat?.close(); }
+  }
+
+  everyRow() {
+    const rows = [];
+    for (const table of this.tables.values()) {
+      for (const row of this.statement(`SELECT ${table.keys.map(quote).join(',')} FROM main.${quote(table.name)}`).all()) rows.push({ name: table.name, key: JSON.stringify(table.keys.map((k) => row[k])) });
+    }
+    return rows;
+  }
+
+  rowOf(name, key) {
+    const table = this.tables.get(name);
+    if (!table) return null;
+    return this.one(`SELECT * FROM main.${quote(name)} WHERE ${table.keys.map((k) => `${quote(k)} IS ?`).join(' AND ')}`, ...JSON.parse(key)) ?? null;
   }
-  export(changes) {
+
+  export(queued) {
     let entry; try { entry = workflowFor(this.root); } catch { return; }
-    const projected=new Set(changes.filter(c=>['tasks','supercode_cards'].includes(c.source.name)).map(c=>JSON.parse(c.source.key)[0]));
-    for(const id of projected)if(this.mem.prepare('SELECT 1 FROM tasks WHERE id=?').get(id))projectStatus(this.mem,this.board(),entry,id);
+    const stored = (id) => storedStatus(this.db, this.board(), entry, id);
+    const projected = new Set(queued.filter((q) => ['tasks', 'supercode_cards'].includes(q.name)).map((q) => JSON.parse(q.key)[0]));
     const compat = new DatabaseSync(this.compatPath);
     try {
       compat.exec('BEGIN'); this.init(compat, { fresh: true });
       // Native events and Hermes events share an export database, not an id sequence.
       // Bootstrap the old identity mapping once; new exports allocate independent Hermes ids.
       if (!compat.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='supercode_export_events'").get()) {
-        compat.exec(`CREATE TABLE supercode_export_events (source_id INTEGER PRIMARY KEY, event_id INTEGER NOT NULL UNIQUE)`);
-        compat.exec(`INSERT INTO supercode_export_events SELECT id, id FROM task_events WHERE json_extract(payload, '$.__supercode_export') = 1`);
+        compat.exec('CREATE TABLE supercode_export_events (source_id INTEGER PRIMARY KEY, event_id INTEGER NOT NULL UNIQUE)');
+        compat.exec("INSERT INTO supercode_export_events SELECT id, id FROM task_events WHERE json_extract(payload, '$.__supercode_export') = 1");
         // Repair existing lowered holds on upgrade, once; subsequent exports stay proportional to changes.
-        for (const state of this.mem.prepare('SELECT task_id, paused, blocked_by FROM supercode_cards').all()) {
-          if (!json(state.paused, null) && !json(state.blocked_by, []).some((b) => b.kind === 'message')) continue;
-          projected.add(state.task_id); projectStatus(this.mem, this.board(), entry, state.task_id);
+        for (const state of this.statement('SELECT task_id, paused, blocked_by FROM main.supercode_cards').all()) {
+          if (json(state.paused, null) || json(state.blocked_by, []).some((b) => b.kind === 'message')) projected.add(state.task_id);
         }
       }
       // Every import is event-based. Existing unconsumed acts must never be erased by an export race.
       const cursor = this.get('hermes_cursor', 0);
       const unseen = compat.prepare('SELECT payload FROM task_events WHERE id > ?').all(cursor).some((r) => !json(r.payload, {})?.__supercode_export);
       if (unseen) throw new Error('Hermes wrote during board export; retained its events for the next read');
-      const sources = new Map(changes.map(c => [`${c.source.name}:${c.source.key}`, c.source]));
-      for (const id of projected) sources.set(`tasks:${JSON.stringify([id])}`, { name: 'tasks', key: JSON.stringify([id]), row: this.mem.prepare('SELECT * FROM tasks WHERE id = ?').get(id) });
-      for (const source of [...sources.values()]) {
-        const id = source.name === 'tasks' ? source.row?.id : source.name === 'supercode_cards' ? source.row?.task_id : null;
-        if (id) sources.set(`tasks:${JSON.stringify([id])}`, {name:'tasks',key:JSON.stringify([id]),row:this.mem.prepare('SELECT * FROM tasks WHERE id=?').get(id)});
+      const sources = new Map(queued.map((q) => [`${q.name}:${q.key}`, { name: q.name, key: q.key, row: this.rowOf(q.name, q.key) }]));
+      for (const id of projected) {
+        const row = this.rowOf('tasks', JSON.stringify([id]));
+        const state = this.rowOf('supercode_cards', JSON.stringify([id]));
+        const status = row ? stored(id) : null;
+        sources.set(`tasks:${JSON.stringify([id])}`, { name: 'tasks', key: JSON.stringify([id]), row: row && { ...row, status: status.stored } });
+        if (state || !row) sources.set(`supercode_cards:${JSON.stringify([id])}`, { name: 'supercode_cards', key: JSON.stringify([id]), row: state && { ...state, stage: status?.status ?? state.stage } });
       }
-      for (const {name,key,row:source} of sources.values()) {
+      for (const { name, key, row: source } of sources.values()) {
         if (name === 'sqlite_sequence') continue;
         if (!compat.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name)) continue;
-        const table = this.rows.tables.get(name);
+        const table = this.tables.get(name);
         if (name === 'task_events') {
           const sourceId = JSON.parse(key)[0];
           const mapped = compat.prepare('SELECT event_id FROM supercode_export_events WHERE source_id = ?').get(sourceId);
@@ -706,12 +942,13 @@ class ZtrackBoard {
           }
           continue;
         }
-        if (!source) { compat.prepare(`DELETE FROM ${quote(name)} WHERE ${table.keys.map(k=>`${quote(k)} IS ?`).join(' AND ')}`).run(...JSON.parse(key)); continue; }
-        const row = {...source};
-        const keys=Object.keys(row);
-        const previous=compat.prepare(`SELECT * FROM ${quote(name)} WHERE ${table.keys.map(k=>`${quote(k)} IS ?`).join(' AND ')}`).get(...JSON.parse(key));
-        if (previous && keys.every(k=>previous[k]===row[k]))continue;
-        compat.prepare(`INSERT OR REPLACE INTO ${quote(name)} (${keys.map(quote)}) VALUES (${keys.map(()=>'?')})`).run(...keys.map(k=>row[k]));
+        const where = table.keys.map((k) => `${quote(k)} IS ?`).join(' AND ');
+        if (!source) { compat.prepare(`DELETE FROM ${quote(name)} WHERE ${where}`).run(...JSON.parse(key)); continue; }
+        const columns = new Set(compat.prepare(`PRAGMA table_info(${quote(name)})`).all().map((c) => c.name));
+        const keys = Object.keys(source).filter((k) => columns.has(k));
+        const previous = compat.prepare(`SELECT * FROM ${quote(name)} WHERE ${where}`).get(...JSON.parse(key));
+        if (previous && keys.every((k) => previous[k] === source[k])) continue;
+        compat.prepare(`INSERT OR REPLACE INTO ${quote(name)} (${keys.map(quote)}) VALUES (${keys.map(() => '?')})`).run(...keys.map((k) => source[k]));
       }
       // Hermes recomputes ready on read. Its sticky block is the last blocked/unblocked event,
       // so lowering the status alone cannot preserve a pause (including one made by a document edit).
@@ -730,7 +967,7 @@ class ZtrackBoard {
       }
       compat.exec('COMMIT');
       // Exported events carry an origin marker and never advance the Hermes input cursor.
-    } catch (error) { try { compat.exec('ROLLBACK'); } catch {} throw error; }
+    } catch (error) { try { compat.exec('ROLLBACK'); } catch { /* not begun */ } throw error; }
     finally { compat.close(); }
   }
 }