@volter/supercode-orchestrator 0.4.37 → 0.4.39

package/board/cli.mjs

@@ -10,9 +10,9 @@ import { basename, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { read } from '../orchestration.mjs';
 import { holdDispatcherLock } from '../hermes-locks.mjs';
-import { boardPath, DEFAULT_BOARD, event, json, listBoards, now, openBoard, tx } from './store.mjs';
+import { backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, tx } from './store.mjs';
 import * as engine from './engine.mjs';
-import { adoptSession, boardLabel, boardSettings, lanesOf, localMachine, observeFleet, paused, startCard, tick } from './dispatch.mjs';
+import { adoptSession, boardLabel, boardSettings, lanesOf, localMachine, observeFleet, paused, plan, startCard, tick } from './dispatch.mjs';
 import { loadWorkflow, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
 import { evaluate } from './expr.mjs';
 
@@ -39,6 +39,8 @@ Hermes Kanban's verbs, with their flags:
   pause [reason] · resume   (Hermes's emergency stop, the ESTOP file: new starts stop, running sessions go on)
 
 supercode's own:
+  init --backing sqlite|files · boards create <slug> --backing sqlite|files
+      Where the board is kept: sqlite is Hermes's kanban.db (the default); files is one JSON file per card.
   create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
       waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
@@ -101,7 +103,7 @@ function boardOf(root, args) {
   for (const want of [args.board, process.env.HERMES_KANBAN_BOARD, existsSync(currentFile(root)) ? readFileSync(currentFile(root), 'utf8').trim() : null]) {
     if (!want) continue;
     const slug = normalSlug(want);
-    if (slug === DEFAULT_BOARD || existsSync(boardPath(root, slug))) return slug;
+    if (slug === DEFAULT_BOARD || boardExists(root, slug)) return slug;
     if (want === args.board) return slug;
   }
   return DEFAULT_BOARD;
@@ -113,16 +115,16 @@ const metaPath = (root, slug) => join(boardDir(root, slug), 'board.json');
 function boardMeta(root, slug) {
   const meta = { slug, name: slug === DEFAULT_BOARD ? 'Default' : slug, description: '', icon: '', color: '', default_workdir: null, project_id: null, created_at: null, archived: false };
   try { Object.assign(meta, JSON.parse(readFileSync(metaPath(root, slug), 'utf8')), { slug }); } catch { /* no metadata yet */ }
-  return { ...meta, db_path: boardPath(root, slug) };
+  return { ...meta, db_path: boardPath(root, slug), backing: backingOf(root, slug) };
 }
 
 function writeMeta(root, slug, patch) {
-  const { db_path: _, ...meta } = boardMeta(root, slug);
+  const { db_path: _, backing: __, ...meta } = boardMeta(root, slug);
   for (const [k, v] of Object.entries(patch)) if (v !== undefined) meta[k] = v;
   meta.created_at ??= now();
   mkdirSync(boardDir(root, slug), { recursive: true });
   writeFileSync(metaPath(root, slug), `${JSON.stringify(meta, null, 2)}\n`);
-  return { ...meta, db_path: boardPath(root, slug) };
+  return { ...meta, db_path: boardPath(root, slug), backing: backingOf(root, slug) };
 }
 
 /** Hermes's list: the default board and every named one with a database or metadata. */
@@ -132,7 +134,7 @@ function boardsOf(root, { includeArchived = true } = {}) {
   if (existsSync(dir)) {
     for (const slug of readdirSync(dir).sort()) {
       if (slug === DEFAULT_BOARD || !SLUG.test(slug)) continue;
-      if (!existsSync(boardPath(root, slug)) && !existsSync(metaPath(root, slug))) continue;
+      if (!boardExists(root, slug) && !existsSync(metaPath(root, slug))) continue;
       const meta = boardMeta(root, slug);
       if (meta.archived && !includeArchived) continue;
       out.push(meta);
@@ -142,7 +144,7 @@ function boardsOf(root, { includeArchived = true } = {}) {
 }
 
 function counts(root, slug) {
-  if (!existsSync(boardPath(root, slug))) return {};
+  if (!boardExists(root, slug)) return {};
   const b = openBoard(root, slug);
   try {
     return Object.fromEntries(b.db.prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status').all().map((r) => [r.status, Number(r.n)]));
@@ -223,7 +225,7 @@ export async function runWorkflow(argv) {
   if (!verb || verb === 'help' || args.help) { process.stdout.write(HELP); return 0; }
   const root = homeOf(args);
   const slug = boardOf(root, args);
-  const open = (create = false) => { const b = openBoard(root, slug, { create }); b.label = boardLabel(root, slug); return b; };
+  const open = (create = false) => { const b = openBoard(root, slug, { create, backing: create ? args.backing ?? null : null }); b.label = boardLabel(root, slug); return b; };
   const withBoard = (fn, create = false) => { const b = open(create); try { return fn(b); } finally { b.close(); } };
   const withBoardAsync = async (fn) => { const b = open(); try { return await fn(b); } finally { b.close(); } };
   const id = rest[0];
@@ -232,7 +234,7 @@ export async function runWorkflow(argv) {
 
   // a caller that is a card's own session (its harness names it; the board recorded which session it launched)
   const sid = process.env.CLAUDE_CODE_SESSION_ID || process.env.CODEX_THREAD_ID;
-  if (sid && !READS.has(verb) && existsSync(boardPath(root, slug))) {
+  if (sid && !READS.has(verb) && boardExists(root, slug)) {
     withBoard((b) => { const own = ownCard(b.db, sid); if (own) authorize(b.db, verb, rest, args, own); });
   }
   // the board's workflow (the IR's): what each verb does, and who may send it, is its
@@ -242,9 +244,9 @@ export async function runWorkflow(argv) {
 
   switch (verb) {
     case 'init': {
-      withBoard(() => {}, true);
+      const backing = withBoard((b) => b.backing, true);
       const { profiles } = await laneState(root).catch(() => ({ profiles: [] }));
-      say(args, `Kanban DB initialized at ${boardPath(root, slug)}\n\n${profiles.length ? `Profiles of this home (any can be an --assignee): ${profiles.join(', ')}` : 'No profiles in this home.'}\nThe dispatcher: \`supercode workflow serve\`, or the orchestrator while it serves the home.`, { ok: true, board: slug, path: boardPath(root, slug), profiles });
+      say(args, `${backing === 'sqlite' ? 'Kanban DB' : `Board (${backing} backing)`} initialized at ${boardPath(root, slug)}\n\n${profiles.length ? `Profiles of this home (any can be an --assignee): ${profiles.join(', ')}` : 'No profiles in this home.'}\nThe dispatcher: \`supercode workflow serve\`, or the orchestrator while it serves the home.`, { ok: true, board: slug, path: boardPath(root, slug), backing, profiles });
       return 0;
     }
 
@@ -615,7 +617,7 @@ export async function runWorkflow(argv) {
     }
     case 'log': {
       need(1, 'a card id');
-      const file = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'logs') : join(boardDir(root, slug), 'logs'), `${id}.log`);
+      const file = join(logsDir(root, slug), `${id}.log`);
       if (!existsSync(file)) {
         // a pane session keeps no log file: its transcript is the harness's own, named by the run
         const s = withBoard((b) => tx(b, (db) => engine.lastSession(db, id)));
@@ -681,8 +683,9 @@ export async function runWorkflow(argv) {
       const { lanes, settings } = await laneState(root);
       const params = { ...(args['failure-limit'] ? { failure_limit: Number(args['failure-limit']) } : {}), ...(args.max ? { max_spawn: Number(args.max) } : {}) };
       if (args['dry-run']) {
-        const would = withBoard((b) => engine.listCards(b.db, { status: 'ready' }).filter((t) => t.assignee && lanes[t.assignee] && !t.subtask_of).map((t) => ({ id: t.id, assignee: t.assignee, machine: t.machine, surface: lanes[t.assignee].surface })));
-        say(args, would.length ? would.map((w) => `would start ${w.id} as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`).join('\n') : 'nothing would start', would);
+        // planned through the workflow's own dispatch (its start event, eligible, order and limits), writing nothing
+        const would = (await plan({ root, lanes, settings, params, slugs: [slug] })).flatMap((r) => r.would);
+        say(args, would.length ? would.map((w) => `would start ${w.id} (${w.status}${w.role ? `, its ${w.role}` : ''}) as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`).join('\n') : 'nothing would start', would);
         return 0;
       }
       const reports = await tick({ root, lanes, settings, params });
@@ -713,7 +716,7 @@ export async function runWorkflow(argv) {
       }
       const events = withBoard((b) => engine.gcEvents(b, eventDays * 86400));
       let logs = 0;
-      const logDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'logs') : join(boardDir(root, slug), 'logs');
+      const logDir = logsDir(root, slug);
       if (existsSync(logDir)) for (const f of readdirSync(logDir)) { const p = join(logDir, f); if (statSync(p).isFile() && statSync(p).mtimeMs < Date.now() - logDays * 86400_000) { unlinkSync(p); logs += 1; } }
       say(args, `GC complete: ${removedWs} workspace(s), ${events} event row(s), ${logs} log file(s) removed`, { workspaces: removedWs, events, logs });
       return 0;
@@ -800,7 +803,7 @@ async function boardsVerb(root, rest, args) {
     case 'create': case 'new': {
       const slug = normalSlug(target);
       const meta = writeMeta(root, slug, { name: args.name, description: args.description, icon: args.icon, color: args.color, default_workdir: args['default-workdir'] });
-      openBoard(root, slug, { create: true }).close();
+      openBoard(root, slug, { create: true, backing: args.backing ?? null }).close();
       if (args.switch) { mkdirSync(join(root, 'kanban'), { recursive: true }); writeFileSync(currentFile(root), `${slug}\n`); }
       say(args, `Board '${slug}' ready.\n  Display name: ${meta.name}\n  DB path:      ${meta.db_path}${args.switch ? `\n  Switched to '${slug}'.` : ''}`, meta);
       return 0;
@@ -821,7 +824,7 @@ async function boardsVerb(root, rest, args) {
     }
     case 'switch': case 'use': {
       const slug = normalSlug(target);
-      if (slug !== DEFAULT_BOARD && !existsSync(boardPath(root, slug))) throw new Error(`board '${slug}' does not exist; \`supercode workflow boards create ${slug}\``);
+      if (slug !== DEFAULT_BOARD && !boardExists(root, slug)) throw new Error(`board '${slug}' does not exist; \`supercode workflow boards create ${slug}\``);
       mkdirSync(join(root, 'kanban'), { recursive: true });
       writeFileSync(currentFile(root), `${slug}\n`);
       say(args, `Active board is now '${slug}'.`, { ok: true, board: slug });
@@ -846,7 +849,7 @@ async function boardsVerb(root, rest, args) {
     }
     case 'export': {
       const slug = normalSlug(target ?? boardOf(root, args));
-      if (!existsSync(boardPath(root, slug))) throw new Error(`board '${slug}' has no database`);
+      if (!boardExists(root, slug)) throw new Error(`board '${slug}' has no database`);
       const out = resolve(args.output ?? `${slug}.tar.gz`);
       const made = exportBoard(root, slug, out, { attachments: !args['no-attachments'], logs: Boolean(args['include-logs']) });
       say(args, `Exported board '${slug}' → ${out}\n  Tasks:       ${made.counts.tasks}\n  Comments:    ${made.counts.task_comments}\n  Attachments: ${made.counts.attachment_files}`, made);
@@ -909,12 +912,12 @@ function exportBoard(root, slug, out, { attachments, logs }) {
     const snap = openBoard(base, DEFAULT_BOARD);
     let counts;
     try { tx(snap, (db) => scrub(db)); counts = rowCounts(snap.db); } finally { snap.close(); }
-    const { db_path: _, default_workdir: __, project_id: ___, ...meta } = boardMeta(root, slug);
+    const { db_path: _, backing: ____, default_workdir: __, project_id: ___, ...meta } = boardMeta(root, slug);
     writeFileSync(join(base, 'board.json'), `${JSON.stringify(meta, null, 2)}\n`);
     const attachmentsDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(boardDir(root, slug), 'attachments');
-    const logsDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'logs') : join(boardDir(root, slug), 'logs');
+    const logsFrom = logsDir(root, slug);
     const files = attachments ? copyTree(attachmentsDir, join(base, 'attachments')) : 0;
-    const logFiles = logs ? copyTree(logsDir, join(base, 'logs')) : 0;
+    const logFiles = logs ? copyTree(logsFrom, join(base, 'logs')) : 0;
     const manifest = { format: ARCHIVE_FORMAT, format_version: 1, board: slug, board_name: meta.name || slug, exported_at: now(), exported_by: 'supercode',
       includes: { attachments, logs }, counts: { ...counts, attachment_files: files, log_files: logFiles } };
     writeFileSync(join(base, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);

package/board/dispatch.mjs

@@ -20,7 +20,7 @@ import { hostname, tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { boardPath, claimer, event, json, listBoards, now, openBoard, tx } from './store.mjs';
+import { boardPath, claimer, event, json, listBoards, logsDir, now, openBoard, tx } from './store.mjs';
 import { holdBoardTickLock } from '../hermes-locks.mjs';
 import { doors, fire, loadWorkflow, resumeOf, scopeOf, statusOf, templateValue, workflowFor } from './workflow.mjs';
 import { evaluate, holds, render } from './expr.mjs';
@@ -266,7 +266,7 @@ const hostOf = (pressure) => ({ memory_pressure: pressure, max_in_progress: deri
  * the cards a reserve names while any waits). Each is sent the start event (its validators are Hermes's respawn
  * guard) and what its new status runs is launched.
  */
-function startCards(board, fleet, lanes, settings, report, entry, effects, { only = null, hostRunning = 0 } = {}) {
+function startCards(board, fleet, lanes, settings, report, entry, effects, { only = null, hostRunning = 0, dry = false } = {}) {
   const stop = paused(board.root);
   if (stop) { report.paused = stop; return; }
   const { workflow, params } = entry;
@@ -321,10 +321,12 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
     if (evaluate(l.group, { card: {} }) === 'home') l.tally.set(JSON.stringify('home'), (l.tally.get(JSON.stringify('home')) ?? 0) + Math.max(0, hostRunning - here));
   }
   const reserveWaits = (l) => l.reserve && candidates.some((c) => holds(l.reserve.for, c.scope));
+  // a dry run (dispatch --dry-run) plans the same way and writes nothing: no notes, no moves, no launches
+  const note = (id, why) => { if (!dry) tx(board, (db) => noteGuard(db, id, why)); };
   for (const c of candidates) {
     const { task, plan, scope } = c;
-    if (!plan.profile) { report.unassigned.push(task.id); tx(board, (db) => noteGuard(db, task.id, 'no profile runs it (no assignee, and the workflow names none)')); continue; }
-    if (!plan.lane) { report.nonspawnable.push(task.id); tx(board, (db) => noteGuard(db, task.id, `${plan.profile} is no lane of this home`)); continue; }
+    if (!plan.profile) { report.unassigned.push(task.id); note(task.id, 'no profile runs it (no assignee, and the workflow names none)'); continue; }
+    if (!plan.lane) { report.nonspawnable.push(task.id); note(task.id, `${plan.profile} is no lane of this home`); continue; }
     let why = null;
     for (const l of limits) {
       const max = evaluate(l.max, scope);
@@ -335,7 +337,12 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
     }
     // the launcher's own conditions: a lane that can start this card where it names
     if (!why) why = launcherCheck(board.db, task, plan.lane, fleet);
-    if (why) { tx(board, (db) => noteGuard(db, task.id, why)); report.queued.push([task.id, why]); continue; }
+    if (why) { note(task.id, why); report.queued.push([task.id, why]); continue; }
+    if (dry) {
+      report.would.push({ id: task.id, status: plan.target, role: plan.runSpec?.role ?? null, assignee: plan.profile, machine: task.machine ?? null, surface: plan.lane.surface });
+      for (const l of limits) if (holds(l.counts, scope)) { const g = JSON.stringify(evaluate(l.group, scope)); l.tally.set(g, (l.tally.get(g) ?? 0) + 1); }
+      continue;
+    }
     let moved;
     try {
       moved = tx(board, (db) => {
@@ -616,7 +623,7 @@ function launchHeadless(board, task, runId, lane, settings, { prompt = null, ski
   const args = ['-p', lane.name, '--cli', '--accept-hooks', ...skills.flatMap((s) => ['--skills', s]),
     ...(task.model_override ? ['-m', task.model_override, ...(task.provider_override ? ['--provider', task.provider_override] : [])] : []),
     ...(task.reasoning_effort ? ['--reasoning', task.reasoning_effort] : []), 'chat', '-q', `work kanban task ${task.id}`];
-  const logDir = join(dirname(board.path), board.slug === 'default' ? 'kanban' : '', 'logs');
+  const logDir = logsDir(board.root, board.slug);
   mkdirSync(logDir, { recursive: true });
   const logFile = join(logDir, `${task.id}.log`);
   rotateLog(logFile, settings.logRotateBytes, settings.logBackups);
@@ -1029,14 +1036,25 @@ async function pool(items, n, fn) {
   }));
 }
 
-/**
- * One tick over every board of the home at `root`. `lanes` from `lanesOf`, `settings` from `boardSettings`.
- * `only` limits starting to one card (a create that answers whether its card started). Answers one report per board.
- */
 /** A board file's fingerprint: a corrupt board is skipped until the file changes (Hermes retries it then). */
 const fingerprint = (path) => { try { const st = statSync(path); return `${st.size}:${st.mtimeMs}`; } catch { return 'missing'; } };
 const CORRUPT = /malformed|not a database|corrupt|disk image/i;
 
+/** What a tick would start on each board of the home, planned through the workflow's `dispatch`, writing nothing. */
+export async function plan({ root, lanes, settings, slugs = null, params = {} }) {
+  const loaded = await loadWorkflow(root, { fresh: true });
+  const entry = { ...loaded, params: { ...loaded.params, ...params } };
+  const fleet = Object.values(lanes).some((l) => l.surface === 'pane') ? observeFleet() : { ok: false, alive: new Set(), online: new Set(), sessions: [], error: 'no pane lanes' };
+  const out = [];
+  for (const slug of slugs ?? listBoards(root)) {
+    const report = { board: slug, would: [], queued: [], unassigned: [], nonspawnable: [] };
+    const board = openBoard(root, slug);
+    try { board.label = boardLabel(root, slug); startCards(board, fleet, lanes, settings, report, entry, [], { dry: true }); } finally { board.close(); }
+    out.push(report);
+  }
+  return out;
+}
+
 /**
  * One tick over every board of the home at `root`. `lanes` from `lanesOf`, `settings` from `boardSettings`.
  * `only` limits starting to one card (a create that answers whether its card started). Each board is ticked under its

package/board/files.mjs

@@ -0,0 +1,261 @@
+// The `files` backing of a board (docs/architecture/orchestrator.md §2.9, "Backings"): the same tables as a
+// Hermes `kanban.db`, kept as a directory of JSON files instead of one SQLite file. `<id>.json` holds everything of
+// one card (its `tasks` row, its `supercode_cards` row, the links to its parents, its comments, events, runs,
+// attachments and subscriptions); `_board.json` holds the schema, the tables that belong to no card and the id
+// counters. A card's history is a file a person or a diff reads, and nothing but supercode's code touches it.
+//
+// The engine speaks SQL to every backing, so this one answers it from an in-memory SQLite database loaded from the
+// directory: a write transaction takes the directory's lock (`_board.lock`), reloads what another process wrote,
+// runs, and writes back the files of 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 { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+const STATE = '_board.json';
+const LOCK = '_board.lock';
+const LOCK_WAIT_MS = 10_000; // as the sqlite backing's busy_timeout
+
+/** Whether `dir` holds a files board. */
+export const isFilesBoard = (dir) => existsSync(join(dir, STATE));
+
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+const quote = (name) => `"${String(name).replaceAll('"', '""')}"`;
+
+function writeAtomic(file, text) {
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, file);
+}
+
+/**
+ * Open the files board in `dir`. `init(db, { fresh })` lays the board's schema over a loaded database (the store's:
+ * Hermes's tables on a fresh one, supercode's own table and columns on every one). Answers `{ db, tx, close }`.
+ */
+export function openFilesBoard(dir, { create = false, init }) {
+  if (!isFilesBoard(dir)) {
+    if (!create) throw new Error(`${dir} is not a board`);
+    mkdirSync(dir, { recursive: true });
+  }
+  const board = new FilesBoard(dir, init);
+  if (!isFilesBoard(dir)) board.tx(() => {}, { force: true });
+  return { db: board.db, tx: (fn) => board.tx(fn), close: () => board.close() };
+}
+
+class FilesBoard {
+  constructor(dir, init) {
+    this.dir = dir;
+    this.init = init;
+    this.mem = null;
+    this.stamp = null;
+    this.inTx = false;
+    this.statements = new Map();
+    const self = this;
+    // the connection the engine holds: SQLite's statement API over whatever snapshot is current
+    this.db = {
+      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.write(sql, () => self.statement(sql).run(...args)),
+        };
+      },
+      exec: (sql) => self.write(sql, () => self.mem.exec(sql)),
+      close: () => self.close(),
+    };
+    this.locked(() => this.load());
+  }
+
+  // ---------------------------------------------------------------- snapshot
+
+  stampOf() {
+    try { const s = statSync(join(this.dir, STATE)); return `${s.ino}:${s.mtimeMs}:${s.size}`; } catch { return 'none'; }
+  }
+
+  /** (Re)load the directory into a fresh in-memory database; the caller holds the lock. */
+  load() {
+    const stamp = this.stampOf();
+    if (this.mem && stamp === this.stamp) return;
+    this.mem?.close();
+    this.statements.clear();
+    const mem = new DatabaseSync(':memory:');
+    this.stateText = stamp === 'none' ? null : readFileSync(join(this.dir, STATE), 'utf8');
+    const state = this.stateText === null ? null : JSON.parse(this.stateText);
+    for (const sql of state?.schema ?? []) mem.exec(sql);
+    this.init(mem, { fresh: !state?.schema?.length });
+    const columns = (table) => new Set(mem.prepare(`PRAGMA table_info(${quote(table)})`).all().map((c) => c.name));
+    const insert = (table, rows) => {
+      const have = columns(table);
+      for (const row of rows) {
+        const keys = Object.keys(row).filter((k) => have.has(k));
+        mem.prepare(`INSERT INTO ${quote(table)} (${keys.map(quote).join(', ')}) VALUES (${keys.map(() => '?').join(', ')})`).run(...keys.map((k) => row[k]));
+      }
+    };
+    this.texts = new Map();
+    for (const name of readdirSync(this.dir)) {
+      if (!name.endsWith('.json') || name.startsWith('_')) continue;
+      const text = readFileSync(join(this.dir, name), 'utf8');
+      const card = JSON.parse(text);
+      this.texts.set(card.id, text);
+      for (const [table, rows] of Object.entries(card.tables ?? {})) insert(table, rows);
+    }
+    for (const [table, rows] of Object.entries(state?.tables ?? {})) insert(table, rows);
+    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);
+    }
+    this.mem = mem;
+    this.watch();
+    this.stamp = stamp;
+  }
+
+  /** Each table that belongs to a card, with the column naming the card. */
+  cardTables() {
+    const out = new Map();
+    for (const { name } of this.mem.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
+      const cols = new Set(this.mem.prepare(`PRAGMA table_info(${quote(name)})`).all().map((c) => c.name));
+      if (name === 'tasks') out.set(name, 'id');
+      else if (name === 'task_links') out.set(name, 'child_id');
+      else if (cols.has('task_id')) out.set(name, 'task_id');
+    }
+    return out;
+  }
+
+  /**
+   * Temporary triggers that note every card a write touches, so a commit writes only those cards' files. The table has
+   * no key: a statement's own conflict clause (an upsert, `OR REPLACE`) governs its triggers' inserts too.
+   */
+  watch() {
+    this.mem.exec('CREATE TEMP TABLE IF NOT EXISTS _touched (id TEXT)');
+    this.keys = this.cardTables();
+    for (const [table, key] of this.keys) {
+      const t = quote(table);
+      this.mem.exec(`CREATE TEMP TRIGGER IF NOT EXISTS ${quote(`_i_${table}`)} AFTER INSERT ON main.${t} BEGIN INSERT INTO _touched VALUES (NEW.${quote(key)}); END;
+        CREATE TEMP TRIGGER IF NOT EXISTS ${quote(`_u_${table}`)} AFTER UPDATE ON main.${t} BEGIN INSERT INTO _touched VALUES (OLD.${quote(key)}); INSERT INTO _touched VALUES (NEW.${quote(key)}); END;
+        CREATE TEMP TRIGGER IF NOT EXISTS ${quote(`_d_${table}`)} AFTER DELETE ON main.${t} BEGIN INSERT INTO _touched VALUES (OLD.${quote(key)}); END;`);
+    }
+    this.mem.exec('DELETE FROM _touched');
+  }
+
+  schema() {
+    return this.mem.prepare("SELECT sql FROM sqlite_master WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY CASE type WHEN 'table' THEN 0 ELSE 1 END, rowid").all().map((r) => r.sql);
+  }
+
+  /** Write the files of the cards the transaction touched, then `_board.json`; the caller holds the lock. */
+  persist(schemaBefore) {
+    const schema = this.schema();
+    const reshaped = schema.join('\n') !== schemaBefore.join('\n');
+    const touched = new Set(this.mem.prepare('SELECT DISTINCT id FROM _touched').all().map((r) => r.id).filter((id) => id !== null));
+    if (reshaped) this.watch(); // a table made in the transaction gets its triggers; every card is written again
+    const keys = this.keys;
+    if (reshaped) for (const [table, key] of keys) for (const r of this.mem.prepare(`SELECT DISTINCT ${quote(key)} AS id FROM ${quote(table)}`).all()) touched.add(r.id);
+    const boardTables = {};
+    for (const { name } of this.mem.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
+      if (!keys.has(name)) boardTables[name] = this.mem.prepare(`SELECT * FROM ${quote(name)} ORDER BY rowid`).all();
+    }
+    const state = { format: 'supercode-board-files', format_version: 1, schema, tables: boardTables, sequence: this.mem.prepare('SELECT name, seq FROM sqlite_sequence ORDER BY name').all() };
+    const stateText = `${JSON.stringify(state, null, 2)}\n`;
+    let wrote = false;
+    for (const id of touched) {
+      const tables = {};
+      for (const [table, key] of keys) {
+        const rows = this.mem.prepare(`SELECT * FROM ${quote(table)} WHERE ${quote(key)} = ? ORDER BY rowid`).all(id);
+        if (rows.length) tables[table] = rows;
+      }
+      const file = join(this.dir, `${String(id).replace(/[^A-Za-z0-9_.-]/g, '_')}.json`);
+      if (!Object.keys(tables).length) {
+        if (this.texts.has(id)) { try { unlinkSync(file); } catch { /* already gone */ } this.texts.delete(id); wrote = true; }
+        continue;
+      }
+      const text = `${JSON.stringify({ id, tables }, null, 2)}\n`;
+      if (this.texts.get(id) === text) continue;
+      writeAtomic(file, text);
+      this.texts.set(id, text);
+      wrote = true;
+    }
+    if (wrote || stateText !== this.stateText) {
+      writeAtomic(join(this.dir, STATE), stateText);
+      this.stateText = stateText;
+    }
+    this.mem.exec('DELETE FROM _touched');
+    this.stamp = this.stampOf();
+  }
+
+  // ---------------------------------------------------------------- lock and transactions
+
+  locked(fn) {
+    const file = join(this.dir, LOCK);
+    const holder = `${hostname()}:${process.pid}`;
+    const until = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+      try {
+        const fd = openSync(file, 'wx');
+        writeSync(fd, holder);
+        closeSync(fd);
+        break;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        let held = '';
+        try { held = readFileSync(file, 'utf8'); } catch { continue; }
+        const [host, pid] = held.split(':');
+        // a holder on this host that is gone left its lock behind
+        if (host === hostname() && Number(pid) && !alive(Number(pid))) { try { unlinkSync(file); } catch { /* taken by another */ } continue; }
+        if (Date.now() > until) throw new Error(`the board ${this.dir} is locked by ${held || 'another writer'}`);
+        sleep(20);
+      }
+    }
+    try { return fn(); } finally { try { unlinkSync(file); } catch { /* gone */ } }
+  }
+
+  statement(sql) {
+    let s = this.statements.get(sql);
+    if (!s) { s = this.mem.prepare(sql); this.statements.set(sql, s); }
+    return s;
+  }
+
+  read(fn) {
+    if (!this.inTx && this.stampOf() !== this.stamp) this.locked(() => this.load());
+    return fn();
+  }
+
+  /** A write outside a transaction commits on its own, as SQLite's autocommit does; VACUUM and PRAGMA only read here. */
+  write(sql, fn) {
+    if (this.inTx || /^\s*(VACUUM|PRAGMA)\b/i.test(sql)) return this.read(fn);
+    return this.tx(fn);
+  }
+
+  tx(fn, { force = false } = {}) {
+    if (this.inTx) return fn(this.db);
+    return this.locked(() => {
+      this.load();
+      const before = this.schema();
+      this.mem.exec('BEGIN');
+      this.inTx = true;
+      let out;
+      try {
+        out = fn(this.db);
+        this.mem.exec('COMMIT');
+      } catch (error) {
+        try { this.mem.exec('ROLLBACK'); } catch { /* already rolled back */ }
+        throw error;
+      } finally {
+        this.inTx = false;
+      }
+      try {
+        if (force) this.stateText = null;
+        this.persist(before);
+      } catch (error) {
+        this.stamp = null; // what memory holds may not be on disk: the next reader reloads from the files
+        throw error;
+      }
+      return out;
+    });
+  }
+
+  close() {
+    this.mem?.close();
+    this.mem = null;
+  }
+}

package/board/store.mjs

@@ -1,18 +1,20 @@
 // The board's store (docs/architecture/orchestrator.md §2.9). A board is a Kanban database in Hermes's own
 // format, so either implementation opens the other's board: `kanban.db` at the home's root is the default board,
-// `kanban/boards/<slug>/kanban.db` a named one; the tables, columns, statuses and event kinds are Hermes's. What
+// `kanban/boards/<slug>/kanban.db` a named one; the tables, columns, statuses and event kinds are Hermes's, whichever
+// backing keeps them (below). What
 // supercode knows beyond Hermes lives where Hermes leaves it alone: a run's `metadata` JSON (the session the
 // dispatcher launched) and a table of our own, `supercode_cards` (the machine a card runs on, the arc a subtask
 // belongs to).
 //
-// This module opens a board and gives its callers one primitive, a write transaction; the transitions are in
-// `engine.mjs`. Hermes's own tools may write the same file at the same time: every write takes SQLite's writer
-// lock (`BEGIN IMMEDIATE`) and retries while the other holds it.
+// 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
+// writer lock (`BEGIN IMMEDIATE`) and retries while the other holds it.
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { isFilesBoard, openFilesBoard } from './files.mjs';
 
 export const DEFAULT_BOARD = 'default';
 
@@ -70,18 +72,51 @@ const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY K
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
 const OURS_COLUMNS = { subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT' };
 
-/** The database file of board `slug` in the home at `root`. */
+// ------------------------------------------------------------------ backings
+//
+// A board's tables are its contract: the engine and the dispatcher speak them as SQL to whatever backing keeps the
+// board. `sqlite` is Hermes's own `kanban.db`, one SQLite file Hermes and supercode both write; `files` (`files.mjs`)
+// is a directory with one JSON file per card that only supercode writes. A board is whichever backing is on disk; a
+// new one is `sqlite` unless its creator names another (`init --backing files`, `boards create <slug> --backing files`).
+export const BACKINGS = ['sqlite', 'files'];
+
+const boardDirOf = (root, slug) => (!slug || slug === DEFAULT_BOARD ? join(root, 'kanban') : join(root, 'kanban', 'boards', slug));
+
+/** Where each backing keeps board `slug` of the home at `root`. */
+export function backingPaths(root, slug = DEFAULT_BOARD) {
+  return {
+    sqlite: !slug || slug === DEFAULT_BOARD ? join(root, 'kanban.db') : join(boardDirOf(root, slug), 'kanban.db'),
+    files: join(boardDirOf(root, slug), 'board'),
+  };
+}
+
+/** The backing that keeps board `slug` now; null when it does not exist. */
+export function backingOf(root, slug = DEFAULT_BOARD) {
+  const at = backingPaths(root, slug);
+  const have = BACKINGS.filter((b) => (b === 'files' ? isFilesBoard(at.files) : existsSync(at.sqlite)));
+  if (have.length > 1) throw new Error(`board ${slug} in ${root} is kept twice (${have.map((b) => at[b]).join(' and ')}); one backing keeps a board`);
+  return have[0] ?? null;
+}
+
+/** Whether board `slug` exists in the home at `root`, in any backing. */
+export const boardExists = (root, slug = DEFAULT_BOARD) => backingOf(root, slug) !== null;
+
+/** Where board `slug` is kept: Hermes's `kanban.db`, or a files board's directory. */
 export function boardPath(root, slug = DEFAULT_BOARD) {
-  return !slug || slug === DEFAULT_BOARD ? join(root, 'kanban.db') : join(root, 'kanban', 'boards', slug, 'kanban.db');
+  const at = backingPaths(root, slug);
+  return at[backingOf(root, slug) ?? 'sqlite'];
 }
 
-/** The home's boards that exist: `default` when `kanban.db` does, and every named one. */
+/** The directory of the board's worker logs, as Hermes lays them out. */
+export const logsDir = (root, slug = DEFAULT_BOARD) => join(boardDirOf(root, slug), 'logs');
+
+/** The home's boards that exist: `default` when it does, and every named one. */
 export function listBoards(root) {
-  const out = existsSync(boardPath(root)) ? [DEFAULT_BOARD] : [];
+  const out = boardExists(root) ? [DEFAULT_BOARD] : [];
   const named = join(root, 'kanban', 'boards');
   if (existsSync(named)) {
     for (const slug of readdirSync(named)) {
-      if (slug.startsWith('_') || !existsSync(boardPath(root, slug))) continue;
+      if (slug.startsWith('_') || !boardExists(root, slug)) continue;
       // a board archived in its metadata is not dispatched (Hermes lists boards without the archived)
       try { if (JSON.parse(readFileSync(join(named, slug, 'board.json'), 'utf8'))?.archived) continue; } catch { /* no metadata: live */ }
       out.push(slug);
@@ -90,33 +125,44 @@ export function listBoards(root) {
   return out;
 }
 
-/** Open (creating when `create`) board `slug`: `{ db, root, slug, path, close }`. */
-export function openBoard(root, slug = DEFAULT_BOARD, { create = false } = {}) {
-  const path = boardPath(root, slug);
-  if (!existsSync(path)) {
-    if (!create) throw new Error(`no board ${slug} in ${root} (${path})`);
-    mkdirSync(dirname(path), { recursive: true });
-  }
+/** Hermes's tables on a fresh board, supercode's own table and columns on every one. */
+function layOut(db, { fresh }) {
+  if (fresh) db.exec(SCHEMA);
+  db.exec(OURS);
+  const have = new Set(db.prepare('PRAGMA table_info(supercode_cards)').all().map((c) => c.name));
+  for (const [column, type] of Object.entries(OURS_COLUMNS)) if (!have.has(column)) db.exec(`ALTER TABLE supercode_cards ADD COLUMN ${column} ${type}`);
+}
+
+/**
+ * Open (creating when `create`, in `backing`) board `slug`: `{ db, root, slug, path, backing, tx, close }`. `db` answers
+ * SQLite's statement API (`prepare(sql).get|all|run`, `exec`) whatever the backing.
+ */
+export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing = null } = {}) {
+  const kept = backingOf(root, slug);
+  if (!kept && !create) throw new Error(`no board ${slug} in ${root} (${boardPath(root, slug)})`);
+  if (kept && backing && kept !== backing) throw new Error(`board ${slug} in ${root} is kept by the ${kept} backing, not ${backing}`);
+  const use = kept ?? backing ?? 'sqlite';
+  if (!BACKINGS.includes(use)) throw new Error(`a board's backing is ${BACKINGS.join(' | ')}, not ${use}`);
+  const path = backingPaths(root, slug)[use];
+  if (use === 'files') return { ...openFilesBoard(path, { create, init: layOut }), root, slug, path, backing: use };
+  if (!kept) mkdirSync(dirname(path), { recursive: true });
   const db = new DatabaseSync(path);
   db.exec('PRAGMA busy_timeout = 10000');
   db.exec('PRAGMA foreign_keys = OFF');
   const fresh = !db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'tasks'").get();
-  if (fresh) {
-    if (!create) { db.close(); throw new Error(`${path} is not a board`); }
-    db.exec(SCHEMA);
-  }
-  db.exec(OURS);
-  const have = new Set(db.prepare('PRAGMA table_info(supercode_cards)').all().map((c) => c.name));
-  for (const [column, type] of Object.entries(OURS_COLUMNS)) if (!have.has(column)) db.exec(`ALTER TABLE supercode_cards ADD COLUMN ${column} ${type}`);
-  return { db, root, slug, path, close: () => db.close() };
+  if (fresh && !create) { db.close(); throw new Error(`${path} is not a board`); }
+  layOut(db, { fresh });
+  return { db, root, slug, path, backing: use, tx: (fn) => sqliteTx(db, fn), close: () => db.close() };
 }
 
 /**
- * Run `fn(db)` in one write transaction (`BEGIN IMMEDIATE`: the writer lock taken up front, so a read inside the
- * transaction is the state it writes over). Answers what `fn` answers; rolls back on a throw.
+ * Run `fn(db)` in one write transaction of the board's backing: answers what `fn` answers; rolls back on a throw.
+ * A read inside the transaction is the state it writes over.
  */
-export function tx(board, fn) {
-  const { db } = board;
+export const tx = (board, fn) => board.tx(fn);
+
+// SQLite's own: `BEGIN IMMEDIATE` takes the writer lock up front, retried while Hermes's writers hold it
+function sqliteTx(db, fn) {
   for (let attempt = 0; ; attempt += 1) {
     try {
       db.exec('BEGIN IMMEDIATE');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "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": {