@volter/supercode-orchestrator 0.4.76 → 0.4.78

package/board/cli.mjs

@@ -10,7 +10,8 @@ import { basename, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { read } from '../orchestration.mjs';
 import { holdDispatcherLock } from '../hermes-locks.mjs';
-import { backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, tx } from './store.mjs';
+import { backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, tx } from './store.mjs';
+import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
 import { adoptSession, boardAddress, boardLabel, boardSettings, callerSession, lanesOf, localMachine, observeFleet, paused, plan, startCard, tick } from './dispatch.mjs';
 import { loadWorkflow, scopeOf, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
@@ -19,7 +20,9 @@ import { evaluate } from './expr.mjs';
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
 
 Hermes Kanban's verbs, with their flags:
-  init · boards list|create|rm|switch|show|rename|set-default-workdir|export|import
+  init [--backing sqlite|files|ztrack] [--document <arcs.md>]
+  migrate --backing ztrack --document <arcs.md> --status-map <json>
+  boards list|create|rm|switch|show|rename|set-default-workdir|export|import
   create <title> [--body] [--assignee] [--parent]... [--workspace scratch|worktree[:<path>]|dir:<path>] [--branch] [--project]
          [--tenant] [--priority] [--triage] [--idempotency-key] [--max-runtime 30m] [--created-by] [--skill]... [--max-retries]
          [--model] [--provider] [--goal|--no-goal] [--goal-max-turns] [--initial-status blocked|running]
@@ -226,7 +229,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, backing: create ? args.backing ?? null : null }); b.label = boardLabel(root, slug); return b; };
+  const open = (create = false) => { const b = openBoard(root, slug, { create, document: args.document ?? null, 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];
@@ -248,6 +251,23 @@ export async function runWorkflow(argv) {
   if (!sid && verb !== 'help') { try { setActor([].concat(workflowFor(root).params?.managers ?? [])[0] ?? null); } catch { /* no workflow */ } }
 
   switch (verb) {
+    case 'migrate': {
+      if (args.backing !== 'ztrack' || !args.document || !args['status-map']) throw new Error('migrate needs --backing ztrack --document <arcs.md> --status-map <json>');
+      if (backingOf(root, slug) !== 'sqlite') throw new Error('migration starts from a SQLite board');
+      const paths = backingPaths(root, slug);
+      const preparing = `${paths.ztrack}.preparing`;
+      if (existsSync(preparing)) throw new Error(`unfinished migration retained at ${preparing}; inspect it before retrying`);
+      const mapping = JSON.parse(readFileSync(args['status-map'], 'utf8'));
+      const source = openBoard(root, slug);
+      try {
+        const migrated = openZtrackBoard(preparing, { create: true, document: args.document, seed: { db: source.db, mapping }, init: layOut, root, slug, compatPath: paths.sqlite });
+        migrated.close();
+      } finally { source.close(); }
+      renameSync(`${preparing}.runtime.db`, `${paths.ztrack}.runtime.db`);
+      renameSync(preparing, paths.ztrack);
+      say(args, `Board migrated to ${args.document}; kanban.db is now a Hermes export`, { ok: true, backing: 'ztrack', document: args.document });
+      return 0;
+    }
     case 'init': {
       const backing = withBoard((b) => b.backing, true);
       const { profiles } = await laneState(root).catch(() => ({ profiles: [] }));
@@ -532,7 +552,7 @@ export async function runWorkflow(argv) {
     case 'unblock': {
       need(1, 'a card id');
       const results = [];
-      for (const t of ids()) results.push([t, (await withBoardAsync((b) => engine.unblock(b, t, { reason: args.reason ?? null }))).to]);
+      for (const t of ids()) results.push([t, (await withBoardAsync((b) => engine.unblock(b, t, { reason: args.reason ?? null, on: args.on ?? null }))).to]);
       // Hermes records the reason as a comment on each card it unblocks
       if (args.reason) for (const [t] of results) await withBoardAsync((b) => engine.comment(b, t, callerName(), `UNBLOCK: ${args.reason}`));
       say(args, results.map(([t, s]) => `Unblocked ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
@@ -841,7 +861,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, backing: args.backing ?? null }).close();
+      openBoard(root, slug, { create: true, document: args.document ?? null, 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;

package/board/dispatch.mjs

@@ -268,7 +268,7 @@ function limitsOf(db, board, entry, task, session) {
   const status = statusOf(db, task);
   const scope = scopeOf(db, board, task, { params: entry.params, extra: { run: { surface: session?.surface ?? null, local: true } } });
   const out = {};
-  for (const [name, expr] of Object.entries(runSpec(entry, status)?.limits ?? {})) {
+  for (const [name, expr] of Object.entries({ ...entry.workflow.run?.limits, ...runSpec(entry, status, task)?.limits })) {
     const v = evaluate(expr, scope);
     out[name] = v === null || v === undefined || v === '' ? null : Number(v);
   }
@@ -321,7 +321,7 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
     const t = transitionsFor(workflow, status, d.start).find((x) => (!x.by?.length || x.by.includes('platform')) && holds(x.guard ?? null, scope));
     if (!t) return null;
     const target = t.target ? String(templateValue(t.target, scope)) : status;
-    const spec = runSpec(entry, target);
+    const spec = runSpec(entry, target, scope.card);
     const profile = spec ? evaluate(workflow.roles?.[spec.role] ?? 'card.assignee', scope) : null;
     return { target, runSpec: spec, profile, lane: profile ? lanes[profile] ?? null : null };
   };
@@ -419,7 +419,7 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
 export function launchRun(board, entry, id, lane, fleet, settings) {
   const task = getTaskNow(board, id);
   const status = tx(board, (db) => statusOf(db, task));
-  const spec = runSpec(entry, status);
+  const spec = runSpec(entry, status, task);
   if (!spec) return null;
   const runId = task.current_run_id;
   const surface = lane.surface === 'pane' ? 'pane' : 'headless';
@@ -431,6 +431,11 @@ export function launchRun(board, entry, id, lane, fleet, settings) {
   // the run's session record knows its status, role and slot (a reviewer's slot is never the implementer's); the slot
   // is a template, so a step can ask for isolation by naming a new one
   const slot = String(templateValue(spec.session ?? 'worker', scope) ?? 'worker');
+  if (spec.role === 'reviewer') {
+    const worker = tx(board, (db) => lastSession(db, id, 'worker'));
+    const reviewer = tx(board, (db) => lastSession(db, id, slot));
+    if (slot === 'worker' || (worker?.session_id && worker.session_id === reviewer?.session_id)) throw new Error('a reviewer must have a different session from the implementer');
+  }
   const meta = { status, role: spec.role, slot };
   return surface === 'pane'
     ? launchPane(board, task, runId, lane, fleet, { input: prompt, slot, meta })
@@ -443,7 +448,7 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
   const fleet = observeFleet();
   const moved = tx(board, (db) => fire(db, board, entry, id, entry.workflow.dispatch.start, { roles, payload: { lock: claimer() } }));
   const task = getTaskNow(board, id);
-  const spec = runSpec(entry, moved.to);
+  const spec = runSpec(entry, moved.to, task);
   const profile = spec ? tx(board, (db) => evaluate(entry.workflow.roles?.[spec.role] ?? 'card.assignee', scopeOf(db, board, task, { params: entry.params }))) : null;
   const lane = profile ? lanes[profile] : null;
   if (spec && !lane) throw new Error(`${id} is ${moved.to}, run by ${spec.role} (${profile ?? 'nobody'}), which is no lane of this home`);

package/board/engine.mjs

@@ -325,7 +325,8 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
     roles ??= callerRoles(db, id);
     const r = fire(db, board, entry, id, name, { roles, payload, extra });
     // the cards that wait on it, and its subtasks, see it change
-    const around = [...childrenOf(db, id), ...all(db, 'SELECT task_id AS id FROM supercode_cards WHERE subtask_of = ?', id).map((x) => x.id)];
+    const related = all(db, 'SELECT task_id, blocked_by FROM supercode_cards').filter((c) => json(c.blocked_by, []).some((b) => b.id === id)).map((c) => c.task_id);
+    const around = [...related, ...childrenOf(db, id), ...all(db, 'SELECT task_id AS id FROM supercode_cards WHERE subtask_of = ?', id).map((x) => x.id)];
     for (const other of new Set(around)) settle(db, board, entry, other, r.effects);
     return r;
   });
@@ -347,7 +348,8 @@ export async function goto(board, id, status, { roles = null, payload = {} } = {
 
 /** The I/O a committed move asked for. */
 export async function runEffects(board, effects = []) {
-  for (const e of effects) {
+  const pending = tx(board, (db) => db.prepare('SELECT id, effect FROM supercode_effects ORDER BY id').all());
+  for (const e of [...pending.map((p) => ({ ...json(p.effect, {}), durableId: p.id })), ...effects]) {
     if (e.kind === 'cleanup_workspace') cleanupWorkspace(board, e.id);
     else if (e.kind === 'invalidate_descendants') tx(board, (db) => invalidateDescendants(db, board, e.id));
     else if ((e.kind === 'run_ended' && e.outcome === 'reclaimed') || e.kind === 'stop_run') stopWorker(board, e.runId);
@@ -355,6 +357,7 @@ export async function runEffects(board, effects = []) {
       const { sessionEffect } = await import('./dispatch.mjs');
       await sessionEffect(board, e);
     }
+    if (e.durableId) tx(board, (db) => db.prepare('DELETE FROM supercode_effects WHERE id = ?').run(e.durableId));
   }
 }
 
@@ -414,7 +417,7 @@ export const complete = (board, id, { result = null, summary = null, metadata =
 // a block names the one thing that ends it: a card it waits on (`on`), or the message whose answer it waits for (`waiting_on`)
 export const block = (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
   act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
-export const unblock = (board, id, { reason = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason } });
+export const unblock = (board, id, { reason = null, on = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason, on } });
 export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles } = {}) =>
   act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId } });
 export const requestChanges = (board, id, { reason = null, reviewer = null, roles } = {}) => act(board, id, 'request_changes', { roles, payload: { reason, reviewer } });

package/board/store.mjs

@@ -14,6 +14,7 @@ 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 { openZtrackBoard } from './ztrack.mjs';
 import { isFilesBoard, openFilesBoard } from './files.mjs';
 
 export const DEFAULT_BOARD = 'default';
@@ -67,7 +68,8 @@ CREATE INDEX IF NOT EXISTS idx_events_run ON task_events(run_id, id);
 
 // supercode's part of a card, beside Hermes's row: where its session runs, and the arc a subtask belongs to (a
 // subtask is worked by its arc's session and never started on its own).
-const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY KEY, machine TEXT, subtask_of TEXT, stage TEXT);`;
+const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY KEY, machine TEXT, subtask_of TEXT, stage TEXT);
+CREATE TABLE IF NOT EXISTS supercode_effects (id INTEGER PRIMARY KEY AUTOINCREMENT, effect TEXT NOT NULL);`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `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', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
@@ -78,7 +80,7 @@ const OURS_COLUMNS = { subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', afte
 // 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'];
+export const BACKINGS = ['sqlite', 'files', 'ztrack'];
 
 const boardDirOf = (root, slug) => (!slug || slug === DEFAULT_BOARD ? join(root, 'kanban') : join(root, 'kanban', 'boards', slug));
 
@@ -87,13 +89,15 @@ 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'),
+    ztrack: join(boardDirOf(root, slug), 'ztrack.json'),
   };
 }
 
 /** 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 (existsSync(at.ztrack)) return 'ztrack'; // kanban.db is this backing's projection
+  const have = BACKINGS.filter((b) => b !== 'ztrack').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;
 }
@@ -126,7 +130,7 @@ export function listBoards(root) {
 }
 
 /** Hermes's tables on a fresh board, supercode's own table and columns on every one. */
-function layOut(db, { fresh }) {
+export 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));
@@ -137,13 +141,14 @@ function layOut(db, { fresh }) {
  * 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 } = {}) {
+export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing = null, document = 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 === 'ztrack') return { ...openZtrackBoard(path, { create, document, init: layOut, root, slug, compatPath: backingPaths(root, slug).sqlite }), root, slug, path, backing: 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);

package/board/workflow.mjs

@@ -472,7 +472,7 @@ const ACTIONS = {
     }
     if (remove) {
       if (!String(reason ?? '').trim()) throw new Error('unblock must say what arrived');
-      blocks = blocks.filter((b) => remove !== '*' && b.id !== remove);
+      blocks = blocks.filter((b) => remove === 'messages' ? b.kind !== 'message' : remove !== '*' && b.id !== remove);
     }
     cardField(ctx, 'blocked_by', JSON.stringify(blocks));
   },
@@ -480,7 +480,7 @@ const ACTIONS = {
     if (!['paused', 'archived'].includes(name)) throw new Error(`unknown flag ${name}`);
     if (name === 'paused') {
       const was = json(one(ctx.db, 'SELECT paused FROM supercode_cards WHERE task_id = ?', ctx.id)?.paused, null);
-      if (!value && was && was.by !== actorOf() && !ctx.scope.sender?.includes('owner')) throw new Error('only the pauser or owner may resume this card');
+      if (!value && was && was.by !== actorOf() && !ctx.scope.sender?.includes('owner') && !(ctx.scope.sender?.includes('hermes') && ctx.scope.event?.hermes)) throw new Error('only the pauser or owner may resume this card');
       if (value && !String(reason ?? '').trim()) throw new Error('pause needs a reason');
       cardField(ctx, name, value ? JSON.stringify({ by: actorOf(), reason }) : null);
     } else cardField(ctx, name, Number(Boolean(value)));
@@ -490,8 +490,8 @@ const ACTIONS = {
     cardField(ctx, 'every', interval == null ? null : String(interval));
     cardField(ctx, 'next_run_at', interval == null ? null : now());
   },
-  card_event(ctx, { name, payload = {} }) {
-    const result = fire(ctx.db, ctx.board, ctx.entry, ctx.id, name, { roles: ['platform'], payload, extra: ctx.scope });
+  card_event(ctx, { name, payload = {}, as = ['platform'] }) {
+    const result = fire(ctx.db, ctx.board, ctx.entry, ctx.id, name, { roles: [].concat(as), payload, extra: { lanes: lanesIn(ctx.entry) } });
     ctx.effects.push(...result.effects);
   },
   record(ctx, args, scope) {
@@ -566,8 +566,9 @@ const ACTIONS = {
       run(ctx.db, "UPDATE task_runs SET status = 'reclaimed', outcome = 'reclaimed', summary = COALESCE(summary, 'invariant recovery on re-claim'), ended_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ? AND ended_at IS NULL", t, task.current_run_id);
     }
     const expires = t + ttl;
+    role = runSpec(ctx.entry, ctx.to, scope.card)?.role ?? role;
     const profile = evaluate(ctx.entry.workflow.roles?.[role] ?? 'card.assignee', scope) ?? task.assignee;
-    const slot = String(templateValue(runSpec(ctx.entry, ctx.to)?.session ?? 'worker', scope) ?? 'worker');
+    const slot = String(templateValue(runSpec(ctx.entry, ctx.to, scope.card)?.session ?? 'worker', scope) ?? 'worker');
     run(ctx.db, 'UPDATE tasks SET claim_lock = ?, claim_expires = ?, started_at = COALESCE(started_at, ?) WHERE id = ?', lock, expires, t, ctx.id);
     const r = run(ctx.db, "INSERT INTO task_runs (task_id, profile, step_key, status, claim_lock, claim_expires, max_runtime_seconds, started_at, metadata) VALUES (?, ?, ?, 'running', ?, ?, ?, ?, ?)",
       ctx.id, profile, ctx.to, lock, expires, task.max_runtime_seconds, t, JSON.stringify({ supercode: { role, status: ctx.to, slot, state: ctx.entry.workflow.run?.initial ?? null } }));
@@ -705,9 +706,10 @@ export function intervalSeconds(value) {
   return seconds;
 }
 
-export function runSpec(entry, status) {
+export function runSpec(entry, status, card = null) {
   const st = entry.workflow.statuses[status];
-  const spec = st?.run_role ? entry.workflow.run?.roles?.[st.run_role] : st?.run;
+  const name = card?.every && entry.workflow.run?.recurring_role ? entry.workflow.run.recurring_role : st?.run_role;
+  const spec = name ? entry.workflow.run?.roles?.[name] : st?.run;
   if (!spec?.prompt_file) return spec;
   const file = resolve(entry.root, spec.prompt_file);
   const rel = relative(entry.root, file);
@@ -760,12 +762,21 @@ function settleRelations(db, board, entry, id, effects) {
   const row = one(db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', id);
   const blocks = json(row?.blocked_by, []) ?? [];
   for (const block of blocks) {
+    if (!json(one(db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', id)?.blocked_by, []).some((b) => b.id === block.id)) continue;
     const dependency = block.kind === 'card' ? one(db, 'SELECT * FROM tasks WHERE id = ?', block.id) : null;
     const status = dependency ? statusOf(db, dependency) : null;
     const answer = block.kind === 'message' ? answerTo(block.id) : null;
     const policy = entry.workflow.relations.blocked_by;
     const name = answer ? policy.answered : status === 'done' ? policy.completed : status === 'cancelled' ? policy.cancelled : null;
     if (name) effects.push(...fire(db, board, entry, id, name, { roles: ['platform'], payload: { on: block.id, reason: answer ? `reply ${answer}` : `${block.id} ${status}` } }).effects);
+    else if (policy.aged && policy.age_seconds != null) {
+      const seconds = Number(evaluate(String(policy.age_seconds), { params: entry.params }));
+      if (seconds > 0 && now() - Number(block.notified_at ?? block.since ?? now()) >= seconds) {
+        const current = json(one(db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', id)?.blocked_by, []);
+        run(db, 'UPDATE supercode_cards SET blocked_by = ? WHERE task_id = ?', JSON.stringify(current.map((b) => b.id === block.id ? { ...b, notified_at: now() } : b)), id);
+        effects.push(...fire(db, board, entry, id, policy.aged, { roles: ['platform'], payload: { on: block.id, reason: block.reason } }).effects);
+      }
+    }
   }
 }
 

package/board/ztrack.mjs

@@ -0,0 +1,366 @@
+// The document is card state; SQLite here is only a runtime journal and Hermes projection.
+// ADR 0001. All markdown interpretation belongs to ztrack's public codec and kanban preset.
+import { createRequire } from 'node:module';
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+import { actorOf, event, json, now, setActor } from './store.mjs';
+import { fire, projectStatus, statusOf, workflowFor } from './workflow.mjs';
+
+const require = createRequire(import.meta.url);
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const read = (path) => existsSync(path) ? readFileSync(path, 'utf8') : '';
+const quote = (s) => `"${s.replaceAll('"', '""')}"`;
+const nativeId = (id) => /^t-[a-f0-9]+$/.test(id) ? id.replace('t-', 't_') : id;
+const RUNTIME = new Set(['claim_lock', 'claim_expires', 'worker_pid', 'last_heartbeat_at', 'current_run_id', 'consecutive_failures', 'last_failure_error', 'block_recurrences', 'session_id']);
+const CARD_MAIN = new Set(['id', 'title', 'body', 'status', 'assignee', 'priority', 'workspace_kind', 'workspace_path', 'branch_name']);
+const EPHEMERAL = new Set(['tasks', 'supercode_cards', 'task_links', 'sqlite_sequence']);
+const atomic = (path, text) => { const tmp = `${path}.${process.pid}.tmp`; writeFileSync(tmp, text, { mode: 0o600 }); renameSync(tmp, path); };
+
+export function openZtrackBoard(marker, { create = false, document = null, seed = null, init, root, slug, compatPath }) {
+  if (!existsSync(marker)) {
+    if (!create) throw new Error(`no ztrack board ${marker}`);
+    mkdirSync(dirname(marker), { recursive: true });
+    atomic(marker, JSON.stringify({ format: 1, document: resolve(document ?? resolve(dirname(marker), 'arcs.md')) }) + '\n');
+  }
+  const config = JSON.parse(read(marker));
+  const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, compatPath });
+  return { db: backing.db, tx: (fn) => backing.tx(fn), close: () => backing.close(), document: backing.path };
+}
+
+class ZtrackBoard {
+  constructor({ document, seed, marker, init, root, slug, compatPath }) {
+    this.path = resolve(dirname(marker), document);
+    this.archive = `${this.path}.archive.md`;
+    this.lockPath = `${marker}.lock`;
+    this.seed = seed;
+    this.root = root; this.slug = slug; this.init = init; this.compatPath = compatPath;
+    this.codec = require('@volter/ztrack/board-document');
+    this.preset = require('@volter/ztrack/kanban-preset');
+    this.runtime = new DatabaseSync(`${marker}.runtime.db`);
+    this.runtime.exec('PRAGMA busy_timeout = 10000; CREATE TABLE IF NOT EXISTS state (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+    this.mem = null; this.active = false;
+    mkdirSync(dirname(this.path), { recursive: true });
+    const self = this;
+    this.db = {
+      prepare(sql) { return Object.fromEntries(['get', 'all', 'run', 'iterate'].map((method) => [method, (...args) => self.access(() => method === 'iterate' ? self.mem.prepare(sql).all(...args)[Symbol.iterator]() : self.mem.prepare(sql)[method](...args), method !== 'run')])); },
+      exec(sql) { return self.access(() => self.mem.exec(sql)); },
+      close() { self.close(); },
+    };
+    this.tx(() => {});
+  }
+  get(key, fallback = null) { return json(this.runtime.prepare('SELECT value FROM state WHERE key = ?').get(key)?.value, fallback); }
+  put(key, value) { this.runtime.prepare('INSERT INTO state VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, JSON.stringify(value)); }
+  stamp() {
+    const fileStamp = (path) => { try { const s = statSync(path); return `${s.ino}:${s.size}:${s.mtimeMs}`; } catch { return 'missing'; } };
+    return [fileStamp(this.path), fileStamp(this.archive), fileStamp(this.compatPath), this.get('version', '')].join('|');
+  }
+  access(fn, reading = false) {
+    if (this.active || (reading && this.mem && this.loadedStamp === this.stamp())) return fn();
+    return this.tx(fn);
+  }
+  close() { this.mem?.close(); this.runtime.close(); }
+  board() { return { root: this.root, slug: this.slug, label: this.slug, db: this.db }; }
+  recover() {
+    const pending = this.get('pending');
+    if (!pending) return;
+    for (const file of pending.files) {
+      const current = hash(read(file.path));
+      if (current !== file.before && current !== hash(file.text)) throw new Error(`unfinished board write conflicts with an edit to ${file.path}; retained runtime journal`);
+      if (current === file.before) atomic(file.path, file.text);
+    }
+    this.put('snapshot', pending.snapshot);
+    this.runtime.prepare("DELETE FROM state WHERE key = 'pending'").run();
+  }
+  tx(fn) {
+    if (this.active) return fn(this.db);
+    let lock;
+    for (let n = 0; ; n++) {
+      try { lock = openSync(this.lockPath, 'wx', 0o600); writeFileSync(lock, String(process.pid)); break; }
+      catch (error) {
+        if (error.code !== 'EEXIST' || n >= 100) throw error;
+        const pid = Number(read(this.lockPath));
+        if (pid) { try { process.kill(pid, 0); } catch (e) { if (e.code === 'ESRCH') { unlinkSync(this.lockPath); continue; } } }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+      }
+    }
+    try { return this.transaction(fn); } finally { closeSync(lock); unlinkSync(this.lockPath); }
+  }
+  transaction(fn) {
+    for (let attempt = 0; attempt < 8; attempt++) {
+      this.runtime.exec('BEGIN IMMEDIATE'); this.active = true;
+      let committed = false;
+      try {
+        this.recover();
+        this.load();
+        if (this.seed) this.seedIntoMemory();
+        else this.lift();
+        const result = fn(this.db);
+        const documents = this.documents();
+        const files = [{ path: this.path, before: hash(this.text), text: documents.open }, { path: this.archive, before: hash(this.archiveText), text: documents.archived }];
+        if (files.some((f) => hash(read(f.path)) !== f.before)) { this.runtime.exec('ROLLBACK'); continue; }
+        const snapshot = this.snapshot();
+        // A durable intent precedes filesystem writes; recovery completes exactly this version.
+        this.put('pending', { files, snapshot });
+        this.runtime.exec('COMMIT'); committed = true;
+        // Detect an editor racing the journal commit before replacing either document.
+        if (files.some((f) => hash(read(f.path)) !== f.before)) {
+          this.runtime.exec('BEGIN IMMEDIATE'); this.runtime.prepare("DELETE FROM state WHERE key = 'pending'").run(); this.runtime.exec('COMMIT');
+          continue;
+        }
+        for (const f of files) if (hash(f.text) !== f.before) atomic(f.path, f.text);
+        this.runtime.exec('BEGIN IMMEDIATE');
+        this.put('snapshot', snapshot); this.runtime.prepare("DELETE FROM state WHERE key = 'pending'").run();
+        this.export();
+        this.put('version', randomBytes(8).toString('hex'));
+        this.runtime.exec('COMMIT');
+        this.loadedStamp = this.stamp();
+        this.seed = null;
+        return result;
+      } catch (error) {
+        try { this.runtime.exec('ROLLBACK'); } catch { /* intent already durable */ }
+        if (committed) error.message += ' (the runtime journal retains any unfinished document write)';
+        throw error;
+      } finally { this.active = false; }
+    }
+    throw new Error('board document kept changing during eight version-checked retries; no edit was overwritten');
+  }
+  seedIntoMemory() {
+    const source = this.seed;
+    for (const table of this.mem.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) this.mem.exec(`DELETE FROM ${quote(table.name)}`);
+    for (const table of source.db.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
+      if (!this.mem.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table.name)) this.mem.exec(table.sql);
+      for (const row of source.db.prepare(`SELECT * FROM ${quote(table.name)}`).all()) this.insert(table.name, row);
+    }
+    for (const task of this.mem.prepare('SELECT * FROM tasks').all()) {
+      const old = this.mem.prepare('SELECT * FROM supercode_cards WHERE task_id = ?').get(task.id) ?? {};
+      if (old.subtask_of) { const key = /^([a-z]+\d+)\s/.exec(task.title)?.[1]; if (key) this.taskKeys.set(task.id, `${old.subtask_of}:${key}`); }
+      const status = old.stage ?? task.status;
+      const mapped = source.mapping[status];
+      if (!mapped) throw new Error(`migration needs an explicit mapping for ${status} (${task.id})`);
+      const stage = typeof mapped === 'string' ? mapped : mapped.status;
+      const parents = this.mem.prepare('SELECT parent_id FROM task_links WHERE child_id = ?').all(task.id).map((p) => ({ id: p.parent_id, kind: 'card' }));
+      const last = this.mem.prepare("SELECT kind, payload FROM task_events WHERE task_id = ? AND kind IN ('blocked','unblocked') ORDER BY id DESC LIMIT 1").get(task.id);
+      const wait = last?.kind === 'blocked' ? json(last.payload, {})?.waiting_on : null;
+      if (wait) parents.push({ id: wait, kind: 'message' });
+      this.insert('supercode_cards', { ...old, task_id: task.id, stage, archived: Number(Boolean(mapped.archived) || stage === 'cancelled'), blocked_by: JSON.stringify(parents),
+        paused: mapped.paused ? JSON.stringify({ by: 'migration', reason: `migrated ${status}: ${json(last?.payload, {})?.reason ?? 'held by previous workflow'}` }) : null });
+      this.mem.prepare('UPDATE tasks SET status = ? WHERE id = ?').run(stage, task.id);
+      if (task.current_run_id && ['done','cancelled'].includes(stage)) {
+        this.mem.prepare("UPDATE task_runs SET ended_at = COALESCE(ended_at, ?), status = 'reclaimed', outcome = COALESCE(outcome, 'reclaimed') WHERE id = ?").run(now(), task.current_run_id);
+        this.mem.prepare('UPDATE tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL WHERE id = ?').run(task.id);
+      } else if (task.current_run_id) {
+        const run = this.mem.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(task.current_run_id);
+        const meta = json(run?.metadata, {}) ?? {}; meta.supercode = { ...meta.supercode, state: 'active' };
+        this.mem.prepare('UPDATE task_runs SET metadata = ? WHERE id = ?').run(JSON.stringify(meta), task.current_run_id);
+      }
+    }
+    this.put('hermes_cursor', Number(source.db.prepare('SELECT COALESCE(MAX(id),0) AS id FROM task_events').get().id));
+  }
+  insert(table, row) {
+    const columns = new Set(this.mem.prepare(`PRAGMA table_info(${quote(table)})`).all().map((c) => c.name));
+    const keys = Object.keys(row).filter((k) => columns.has(k));
+    if (!keys.length) return;
+    this.mem.prepare(`INSERT OR REPLACE INTO ${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
+  }
+  load() {
+    this.text = read(this.path); this.archiveText = read(this.archive);
+    this.mem?.close(); this.mem = new DatabaseSync(':memory:'); this.init(this.mem, { fresh: true });
+    this.saved = this.get('snapshot', { tables: {}, runtime: {}, clocks: {}, fingerprints: {} });
+    for (const item of Object.values(this.saved.tables ?? {})) {
+      if (item.sql) this.mem.exec(item.sql.replace('CREATE TABLE ', 'CREATE TABLE IF NOT EXISTS '));
+      for (const row of item.rows ?? []) this.insert(item.name, row);
+    }
+    const records = [...this.codec.parseBoardDocument(this.text, this.path), ...this.codec.parseBoardDocument(this.archiveText, this.archive)];
+    const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban(records));
+    this.originals = new Map(); this.fileIds = new Map(); this.taskKeys = new Map();
+    for (const card of parsed.issues) {
+      const id = nativeId(card.id);
+      if (this.originals.has(id)) throw new Error(`duplicate board card ${id}`);
+      this.originals.set(id, card); this.fileIds.set(id, card.id);
+      this.loadCard(id, card);
+      for (const task of card.acceptanceCriteria) {
+        const tid = task.metadata?.id ?? this.saved.taskIds?.[`${id}:${task.id}`] ?? `t_${randomBytes(4).toString('hex')}`;
+        this.taskKeys.set(tid, `${id}:${task.id}`);
+        const body = task.metadata?.body ?? '';
+        const taskCard = { ...task.metadata?.card, id: tid, title: `${task.id} ${task.text}`, body,
+          status: task.status === 'passed' ? 'done' : (task.metadata?.status === 'done' ? 'todo' : task.metadata?.status ?? 'todo'),
+          metadata: task.metadata?.properties ?? {}, assignee: task.metadata?.assignee ?? card.assignee,
+          machine: task.metadata?.machine ?? card.machine, acceptanceCriteria: [],
+          acceptance: task.lines ?? [], relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
+        if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
+        this.loadCard(tid, taskCard, id);
+      }
+    }
+    // Resolve local task refs only after all subtask identities are available.
+    const taskIds = new Map([...this.taskKeys].map(([id, key]) => [key, id]));
+    for (const row of this.mem.prepare('SELECT task_id, blocked_by FROM supercode_cards').all()) {
+      const blocks = json(row.blocked_by, []).map((b) => ({ ...b, id: taskIds.get(b.id) ?? b.id }));
+      this.mem.prepare('UPDATE supercode_cards SET blocked_by = ? WHERE task_id = ?').run(JSON.stringify(blocks), row.task_id);
+      for (const b of blocks.filter((b) => b.kind === 'card')) this.insert('task_links', { parent_id: b.id, child_id: row.task_id });
+    }
+    this.documentEvents();
+  }
+  loadCard(id, card, parent = null) {
+    const meta = card.metadata ?? {};
+    const stored = this.preset.serializeKanbanCard({ ...card, acceptanceCriteria: [], relations: [], metadata: undefined, paused: undefined, every: undefined, workspace: undefined, branch: undefined, machine: undefined, priority: undefined });
+    const workspace = /^(scratch|dir|worktree)(?::(.*))?$/.exec(card.workspace ?? 'scratch');
+    this.insert('tasks', { ...meta, ...this.saved.runtime?.[id], id, title: card.title, body: stored.body,
+      status: card.status, assignee: card.assignee ?? null, created_at: meta.created_at ?? now(), priority: card.priority ?? 0,
+      workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: workspace?.[2] ?? null, branch_name: card.branch ?? null });
+    this.insert('supercode_cards', { ...this.saved.clocks?.[id], task_id: id, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
+      blocked_by: JSON.stringify((card.relations ?? []).map((r) => ({ ...(meta.blocked_by ?? []).find((b) => b.id === nativeId(r.issueId)), id: nativeId(r.issueId), kind: /^[ma]-/.test(r.issueId) ? 'message' : 'card' }))),
+      paused: card.paused ? JSON.stringify(card.paused) : null, archived: meta.archived ? 1 : 0, every: card.every ?? null });
+  }
+  fingerprints() {
+    return Object.fromEntries(this.mem.prepare('SELECT * FROM tasks').all().map((t) => {
+      const c = this.mem.prepare('SELECT * FROM supercode_cards WHERE task_id = ?').get(t.id) ?? {};
+      return [t.id, { hash: hash(JSON.stringify([t.title, t.body, c.stage, t.assignee, c.machine, c.blocked_by, c.paused, c.every])), title: hash(t.title), body: hash(t.body ?? ''), status: c.stage, assignee: t.assignee, machine: c.machine, parent: c.subtask_of }];
+    }));
+  }
+  documentEvents() {
+    const previous = this.saved.fingerprints ?? {};
+    const current = this.fingerprints();
+    if (!Object.keys(previous).length) return;
+    const by = this.committer();
+    for (const [id, value] of Object.entries(current)) {
+      const old = previous[id];
+      if (old?.hash === value.hash) continue;
+      let entry; try { entry = workflowFor(this.root); } catch {}
+      if (old && entry?.workflow.verbs?.document_changed) {
+        const change = fire(this.mem, this.board(), entry, id, 'document_changed', { roles: ['platform'], payload: { previous_status: old.status, by, source: 'document' } });
+        for (const effect of change.effects) this.mem.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+      }
+      const kind = !old ? 'created' : old.status !== value.status ? 'status' : old.assignee !== value.assignee ? 'assigned' : 'specified';
+      event(this.mem, id, kind, { by, source: 'document', status: value.status, assignee: value.assignee, author: by });
+      if (!old && value.parent) event(this.mem, value.parent, 'subtask_added', { by, subtask: id, title: this.mem.prepare('SELECT title FROM tasks WHERE id = ?').get(id).title });
+    }
+    for (const id of Object.keys(previous)) if (!current[id]) {
+      if (this.saved.runtime?.[id]?.current_run_id) throw new Error(`document removed ${id} with a live run; cancel it through its workflow first`);
+      event(this.mem, id, 'removed', { by, source: 'document' });
+    }
+  }
+  committer() {
+    const r = spawnSync('git', ['-C', dirname(this.path), 'log', '-1', '--format=%an <%ae>', '--', this.path], { encoding: 'utf8', timeout: 5000 });
+    return r.status === 0 && r.stdout.trim() ? `git:${r.stdout.trim()}` : 'document-editor';
+  }
+  documents() {
+    const rows = this.mem.prepare('SELECT * FROM tasks ORDER BY created_at, id').all();
+    const states = new Map(this.mem.prepare('SELECT * FROM supercode_cards').all().map((c) => [c.task_id, c]));
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const cards = new Map();
+    for (const row of rows.filter((r) => !states.get(r.id)?.subtask_of)) {
+      const c = states.get(row.id) ?? {};
+      const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([{ id: this.fileIds.get(row.id) ?? row.id, title: row.title, status: c.stage ?? row.status, assignee: row.assignee || undefined, body: row.body ?? '' }])).issues[0];
+      const metadata = Object.fromEntries(Object.entries(row).filter(([k, v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null));
+      if (c.archived) metadata.archived = true;
+      if (json(c.blocked_by, []).length) metadata.blocked_by = json(c.blocked_by, []);
+      cards.set(row.id, { ...parsed, metadata, priority: row.priority ?? 0, workspace: row.workspace_kind + (row.workspace_path ? `:${row.workspace_path}` : ''),
+        branch: row.branch_name || undefined, machine: c.machine || undefined, paused: json(c.paused, null) ?? undefined, every: c.every || undefined,
+        relations: json(c.blocked_by, []).map((b) => ({ type: 'blocked-by', issueId: this.fileIds.get(b.id) ?? b.id })), acceptanceCriteria: [] });
+    }
+    const occupied = new Map();
+    for (const row of rows) {
+      const parent = states.get(row.id)?.subtask_of;
+      if (!parent) continue;
+      const key = this.taskKeys.get(row.id)?.split(':').at(-1) ?? /^([a-z]+\d+)\s/.exec(row.title)?.[1];
+      if (key) { const set = occupied.get(parent) ?? new Set(); set.add(key); occupied.set(parent, set); }
+    }
+    const renderedKeys = new Set();
+    for (const row of rows.filter((r) => states.get(r.id)?.subtask_of)) {
+      const c = states.get(row.id); const parent = cards.get(c.subtask_of);
+      if (!parent) throw new Error(`subtask ${row.id} has no arc ${c.subtask_of}`);
+      const taken = occupied.get(c.subtask_of) ?? new Set(); occupied.set(c.subtask_of, taken);
+      const match = /^([a-z]+\d+)\s+(.+)$/.exec(row.title);
+      let key = this.taskKeys.get(row.id)?.split(':').at(-1) ?? match?.[1];
+      if (!key || renderedKeys.has(`${c.subtask_of}:${key}`)) { let n = 1; while (taken.has(`c${n}`)) n++; key = `c${n}`; }
+      taken.add(key); renderedKeys.add(`${c.subtask_of}:${key}`); this.taskKeys.set(row.id, `${c.subtask_of}:${key}`);
+      const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([{ id: row.id, title: row.title, status: c.stage ?? row.status, body: row.body ?? '' }])).issues[0];
+      const originalTask = this.originals.get(c.subtask_of)?.acceptanceCriteria.find((t) => t.id === key);
+      parent.acceptanceCriteria.push({ sources: originalTask?.sources, id: key, status: ['done', 'cancelled'].includes(c.stage ?? row.status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? row.title,
+        metadata: { id: row.id, status: c.stage ?? row.status, body: parsed.body, assignee: row.assignee, machine: c.machine,
+          properties: Object.fromEntries(Object.entries(row).filter(([k,v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null)),
+          card: { paused: json(c.paused, null) ?? undefined, every: c.every || undefined } }, lines: parsed.acceptance,
+        blockedBy: json(c.blocked_by, []).map((b) => ({ issue: b.id })) });
+    }
+    const open = [], archived = [];
+    for (const [id, card] of cards) {
+      const serialized = this.preset.serializeKanbanCard(card);
+      const record = { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+      (states.get(id)?.archived || ['done', 'cancelled'].includes(card.status) ? archived : open).push(record);
+    }
+    return { open: this.codec.renderBoardDocument(this.text, open, this.path), archived: this.codec.renderBoardDocument(this.archiveText, archived, this.archive) };
+  }
+  snapshot() {
+    const tables = {};
+    for (const table of this.mem.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
+      if (!EPHEMERAL.has(table.name)) tables[table.name] = { ...table, rows: this.mem.prepare(`SELECT * FROM ${quote(table.name)}`).all() };
+    }
+    const runtime = Object.fromEntries(this.mem.prepare('SELECT * FROM tasks').all().map((t) => [t.id, Object.fromEntries(Object.entries(t).filter(([k]) => RUNTIME.has(k)))]));
+    const clocks = Object.fromEntries(this.mem.prepare('SELECT * FROM supercode_cards').all().map((c) => [c.task_id, { since: c.since, after_fired: c.after_fired, next_run_at: c.next_run_at }]));
+    return { tables, runtime, clocks, fingerprints: this.fingerprints(), taskIds: Object.fromEntries([...this.taskKeys].map(([id, key]) => [key, id])) };
+  }
+  lift() {
+    if (!existsSync(this.compatPath)) return;
+    let entry; try { entry = workflowFor(this.root); } catch { return; }
+    const compat = new DatabaseSync(this.compatPath);
+    try {
+      const cursor = this.get('hermes_cursor', 0);
+      const rows = compat.prepare('SELECT * FROM task_events WHERE id > ? ORDER BY id').all(cursor);
+      const before = actorOf();
+      try {
+        for (const row of rows) {
+          const payload = json(row.payload, {}) ?? {};
+          if (payload.__supercode_export) continue;
+          const task = this.mem.prepare('SELECT * FROM tasks WHERE id = ?').get(row.task_id);
+          if (!task) continue;
+          const roles = ['manager', 'reviewer', 'platform', 'hermes'];
+          setActor(payload.by ?? 'hermes');
+          let name = null; let words = { ...payload, reason: payload.reason ?? 'unblocked in Hermes' };
+          if (row.kind === 'unblocked') { name = 'unblock'; words = { ...words, reason: 'unblocked in Hermes', hermes: true }; }
+          else if (row.kind === 'completed') { name = 'complete'; words.summary = payload.summary ?? task.result; }
+          else if (row.kind === 'blocked' || row.kind === 'dependency_wait') { name = 'block'; words.on = payload.on ?? payload.parent ?? null; words.hermes = true; }
+          else if (row.kind === 'archived' && statusOf(this.mem, task) !== 'done') name = 'cancel';
+          if (row.kind === 'unblocked' && entry.workflow.verbs?.hermes_unpause) {
+            const resumed = fire(this.mem, this.board(), entry, task.id, 'hermes_unpause', { roles, payload: { hermes: true, reason: 'unblocked in Hermes' } });
+            for (const effect of resumed.effects) this.mem.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+          }
+          if (name) {
+            const result = fire(this.mem, this.board(), entry, task.id, name, { roles, payload: words });
+            for (const effect of result.effects) this.mem.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+          }
+          event(this.mem, task.id, 'hermes_lifted', { by: 'hermes', source_event: row.id, verb: name, kind: row.kind });
+        }
+      } finally { setActor(before); }
+      if (rows.length) this.put('hermes_cursor', rows.at(-1).id);
+    } finally { compat.close(); }
+  }
+  export() {
+    let entry; try { entry = workflowFor(this.root); } catch { return; }
+    for (const { id } of this.mem.prepare('SELECT id FROM tasks').all()) projectStatus(this.mem, this.board(), entry, id);
+    const compat = new DatabaseSync(this.compatPath);
+    compat.exec('PRAGMA busy_timeout = 10000');
+    try {
+      compat.exec('BEGIN IMMEDIATE'); this.init(compat, { fresh: true });
+      // Every import is event-based. Existing unconsumed acts must never be erased by an export race.
+      const cursor = this.get('hermes_cursor', 0);
+      const unseen = compat.prepare('SELECT payload FROM task_events WHERE id > ?').all(cursor).some((r) => !json(r.payload, {})?.__supercode_export);
+      if (unseen) throw new Error('Hermes wrote during board export; retained its events for the next read');
+      const tables = this.mem.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
+      for (const { name } of tables) {
+        if (!compat.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name)) continue;
+        compat.exec(`DELETE FROM ${quote(name)}`);
+        for (const source of this.mem.prepare(`SELECT * FROM ${quote(name)}`).all()) {
+          const row = { ...source };
+          if (name === 'task_events') row.payload = JSON.stringify({ ...json(row.payload, {}), __supercode_export: true });
+          const keys = Object.keys(row); compat.prepare(`INSERT INTO ${quote(name)} (${keys.map(quote)}) VALUES (${keys.map(() => '?')})`).run(...keys.map((k) => row[k]));
+        }
+      }
+      compat.exec('COMMIT');
+      this.put('hermes_cursor', Number(compat.prepare('SELECT COALESCE(MAX(id),0) AS id FROM task_events').get().id));
+    } catch (error) { try { compat.exec('ROLLBACK'); } catch {} throw error; }
+    finally { compat.close(); }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.76",
+  "version": "0.4.78",
   "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": {
@@ -25,7 +25,8 @@
   },
   "dependencies": {
     "yaml": "^2.9.0",
-    "@volter/supercode-harness-sdk": "^0.3.41"
+    "@volter/supercode-harness-sdk": "^0.3.41",
+    "@volter/ztrack": "^2.4.14"
   },
   "devDependencies": {
     "@chat-adapter/state-memory": "4.39.0",