@volter/supercode-orchestrator 0.4.17 → 0.4.19

package/board/engine.mjs

@@ -7,6 +7,10 @@
 //
 // Each function takes an open board (`store.mjs`) and runs in one write transaction. Nothing here launches,
 // observes or sends: the dispatcher (`dispatch.mjs`) does, and records what it did through these.
+import { spawnSync } from 'node:child_process';
+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';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
@@ -105,7 +109,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). */
@@ -124,6 +129,17 @@ function resumeStatus(db, taskId) {
  * machine its session runs on. Answers its id; with an `idempotencyKey` a live card already filed under it is
  * answered instead.
  */
+/** A project in the home's `projects.db` (Hermes's registry), by id or slug; null when there is none. */
+function projectOf(root, idOrSlug) {
+  const file = join(root, 'projects.db');
+  if (!existsSync(file)) return null;
+  const db = new DatabaseSync(file, { readOnly: true });
+  try {
+    return db.prepare('SELECT id, slug, name, primary_path FROM projects WHERE id = ?').get(idOrSlug)
+      ?? db.prepare('SELECT id, slug, name, primary_path FROM projects WHERE slug = ?').get(String(idOrSlug).toLowerCase()) ?? null;
+  } catch { return null; } finally { db.close(); }
+}
+
 export function createCard(board, spec) {
   const title = String(spec.title ?? '').trim();
   if (!title) throw new Error('a card has a title');
@@ -149,14 +165,26 @@ export function createCard(board, spec) {
     else if (parents.some((p) => !['done', 'archived'].includes(one(db, 'SELECT status FROM tasks WHERE id = ?', p).status))) status = 'todo';
     let id = newTaskId();
     while (one(db, 'SELECT 1 FROM tasks WHERE id = ?', id)) id = newTaskId();
+    // a project (Hermes's projects registry, `projects.db` in the home) anchors the card's worktree in its repository
+    const project = spec.project ? projectOf(board.root, spec.project) : null;
+    if (project) {
+      if (ws.kind === 'scratch') ws.kind = 'worktree';
+      if (ws.kind === 'worktree' && !ws.path && project.primary_path) ws.path = join(project.primary_path, '.worktrees', id);
+      if (ws.kind === 'worktree' && !spec.branch) {
+        const t = title.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+        spec = { ...spec, branch: `${project.slug}/${id}${t ? `-${t}` : ''}` };
+      }
+    }
+    spec = { ...spec, project: project?.id ?? null };
     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 +278,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 +297,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;
 }
 
@@ -311,7 +340,26 @@ export function recordFailure(db, id, error, { failureLimit = DEFAULT_FAILURE_LI
   return true;
 }
 
-export function complete(board, id, { result = null, summary = null, metadata = null } = {}) {
+export function complete(board, id, opts = {}) {
+  completeIn(board, id, opts);
+  cleanupWorkspace(board, id);
+}
+
+/**
+ * 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`.
+ */
+function cleanupWorkspace(board, id) {
+  const task = tx(board, (db) => getTask(db, id));
+  if (!task?.workspace_path || !['scratch', 'worktree'].includes(task.workspace_kind)) return;
+  const waiting = tx(board, (db) => one(db, "SELECT 1 FROM task_links l JOIN tasks t ON t.id = l.child_id WHERE l.parent_id = ? AND t.status NOT IN ('done', 'archived') LIMIT 1", id));
+  if (waiting || !existsSync(task.workspace_path)) return;
+  if (task.workspace_kind === 'worktree') { spawnSync('git', ['-C', task.workspace_path, 'worktree', 'remove', '--force', task.workspace_path], { encoding: 'utf8' }); return; }
+  const managed = resolve(board.slug === 'default' ? join(board.root, 'kanban', 'workspaces') : join(board.root, 'kanban', 'boards', board.slug, 'workspaces'));
+  if (resolve(task.workspace_path).startsWith(`${managed}/`)) rmSync(task.workspace_path, { recursive: true, force: true });
+}
+
+function completeIn(board, id, { result = null, summary = null, metadata = null } = {}) {
   return tx(board, (db) => {
     const task = must(db, id);
     if (!parentsDone(db, id)) throw new Error(`${id} waits on parents that are not done`);
@@ -322,7 +370,12 @@ export function complete(board, id, { result = null, summary = null, metadata =
     let runId = endRun(db, id, { outcome: 'completed', status: 'done', summary: said, metadata: metadata ?? undefined });
     if (runId === null && (said || metadata || task.status === 'review')) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said ?? (task.status === 'review' ? 'Review approved without additional evidence.' : null), metadata });
     const first = String(said ?? '').trim().split('\n')[0].slice(0, 400);
-    event(db, id, 'completed', { result_len: result ? result.length : 0, summary: first || null }, runId);
+    const artifacts = Array.isArray(metadata?.artifacts) ? metadata.artifacts.filter((a) => typeof a === 'string' && a.trim()) : [];
+    event(db, id, 'completed', { result_len: result ? result.length : 0, summary: first || null, ...(artifacts.length ? { artifacts } : {}) }, 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 +433,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 +600,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/store.mjs

@@ -9,7 +9,7 @@
 // `engine.mjs`. Hermes's own tools may write the same file at the same time: every write takes SQLite's writer
 // lock (`BEGIN IMMEDIATE`) and retries while the other holds it.
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
@@ -78,7 +78,12 @@ export function listBoards(root) {
   const out = existsSync(boardPath(root)) ? [DEFAULT_BOARD] : [];
   const named = join(root, 'kanban', 'boards');
   if (existsSync(named)) {
-    for (const slug of readdirSync(named)) if (existsSync(boardPath(root, slug))) out.push(slug);
+    for (const slug of readdirSync(named)) {
+      if (slug.startsWith('_') || !existsSync(boardPath(root, slug))) continue;
+      // a board archived in its metadata is not dispatched (Hermes lists boards without the archived)
+      try { if (JSON.parse(readFileSync(join(named, slug, 'board.json'), 'utf8'))?.archived) continue; } catch { /* no metadata: live */ }
+      out.push(slug);
+    }
   }
   return out;
 }

package/board.mjs

@@ -11,6 +11,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { holdDispatcherLock } from './hermes-locks.mjs';
 import { summary } from './board/cli.mjs';
+import { notifyChats } from './board/dispatch.mjs';
 
 const ENTRY = fileURLToPath(new URL('./bin/orchestrator.mjs', import.meta.url));
 
@@ -30,7 +31,7 @@ function dispatchOnce(root) {
 }
 
 /** Start the board's dispatcher for the home at `root`; answers `{ tick, stop }`, or null when it does not dispatch. */
-export async function startBoard({ root, config = {}, log = () => {} }) {
+export async function startBoard({ root, config = {}, log = () => {}, adapters = {} }) {
   const kanban = config.kanban ?? {};
   const off = String(process.env.HERMES_KANBAN_DISPATCH_IN_GATEWAY ?? '').trim().toLowerCase();
   if (['0', 'false', 'no', 'off'].includes(off)) { log('info', 'board: not dispatched (HERMES_KANBAN_DISPATCH_IN_GATEWAY)'); return null; }
@@ -42,19 +43,27 @@ export async function startBoard({ root, config = {}, log = () => {} }) {
   let running = false;
   let stopped = false;
   const said = new Set();
+  const stuck = {};
+  const warned = {};
   const tick = async () => {
     if (running || stopped) return;
     running = true;
     try {
       const { reports, error } = await dispatchOnce(root);
       if (error) { log('warn', `board: tick failed: ${error}`); return; }
+      // chat-platform subscriptions are delivered here, through the daemon's own channel adapters
+      try { await notifyChats(root, adapters, log); } catch (error) { log('warn', `board: chat notices failed: ${error.message}`); }
       for (const r of reports) {
         const line = summary(r);
+        stuck[r.board] = r.ready_waiting && !r.started?.length && !r.paused ? (stuck[r.board] ?? 0) + 1 : 0;
+        if (stuck[r.board] >= 6 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log('warn', `board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${stuck[r.board]} ticks`); warned[r.board] = Date.now(); }
+        if (r.paused && !said.has(`paused:${r.board}`)) { said.add(`paused:${r.board}`); log('info', `board ${r.board}: new starts paused by ${r.paused}`); }
+        if (!r.paused) said.delete(`paused:${r.board}`);
         if (!line.endsWith('nothing to do')) log(r.error ? 'warn' : 'info', line);
         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`); }
+        const unserved = r.chat_subscriptions && !Object.keys(adapters).length;
+        if (unserved && !said.has(`subs:${r.board}`)) { said.add(`subs:${r.board}`); log('warn', `board ${r.board}: ${r.chat_subscriptions} subscription(s) name a chat platform and this daemon hosts no channel adapter to tell them`); }
         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/hermes-locks.mjs

@@ -13,7 +13,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 /** Hermes's gateway kind, the `kind` of every record it writes. */
 export const GATEWAY_KIND = 'hermes-gateway';
@@ -154,6 +154,14 @@ export function holdDispatcherLock(root, { python = 'python3' } = {}) {
   return holdFileLock(path, root, { python, what: `the board at ${resolve(root)} is dispatched by`, tail: 'one dispatcher serves a board' });
 }
 
+/**
+ * Hold one board's per-tick lock, `<kanban.db>.dispatch.lock` (Hermes's `_dispatch_tick_lock`), for one tick: a
+ * one-shot `dispatch` never ticks a board beside another dispatcher. Rejects, naming the holder, when it is held.
+ */
+export function holdBoardTickLock(dbPath, { python = 'python3' } = {}) {
+  return holdFileLock(`${dbPath}.dispatch.lock`, dirname(dbPath), { python, what: `the board ${dbPath} is being ticked by`, tail: 'one tick at a time' });
+}
+
 function holdFileLock(path, home, { python, what, tail }) {
   return new Promise((done, fail) => {
     let child;

package/loop.mjs

@@ -85,7 +85,7 @@ export class Orchestrator {
     // reject unhandled, which Node treats as fatal and which stopped the daemon
     if (this.autoTick) { this.timer = setInterval(() => { this.tick().catch(() => undefined); }, TICK_MS); this.timer.unref?.(); }
     // the home's board, dispatched as a Hermes gateway dispatches it (docs/plans/hermes-compat.md row 14)
-    if (this.autoTick) this.board = await startBoard({ root: this.state.root, config: this.state.profiles.default?.residue?.config ?? {}, log: this.log });
+    if (this.autoTick) this.board = await startBoard({ root: this.state.root, config: this.state.profiles.default?.residue?.config ?? {}, log: this.log, adapters: this.adapters });
   }
 
   /**

package/package.json

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