@volter/supercode-orchestrator 0.4.29 → 0.4.31

package/board/engine.mjs

@@ -12,6 +12,7 @@ import { existsSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { claimer, event, json, newTaskId, now, tx } from './store.mjs';
+import { fire, initialStatus, loadWorkflow, setStatus, settle, statusOf, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
 export const BLOCK_KINDS = ['dependency', 'needs_input', 'capability', 'transient'];
@@ -111,10 +112,11 @@ export function setRunSession(db, runId, session) {
 }
 
 /** The card's latest session the dispatcher recorded, newest run first; null when it never had one. */
-export function lastSession(db, taskId) {
+export function lastSession(db, taskId, slot = 'worker') {
+  // a session slot's own last session (runs recorded before slots existed are the worker's)
   for (const row of all(db, 'SELECT metadata FROM task_runs WHERE task_id = ? AND metadata IS NOT NULL ORDER BY id DESC', taskId)) {
     const s = json(row.metadata, {})?.supercode;
-    if (s?.session_id) return s;
+    if (s?.session_id && (s.slot ?? 'worker') === slot) return s;
   }
   return null;
 }
@@ -174,10 +176,6 @@ export function createCard(board, spec) {
     const arc = spec.subtaskOf ? getTask(db, spec.subtaskOf) : null;
     if (spec.subtaskOf && !arc) throw new Error(`no card ${spec.subtaskOf} to be a subtask of`);
     if (arc?.subtask_of) throw new Error(`${arc.id} is itself a subtask of ${arc.subtask_of}; a subtask belongs to an arc`);
-    let status = 'ready';
-    if (initial === 'blocked') status = 'blocked';
-    else if (spec.triage) status = 'triage';
-    else if (parents.some((p) => !['done', 'archived'].includes(one(db, 'SELECT status FROM tasks WHERE id = ?', p).status))) status = 'todo';
     let id = newTaskId();
     while (one(db, 'SELECT 1 FROM tasks WHERE id = ?', id)) id = newTaskId();
     // a project (Hermes's projects registry, `projects.db` in the home) anchors the card's worktree in its repository
@@ -196,13 +194,17 @@ export function createCard(board, spec) {
                tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id,
                project_id, goal_mode, goal_max_turns)
              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-      id, title, spec.body ?? null, spec.assignee || null, status, Number(spec.priority) || 0, spec.createdBy ?? 'user', t, ws.kind, ws.path,
+      id, title, spec.body ?? null, spec.assignee || null, 'todo', Number(spec.priority) || 0, spec.createdBy ?? 'user', t, ws.kind, ws.path,
       spec.branch ?? null, spec.tenant ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
       spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
     const machine = spec.machine ?? arc?.machine ?? null;
     if (machine || arc) run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id, machine, subtask_of) VALUES (?, ?, ?)', id, machine, arc?.id ?? null);
     for (const p of parents) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', p, id);
+    // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
+    const entry = workflowFor(board.root);
+    const status = initialStatus(db, board, entry, getTask(db, id), { triage: Boolean(spec.triage), initial_status: initial });
+    setStatus(db, entry.workflow, id, status);
     event(db, id, 'created', { assignee: spec.assignee || null, status, parents, tenant: spec.tenant ?? null, ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
     if (parents.length) inheritSubscriptions(db, id, parents);
     if (arc) {
@@ -228,58 +230,18 @@ function wouldCycle(db, parent, child) {
   return false;
 }
 
-/** `child` waits for `parent`: a ready child goes back to todo while the parent is not done. */
-export function link(board, parent, child) {
-  if (parent === child) throw new Error('a card cannot depend on itself');
-  return tx(board, (db) => {
-    must(db, parent); must(db, child);
-    if (wouldCycle(db, parent, child)) throw new Error(`linking ${parent} -> ${child} would make a cycle`);
-    run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', parent, child);
-    if (one(db, 'SELECT status FROM tasks WHERE id = ?', parent).status !== 'done') run(db, "UPDATE tasks SET status = 'todo' WHERE id = ? AND status = 'ready'", child);
-    event(db, child, 'linked', { parent, child });
-    inheritSubscriptions(db, child, [parent]);
-  });
-}
 
-export function unlink(board, parent, child) {
-  return tx(board, (db) => {
-    const r = run(db, 'DELETE FROM task_links WHERE parent_id = ? AND child_id = ?', parent, child);
-    if (!r.changes) return false;
-    event(db, child, 'unlinked', { parent, child });
-    recomputeIn(db);
-    return true;
-  });
-}
 
 // ------------------------------------------------------------------ the thread and the card's fields
 
-export function comment(board, id, author, body) {
-  if (!String(body ?? '').trim()) throw new Error('a comment has a body');
-  if (!String(author ?? '').trim()) throw new Error('a comment has an author');
-  return tx(board, (db) => {
-    must(db, id);
-    const r = run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', id, author.trim(), body.trim(), now());
-    event(db, id, 'commented', { author: author.trim(), len: body.length });
-    return Number(r.lastInsertRowid);
-  });
-}
 
-/** A new assignee (profile). A running card is reclaimed first, on purpose, never moved under its session. */
-export function assign(board, id, profile) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status === 'running' && task.claim_lock) throw new Error(`${id} is running; reclaim it before reassigning`);
-    run(db, `UPDATE tasks SET assignee = ?${task.assignee !== (profile || null) ? ', consecutive_failures = 0, last_failure_error = NULL' : ''} WHERE id = ?`, profile || null, id);
-    event(db, id, 'assigned', { assignee: profile || null });
-  });
-}
 
 /** The machine a card's session runs on. Moving it is a decision: a running card is reclaimed first. */
 export function setMachine(board, id, machine) {
   return tx(board, (db) => {
     const task = must(db, id);
     if (task.status === 'running' && task.claim_lock) throw new Error(`${id} is running on ${task.machine}; reclaim it before moving it`);
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id, machine) VALUES (?, ?)', id, machine || null);
+    run(db, 'INSERT INTO supercode_cards (task_id, machine) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET machine = excluded.machine', id, machine || null);
     event(db, id, 'machine_set', { machine: machine || null, was: task.machine });
   });
 }
@@ -355,10 +317,6 @@ export function recordFailure(db, id, error, { failureLimit = DEFAULT_FAILURE_LI
   return true;
 }
 
-export function complete(board, id, opts = {}) {
-  completeIn(board, id, opts);
-  cleanupWorkspace(board, id);
-}
 
 /**
  * A completed card's workspace goes, as Hermes cleans up on completion: a scratch directory under the board's own
@@ -374,197 +332,171 @@ function cleanupWorkspace(board, id) {
   if (resolve(task.workspace_path).startsWith(`${managed}/`)) rmSync(task.workspace_path, { recursive: true, force: true });
 }
 
-function completeIn(board, id, { result = null, summary = null, metadata = null } = {}) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (!parentsDone(db, id)) throw new Error(`${id} waits on parents that are not done`);
-    if (!['running', 'ready', 'blocked', 'review'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a running, ready, blocked or review card completes`);
-    run(db, "UPDATE tasks SET status = 'done', result = ?, completed_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, block_kind = NULL, block_recurrences = 0, consecutive_failures = 0, last_failure_error = NULL WHERE id = ?",
-      result, now(), id);
-    const said = summary ?? result;
-    let runId = endRun(db, id, { outcome: 'completed', status: 'done', summary: said, metadata: metadata ?? undefined });
-    if (runId === null && (said || metadata || task.status === 'review')) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said ?? (task.status === 'review' ? 'Review approved without additional evidence.' : null), metadata });
-    const first = String(said ?? '').trim().split('\n')[0].slice(0, 400);
-    const artifacts = Array.isArray(metadata?.artifacts) ? metadata.artifacts.filter((a) => typeof a === 'string' && a.trim()) : [];
-    event(db, id, 'completed', { result_len: result ? result.length : 0, summary: first || null, ...(artifacts.length ? { artifacts } : {}) }, runId);
-    // card ids the handoff names that no card has (Hermes flags them the same way)
-    const named = [...new Set(`${summary ?? ''} ${result ?? ''}`.match(/\bt_[a-f0-9]{8,}\b/g) ?? [])];
-    const phantom = named.filter((t) => !one(db, 'SELECT 1 FROM tasks WHERE id = ?', t));
-    if (phantom.length) event(db, id, 'suspected_hallucinated_references', { phantom_refs: phantom, source: 'completion_summary' }, runId);
-    recomputeIn(db);
-  });
-}
 
-export function block(board, id, { reason = null, kind = null } = {}) {
-  return tx(board, (db) => blockIn(db, id, { reason, kind }));
-}
 
-/** `block` inside the caller's transaction (the dispatcher's own blocks keep the same recurrence accounting). */
-export function blockIn(db, id, { reason = null, kind = null } = {}) {
-  if (kind && !BLOCK_KINDS.includes(kind)) throw new Error(`block kind is one of ${BLOCK_KINDS.join(', ')}`);
-  const task = must(db, id);
-  if (!['running', 'ready'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a running or ready card blocks`);
-  const source = task.status === 'running' ? retryStatus(db, id) : 'ready';
-  if (kind === 'dependency') {
-    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, block_kind = ? WHERE id = ?", kind, id);
-    const runId = endRun(db, id, { outcome: 'blocked', summary: reason }) ?? (reason ? synthesizeRun(db, id, { outcome: 'blocked', summary: reason }) : null);
-    event(db, id, 'dependency_wait', { reason, kind, source_status: source }, runId);
-    return 'todo';
-  }
-  const recurrences = task.block_kind === kind ? Number(task.block_recurrences || 0) + 1 : 1;
-  const loop = recurrences >= BLOCK_RECURRENCE_LIMIT;
-  const status = loop ? 'triage' : 'blocked';
-  run(db, 'UPDATE tasks SET status = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, block_kind = ?, block_recurrences = ? WHERE id = ?', status, kind, recurrences, id);
-  const runId = endRun(db, id, { outcome: 'blocked', summary: reason }) ?? (reason ? synthesizeRun(db, id, { outcome: 'blocked', summary: reason }) : null);
-  event(db, id, loop ? 'block_loop_detected' : 'blocked', { reason, kind, recurrences, ...(loop ? { limit: BLOCK_RECURRENCE_LIMIT } : {}), source_status: source }, runId);
-  return status;
-}
 
-export function unblock(board, id) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (!['blocked', 'scheduled'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a blocked or scheduled card unblocks`);
-    const resume = task.status === 'blocked' ? resumeStatus(db, id) : 'ready';
-    if (task.current_run_id) run(db, "UPDATE task_runs SET status = 'reclaimed', outcome = 'reclaimed', summary = COALESCE(summary, 'invariant recovery on unblock'), ended_at = ? WHERE id = ? AND ended_at IS NULL", now(), task.current_run_id);
-    const landing = parentsDone(db, id) ? 'ready' : 'todo';
-    const status = landing === 'ready' && resume === 'review' ? 'review' : landing;
-    run(db, 'UPDATE tasks SET status = ?, current_run_id = NULL, consecutive_failures = 0, last_failure_error = NULL WHERE id = ?', status, id);
-    event(db, id, 'unblocked', status !== 'ready' || resume !== 'ready' ? { status, resume_status: resume } : null);
-    return status;
-  });
-}
 
-/** Implementation done, awaiting review (not a block): the review lane, optionally under a reviewer profile. */
-export function requestReview(board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null } = {}) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (!parentsDone(db, id)) throw new Error(`${id} waits on parents that are not done`);
-    if (!['running', 'ready'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a running or ready card goes to review`);
-    // a live claim is its worker's to hand off; anyone else says so on purpose (Hermes's guard)
-    // (Hermes's expected_run_id: the worker names the run it holds; a superseded run changes nothing)
-    if (expectedRunId !== null && Number(task.current_run_id) !== Number(expectedRunId)) throw new Error(`run ${expectedRunId} of ${id} is no longer its current run; nothing was changed`);
-    if (task.status === 'running' && task.claim_lock && !force && expectedRunId === null) throw new Error(`${id} is running under a live claim; its worker requests review, or pass --force to override on purpose`);
-    // a re-review goes back to the reviewer who asked for the changes
-    if (!reviewer) {
-      const changed = one(db, "SELECT id FROM task_runs WHERE task_id = ? AND outcome = 'changes_requested' ORDER BY id DESC LIMIT 1", id);
-      if (changed) {
-        const asked = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND run_id = ? AND kind = 'changes_requested' ORDER BY id DESC LIMIT 1", id, changed.id)?.payload, {}) ?? {};
-        if (!asked.reviewer) throw new Error(`${id}'s last changes request names no reviewer; pass --reviewer`);
-        reviewer = asked.reviewer;
-      }
-    }
-    run(db, `UPDATE tasks SET status = 'review', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL${reviewer ? ', assignee = ?' : ''} WHERE id = ?`, ...(reviewer ? [reviewer, id] : [id]));
-    const runId = endRun(db, id, { outcome: 'review_requested', status: 'review', summary, metadata: metadata ?? undefined }) ?? (summary || metadata ? synthesizeRun(db, id, { outcome: 'review_requested', summary, metadata }) : null);
-    event(db, id, 'review_requested', { summary: String(summary ?? '').trim().split('\n')[0].slice(0, 400) || null, implementer: task.assignee, reviewer }, runId);
-  });
-}
 
