@volter/supercode-orchestrator 0.4.15 → 0.4.17

package/board/engine.mjs

@@ -0,0 +1,547 @@
+// The board's transitions (docs/architecture/orchestrator.md §2.9): what a card may do, written for supercode and
+// kept to Hermes Kanban's lifecycle so the two read each other's boards. Statuses: triage · todo · scheduled ·
+// ready · running · blocked · review · done · archived. A card with a parent that is not done waits in `todo`
+// and becomes `ready` when every parent is; a claim moves `ready` to `running` and opens a run; a run ends
+// completed, blocked, reclaimed, review_requested, spawn_failed, crashed or timed_out. Every change appends an
+// event (Hermes's kinds) to the card's thread, which is what subscribers are told.
+//
+// Each function takes an open board (`store.mjs`) and runs in one write transaction. Nothing here launches,
+// observes or sends: the dispatcher (`dispatch.mjs`) does, and records what it did through these.
+import { claimer, event, json, newTaskId, now, tx } from './store.mjs';
+
+export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
+export const BLOCK_KINDS = ['dependency', 'needs_input', 'capability', 'transient'];
+export const WORKSPACE_KINDS = ['scratch', 'dir', 'worktree'];
+/** A card blocked this many times in a row for the same kind goes to triage for a person (Hermes's limit). */
+export const BLOCK_RECURRENCE_LIMIT = 2;
+export const DEFAULT_FAILURE_LIMIT = 2;
+export const DEFAULT_CLAIM_TTL_SECONDS = 15 * 60;
+
+export function claimTtl(configured) {
+  const env = Number(process.env.HERMES_KANBAN_CLAIM_TTL_SECONDS);
+  const n = Number(configured) || (Number.isInteger(env) && env > 0 ? env : 0);
+  return n > 0 ? Math.floor(n) : DEFAULT_CLAIM_TTL_SECONDS;
+}
+
+const one = (db, sql, ...args) => db.prepare(sql).get(...args);
+const all = (db, sql, ...args) => db.prepare(sql).all(...args);
+const run = (db, sql, ...args) => db.prepare(sql).run(...args);
+
+export function getTask(db, id) {
+  const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
+  if (!row) return null;
+  const ours = one(db, 'SELECT machine, subtask_of FROM supercode_cards WHERE task_id = ?', id);
+  return { ...row, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
+}
+
+function must(db, id) {
+  const task = getTask(db, id);
+  if (!task) throw new Error(`no card ${id}`);
+  return task;
+}
+
+const parentsOf = (db, id) => all(db, 'SELECT t.id, t.status FROM tasks t JOIN task_links l ON l.parent_id = t.id WHERE l.child_id = ?', id);
+const childrenOf = (db, id) => all(db, 'SELECT child_id AS id FROM task_links WHERE parent_id = ?', id).map((r) => r.id);
+const parentsDone = (db, id) => parentsOf(db, id).every((p) => p.status === 'done' || p.status === 'archived');
+
+/** The workspace word Hermes's CLI takes: `scratch`, `worktree`, `worktree:<path>`, `dir:<path>`. */
+export function parseWorkspace(word = 'scratch') {
+  const [kind, ...rest] = String(word).split(':');
+  const path = rest.join(':') || null;
+  if (!WORKSPACE_KINDS.includes(kind)) throw new Error(`workspace is scratch | worktree | worktree:<path> | dir:<path>, not ${word}`);
+  if (kind === 'dir' && !path) throw new Error('a dir workspace names its path (dir:<absolute path>)');
+  if (path && !/^(\/|~|[A-Za-z]:[\\/])/.test(path)) throw new Error(`workspace path ${path} is not absolute`);
+  return { kind, path };
+}
+
+// ------------------------------------------------------------------ runs
+
+/** Close the card's open run; answers its id, or null when none was open. */
+export function endRun(db, taskId, { outcome, status = null, summary = null, error = null, metadata = undefined }) {
+  const row = one(db, 'SELECT current_run_id FROM tasks WHERE id = ?', taskId);
+  if (!row?.current_run_id) return null;
+  const runId = Number(row.current_run_id);
+  const keep = metadata === undefined ? one(db, 'SELECT metadata FROM task_runs WHERE id = ?', runId)?.metadata ?? null : (metadata ? JSON.stringify(metadata) : null);
+  run(db, `UPDATE task_runs SET status = ?, outcome = ?, summary = ?, error = ?, metadata = ?, ended_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL
+           WHERE id = ? AND ended_at IS NULL`, status ?? outcome, outcome, summary, error, keep, now(), runId);
+  run(db, 'UPDATE tasks SET current_run_id = NULL WHERE id = ?', taskId);
+  return runId;
+}
+
+/** A closed run recording an outcome reached with no run open (a person completing a card nobody claimed). */
+function synthesizeRun(db, taskId, { outcome, summary = null, metadata = null }) {
+  const task = one(db, 'SELECT assignee FROM tasks WHERE id = ?', taskId);
+  const t = now();
+  const r = run(db, 'INSERT INTO task_runs (task_id, profile, status, started_at, ended_at, outcome, summary, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    taskId, task?.assignee ?? null, outcome, t, t, outcome, summary, metadata ? JSON.stringify(metadata) : null);
+  return Number(r.lastInsertRowid);
+}
+
+export function currentRun(db, taskId) {
+  const row = one(db, 'SELECT r.* FROM task_runs r JOIN tasks t ON t.current_run_id = r.id WHERE t.id = ?', taskId);
+  return row ? { ...row, metadata: json(row.metadata, {}) ?? {} } : null;
+}
+
+/** Merge `patch` into the run's `metadata.supercode` (what the dispatcher launched and observed). */
+export function setRunSession(db, runId, session) {
+  const row = one(db, 'SELECT metadata FROM task_runs WHERE id = ?', runId);
+  const whole = json(row?.metadata, {}) ?? {};
+  whole.supercode = session;
+  run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(whole), runId);
+  return whole;
+}
+
+/** The card's latest session the dispatcher recorded, newest run first; null when it never had one. */
+export function lastSession(db, taskId) {
+  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;
+  }
+  return null;
+}
+
+/** Where an interrupted run resumes: `review` for a reviewer's run, `ready` otherwise. */
+function retryStatus(db, taskId) {
+  const row = one(db, 'SELECT current_run_id FROM tasks WHERE id = ?', taskId);
+  if (!row?.current_run_id) return 'ready';
+  const claimed = one(db, "SELECT payload FROM task_events WHERE task_id = ? AND run_id = ? AND kind = 'claimed' ORDER BY id DESC LIMIT 1", taskId, row.current_run_id);
+  return json(claimed?.payload, {})?.source_status === 'review' ? 'review' : 'ready';
+}
+
+/** The phase a card blocked out of comes back to (Hermes reads it off the latest interruption). */
+function resumeStatus(db, taskId) {
+  const row = one(db, `SELECT payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'block_loop_detected', 'dependency_wait', 'gave_up',
+    'unblocked', 'changes_requested', 'review_reopened', 'status', 'reclaimed', 'stale', 'timed_out', 'crashed', 'spawn_failed', 'rate_limited', 'session_lost')
+    ORDER BY id DESC LIMIT 1`, taskId);
+  const p = json(row?.payload, {}) ?? {};
+  return ['resume_status', 'retry_status', 'source_status'].some((k) => p[k] === 'review') ? 'review' : 'ready';
+}
+
+// ------------------------------------------------------------------ creating and linking
+
+/**
+ * A new card. `workspace` is Hermes's word (`dir:<path>` for a machine's directory); `machine` the enrolled
+ * machine its session runs on. Answers its id; with an `idempotencyKey` a live card already filed under it is
+ * answered instead.
+ */
+export function createCard(board, spec) {
+  const title = String(spec.title ?? '').trim();
+  if (!title) throw new Error('a card has a title');
+  const ws = parseWorkspace(spec.workspace ?? 'scratch');
+  if (spec.branch && ws.kind !== 'worktree') throw new Error('a branch is only for a worktree workspace');
+  const parents = [...new Set((spec.parents ?? []).filter(Boolean))];
+  const initial = spec.initialStatus ?? null;
+  if (initial && !['blocked', 'running'].includes(initial)) throw new Error('initial status is blocked or running');
+  if (spec.provider && !spec.model) throw new Error('a provider needs a model');
+  return tx(board, (db) => {
+    if (spec.idempotencyKey) {
+      const got = one(db, "SELECT id FROM tasks WHERE idempotency_key = ? AND status != 'archived' ORDER BY created_at DESC LIMIT 1", spec.idempotencyKey);
+      if (got) return { id: got.id, existing: true };
+    }
+    const missing = parents.filter((p) => !one(db, 'SELECT 1 FROM tasks WHERE id = ?', p));
+    if (missing.length) throw new Error(`unknown parent card(s): ${missing.join(', ')}`);
+    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();
+    const t = now();
+    run(db, `INSERT INTO tasks (id, title, body, assignee, status, priority, created_by, created_at, workspace_kind, workspace_path, branch_name,
+               tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      id, title, spec.body ?? null, spec.assignee || null, status, 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);
+    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);
+    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) {
+      // the arc's subscribers hear its subtasks, and the arc's session works them
+      inheritSubscriptions(db, id, [arc.id], { workers: true });
+      event(db, arc.id, 'subtask_added', { subtask: id, title });
+    }
+    if (initial === 'running') claimIn(db, id, { ttl: claimTtl() });
+    return { id, existing: false };
+  });
+}
+
+function wouldCycle(db, parent, child) {
+  const seen = new Set();
+  const stack = [child];
+  while (stack.length) {
+    const node = stack.pop();
+    if (node === parent) return true;
+    if (seen.has(node)) continue;
+    seen.add(node);
+    stack.push(...childrenOf(db, node));
+  }
+  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);
+    event(db, id, 'machine_set', { machine: machine || null, was: task.machine });
+  });
+}
+
+// ------------------------------------------------------------------ lifecycle
+
+/** Claim a ready card: running, a claim held until `ttl` from now, a run opened. Answers the run id or null. */
+export function claim(board, id, { ttl, lock = claimer(), expectStatus = 'ready' } = {}) {
+  return tx(board, (db) => claimIn(db, id, { ttl, lock, expectStatus }));
+}
+
+/** `claim` inside the caller's own transaction (a dispatcher's guard and claim see one state). */
+export function claimIn(db, id, { ttl = claimTtl(), lock = claimer(), expectStatus = null } = {}) {
+  if (!parentsDone(db, id)) {
+    run(db, "UPDATE tasks SET status = 'todo' WHERE id = ? AND status = 'ready'", id);
+    event(db, id, 'claim_rejected', { reason: 'parents_not_done' });
+    return null;
+  }
+  const task = must(db, id);
+  if (expectStatus && task.status !== expectStatus) return null;
+  if (task.claim_lock) return null;
+  const t = now();
+  if (task.current_run_id) {
+    run(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;
+  run(db, 'UPDATE tasks SET status = ?, claim_lock = ?, claim_expires = ?, started_at = COALESCE(started_at, ?) WHERE id = ?', 'running', lock, expires, t, id);
+  const r = run(db, "INSERT INTO task_runs (task_id, profile, step_key, status, claim_lock, claim_expires, max_runtime_seconds, started_at) VALUES (?, ?, ?, 'running', ?, ?, ?, ?)",
+    id, task.assignee, task.current_step_key, lock, expires, task.max_runtime_seconds, t);
+  const runId = Number(r.lastInsertRowid);
+  run(db, 'UPDATE tasks SET current_run_id = ? WHERE id = ?', runId, id);
+  event(db, id, 'claimed', { lock, expires, run_id: runId, source_status: task.status === 'review' ? 'review' : 'ready' }, runId);
+  return runId;
+}
+
+/** Extend a running card's claim (the dispatcher keeps the claim of a session it sees live). */
+export function extendClaim(db, id, { ttl, reason, extra = {} }) {
+  const task = one(db, 'SELECT claim_lock, current_run_id FROM tasks WHERE id = ? AND status = ?', id, 'running');
+  if (!task) return false;
+  const expires = now() + ttl;
+  run(db, 'UPDATE tasks SET claim_expires = ? WHERE id = ? AND status = ?', expires, id, 'running');
+  if (task.current_run_id) run(db, 'UPDATE task_runs SET claim_expires = ? WHERE id = ?', expires, task.current_run_id);
+  event(db, id, 'claim_extended', { reason, claim_expires_now: expires, ...extra }, task.current_run_id);
+  return true;
+}
+
+/** Put a running card back where its run came from, closing the run with `outcome`. Answers the closed run id. */
+export function release(db, id, { outcome = 'reclaimed', error = null, metadata = undefined, kind = 'reclaimed', payload = {} } = {}) {
+  const task = one(db, 'SELECT status, claim_lock FROM tasks WHERE id = ?', id);
+  if (!task || task.status !== 'running') return null;
+  const retry = retryStatus(db, id);
+  run(db, 'UPDATE tasks SET status = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?', retry, id);
+  const runId = endRun(db, id, { outcome, status: outcome, error, metadata });
+  event(db, id, kind, { ...payload, retry_status: retry }, runId);
+  return runId;
+}
+
+/**
+ * Count a failure against the card (Hermes's circuit breaker): at the card's `max_retries`, else `failureLimit`,
+ * consecutive failures it is blocked with a `gave_up` event. Answers true when it tripped.
+ */
+export function recordFailure(db, id, error, { failureLimit = DEFAULT_FAILURE_LIMIT, outcome = 'crashed' } = {}) {
+  const task = one(db, 'SELECT consecutive_failures, max_retries, status FROM tasks WHERE id = ?', id);
+  if (!task) return false;
+  const failures = Number(task.consecutive_failures || 0) + 1;
+  run(db, 'UPDATE tasks SET consecutive_failures = ?, last_failure_error = ? WHERE id = ?', failures, String(error).slice(0, 500), id);
+  const limit = task.max_retries ?? failureLimit;
+  if (failures < limit) return false;
+  if (task.status === 'running') endRun(db, id, { outcome, error: String(error) });
+  run(db, "UPDATE tasks SET status = 'blocked', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
+  event(db, id, 'gave_up', { error: String(error).slice(0, 500), failures, limit, outcome });
+  return true;
+}
+
+export function complete(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);
+    event(db, id, 'completed', { result_len: result ? result.length : 0, summary: first || null }, runId);
+    recomputeIn(db);
+  });
+}
+
+export function block(board, id, { reason = null, kind = null } = {}) {
+  if (kind && !BLOCK_KINDS.includes(kind)) throw new Error(`block kind is one of ${BLOCK_KINDS.join(', ')}`);
+  return tx(board, (db) => {
+    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 } = {}) {
+  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`);
+    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`);
+    const back = 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);
+  });
+}
+
+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);
+  });
+}
+
+export function promote(board, id, { actor = 'user', reason = null, force = false } = {}) {
+  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 });
+  });
+}
+
+/** 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);
+  });
+}
+
+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;
+  });
+}
+
+/** 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));
+}
+
+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;
+}
+
+// ------------------------------------------------------------------ subscriptions
+
+/**
+ * Subscribe `address` (a supercode session address) to a card's events from now on. `role` is `creator` (told of
+ * starts, completion and blocks) or `worker` (told of updates to the card it works).
+ */
+export function subscribeIn(db, id, address, role = 'creator') {
+  const cursor = one(db, 'SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?', id).c;
+  run(db, `INSERT OR IGNORE INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, chat_type, delivery_mode, delivery_metadata, created_at, last_event_id)
+           VALUES (?, 'supercode', ?, '', 'dm', 'notify', ?, ?, ?)`, id, address, JSON.stringify({ role }), now(), cursor);
+}
+
+export function subscribe(board, id, address, role = 'creator') {
+  return tx(board, (db) => { must(db, id); subscribeIn(db, id, address, role); });
+}
+
+export function unsubscribe(board, id, address) {
+  return tx(board, (db) => run(db, "DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?", id, address).changes > 0);
+}
+
+/** A child hears what its parents' subscribers hear (Hermes copies them at link time); a subtask its arc's session too. */
+function inheritSubscriptions(db, child, parents, { workers = false } = {}) {
+  const cursor = one(db, 'SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?', child).c;
+  for (const p of parents) {
+    for (const s of all(db, 'SELECT * FROM kanban_notify_subs WHERE task_id = ?', p)) {
+      const role = json(s.delivery_metadata, {})?.role;
+      if ((role === 'worker' && !workers) || role === 'dependency') continue; // a parent's session does not work the child
+      run(db, `INSERT OR IGNORE INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, user_id, user_id_alt, chat_type, notifier_profile, delivery_mode, delivery_metadata, created_at, last_event_id)
+               VALUES (?, ?, ?, ?, ?, ?, COALESCE(?, 'dm'), ?, COALESCE(?, 'notify'), ?, ?, ?)`,
+        child, s.platform, s.chat_id, s.thread_id, s.user_id, s.user_id_alt, s.chat_type, s.notifier_profile, s.delivery_mode, s.delivery_metadata, now(), cursor);
+    }
+  }
+}
+
+export const subscriptions = (db, id = null) => (id ? all(db, 'SELECT * FROM kanban_notify_subs WHERE task_id = ?', id) : all(db, 'SELECT * FROM kanban_notify_subs'))
+  .map((s) => ({ ...s, delivery_metadata: json(s.delivery_metadata, {}) ?? {} }));
+
+// ------------------------------------------------------------------ reading
+
+export function listCards(db, { status = null, assignee = null, machine = null, includeArchived = false } = {}) {
+  const rows = all(db, `SELECT t.*, c.machine, c.subtask_of FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id
+    WHERE (? IS NULL OR t.status = ?) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? OR t.status != 'archived')
+    ORDER BY t.priority DESC, t.created_at ASC`, status, status, assignee, assignee, machine, machine, includeArchived ? 1 : 0);
+  return rows.map((r) => ({ ...r, skills: json(r.skills, []) ?? [] }));
+}
+
+export function showCard(db, id) {
+  const task = must(db, id);
+  return {
+    task,
+    parents: parentsOf(db, id),
+    children: childrenOf(db, id),
+    subtasks: all(db, 'SELECT t.id, t.status, t.title FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at', id),
+    comments: all(db, 'SELECT author, body, created_at FROM task_comments WHERE task_id = ? ORDER BY id', id),
+    runs: all(db, 'SELECT * FROM task_runs WHERE task_id = ? ORDER BY id', id).map((r) => ({ ...r, metadata: json(r.metadata, null) })),
+    events: all(db, 'SELECT id, kind, payload, created_at, run_id FROM task_events WHERE task_id = ? ORDER BY id', id).map((e) => ({ ...e, payload: json(e.payload, null) })),
+    subscriptions: subscriptions(db, id),
+  };
+}
+
+const cap = (text, n) => (text && text.length > n ? `${text.slice(0, n)}… (${text.length - n} more characters)` : text);
+
+/** What a session starting on a card reads first: the card, its parents' results, earlier attempts and the thread. */
+export function cardContext(db, id) {
+  const task = must(db, id);
+  const out = [`# Card ${task.id}: ${task.title}`, ''];
+  out.push(`Status: ${task.status}. Machine: ${task.machine ?? 'unset'}. Workspace: ${task.workspace_kind}${task.workspace_path ? ` ${task.workspace_path}` : ''}.${task.subtask_of ? ` A subtask of ${task.subtask_of}.` : ''}`);
+  if (task.body) out.push('', cap(task.body, 8 * 1024));
+  const parents = all(db, 'SELECT t.id, t.title, t.result FROM tasks t JOIN task_links l ON l.parent_id = t.id WHERE l.child_id = ?', id);
+  if (parents.length) {
+    out.push('', '## Parent cards');
+    for (const p of parents) {
+      const last = one(db, "SELECT summary FROM task_runs WHERE task_id = ? AND outcome = 'completed' ORDER BY id DESC LIMIT 1", p.id);
+      out.push(`- ${p.id} ${p.title}${last?.summary || p.result ? `: ${cap(last?.summary || p.result, 4 * 1024)}` : ''}`);
+    }
+  }
+  const subtasks = all(db, 'SELECT t.id, t.status, t.title FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at', id);
+  if (subtasks.length) {
+    out.push('', '## Subtasks');
+    for (const t of subtasks) out.push(`- ${t.id} [${t.status}] ${t.title}`);
+  }
+  const runs = all(db, 'SELECT id, outcome, summary, error, started_at, ended_at FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL ORDER BY id DESC LIMIT 10', id);
+  if (runs.length) {
+    out.push('', '## Earlier attempts (newest first)');
+    for (const r of runs) out.push(`- run ${r.id}: ${r.outcome ?? 'ended'}${r.summary ? ` — ${cap(r.summary, 4 * 1024)}` : ''}${r.error ? ` (error: ${cap(r.error, 1024)})` : ''}`);
+  }
+  const comments = all(db, 'SELECT author, body FROM task_comments WHERE task_id = ? ORDER BY id DESC LIMIT 30', id).reverse();
+  if (comments.length) {
+    out.push('', '## Thread');
+    for (const c of comments) out.push(`- ${c.author}: ${cap(c.body, 2 * 1024)}`);
+  }
+  return out.join('\n');
+}