@volter/supercode-orchestrator 0.4.32 → 0.4.34

package/board/cli.mjs

@@ -13,7 +13,7 @@ import { holdDispatcherLock } from '../hermes-locks.mjs';
 import { boardPath, DEFAULT_BOARD, event, json, listBoards, now, openBoard, tx } from './store.mjs';
 import * as engine from './engine.mjs';
 import { adoptSession, boardLabel, boardSettings, lanesOf, localMachine, observeFleet, paused, startCard, tick } from './dispatch.mjs';
-import { loadWorkflow, useWorkflow, workflowEntry } from './workflow.mjs';
+import { loadWorkflow, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
 import { evaluate } from './expr.mjs';
 
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
@@ -26,7 +26,7 @@ Hermes Kanban's verbs, with their flags:
   swarm <goal> --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
   list [--mine] [--assignee] [--status] [--tenant] [--session] [--archived] [--sort]   show <id>   context <id>   runs <id>
   assign <id> <profile|none>   reassign <id> <profile> [--reclaim] [--reason]   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
-  claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note]   link|unlink <parent> <child>
+  claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
   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] [--kind dependency|needs_input|capability|transient] [--ids ...]   schedule <id> [reason] [--ids ...]
@@ -178,7 +178,8 @@ const ts = (t) => {
   const p = (n) => String(n).padStart(2, '0');
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 };
-const line = (t) => `${ICONS[t.status] ?? '?'} ${t.id}  ${t.status.padEnd(8)}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
+// a card's status is the workflow's (triaging, reviewing, …); kanban.db stores the Hermes status it maps to
+const line = (t) => `${ICONS[t.status] ?? '?'} ${t.id}  ${(t.stage ?? t.status).padEnd(8)}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
 const cardDict = (t) => ({
   id: t.id, title: t.title, body: t.body, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant,
   workspace_kind: t.workspace_kind, workspace_path: t.workspace_path, branch_name: t.branch_name, project_id: t.project_id,
@@ -189,6 +190,15 @@ const cardDict = (t) => ({
 });
 
 /** Hermes's durations: seconds, or 30s / 5m / 2h / 1d. */
+// a moment the caller names: an ISO time, or a duration from now (30m, 2h); epoch seconds, or null
+function untilOf(v) {
+  if (v === undefined || v === null || v === '' || v === true) return null;
+  if (/^\d+(?:\.\d+)?[smhd]?$/i.test(String(v).trim())) return now() + duration(v);
+  const t = Date.parse(String(v));
+  if (Number.isNaN(t)) throw new Error(`malformed --until ${v} (expected an ISO time such as 2026-09-29T04:35Z, or a duration such as 2h)`);
+  return Math.floor(t / 1000);
+}
+
 function duration(v) {
   if (v === undefined || v === null || v === '') return null;
   const s = String(v).trim().toLowerCase();
@@ -224,8 +234,9 @@ export async function runWorkflow(argv) {
     withBoard((b) => { const own = ownCard(b.db, sid); if (own) authorize(b.db, verb, rest, args, own); });
   }
   // the board's workflow (the IR's): what each verb does, and who may send it, is its
-  if (!READS.has(verb) && verb !== 'help') await loadWorkflow(root).catch((error) => { if (verb !== 'init' && verb !== 'boards') throw error; });
-  engine.setCaller((db, cardId) => rolesFor(db, cardId, sid));
+  // every verb reads the board through its workflow (a list settles cards too), so every verb loads it
+  if (verb !== 'help') await loadWorkflow(root).catch((error) => { if (verb !== 'init' && verb !== 'boards') throw error; });
+  engine.setCaller((db, cardId) => rolesFor(db, cardId, sid, workflowFor(root).params));
 
   switch (verb) {
     case 'init': {
@@ -245,15 +256,14 @@ export async function runWorkflow(argv) {
       const meta = boardMeta(root, slug);
       let workspace = args.workspace;
       if ((workspace === 'dir' || workspace === 'worktree') && meta.default_workdir) workspace = `${workspace}:${meta.default_workdir}`;
-      // a home whose `kanban.goal_mode_default` is true makes every new card a goal card (a subtask is never started alone)
-      const goalDefault = !args.goal && !args['no-goal'] && !args['subtask-of'] && (await laneState(root)).kanban.goal_mode_default === true;
+      // --goal / --no-goal are the create's words; without either, the workflow's initial decides
       const created = withBoard((b) => engine.createCard(b, {
         title: rest.join(' '), body: args.body, assignee: args.assignee === 'none' ? null : args.assignee, machine: args.machine,
         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: process.env.CLAUDE_CODE_SESSION_ID ?? null, subtaskOf: args['subtask-of'] ?? null, initialStatus: args['initial-status'] ?? null,
-        project: args.project ?? meta.project_id ?? null, goal: args.goal || goalDefault ? { maxTurns: args['goal-max-turns'] ? Number(args['goal-max-turns']) : null } : 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 };
       if (!args['no-start'] && !created.existing && !args['subtask-of']) {
@@ -318,6 +328,7 @@ export async function runWorkflow(argv) {
         const got = engine.showCard(b.db, id);
         got.runs = engine.runs(b.db, id, { stateType: args['state-type'] ?? null, stateName: args['state-name'] ?? null });
         got.diagnostics = engine.diagnose(b.db, got.task, { failureLimit: settings.failureLimit });
+        got.stage = statusOf(b.db, got.task);
         return got;
       });
       const t = card.task;
@@ -326,7 +337,7 @@ export async function runWorkflow(argv) {
         say(args, '', { task: cardDict(t), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
         return 0;
       }
-      const out = [`Task ${t.id}: ${t.title}`, `  status:    ${t.status}`, `  assignee:  ${t.assignee || '-'}`];
+      const out = [`Task ${t.id}: ${t.title}`, `  status:    ${card.stage}${card.stage !== t.status ? ` (${t.status} in kanban.db)` : ''}`, `  assignee:  ${t.assignee || '-'}`];
       if (t.machine) out.push(`  machine:   ${t.machine}`);
       if (t.subtask_of) out.push(`  subtask of: ${t.subtask_of}`);
       if (t.tenant) out.push(`  tenant:    ${t.tenant}`);
@@ -416,7 +427,7 @@ export async function runWorkflow(argv) {
       return 0;
     }
     case 'reclaim': need(1, 'a card id'); await withBoardAsync((b) => engine.reclaim(b, id, args.reason ?? (rest.slice(1).join(' ') || null))); say(args, `Reclaimed ${id}`, { ok: true }); return 0;
-    case 'heartbeat': need(1, 'a card id'); await withBoardAsync((b) => engine.heartbeat(b, id, args.note ?? null)); say(args, `Heartbeat recorded for ${id}`, { ok: true }); return 0;
+    case 'heartbeat': need(1, 'a card id'); await withBoardAsync((b) => engine.heartbeat(b, id, args.note ?? null, { until: untilOf(args.until) })); say(args, `Heartbeat recorded for ${id}`, { ok: true }); return 0;
 
     case 'link': need(2, 'a parent and a child'); await withBoardAsync((b) => engine.link(b, rest[0], rest[1])); say(args, `Linked ${rest[0]} -> ${rest[1]}`, { ok: true }); return 0;
     case 'unlink': { need(2, 'a parent and a child'); const gone = await withBoardAsync((b) => engine.unlink(b, rest[0], rest[1])); say(args, gone ? `Unlinked ${rest[0]} -> ${rest[1]}` : `no link ${rest[0]} -> ${rest[1]}`, { ok: gone }); return gone ? 0 : 1; }
@@ -489,7 +500,7 @@ export async function runWorkflow(argv) {
       say(args, results.map(([t, s]) => `Unblocked ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
     }
     case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
-    case 'request-changes': need(2, 'a card id and the reason'); await withBoardAsync((b) => engine.requestChanges(b, id, { reason: rest.slice(1).join(' '), reviewer: args.reviewer ?? callerName() })); say(args, `${id} sent back for changes`, { ok: true }); return 0;
+    case 'request-changes': need(2, 'a card id and the reason'); await withBoardAsync((b) => engine.requestChanges(b, id, { reason: rest.slice(1).join(' '), reviewer: args.reviewer ?? null })); say(args, `${id} sent back for changes`, { ok: true }); return 0;
     case 'reopen': {
       // a done card back to work; the cards that built on it are invalidated with it (Hermes's reopen)
       need(1, 'a card id');
@@ -652,14 +663,13 @@ export async function runWorkflow(argv) {
 
     case 'dispatch': {
       const { lanes, settings } = await laneState(root);
-      if (args['failure-limit']) settings.failureLimit = Number(args['failure-limit']);
-      if (args.max) settings.maxInProgress = Number(args.max);
+      const params = { ...(args['failure-limit'] ? { failure_limit: Number(args['failure-limit']) } : {}), ...(args.max ? { max_spawn: Number(args.max) } : {}) };
       if (args['dry-run']) {
         const would = withBoard((b) => engine.listCards(b.db, { status: 'ready' }).filter((t) => t.assignee && lanes[t.assignee] && !t.subtask_of).map((t) => ({ id: t.id, assignee: t.assignee, machine: t.machine, surface: lanes[t.assignee].surface })));
         say(args, would.length ? would.map((w) => `would start ${w.id} as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`).join('\n') : 'nothing would start', would);
         return 0;
       }
-      const reports = await tick({ root, lanes, settings });
+      const reports = await tick({ root, lanes, settings, params });
       if (args.json) say(args, '', reports);
       else for (const r of reports) process.stdout.write(`${summary(r)}\n`);
       return reports.some((r) => r.error) ? 1 : 0;
@@ -963,8 +973,11 @@ const READS = new Set(['list', 'ls', 'show', 'context', 'runs', 'log', 'tail', '
  * is `manager`; the session of the card's current run has that run's role; the card's working session between runs
  * is its `implementer`; the session working a subtask's arc is `arc`; any other session is nobody on it.
  */
-function rolesFor(db, cardId, sessionId) {
+function rolesFor(db, cardId, sessionId, params = {}) {
   if (!sessionId) return ['manager'];
+  // 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'];
   const task = engine.getTask(db, cardId);
   if (!task) return [];
   const roles = [];
@@ -1024,11 +1037,9 @@ export function summary(r) {
 async function serve(root, args = {}) {
   const lock = await holdDispatcherLock(root);
   // Hermes's daemon flags: --interval seconds, --max starts per tick, --failure-limit, --pidfile, --verbose
-  const override = {
-    ...(Number(args.interval) > 0 ? { interval: Number(args.interval) } : {}),
-    ...(Number(args.max) > 0 ? { maxSpawn: Number(args.max) } : {}),
-    ...(Number(args['failure-limit']) > 0 ? { failureLimit: Number(args['failure-limit']) } : {}),
-  };
+  const override = Number(args.interval) > 0 ? { interval: Number(args.interval) } : {};
+  // --max and --failure-limit are params of every tick, read by the workflow as its own
+  const params = { ...(Number(args.max) > 0 ? { max_spawn: Number(args.max) } : {}), ...(Number(args['failure-limit']) > 0 ? { failure_limit: Number(args['failure-limit']) } : {}) };
   if (args.pidfile) writeFileSync(args.pidfile, `${process.pid}\n`);
   let stopped = false;
   const stop = () => { stopped = true; };
@@ -1048,7 +1059,7 @@ async function serve(root, args = {}) {
         const state = await laneState(root);
         const settings = { ...state.settings, ...override };
         interval = settings.interval;
-        for (const r of await tick({ root, lanes: state.lanes, settings })) {
+        for (const r of await tick({ root, lanes: state.lanes, settings, params })) {
           const said = summary(r);
           if (!said.endsWith('nothing to do') || args.verbose) log(said);
           if (args.verbose && r.ms) log(`  took ${Object.entries(r.ms).map(([k, v]) => `${k} ${(v / 1000).toFixed(1)}s`).join(', ')}`);

package/board/dispatch.mjs

@@ -30,13 +30,6 @@ import {
 } from './engine.mjs';
 
 const WORKER = fileURLToPath(new URL('../bin/hermes-worker.mjs', import.meta.url));
-const MAIL_KINDS = {
-  creator: ['completed', 'blocked', 'gave_up', 'crashed', 'timed_out', 'status', 'archived', 'block_loop_detected', 'review_requested',
-    'changes_requested', 'session_started', 'session_resumed', 'session_replaced', 'session_adopted', 'session_lost', 'spawn_failed'],
-  worker: ['commented', 'assigned', 'machine_set', 'blocked', 'unblocked', 'completed', 'archived', 'changes_requested', 'linked', 'unlinked', 'promoted_manual', 'subtask_added', 'session_adopted'],
-  // a card the session's own card depends on: it sees it change
-  dependency: ['completed', 'blocked', 'unblocked', 'archived', 'review_requested', 'changes_requested', 'commented'],
-};
 
 // ------------------------------------------------------------------ names and the fleet
 
@@ -107,30 +100,26 @@ function derivedMaxInProgress() {
   } catch { return null; }
 }
 
-/** The board's settings: the home's `kanban:` block, Hermes's keys and supercode's own (`machines`, `session_grace_seconds`). */
-export function boardSettings(kanban = {}) {
+/**
+ * What the platform itself reads from the workflow's params (everything else the dispatcher does is the workflow's
+ * transitions and `dispatch`): the claim ttl, the session grace, the tick interval, log rotation, hooks, the failure
+ * limit the diagnostics report against, and Hermes's environment override for the crash grace.
+ */
+export function boardSettings(params = {}) {
   const pos = (v) => (Number.isInteger(Number(v)) && Number(v) >= 1 ? Number(v) : null);
+  const env = (name, fallback) => {
+    const raw = process.env[name];
+    return raw !== undefined && raw !== '' && Number.isInteger(Number(raw)) && Number(raw) >= 0 ? Number(raw) : fallback;
+  };
   return {
-    failureLimit: pos(kanban.failure_limit) ?? DEFAULT_FAILURE_LIMIT,
-    maxInProgress: pos(kanban.max_in_progress) ?? derivedMaxInProgress(),
-    crashGrace: Number.isInteger(Number(process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS)) && process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS !== '' && Number(process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS) >= 0 ? Number(process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS) : 30,
-    perProfile: pos(kanban.max_in_progress_per_profile),
-    defaultAssignee: String(kanban.default_assignee ?? '').trim() || null,
-    reviewDispatch: kanban.review_dispatch !== false,
-    ttl: claimTtl(kanban.claim_ttl_seconds),
-    grace: pos(kanban.session_grace_seconds) ?? 120,
-    machines: Object.fromEntries(Object.entries(kanban.machines ?? {}).map(([name, m]) => [normalMachine(name), { capacity: pos(m?.capacity) }])),
-    interval: Math.max(Number(kanban.dispatch_interval_seconds) || 60, 1),
-    staleTimeout: pos(kanban.dispatch_stale_timeout_seconds),
-    autoDecompose: kanban.auto_decompose !== false,
-    autoDecomposePerTick: pos(kanban.auto_decompose_per_tick) ?? 3,
-    goalMaxTurns: pos(kanban.goal_max_turns) ?? 20,
-    maxSpawn: pos(kanban.max_spawn),
-    reconcileOrphans: kanban.reconcile_orphans !== false,
-    logRotateBytes: pos(kanban.worker_log_rotate_bytes) ?? 2 * 1024 * 1024,
-    logBackups: Number.isInteger(Number(kanban.worker_log_backup_count)) && Number(kanban.worker_log_backup_count) >= 0 ? Number(kanban.worker_log_backup_count) : 1,
-    hooks: kanban.hooks && typeof kanban.hooks === 'object' ? kanban.hooks : {},
-    rateLimitCooldown: Number.isInteger(Number(process.env.HERMES_KANBAN_RATE_LIMIT_COOLDOWN_SECONDS)) && process.env.HERMES_KANBAN_RATE_LIMIT_COOLDOWN_SECONDS !== '' ? Number(process.env.HERMES_KANBAN_RATE_LIMIT_COOLDOWN_SECONDS) : 300,
+    failureLimit: pos(params.failure_limit) ?? DEFAULT_FAILURE_LIMIT,
+    ttl: claimTtl(params.claim_ttl_seconds),
+    grace: pos(params.session_grace_seconds) ?? 120,
+    interval: Math.max(Number(params.dispatch_interval_seconds) || 60, 1),
+    logRotateBytes: pos(params.worker_log_rotate_bytes) ?? 2 * 1024 * 1024,
+    logBackups: Number.isInteger(Number(params.worker_log_backup_count)) && Number(params.worker_log_backup_count) >= 0 ? Number(params.worker_log_backup_count) : 1,
+    hooks: params.hooks && typeof params.hooks === 'object' ? params.hooks : {},
+    crashGrace: env('HERMES_KANBAN_CRASH_GRACE_SECONDS', 30),
   };
 }
 
@@ -171,7 +160,8 @@ function supervise(board, fleet, settings, report, entry, effects) {
       const limits = limitsOf(db, board, entry, task, session);
       // Hermes's orphan reconciliation: a running card whose claim bookkeeping is broken, with nothing live behind it
       const live = session?.surface === 'headless' ? pidAlive(session.pid) : session?.session_id ? (fleet.ok ? sessionAlive(fleet, session) : true) : false;
-      if (settings.reconcileOrphans && (!task.claim_lock || !task.claim_expires) && !live) {
+      // (whether it is reconciled is the workflow's: its `orphaned` transitions and their guard)
+      if ((!task.claim_lock || !task.claim_expires) && !live) {
         observe('orphaned', { reason: 'orphaned_running', claim_lock: task.claim_lock, claim_expires: task.claim_expires, error: 'orphaned running card (broken claim bookkeeping)' }, 'reclaimed');
         return;
       }
@@ -533,7 +523,10 @@ function memoryPressure() {
 
 /** Record a guard reason once per change, not once per tick. */
 function noteGuard(db, id, reason) {
-  const last = db.prepare("SELECT payload FROM task_events WHERE task_id = ? AND kind IN ('respawn_guarded', 'claimed') ORDER BY id DESC LIMIT 1").get(id);
+  // once per reason per entry into the status: a card back in ready (a new `since`) is noted again, so the workflow's
+  // after-timers that read the reason (card.queue_reason) see it
+  const since = Number(db.prepare('SELECT since FROM supercode_cards WHERE task_id = ?').get(id)?.since ?? 0);
+  const last = db.prepare("SELECT payload FROM task_events WHERE task_id = ? AND kind IN ('respawn_guarded', 'claimed') AND created_at >= ? ORDER BY id DESC LIMIT 1").get(id, since);
   if (json(last?.payload, {})?.reason === reason) return;
   event(db, id, 'respawn_guarded', { reason });
 }
@@ -737,39 +730,6 @@ export function adoptSession(board, id, who, { workspace = null, ttl, assignee =
 
 // ------------------------------------------------------------------ notify
 
-function notice(kind, task, p, role) {
-  const tid = task?.id ?? '?';
-  const who = task?.assignee ? `@${task.assignee} ` : '';
-  const title = task?.title ?? '';
-  switch (kind) {
-    case 'session_started': case 'session_resumed': case 'session_replaced': {
-      const verb = { session_started: 'started', session_resumed: 'resumed', session_replaced: 'could not resume the card\'s last session and started' }[kind];
-      return `▶ ${who}card ${tid} — ${title}: the board ${verb} session ${p.session_id} on ${p.machine} (pane ${p.pane}; ${p.address}).`;
-    }
-    case 'session_adopted': return role === 'worker'
-      ? `▶ card ${tid} — ${title} is running again, with you: carry it on from where it stands (\`supercode workflow show ${tid}\` reads it).`
-      : `▶ ${who}card ${tid} — ${title}: the board found session ${p.session_id} still live on ${p.machine} and kept it (${p.address}).`;
-    case 'session_lost': return `✖ ${who}card ${tid}: session ${p.session_id} is gone from ${p.machine}; the board resumes it, and replaces it from the card only when it cannot.`;
-    case 'spawn_failed': return `✖ ${who}card ${tid}: its session did not start: ${String(p.error ?? '').slice(0, 300)}`;
-    case 'completed': return `✔ ${who}card ${tid} done — ${title}${p.summary ? `\n${String(p.summary).slice(0, 300)}` : ''}`;
-    case 'blocked': return `⏸ ${who}card ${tid} blocked${p.reason ? `: ${String(p.reason).slice(0, 300)}` : ''}`;
-    case 'unblocked': return `▶ card ${tid} unblocked`;
-    case 'gave_up': return `✖ ${who}card ${tid} gave up after ${p.failures} failures${p.error ? `\n${String(p.error).slice(0, 300)}` : ''}`;
-    case 'crashed': return `✖ ${who}card ${tid}: its worker exited without completing it; the board will retry`;
-    case 'timed_out': return `⏱ ${who}card ${tid} timed out (max_runtime ${p.limit_seconds}s); the board will retry`;
-    case 'status': return `🔄 ${who}card ${tid} → ${p.status}`;
-    case 'archived': return role === 'worker' ? `card ${tid} archived` : null;
-    case 'block_loop_detected': return `🛑 ${who}card ${tid} went to triage: blocked ${p.recurrences}x for the same cause${p.reason ? `: ${String(p.reason).slice(0, 200)}` : ''}`;
-    case 'review_requested': return `👀 ${who}card ${tid} ready for review — ${title}${p.summary ? `\n${String(p.summary).slice(0, 300)}` : ''}`;
-    case 'changes_requested': return `🛑 card ${tid}: review asked for changes: ${String(p.reason ?? 'reviewer feedback').slice(0, 300)}`;
-    case 'assigned': return `card ${tid} is now assigned to ${p.assignee ?? 'nobody'}`;
-    case 'machine_set': return `card ${tid} now runs on ${p.machine ?? 'no machine'}`;
-    case 'linked': case 'unlinked': return `card ${tid}: dependency ${kind} (${p.parent} → ${p.child})`;
-    case 'promoted_manual': return `card ${tid} promoted to ready by ${p.actor}`;
-    case 'subtask_added': return `card ${tid} has a new subtask ${p.subtask}: ${p.title}`;
-    default: return null;
-  }
-}
 
 // a notice sent within a transaction's caller that cannot await (the launcher): the same door, synchronously
 function deliverNow(board, to, body, key) {
@@ -796,7 +756,22 @@ export const boardAddress = (label) => `sc:${localMachine()}:board:${label.repla
 /** Consecutive failed sends after which a subscription is dropped (Hermes's notifier drops a dead chat after 12). */
 const MAX_SEND_FAILURES = 12;
 
-async function notify(board, fleet, report) {
+/**
+ * What an audience is told of an event: the workflow's `notify[audience][kind]` template over the card, the event's
+ * payload and (for a comment) the comment; null when the workflow names no such notice.
+ */
+export function noticeOf(entry, audience, kind, task, payload, comment = null) {
+  const template = entry.workflow.notify?.[audience]?.[kind];
+  if (template === undefined || template === null) return null;
+  const cut = (text, n) => String(text ?? '').slice(0, Number(n));
+  const text = render(template, { card: task, event: payload ?? {}, comment, params: entry.params, cut });
+  return text.trim() ? text : null;
+}
+
+/** The event kinds an audience hears (the workflow's notify). */
+const heardBy = (entry, audience) => Object.keys(entry.workflow.notify?.[audience] ?? {});
+
+async function notify(board, fleet, report, entry) {
   const from = boardAddress(board.label);
   // each subscription's notices go in order; different subscribers are told side by side
   await pool(subscriptions(board.db).filter((sub) => sub.platform === 'supercode'), SEND_CONCURRENCY, async (sub) => {
@@ -806,7 +781,8 @@ async function notify(board, fleet, report) {
       tx(board, (db) => db.prepare("DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?").run(sub.task_id, sub.chat_id));
       return;
     }
-    const kinds = MAIL_KINDS[role];
+    const kinds = heardBy(entry, role);
+    if (!kinds.length) return;
     const events = board.db.prepare(`SELECT id, kind, payload, created_at FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id`)
       .all(sub.task_id, sub.last_event_id, ...kinds);
     if (!events.length) return;
@@ -819,9 +795,9 @@ async function notify(board, fleet, report) {
         let text;
         if (ev.kind === 'commented') {
           if (p.author === sub.chat_id) { cursor = ev.id; continue; }
-          const c = board.db.prepare('SELECT body FROM task_comments WHERE task_id = ? AND author = ? AND created_at >= ? ORDER BY id LIMIT 1').get(sub.task_id, p.author, ev.created_at);
-          text = c ? `💬 card ${sub.task_id}, ${p.author}:\n${c.body}` : null;
-        } else text = notice(ev.kind, task, p, role);
+          const c = board.db.prepare('SELECT author, body FROM task_comments WHERE task_id = ? AND author = ? AND created_at >= ? ORDER BY id LIMIT 1').get(sub.task_id, p.author, ev.created_at);
+          text = c ? noticeOf(entry, role, ev.kind, task, p, c) : null;
+        } else text = noticeOf(entry, role, ev.kind, task, p);
         if (text) {
           // Hermes's delivery modes: `notify` is passive (read at the session's next turn), `wake`/`notify+wake` start its turn
           await send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { queue: sub.delivery_mode === 'notify' });
@@ -846,7 +822,6 @@ async function notify(board, fleet, report) {
 }
 
 // Hermes's terminal kinds for a chat subscriber, in its order of silence: archived and unblocked move the cursor and say nothing
-const CHAT_KINDS = ['completed', 'blocked', 'gave_up', 'crashed', 'timed_out', 'status', 'archived', 'unblocked', 'block_loop_detected', 'review_requested', 'changes_requested'];
 
 /**
  * A chat-platform subscription's events, sent through the orchestrator's own channel adapters (the daemon hosts them;
@@ -854,6 +829,10 @@ const CHAT_KINDS = ['completed', 'blocked', 'gave_up', 'crashed', 'timed_out', '
  */
 export async function notifyChats(root, adapters, log = () => {}, wake = null) {
   const sent = [];
+  // what a chat is told is the workflow's (notify.chat)
+  const entry = await loadWorkflow(root, { fresh: true });
+  const kinds = heardBy(entry, 'chat');
+  if (!kinds.length) return sent;
   for (const slug of listBoards(root)) {
     const board = openBoard(root, slug);
     board.label = boardLabel(root, slug);
@@ -861,14 +840,14 @@ export async function notifyChats(root, adapters, log = () => {}, wake = null) {
       for (const sub of subscriptions(board.db)) {
         const adapter = adapters?.[sub.platform];
         if (sub.platform === 'supercode' || !adapter) continue;
-        const events = board.db.prepare(`SELECT id, kind, payload FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${CHAT_KINDS.map(() => '?').join(', ')}) ORDER BY id`).all(sub.task_id, sub.last_event_id, ...CHAT_KINDS);
+        const events = board.db.prepare(`SELECT id, kind, payload FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id`).all(sub.task_id, sub.last_event_id, ...kinds);
         if (!events.length) continue;
         const task = tx(board, (db) => getTask(db, sub.task_id));
         let cursor = Number(sub.last_event_id);
         let failed = false;
         for (const ev of events) {
           const payload = json(ev.payload, {}) ?? {};
-          const text = ['archived', 'unblocked'].includes(ev.kind) ? null : notice(ev.kind, task, payload, 'creator');
+          const text = noticeOf(entry, 'chat', ev.kind, task, payload);
           if (text) {
             // a completed card's deliverables go with it as uploads, as Hermes's notifier sends them
             const files = ev.kind === 'completed' ? artifactsOf(payload, task).map((path) => ({ path })) : [];
@@ -1063,8 +1042,10 @@ const CORRUPT = /malformed|not a database|corrupt|disk image/i;
  * `only` limits starting to one card (a create that answers whether its card started). Each board is ticked under its
  * per-tick lock (Hermes's `.dispatch.lock`), skipped when another dispatcher holds it. Answers one report per board.
  */
-export async function tick({ root, lanes, settings, only = null, slugs = null, dispatch = true }) {
-  const entry = await loadWorkflow(root, { fresh: true });
+export async function tick({ root, lanes, settings, only = null, slugs = null, dispatch = true, params = {} }) {
+  // a verb's flags (dispatch --max, --failure-limit) are params of this tick, read by the workflow as its own
+  const loaded = await loadWorkflow(root, { fresh: true });
+  const entry = { ...loaded, params: { ...loaded.params, ...params } };
   const needFleet = Object.values(lanes).some((l) => l.surface === 'pane');
   const fleetAt = Date.now();
   const fleet = needFleet ? observeFleet() : { ok: false, alive: new Set(), online: new Set(), sessions: [], error: 'no pane lanes' };
@@ -1103,7 +1084,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       // what the moves asked for, once they are committed (messages to actors, closed panes, cleaned workspaces)
       await runEffects(board, effects);
       phase('goals');
-      await notify(board, fleet, report); phase('notify');
+      await notify(board, fleet, report, entry); phase('notify');
       fireHooks(board, settings, report);
       if (String(board.db.prepare('PRAGMA journal_mode').get()?.journal_mode).toLowerCase() === 'wal') board.db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get();
       report.ready_waiting = Number(board.db.prepare("SELECT COUNT(*) AS n FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.status = 'ready' AND t.assignee IS NOT NULL AND c.subtask_of IS NULL").get().n);

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 { fire, initialStatus, loadWorkflow, setStatus, settle, statusOf, workflowFor } from './workflow.mjs';
+import { fire, loadWorkflow, setStatus, settle, startNew, statusOf, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
 export const BLOCK_KINDS = ['dependency', 'needs_input', 'capability', 'transient'];
@@ -130,15 +130,6 @@ function retryStatus(db, taskId) {
   return source === 'review' || source === 'triage' ? source : '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
 
 /**
@@ -203,8 +194,9 @@ export function createCard(board, spec) {
     for (const p of parents) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', p, id);
     // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
     const entry = workflowFor(board.root);
-    const status = initialStatus(db, board, entry, getTask(db, id), { triage: Boolean(spec.triage), initial_status: initial });
-    setStatus(db, entry.workflow, id, status);
+    // 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 });
     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) {
@@ -289,35 +281,6 @@ export function extendClaim(db, id, { ttl, reason, extra = {} }) {
   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;
-}
-
-
 /**
  * A completed card's workspace goes, as Hermes cleans up on completion: a scratch directory under the board's own
  * workspaces, or a worktree (its branch stays); never while a child still waits on it, never a `dir`.
@@ -449,7 +412,7 @@ export const reclaim = (board, id, reason = null, { roles } = {}) => act(board,
 export const archive = (board, id, { roles } = {}) => act(board, id, 'archive', { roles });
 export const specify = (board, id, { title = null, body = null, author = 'user', roles } = {}) => act(board, id, 'specify', { roles, payload: { title, body, author } });
 export const editResult = (board, id, { result, summary = null, metadata = undefined, roles } = {}) => act(board, id, 'edit', { roles, payload: { result, summary, metadata } });
-export const heartbeat = (board, id, note = null, { roles } = {}) => act(board, id, 'heartbeat', { roles, payload: { note } });
+export const heartbeat = (board, id, note = null, { roles, until = null } = {}) => act(board, id, 'heartbeat', { roles, payload: { note, until } });
 export const setModel = (board, id, model = null, provider = null, { roles } = {}) => {
   if (provider && !model) throw new Error('a provider needs a model');
   return act(board, id, 'set_model', { roles, payload: { model: model || null, provider: provider || null } });
@@ -539,9 +502,9 @@ export const subscriptions = (db, id = null) => (id ? all(db, 'SELECT * FROM kan
 // ------------------------------------------------------------------ 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);
+  const rows = all(db, `SELECT t.*, c.machine, c.subtask_of, c.stage FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id
+    WHERE (? IS NULL OR t.status = ? OR c.stage = ?) 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, status, assignee, assignee, machine, machine, includeArchived ? 1 : 0);
   return rows.map((r) => ({ ...r, skills: json(r.skills, []) ?? [] }));
 }
 

package/board/workflow.mjs

@@ -98,10 +98,14 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
     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',
+    // where the latest interruption says the card resumes (any status the workflow declares); none recorded: null
+    resume_status: interruption.resume_status ?? interruption.retry_status ?? interruption.source_status ?? null,
     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),
+    // the latest event of each kind on the card: kind → { created_at, payload }
+    last_events: Object.fromEntries(all(db, 'SELECT e.kind, e.created_at, e.payload FROM task_events e JOIN (SELECT kind, MAX(id) AS id FROM task_events WHERE task_id = ? GROUP BY kind) l ON l.id = e.id', task.id)
+      .map((r) => [r.kind, { created_at: r.created_at, payload: json(r.payload, {}) ?? {} }])),
     comments_since: (t) => all(db, 'SELECT author, body, created_at FROM task_comments WHERE task_id = ? AND created_at >= ?', task.id, t),
   };
   return {
@@ -235,12 +239,20 @@ function dueAfter(db, workflow, task, status, scope) {
   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 });
+/**
+ * Where a new card starts: the first `initial` transition that holds (`event` is the create's own words), its status
+ * set and its actions run (a goal card by the workflow's default, for one). Answers the status.
+ */
+export function startNew(db, board, entry, task, event) {
+  const scope = scopeOf(db, board, task, { params: entry.params, event, extra: { lanes: lanesIn(entry) } });
   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));
+  const status = String(templateValue(t.target, scope));
+  if (!entry.workflow.statuses[status]) throw new Error(`the workflow starts a new card in ${status}, which it does not declare`);
+  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);
+  return status;
 }
 
 // ------------------------------------------------------------------ actions
@@ -270,7 +282,8 @@ const FORMAT = {
   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 }),
+  // the reviewer is the lane that reviewed (the card's assignee while in review), unless the verdict names one
+  changes_requested: ({ e, before, after }) => ({ reason: e.reason ?? null, reviewer: e.reviewer ?? before.assignee ?? 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 }),
@@ -283,7 +296,7 @@ const FORMAT = {
   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),
+  heartbeat: ({ e }) => (e.note || e.until ? { ...(e.note ? { note: e.note } : {}), ...(e.until ? { until: Number(e.until) } : {}) } : 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 }),

package/package.json

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