@volter/supercode-orchestrator 0.4.17 → 0.4.18

package/board/dispatch.mjs

@@ -106,6 +106,11 @@ export function boardSettings(kanban = {}) {
     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,
+    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,
   };
 }
 
@@ -141,6 +146,13 @@ function supervise(board, fleet, settings, report) {
         return;
       }
       if (session?.surface === 'headless') {
+        // Hermes's stale check: a worker running past the timeout with no heartbeat in the last hour is stopped
+        if (settings.staleTimeout && runRow && t - Number(runRow.started_at) >= settings.staleTimeout && !(task.last_heartbeat_at && t - Number(task.last_heartbeat_at) < 3600)) {
+          stop.push(session);
+          release(db, id, { outcome: 'stale', error: `no heartbeat after ${t - Number(runRow.started_at)}s running`, kind: 'stale', payload: { timeout_seconds: settings.staleTimeout, pid: session.pid } });
+          report.reclaimed.push(id);
+          return;
+        }
         if (pidAlive(session.pid)) {
           if (Number(task.claim_expires) <= t + 60) extendClaim(db, id, { ttl: settings.ttl, reason: 'pid_alive', extra: { worker_pid: session.pid } });
           return;
@@ -228,6 +240,38 @@ function guard(db, task, lane, fleet, settings) {
   return null;
 }
 
+// Hermes's respawn guard, for a one-shot (headless) worker: no respawn while the last failure is an auth or quota
+// wall, after a completion nobody requeued, or while a pull request is open on the card. A pane session is resumed
+// rather than respawned, so it never runs twice and these do not apply.
+const BLOCKER = /\b(quota|rate[\s_-]?limit|429|403|auth\w*|unauthorized|forbidden|billing|subscription|access[\s_]denied|permission[\s_]denied|invalid[\s_]api[\s_]key)\b/i;
+const PR_URL = /https?:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/\d+/i;
+
+function respawnGuard(db, task, settings, lane) {
+  const t = now();
+  const last = db.prepare('SELECT outcome, ended_at FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL ORDER BY ended_at DESC LIMIT 1').get(task.id);
+  if (last?.outcome === 'rate_limited') return settings.rateLimitCooldown > 0 && t - Number(last.ended_at) < settings.rateLimitCooldown ? 'rate_limit_cooldown' : null;
+  if (task.last_failure_error && BLOCKER.test(task.last_failure_error)) return 'blocker_auth';
+  if (lane === 'review') return null;
+  const done = db.prepare("SELECT ended_at FROM task_runs WHERE task_id = ? AND outcome = 'completed' AND ended_at >= ? ORDER BY ended_at DESC LIMIT 1").get(task.id, t - 3600);
+  if (done && !db.prepare("SELECT 1 FROM task_events WHERE task_id = ? AND created_at >= ? AND kind IN ('status', 'promoted', 'unblocked', 'reclaimed') LIMIT 1").get(task.id, done.ended_at)) return 'recent_success';
+  for (const c of db.prepare('SELECT body FROM task_comments WHERE task_id = ? AND created_at >= ?').all(task.id, t - 86400)) if (PR_URL.test(c.body ?? '')) return 'active_pr';
+  return null;
+}
+
+/** This machine's memory pressure as Hermes reads it (Linux's MemAvailable; `unknown` elsewhere, which restricts nothing). */
+function memoryPressure() {
+  try {
+    const info = Object.fromEntries(readFileSync('/proc/meminfo', 'utf8').split('\n').map((l) => /^(\w+):\s+(\d+)/.exec(l)).filter(Boolean).map((m) => [m[1], Number(m[2])]));
+    const avail = info.MemAvailable;
+    const total = info.MemTotal;
+    if (!Number.isFinite(avail)) return 'unknown';
+    const fraction = total > 0 ? avail / total : null;
+    if (avail < 64 * 1024 || (fraction !== null && fraction < 0.05)) return 'critical';
+    if (avail < 128 * 1024 || (fraction !== null && fraction < 0.15)) return 'elevated';
+    return 'ok';
+  } catch { return 'unknown'; }
+}
+
 /** 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);
@@ -237,6 +281,8 @@ function noteGuard(db, id, reason) {
 
 function start(board, fleet, lanes, settings, report, { only = null } = {}) {
   const lanesWanted = settings.reviewDispatch ? "('ready', 'review')" : "('ready')";
+  const pressure = memoryPressure();
+  let headlessStarted = 0;
   const rows = board.db.prepare(`SELECT id, status, assignee FROM tasks WHERE status IN ${lanesWanted} AND claim_lock IS NULL ORDER BY priority DESC, created_at ASC`).all();
   for (const row of rows) {
     if (only && row.id !== only) continue;
@@ -248,7 +294,12 @@ function start(board, fleet, lanes, settings, report, { only = null } = {}) {
     const claimed = tx(board, (db) => {
       const task = getTask(db, row.id);
       if (!task || task.status !== row.status || task.claim_lock) return null;
-      const why = guard(db, task, lane, fleet, settings);
+      let why = guard(db, task, lane, fleet, settings);
+      if (!why && lane.surface !== 'pane') {
+        // a one-shot worker runs on this machine: its memory, and Hermes's respawn guard
+        if (pressure === 'critical' || (pressure === 'elevated' && headlessStarted >= 1)) why = `this machine's memory pressure is ${pressure}; the card starts when it eases`;
+        else why = respawnGuard(db, task, settings, row.status);
+      }
       if (why) { noteGuard(db, row.id, why); report.queued.push([row.id, why]); return null; }
       if (!row.assignee) {
         db.prepare('UPDATE tasks SET assignee = ? WHERE id = ?').run(assignee, row.id);
@@ -259,7 +310,10 @@ function start(board, fleet, lanes, settings, report, { only = null } = {}) {
     });
     if (!claimed) continue;
     try {
-      const session = lane.surface === 'pane' ? launchPane(board, claimed.task, claimed.runId, lane, fleet) : launchHeadless(board, claimed.task, claimed.runId, lane, settings);
+      const session = lane.surface === 'pane'
+        ? launchPane(board, claimed.task, claimed.runId, lane, fleet, { input: row.status === 'review' ? reviewAsk(board, claimed.task) : null })
+        : launchHeadless(board, claimed.task, claimed.runId, lane, settings);
+      if (lane.surface !== 'pane') headlessStarted += 1;
       report.started.push([row.id, session.address ?? `pid ${session.pid}`, session.mode]);
     } catch (error) {
       tx(board, (db) => {
@@ -271,6 +325,50 @@ function start(board, fleet, lanes, settings, report, { only = null } = {}) {
   }
 }
 
+/** What a session started from the review lane is asked to do: verify the handoff and give the verdict. */
+function reviewAsk(board, task) {
+  const local = normalMachine(task.machine) === localMachine();
+  const where = local ? `--root ${board.root}${board.slug !== 'default' ? ` --board ${board.slug}` : ''}` : `--at ${boardAddress(board.label)}`;
+  return `You are reviewing card ${task.id} on the ${board.label} board: its implementer asked for review. Verify the handoff against the card's acceptance, `
+    + `then give the verdict: \`supercode workflow complete ${task.id} --summary "<what you verified>" ${where}\` approves it, and `
+    + `\`supercode workflow request-changes ${task.id} "<what must change>" ${where}\` sends it back.\n\n${tx(board, (db) => cardContext(db, task.id))}`;
+}
+
+/** What a session started on a triage card is asked to do: write its spec, or split it into cards it waits on. */
+function triageAsk(board, task, label, purpose) {
+  const local = normalMachine(task.machine) === localMachine();
+  const where = local ? `--root ${board.root}${board.slug !== 'default' ? ` --board ${board.slug}` : ''}` : `--at ${boardAddress(label)}`;
+  const context = tx(board, (db) => cardContext(db, task.id));
+  return purpose === 'decompose'
+    ? `Card ${task.id} on the ${label} board is in triage: a rough idea to split. Read it, then file the cards it breaks into and make it wait on them: `
+      + `\`supercode workflow decompose ${task.id} --child "<title>[@<profile>]" --child "..." ${where}\` (each child gets this card's machine and directory). `
+      + `The card itself stays and wakes when they are done.\n\n${context}`
+    : `Card ${task.id} on the ${label} board is in triage: a rough idea. Write its spec (the goal, the approach, what will show it is done), then file it: `
+      + `\`supercode workflow specify ${task.id} --title "<a tightened title>" --body "<the spec>" ${where}\`. The card then waits for its parents and starts.\n\n${context}`;
+}
+
+/**
+ * Start a session on a triage card to specify or decompose it (where Hermes asks an auxiliary model, supercode asks a
+ * session in the card's lane, which then keeps the card's memory when the card starts). Answers the session.
+ */
+export function startTriageSession(board, id, lanes, settings, purpose) {
+  const fleet = observeFleet();
+  const task = tx(board, (db) => getTask(db, id));
+  if (!task) throw new Error(`no card ${id}`);
+  if (task.status !== 'triage') throw new Error(`${id} is ${task.status}; only a triage card is ${purpose === 'decompose' ? 'decomposed' : 'specified'}`);
+  const lane = lanes[task.assignee || settings.defaultAssignee];
+  if (!lane || lane.surface !== 'pane') throw new Error(`${id} has no pane lane to start a session in; give its spec directly (${purpose === 'decompose' ? '--child' : '--title/--body'})`);
+  const runId = tx(board, (db) => {
+    const why = guard(db, task, lane, fleet, settings);
+    if (why) throw new Error(`${id} cannot start a session now: ${why}`);
+    return claimIn(db, id, { ttl: settings.ttl, expectStatus: 'triage' });
+  });
+  if (!runId) throw new Error(`${id} could not be claimed`);
+  return launchPane(board, getTaskNow(board, id), runId, lane, fleet, { input: triageAsk(board, task, board.label, purpose) });
+}
+
+const getTaskNow = (board, id) => tx(board, (db) => getTask(db, id));
+
 function opening(board, task, label) {
   const context = tx(board, (db) => cardContext(db, task.id));
   const skills = task.skills?.length ? `\nSkills pinned to this card: ${task.skills.join(', ')}.` : '';
@@ -279,13 +377,13 @@ function opening(board, task, label) {
   const local = normalMachine(task.machine) === localMachine();
   const where = local ? at : `--at ${boardAddress(label)}`;
   const door = `\nYour card is yours to keep current: \`supercode workflow comment ${task.id} "<text>" ${where}\`, \`block ${task.id} "<why>" --kind <needs_input|capability|transient|dependency> ${where}\` `
-    + `and \`review ${task.id} --summary "<what>" ${where}\` update it; \`create "<title>" --subtask-of ${task.id} ${where}\` files a subtask, and \`complete <subtask> ${where}\` marks one done`
+    + `and \`request-review ${task.id} --summary "<what>" ${where}\` update it; \`create "<title>" --subtask-of ${task.id} ${where}\` files a subtask, and \`complete <subtask> ${where}\` marks one done`
     + `${local ? '' : ' (each is filed with the board and answered by a board notice)'}. Its reviewers, not you, mark the card itself done.`;
   return `You are the session working card ${task.id} on the ${label} board. The board started you; updates to the card `
     + `(comments, reassignment, blocks, completion) and to the cards it waits on reach you as board notices.${door}${skills}\n\n${context}`;
 }
 
-function launchPane(board, task, runId, lane, fleet) {
+function launchPane(board, task, runId, lane, fleet, { input = null } = {}) {
   const machine = normalMachine(task.machine);
   const model = task.model_override ?? lane.model;
   const tail = model ? ['--model', model] : [];
@@ -309,7 +407,7 @@ function launchPane(board, task, runId, lane, fleet) {
   } else if (prev) replaced = { session_id: prev.session_id, why: `the card moved from ${prev.machine} to ${machine}` };
   if (!session) {
     const sid = randomUUID();
-    const r = sc([...base, '--key', `board-${task.id}-r${runId}-${sid.slice(0, 8)}`, '--input', opening(board, task, board.label), '--', '--session-id', sid, ...tail], { timeout: 180_000 });
+    const r = sc([...base, '--key', `board-${task.id}-r${runId}-${sid.slice(0, 8)}`, '--input', input ?? opening(board, task, board.label), '--', '--session-id', sid, ...tail], { timeout: 180_000 });
     if (r.code !== 0) throw new Error(`supercode open --on ${task.machine}: ${(r.stderr || r.stdout).trim().slice(-500)}`);
     session = { surface: 'pane', session_id: sid, machine, pane: lastJson(r.stdout)?.pane ?? null, mode: 'fresh', launched_at: now(), ...(replaced ? { replaces: replaced.session_id } : {}) };
   }
@@ -342,7 +440,9 @@ function paneSurvives(machine, pane) {
 /** Hermes's own worker argv and task environment, run on this machine; watched by its pid. */
 function launchHeadless(board, task, runId, lane, settings) {
   const workspace = resolveLocalWorkspace(board, task);
-  const args = ['-p', lane.name, '--cli', '--accept-hooks', ...task.skills.flatMap((s) => ['--skills', s]),
+  const reviewing = tx(board, (db) => json(db.prepare("SELECT payload FROM task_events WHERE task_id = ? AND run_id = ? AND kind = 'claimed'").get(task.id, runId)?.payload, {})?.source_status === 'review');
+  const skills = reviewing ? [...new Set([...task.skills, 'sdlc-review'])] : task.skills;
+  const args = ['-p', lane.name, '--cli', '--accept-hooks', ...skills.flatMap((s) => ['--skills', s]),
     ...(task.model_override ? ['-m', task.model_override, ...(task.provider_override ? ['--provider', task.provider_override] : [])] : []),
     ...(task.reasoning_effort ? ['--reasoning', task.reasoning_effort] : []), 'chat', '-q', `work kanban task ${task.id}`];
   const logDir = join(dirname(board.path), board.slug === 'default' ? 'kanban' : '', 'logs');
@@ -398,7 +498,7 @@ function resolveLocalWorkspace(board, task) {
  * never as the session describes itself. From then on the board watches it, resumes it when lost, and tells it of
  * its card. `who` is an address, a session id, or a `name@machine` the fleet lists.
  */
-export function attachSession(board, id, who, { workspace = null, ttl } = {}) {
+export function adoptSession(board, id, who, { workspace = null, ttl } = {}) {
   const fleet = observeFleet();
   if (!fleet.ok) throw new Error(`supercode could not read the fleet: ${fleet.error}`);
   const found = fleet.sessions.find((s) => s.address === who || s.address.endsWith(`:${who}`) || s.name === who);
@@ -528,7 +628,7 @@ function notify(board, fleet, report) {
 // ------------------------------------------------------------------ the board's mailbox
 
 const ENTRY = fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url));
-const NOT_BY_MAIL = new Set(['serve', 'dispatch', 'init', 'attach']);
+const NOT_BY_MAIL = new Set(['serve', 'daemon', 'dispatch', 'init', 'adopt', 'boards', 'gc', 'repair', 'watch', 'tail', 'attach']);
 
 /** The board's mailbox on this machine: the directory supercode files mail for `address` in, or null. */
 function mailboxOf(address) {
@@ -572,6 +672,62 @@ function readMailbox(board, address, report) {
   }
 }
 
+// ------------------------------------------------------------------ goals and triage
+
+/**
+ * Hermes's goal loop for a pane session: a goal card whose session sits idle while the card is still running is told
+ * to keep going, up to the card's turn budget; when the budget is spent the card is blocked for review. Whether the
+ * work is done is the session's call through its card (`request-review`), not an auxiliary judge's.
+ */
+function pursueGoals(board, fleet, settings, report) {
+  if (!fleet.ok) return;
+  const cards = board.db.prepare("SELECT id FROM tasks WHERE status = 'running' AND goal_mode = 1").all();
+  for (const { id } of cards) {
+    const nudge = tx(board, (db) => {
+      const task = getTask(db, id);
+      const runRow = currentRun(db, id);
+      const session = runRow?.metadata?.supercode;
+      if (!session?.session_id || session.surface !== 'pane') return null;
+      const live = fleet.sessions.find((x) => x.address?.endsWith(`:${session.session_id}`));
+      if (live?.status !== 'idle') return null;
+      if (session.goal_nudged_at && now() - session.goal_nudged_at < settings.interval * 2) return null;
+      const turns = Number(session.goal_turns ?? 0);
+      const budget = task.goal_max_turns ?? settings.goalMaxTurns;
+      if (turns >= budget) {
+        db.prepare("UPDATE tasks SET status = 'blocked', claim_lock = NULL, claim_expires = NULL WHERE id = ?").run(id);
+        const ended = endRun(db, id, { outcome: 'blocked', summary: `goal turn budget (${budget}) spent` });
+        event(db, id, 'blocked', { reason: `goal turn budget (${budget}) spent; review it`, kind: 'needs_input', source_status: 'ready' }, ended);
+        return null;
+      }
+      setRunSession(db, runRow.id, { ...session, goal_turns: turns + 1, goal_nudged_at: now() });
+      event(db, id, 'goal_continued', { turn: turns + 1, budget }, runRow.id);
+      return { address: live.address, text: `Card ${id} (${task.title}) is not done yet: keep working toward it (goal turn ${turns + 1} of ${budget}). When it is done, \`request-review\` it; if you are stuck, \`block\` it with its kind.` };
+    });
+    if (nudge) {
+      try { send(boardAddress(board.label), board.label, nudge.address, nudge.text, `board-goal-${id}-${now()}`); report.notified.push([id, 'goal_continued', nudge.address]); }
+      catch (error) { report.undelivered.push([id, nudge.address, String(error.message).slice(-200)]); }
+    }
+  }
+}
+
+/** Hermes's auto-decompose: triage cards with a pane lane get a session that splits them, a few per tick. */
+function autoDecompose(board, lanes, settings, report) {
+  if (!settings.autoDecompose) return;
+  let started = 0;
+  for (const { id, assignee } of board.db.prepare("SELECT id, assignee FROM tasks WHERE status = 'triage' ORDER BY priority DESC, created_at ASC").all()) {
+    if (started >= settings.autoDecomposePerTick) break;
+    const lane = lanes[assignee || settings.defaultAssignee];
+    if (lane?.surface !== 'pane') continue;
+    try {
+      const session = startTriageSession(board, id, lanes, settings, 'decompose');
+      report.started.push([id, session.address, 'decompose']);
+      started += 1;
+    } catch (error) {
+      report.queued.push([id, String(error.message).slice(-300)]);
+    }
+  }
+}
+
 // ------------------------------------------------------------------ the tick
 
 /** The board's name in notices: the home's owner folder (`…/volter-manager/home` → `volter-manager`), and the slug. */
@@ -598,10 +754,10 @@ export function tick({ root, lanes, settings, only = null, slugs = null, dispatc
       supervise(board, fleet, settings, report);
       report.promoted = recomputeReady(board, settings.failureLimit);
       if (dispatch) start(board, fleet, lanes, settings, report, { only });
+      if (dispatch && !only) { pursueGoals(board, fleet, settings, report); autoDecompose(board, lanes, settings, report); }
       notify(board, fleet, report);
       // what a Hermes gateway serves around its dispatcher and this one does not: said by the caller
       report.chat_subscriptions = Number(board.db.prepare("SELECT COUNT(*) AS n FROM kanban_notify_subs WHERE platform != 'supercode'").get().n);
-      report.triage = Number(board.db.prepare("SELECT COUNT(*) AS n FROM tasks WHERE status = 'triage'").get().n);
     } catch (error) {
       report.error = error.message;
     } finally {

package/board/engine.mjs

@@ -105,7 +105,8 @@ function retryStatus(db, taskId) {
   const row = one(db, 'SELECT current_run_id FROM tasks WHERE id = ?', taskId);
   if (!row?.current_run_id) return 'ready';
   const claimed = one(db, "SELECT payload FROM task_events WHERE task_id = ? AND run_id = ? AND kind = 'claimed' ORDER BY id DESC LIMIT 1", taskId, row.current_run_id);
-  return json(claimed?.payload, {})?.source_status === 'review' ? 'review' : 'ready';
+  const source = json(claimed?.payload, {})?.source_status;
+  return source === 'review' || source === 'triage' ? source : 'ready';
 }
 
 /** The phase a card blocked out of comes back to (Hermes reads it off the latest interruption). */
@@ -151,12 +152,13 @@ export function createCard(board, spec) {
     while (one(db, 'SELECT 1 FROM tasks WHERE id = ?', id)) id = newTaskId();
     const t = now();
     run(db, `INSERT INTO tasks (id, title, body, assignee, status, priority, created_by, created_at, workspace_kind, workspace_path, branch_name,
-               tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+               tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id,
+               project_id, goal_mode, goal_max_turns)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       id, title, spec.body ?? null, spec.assignee || null, status, Number(spec.priority) || 0, spec.createdBy ?? 'user', t, ws.kind, ws.path,
       spec.branch ?? null, spec.tenant ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
-      spec.reasoning ?? null, spec.sessionId ?? null);
+      spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
     const machine = spec.machine ?? arc?.machine ?? null;
     if (machine || arc) run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id, machine, subtask_of) VALUES (?, ?, ?)', id, machine, arc?.id ?? null);
     for (const p of parents) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', p, id);
@@ -250,7 +252,8 @@ export function claim(board, id, { ttl, lock = claimer(), expectStatus = 'ready'
 
 /** `claim` inside the caller's own transaction (a dispatcher's guard and claim see one state). */
 export function claimIn(db, id, { ttl = claimTtl(), lock = claimer(), expectStatus = null } = {}) {
-  if (!parentsDone(db, id)) {
+  // a triage card is claimed to be specified, which does not wait on its parents
+  if (expectStatus !== 'triage' && !parentsDone(db, id)) {
     run(db, "UPDATE tasks SET status = 'todo' WHERE id = ? AND status = 'ready'", id);
     event(db, id, 'claim_rejected', { reason: 'parents_not_done' });
     return null;
@@ -268,7 +271,7 @@ export function claimIn(db, id, { ttl = claimTtl(), lock = claimer(), expectStat
     id, task.assignee, task.current_step_key, lock, expires, task.max_runtime_seconds, t);
   const runId = Number(r.lastInsertRowid);
   run(db, 'UPDATE tasks SET current_run_id = ? WHERE id = ?', runId, id);
-  event(db, id, 'claimed', { lock, expires, run_id: runId, source_status: task.status === 'review' ? 'review' : 'ready' }, runId);
+  event(db, id, 'claimed', { lock, expires, run_id: runId, source_status: ['review', 'triage'].includes(task.status) ? task.status : 'ready' }, runId);
   return runId;
 }
 
@@ -323,6 +326,10 @@ export function complete(board, id, { result = null, summary = null, metadata =
     if (runId === null && (said || metadata || task.status === 'review')) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said ?? (task.status === 'review' ? 'Review approved without additional evidence.' : null), metadata });
     const first = String(said ?? '').trim().split('\n')[0].slice(0, 400);
     event(db, id, 'completed', { result_len: result ? result.length : 0, summary: first || null }, runId);
+    // card ids the handoff names that no card has (Hermes flags them the same way)
+    const named = [...new Set(`${summary ?? ''} ${result ?? ''}`.match(/\bt_[a-f0-9]{8,}\b/g) ?? [])];
+    const phantom = named.filter((t) => !one(db, 'SELECT 1 FROM tasks WHERE id = ?', t));
+    if (phantom.length) event(db, id, 'suspected_hallucinated_references', { phantom_refs: phantom, source: 'completion_summary' }, runId);
     recomputeIn(db);
   });
 }
@@ -380,7 +387,9 @@ export function requestChanges(board, id, { reason = null, reviewer = null, impl
   return tx(board, (db) => {
     const task = must(db, id);
     if (task.status !== 'review' && !(task.status === 'running' && retryStatus(db, id) === 'review')) throw new Error(`${id} is not in review`);
-    const back = implementer ?? task.assignee;
+    // back to the implementer the review request recorded, not to the reviewer now holding it
+    const asked = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", id)?.payload, {}) ?? {};
+    const back = implementer ?? asked.implementer ?? task.assignee;
     run(db, "UPDATE tasks SET status = ?, assignee = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", parentsDone(db, id) ? 'ready' : 'todo', back, id);
     const runId = endRun(db, id, { outcome: 'changes_requested', summary: reason });
     event(db, id, 'changes_requested', { reason, reviewer, implementer: back }, runId);
@@ -545,3 +554,212 @@ export function cardContext(db, id) {
   }
   return out.join('\n');
 }
+
+// ------------------------------------------------------------------ the rest of Hermes's verbs
+
+/** A triage card gets its spec (a tightened title and a body) and waits in todo for its parents, as Hermes's specifier leaves it. */
+export function specify(board, id, { title = null, body = null, author = 'user' } = {}) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'triage' && task.status !== 'running') throw new Error(`${id} is ${task.status}; only a triage card is specified`);
+    if (title && String(title).trim()) run(db, 'UPDATE tasks SET title = ? WHERE id = ?', String(title).trim(), id);
+    if (body !== null) run(db, 'UPDATE tasks SET body = ? WHERE id = ?', body, id);
+    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
+    const runId = endRun(db, id, { outcome: 'specified', summary: 'specified' });
+    event(db, id, 'specified', { author, title_changed: Boolean(title), body_len: body ? body.length : 0 }, runId);
+    recomputeIn(db);
+  });
+}
+
+/**
+ * A triage card fans out into children it waits on (Hermes's decomposer: the root stays and is the child of every
+ * leaf, so it wakes when the graph is done). `children` are `{ title, body?, assignee? }`; answers their ids.
+ */
+export function decompose(board, id, children, { author = 'user' } = {}) {
+  if (!children.length) throw new Error('decompose names at least one child (--child "<title>[@<assignee>]")');
+  const task = tx(board, (db) => must(db, id));
+  if (task.status !== 'triage' && task.status !== 'running') throw new Error(`${id} is ${task.status}; only a triage card is decomposed`);
+  const ids = children.map((c) => createCard(board, {
+    title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
+    workspace: task.workspace_path ? `${task.workspace_kind}:${task.workspace_path}` : task.workspace_kind, tenant: task.tenant, createdBy: author,
+  }).id);
+  tx(board, (db) => {
+    for (const child of ids) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', child, id);
+    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
+    const runId = endRun(db, id, { outcome: 'decomposed', summary: `decomposed into ${ids.join(', ')}` });
+    event(db, id, 'decomposed', { children: ids, author }, runId);
+  });
+  return ids;
+}
+
+/** Hermes's swarm: a completed root as the shared blackboard, workers after it, a verifier after them all, a synthesizer last. */
+export function swarm(board, { goal, workers, verifier, synthesizer, tenant = null, createdBy = 'swarm-orchestrator', priority = 0, idempotencyKey = null }) {
+  if (!String(goal ?? '').trim()) throw new Error('a swarm has a goal');
+  if (!workers.length) throw new Error('a swarm has at least one --worker PROFILE:TITLE[:SKILL,SKILL]');
+  const protocol = (root) => `\n\n## Swarm protocol\n- Swarm root / shared blackboard: \`${root}\`.\n- Read sibling/parent handoffs from the board's context before working.\n`
+    + `- Put machine-readable facts in completion metadata.\n- Put cross-worker notes on the root card as comments.\n- Goal: ${goal.trim()}\n`;
+  const root = createCard(board, { title: `Swarm: ${goal.trim()}`.slice(0, 200), body: goal, tenant, createdBy, priority, idempotencyKey, initialStatus: 'blocked' });
+  if (root.existing) return { root_id: root.id, existing: true };
+  tx(board, (db) => {
+    run(db, "UPDATE tasks SET status = 'done', completed_at = ? WHERE id = ?", now(), root.id);
+    const runId = synthesizeRun(db, root.id, { outcome: 'completed', summary: 'swarm blackboard', metadata: { swarm: true } });
+    event(db, root.id, 'completed', { result_len: 0, summary: 'swarm blackboard' }, runId);
+  });
+  const workerIds = workers.map((w) => createCard(board, { title: w.title, body: `${w.title}${protocol(root.id)}`, assignee: w.profile, skills: w.skills, parents: [root.id], tenant, createdBy, priority }).id);
+  const verifierId = createCard(board, { title: 'Verify swarm outputs', body: `Verify the workers' outputs.${protocol(root.id)}`, assignee: verifier, parents: workerIds, tenant, createdBy, priority }).id;
+  const synthesizerId = createCard(board, { title: 'Synthesize swarm outputs', body: `Synthesize the verified outputs.${protocol(root.id)}`, assignee: synthesizer, parents: [verifierId], tenant, createdBy, priority }).id;
+  return { root_id: root.id, worker_ids: workerIds, verifier_id: verifierId, synthesizer_id: synthesizerId };
+}
+
+/** Hermes's `edit`: correct a done card's result (and its completed run's summary and metadata). */
+export function editResult(board, id, { result, summary = null, metadata = undefined }) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'done') throw new Error(`${id} is ${task.status}; edit corrects a done card's result`);
+    run(db, 'UPDATE tasks SET result = ? WHERE id = ?', result, id);
+    const said = summary ?? result;
+    const last = one(db, "SELECT id FROM task_runs WHERE task_id = ? AND outcome = 'completed' ORDER BY COALESCE(ended_at, started_at, 0) DESC, id DESC LIMIT 1", id);
+    let runId = last ? Number(last.id) : null;
+    if (runId === null) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said, metadata: metadata ?? null });
+    else {
+      run(db, 'UPDATE task_runs SET summary = ? WHERE id = ?', said, runId);
+      if (metadata !== undefined) run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(metadata), runId);
+    }
+    event(db, id, 'edited', { fields: ['result', 'summary', ...(metadata !== undefined ? ['metadata'] : [])], result_len: result ? result.length : 0, summary: String(said ?? '').split('\n')[0].slice(0, 400) || null }, runId);
+  });
+}
+
+/** Send a card in review back to its implementer (ready, or todo while parents are open). */
+export function reopenReview(board, id) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'review') throw new Error(`${id} is ${task.status}, not in review`);
+    const handoff = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", id)?.payload, {}) ?? {};
+    const status = parentsDone(db, id) ? 'ready' : 'todo';
+    const implementer = typeof handoff.implementer === 'string' && handoff.implementer.trim() ? handoff.implementer : null;
+    run(db, `UPDATE tasks SET status = ?, current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL${implementer ? ', assignee = ?' : ''} WHERE id = ?`, ...(implementer ? [status, implementer, id] : [status, id]));
+    event(db, id, 'review_reopened', { status, ...(implementer ? { implementer } : {}) });
+    return status;
+  });
+}
+
+/** A running card's worker says it is alive (Hermes's `heartbeat`); the dispatcher does not rely on it. */
+export function heartbeat(board, id, note = null) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'running') throw new Error(`${id} is ${task.status}, not running`);
+    const t = now();
+    run(db, 'UPDATE tasks SET last_heartbeat_at = ? WHERE id = ?', t, id);
+    if (task.current_run_id) run(db, 'UPDATE task_runs SET last_heartbeat_at = ? WHERE id = ?', t, task.current_run_id);
+    event(db, id, 'heartbeat', note ? { note } : null, task.current_run_id);
+  });
+}
+
+/** A card's model (and provider) for its next start, or cleared. */
+export function setModel(board, id, model = null, provider = null) {
+  if (provider && !model) throw new Error('a provider needs a model');
+  return tx(board, (db) => {
+    must(db, id);
+    run(db, 'UPDATE tasks SET model_override = ?, provider_override = ? WHERE id = ?', model || null, provider || null, id);
+    event(db, id, 'model_override_set', { model: model || null, provider: provider || null });
+  });
+}
+
+export function addAttachment(board, id, { file, name, contentType = null, author = 'user', dir }) {
+  return tx(board, (db) => {
+    must(db, id);
+    const r = run(db, 'INSERT INTO task_attachments (task_id, filename, stored_path, content_type, size, uploaded_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)',
+      id, name, file.path, contentType, file.size, author, now());
+    event(db, id, 'attachment_added', { id: Number(r.lastInsertRowid), filename: name, size: file.size });
+    return Number(r.lastInsertRowid);
+  });
+}
+
+export const attachments = (db, id) => all(db, 'SELECT * FROM task_attachments WHERE task_id = ? ORDER BY id', id);
+
+export function removeAttachment(board, attachmentId) {
+  return tx(board, (db) => {
+    const row = one(db, 'SELECT * FROM task_attachments WHERE id = ?', attachmentId);
+    if (!row) throw new Error(`no attachment ${attachmentId}`);
+    run(db, 'DELETE FROM task_attachments WHERE id = ?', attachmentId);
+    event(db, row.task_id, 'attachment_removed', { id: Number(attachmentId), filename: row.filename });
+    return row;
+  });
+}
+
+/** Per status, per assignee, and the oldest ready card's age (Hermes's `stats`). */
+export function stats(db) {
+  const byStatus = {};
+  for (const r of all(db, "SELECT status, COUNT(*) AS n FROM tasks WHERE status != 'archived' GROUP BY status")) byStatus[r.status] = Number(r.n);
+  const byAssignee = {};
+  for (const r of all(db, "SELECT assignee, status, COUNT(*) AS n FROM tasks WHERE status != 'archived' AND assignee IS NOT NULL GROUP BY assignee, status")) (byAssignee[r.assignee] ??= {})[r.status] = Number(r.n);
+  const byMachine = {};
+  for (const r of all(db, "SELECT c.machine, t.status, COUNT(*) AS n FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE t.status != 'archived' AND c.machine IS NOT NULL GROUP BY c.machine, t.status")) (byMachine[r.machine] ??= {})[r.status] = Number(r.n);
+  const oldest = one(db, "SELECT MIN(created_at) AS ts FROM tasks WHERE status = 'ready'")?.ts;
+  const t = now();
+  return { by_status: byStatus, by_assignee: byAssignee, by_machine: byMachine, oldest_ready_age_seconds: oldest ? t - Number(oldest) : null, now: t };
+}
+
+export function runs(db, id, { stateType = null, stateName = null } = {}) {
+  must(db, id);
+  const where = stateType === 'status' ? ' AND status = ?' : stateType === 'outcome' ? ' AND outcome = ?' : '';
+  return all(db, `SELECT * FROM task_runs WHERE task_id = ?${where} ORDER BY id`, ...(where ? [id, stateName] : [id])).map((r) => ({ ...r, metadata: json(r.metadata, null) }));
+}
+
+/** Delete the thread events of done and archived cards older than `seconds` (Hermes's `gc` of events). */
+export function gcEvents(board, seconds) {
+  return tx(board, (db) => Number(run(db, "DELETE FROM task_events WHERE created_at < ? AND task_id IN (SELECT id FROM tasks WHERE status IN ('done', 'archived'))", now() - seconds).changes));
+}
+
+// ------------------------------------------------------------------ diagnostics
+
+const hours = (s) => s / 3600;
+
+/**
+ * Distress signals on a card, computed on demand and never stored (Hermes's diagnostics, the same kinds where the
+ * same thing can go wrong, and supercode's own where only its sessions can): each `{ kind, severity, title, data,
+ * actions }`, worst first.
+ */
+export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, strandedSeconds = 30 * 60, blockedHours = 24, fleet = null } = {}) {
+  const out = [];
+  const t = now();
+  const events = all(db, 'SELECT kind, payload, created_at FROM task_events WHERE task_id = ? ORDER BY id', task.id);
+  const failures = Number(task.consecutive_failures || 0);
+  if (failures >= Math.max(1, (task.max_retries ?? failureLimit) - 1) && task.status !== 'done') {
+    out.push({ kind: 'repeated_failures', severity: task.status === 'blocked' ? 'error' : 'warning', title: `${failures} consecutive failures`,
+      data: { failures, last_error: task.last_failure_error }, actions: [`supercode workflow reclaim ${task.id}`, `supercode workflow reassign ${task.id} <profile>`] });
+  }
+  const phantom = [...events].reverse().find((e) => e.kind === 'suspected_hallucinated_references');
+  if (phantom && !events.some((e) => e.kind === 'edited' && e.created_at > phantom.created_at)) {
+    out.push({ kind: 'prose_phantom_refs', severity: 'warning', title: 'its completion summary names card ids no card has', data: json(phantom.payload, {}) ?? {}, actions: [`supercode workflow edit ${task.id} --result <corrected>`] });
+  }
+  const lost = events.filter((e) => e.kind === 'session_lost' && t - e.created_at < 24 * 3600).length;
+  if (lost >= 2) out.push({ kind: 'repeated_session_loss', severity: 'warning', title: `its session was lost ${lost}x in 24h`, data: { lost }, actions: [`supercode workflow move ${task.id} <machine>`] });
+  const crashes = events.filter((e) => e.kind === 'crashed' && t - e.created_at < 24 * 3600).length;
+  if (crashes >= 2) out.push({ kind: 'repeated_crashes', severity: 'error', title: `its worker crashed ${crashes}x in 24h`, data: { crashes }, actions: [`supercode workflow log ${task.id}`] });
+  if (task.status === 'blocked') {
+    const since = [...events].reverse().find((e) => e.kind === 'blocked' || e.kind === 'gave_up')?.created_at ?? task.created_at;
+    if (hours(t - since) >= blockedHours) out.push({ kind: 'stuck_in_blocked', severity: 'warning', title: `blocked for ${Math.floor(hours(t - since))}h`, data: { hours: Math.floor(hours(t - since)) }, actions: [`supercode workflow unblock ${task.id}`] });
+    const cycles = events.filter((e) => e.kind === 'unblocked' && t - e.created_at < 24 * 3600).length;
+    if (cycles >= 3) out.push({ kind: 'block_unblock_cycling', severity: 'warning', title: `block→unblock cycled ${cycles}x in 24h`, data: { cycles }, actions: [] });
+  }
+  if (task.status === 'ready' && task.assignee) {
+    const since = [...events].reverse().find((e) => ['created', 'promoted', 'unblocked', 'reclaimed', 'session_lost', 'promoted_manual'].includes(e.kind))?.created_at ?? task.created_at;
+    const age = t - since;
+    if (age >= strandedSeconds) {
+      const guard = json([...events].reverse().find((e) => e.kind === 'respawn_guarded')?.payload, {})?.reason;
+      out.push({ kind: 'stranded_in_ready', severity: age >= strandedSeconds * 6 ? 'critical' : age >= strandedSeconds * 2 ? 'error' : 'warning',
+        title: `ready for ${Math.floor(age / 60)}m with no session`, data: { age_seconds: age, ...(guard ? { waiting_because: guard } : {}) }, actions: [`supercode workflow reassign ${task.id} <profile>`] });
+    }
+  }
+  if (task.status === 'review') {
+    const children = all(db, 'SELECT child_id FROM task_links WHERE parent_id = ?', task.id).length;
+    if (children) out.push({ kind: 'review_dependency_deadlock', severity: 'warning', title: `review handoff holds ${children} dependent card(s)`, data: { children }, actions: [`supercode workflow complete ${task.id}`] });
+  }
+  if (task.status === 'running' && fleet?.ok) {
+    const session = lastSession(db, task.id);
+    if (session?.machine && !fleet.online.has(session.machine)) out.push({ kind: 'machine_offline', severity: 'warning', title: `its machine ${session.machine} is offline`, data: { machine: session.machine }, actions: [] });
+  }
+  const order = ['critical', 'error', 'warning'];
+  return out.sort((a, b) => order.indexOf(a.severity) - order.indexOf(b.severity));
+}

package/board.mjs

@@ -54,7 +54,6 @@ export async function startBoard({ root, config = {}, log = () => {} }) {
         for (const [task, why] of r.failed ?? []) log('warn', `board ${r.board}: ${task} did not start: ${why}`);
         for (const [task, to, why] of r.undelivered ?? []) log('warn', `board ${r.board}: a notice for ${task} to ${to} was not delivered: ${why}`);
         if (r.chat_subscriptions && !said.has(`subs:${r.board}`)) { said.add(`subs:${r.board}`); log('warn', `board ${r.board}: ${r.chat_subscriptions} subscription(s) name a chat platform, which Hermes's gateway notifier serves and this dispatcher does not (it tells supercode sessions)`); }
-        if (r.triage && !said.has(`triage:${r.board}`)) { said.add(`triage:${r.board}`); log('warn', `board ${r.board}: ${r.triage} triage card(s) wait for decomposition, which Hermes's gateway runs on its auxiliary model and this dispatcher does not`); }
         if (r.nonspawnable?.length && !said.has(`lane:${r.board}`)) { said.add(`lane:${r.board}`); log('warn', `board ${r.board}: ${r.nonspawnable.length} card(s) name an assignee that is no profile of this home, and wait`); }
       }
     } finally {

package/package.json

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