-/** A reviewer's verdict sending the card back to its implementer. */
-export function requestChanges(board, id, { reason = null, reviewer = null, implementer = null } = {}) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status !== 'review' && !(task.status === 'running' && retryStatus(db, id) === 'review')) throw new Error(`${id} is not in review`);
-    // back to the implementer the review request recorded, not to the reviewer now holding it
-    const asked = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", id)?.payload, {}) ?? {};
-    const back = implementer ?? asked.implementer ?? task.assignee;
-    run(db, "UPDATE tasks SET status = ?, assignee = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", parentsDone(db, id) ? 'ready' : 'todo', back, id);
-    const runId = endRun(db, id, { outcome: 'changes_requested', summary: reason });
-    event(db, id, 'changes_requested', { reason, reviewer, implementer: back }, runId);
-  });
-}
+
+
+
+
+
+
+
+// ------------------------------------------------------------------ events through the workflow
 
 /**
- * A done (or archived) card reopened: back to ready (todo while a parent is open), and every descendant that had moved on
- * because of it pulled back to todo (Hermes's dashboard reopen, `invalidate_descendants_for_parent_reopen`).
+ * Send card `id` the event `name` (the board's workflow decides what it does: `workflow.mjs`), then settle the cards
+ * that wait on it (Hermes's recompute_ready) and run what the move asked for once it is committed. `roles` are who
+ * sends it: `manager` for a person or the fleet's manager at the CLI, the card's own role for its session,
+ * `platform` for the dispatcher. Answers `{ from, to, moved }`; throws the workflow's refusal.
  */
