@volter/supercode-orchestrator 0.4.88 → 0.4.90

package/board/engine.mjs

@@ -12,7 +12,7 @@ import { existsSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { claimer, event, json, newTaskId, now, tx } from './store.mjs';
-import { eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
+import { refreshCardInputs, eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
 export const WORKSPACE_KINDS = ['scratch', 'dir', 'worktree'];
@@ -321,6 +321,7 @@ export function setCaller(fn) { callerRoles = fn; }
 
 export async function act(board, id, name, { roles = null, payload = {}, extra = {} } = {}) {
   const entry = await loadWorkflow(board.root);
+  refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
   const result = tx(board, (db) => {
     roles ??= callerRoles(db, id);
     const r = fire(db, board, entry, id, name, { roles, payload, extra });
@@ -337,10 +338,12 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
 /** Take card `id` to `status` by the event the workflow says goes there for this caller (`goto`). */
 export async function goto(board, id, status, { roles = null, payload = {} } = {}) {
   const entry = await loadWorkflow(board.root);
-  const { name, refusal, from } = tx(board, (db) => {
+  refreshCardInputs(board, id, { commits: true });
+  const { name, refusal, from } = (() => {
+    const db=board.db;
     roles ??= callerRoles(db, id);
     return { ...eventTo(db, board, entry, id, status, { roles, payload }), from: statusOf(db, getTask(db, id)) };
-  });
+  })();
   if (from === status) return { from, to: status, moved: false, event: null };
   if (!name) throw new Error(refusal ?? `${id} is ${from}; no event you may send takes it to ${status}`);
   return { ...(await act(board, id, name, { roles, payload })), event: name };
@@ -348,7 +351,7 @@ export async function goto(board, id, status, { roles = null, payload = {} } = {
 
 /** The I/O a committed move asked for. */
 export async function runEffects(board, effects = []) {
-  const pending = tx(board, (db) => db.prepare('SELECT id, effect FROM supercode_effects ORDER BY id').all());
+  const pending = board.db.prepare('SELECT id, effect FROM supercode_effects ORDER BY id').all();
   for (const e of [...pending.map((p) => ({ ...json(p.effect, {}), durableId: p.id })), ...effects]) {
     if (e.kind === 'cleanup_workspace') cleanupWorkspace(board, e.id);
     else if (e.kind === 'invalidate_descendants') tx(board, (db) => invalidateDescendants(db, board, e.id));

package/board/rows.mjs

@@ -0,0 +1,82 @@
+// Normalized runtime rows. Card text remains in the document; this stores only runtime
+// tables, run fields and small indexing metadata. No application locks or snapshot rewrites.
+import { json } from './store.mjs';
+const quote = s => `"${s.replaceAll('"', '""')}"`;
+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']);
+const OMIT = new Set(['tasks','supercode_cards','task_links','sqlite_sequence']);
+export class RuntimeRows {
+  constructor(db) { this.db=db; this.revision=null; this.tables=new Map(); this.runtime={}; this.clocks={}; this.cachedTasks={}; this.cachedCards={}; }
+  normalized() { return Boolean(this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='runtime_rows'").get()); }
+  watch(mem) {
+    mem.exec('CREATE TEMP TABLE IF NOT EXISTS _runtime_dirty (name TEXT, key TEXT, PRIMARY KEY(name,key))');
+    for (const {name,sql} of mem.prepare("SELECT name,sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all()) {
+      const columns=mem.prepare(`PRAGMA 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,sql,keys});
+      const key=prefix=>`json_array(${keys.map(k=>`${prefix}.${quote(k)}`).join(',')})`;
+      for(const [suffix,verb,prefix] of [['i','INSERT','NEW'],['u','UPDATE','NEW'],['d','DELETE','OLD']])
+        mem.exec(`CREATE TEMP TRIGGER IF NOT EXISTS ${quote(`_runtime_${name}_${suffix}`)} AFTER ${verb} ON main.${quote(name)} BEGIN INSERT OR IGNORE INTO _runtime_dirty VALUES ('${name}',${key(prefix)}); END`);
+    }
+    mem.exec('DELETE FROM _runtime_dirty');
+  }
+  insert(mem,name,row,key=null) {
+    if(row===null) {
+      const table=this.tables.get(name);if(!table)return;
+      mem.prepare(`DELETE FROM ${quote(name)} WHERE ${table.keys.map(k=>`${quote(k)} IS ?`).join(' AND ')}`).run(...JSON.parse(key));return;
+    }
+    const keys=Object.keys(row);
+    mem.prepare(`INSERT OR REPLACE INTO ${quote(name)} (${keys.map(quote).join(',')}) VALUES (${keys.map(()=>'?').join(',')})`).run(...keys.map(k=>row[k]??null));
+  }
+  load(mem,{fresh=false}={}) {
+    if(!this.normalized())return false;
+    if(fresh) {
+      for(const row of this.db.prepare('SELECT name,sql FROM runtime_schema').all()) mem.exec(row.sql.replace('CREATE TABLE ','CREATE TABLE IF NOT EXISTS '));
+      this.watch(mem);
+    }
+    const query=this.revision===null?'SELECT * FROM runtime_rows':'SELECT * FROM runtime_rows WHERE revision>?';
+    const rows=this.revision===null?this.db.prepare(query).all():this.db.prepare(query).all(this.revision);
+    for(const row of rows) {
+      const value=json(row.value,null);
+      if(row.name==='@runtime') { if(value)this.runtime[row.key]=value;else delete this.runtime[row.key]; }
+      else if(row.name==='@clock') { if(value)this.clocks[row.key]=value;else delete this.clocks[row.key]; }
+      else if(row.name==='@task_cache') { if(value)this.cachedTasks[row.key]=value;else delete this.cachedTasks[row.key]; }
+      else if(row.name==='@card_cache') { if(value)this.cachedCards[row.key]=value;else delete this.cachedCards[row.key]; }
+      else this.insert(mem,row.name,value,row.key);
+    }
+    this.revision=Number(this.db.prepare("SELECT value FROM state WHERE key='rows_revision'").get()?.value??0);
+    return true;
+  }
+  changes(mem,{all=false}={}) {
+    const dirty=all?[...this.tables.values()].flatMap(t=>mem.prepare(`SELECT ${t.keys.map(quote).join(',')} FROM ${quote(t.name)}`).all().map(row=>({name:t.name,key:JSON.stringify(t.keys.map(k=>row[k]))}))):mem.prepare('SELECT * FROM _runtime_dirty').all();
+    return dirty.map(({name,key})=>{
+      const table=this.tables.get(name);
+      const row=mem.prepare(`SELECT * FROM ${quote(name)} WHERE ${table.keys.map(k=>`${quote(k)} IS ?`).join(' AND ')}`).get(...JSON.parse(key))??null;
+      if(name==='tasks')return {name:'@runtime',key:JSON.parse(key)[0],value:row&&Object.fromEntries(Object.entries(row).filter(([k])=>RUNTIME.has(k))),source:{name,key,row}};
+      if(name==='supercode_cards')return {name:'@clock',key:JSON.parse(key)[0],value:row&&{since:row.since,after_fired:row.after_fired,next_run_at:row.next_run_at},source:{name,key,row}};
+      return {name,key,value:row,source:{name,key,row}};
+    });
+  }
+  write(changes) {
+    this.db.exec('CREATE TABLE IF NOT EXISTS runtime_schema(name TEXT PRIMARY KEY,sql TEXT NOT NULL); CREATE TABLE IF NOT EXISTS runtime_rows(name TEXT,key TEXT,value TEXT,revision INTEGER NOT NULL,PRIMARY KEY(name,key)); CREATE INDEX IF NOT EXISTS runtime_rows_revision ON runtime_rows(revision)');
+    const revision=Number(this.db.prepare("SELECT value FROM state WHERE key='rows_revision'").get()?.value??0)+1;
+    const statement=this.db.prepare('INSERT INTO runtime_rows VALUES(?,?,?,?) ON CONFLICT(name,key) DO UPDATE SET value=excluded.value,revision=excluded.revision');
+    for(const {name,key,value,source} of changes) {
+      if (OMIT.has(name)) continue;
+      const encoded=value===null?null:JSON.stringify(value);
+      if (this.db.prepare('SELECT value FROM runtime_rows WHERE name=? AND key=?').get(name,key)?.value !== encoded) statement.run(name,key,encoded,revision);
+      if(name==='@runtime' || name==='@clock') {
+        const cacheName=name==='@runtime'?'@task_cache':'@card_cache';
+        const cache=name==='@runtime'?this.cachedTasks:this.cachedCards;
+        const encodedCache=source?.row?JSON.stringify(source.row):null;
+        if (this.db.prepare('SELECT value FROM runtime_rows WHERE name=? AND key=?').get(cacheName,key)?.value !== encodedCache) statement.run(cacheName,key,encodedCache,revision);
+        if(source?.row)cache[key]=source.row;else delete cache[key];
+      }
+      if(name==='@runtime') { if(value)this.runtime[key]=value;else delete this.runtime[key]; }
+      if(name==='@clock') { if(value)this.clocks[key]=value;else delete this.clocks[key]; }
+    }
+    for(const {name,sql} of this.tables.values())if(!OMIT.has(name))this.db.prepare('INSERT OR IGNORE INTO runtime_schema VALUES(?,?)').run(name,sql);
+    this.db.prepare("INSERT INTO state VALUES('rows_revision',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(String(revision));
+    this.revision=revision;
+  }
+}

package/board/workflow.mjs

@@ -80,7 +80,7 @@ function pattern(p) {
 // the time of the latest commit that names `id` in its message, on any ref of the repository at `path` (a worktree's
 // pushes land on the shared remote-tracking refs), or null (asked only when an expression does)
 const commitTimes = new Map();
-function lastCommitAt(path, id) {
+function observeLastCommit(path, id) {
   if (!path) return null;
   const key = `${path}:${id}`;
   const cached = commitTimes.get(key);
@@ -108,6 +108,18 @@ function lastCommitAt(path, id) {
   return value;
 }
 
+function lastCommitAt(path, id) { return path ? commitTimes.get(`${path}:${id}`)?.value ?? null : null; }
+/** Observe external facts before entering an optimistic board mutation. */
+export function refreshCardInputs(board, id, { commits = false } = {}) {
+  const task=board.db.prepare('SELECT t.*,c.subtask_of FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
+  if (!task)return;
+  if (commits) {
+    const own=task.workspace_kind!=='scratch'?task.workspace_path:null;
+    const parent=!own && task.subtask_of?board.db.prepare('SELECT workspace_path FROM tasks WHERE id=?').get(task.subtask_of)?.workspace_path:null;
+    observeLastCommit(own??parent??null,id);
+  }
+}
+
 // Mailbox I/O is prefetched by the dispatcher, outside every board write.
 const mailboxAnswers = new Map();
 const execFileAsync = promisify(execFile);
@@ -124,7 +136,7 @@ export async function refreshRelationAnswers(board) {
       const { stdout } = await execFileAsync(process.env.SUPERCODE_BIN || 'supercode', ['message', 'show', '--replies', id, '--json'], { encoding: 'utf8', timeout: 20_000, maxBuffer: 1024 * 1024 });
       const rows = JSON.parse(stdout);
       if (!Array.isArray(rows)) throw new Error('message door returned no message list');
-      mailboxAnswers.set(id, { answer: rows[0]?.replies?.[0]?.id ?? null });
+      mailboxAnswers.set(id, { answer: rows[0]?.replies?.[0]?.id ?? null, askedOf: rows[0]?.message?.session ?? null });
     } catch (error) { mailboxAnswers.set(id, { error: `the answer to ${id} could not be read: ${error.message.slice(0, 200)}` }); }
   }));
 }
@@ -173,14 +185,7 @@ function timeOf(db, task) {
 }
 
 /** The session message `id` was filed for (`supercode message show`): who was asked; or null. */
-function askedOf(id) {
-  if (!id) return null;
-  const r = spawnSync(process.env.SUPERCODE_BIN || 'supercode', ['message', 'show', id, '--json'], { encoding: 'utf8', timeout: 20_000 });
-  let rows = null;
-  try { rows = JSON.parse(r.stdout); } catch { /* read below */ }
-  if (!Array.isArray(rows)) throw new Error(`who ${id} was sent to could not be read (supercode message show): ${(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim().slice(-200)}`);
-  return rows[0]?.message?.session ?? null;
-}
+function askedOf(id) { return mailboxAnswers.get(id)?.askedOf ?? null; }
 
 /** The scope an expression is evaluated in: the card (with its relations), the event, params, time, extras. */
 export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}) {
@@ -300,6 +305,7 @@ export function transitionsFor(workflow, status, name) {
  * `{ from, to, effects }`; throws the refusal when no transition applies or a validator fails.
  */
 export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
+  if (db.boardErrors?.has(id)) throw new Error(`${id}: ${db.boardErrors.get(id)}`);
   const { workflow, params } = entry;
   if (workflow.run && (workflow.run.on?.[name] || Object.values(workflow.run.states ?? {}).some((s) => s.on?.[name]))) return fireRun(db, board, entry, id, name, { roles, payload, extra });
   const task = cardOf(db, id);

package/board/ztrack.mjs

@@ -4,7 +4,7 @@ import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+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';
@@ -40,16 +40,18 @@ class ZtrackBoard {
     this.preset = require('@volter/ztrack/kanban-preset');
     this.runtime = new DatabaseSync(`${marker}.runtime.db`);
     if (!this.runtime.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='state'").get()) this.runtime.exec('CREATE TABLE state (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
-    this.mem = null; this.active = false;
+    this.errors = new Map(); this.preserve = new Map();
+    this.mem = null; this.active = false; this.rows = new RuntimeRows(this.runtime);
     mkdirSync(dirname(this.path), { recursive: true });
     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)); },
       close() { self.close(); },
     };
     if (seed) this.tx(() => {});
-    else { this.load(); this.loadedStamp = this.stamp(); }
+    else this.readOnly(()=>{ this.load(); this.loadedStamp = this.stamp(); });
   }
   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)); }
@@ -57,7 +59,9 @@ class ZtrackBoard {
     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(!/busy|locked/i.test(error.message))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);
@@ -67,13 +71,33 @@ class ZtrackBoard {
   recover() {
     const pending = this.get('pending');
     if (!pending) return;
-    for (const file of pending.files) {
-      const current = hash(read(file.path));
-      if (current !== file.before && current !== hash(file.text)) throw new Error(`unfinished board write conflicts with an edit to ${file.path}; retained runtime journal`);
-      if (current === file.before) atomic(file.path, file.text);
+    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];
+      }
     }
     this.put('snapshot', pending.snapshot);
-    if (pending.intent) this.put(`applied:${pending.intent}`, true);
+    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();
   }
@@ -84,7 +108,7 @@ class ZtrackBoard {
 
   transaction(fn) {
     for (;;) {
-      try { this.runtime.exec('BEGIN IMMEDIATE'); }
+      try { this.runtime.exec('BEGIN'); }
       catch (error) { if (!/busy|locked/i.test(error.message)) throw error; continue; }
       this.active = true;
       let committed = false;
@@ -98,48 +122,59 @@ class ZtrackBoard {
         if (this.seed) this.seedIntoMemory();
         else this.lift();
         const result = fn(this.db);
-        const documents = this.documents();
-        const files = [{ path: this.path, before: hash(this.text), text: documents.open }, { path: this.archive, before: hash(this.archiveText), text: documents.archived }];
+        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 cardDirty = this.seed || changes.some(({source})=>{
+          if(source.name==='tasks')return JSON.stringify(canonical(source.row,new Set([...RUNTIME,'status'])))!==JSON.stringify(canonical(this.rows.cachedTasks[JSON.parse(source.key)[0]],new Set([...RUNTIME,'status'])));
+          if(source.name==='supercode_cards')return JSON.stringify(canonical(source.row,new Set(['since','after_fired','next_run_at'])))!==JSON.stringify(canonical(this.rows.cachedCards[JSON.parse(source.key)[0]],new Set(['since','after_fired','next_run_at'])));
+          return source.name==='task_links';
+        });
+        const documents = cardDirty ? this.documents() : {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();
         this.computing = false;
-        this.runtime.exec('BEGIN IMMEDIATE');
+        this.runtime.exec('BEGIN');
         this.recover();
-        if (this.get('version') !== version || files.some((f) => hash(read(f.path)) !== f.before)) { this.runtime.exec('ROLLBACK'); continue; }
+        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 this.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 });
+        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 IMMEDIATE');
+        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; return result; }
-          continue;
+          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;
         }
         // 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');
-          continue;
+          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.export();
+        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 (!/busy|locked|Hermes wrote/i.test(error.message)) throw error; }
         this.loadedStamp = this.stamp();
         this.seed = null;
         return result;
       } catch (error) {
         try { this.runtime.exec('ROLLBACK'); } catch { /* intent already durable */ }
-        if (/busy|locked|Hermes wrote/i.test(error.message)) continue;
+        this.invalidate();
+        if (/busy|locked|Hermes wrote|document changed during recovery/i.test(error.message)) continue;
         if (committed) error.message += ' (the runtime journal retains any unfinished document write)';
         throw error;
       } finally { this.active = false; this.computing = false; this.pendingValues = null; }
     }
   }
+  invalidate() { this.mem?.close(); this.mem = null; this.rows = new RuntimeRows(this.runtime); this.loadedStamp = null; }
   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)}`);
@@ -172,6 +207,7 @@ class ZtrackBoard {
         this.mem.prepare('UPDATE task_runs SET metadata = ? WHERE id = ?').run(JSON.stringify(meta), task.current_run_id);
       }
     }
+    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) {
@@ -181,15 +217,49 @@ class ZtrackBoard {
     this.mem.prepare(`INSERT OR REPLACE INTO ${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
   }
   load({ observe = false } = {}) {
-    this.text = read(this.path); this.archiveText = read(this.archive);
-    this.mem?.close(); this.mem = new DatabaseSync(':memory:'); this.init(this.mem, { fresh: true });
+    const text = read(this.path), archiveText = read(this.archive);
+    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: {} });
-    for (const item of Object.values(this.saved.tables ?? {})) {
+    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);
     }
-    const records = [...this.codec.parseBoardDocument(this.text, this.path), ...this.codec.parseBoardDocument(this.archiveText, this.archive)];
-    const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban(records));
+    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=? WHERE task_id=?').run(row.since??null,row.after_fired??null,row.next_run_at??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 = [];
+    for (const [text,path] of [[this.text,this.path],[this.archiveText,this.archive]]) {
+      const result = this.codec.inspectBoardDocument(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) {
+        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);
@@ -209,6 +279,22 @@ class ZtrackBoard {
         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`);
+      }
+    }
+    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.');
+    }
     // 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()) {
@@ -241,6 +327,7 @@ class ZtrackBoard {
     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 {}
@@ -252,21 +339,20 @@ class ZtrackBoard {
       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]) {
-      if (this.saved.runtime?.[id]?.current_run_id) throw new Error(`document removed ${id} with a live run; cancel it through its workflow first`);
+    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() {
-    const r = spawnSync('git', ['-C', dirname(this.path), 'log', '-1', '--format=%an <%ae>', '--', this.path], { encoding: 'utf8', timeout: 5000 });
-    return r.status === 0 && r.stdout.trim() ? `git:${r.stdout.trim()}` : 'document-editor';
+    return 'document-editor';
   }
   documents() {
     const rows = 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 byId = new Map(rows.map((r) => [r.id, r]));
     const cards = new Map();
-    for (const row of rows.filter((r) => !states.get(r.id)?.subtask_of)) {
+    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));
@@ -284,7 +370,7 @@ class ZtrackBoard {
       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)) {
+    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);
       if (!parent) 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);
@@ -306,17 +392,12 @@ class ZtrackBoard {
       const record = { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
       (states.get(id)?.archived || ['done', 'cancelled'].includes(card.status) ? archived : open).push(record);
     }
-    return { open: this.codec.renderBoardDocument(this.text, open, this.path), archived: this.codec.renderBoardDocument(this.archiveText, archived, this.archive) };
+    return { open: this.codec.renderBoardDocument(this.text, open, this.path, [...(this.preserve.get(this.path)??[])]), archived: this.codec.renderBoardDocument(this.archiveText, archived, this.archive, [...(this.preserve.get(this.archive)??[])]) };
   }
   snapshot() {
-    const tables = {};
-    for (const table of this.mem.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
-      if (!EPHEMERAL.has(table.name)) tables[table.name] = { ...table, rows: this.mem.prepare(`SELECT * FROM ${quote(table.name)}`).all() };
-    }
-    const runtime = Object.fromEntries(this.mem.prepare('SELECT * FROM tasks').all().map((t) => [t.id, Object.fromEntries(Object.entries(t).filter(([k]) => RUNTIME.has(k)))]));
-    const clocks = Object.fromEntries(this.mem.prepare('SELECT * FROM supercode_cards').all().map((c) => [c.task_id, { since: c.since, after_fired: c.after_fired, next_run_at: c.next_run_at }]));
-    return { tables, runtime, clocks, fingerprints: this.fingerprints(), taskIds: Object.fromEntries([...this.taskKeys].map(([id, key]) => [key, id])) };
+    return { fingerprints: this.fingerprints(), taskIds: Object.fromEntries([...this.taskKeys].map(([id, key]) => [key, id])) };
   }
+
   lift() {
     if (!existsSync(this.compatPath)) return;
     let entry; try { entry = workflowFor(this.root); } catch { return; }
@@ -331,6 +412,8 @@ class ZtrackBoard {
           if (payload.__supercode_export) continue;
           const task = this.mem.prepare('SELECT * FROM tasks WHERE id = ?').get(row.task_id);
           if (!task) continue;
+          this.mem.exec('SAVEPOINT hermes_card');
+          try {
           const roles = ['manager', 'reviewer', 'platform', 'hermes'];
           setActor(payload.by ?? 'hermes');
           let name = null; let words = { ...payload, reason: payload.reason ?? 'unblocked in Hermes' };
@@ -347,34 +430,56 @@ class ZtrackBoard {
             for (const effect of result.effects) this.mem.prepare('INSERT INTO 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});
+          }
         }
       } finally { setActor(before); }
       if (rows.length) this.put('hermes_cursor', rows.at(-1).id);
     } finally { compat.close(); }
   }
-  export() {
+  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');
+    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; }
+  }
+  export(changes) {
     let entry; try { entry = workflowFor(this.root); } catch { return; }
     for (const { id } of this.mem.prepare('SELECT id FROM tasks').all()) projectStatus(this.mem, this.board(), entry, id);
     const compat = new DatabaseSync(this.compatPath);
-    compat.exec('PRAGMA busy_timeout = 10000');
     try {
-      compat.exec('BEGIN IMMEDIATE'); this.init(compat, { fresh: true });
+      compat.exec('BEGIN'); this.init(compat, { fresh: true });
       // 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 tables = this.mem.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
-      for (const { name } of tables) {
-        if (!compat.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name)) continue;
-        compat.exec(`DELETE FROM ${quote(name)}`);
-        for (const source of this.mem.prepare(`SELECT * FROM ${quote(name)}`).all()) {
-          const row = { ...source };
-          if (name === 'task_events') row.payload = JSON.stringify({ ...json(row.payload, {}), __supercode_export: true });
-          const keys = Object.keys(row); compat.prepare(`INSERT INTO ${quote(name)} (${keys.map(quote)}) VALUES (${keys.map(() => '?')})`).run(...keys.map((k) => row[k]));
-        }
+      const sources = new Map(changes.map(c => [`${c.source.name}:${c.source.key}`, c.source]));
+      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)});
+      }
+      for (const {name,key,row:source} of sources.values()) {
+        if (!compat.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name)) continue;
+        const table = this.rows.tables.get(name);
+        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};
+        if (name === 'task_events') row.payload = JSON.stringify({...json(row.payload,{}),__supercode_export:true});
+        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]));
       }
       compat.exec('COMMIT');
-      this.put('hermes_cursor', Number(compat.prepare('SELECT COALESCE(MAX(id),0) AS id FROM task_events').get().id));
+      // Exported events carry an origin marker and never advance the Hermes input cursor.
     } catch (error) { try { compat.exec('ROLLBACK'); } catch {} throw error; }
     finally { compat.close(); }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.88",
+  "version": "0.4.90",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -24,9 +24,9 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "yaml": "^2.9.0",
     "@volter/supercode-harness-sdk": "^0.3.41",
-    "@volter/ztrack": "^2.4.14"
+    "@volter/ztrack": "^2.4.15",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@chat-adapter/state-memory": "4.39.0",