@volter/supercode-orchestrator 0.5.69 → 0.5.71

package/board/files.mjs

@@ -9,6 +9,8 @@
 // runs, retries if that hash changed, and writes the cards it touched (temporary triggers name them), `_board.json` last. A read
 // outside a transaction reloads first when `_board.json` changed, as a SQLite reader sees the last commit.
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { fenced } from './fence.mjs';
+import { markRemovedHeads } from './published.mjs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
@@ -81,6 +83,8 @@ class FilesBoard {
   load() {
     const stamp = this.stampOf();
     if (this.mem && stamp === this.stamp) return;
+    const marked = this.mem && this.mem.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'supercode_publication_dirty'").get()
+      ? this.mem.prepare('SELECT DISTINCT task_id FROM supercode_publication_dirty').all().map((r) => r.task_id) : [];
     this.mem?.close();
     this.statements.clear();
     const mem = new DatabaseSync(':memory:');
@@ -96,6 +100,7 @@ class FilesBoard {
         mem.prepare(`INSERT INTO ${quote(table)} (${keys.map(quote).join(', ')}) VALUES (${keys.map(() => '?').join(', ')})`).run(...keys.map((k) => row[k]));
       }
     };
+    const previous = this.texts;
     this.texts = new Map();
     for (const name of readdirSync(this.dir)) {
       if (!name.endsWith('.json') || name.startsWith('_')) continue;
@@ -108,6 +113,19 @@ class FilesBoard {
     for (const { name, seq } of state?.sequence ?? []) {
       if (mem.prepare('UPDATE sqlite_sequence SET seq = MAX(seq, ?) WHERE name = ?').run(seq, name).changes === 0) mem.prepare('INSERT INTO sqlite_sequence (name, seq) VALUES (?, ?)').run(name, seq);
     }
+    // Loading inserts every card, which marks every card changed (published.mjs). The first load of this projection keeps
+    // those marks: its next write compares each card with its published head once (a named limit: each projection opened
+    // compares every card once, as each load already reads every card's file). A reload keeps the marks not yet
+    // published and adds only the cards whose files changed since (a hand edit, a card another writer added or removed);
+    // this process's own writes are already the texts it knows (persist), so they are not marked again.
+    if (previous && mem.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'supercode_publication_dirty'").get()) {
+      mem.exec('DELETE FROM supercode_publication_dirty');
+      const mark = mem.prepare('INSERT INTO supercode_publication_dirty (task_id) VALUES (?)');
+      const changed = [...new Set([...previous.keys(), ...this.texts.keys()])].filter((id) => previous.get(id) !== this.texts.get(id));
+      for (const id of new Set([...marked, ...changed])) mark.run(id);
+    }
+    // a card whose file is gone has no row to fire its delete trigger: its live head is marked, so it is published removed
+    if (mem.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'supercode_publication_heads'").get()) markRemovedHeads(mem);
     this.mem = mem;
     this.watch();
     this.stamp = stamp;
@@ -169,21 +187,22 @@ class FilesBoard {
       }
       const file = join(this.dir, `${String(id).replace(/[^A-Za-z0-9_.-]/g, '_')}.json`);
       if (!Object.keys(tables).length) {
-        if (this.texts.has(id)) { writes.push({ file, text: null }); wrote = true; }
+        if (this.texts.has(id)) { writes.push({ file, text: null, id }); wrote = true; }
         continue;
       }
       const text = `${JSON.stringify({ id, tables }, null, 2)}\n`;
       if (this.texts.get(id) === text) continue;
-      writes.push({ file, text });
+      writes.push({ file, text, id });
       wrote = true;
     }
     if (wrote || stateText !== this.stateText) {
       writes.push({ file: join(this.dir, STATE), text: stateText });
     }
     if (this.stampOf() !== this.stamp) return false;
-    for (const { file, text } of writes) {
+    for (const { file, text, id } of writes) {
       if (text === null) { try { unlinkSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
       else writeAtomic(file, text);
+      if (id !== undefined) { if (text === null) this.texts.delete(id); else this.texts.set(id, text); }
     }
     this.stamp = null; // next read reloads the committed file hashes and card texts
     return true;
@@ -216,6 +235,7 @@ class FilesBoard {
       const before = this.schema();
       this.mem.exec('BEGIN');
       this.inTx = true;
+      fenced(this.mem);
       let out;
       try {
         out = fn(this.db);

package/board/git-document.mjs

@@ -6,6 +6,7 @@
 // the two texts of a board document merged by ztrack's own document merge, in which a hand edit wins its cards. Nothing
 // either side wrote is dropped; a merge that cannot be made stops the push and says why, leaving both texts in the
 // checkout's history.
+import { current } from './call.mjs';
 import { execFileSync, spawn } from 'node:child_process';
 import { readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, relative } from 'node:path';
@@ -50,7 +51,7 @@ export class GitDocument {
   /** Said once per process: a checkout on no branch keeps its commits here (every write tried to push `HEAD:HEAD`
    *  three times, with a fetch and a merge between, and failed: seconds of network on each write, t_23e47b73). */
   detached() {
-    if (!this.warnedDetached) process.stderr.write(`board: the board documents' checkout ${this.root} is on no branch; writes are committed there and not pushed until it is on one\n`);
+    if (!this.warnedDetached) current().err(`board: the board documents' checkout ${this.root} is on no branch; writes are committed there and not pushed until it is on one\n`);
     this.warnedDetached = true;
   }
 

package/board/lock-holder.mjs

@@ -0,0 +1,49 @@
+// The board owner's one-per-home lock, held by a process of its own. A POSIX record lock belongs to the process that took
+// it, and any open and close of the same file in that process drops it; no reader in the owner can reach a lock another
+// process holds. The holder takes SQLite's exclusive lock on `board.lock` (the default VFS), says so, and exits when its
+// standard input closes, which the kernel does when the owner ends however it ends, so the lock is released with the
+// owner. One spawn per owner lifetime.
+import { spawn } from 'node:child_process';
+
+const HOLDER = `
+const { DatabaseSync } = require('node:sqlite');
+let lock;
+try {
+  lock = new DatabaseSync(process.argv[1]);
+  lock.exec('PRAGMA busy_timeout = 0; PRAGMA locking_mode = EXCLUSIVE; BEGIN EXCLUSIVE');
+} catch (error) { process.stdout.write('held ' + String(error.message).replace(/\\n/g, ' ') + '\\n'); process.exit(1); }
+process.stdout.write('ready\\n');
+process.stdin.on('data', () => {});
+process.stdin.on('end', () => process.exit(0));
+process.stdin.on('error', () => process.exit(0));
+`;
+
+/**
+ * Hold `path` for this process's life. Resolves once the holder has the lock; rejects with its reason when another
+ * owner holds it. `onLost` is told if the holder ends while this process still runs (the lock is then gone).
+ * Returns `release()`, which ends the holder.
+ */
+export function holdLock(path, { onLost = () => {} } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['--no-warnings', '-e', HOLDER, path], { stdio: ['pipe', 'pipe', 'ignore'] });
+    let said = '';
+    let ready = false;
+    let released = false;
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      said += chunk;
+      if (ready || !said.includes('\n')) return;
+      const line = said.slice(0, said.indexOf('\n'));
+      if (line === 'ready') {
+        ready = true;
+        child.unref(); child.stdout.unref?.(); child.stdin.unref?.();
+        resolve({ release: () => { released = true; child.stdin.end(); } });
+      } else reject(new Error(line.replace(/^held /, '')));
+    });
+    child.on('error', (error) => { if (!ready) reject(error); });
+    child.on('exit', (code, signal) => {
+      if (!ready) { if (!said.includes('\n')) reject(new Error(`the lock holder ended before it held the lock (${signal ?? code})`)); return; }
+      if (!released) onLost(new Error(`the lock holder for ${path} ended (${signal ?? code})`));
+    });
+  });
+}

package/board/owner-files.mjs

@@ -0,0 +1,19 @@
+// The owner never takes its own runtime files (`<home>/board.lock`, `<home>/board.sock`) as a path from outside: a verb's
+// input (cli.mjs callerPath) or a file the workflow names (workflow.mjs, a run's prompt_file). One real-path check.
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const RUNTIME = new Set(['board.lock', 'board.sock']);
+let home = null;
+
+/** The home this process owns (the owner's, set once when it binds). */
+export function ownHome(root) { try { home = realpathSync(root); } catch { home = resolve(root); } }
+
+/** `path`, unless its real path is one of the owned home's runtime files. */
+export function notRuntime(path) {
+  if (home === null) return path;
+  let real;
+  try { real = realpathSync(path); } catch { try { real = join(realpathSync(dirname(resolve(path))), basename(path)); } catch { return path; } }
+  if (dirname(real) === home && RUNTIME.has(basename(real))) throw new Error(`${path} is the board owner's own runtime file; no verb takes it`);
+  return path;
+}

package/board/published.mjs

@@ -1,4 +1,9 @@
-// The card writer commits the full snapshot and a retained delivery obligation together.
+// The card writer commits the changed cards' snapshots and a retained delivery obligation together (ADR 0003: a write is
+// proportional to the cards it changed; ADR 0008: a source change and its publication are one transaction).
+//
+// What changed is marked in the store itself: triggers on every table a card's snapshot reads note the card's id in
+// supercode_publication_dirty, whoever writes (this process, Hermes's native writer, a document import). A transaction
+// publishes the marked cards and clears their marks; one that marked nothing reads one row and publishes nothing.
 import { createHash, randomUUID } from 'node:crypto';
 export const PUBLICATION_SCHEMA = `
 CREATE TABLE IF NOT EXISTS supercode_publications (
@@ -10,7 +15,52 @@ CREATE TABLE IF NOT EXISTS supercode_publication_heads (
 );
 CREATE TABLE IF NOT EXISTS supercode_publication_log (
   id TEXT PRIMARY KEY, pruned_through INTEGER NOT NULL DEFAULT 0
-);`;
+);
+-- keyless: a writing statement's own conflict clause (an upsert, OR REPLACE, OR ABORT) governs its triggers' inserts
+-- too, so a key here would fail the writer's statement; readers take the distinct ids
+CREATE TABLE IF NOT EXISTS supercode_publication_dirty (task_id TEXT NOT NULL);
+CREATE INDEX IF NOT EXISTS supercode_publication_dirty_task ON supercode_publication_dirty(task_id);
+CREATE INDEX IF NOT EXISTS supercode_publication_heads_sequence ON supercode_publication_heads(sequence);`;
+
+const REVIEW_KIND_LIST = ['review_requested', 'approved', 'review_approved', 'changes_requested', 'escalated'];
+// The tables a card's snapshot reads (cardSnapshot), each with the column naming its card; a link names two.
+const MARKED = [['tasks', ['id']], ['supercode_cards', ['task_id']], ['task_comments', ['task_id']], ['task_runs', ['task_id']], ['task_links', ['parent_id', 'child_id']], ['task_events', ['task_id']]];
+/**
+ * The triggers that mark a changed card, on a store that has these tables (CREATE … IF NOT EXISTS: laid out on every
+ * open). A card already marked is not marked again, so a writer's many writes while the owner is away leave one mark.
+ * Their first installation reconciles once, in the same savepoint: every card and every live head is marked, so a
+ * change a native writer committed before any trigger existed (an edit, a new card, a deletion) is compared once.
+ */
+export function publicationTriggers(db) {
+  const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => row.name));
+  const first = !db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'trigger' AND name = 'supercode_publish_tasks_insert'").get();
+  const reviews = `(${REVIEW_KIND_LIST.map((kind) => `'${kind}'`).join(',')})`;
+  db.exec('SAVEPOINT supercode_publication_marking');
+  try {
+    for (const [table, columns] of MARKED) {
+      if (!tables.has(table)) continue;
+      // a task event changes a snapshot only when it is a review (the snapshot's `reviews`): an update marks when the
+      // row was one before or is one after
+      const when = (rows) => table === 'task_events' ? ` WHEN ${rows.map((row) => `${row}.kind IN ${reviews}`).join(' OR ')}` : '';
+      const mark = (row) => columns.map((column) => `INSERT INTO supercode_publication_dirty (task_id) SELECT ${row}.${column} WHERE ${row}.${column} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM supercode_publication_dirty WHERE task_id = ${row}.${column});`).join(' ');
+      db.exec(`CREATE TRIGGER IF NOT EXISTS supercode_publish_${table}_insert AFTER INSERT ON ${table}${when(['NEW'])} BEGIN ${mark('NEW')} END;
+        CREATE TRIGGER IF NOT EXISTS supercode_publish_${table}_update AFTER UPDATE ON ${table}${when(['OLD', 'NEW'])} BEGIN ${mark('NEW')} ${mark('OLD')} END;
+        CREATE TRIGGER IF NOT EXISTS supercode_publish_${table}_delete AFTER DELETE ON ${table}${when(['OLD'])} BEGIN ${mark('OLD')} END;`);
+    }
+    if (first && tables.has('tasks')) db.exec(`INSERT INTO supercode_publication_dirty (task_id)
+      SELECT id FROM tasks UNION SELECT resource_id FROM supercode_publication_heads WHERE digest != 'removed'
+      EXCEPT SELECT task_id FROM supercode_publication_dirty`);
+    db.exec('RELEASE supercode_publication_marking');
+  } catch (error) { db.exec('ROLLBACK TO supercode_publication_marking; RELEASE supercode_publication_marking'); throw error; }
+}
+
+/** Mark the live heads whose card is gone: a backing that loads cards from files (files.mjs) has no row to fire a delete
+ *  trigger when a card's file is removed outside it. */
+export function markRemovedHeads(db) {
+  db.exec(`INSERT INTO supercode_publication_dirty (task_id)
+    SELECT resource_id FROM supercode_publication_heads WHERE digest != 'removed' AND resource_id NOT IN (SELECT id FROM tasks)
+    EXCEPT SELECT task_id FROM supercode_publication_dirty`);
+}
 // Every card's head stays; older changes beyond this many are pruned in one batch once twice as many accumulate.
 // A reader whose cursor falls below the pruned floor takes a new snapshot.
 const RETAINED_CHANGES = 1024;
@@ -30,7 +80,7 @@ export function taskStatusOf(lane, completedAt) {
   return 'todo';
 }
 
-const REVIEW_KINDS="('review_requested','approved','review_approved','changes_requested','escalated')";
+const REVIEW_KINDS=`(${REVIEW_KIND_LIST.map((kind) => `'${kind}'`).join(',')})`;
 /** A card's rows read one card at a time. */
 const perCard=db=>({
   own:id=>db.prepare('SELECT * FROM supercode_cards WHERE task_id=?').get(id),
@@ -40,21 +90,6 @@ const perCard=db=>({
   parents:id=>db.prepare('SELECT parent_id FROM task_links WHERE child_id=? ORDER BY parent_id').all(id).map(link=>link.parent_id),
   children:id=>db.prepare('SELECT child_id FROM task_links WHERE parent_id=? ORDER BY child_id').all(id).map(link=>link.child_id),
 });
-/** Every card's rows read in one query per table: what a write that snapshots the whole board reads (one query per card
- *  and table was most of each write's transaction, 470 ms for this board's 1,553 cards, t_23e47b73). */
-function wholeBoard(db){
-  const grouped=(sql,pick)=>{const by=new Map();for(const row of db.prepare(sql).all()){const list=by.get(row.task_id);const value=pick(row);if(list)list.push(value);else by.set(row.task_id,[value]);}return id=>by.get(id)??[];};
-  const own=new Map(db.prepare('SELECT * FROM supercode_cards').all().map(row=>[row.task_id,row]));
-  return {
-    own:id=>own.get(id),
-    comments:grouped('SELECT task_id,id,author,body,created_at FROM task_comments ORDER BY id',({id,author,body,created_at})=>({id,author,body,created_at})),
-    reviews:grouped(`SELECT task_id,id,kind,payload,created_at FROM task_events WHERE kind IN ${REVIEW_KINDS} ORDER BY id`,({id,kind,payload,created_at})=>({id,kind,payload,created_at})),
-    attempts:grouped('SELECT task_id,id,profile,step_key,status,started_at,ended_at,outcome,summary,metadata,error FROM task_runs ORDER BY id',({task_id:_,...run})=>run),
-    parents:grouped('SELECT child_id AS task_id,parent_id FROM task_links ORDER BY parent_id',link=>link.parent_id),
-    children:grouped('SELECT parent_id AS task_id,child_id FROM task_links ORDER BY child_id',link=>link.child_id),
-  };
-}
-
 export function cardSnapshot(db,row,rows=perCard(db)) {
   const own=rows.own(row.id)??{};
   const comments=rows.comments(row.id).map(comment=>({...comment,created_at:at(comment.created_at)}));
@@ -76,31 +111,61 @@ export function cardSnapshot(db,row,rows=perCard(db)) {
     reviews,children:rows.children(row.id),comments,attempts};
 }
 
-/** Runs inside the backing's native transaction, including files and ztrack projections. */
+/**
+ * Publish the cards this transaction (or a native writer before it) marked changed, inside the backing's own
+ * transaction: each marked card's snapshot when it differs from its published head, a removal when the card is gone.
+ * The marks are cleared with it. Retention is the owner's (prunePublications), never a transaction's.
+ */
 export function recordCardPublications(db,actor) {
-  const rows=db.prepare('SELECT * FROM tasks ORDER BY id').all(),present=new Set(),board=wholeBoard(db);let changed=0;
-  const heads=new Map(db.prepare('SELECT resource_id,digest,last_event_id FROM supercode_publication_heads').all().map(head=>[head.resource_id,head]));
-  for(const row of rows){
-    present.add(row.id);const snapshot=JSON.stringify(cardSnapshot(db,row,board)),digest=hash(snapshot);
-    const previous=heads.get(row.id);
-    if(previous?.digest===digest)continue;
-    const last=db.prepare('SELECT id,kind FROM task_events WHERE task_id=? ORDER BY id DESC LIMIT 1').get(row.id);
-    const kind=`task.${previous?(last?.id!==previous.last_event_id?kinds[last?.kind]??'changed':'changed'):'created'}`;
-    const inserted=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at) VALUES (?,?,?,?,?,?)').run(`event_${randomUUID()}`,row.id,kind,snapshot,actor,Date.now());
-    db.prepare('INSERT INTO supercode_publication_heads(resource_id,digest,sequence,last_event_id) VALUES (?,?,?,?) ON CONFLICT(resource_id) DO UPDATE SET digest=excluded.digest,sequence=excluded.sequence,last_event_id=excluded.last_event_id').run(row.id,digest,Number(inserted.lastInsertRowid),last?.id??null);changed++;
-  }
-  for(const old of db.prepare('SELECT resource_id,digest FROM supercode_publication_heads').all()){
-    if(present.has(old.resource_id)||old.digest==='removed')continue;
-    const inserted=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at) VALUES (?,?,?,?,?,?)').run(`event_${randomUUID()}`,old.resource_id,'task.changed',JSON.stringify({id:old.resource_id,removed:true}),actor,Date.now());
-    db.prepare('UPDATE supercode_publication_heads SET digest=?,sequence=? WHERE resource_id=?').run('removed',Number(inserted.lastInsertRowid),old.resource_id);changed++;
-  }
+  const marked=db.prepare('SELECT DISTINCT task_id FROM supercode_publication_dirty').all().map(row=>row.task_id);
+  if(!marked.length)return 0;
   db.prepare('INSERT INTO supercode_publication_log(id,pruned_through) SELECT ?,0 WHERE NOT EXISTS (SELECT 1 FROM supercode_publication_log)').run(`log_${randomUUID()}`);
-  const history=Number(db.prepare('SELECT count(*) AS n FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads)').get().n);
-  if(history>2*RETAINED_CHANGES){
-    const cut=Number(db.prepare('SELECT sequence FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads) ORDER BY sequence DESC LIMIT 1 OFFSET ?').get(RETAINED_CHANGES).sequence);
-    const old='SELECT id FROM supercode_publications WHERE sequence<=? AND sequence NOT IN (SELECT sequence FROM supercode_publication_heads)';
-    db.prepare(`DELETE FROM supercode_publications WHERE id IN (${old})`).run(cut);
-    db.prepare('UPDATE supercode_publication_log SET pruned_through=MAX(pruned_through,?)').run(cut);
+  const rows=perCard(db),task=db.prepare('SELECT * FROM tasks WHERE id=?'),head=db.prepare('SELECT resource_id,digest,last_event_id FROM supercode_publication_heads WHERE resource_id=?');
+  const lastEvent=db.prepare('SELECT id,kind FROM task_events WHERE task_id=? ORDER BY id DESC LIMIT 1');
+  const insert=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at) VALUES (?,?,?,?,?,?)');
+  const upsert=db.prepare('INSERT INTO supercode_publication_heads(resource_id,digest,sequence,last_event_id) VALUES (?,?,?,?) ON CONFLICT(resource_id) DO UPDATE SET digest=excluded.digest,sequence=excluded.sequence,last_event_id=excluded.last_event_id');
+  let changed=0;
+  for(const id of marked){
+    const row=task.get(id),previous=head.get(id);
+    if(row){
+      const snapshot=JSON.stringify(cardSnapshot(db,row,rows)),digest=hash(snapshot);
+      if(previous?.digest===digest)continue;
+      const last=lastEvent.get(id);
+      const kind=`task.${previous&&previous.digest!=='removed'?(last?.id!==previous.last_event_id?kinds[last?.kind]??'changed':'changed'):'created'}`;
+      const inserted=insert.run(`event_${randomUUID()}`,id,kind,snapshot,actor,Date.now());
+      upsert.run(id,digest,Number(inserted.lastInsertRowid),last?.id??null);changed++;
+    }else if(previous&&previous.digest!=='removed'){
+      const inserted=insert.run(`event_${randomUUID()}`,id,'task.changed',JSON.stringify({id,removed:true}),actor,Date.now());
+      db.prepare('UPDATE supercode_publication_heads SET digest=?,sequence=? WHERE resource_id=?').run('removed',Number(inserted.lastInsertRowid),id);changed++;
+    }
   }
+  db.prepare('DELETE FROM supercode_publication_dirty').run();
   return changed;
 }
+
+/**
+ * Bounded retention, the publication owner's maintenance (never a write's): every card's head stays, and once more than
+ * twice RETAINED_CHANGES older changes accumulate, all but the newest RETAINED_CHANGES of them go in one batch, the
+ * floor recording where. A reader whose cursor is below the floor takes a new snapshot. Answers the changes removed.
+ */
+/** Whether retention has work: an upper bound on the older changes kept (sequences above the floor that are no card's
+ *  head), from the log's ends and the heads above the floor, in indexed reads. */
+export function pruneDue(db) {
+  const log=db.prepare('SELECT pruned_through FROM supercode_publication_log').get();
+  if(!log)return false;
+  const high=Number(db.prepare('SELECT MAX(sequence) AS n FROM supercode_publications').get()?.n??0);
+  // the heads above the floor are not older changes; those below it were already left out by subtracting the floor
+  const heads=Number(db.prepare('SELECT count(*) AS n FROM supercode_publication_heads WHERE sequence>?').get(Number(log.pruned_through)).n);
+  return high-Number(log.pruned_through)-heads>2*RETAINED_CHANGES;
+}
+
+export function prunePublications(db) {
+  if(!pruneDue(db))return 0;
+  const history=Number(db.prepare('SELECT count(*) AS n FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads)').get().n);
+  if(history<=2*RETAINED_CHANGES)return 0;
+  const cut=Number(db.prepare('SELECT sequence FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads) ORDER BY sequence DESC LIMIT 1 OFFSET ?').get(RETAINED_CHANGES).sequence);
+  const old='SELECT id FROM supercode_publications WHERE sequence<=? AND sequence NOT IN (SELECT sequence FROM supercode_publication_heads)';
+  const removed=db.prepare(`DELETE FROM supercode_publications WHERE id IN (${old})`).run(cut).changes;
+  db.prepare('UPDATE supercode_publication_log SET pruned_through=MAX(pruned_through,?)').run(cut);
+  return Number(removed);
+}

package/board/store.mjs

@@ -9,6 +9,8 @@
 // This module opens a board in its backing and gives its callers one primitive, a write transaction; the transitions
 // are in `engine.mjs`. Hermes's own tools may write a `kanban.db` at the same time: every write there takes SQLite's
 // native transaction boundary and retries an optimistic conflict.
+import { current } from './call.mjs';
+import { fenced } from './fence.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { redactValue } from '@volter/teams/redact';
 import { randomBytes } from 'node:crypto';
@@ -19,7 +21,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { openZtrackBoard } from './ztrack.mjs';
 import { isFilesBoard, openFilesBoard } from './files.mjs';
 import { signalBoardWrite } from './wake.mjs';
-import { PUBLICATION_SCHEMA, recordCardPublications } from './published.mjs';
+import { PUBLICATION_SCHEMA, pruneDue, prunePublications, publicationTriggers, recordCardPublications } from './published.mjs';
 
 export const DEFAULT_BOARD = 'default';
 
@@ -146,6 +148,8 @@ export function layOut(db, { fresh }) {
   for (const [column, type] of Object.entries(OURS_COLUMNS)) if (!have.has(column)) db.exec(`ALTER TABLE supercode_cards ADD COLUMN ${column} ${type}`);
   const effectColumns = new Set(db.prepare('PRAGMA table_info(supercode_effects)').all().map((c) => c.name));
   for (const [column, type] of Object.entries(EFFECT_COLUMNS)) if (!effectColumns.has(column)) db.exec(`ALTER TABLE supercode_effects ADD COLUMN ${column} ${type}`);
+  // what changed is marked by the store itself, whoever writes it (published.mjs)
+  publicationTriggers(db);
 }
 
 /**
@@ -192,6 +196,7 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
       const fresh = !db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'tasks'").get();
       if (fresh && !create) { db.exec('ROLLBACK'); db.close(); throw new Error(`${path} is not a board`); }
       layOut(db, { fresh });
+      fenced(db);
       db.exec('COMMIT');
       break;
     } catch (error) {
@@ -212,11 +217,32 @@ export const tx = (board, fn) => {
   const caller = /at (?:async )?([\w.$<>]+) /.exec(String(new Error().stack).split('\n')[2] ?? '')?.[1] ?? 'unknown';
   const started = performance.now();
   try {
-    const result = board.tx(db => {const result=fn(db);recordCardPublications(db,actor);return result;});
-    signalBoardWrite(board.root, actor);
+    const result = board.tx(db => {const result=fn(db);recordCardPublications(db,actorOf());return result;});
+    signalBoardWrite(board.root, actorOf());
     return result;
   } finally { noteStep(`board tx from ${caller}`, performance.now() - started); }
 };
+/**
+ * The board owner's publication work on a wake: each board's cards that a writer outside this process marked changed
+ * (Hermes's native writer, a hand-edited files board) are published in a transaction of their own, and the retained
+ * history is bounded (prunePublications). A board with no marks is one read. Answers the cards published.
+ */
+export function publishMarked(root) {
+  let published = 0;
+  for (const slug of listBoards(root)) {
+    let board;
+    try {
+      board = openBoard(root, slug);
+      // a mark in the store, or a backing edit not yet imported into its tables (a ztrack document): the transaction
+      // imports the edit, which marks its cards, and publishes them
+      const marked = board.db.prepare('SELECT 1 FROM supercode_publication_dirty LIMIT 1').get() || board.unimported?.();
+      if (marked) published += board.tx((db) => recordCardPublications(db, actorOf()));
+      if (pruneDue(board.db)) board.tx((db) => prunePublications(db));
+    } finally { board?.close(); }
+  }
+  return published;
+}
+
 // SQLite's own contention (BUSY, LOCKED, and their extended codes) and nothing else: a refusal whose words happen to
 // say "blocked" or "busy" reaches its caller at once instead of being retried forever.
 export const contention = (error) => [5, 6].includes(Number(error?.errcode) & 255)
@@ -246,6 +272,7 @@ function sqliteTx(db, fn) {
     try {
       db.exec('BEGIN');
       inTx.add(db);
+      fenced(db);
       const out=fn(db);
       db.exec('COMMIT');
       return out;
@@ -295,16 +322,15 @@ export function json(text, fallback = null) {
 /** Append one event to a card's thread (Hermes's `task_events`); answers its id. */
 // the session whose command this process runs (its address), set by the CLI: each event it records says who acted
 // (`by`), so the session is not told of its own act
-let actor = null;
-export const actorOf = () => actor;
-export function setActor(address) { actor = address || null; }
+// (each call's own: call.mjs)
+export const actorOf = () => current().actor;
+export function setActor(address) { current().actor = address || null; }
 // C4: the principal the caller acts as (`agent:<id>`, `automation:<name>`, `person:<id>`, `session:<address>`): what a
 // card's `created_by` records, and what a relaunched agent still matches when it acts on the cards it created.
-let principal = null;
-export const principalOf = () => principal;
-export function setPrincipal(ref) { principal = ref || null; }
+export const principalOf = () => current().principal;
+export function setPrincipal(ref) { current().principal = ref || null; }
 /** Whether a recorded creator is the caller: its principal, its session address, or that session as an actor. */
-export const isCaller = (ref) => Boolean(ref) && [principal, actor, actor ? `session:${actor}` : null].includes(ref);
+export const isCaller = (ref) => { const { principal, actor } = current(); return Boolean(ref) && [principal, actor, actor ? `session:${actor}` : null].includes(ref); };
 
 export function event(db, taskId, kind, payload = null, runId = null) {
   // Session observations belong to the run machine. Legacy runs without a machine state retain
@@ -313,11 +339,12 @@ export function event(db, taskId, kind, payload = null, runId = null) {
     const row = db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(runId);
     const meta = json(row?.metadata, {}) ?? {};
     if (meta.supercode?.state) {
-      appendRunObservation(meta, { kind, payload, by: actor, at: now() });
+      appendRunObservation(meta, { kind, payload, by: actorOf(), at: now() });
       db.prepare('UPDATE task_runs SET metadata = ? WHERE id = ?').run(JSON.stringify(meta), runId);
       return 0;
     }
   }
+  const actor = actorOf();
   const said = actor && !(payload && 'by' in payload) ? { ...(payload ?? {}), by: actor } : payload;
   // An event carries what the board observed (a command's stderr, a session's screen), which a verb's text check never
   // saw: a secret in it is stored as its marker (@volter/teams/redact), never as its value.

package/board/workflow.mjs

@@ -4,10 +4,12 @@
 // must hold and what happens; this module applies it to the board file and keeps no rule of its own. Its actions are
 // the engine's primitives (the rows Hermes's tables hold); the I/O an action asks for (stopping a worker, closing a
 // pane, sending a session a message, cleaning a workspace) is answered as effects the caller runs after commit.
+import { current } from './call.mjs';
+import { notRuntime } from './owner-files.mjs';
 import { spawnSync, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve, relative, isAbsolute } from 'node:path';
+import { existsSync, readdirSync, realpathSync, watch, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { actorOf, appendRunObservation, event as record, json, now } from './store.mjs';
 import { evaluate, holds, render } from './expr.mjs';
@@ -16,18 +18,111 @@ import { isWorkspacePath } from './workspace.mjs';
 import { identifyNotice } from './notices.mjs';
 
 const loaded = new Map();
+const homes = new Map(); // root → Promise<orchestration>: the home as the IR reads it, held until it changes
 
-/** Read the home's workflow through the IR (and the params its `kanban:` keys override); cached per home. */
-export async function loadWorkflow(root, { fresh = false } = {}) {
-  if (!fresh && loaded.has(root)) return loaded.get(root);
-  const { read } = await import('../orchestration.mjs');
-  const orchestration = await read(root);
-  const entry = workflowEntry(orchestration);
-  entry.root = root;
-  loaded.set(root, entry);
+/**
+ * The home as the IR reads it, read once and held: the board's owner holds it for its lifetime and reads it again only
+ * when a file it is decoded from changes (followHome). One read for every verb and round, not one each.
+ */
+export async function readHome(root) {
+  if (!homes.has(root)) {
+    const reading = import('../orchestration.mjs').then(({ read }) => read(root));
+    homes.set(root, reading);
+    reading.catch(() => { if (homes.get(root) === reading) homes.delete(root); });
+  }
+  return homes.get(root);
+}
+
+/**
+ * Read the home's workflow through the IR (and the params its `kanban:` keys override): the held home's. The call that
+ * reads it keeps it as its basis (call.mjs `workflows`), so a reload while it runs changes only the next call's.
+ */
+export async function loadWorkflow(root) {
+  // a call keeps the workflow it first read (its basis), whatever a later load in it would read
+  const pinned = current().workflows.get(root);
+  if (pinned) return pinned;
+  const orchestration = await readHome(root);
+  let entry = loaded.get(root);
+  if (entry?.orchestration !== orchestration) {
+    entry = workflowEntry(orchestration);
+    entry.root = root;
+    entry.orchestration = orchestration;
+    loaded.set(root, entry);
+  }
+  current().workflows.set(root, entry);
   return entry;
 }
 
+// What the board's view of a home is decoded from: the workflow, each profile's config, credentials and the agent
+// layer, and which profiles there are. A session store or a run log changing is no change to it.
+const DECODED = /^(?:(?:profiles\/[^/]+\/)?(?:config\.yaml|\.env|agents\.json)|workflow\.yaml|profiles(?:\/[^/]+)?)$/;
+
+/**
+ * Follow the home's own files, so the held view is read again on its next use after one it is decoded from changes:
+ * file events from the home, never an interval. Installed before the home is first read (the view held is never older
+ * than the watch). An event that names no file is taken as a change. A watch that fails is installed again with the
+ * view dropped; if it cannot be, `onLost` says so and the view is no longer trusted. Throws when it cannot start.
+ * Answers a stop.
+ */
+export function followHome(root, { onChange = () => {}, onLost = () => {} } = {}) {
+  let watcher = null;
+  let stopped = false;
+  // A decoded file that is a link (a workflow kept in another checkout) is watched at its real target too, in the
+  // target's own folder: an edit there replaces the target, which the home's own tree never reports. The links are read
+  // again after every change, so a relinked file is followed to its new target.
+  const linked = new Map(); // target folder → watcher
+  const followLinks = () => {
+    const targets = new Map();
+    const decoded = ['workflow.yaml', 'config.yaml', '.env', 'agents.json'];
+    const watchIn = (folder, name) => { if (!targets.has(folder)) targets.set(folder, new Set()); targets.get(folder).add(name); };
+    let realRoot = root;
+    try { realRoot = realpathSync(root); } catch { /* the home's own watch reports it */ }
+    let profiles = [];
+    try { profiles = readdirSync(join(root, 'profiles')).filter((name) => !name.startsWith('.')).map((name) => join('profiles', name)); } catch { /* no profiles */ }
+    // Each decoded file and the folder it sits in, by their real paths: a file that is a link, or one in a folder that
+    // is (a linked profile, a linked parent), is watched where it really is, which the home's own tree does not cover.
+    for (const base of ['', ...profiles]) {
+      let realDir;
+      try { realDir = realpathSync(join(root, base)); } catch { continue; }
+      if (realDir !== join(realRoot, base)) for (const file of decoded) watchIn(realDir, file);
+      for (const file of decoded) {
+        let real;
+        try { real = realpathSync(join(root, base, file)); } catch { continue; }
+        if (real !== join(realRoot, base, file)) watchIn(dirname(real), basename(real));
+      }
+    }
+    // A linked profiles/ registry is watched at its real folder for any entry: a profile added or removed there is a
+    // change to which profiles there are, which the home's own tree never reports.
+    try { const registry = realpathSync(join(root, 'profiles')); if (registry !== join(realRoot, 'profiles')) watchIn(registry, '*'); } catch { /* no profiles */ }
+    for (const [folder, handle] of linked) if (!targets.has(folder)) { handle.close(); linked.delete(folder); }
+    for (const [folder, names] of targets) {
+      linked.get(folder)?.close();
+      try {
+        const handle = watch(folder, (_kind, name) => { if (!name || names.has('*') || names.has(String(name))) changed(`${folder}/${name ?? '(unnamed)'}`); });
+        handle.on('error', () => { handle.close(); linked.delete(folder); changed(`(the watch on ${folder} failed)`); });
+        linked.set(folder, handle);
+      } catch (error) { onLost(error); }
+    }
+  };
+  const changed = (name) => { homes.delete(root); onChange(name); if (!stopped) followLinks(); };
+  const install = () => {
+    watcher = watch(root, { recursive: true }, (_kind, name) => {
+      if (name && !DECODED.test(String(name).split(sep).join('/'))) return;
+      changed(name ? String(name) : '(a change the event did not name)');
+    });
+    watcher.on('error', (error) => {
+      try { watcher.close(); } catch { /* already unusable */ }
+      if (stopped) return;
+      changed(`(the watch failed: ${error.message})`);
+      try { install(); } catch (again) { homes.delete(root); onLost(again); }
+    });
+  };
+  homes.delete(root);
+  install();
+  followLinks();
+  return () => { stopped = true; try { watcher?.close(); } catch { /* closed */ } for (const handle of linked.values()) handle.close(); };
+}
+
 /** The workflow entry for an orchestration value already read. */
 export function workflowEntry(orchestration) {
   const workflow = orchestration?.workflow;
@@ -36,9 +131,9 @@ export function workflowEntry(orchestration) {
   return { workflow, params: { ...workflow.params, ...kanban }, profiles: orchestration.profiles ?? {} };
 }
 
-/** The workflow loaded for `root` (loadWorkflow first). */
+/** The workflow loaded for `root` (loadWorkflow first): the running call's basis, else the latest read. */
 export function workflowFor(root) {
-  const entry = loaded.get(root);
+  const entry = current().workflows.get(root) ?? loaded.get(root);
   if (!entry) throw new Error(`the board workflow of ${root} is not loaded`);
   return entry;
 }
@@ -47,6 +142,7 @@ export function workflowFor(root) {
 export function useWorkflow(root, entry) {
   entry.root = root;
   loaded.set(root, entry);
+  current().workflows.set(root, entry);
   return entry;
 }
 
@@ -1037,7 +1133,7 @@ export function runSpec(entry, status, card = null) {
   const rel = relative(entry.root, file);
   if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('prompt file must live in the orchestration home');
   if (!existsSync(file) && spec.prompt) return spec; // embedded prompts of the built-in instance
-  return { ...spec, prompt: readFileSync(file, 'utf8') };
+  return { ...spec, prompt: readFileSync(notRuntime(file), 'utf8') };
 }
 
 export function runEvent(db, id, kind, payload) {