-export function reopen(board, id, { author = 'user', reason = null } = {}) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (!['done', 'archived'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a done or archived card is reopened`);
-    const status = parentsDone(db, id) ? 'ready' : 'todo';
-    run(db, 'UPDATE tasks SET status = ?, completed_at = NULL WHERE id = ?', status, id);
-    event(db, id, 'status', { status, reason: reason ?? 'reopened', previous_status: task.status });
-    const invalidated = [];
-    const t = now();
-    const rows = all(db, `WITH RECURSIVE d(id) AS (SELECT child_id FROM task_links WHERE parent_id = ? UNION SELECT l.child_id FROM task_links l JOIN d ON d.id = l.parent_id)
-                          SELECT t.id, t.status FROM d JOIN tasks t ON t.id = d.id ORDER BY t.id`, id);
-    for (const row of rows) {
-      if (!['ready', 'review', 'running', 'done'].includes(row.status)) continue;
-      const resume = row.status === 'review' ? 'review' : row.status === 'running' ? retryStatus(db, row.id) : 'ready';
-      const runId = row.status === 'running' ? endRun(db, row.id, { outcome: 'reclaimed', status: 'todo', summary: `ancestor ${id} reopened` }) : null;
-      run(db, "UPDATE tasks SET status = 'todo', completed_at = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, current_run_id = NULL, consecutive_failures = 0 WHERE id = ?", row.id);
-      event(db, row.id, 'descendant_invalidated', { ancestor: id, prior_status: row.status, new_status: 'todo', resume_status: resume }, runId);
-      event(db, row.id, 'status', { status: 'todo', reason: 'ancestor_reopened', parent: id, previous_status: row.status, resume_status: resume }, runId);
-      run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', row.id, author, `Invalidated: ancestor ${id} was reopened; retracted from '${row.status}' to 'todo' (will resume via '${resume}').`, t);
-      invalidated.push({ id: row.id, prior_status: row.status });
-    }
-    return { status, invalidated };
+// who is sending, when a caller does not say: the CLI answers with the caller's role on the card (setCaller)
+let callerRoles = () => ['manager'];
+/** How the engine learns who a caller is on a card: `fn(db, cardId)` answers the caller's roles there. */
+export function setCaller(fn) { callerRoles = fn; }
+
+export async function act(board, id, name, { roles = null, payload = {}, extra = {} } = {}) {
+  const entry = await loadWorkflow(board.root);
+  const result = tx(board, (db) => {
+    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)];
+    for (const other of new Set(around)) settle(db, board, entry, other, r.effects);
+    return r;
   });
+  await runEffects(board, result.effects);
+  return { from: result.from, to: result.to, moved: result.moved };
+}
+
+/** The I/O a committed move asked for. */
+export async function runEffects(board, effects = []) {
+  for (const e of 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);
+    else if (e.kind === 'close_session' || e.kind === 'send_to_actor') {
+      const { sessionEffect } = await import('./dispatch.mjs');
+      await sessionEffect(board, e);
+    }
+  }
 }
 
-export function schedule(board, id, reason = null) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (!['todo', 'ready', 'running', 'blocked'].includes(task.status)) throw new Error(`${id} is ${task.status}; it cannot be scheduled`);
-    run(db, "UPDATE tasks SET status = 'scheduled', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
-    const runId = endRun(db, id, { outcome: 'scheduled', summary: reason }) ?? (reason ? synthesizeRun(db, id, { outcome: 'scheduled', summary: reason }) : null);
-    event(db, id, 'scheduled', { reason }, runId);
-  });
+// a run taken back stops its one-shot worker on this host (Hermes's _terminate_reclaimed_worker); a pane session is
+// a person-visible session and is never killed from the board
+function stopWorker(board, runId) {
+  if (!runId) return;
+  const row = tx(board, (db) => one(db, 'SELECT metadata, claim_lock FROM task_runs WHERE id = ?', runId));
+  const worker = json(row?.metadata, {})?.supercode;
+  if (worker?.surface === 'headless' && worker.pid) terminate(Number(worker.pid));
 }
 
-export function promote(board, id, { actor = 'user', reason = null, force = false } = {}) {
+/** Every card whose workflow status has an `always` move that holds takes it (the tick's recompute). Answers how many moved. */
+export function recomputeReady(board) {
+  const entry = workflowFor(board.root);
   return tx(board, (db) => {
-    const task = must(db, id);
-    if (!['todo', 'blocked'].includes(task.status)) throw new Error(`${id} is ${task.status}; promote moves a todo or blocked card`);
-    const open = parentsOf(db, id).filter((p) => !['done', 'archived'].includes(p.status)).map((p) => p.id);
-    if (open.length && !force) throw new Error(`parents not done: ${open.join(', ')} (force to override)`);
-    run(db, "UPDATE tasks SET status = 'ready' WHERE id = ?", id);
-    event(db, id, 'promoted_manual', { actor, reason, forced: force });
+    let moved = 0;
+    for (const { id } of all(db, "SELECT id FROM tasks WHERE status NOT IN ('done', 'archived')")) {
+      const before = statusOf(db, getTask(db, id));
+      settle(db, board, entry, id);
+      if (statusOf(db, getTask(db, id)) !== before) moved += 1;
+    }
+    return moved;
   });
 }
 
-/** Release a running card's claim by hand (its session is left alone); failures are forgiven. */
-export function reclaim(board, id, reason = null) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status !== 'running') throw new Error(`${id} is ${task.status}, not running`);
-    release(db, id, { outcome: 'reclaimed', error: reason ? `manual_reclaim: ${reason}` : 'manual_reclaim', payload: { manual: true, reason, prev_lock: task.claim_lock } });
-    run(db, 'UPDATE tasks SET consecutive_failures = 0, last_failure_error = NULL WHERE id = ?', id);
-  });
+// Hermes's invalidate_descendants_for_parent_reopen: every descendant that moved on because of the reopened card
+// is pulled back to todo, its run ended, a comment saying why
+function invalidateDescendants(db, board, id) {
+  const { workflow } = workflowFor(board.root);
+  const t = now();
+  const rows = all(db, `WITH RECURSIVE d(id) AS (SELECT child_id FROM task_links WHERE parent_id = ? UNION SELECT l.child_id FROM task_links l JOIN d ON d.id = l.parent_id)
+                        SELECT t.id, t.status FROM d JOIN tasks t ON t.id = d.id ORDER BY t.id`, id);
+  const out = [];
+  for (const row of rows) {
+    if (!['ready', 'review', 'running', 'done'].includes(row.status)) continue;
+    const resume = row.status === 'review' ? 'review' : row.status === 'running' ? retryStatus(db, row.id) : 'ready';
+    const runId = row.status === 'running' ? endRun(db, row.id, { outcome: 'reclaimed', status: 'todo', summary: `ancestor ${id} reopened` }) : null;
+    run(db, 'UPDATE tasks SET completed_at = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, current_run_id = NULL, consecutive_failures = 0 WHERE id = ?', row.id);
+    setStatus(db, workflow, row.id, 'todo');
+    event(db, row.id, 'descendant_invalidated', { ancestor: id, prior_status: row.status, new_status: 'todo', resume_status: resume }, runId);
+    event(db, row.id, 'status', { status: 'todo', reason: 'ancestor_reopened', parent: id, previous_status: row.status, resume_status: resume }, runId);
+    run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', row.id, 'workflow', `Invalidated: ancestor ${id} was reopened; retracted from '${row.status}' to 'todo' (will resume via '${resume}').`, t);
+    out.push({ id: row.id, prior_status: row.status });
+  }
+  return out;
 }
 
-export function archive(board, id) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status === 'archived') return false;
-    run(db, "UPDATE tasks SET status = 'archived', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
-    const runId = endRun(db, id, { outcome: 'reclaimed', summary: 'task archived with run still active' });
-    event(db, id, 'archived', null, runId);
-    recomputeIn(db);
-    return true;
+// each of Hermes's verbs is an event of the workflow; the words it takes are the event's payload
+
+export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null } = {}) =>
+  act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId } });
+export const block = (board, id, { reason = null, kind = null, roles, runId = null } = {}) => {
+  if (kind && !BLOCK_KINDS.includes(kind)) throw new Error(`block kind is one of ${BLOCK_KINDS.join(', ')}`);
+  return act(board, id, 'block', { roles, payload: { reason, kind, run_id: runId } });
+};
+export const unblock = (board, id, { reason = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason } });
+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 } });
+export const reopen = (board, id, { author = 'user', reason = null, roles } = {}) => act(board, id, 'reopen', { roles, payload: { author, reason } });
+export const reopenReview = (board, id, { roles } = {}) => act(board, id, 'reopen_review', { roles });
+export const schedule = (board, id, reason = null, { roles } = {}) => act(board, id, 'schedule', { roles, payload: { reason } });
+export const promote = (board, id, { actor = 'user', reason = null, force = false, roles } = {}) => act(board, id, 'promote', { roles, payload: { actor, reason, force } });
+export const reclaim = (board, id, reason = null, { roles } = {}) => act(board, id, 'reclaim', { roles, payload: { reason } });
+export const archive = (board, id, { roles } = {}) => act(board, id, 'archive', { roles });
+export const specify = (board, id, { title = null, body = null, author = 'user', roles } = {}) => act(board, id, 'specify', { roles, payload: { title, body, author } });
+export const editResult = (board, id, { result, summary = null, metadata = undefined, roles } = {}) => act(board, id, 'edit', { roles, payload: { result, summary, metadata } });
+export const heartbeat = (board, id, note = null, { roles } = {}) => act(board, id, 'heartbeat', { roles, payload: { note } });
+export const setModel = (board, id, model = null, provider = null, { roles } = {}) => {
+  if (provider && !model) throw new Error('a provider needs a model');
+  return act(board, id, 'set_model', { roles, payload: { model: model || null, provider: provider || null } });
+};
+export const setGoal = (board, id, { on = true, maxTurns = null, roles } = {}) => act(board, id, 'set_goal', { roles, payload: { goal: Boolean(on), max_turns: on ? maxTurns : null } });
+export const assign = (board, id, profile, { roles } = {}) => act(board, id, 'assign', { roles, payload: { assignee: profile || null } });
+
+/** A triage card fans out into children it waits on (Hermes's decomposer); answers their ids. */
+export async function decompose(board, id, children, { author = 'user', roles } = {}) {
+  if (!children.length) throw new Error('decompose names at least one child (--child "<title>[@<assignee>]")');
+  const task = tx(board, (db) => must(db, id));
+  const ids = children.map((c) => createCard(board, {
+    title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
+    workspace: task.workspace_path ? `${task.workspace_kind}:${task.workspace_path}` : task.workspace_kind, tenant: task.tenant, createdBy: author,
+  }).id);
+  await act(board, id, 'decompose', { roles, payload: { children: ids, author } });
+  return ids;
+}
+
+/** `child` waits for `parent`. */
+export function link(board, parent, child, { roles } = {}) {
+  if (parent === child) throw new Error('a card cannot depend on itself');
+  tx(board, (db) => {
+    must(db, parent); must(db, child);
+    if (wouldCycle(db, parent, child)) throw new Error(`linking ${parent} -> ${child} would make a cycle`);
+    inheritSubscriptions(db, child, [parent]);
   });
+  return act(board, child, 'link', { roles, payload: { parent, child } });
 }
 
-/** Every todo (and non-sticky blocked) card whose parents are all done becomes ready. Answers how many. */
-export function recomputeReady(board, failureLimit = DEFAULT_FAILURE_LIMIT) {
-  return tx(board, (db) => recomputeIn(db, failureLimit));
+export async function unlink(board, parent, child, { roles } = {}) {
+  const linked = tx(board, (db) => one(db, 'SELECT 1 FROM task_links WHERE parent_id = ? AND child_id = ?', parent, child));
+  if (!linked) return false;
+  await act(board, child, 'unlink', { roles, payload: { parent, child } });
+  return true;
 }
 
-function recomputeIn(db, failureLimit = DEFAULT_FAILURE_LIMIT) {
-  let promoted = 0;
-  for (const row of all(db, "SELECT id, status, consecutive_failures, max_retries FROM tasks WHERE status IN ('todo', 'blocked')")) {
-    if (row.status === 'blocked') {
-      const last = one(db, "SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked') ORDER BY id DESC LIMIT 1", row.id);
-      if (last?.kind === 'blocked') continue; // a person's block stays until a person unblocks it
-      if (Number(row.consecutive_failures || 0) >= (row.max_retries ?? failureLimit)) continue;
-    }
-    if (!parentsDone(db, row.id)) continue;
-    const status = resumeStatus(db, row.id);
-    run(db, 'UPDATE tasks SET status = ? WHERE id = ? AND status = ?', status, row.id, row.status);
-    event(db, row.id, 'promoted', status !== 'ready' ? { status } : null);
-    promoted += 1;
-  }
-  return promoted;
+/** A comment on the card's thread; answers its id. */
+export async function comment(board, id, author, body, { roles } = {}) {
+  if (!String(body ?? '').trim()) throw new Error('a comment has a body');
+  if (!String(author ?? '').trim()) throw new Error('a comment has an author');
+  const commentId = tx(board, (db) => {
+    must(db, id);
+    return Number(run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', id, author.trim(), body.trim(), now()).lastInsertRowid);
+  });
+  await act(board, id, 'comment', { roles, payload: { author: author.trim(), body } });
+  return commentId;
 }
 
 // ------------------------------------------------------------------ subscriptions
@@ -663,40 +595,7 @@ export function cardContext(db, id) {
 
 // ------------------------------------------------------------------ the rest of Hermes's verbs
 
-/** A triage card gets its spec (a tightened title and a body) and waits in todo for its parents, as Hermes's specifier leaves it. */
-export function specify(board, id, { title = null, body = null, author = 'user' } = {}) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status !== 'triage' && task.status !== 'running') throw new Error(`${id} is ${task.status}; only a triage card is specified`);
-    if (title && String(title).trim()) run(db, 'UPDATE tasks SET title = ? WHERE id = ?', String(title).trim(), id);
-    if (body !== null) run(db, 'UPDATE tasks SET body = ? WHERE id = ?', body, id);
-    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
-    const runId = endRun(db, id, { outcome: 'specified', summary: 'specified' });
-    event(db, id, 'specified', { author, title_changed: Boolean(title), body_len: body ? body.length : 0 }, runId);
-    recomputeIn(db);
-  });
-}
 
-/**
- * A triage card fans out into children it waits on (Hermes's decomposer: the root stays and is the child of every
- * leaf, so it wakes when the graph is done). `children` are `{ title, body?, assignee? }`; answers their ids.
- */
-export function decompose(board, id, children, { author = 'user' } = {}) {
-  if (!children.length) throw new Error('decompose names at least one child (--child "<title>[@<assignee>]")');
-  const task = tx(board, (db) => must(db, id));
-  if (task.status !== 'triage' && task.status !== 'running') throw new Error(`${id} is ${task.status}; only a triage card is decomposed`);
-  const ids = children.map((c) => createCard(board, {
-    title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
-    workspace: task.workspace_path ? `${task.workspace_kind}:${task.workspace_path}` : task.workspace_kind, tenant: task.tenant, createdBy: author,
-  }).id);
-  tx(board, (db) => {
-    for (const child of ids) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', child, id);
-    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
-    const runId = endRun(db, id, { outcome: 'decomposed', summary: `decomposed into ${ids.join(', ')}` });
-    event(db, id, 'decomposed', { children: ids, author }, runId);
-  });
-  return ids;
-}
 
 /** Hermes's swarm: a completed root as the shared blackboard, workers after it, a verifier after them all, a synthesizer last. */
 export function swarm(board, { goal, workers, verifier, synthesizer, tenant = null, createdBy = 'swarm-orchestrator', priority = 0, idempotencyKey = null }) {
@@ -717,68 +616,10 @@ export function swarm(board, { goal, workers, verifier, synthesizer, tenant = nu
   return { root_id: root.id, worker_ids: workerIds, verifier_id: verifierId, synthesizer_id: synthesizerId };
 }
 
-/** Hermes's `edit`: correct a done card's result (and its completed run's summary and metadata). */
-export function editResult(board, id, { result, summary = null, metadata = undefined }) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status !== 'done') throw new Error(`${id} is ${task.status}; edit corrects a done card's result`);
-    run(db, 'UPDATE tasks SET result = ? WHERE id = ?', result, id);
-    const said = summary ?? result;
-    const last = one(db, "SELECT id FROM task_runs WHERE task_id = ? AND outcome = 'completed' ORDER BY COALESCE(ended_at, started_at, 0) DESC, id DESC LIMIT 1", id);
-    let runId = last ? Number(last.id) : null;
-    if (runId === null) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said, metadata: metadata ?? null });
-    else {
-      run(db, 'UPDATE task_runs SET summary = ? WHERE id = ?', said, runId);
-      if (metadata !== undefined) run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(metadata), runId);
-    }
-    event(db, id, 'edited', { fields: ['result', 'summary', ...(metadata !== undefined ? ['metadata'] : [])], result_len: result ? result.length : 0, summary: String(said ?? '').split('\n')[0].slice(0, 400) || null }, runId);
-  });
-}
 
