@volter/supercode-orchestrator 0.4.38 → 0.4.39

package/board/cli.mjs

@@ -10,7 +10,7 @@ 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, plan, startCard, tick } from './dispatch.mjs';
 import { loadWorkflow, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.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)));
@@ -714,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;
@@ -801,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;
@@ -822,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 });
@@ -847,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);
@@ -910,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';
@@ -623,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);

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.38",
+  "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": {