@volter/supercode-orchestrator 0.4.29 → 0.4.30

package/board/workflow.mjs

@@ -0,0 +1,442 @@
+// The board's workflow, interpreted (docs/architecture/orchestrator.md §2.9). The IR's `Orchestration.workflow`
+// (crates/interchange/src/orchestration/workflow.rs; Hermes's dispatcher, hermes.workflow.yaml, when a home declares
+// none) says every status a card can be in, what runs there, which events move a card and who may send them, what
+// must hold and what happens; this module applies it to the board file and keeps no rule of its own. Its actions are
+// the engine's primitives (the rows Hermes's tables hold); the I/O an action asks for (stopping a worker, closing a
+// pane, sending a session a message, cleaning a workspace) is answered as effects the caller runs after commit.
+import { event as record, json, now } from './store.mjs';
+import { evaluate, holds, render } from './expr.mjs';
+
+const loaded = new Map();
+
+/** Read the home's workflow through the IR (and the params its `kanban:` keys override); cached per home. */
+export async function loadWorkflow(root, { fresh = false } = {}) {
+  if (!fresh && loaded.has(root)) return loaded.get(root);
+  const { read } = await import('../orchestration.mjs');
+  const orchestration = await read(root);
+  const entry = workflowEntry(orchestration);
+  loaded.set(root, entry);
+  return entry;
+}
+
+/** The workflow entry for an orchestration value already read. */
+export function workflowEntry(orchestration) {
+  const workflow = orchestration?.workflow;
+  if (!workflow?.statuses) throw new Error('the IR this supercode answers has no board workflow (Orchestration.workflow); update supercode');
+  const kanban = orchestration.profiles?.default?.residue?.config?.kanban ?? {};
+  return { workflow, params: { ...workflow.params, ...kanban }, profiles: orchestration.profiles ?? {} };
+}
+
+/** The workflow loaded for `root` (loadWorkflow first). */
+export function workflowFor(root) {
+  const entry = loaded.get(root);
+  if (!entry) throw new Error(`the board workflow of ${root} is not loaded`);
+  return entry;
+}
+
+/** Use `entry` for `root` (a caller that read the IR itself). */
+export function useWorkflow(root, entry) {
+  loaded.set(root, entry);
+  return entry;
+}
+
+// ------------------------------------------------------------------ cards as the workflow sees them
+
+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);
+
+/** The card's workflow status: our exact name where it differs from what kanban.db stores, else the stored one. */
+export function statusOf(db, task) {
+  return one(db, 'SELECT stage FROM supercode_cards WHERE task_id = ?', task.id)?.stage ?? task.status;
+}
+
+/** What kanban.db stores for `status`. */
+export function storedAs(workflow, status) {
+  return workflow.statuses[status]?.stored_as ?? status;
+}
+
+/** Where a card interrupted in `status` resumes: its `exited` transition's unguarded target (data, not a rule here). */
+export function resumeOf(workflow, status) {
+  const exited = workflow.statuses[status]?.on?.exited ?? [];
+  const fallback = [...exited].reverse().find((t) => !t.guard && t.target && !t.target.includes('{{'));
+  return fallback?.target ?? status;
+}
+
+// a regular expression written Python's way (a leading `(?i)`), as Hermes's patterns are
+function pattern(p) {
+  const text = String(p ?? '');
+  return text.startsWith('(?i)') ? new RegExp(text.slice(4), 'i') : new RegExp(text);
+}
+
+/** The scope an expression is evaluated in: the card (with its relations), the event, params, time, extras. */
+export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}) {
+  const status = statusOf(db, task);
+  const parents = all(db, 'SELECT t.id, t.status, t.title FROM tasks t JOIN task_links l ON l.parent_id = t.id WHERE l.child_id = ?', task.id);
+  const children = all(db, 'SELECT t.id, t.status FROM tasks t JOIN task_links l ON l.child_id = t.id WHERE l.parent_id = ?', task.id);
+  const lastRun = one(db, 'SELECT * FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL ORDER BY ended_at DESC, id DESC LIMIT 1', task.id);
+  const lastCompleted = one(db, "SELECT * FROM task_runs WHERE task_id = ? AND outcome = 'completed' ORDER BY ended_at DESC LIMIT 1", task.id);
+  const asked = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", task.id)?.payload, {}) ?? {};
+  const changes = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'changes_requested' ORDER BY id DESC LIMIT 1", task.id)?.payload, {}) ?? {};
+  const interruption = json(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`, task.id)?.payload, {}) ?? {};
+  const currentRun = task.current_run_id ? one(db, 'SELECT metadata FROM task_runs WHERE id = ?', task.current_run_id) : null;
+  const session = json(currentRun?.metadata, {})?.supercode ?? {};
+  const card = {
+    ...task,
+    status,
+    stored_as: task.status,
+    board: board.slug,
+    parents,
+    children,
+    counters: { failures: Number(task.consecutive_failures || 0), block_recurrences: Number(task.block_recurrences || 0), goal_turns: Number(session.goal_turns || 0) },
+    goal_mode: Boolean(task.goal_mode),
+    implementer: asked.implementer ?? task.assignee,
+    last_reviewer: changes.reviewer ?? null,
+    arc: task.subtask_of ? one(db, 'SELECT id, status, title FROM tasks WHERE id = ?', task.subtask_of) ?? null : null,
+    queue_reason: json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'respawn_guarded' AND created_at >= ? ORDER BY id DESC LIMIT 1",
+      task.id, Number(one(db, 'SELECT since FROM supercode_cards WHERE task_id = ?', task.id)?.since ?? 0))?.payload, {})?.reason ?? null,
+    last_block_event: one(db, "SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked') ORDER BY id DESC LIMIT 1", task.id)?.kind ?? null,
+    resume_status: ['resume_status', 'retry_status', 'source_status'].some((k) => interruption[k] === 'review') ? 'review' : 'ready',
+    last_run: lastRun ?? {},
+    last_completed: lastCompleted ?? null,
+    events_since: (t, kinds = []) => all(db, `SELECT kind FROM task_events WHERE task_id = ? AND created_at >= ?${kinds.length ? ` AND kind IN (${kinds.map(() => '?').join(', ')})` : ''}`, task.id, t, ...kinds),
+    comments_since: (t) => all(db, 'SELECT author, body, created_at FROM task_comments WHERE task_id = ? AND created_at >= ?', task.id, t),
+  };
+  return {
+    card,
+    event,
+    params,
+    now: now(),
+    board: board.label ?? board.slug,
+    matches: (text, p) => (text === null || text === undefined ? false : pattern(p).test(String(text))),
+    ...extra,
+  };
+}
+
+// ------------------------------------------------------------------ events
+
+/** A template's value: literal text with `{{expr}}` parts; one whole `{{expr}}` gives the expression's own value. */
+export function templateValue(template, scope) {
+  if (typeof template !== 'string') return template;
+  const whole = /^\{\{([\s\S]+)\}\}$/.exec(template.trim());
+  return whole && !whole[1].includes('}}') ? evaluate(whole[1], scope) : render(template, scope);
+}
+
+const argsValue = (args, scope) => {
+  if (Array.isArray(args)) return args.map((a) => argsValue(a, scope));
+  if (args && typeof args === 'object') return Object.fromEntries(Object.entries(args).map(([k, v]) => [k, argsValue(v, scope)]));
+  return templateValue(args, scope);
+};
+
+/** The transitions `name` may take from `status`: the status's own, then the workflow's for every status. */
+export function transitionsFor(workflow, status, name) {
+  return [...(workflow.statuses[status]?.on?.[name] ?? []), ...(workflow.on?.[name] ?? [])];
+}
+
+/**
+ * Apply event `name` to card `id` in the caller's transaction. `roles` are who sends it (a transition with `by`
+ * takes only a sender in one of its roles; `platform` for the dispatcher's own observations). Answers
+ * `{ from, to, effects }`; throws the refusal when no transition applies or a validator fails.
+ */
+export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
+  const { workflow, params } = entry;
+  const task = cardOf(db, id);
+  const from = statusOf(db, task);
+  if (!workflow.statuses[from]) throw new Error(`${id} is ${from}, which the board's workflow does not declare`);
+  const candidates = transitionsFor(workflow, from, name);
+  if (!candidates.length) throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} does not apply there`);
+  // `sender`: the roles the event was sent with (a validator can ask who is asking)
+  const scope = scopeOf(db, board, task, { params, event: payload, extra: { lanes: lanesIn(entry), ...extra, sender: roles } });
+  const allowed = candidates.filter((t) => !t.by?.length || t.by.some((r) => roles.includes(r)));
+  if (!allowed.length) throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(candidates.flatMap((t) => t.by ?? []))].join(' or ')}`);
+  const taken = allowed.find((t) => holds(t.guard ?? null, scope));
+  if (!taken) { const none = new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} does not apply to it now`); none.noTransition = true; throw none; }
+  for (const v of taken.validate ?? []) {
+    if (!holds(v.expr, scope)) { const refusal = new Error(v.message); refusal.refusal = v.message; throw refusal; }
+  }
+  const effects = [];
+  const to = take(db, board, entry, task, from, taken, scope, effects);
+  settle(db, board, entry, id, effects);
+  return { from, to: statusOf(db, cardOf(db, id)), moved: to !== from, effects };
+}
+
+function cardOf(db, id) {
+  const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
+  if (!row) throw new Error(`no card ${id}`);
+  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 };
+}
+
+// one transition: the old status's exit actions, the move, the transition's actions, the new status's entry actions
+function take(db, board, entry, task, from, transition, scope, effects) {
+  const { workflow } = entry;
+  const target = transition.target ? String(templateValue(transition.target, scope) ?? '') : null;
+  if (target && !workflow.statuses[target]) throw new Error(`the workflow moves ${task.id} to ${target}, which it does not declare`);
+  const moves = target && target !== from;
+  const ctx = { db, board, entry, id: task.id, scope: { ...scope, before: scope.card }, from, to: target ?? from, effects, runId: task.current_run_id ?? null };
+  if (moves) for (const a of workflow.statuses[from].exit ?? []) act(ctx, a);
+  if (moves) setStatus(db, workflow, task.id, target);
+  for (const a of transition.actions ?? []) act(ctx, a);
+  if (moves) {
+    for (const a of workflow.statuses[target].entry ?? []) act(ctx, a);
+    if (workflow.statuses[target].run) effects.push({ kind: 'run', id: task.id, status: target });
+  }
+  return target ?? from;
+}
+
+/** Put the card in `status`: kanban.db holds its `stored_as`, our table the exact name where they differ. */
+export function setStatus(db, workflow, id, status) {
+  const stored = storedAs(workflow, status);
+  run(db, 'UPDATE tasks SET status = ? WHERE id = ?', stored, id);
+  run(db, `INSERT INTO supercode_cards (task_id, stage, since, after_fired) VALUES (?, ?, ?, NULL)
+           ON CONFLICT(task_id) DO UPDATE SET stage = excluded.stage, since = excluded.since, after_fired = NULL`, id, stored === status ? null : status, now());
+}
+
+/** Take every `always` transition that holds, from wherever the card is, until none does. */
+export function settle(db, board, entry, id, effects = []) {
+  const { workflow, params } = entry;
+  for (let hops = 0; hops < 16; hops += 1) {
+    const task = cardOf(db, id);
+    const from = statusOf(db, task);
+    const scope = scopeOf(db, board, task, { params, extra: { lanes: lanesIn(entry) } });
+    let t = (workflow.statuses[from]?.always ?? []).find((x) => holds(x.guard ?? null, scope));
+    if (!t) t = dueAfter(db, workflow, task, from, scope);
+    if (!t) return effects;
+    const to = take(db, board, entry, task, from, t, scope, effects);
+    if (to === from) return effects;
+  }
+  throw new Error(`${id}: the workflow's always transitions do not come to rest`);
+}
+
+// the home's lanes (profiles with a worker), for expressions that ask whether a profile can run a card
+const lanesIn = (entry) => Object.entries(entry.profiles ?? {}).filter(([, p]) => p?.worker?.harness).map(([name]) => name);
+
+// the first `after` move of the status whose time in it has passed and whose guard holds, once per entry to the status
+function dueAfter(db, workflow, task, status, scope) {
+  const moves = workflow.statuses[status]?.after ?? [];
+  if (!moves.length) return null;
+  const ours = one(db, 'SELECT since, after_fired FROM supercode_cards WHERE task_id = ?', task.id);
+  if (!ours?.since) {
+    // a card from before `since` was kept: its time in the status counts from now
+    run(db, 'INSERT INTO supercode_cards (task_id, since) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET since = excluded.since', task.id, now());
+    return null;
+  }
+  const fired = new Set(json(ours.after_fired, []) ?? []);
+  for (let i = 0; i < moves.length; i += 1) {
+    if (fired.has(i)) continue;
+    const seconds = Number(evaluate(moves[i].after, scope));
+    if (!(seconds >= 0) || now() - Number(ours.since) < seconds || !holds(moves[i].guard ?? null, scope)) continue;
+    fired.add(i);
+    run(db, 'UPDATE supercode_cards SET after_fired = ? WHERE task_id = ?', JSON.stringify([...fired]), task.id);
+    return moves[i];
+  }
+  return null;
+}
+
+/** Where a new card starts: the first `initial` transition that holds (`event` is the create's own words). */
+export function initialStatus(db, board, entry, task, event) {
+  const scope = scopeOf(db, board, task, { params: entry.params, event });
+  const t = entry.workflow.initial.find((x) => holds(x.guard ?? null, scope));
+  if (!t?.target) throw new Error('the workflow says nowhere for a new card to start');
+  return String(templateValue(t.target, scope));
+}
+
+// ------------------------------------------------------------------ actions
+
+// the task columns an `assign` may write (Hermes's table; anything else would be a typo in the workflow)
+const ASSIGNABLE = new Set(['assignee', 'block_kind', 'model_override', 'provider_override', 'goal_mode', 'goal_max_turns', 'last_failure_error', 'priority', 'title', 'body', 'result']);
+const COUNTER_COLUMNS = { failures: 'consecutive_failures', block_recurrences: 'block_recurrences' };
+
+function act(ctx, action) {
+  const [name, raw] = Object.entries(action)[0] ?? [];
+  const primitive = ACTIONS[name];
+  if (!primitive) throw new Error(`the workflow names an action the engine does not have: ${name}`);
+  const scope = { ...ctx.scope, card: scopeOf(ctx.db, ctx.board, cardOf(ctx.db, ctx.id), { params: ctx.entry.params, event: ctx.scope.event }).card };
+  primitive(ctx, argsValue(raw, scope), scope);
+}
+
+// kanban.db's event format: the payload Hermes's readers expect for each kind, built from the event, the card as it
+// was when the event arrived (`before`) and as it is now (`after`). A format, like the codec's for Hermes's files;
+// what happens is the workflow's. A kind with no entry here carries the event's own fields.
+const firstLine = (text) => String(text ?? '').trim().split('\n')[0].slice(0, 400) || null;
+const FORMAT = {
+  completed: ({ e }) => {
+    const artifacts = Array.isArray(e.metadata?.artifacts) ? e.metadata.artifacts.filter((a) => typeof a === 'string' && a.trim()) : [];
+    return { result_len: e.result ? String(e.result).length : 0, summary: firstLine(e.summary ?? e.result), ...(artifacts.length ? { artifacts } : {}) };
+  },
+  blocked: ({ e, after, source }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), source_status: source }),
+  block_loop_detected: ({ e, after, source, params }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), limit: params.block_recurrence_limit, source_status: source }),
+  dependency_wait: ({ e, source }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, source_status: source }),
+  review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), implementer: before.assignee, reviewer: after.assignee !== before.assignee ? after.assignee : (e.reviewer ?? null) }),
+  changes_requested: ({ e, after }) => ({ reason: e.reason ?? null, reviewer: e.reviewer ?? null, implementer: after.assignee }),
+  review_reopened: ({ after, to }) => ({ status: to, implementer: after.assignee }),
+  unblocked: ({ to }) => (to !== 'ready' ? { status: to, resume_status: to } : null),
+  gave_up: ({ e, after, params, outcome }) => ({ error: String(e.error ?? '').slice(0, 500) || null, failures: Number(after.consecutive_failures || 0), limit: after.max_retries ?? params.failure_limit, outcome }),
+  promoted_manual: ({ e }) => ({ actor: e.actor ?? 'user', reason: e.reason ?? null, forced: Boolean(e.force) }),
+  promoted: ({ to }) => (to !== 'ready' ? { status: to } : null),
+  scheduled: ({ e }) => ({ reason: e.reason ?? null }),
+  specified: ({ e }) => ({ author: e.author ?? 'user', title_changed: Boolean(e.title), body_len: e.body ? String(e.body).length : 0 }),
+  decomposed: ({ e }) => ({ children: e.children ?? [], author: e.author ?? 'user' }),
+  edited: ({ e }) => ({ fields: ['result', 'summary', ...(e.metadata !== undefined ? ['metadata'] : [])], result_len: e.result ? String(e.result).length : 0, summary: firstLine(e.summary ?? e.result) }),
+  assigned: ({ after }) => ({ assignee: after.assignee ?? null }),
+  model_override_set: ({ e }) => ({ model: e.model || null, provider: e.provider || null }),
+  goal_set: ({ after }) => ({ goal_mode: Boolean(after.goal_mode), goal_max_turns: after.goal_mode ? after.goal_max_turns ?? null : null }),
+  heartbeat: ({ e }) => (e.note ? { note: e.note } : null),
+  commented: ({ e }) => ({ author: String(e.author ?? 'user').trim(), len: String(e.body ?? '').length }),
+  archived: () => null,
+  status: ({ e, before, to }) => ({ status: to, reason: e.reason ?? 'reopened', previous_status: before.stored_as }),
+};
+const RETRY_KINDS = new Set(['crashed', 'timed_out', 'stale', 'rate_limited', 'session_lost', 'reclaimed', 'reconciled', 'spawn_failed']);
+
+const ACTIONS = {
+  record(ctx, args, scope) {
+    const kind = typeof args === 'string' ? args : args?.kind;
+    const given = typeof args === 'object' && args?.payload ? args.payload : null;
+    const after = cardOf(ctx.db, ctx.id);
+    const source = resumeOf(ctx.entry.workflow, ctx.from);
+    const e = scope.event ?? {};
+    const shape = FORMAT[kind];
+    let payload;
+    if (given) payload = given;
+    else if (shape) payload = shape({ e, before: ctx.scope.before, after, to: ctx.to, source, params: ctx.entry.params, outcome: ctx.lastOutcome ?? null });
+    else {
+      const { run_id: _r, force: _f, lock: _l, ...said } = e;
+      payload = { ...said, ...(RETRY_KINDS.has(kind) ? { retry_status: ctx.to } : { source_status: source }) };
+    }
+    record(ctx.db, ctx.id, kind, payload && Object.keys(payload).length ? payload : null, ctx.runId);
+  },
+  assign(ctx, { field, value }) {
+    if (!ASSIGNABLE.has(field)) throw new Error(`the workflow assigns ${field}, which is not a card field it may set`);
+    run(ctx.db, `UPDATE tasks SET ${field} = ? WHERE id = ?`, typeof value === 'boolean' ? Number(value) : value ?? null, ctx.id);
+  },
+  count(ctx, counter) {
+    const column = COUNTER_COLUMNS[counter];
+    if (column) {
+      run(ctx.db, `UPDATE tasks SET ${column} = ${column} + 1 WHERE id = ?`, ctx.id);
+      if (counter === 'failures' && ctx.scope.event?.error) run(ctx.db, 'UPDATE tasks SET last_failure_error = ? WHERE id = ?', String(ctx.scope.event.error).slice(0, 500), ctx.id);
+      return;
+    }
+    // a counter of the run's own (the goal loop's turns), kept with the session the dispatcher recorded
+    runSession(ctx, (s) => ({ ...s, [counter]: Number(s[counter] ?? 0) + 1 }));
+  },
+  reset(ctx, counters) {
+    for (const counter of [counters].flat()) {
+      const column = COUNTER_COLUMNS[counter];
+      if (column) run(ctx.db, `UPDATE tasks SET ${column} = 0 WHERE id = ?`, ctx.id);
+      else runSession(ctx, (s) => ({ ...s, [counter]: 0 }));
+    }
+  },
+  end_run(ctx, { outcome, summary = null, error = null } = {}) {
+    const row = one(ctx.db, 'SELECT current_run_id FROM tasks WHERE id = ?', ctx.id);
+    const t = now();
+    if (row?.current_run_id) {
+      const runId = Number(row.current_run_id);
+      run(ctx.db, `UPDATE task_runs SET status = ?, outcome = ?, summary = COALESCE(?, summary), error = COALESCE(?, error), ended_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL
+               WHERE id = ? AND ended_at IS NULL`, outcome, outcome, summary, error ?? ctx.scope.event?.error ?? null, t, runId);
+      ctx.runId = runId;
+      ctx.lastOutcome = outcome;
+      ctx.effects.push({ kind: 'run_ended', id: ctx.id, runId, outcome });
+    } else if (summary || ctx.scope.event?.metadata) {
+      // an outcome reached with no run open (a person completing a card nobody claimed)
+      const task = one(ctx.db, 'SELECT assignee FROM tasks WHERE id = ?', ctx.id);
+      const r = run(ctx.db, 'INSERT INTO task_runs (task_id, profile, status, started_at, ended_at, outcome, summary, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+        ctx.id, task?.assignee ?? null, outcome, t, t, outcome, summary, ctx.scope.event?.metadata ? JSON.stringify(ctx.scope.event.metadata) : null);
+      ctx.runId = Number(r.lastInsertRowid);
+    }
+    run(ctx.db, 'UPDATE tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?', ctx.id);
+  },
+  claim(ctx, role, scope) {
+    const task = cardOf(ctx.db, ctx.id);
+    const t = now();
+    const ttl = Number(ctx.entry.params.claim_ttl_seconds) || 900;
+    const lock = ctx.scope.event?.lock;
+    if (!lock) throw new Error('a claim needs the dispatcher\'s lock');
+    if (task.current_run_id) {
+      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;
+    const profile = evaluate(ctx.entry.workflow.roles?.[role] ?? 'card.assignee', scope) ?? task.assignee;
+    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: ctx.entry.workflow.statuses[ctx.to]?.run?.session ?? 'worker' } }));
+    ctx.runId = Number(r.lastInsertRowid);
+    run(ctx.db, 'UPDATE tasks SET current_run_id = ? WHERE id = ?', ctx.runId, ctx.id);
+    record(ctx.db, ctx.id, 'claimed', { lock, expires, run_id: ctx.runId, source_status: resumeOf(ctx.entry.workflow, ctx.to) }, ctx.runId);
+  },
+  extend_claim(ctx) {
+    const ttl = Number(ctx.entry.params.claim_ttl_seconds) || 900;
+    const expires = now() + ttl;
+    run(ctx.db, 'UPDATE tasks SET claim_expires = ?, last_heartbeat_at = ? WHERE id = ?', expires, now(), ctx.id);
+    if (ctx.runId) run(ctx.db, 'UPDATE task_runs SET claim_expires = ?, last_heartbeat_at = ? WHERE id = ?', expires, now(), ctx.runId);
+  },
+  set_result(ctx, said) {
+    const e = said ?? {};
+    const summary = e.summary ?? null;
+    run(ctx.db, 'UPDATE tasks SET result = COALESCE(?, result), completed_at = COALESCE(completed_at, ?) WHERE id = ?', e.result ?? summary ?? null, now(), ctx.id);
+    if (ctx.runId) run(ctx.db, 'UPDATE task_runs SET summary = COALESCE(?, summary), metadata = COALESCE(?, metadata) WHERE id = ?', summary, e.metadata ? JSON.stringify(e.metadata) : null, ctx.runId);
+  },
+  link(ctx, parent) {
+    run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', parent, ctx.id);
+  },
+  unlink(ctx, parent) {
+    run(ctx.db, 'DELETE FROM task_links WHERE parent_id = ? AND child_id = ?', parent, ctx.id);
+  },
+  specify(ctx, said) {
+    if (said?.title && String(said.title).trim()) run(ctx.db, 'UPDATE tasks SET title = ? WHERE id = ?', String(said.title).trim(), ctx.id);
+    if (said?.body !== undefined && said?.body !== null) run(ctx.db, 'UPDATE tasks SET body = ? WHERE id = ?', said.body, ctx.id);
+  },
+  decompose(ctx, said) {
+    // the children are filed by the caller before the event (they are cards of their own); the card waits on them
+    for (const child of said?.children ?? []) run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', child, ctx.id);
+  },
+  // card ids a handoff names that no card has (Hermes flags them the same way)
+  check_references(ctx, said) {
+    const named = [...new Set(`${said?.summary ?? ''} ${said?.result ?? ''}`.match(/\bt_[a-f0-9]{8,}\b/g) ?? [])];
+    const phantom = named.filter((t) => !one(ctx.db, 'SELECT 1 FROM tasks WHERE id = ?', t));
+    if (phantom.length) record(ctx.db, ctx.id, 'suspected_hallucinated_references', { phantom_refs: phantom, source: 'completion_summary' }, ctx.runId);
+  },
+  invalidate_descendants(ctx) {
+    ctx.effects.push({ kind: 'invalidate_descendants', id: ctx.id });
+  },
+  comment(ctx, body) {
+    run(ctx.db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', ctx.id, 'dispatcher', String(body), now());
+  },
+  cleanup_workspace(ctx) { ctx.effects.push({ kind: 'cleanup_workspace', id: ctx.id }); },
+  stop_run(ctx) { ctx.effects.push({ kind: 'stop_run', id: ctx.id, runId: ctx.runId }); },
+  close_session(ctx, slot) { ctx.effects.push({ kind: 'close_session', id: ctx.id, slot }); },
+  send_to_actor(ctx, text) { ctx.effects.push({ kind: 'send_to_actor', id: ctx.id, text }); },
+};
+
+function runSession(ctx, change) {
+  const runId = ctx.runId ?? one(ctx.db, 'SELECT current_run_id FROM tasks WHERE id = ?', ctx.id)?.current_run_id;
+  if (!runId) return;
+  const row = one(ctx.db, 'SELECT metadata FROM task_runs WHERE id = ?', runId);
+  const whole = json(row?.metadata, {}) ?? {};
+  whole.supercode = change(whole.supercode ?? {});
+  run(ctx.db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(whole), runId);
+}
+
+// ------------------------------------------------------------------ doors
+
+/**
+ * The events a sender in `role` may send a card in `status`, each as the command that sends it (`where` locates
+ * the board: `--root …` or `--at …`) and its transition's description: what a started session is told it can do.
+ */
+// the board tool a one-shot worker sends an event with (Hermes's kanban_* tools)
+const TOOL_OF = { complete: 'kanban_complete', block: 'kanban_block', request_review: 'kanban_request_review', request_changes: 'kanban_request_changes', heartbeat: 'kanban_heartbeat', comment: 'kanban_comment' };
+
+export function doors(workflow, status, role, id, where, surface = 'pane') {
+  const events = new Map();
+  for (const [name, ts] of [...Object.entries(workflow.statuses[status]?.on ?? {}), ...Object.entries(workflow.on ?? {})]) {
+    for (const t of ts) {
+      if (!t.by?.length || !t.by.includes(role)) continue;
+      if (!events.has(name)) events.set(name, t.description ?? null);
+    }
+  }
+  if (!events.size) return '';
+  const lines = [...events].filter(([name]) => surface === 'pane' || TOOL_OF[name])
+    .map(([name, what]) => (surface === 'pane' ? `- \`supercode workflow ${name.replace(/_/g, '-')} ${id} … ${where}\`` : `- \`${TOOL_OF[name]}\``) + (what ? `: ${what}` : ''));
+  return ['What you may do with the card:', ...lines].join('\n');
+}

