@volter/supercode-orchestrator 0.4.73 → 0.4.75

package/board/cli.mjs

@@ -30,6 +30,7 @@ Hermes Kanban's verbs, with their flags:
   comment <id> <text> [--author] [--max-len]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   complete <id>... [--result] [--summary] [--metadata JSON]   edit <id> --result [--summary] [--metadata]
   block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
+  pause <id> --reason <why>   resume <id>   cancel <id>   set-every <id> <interval|none>
   unblock <id>... [--reason]   request-review <id> [--summary] [--reviewer] [--force]   request-changes <id> <reason>   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... [--rm <id>...]
   specify <id> [--title --body] [--all]   decompose <id> [--child "<title>[@<profile>]"]... [--all]
@@ -270,7 +271,7 @@ export async function runWorkflow(argv) {
         workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
         triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: duration(args['max-runtime']),
         maxRetries, skills: args.skill, model: args.model, provider: args.provider, createdBy: args['created-by'] ?? callerName(),
-        sessionId: callerSession(), subtaskOf: args['subtask-of'] ?? null, initialStatus: args['initial-status'] ?? null,
+        every: args.every ?? null, sessionId: callerSession(), subtaskOf: args['subtask-of'] ?? null, initialStatus: args['initial-status'] ?? null,
         project: args.project ?? meta.project_id ?? null, goal: args.goal ? { maxTurns: args['goal-max-turns'] ? Number(args['goal-max-turns']) : null } : args['no-goal'] ? false : null,
       }), true);
       let answer = { id: created.id, existing: created.existing };