-/** Send a card in review back to its implementer (ready, or todo while parents are open). */
-export function reopenReview(board, id) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status !== 'review') throw new Error(`${id} is ${task.status}, not in review`);
-    const handoff = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", id)?.payload, {}) ?? {};
-    const status = parentsDone(db, id) ? 'ready' : 'todo';
-    const implementer = typeof handoff.implementer === 'string' && handoff.implementer.trim() ? handoff.implementer : null;
-    run(db, `UPDATE tasks SET status = ?, current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL${implementer ? ', assignee = ?' : ''} WHERE id = ?`, ...(implementer ? [status, implementer, id] : [status, id]));
-    event(db, id, 'review_reopened', { status, ...(implementer ? { implementer } : {}) });
-    return status;
-  });
-}
 
-/** A running card's worker says it is alive (Hermes's `heartbeat`); the dispatcher does not rely on it. */
-export function heartbeat(board, id, note = null) {
-  return tx(board, (db) => {
-    const task = must(db, id);
-    if (task.status !== 'running') throw new Error(`${id} is ${task.status}, not running`);
-    const t = now();
-    run(db, 'UPDATE tasks SET last_heartbeat_at = ? WHERE id = ?', t, id);
-    if (task.current_run_id) run(db, 'UPDATE task_runs SET last_heartbeat_at = ? WHERE id = ?', t, task.current_run_id);
-    event(db, id, 'heartbeat', note ? { note } : null, task.current_run_id);
-  });
-}
 
-/** A card's model (and provider) for its next start, or cleared. */
-export function setModel(board, id, model = null, provider = null) {
-  if (provider && !model) throw new Error('a provider needs a model');
-  return tx(board, (db) => {
-    must(db, id);
-    run(db, 'UPDATE tasks SET model_override = ?, provider_override = ? WHERE id = ?', model || null, provider || null, id);
-    event(db, id, 'model_override_set', { model: model || null, provider: provider || null });
-  });
-}
 
-/** Goal mode on a card (Hermes's goal loop, which Hermes sets only at creation): on or off, with its turn budget. */
-export function setGoal(board, id, { on = true, maxTurns = null } = {}) {
-  return tx(board, (db) => {
-    must(db, id);
-    run(db, 'UPDATE tasks SET goal_mode = ?, goal_max_turns = ? WHERE id = ?', on ? 1 : 0, on ? maxTurns : null, id);
-    event(db, id, 'goal_set', { goal_mode: Boolean(on), goal_max_turns: on ? maxTurns : null });
-  });
-}
 
 export function addAttachment(board, id, { file, name, contentType = null, author = 'user', dir }) {
   return tx(board, (db) => {