package/board.mjs

@@ -12,6 +12,8 @@ import { fileURLToPath } from 'node:url';
 import { holdDispatcherLock } from './hermes-locks.mjs';
 import { summary } from './board/cli.mjs';
 import { notifyChats } from './board/dispatch.mjs';
+import { workflowEntry } from './board/workflow.mjs';
+import { evaluate, holds } from './board/expr.mjs';
 
 const ENTRY = fileURLToPath(new URL('./bin/orchestrator.mjs', import.meta.url));
 
@@ -31,15 +33,17 @@ function dispatchOnce(root) {
 }
 
 /** Start the board's dispatcher for the home at `root`; answers `{ tick, stop }`, or null when it does not dispatch. */
-export async function startBoard({ root, config = {}, log = () => {}, adapters = {}, wake = null }) {
-  const kanban = config.kanban ?? {};
+export async function startBoard({ root, orchestration = null, log = () => {}, adapters = {}, wake = null }) {
   const off = String(process.env.HERMES_KANBAN_DISPATCH_IN_GATEWAY ?? '').trim().toLowerCase();
   if (['0', 'false', 'no', 'off'].includes(off)) { log('info', 'board: not dispatched (HERMES_KANBAN_DISPATCH_IN_GATEWAY)'); return null; }
-  if (kanban.dispatch_in_gateway === false) { log('info', 'board: not dispatched (kanban.dispatch_in_gateway: false)'); return null; }
+  // whether and how often the served home dispatches is the board workflow's (`dispatch.serve`, `dispatch.tick`)
+  let entry;
+  try { entry = workflowEntry(orchestration); } catch (error) { log('warn', `board: not dispatched: ${error.message}`); return null; }
+  if (!holds(entry.workflow.dispatch.serve ?? null, { params: entry.params })) { log('info', 'board: not dispatched (the board workflow\'s dispatch.serve)'); return null; }
   let lock;
   try { lock = await holdDispatcherLock(root); }
   catch (error) { log('info', `board: not dispatched: ${error.message}`); return null; }
-  const seconds = Math.max(Number(kanban.dispatch_interval_seconds) || 60, 1);
+  const seconds = Math.max(Number(evaluate(entry.workflow.dispatch.tick, { params: entry.params })) || 60, 1);
   let running = false;
   let stopped = false;
   const said = new Set();

package/kanban-worker.mjs

@@ -69,7 +69,8 @@ export async function runKanbanWorker(argv, env = process.env) {
   const surfaceKey = `kanban|task|${taskId}`;
   const runEnv = { HERMES_HOME: profile.dir, ...activationEnv({ root, profile, surfaceKey, vault }), ...route.env, ...task };
   // the persona, the task protocol and the pinned skills, supercode's own (board/worker-prompt.mjs)
-  const instructions = [userHomePersona(profile), taskProtocol(taskId), pinnedSkills(profile.dir, args.skills)].filter(Boolean).join('\n\n');
+  // the board workflow's own words for this run (its status's prompt and doors), after the task protocol
+  const instructions = [userHomePersona(profile), taskProtocol(taskId), env.SUPERCODE_BOARD_PROMPT ?? '', pinnedSkills(profile.dir, args.skills)].filter(Boolean).join('\n\n');
 
   const client = new SupercodeHarnessClient(env.SUPERCODE_BIN ? { command: env.SUPERCODE_BIN } : {});
   try {

package/loop.mjs

@@ -86,7 +86,7 @@ export class Orchestrator {
     if (this.autoTick) { this.timer = setInterval(() => { this.tick().catch(() => undefined); }, TICK_MS); this.timer.unref?.(); }
     // the home's board, dispatched as a Hermes gateway dispatches it (docs/plans/hermes-compat.md row 14)
     if (this.autoTick) this.board = await startBoard({
-      root: this.state.root, config: this.state.profiles.default?.residue?.config ?? {}, log: this.log, adapters: this.adapters,
+      root: this.state.root, orchestration: this.state, log: this.log, adapters: this.adapters,
       // a board notice as a turn in the subscribed chat's own session (Hermes's wake), sent as the subscriber
       wake: (sub, text) => this.dispatchLogged(events.inbound({
         profile: sub.notifier_profile || 'default', key: { platform: sub.platform, kind: sub.chat_type || 'dm', chat_id: sub.chat_id, ...(sub.thread_id ? { thread_id: sub.thread_id } : {}) },

package/package.json

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