@@ -394,7 +395,8 @@ export async function runWorkflow(argv) {
       // the card's history, without the board's own bookkeeping (a claim, a session kept or started, a goal ask, a
       // message queued); `--all` shows every event, `--json` always does
       const PLUMBING = new Set(['claimed', 'session_started', 'session_resumed', 'session_adopted', 'session_replaced', 'session_closed',
-        'goal_set', 'goal_continued', 'decision_asked', 'board_message', 'board_message_sent', 'heartbeat', 'promoted', 'respawn_guarded']);
+        'goal_set', 'goal_continued', 'decision_asked', 'board_message', 'board_message_sent', 'heartbeat', 'promoted', 'respawn_guarded',
+        'claim_extended', 'reclaimed', 'reconciled', 'status']);
       const history = args.all ? card.events : card.events.filter((e) => !PLUMBING.has(e.kind));
       if (history.length) {
         out.push('', `Events (${history.length}${history.length < card.events.length ? ` of ${card.events.length}; --all shows every one` : ''}):`);
@@ -757,13 +759,31 @@ export async function runWorkflow(argv) {
       return report.status === 'corrupt' ? 1 : 0;
     }
 
+    case 'set-every': {
+      need(1, 'a card id');
+      await withBoardAsync((b) => engine.act(b, id, 'set_every', { payload: { every: rest[1] === 'none' ? null : rest[1] } }));
+      say(args, `${id} recurrence updated`, { ok: true }); return 0;
+    }
+    case 'cancel': {
+      need(1, 'a card id');
+      await withBoardAsync((b) => engine.act(b, id, 'cancel', { payload: { reason: args.reason ?? rest.slice(1).join(' ') } }));
+      say(args, `${id} cancelled`, { ok: true }); return 0;
+    }
     case 'pause': {
+      if (id) {
+        await withBoardAsync((b) => engine.act(b, id, 'pause', { payload: { reason: args.reason ?? rest.slice(1).join(' ') } }));
+        say(args, `${id} paused`, { ok: true }); return 0;
+      }
       // Hermes's emergency stop: new starts stop on every board of the home; running sessions go on
       writeFileSync(join(root, 'ESTOP'), `${JSON.stringify({ engaged_at: new Date().toISOString(), reason: rest.join(' ') || null })}\n`);
       say(args, `New starts paused (${join(root, 'ESTOP')}); \`supercode workflow resume\` lifts it`, { ok: true, paused: join(root, 'ESTOP') });
       return 0;
     }
     case 'resume': {
+      if (id) {
+        await withBoardAsync((b) => engine.act(b, id, 'resume'));
+        say(args, `${id} resumed`, { ok: true }); return 0;
+      }
       const lifted = [join(root, 'ESTOP'), join(process.env.HOME ?? '', '.hermes', 'ESTOP')].filter((p) => existsSync(p));
       for (const p of lifted) unlinkSync(p);
       say(args, lifted.length ? `Resumed (removed ${lifted.join(', ')})` : 'Not paused', { ok: true, lifted });
@@ -1030,7 +1050,7 @@ const READS = new Set(['list', 'ls', 'show', 'context', 'runs', 'log', 'tail', '
  * is its `implementer`; the session working a subtask's arc is `arc`; any other session is nobody on it.
  */
 function rolesFor(db, cardId, sessionId, params = {}) {
-  if (!sessionId) return ['manager'];
+  if (!sessionId) return ['manager', 'owner'];
   // a session the workflow names as the board's manager (params.managers: its addresses) is the manager on every card
   const managers = Array.isArray(params.managers) ? params.managers.map(String) : [];
   if (managers.some((m) => m === sessionId || m.endsWith(`:${sessionId}`))) return ['manager'];
@@ -1053,7 +1073,7 @@ function authorize(db, verb, rest, args, own) {
   if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
   // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
   // (what a session may do to a card is its workflow's: each transition's `by`)
-  if (['pause', 'resume', 'swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'claim', 'attach-rm'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
+  if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'claim', 'attach-rm'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
   if (args.all) refuse(`does not ${verb} every card; only its own`);
   const card = engine.getTask(db, rest[0]);
   if (!card) return; // the verb itself answers "no card"

package/board/dispatch.mjs

@@ -23,7 +23,7 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { boardPath, claimer, event, json, listBoards, logsDir, now, openBoard, setActor, tx } from './store.mjs';
 import { holdBoardTickLock } from '../hermes-locks.mjs';
-import { doors, fire, loadWorkflow, resumeOf, scopeOf, statusOf, templateValue, workflowFor } from './workflow.mjs';
+import { doors, fire, loadWorkflow, resumeOf, runSpec, transitionsFor, scopeOf, statusOf, templateValue, workflowFor } from './workflow.mjs';
 import { evaluate, holds, render } from './expr.mjs';
 import {
   cardContext, claimTtl, currentRun, DEFAULT_FAILURE_LIMIT, extendClaim, getTask, lastSession,
@@ -176,11 +176,11 @@ export function lanesOf(profiles = {}) {
 // ------------------------------------------------------------------ supervise
 
 function supervise(board, fleet, settings, report, entry, effects) {
-  const rows = board.db.prepare("SELECT id FROM tasks WHERE status = 'running'").all();
+  const rows = board.db.prepare(entry.workflow.run ? "SELECT id FROM tasks WHERE current_run_id IS NOT NULL" : "SELECT id FROM tasks WHERE status = 'running'").all();
   for (const { id } of rows) {
     tx(board, (db) => {
       const task = getTask(db, id);
-      if (task?.status !== 'running') return;
+      if (!task || (entry.workflow.run ? !task.current_run_id : task.status !== 'running')) return;
       const runRow = currentRun(db, id);
       const session = runRow?.metadata?.supercode ?? null;
       const t = now();
@@ -268,7 +268,7 @@ function limitsOf(db, board, entry, task, session) {
   const status = statusOf(db, task);
   const scope = scopeOf(db, board, task, { params: entry.params, extra: { run: { surface: session?.surface ?? null, local: true } } });
   const out = {};
-  for (const [name, expr] of Object.entries(entry.workflow.statuses[status]?.run?.limits ?? {})) {
+  for (const [name, expr] of Object.entries(runSpec(entry, status)?.limits ?? {})) {
     const v = evaluate(expr, scope);
     out[name] = v === null || v === undefined || v === '' ? null : Number(v);
   }
@@ -312,22 +312,24 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
   const d = workflow.dispatch;
   const pressure = memoryPressure();
   const tickState = { local_started: 0 };
-  const startable = new Set(Object.entries(workflow.statuses).filter(([, st]) => st.on?.[d.start]).map(([name]) => name));
+  const startable = new Set(Object.keys(workflow.statuses).filter((status) => transitionsFor(workflow, status, d.start).length));
   const everyCard = board.db.prepare("SELECT id FROM tasks WHERE status != 'archived'").all().map((r) => getTask(board.db, r.id));
   const scopeFor = (task, extra = {}) => scopeOf(board.db, board, task, { params, extra: { host: hostOf(pressure), tick: tickState, ...extra } });
   // who would run it: the role of the status its start moves it to, and that role's lane
   const planOf = (task, scope) => {
     const status = statusOf(board.db, task);
-    const t = (workflow.statuses[status]?.on?.[d.start] ?? []).find((x) => (!x.by?.length || x.by.includes('platform')) && holds(x.guard ?? null, scope));
-    if (!t?.target) return null;
-    const target = String(templateValue(t.target, scope));
-    const runSpec = workflow.statuses[target]?.run ?? null;
-    const profile = runSpec ? evaluate(workflow.roles?.[runSpec.role] ?? 'card.assignee', scope) : null;
-    return { target, runSpec, profile, lane: profile ? lanes[profile] ?? null : null };
+    const t = transitionsFor(workflow, status, d.start).find((x) => (!x.by?.length || x.by.includes('platform')) && holds(x.guard ?? null, scope));
+    if (!t) return null;
+    const target = t.target ? String(templateValue(t.target, scope)) : status;
+    const spec = runSpec(entry, target);
+    const profile = spec ? evaluate(workflow.roles?.[spec.role] ?? 'card.assignee', scope) : null;
+    return { target, runSpec: spec, profile, lane: profile ? lanes[profile] ?? null : null };
   };
   const candidates = [];
   for (const task of everyCard) {
     if (only && task.id !== only) continue;
+    const state = scopeFor(task).card;
+    if (workflow.run && (task.subtask_of || state.paused || state.archived || state.blocked_by.length || task.current_run_id || (state.every && state.next_run_at > now()))) continue;
     if (!startable.has(statusOf(board.db, task))) continue;
     const plan = planOf(task, scopeFor(task));
     if (!plan) continue;
@@ -417,7 +419,7 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
 export function launchRun(board, entry, id, lane, fleet, settings) {
   const task = getTaskNow(board, id);
   const status = tx(board, (db) => statusOf(db, task));
-  const spec = entry.workflow.statuses[status]?.run;
+  const spec = runSpec(entry, status);
   if (!spec) return null;
   const runId = task.current_run_id;
   const surface = lane.surface === 'pane' ? 'pane' : 'headless';
@@ -441,7 +443,7 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
   const fleet = observeFleet();
   const moved = tx(board, (db) => fire(db, board, entry, id, entry.workflow.dispatch.start, { roles, payload: { lock: claimer() } }));
   const task = getTaskNow(board, id);
-  const spec = entry.workflow.statuses[moved.to]?.run;
+  const spec = runSpec(entry, moved.to);
   const profile = spec ? tx(board, (db) => evaluate(entry.workflow.roles?.[spec.role] ?? 'card.assignee', scopeOf(db, board, task, { params: entry.params }))) : null;
   const lane = profile ? lanes[profile] : null;
   if (spec && !lane) throw new Error(`${id} is ${moved.to}, run by ${spec.role} (${profile ?? 'nobody'}), which is no lane of this home`);
@@ -469,11 +471,11 @@ function closeRequested(board, report) {
 
 function observeIdle(board, fleet, settings, report, entry, effects) {
   if (!fleet.ok) return;
-  for (const { id } of board.db.prepare("SELECT id FROM tasks WHERE status = 'running'").all()) {
+  for (const { id } of board.db.prepare(entry.workflow.run ? "SELECT id FROM tasks WHERE current_run_id IS NOT NULL" : "SELECT id FROM tasks WHERE status = 'running'").all()) {
     tx(board, (db) => {
       const task = getTask(db, id);
       const status = statusOf(db, task);
-      if (!(entry.workflow.statuses[status]?.on?.session_idle || entry.workflow.on?.session_idle)) return;
+      if (!(entry.workflow.statuses[status]?.on?.session_idle || entry.workflow.on?.session_idle || entry.workflow.run?.on?.session_idle)) return;
       const runRow = currentRun(db, id);
       const session = runRow?.metadata?.supercode;
       if (!session?.session_id || session.surface !== 'pane') return;
@@ -487,7 +489,7 @@ function observeIdle(board, fleet, settings, report, entry, effects) {
       try {
         const where = whereOf(board, task);
         // the ask names what the session may do, as its run's prompt did
-        const said = doors(entry.workflow, status, session.role ?? entry.workflow.statuses[status]?.run?.role ?? 'implementer', id, where, session.surface === 'pane' ? 'pane' : 'headless');
+        const said = doors(entry.workflow, status, session.role ?? runSpec(entry, status)?.role ?? 'implementer', id, where, session.surface === 'pane' ? 'pane' : 'headless');
         const r = fire(db, board, entry, id, 'session_idle', { roles: ['platform'], payload: { turns: Number(session.goal_turns ?? 0), worked }, extra: { where, doors: said } });
         effects.push(...r.effects);
         const after = currentRun(db, id);
@@ -532,7 +534,7 @@ export async function sessionEffect(board, e) {
 
 // ------------------------------------------------------------------ start
 
-const running = (db, sql, ...args) => Number(db.prepare(`SELECT COUNT(*) AS n FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.status = 'running' ${sql}`).get(...args).n);
+const running = (db, sql, ...args) => Number(db.prepare(`SELECT COUNT(*) AS n FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.current_run_id IS NOT NULL ${sql}`).get(...args).n);
 
 /**
  * How many sessions the board has on `machine`: every running card's, and every other card's latest session that is
@@ -542,7 +544,7 @@ function machineLoad(db, machine, fleet) {
   let n = 0;
   for (const card of db.prepare("SELECT t.id, t.status, c.machine FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE c.machine IS NOT NULL AND t.status != 'archived'").all()) {
     if (normalMachine(card.machine) !== machine) continue;
-    if (card.status === 'running' || (fleet.ok && sessionAlive(fleet, lastSession(db, card.id)))) n += 1;
+    if (card.current_run_id || (fleet.ok && sessionAlive(fleet, lastSession(db, card.id)))) n += 1;
   }
   return n;
 }
@@ -1213,7 +1215,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
   // the running cards of every board of the home, for kanban.max_in_progress (host-wide, as Hermes counts it)
   let hostRunning = 0;
   for (const slug of boards) {
-    try { const b = openBoard(root, slug); try { hostRunning += Number(b.db.prepare("SELECT COUNT(*) AS n FROM tasks WHERE status = 'running'").get().n); } finally { b.close(); } } catch { /* its own tick reports it */ }
+    try { const b = openBoard(root, slug); try { hostRunning += Number(b.db.prepare("SELECT COUNT(*) AS n FROM tasks WHERE current_run_id IS NOT NULL").get().n); } finally { b.close(); } } catch { /* its own tick reports it */ }
   }
   const out = [];
   for (const slug of boards) {

package/board/engine.mjs

@@ -12,7 +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 { eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, workflowFor } from './workflow.mjs';
+import { eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
 export const WORKSPACE_KINDS = ['scratch', 'dir', 'worktree'];
@@ -34,8 +34,8 @@ 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 };
+  const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
+  return { ...row, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
 }
 
 function must(db, id) {
@@ -195,7 +195,7 @@ export function createCard(board, spec) {
     const entry = workflowFor(board.root);
     // the create's own words: whether it asked to be a goal card (null: the workflow decides), triage, its arc
     const status = startNew(db, board, entry, getTask(db, id), { triage: Boolean(spec.triage), initial_status: initial,
-      goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
+      every: spec.every ?? null, goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
     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) {
@@ -271,12 +271,12 @@ export function claimIn(db, id, { ttl = claimTtl(), lock = claimer(), expectStat
 
 /** 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');
+  const task = one(db, 'SELECT claim_lock, current_run_id FROM tasks WHERE id = ? AND current_run_id IS NOT NULL', id);
   if (!task) return false;
   const expires = now() + ttl;
-  run(db, 'UPDATE tasks SET claim_expires = ? WHERE id = ? AND status = ?', expires, id, 'running');
+  run(db, 'UPDATE tasks SET claim_expires = ? WHERE id = ?', expires, id);
   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);
+  runEvent(db, task.current_run_id, 'claim_extended', { reason, claim_expires_now: expires, ...extra });
   return true;
 }
 

package/board/store.mjs

@@ -70,7 +70,7 @@ CREATE INDEX IF NOT EXISTS idx_events_run ON task_events(run_id, id);
 const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY KEY, machine TEXT, subtask_of TEXT, stage TEXT);`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
-const OURS_COLUMNS = { subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT' };
+const OURS_COLUMNS = { subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
 
 // ------------------------------------------------------------------ backings
 //
@@ -199,6 +199,7 @@ export function json(text, fallback = null) {
 // the session whose command this process runs (its address), set by the CLI: each event it records says who acted
 // (`by`), so the session is not told of its own act
 let actor = null;
+export const actorOf = () => actor;
 export function setActor(address) { actor = address || null; }
 
 export function event(db, taskId, kind, payload = null, runId = null) {

package/board/workflow.mjs

@@ -5,8 +5,10 @@
 // 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 { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { event as record, json, now } from './store.mjs';
+import { actorOf, event as record, json, now } from './store.mjs';
 import { evaluate, holds, render } from './expr.mjs';
 
 const loaded = new Map();
@@ -17,6 +19,7 @@ export async function loadWorkflow(root, { fresh = false } = {}) {
   const { read } = await import('../orchestration.mjs');
   const orchestration = await read(root);
   const entry = workflowEntry(orchestration);
+  entry.root = root;
   loaded.set(root, entry);
   return entry;
 }
@@ -38,6 +41,7 @@ export function workflowFor(root) {
 
 /** Use `entry` for `root` (a caller that read the IR itself). */
 export function useWorkflow(root, entry) {
+  entry.root = root;
   loaded.set(root, entry);
   return entry;
 }
@@ -157,13 +161,31 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
   const waitingOn = lastBlock?.kind === 'blocked' ? json(lastBlock.payload, {})?.waiting_on ?? null : null;
   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 state = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', task.id) ?? {};
+  const blocks = json(state.blocked_by, []) ?? [];
   const card = {
     ...task,
     status,
+    blocked_by: blocks,
+    paused: json(state.paused, null),
+    archived: Boolean(state.archived),
+    every: state.every ?? null,
+    next_run_at: state.next_run_at ?? null,
+
     stored_as: task.status,
     board: board.slug,
     parents,
     children,
+    acceptance_complete: () => {
+      const lines = String(task.body ?? '').split('\n');
+      let acceptance = false;
+      return lines.every((line) => {
+        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+        if (heading) acceptance = heading[1].toLowerCase() === 'acceptance';
+        if (!acceptance || !/^\s*[-*] \[[ xX]\]/.test(line)) return true;
+        return /^\s*[-*] \[[xX]\] .+: \S.+$/.test(line);
+      });
+    },
     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,
@@ -199,6 +221,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
       return lastCommitAt(own ?? arcWs ?? null, task.id);
     },
   };
+  for (const [key, expr] of Object.entries(loaded.get(board.root)?.workflow?.derived ?? {})) card[key] = evaluate(expr, { card, event, params, now: now() });
   return {
     card,
     event,
@@ -227,7 +250,7 @@ const argsValue = (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] ?? [])];
+  return [...(workflow.verbs?.[name] ?? []).filter((t) => !t.from?.length || t.from.includes(status)), ...(workflow.statuses[status]?.on?.[name] ?? []), ...(workflow.on?.[name] ?? [])];
 }
 
 /**
@@ -237,6 +260,7 @@ export function transitionsFor(workflow, status, name) {
  */
 export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
   const { workflow, params } = entry;
+  if (workflow.run && (workflow.run.on?.[name] || Object.values(workflow.run.states ?? {}).some((s) => s.on?.[name]))) return fireRun(db, board, entry, id, name, { roles, payload, extra });
   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`);
@@ -270,7 +294,7 @@ export function eventTo(db, board, entry, id, status, { roles = [], payload = {}
   const from = statusOf(db, task);
   const scope = scopeOf(db, board, task, { params, event: payload, extra: { lanes: lanesIn(entry), sender: roles } });
   let refusal = null;
-  for (const name of new Set([...Object.keys(workflow.statuses[from]?.on ?? {}), ...Object.keys(workflow.on ?? {})])) {
+  for (const name of new Set([...Object.keys(workflow.statuses[from]?.on ?? {}), ...Object.keys(workflow.on ?? {}), ...Object.keys(workflow.verbs ?? {})])) {
     const taken = transitionsFor(workflow, from, name).filter((t) => !t.by?.length || t.by.some((r) => roles.includes(r))).find((t) => holds(t.guard ?? null, scope));
     if (!taken?.target || String(templateValue(taken.target, scope) ?? '') !== status) continue;
     const failed = (taken.validate ?? []).find((v) => !holds(v.expr, scope));
@@ -283,7 +307,7 @@ export function eventTo(db, board, entry, id, status, { roles = [], payload = {}
 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);
+  const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
   return { ...row, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
 }
 
@@ -299,7 +323,7 @@ function take(db, board, entry, task, from, transition, scope, effects) {
   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 });
+    if (workflow.statuses[target].run || workflow.statuses[target].run_role) effects.push({ kind: 'run', id: task.id, status: target });
   }
   return target ?? from;
 }
@@ -315,6 +339,7 @@ export function setStatus(db, workflow, id, status) {
 /** 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;
+  settleRelations(db, board, entry, id, effects);
   for (let hops = 0; hops < 16; hops += 1) {
     const task = cardOf(db, id);
     const from = statusOf(db, task);
@@ -366,6 +391,7 @@ export function startNew(db, board, entry, task, event) {
   setStatus(db, entry.workflow, task.id, status);
   const ctx = { db, board, entry, id: task.id, scope: { ...scope, before: scope.card }, from: status, to: status, effects: [], runId: null };
   for (const a of t.actions ?? []) act(ctx, a);
+  if (event.every != null) ACTIONS.every(ctx, event.every);
   return status;
 }
 
@@ -419,6 +445,51 @@ const FORMAT = {
 const RETRY_KINDS = new Set(['crashed', 'timed_out', 'stale', 'rate_limited', 'session_lost', 'reclaimed', 'reconciled', 'spawn_failed']);
 
 const ACTIONS = {
+  relation(ctx, { add = null, remove = null, reason = null } = {}) {
+    const row = one(ctx.db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', ctx.id);
+    let blocks = json(row?.blocked_by, []) ?? [];
+    if (add) {
+      const id = String(add);
+      if (id === ctx.id) throw new Error('a card cannot block itself');
+      const kind = id.startsWith('m-') ? 'message' : 'card';
+      if (kind === 'card' && !one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', id)) throw new Error(`no blocking card ${id}`);
+      if (kind === 'card') {
+        const seen = new Set(); const pending = [id];
+        while (pending.length) {
+          const node = pending.pop();
+          if (node === ctx.id) throw new Error('blocking relation would create a cycle');
+          if (seen.has(node)) continue;
+          seen.add(node);
+          const related = json(one(ctx.db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', node)?.blocked_by, []) ?? [];
+          pending.push(...related.filter((b) => b.kind === 'card').map((b) => b.id));
+        }
+      }
+      if (!blocks.some((b) => b.id === id)) blocks.push({ id, kind, reason, by: actorOf(), since: now() });
+    }
+    if (remove) {
+      if (!String(reason ?? '').trim()) throw new Error('unblock must say what arrived');
+      blocks = blocks.filter((b) => remove !== '*' && b.id !== remove);
+    }
+    cardField(ctx, 'blocked_by', JSON.stringify(blocks));
+  },
+  flag(ctx, { name, value, reason = null }) {
+    if (!['paused', 'archived'].includes(name)) throw new Error(`unknown flag ${name}`);
+    if (name === 'paused') {
+      const was = json(one(ctx.db, 'SELECT paused FROM supercode_cards WHERE task_id = ?', ctx.id)?.paused, null);
+      if (!value && was && was.by !== actorOf() && !ctx.scope.sender?.includes('owner')) throw new Error('only the pauser or owner may resume this card');
+      if (value && !String(reason ?? '').trim()) throw new Error('pause needs a reason');
+      cardField(ctx, name, value ? JSON.stringify({ by: actorOf(), reason }) : null);
+    } else cardField(ctx, name, Number(Boolean(value)));
+  },
+  every(ctx, interval) {
+    intervalSeconds(interval); // refuse malformed intervals before storing
+    cardField(ctx, 'every', interval == null ? null : String(interval));
+    cardField(ctx, 'next_run_at', interval == null ? null : now());
+  },
+  card_event(ctx, { name, payload = {} }) {
+    const result = fire(ctx.db, ctx.board, ctx.entry, ctx.id, name, { roles: ['platform'], payload, extra: ctx.scope });
+    ctx.effects.push(...result.effects);
+  },
   record(ctx, args, scope) {
     const kind = typeof args === 'string' ? args : args?.kind;
     const given = typeof args === 'object' && args?.payload ? args.payload : null;
@@ -436,7 +507,9 @@ const ACTIONS = {
     // `on`: the event is another card's (a dependency hears what waits on it), recorded there with no run
     const on = typeof args === 'object' && args?.on ? String(args.on) : null;
     if (on && !one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', on)) return;
-    record(ctx.db, on ?? ctx.id, kind, payload && Object.keys(payload).length ? payload : null, on ? null : ctx.runId);
+    if (ctx.machine === 'run' && !on) {
+      runEvent(ctx.db, ctx.runId, kind, payload);
+    } else record(ctx.db, on ?? ctx.id, kind, payload && Object.keys(payload).length ? payload : null, on ? 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`);
@@ -482,6 +555,7 @@ const ACTIONS = {
     const task = cardOf(ctx.db, ctx.id);
     const t = now();
     const ttl = Number(ctx.entry.params.claim_ttl_seconds) || 900;
+    if (ctx.entry.workflow.run && (task.subtask_of || scope.card.paused || scope.card.archived || scope.card.blocked_by.length)) throw new Error('this card cannot run while blocked, paused, archived, or a subtask');
     const lock = ctx.scope.event?.lock;
     if (!lock) throw new Error('a claim needs the dispatcher\'s lock');
     if (task.current_run_id) {
@@ -489,13 +563,14 @@ const ACTIONS = {
     }
     const expires = t + ttl;
     const profile = evaluate(ctx.entry.workflow.roles?.[role] ?? 'card.assignee', scope) ?? task.assignee;
-    const slot = String(templateValue(ctx.entry.workflow.statuses[ctx.to]?.run?.session ?? 'worker', scope) ?? 'worker');
+    const slot = String(templateValue(runSpec(ctx.entry, ctx.to)?.session ?? 'worker', scope) ?? 'worker');
     run(ctx.db, 'UPDATE tasks SET claim_lock = ?, claim_expires = ?, started_at = COALESCE(started_at, ?) WHERE id = ?', lock, expires, t, ctx.id);
     const r = run(ctx.db, "INSERT INTO task_runs (task_id, profile, step_key, status, claim_lock, claim_expires, max_runtime_seconds, started_at, metadata) VALUES (?, ?, ?, 'running', ?, ?, ?, ?, ?)",
-      ctx.id, profile, ctx.to, lock, expires, task.max_runtime_seconds, t, JSON.stringify({ supercode: { role, status: ctx.to, slot } }));
+      ctx.id, profile, ctx.to, lock, expires, task.max_runtime_seconds, t, JSON.stringify({ supercode: { role, status: ctx.to, slot, state: ctx.entry.workflow.run?.initial ?? null } }));
     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);
+    if (scope.card.every) cardField(ctx, 'next_run_at', t + intervalSeconds(scope.card.every));
+    if (!ctx.entry.workflow.run) 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;
@@ -601,7 +676,7 @@ const TOOL_OF = { complete: 'kanban_complete', block: 'kanban_block', request_re
 
 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 [name, ts] of [...Object.entries(workflow.statuses[status]?.on ?? {}), ...Object.entries(workflow.on ?? {}), ...Object.entries(workflow.run?.on ?? {}), ...Object.entries(workflow.verbs ?? {}).map(([name, ts]) => [name, ts.filter((t) => !t.from?.length || t.from.includes(status))])]) {
     for (const t of ts) {
       if (!t.by?.length || !t.by.includes(role)) continue;
       if (!events.has(name)) events.set(name, t.description ?? null);
@@ -612,3 +687,78 @@ export function doors(workflow, status, role, id, where, surface = 'pane') {
     .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');
 }
+
+
+function cardField(ctx, field, value) {
+  run(ctx.db, `INSERT INTO supercode_cards (task_id, ${field}) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET ${field} = excluded.${field}`, ctx.id, value);
+}
+
+export function intervalSeconds(value) {
+  if (value == null) return null;
+  const match = /^(\d+(?:\.\d+)?)\s*(s|m|h|d|w)?$/.exec(String(value));
+  const seconds = match && Number(match[1]) * ({ s: 1, m: 60, h: 3600, d: 86400, w: 604800 }[match[2] ?? 's']);
+  if (!(seconds > 0)) throw new Error(`invalid recurring interval ${value}`);
+  return seconds;
+}
+
+export function runSpec(entry, status) {
+  const st = entry.workflow.statuses[status];
+  const spec = st?.run_role ? entry.workflow.run?.roles?.[st.run_role] : st?.run;
+  if (!spec?.prompt_file) return spec;
+  const file = resolve(entry.root, spec.prompt_file);
+  const rel = relative(entry.root, file);
+  if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('prompt file must live in the orchestration home');
+  return { ...spec, prompt: readFileSync(file, 'utf8') };
+}
+
+export function runEvent(db, id, kind, payload) {
+  if (!id) return;
+  const row = one(db, 'SELECT metadata FROM task_runs WHERE id = ?', id);
+  const meta = json(row?.metadata, {}) ?? {};
+  meta.events = [...(meta.events ?? []), { kind, payload, by: actorOf(), at: now() }];
+  run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(meta), id);
+}
+
+export function fireRun(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
+  const task = cardOf(db, id);
+  const row = task.current_run_id && one(db, 'SELECT * FROM task_runs WHERE id = ?', task.current_run_id);
+  if (!row) throw new Error(`${id} has no current run for ${name}`);
+  const machine = entry.workflow.run;
+  const meta = json(row.metadata, {}) ?? {};
+  const from = meta.supercode?.state ?? machine.initial;
+  const scope = scopeOf(db, board, task, { params: entry.params, event: payload, extra: { ...extra, sender: roles, run: { ...row, state: from } } });
+  const candidates = [...(machine.states[from]?.on?.[name] ?? []), ...(machine.on?.[name] ?? [])];
+  const t = candidates.find((t) => (!t.by?.length || t.by.some((r) => roles.includes(r))) && holds(t.guard ?? null, scope));
+  if (!t) { const error = new Error(`${id}: run event ${name} does not apply`); error.noTransition = true; throw error; }
+  for (const v of t.validate ?? []) if (!holds(v.expr, scope)) throw new Error(v.message);
+  const to = t.target ? String(templateValue(t.target, scope)) : from;
+  if (!machine.states[to]) throw new Error(`unknown run state ${to}`);
+  const effects = [];
+  const status = statusOf(db, task);
+  const ctx = { db, board, entry, id, scope: { ...scope, before: scope.card }, from: status, to: status, effects, runId: row.id, machine: 'run' };
+  if (to !== from) for (const a of machine.states[from]?.exit ?? []) act(ctx, a);
+  runSession(ctx, (s) => ({ ...s, state: to }));
+  runEvent(db, row.id, name, payload);
+  for (const a of t.actions ?? []) act(ctx, a);
+  if (to !== from) for (const a of machine.states[to]?.entry ?? []) act(ctx, a);
+  if (to !== from) {
+    const after = scopeOf(db, board, cardOf(db, id), { params: entry.params, event: payload, extra: { ...extra, sender: roles } });
+    const outcome = (machine.outcomes?.[to] ?? []).find((t) => holds(t.guard ?? null, after));
+    if (outcome) take(db, board, entry, cardOf(db, id), statusOf(db, cardOf(db, id)), outcome, after, effects);
+  }
+  return { from: status, to: statusOf(db, cardOf(db, id)), effects };
+}
+
+function settleRelations(db, board, entry, id, effects) {
+  if (!entry.workflow.relations?.blocked_by) return;
+  const row = one(db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', id);
+  const blocks = json(row?.blocked_by, []) ?? [];
+  for (const block of blocks) {
+    const dependency = block.kind === 'card' ? one(db, 'SELECT * FROM tasks WHERE id = ?', block.id) : null;
+    const status = dependency ? statusOf(db, dependency) : null;
+    const answer = block.kind === 'message' ? answerTo(block.id) : null;
+    const policy = entry.workflow.relations.blocked_by;
+    const name = answer ? policy.answered : status === 'done' ? policy.completed : status === 'cancelled' ? policy.cancelled : null;
+    if (name) effects.push(...fire(db, board, entry, id, name, { roles: ['platform'], payload: { on: block.id, reason: answer ? `reply ${answer}` : `${block.id} ${status}` } }).effects);
+  }
+}

package/package.json

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