@volter/supercode-orchestrator 0.4.18 → 0.4.20

package/adapters/chat-sdk.mjs

@@ -57,7 +57,7 @@
 // leaves the IR's queue as the single one. `extra.concurrency` overrides it.
 
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { parseDotenv } from '../orchestration.mjs';
 import { TOKEN_SCOPES, acquireTokenLock, releaseTokenLock } from '../hermes-locks.mjs';
 import { chunks } from './chunks.mjs';
@@ -438,15 +438,19 @@ export class ChatSdkAdapter {
     // A platform that caps a message's length gets the text in parts, in order, as Hermes's own adapters send it
     // (Discord refuses past 2000 characters, and a fire's report was cut off there). The first part is the handle.
     const limit = MESSAGE_LIMIT[this.platform];
+    const parts = limit ? chunks(content.text ?? '', limit) : [content.text ?? ''];
+    // files ride with the last part, as the Chat SDK uploads them (`{ markdown, files }`): `{ path }` read here, or `{ data, filename }`
+    const files = (content.files ?? []).map((f) => ({ data: f.data ?? readFileSync(f.path), filename: f.filename ?? basename(f.path), ...(f.mime ? { mimeType: f.mime } : {}) }));
     let first;
-    for (const [index, text] of (limit ? chunks(content.text ?? '', limit) : [content.text ?? '']).entries()) {
+    for (const [index, text] of parts.entries()) {
+      const message = files.length && index === parts.length - 1 ? { markdown: text, files } : text;
       let sent;
       if (thread) {
-        sent = content.reply_to && index === 0 ? await thread.reply(String(content.reply_to), text) : await thread.post(text);
+        sent = content.reply_to && index === 0 ? await thread.reply(String(content.reply_to), message) : await thread.post(message);
       } else if (threadId) {
-        sent = await this.sdkAdapter.postMessage(threadId, text);
+        sent = await this.sdkAdapter.postMessage(threadId, message);
       } else {
-        sent = await this.sdkAdapter.postChannelMessage(this.channelId(String(target.chat_id)), text);
+        sent = await this.sdkAdapter.postChannelMessage(this.channelId(String(target.chat_id)), message);
       }
       first ??= sent;
     }

package/board/cli.mjs

@@ -12,7 +12,7 @@ import { read } from '../orchestration.mjs';
 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, startTriageSession, tick } from './dispatch.mjs';
+import { adoptSession, boardLabel, boardSettings, lanesOf, localMachine, observeFleet, paused, startTriageSession, tick } from './dispatch.mjs';
 
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
 
@@ -34,12 +34,13 @@ Hermes Kanban's verbs, with their flags:
   diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
   notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
   dispatch [--dry-run] [--max N] [--failure-limit N]   daemon   gc [--event-retention-days] [--log-retention-days]   repair
+  pause [reason] · resume   (Hermes's emergency stop, the ESTOP file: new starts stop, running sessions go on)
 
 supercode's own:
   create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
       waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
-  move <id> <machine|none>   adopt <id> <session>   close <id>   serve (= daemon)   list --machine M
+  move <id> <machine|none>   adopt <id> <session> [--assignee P]   close <id>   serve (= daemon)   list --machine M
   notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
   Any verb … --at sc:<machine>:board:<home>: sent as mail to a board kept on another machine.
 
@@ -244,7 +245,7 @@ export async function runWorkflow(argv) {
       }), true);
       let answer = { id: created.id, existing: created.existing };
       if (!args['no-start'] && !created.existing && !args['subtask-of']) {
-        const [report] = tick({ root, lanes, settings, only: created.id, slugs: [slug] });
+        const [report] = await tick({ root, lanes, settings, only: created.id, slugs: [slug] });
         const started = report.started.find(([t]) => t === created.id);
         const queued = report.queued.find(([t]) => t === created.id);
         const failed = report.failed.find(([t]) => t === created.id);
@@ -626,7 +627,7 @@ export async function runWorkflow(argv) {
         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 = tick({ root, lanes, settings });
+      const reports = await tick({ root, lanes, settings });
       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;
@@ -677,10 +678,22 @@ export async function runWorkflow(argv) {
       return report.status === 'corrupt' ? 1 : 0;
     }
 
+    case 'pause': {
+      // Hermes's emergency stop: new starts stop on every board of the home; running sessions go on
+      writeFileSync(join(root, 'ESTOP'), `${JSON.stringify({ engaged_at: new Date().toISOString(), reason: rest.join(' ') || null })}\n`);
+      say(args, `New starts paused (${join(root, 'ESTOP')}); \`supercode workflow resume\` lifts it`, { ok: true, paused: join(root, 'ESTOP') });
+      return 0;
+    }
+    case 'resume': {
+      const lifted = [join(root, 'ESTOP'), join(process.env.HOME ?? '', '.hermes', 'ESTOP')].filter((p) => existsSync(p));
+      for (const p of lifted) unlinkSync(p);
+      say(args, lifted.length ? `Resumed (removed ${lifted.join(', ')})` : 'Not paused', { ok: true, lifted });
+      return 0;
+    }
     case 'adopt': {
       need(2, 'a card id and a session');
       const { settings } = await laneState(root);
-      const got = withBoard((b) => adoptSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl }));
+      const got = withBoard((b) => adoptSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl, assignee: args.assignee ?? null }));
       say(args, `${id} is worked by ${got.address} (pane ${got.pane ?? '?'} in ${got.workspace ?? 'its card\'s directory'})`, { ok: true, ...got });
       return 0;
     }
@@ -909,6 +922,9 @@ function authorize(db, verb, rest, args, own) {
     return;
   }
   if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
+  // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
+  if (['pause', 'resume', 'swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'reassign', 'assign', 'set-model', 'claim', 'reclaim', 'archive', 'promote', 'schedule', 'link', 'unlink', 'edit', 'reopen-review', 'attach-rm'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
+  if (args.all) refuse(`does not ${verb} every card; only its own`);
   const card = engine.getTask(db, rest[0]);
   if (!card) return; // the verb itself answers "no card"
   const mine = card.id === own.id;
@@ -961,15 +977,23 @@ async function serve(root) {
   process.on('SIGINT', stop);
   const log = (text) => process.stdout.write(`${new Date().toISOString()} ${text}\n`);
   log(`dispatching the boards of ${root} from ${localMachine()}`);
+  const stuck = {};
+  const warned = {};
+  let pausedSaid = false;
   try {
     while (!stopped) {
+      pausedSaid = Boolean(paused(root)) && pausedSaid;
       let interval = 60;
       try {
         const { lanes, settings } = await laneState(root);
         interval = settings.interval;
-        for (const r of tick({ root, lanes, settings })) {
+        for (const r of await tick({ root, lanes, settings })) {
           const said = summary(r);
           if (!said.endsWith('nothing to do')) log(said);
+          if (r.paused && !pausedSaid) { log(`new starts paused by ${r.paused} (\`supercode workflow resume\` lifts it)`); pausedSaid = true; }
+          // Hermes's stuck warning: ready work for six ticks running and nothing started
+          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(`board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${stuck[r.board]} ticks; \`supercode workflow diagnostics\``); warned[r.board] = Date.now(); }
           for (const [t, why] of r.failed) log(`  ${t} did not start: ${why}`);
           for (const [t, s, m] of r.started) log(`  ${t} started ${s} (${m})`);
           for (const [t, to, why] of r.undelivered) log(`  notice for ${t} to ${to} not delivered: ${why}`);

package/board/dispatch.mjs

@@ -15,12 +15,13 @@
 // subscriber's cursor moves only after its notice was delivered, so two dispatchers over one board never both
 // launch and a crash between the two steps is answered by the next tick.
 import { spawn as spawnChild, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync } from 'node:fs';
+import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname, tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { event, json, listBoards, now, openBoard, tx } from './store.mjs';
+import { boardPath, event, json, listBoards, now, openBoard, tx } from './store.mjs';
+import { holdBoardTickLock } from '../hermes-locks.mjs';
 import {
   cardContext, claimIn, claimTtl, currentRun, DEFAULT_FAILURE_LIMIT, extendClaim, getTask, lastSession,
   recomputeReady, recordFailure, release, setRunSession, subscribeIn, subscriptions,
@@ -110,6 +111,11 @@ export function boardSettings(kanban = {}) {
     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,
   };
 }
@@ -137,6 +143,14 @@ function supervise(board, fleet, settings, report) {
       const runRow = currentRun(db, id);
       const session = runRow?.metadata?.supercode ?? null;
       const t = now();
+      // 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) {
+        release(db, id, { outcome: 'reclaimed', error: 'orphaned running card (broken claim bookkeeping)', kind: 'reconciled', payload: { reason: 'orphaned_running', claim_lock: task.claim_lock, claim_expires: task.claim_expires } });
+        db.prepare('INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)').run(id, 'dispatcher', 'Requeued: the card was running with no claim and nothing live behind it.', t);
+        report.reclaimed.push(id);
+        return;
+      }
       // a card past its max runtime is stopped and counted, as Hermes times its workers out
       if (task.max_runtime_seconds && runRow && t - Number(runRow.started_at) > Number(task.max_runtime_seconds)) {
         stop.push(session);
@@ -158,8 +172,20 @@ function supervise(board, fleet, settings, report) {
           return;
         }
         if (t - Number(session.launched_at ?? 0) < 30) return;
-        release(db, id, { outcome: 'crashed', error: `worker ${session.pid} exited without completing the card`, kind: 'crashed', payload: { worker_pid: session.pid } });
-        if (recordFailure(db, id, `worker ${session.pid} exited without completing the card`, { failureLimit: settings.failureLimit })) report.auto_blocked.push(id);
+        // how the worker ended, from the exit code its wrapper wrote (Hermes reads its reaped children's)
+        const code = session.exit_file && existsSync(session.exit_file) ? Number(readFileSync(session.exit_file, 'utf8').trim()) : null;
+        if (code === 75) {
+          // a quota wall: back to ready with no failure counted; the respawn guard waits out the cooldown
+          release(db, id, { outcome: 'rate_limited', error: 'worker hit a rate limit (exit 75)', kind: 'rate_limited', payload: { worker_pid: session.pid, exit_code: 75 } });
+          report.crashed.push(id);
+          return;
+        }
+        const clean = code === 0;
+        const why = clean ? `worker ${session.pid} exited cleanly (rc=0) without completing or blocking the card` : `worker ${session.pid} exited${code === null ? '' : ` with ${code}`} without completing the card`;
+        release(db, id, { outcome: 'crashed', error: why, kind: 'crashed', payload: { worker_pid: session.pid, exit_code: code, protocol_violation: clean } });
+        // a clean exit that left the card running is a protocol violation: Hermes trips the breaker on the first
+        if (clean) db.prepare('UPDATE tasks SET consecutive_failures = ? WHERE id = ?').run(Math.max(0, (task.max_retries ?? settings.failureLimit) - 1), id);
+        if (recordFailure(db, id, why, { failureLimit: settings.failureLimit })) report.auto_blocked.push(id);
         report.crashed.push(id);
         return;
       }
@@ -202,7 +228,14 @@ function supervise(board, fleet, settings, report) {
 
 function stopSession(session) {
   if (!session) return;
-  if (session.surface === 'headless' && pidAlive(session.pid)) { try { process.kill(session.pid, 'SIGTERM'); } catch { /* gone */ } return; }
+  if (session.surface === 'headless' && pidAlive(session.pid)) {
+    // SIGTERM to the worker's process group, then SIGKILL if it is still there after a grace, as Hermes stops its own
+    const signal = (sig) => { try { process.kill(-session.pid, sig); } catch { try { process.kill(session.pid, sig); } catch { /* gone */ } } };
+    signal('SIGTERM');
+    for (let waited = 0; waited < 10 && pidAlive(session.pid); waited += 1) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 500);
+    if (pidAlive(session.pid)) signal('SIGKILL');
+    return;
+  }
   if (session.pane) sc(['teams', 'panes', 'close', session.pane, ...(session.machine ? ['--machine', session.machine] : [])], { timeout: 60_000 });
 }
 
@@ -224,8 +257,8 @@ function machineLoad(db, machine, fleet) {
 }
 
 /** Why a card cannot start now, or null. */
-function guard(db, task, lane, fleet, settings) {
-  if (settings.maxInProgress && running(db, '') >= settings.maxInProgress) return `the board runs ${settings.maxInProgress} cards at most (kanban.max_in_progress)`;
+function guard(db, task, lane, fleet, settings, budget = null) {
+  if (budget && budget.left <= 0) return budget.why;
   const cap = lane.capacity ?? settings.perProfile;
   if (cap && running(db, 'AND t.assignee = ?', lane.name) >= cap) return `${lane.name} is at capacity (${cap}); the card starts when one of its sessions ends`;
   if (lane.surface !== 'pane') return null;
@@ -235,7 +268,9 @@ function guard(db, task, lane, fleet, settings) {
   if (mcap && machineLoad(db, machine, fleet) >= mcap) return `machine ${machine} holds ${mcap} of the board's sessions (its capacity); the card starts when one is closed`;
   if (!fleet.ok) return `supercode could not read the fleet: ${fleet.error}`;
   if (!fleet.online.has(machine)) return `machine ${machine} is offline; the card starts when it is back`;
-  if (task.workspace_kind !== 'dir' || !task.workspace_path) return `a pane session starts in a directory on ${machine}: the card's workspace is dir:<absolute path>, not ${task.workspace_kind}`;
+  // a card on this machine gets its workspace made here (scratch, dir or worktree, as Hermes makes it); another
+  // machine's card names its directory there
+  if (machine !== localMachine() && (task.workspace_kind !== 'dir' || !task.workspace_path)) return `a pane session on ${machine} starts in a directory there: the card's workspace is dir:<absolute path>, not ${task.workspace_kind}`;
   if (lane.harness !== 'claude-code') return `a pane session's id is chosen at launch, which ${lane.harness} does not take; the lane's worker is claude-code`;
   return null;
 }
@@ -279,12 +314,39 @@ function noteGuard(db, id, reason) {
   event(db, id, 'respawn_guarded', { reason });
 }
 
-function start(board, fleet, lanes, settings, report, { only = null } = {}) {
-  const lanesWanted = settings.reviewDispatch ? "('ready', 'review')" : "('ready')";
+/** Hermes's emergency stop: the `ESTOP` sentinel in the home or in `~/.hermes` stops new starts (running ones go on). */
+export function paused(root) {
+  return [join(root, 'ESTOP'), join(process.env.HOME ?? '', '.hermes', 'ESTOP')].find((p) => existsSync(p)) ?? null;
+}
+
+/**
+ * The tick's spawn budget, as Hermes counts it: `kanban.max_spawn` against this board's running cards, and
+ * `kanban.max_in_progress` against every board of the home (workers share one machine's memory).
+ */
+function spawnBudget(board, settings, hostRunning) {
+  const here = Number(board.db.prepare("SELECT COUNT(*) AS n FROM tasks WHERE status = 'running'").get().n);
+  const limits = [];
+  if (settings.maxSpawn) limits.push([settings.maxSpawn - here, `the board runs ${settings.maxSpawn} cards at most (kanban.max_spawn)`]);
+  if (settings.maxInProgress) limits.push([settings.maxInProgress - hostRunning, `the home runs ${settings.maxInProgress} cards at most across its boards (kanban.max_in_progress)`]);
+  if (!limits.length) return null;
+  const [left, why] = limits.sort((a, b) => a[0] - b[0])[0];
+  return { left, why };
+}
+
+function start(board, fleet, lanes, settings, report, { only = null, hostRunning = 0 } = {}) {
+  const stop = paused(board.root);
+  if (stop) { report.paused = stop; return; }
   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) {
+  const order = 'ORDER BY priority DESC, created_at ASC';
+  const ready = board.db.prepare(`SELECT id, status, assignee FROM tasks WHERE status = 'ready' AND claim_lock IS NULL ${order}`).all();
+  const review = settings.reviewDispatch ? board.db.prepare(`SELECT id, status, assignee FROM tasks WHERE status = 'review' AND claim_lock IS NULL ${order}`).all() : [];
+  const budget = spawnBudget(board, settings, hostRunning);
+  // Hermes's review reservation: while review work waits, one slot of the budget is held back from the ready lane
+  const reviewWaits = review.some((r) => lanes[r.assignee || settings.defaultAssignee]);
+  const readyBudget = budget && budget.left > 0 && reviewWaits ? { left: budget.left - 1, why: `${budget.why}; one slot is held for review` } : budget;
+  for (const row of [...ready, ...review]) {
+    const lanesBudget = row.status === 'review' ? budget : readyBudget;
     if (only && row.id !== only) continue;
     if (board.db.prepare('SELECT subtask_of FROM supercode_cards WHERE task_id = ?').get(row.id)?.subtask_of) continue; // worked by its arc's session
     const assignee = row.assignee || settings.defaultAssignee;
@@ -294,7 +356,7 @@ 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;
-      let why = guard(db, task, lane, fleet, settings);
+      let why = guard(db, task, lane, fleet, settings, lanesBudget);
       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`;
@@ -314,6 +376,8 @@ function start(board, fleet, lanes, settings, report, { only = null } = {}) {
         ? 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;
+      if (budget) budget.left -= 1;
+      if (readyBudget && readyBudget !== budget) readyBudget.left -= 1;
       report.started.push([row.id, session.address ?? `pid ${session.pid}`, session.mode]);
     } catch (error) {
       tx(board, (db) => {
@@ -385,6 +449,11 @@ function opening(board, task, label) {
 
 function launchPane(board, task, runId, lane, fleet, { input = null } = {}) {
   const machine = normalMachine(task.machine);
+  if (machine === localMachine() && !(task.workspace_kind === 'dir' && task.workspace_path && existsSync(task.workspace_path))) {
+    const made = resolveLocalWorkspace(board, task);
+    tx(board, (db) => db.prepare('UPDATE tasks SET workspace_path = ? WHERE id = ?').run(made, task.id));
+    task = { ...task, workspace_path: made };
+  }
   const model = task.model_override ?? lane.model;
   const tail = model ? ['--model', model] : [];
   const base = ['open', '--new', 'claude', '--detach', '--on', task.machine, '--cwd', task.workspace_path];
@@ -447,10 +516,16 @@ function launchHeadless(board, task, runId, lane, settings) {
     ...(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');
   mkdirSync(logDir, { recursive: true });
-  const out = openSync(join(logDir, `${task.id}.log`), 'a');
-  const child = spawnChild(process.execPath, [WORKER, ...args], {
+  const logFile = join(logDir, `${task.id}.log`);
+  rotateLog(logFile, settings.logRotateBytes, settings.logBackups);
+  const out = openSync(logFile, 'a');
+  const exitFile = join(logDir, `${task.id}.r${runId}.exit`);
+  // the worker runs under a shell that records its exit code, so a later tick can tell a clean exit from a crash
+  const child = spawnChild('/bin/sh', ['-c', '"$0" "$@"; echo $? > "$SUPERCODE_BOARD_EXIT_FILE"', process.execPath, WORKER, ...args], {
     cwd: workspace, detached: true, stdio: ['ignore', out, out],
     env: {
+      SUPERCODE_BOARD_EXIT_FILE: exitFile,
+      ...(task.goal_mode ? { HERMES_KANBAN_GOAL_MODE: '1', ...(task.goal_max_turns ? { HERMES_KANBAN_GOAL_MAX_TURNS: String(task.goal_max_turns) } : {}) } : {}),
       ...process.env, HERMES_HOME: lane.dir, HERMES_PROFILE: lane.name, HERMES_KANBAN_TASK: task.id, HERMES_KANBAN_WORKSPACE: workspace,
       HERMES_KANBAN_RUN_ID: String(runId), HERMES_KANBAN_DB: board.path, HERMES_KANBAN_BOARD: board.slug, HERMES_SESSION_SOURCE: 'kanban',
       HERMES_KANBAN_CLAIM_LOCK: `${hostname()}:${process.pid}`, ...(task.tenant ? { HERMES_TENANT: task.tenant } : {}),
@@ -458,7 +533,7 @@ function launchHeadless(board, task, runId, lane, settings) {
     },
   });
   child.unref();
-  const session = { surface: 'headless', pid: child.pid, machine: normalMachine(hostname()), mode: 'fresh', launched_at: now() };
+  const session = { surface: 'headless', pid: child.pid, machine: localMachine(), mode: 'fresh', launched_at: now(), exit_file: exitFile };
   tx(board, (db) => {
     db.prepare('UPDATE tasks SET worker_pid = ? WHERE id = ?').run(child.pid, task.id);
     db.prepare('UPDATE task_runs SET worker_pid = ? WHERE id = ?').run(child.pid, runId);
@@ -468,6 +543,16 @@ function launchHeadless(board, task, runId, lane, settings) {
   return session;
 }
 
+/** Hermes's worker log rotation: past `max` bytes the log moves to `.1` (… `.n`), the oldest dropped. */
+function rotateLog(file, max, backups) {
+  try {
+    if (!existsSync(file) || statSync(file).size <= max) return;
+    if (backups === 0) { unlinkSync(file); return; }
+    for (let n = backups - 1; n >= 1; n -= 1) if (existsSync(`${file}.${n}`)) renameSync(`${file}.${n}`, `${file}.${n + 1}`);
+    renameSync(file, `${file}.1`);
+  } catch { /* a log that cannot rotate keeps growing */ }
+}
+
 /** A headless card's directory on this machine, made as Hermes makes it (scratch, dir, or a git worktree). */
 function resolveLocalWorkspace(board, task) {
   const root = board.root;
@@ -498,7 +583,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 adoptSession(board, id, who, { workspace = null, ttl } = {}) {
+export function adoptSession(board, id, who, { workspace = null, ttl, assignee = null } = {}) {
   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);
@@ -518,6 +603,8 @@ export function adoptSession(board, id, who, { workspace = null, ttl } = {}) {
     const was = lastSession(db, id);
     if (was && was.session_id !== sessionId && sessionAlive(fleet, was)) throw new Error(`${id} already has a live session, ${was.address}`);
     if (!task.machine) db.prepare('INSERT OR REPLACE INTO supercode_cards (task_id, machine, subtask_of) VALUES (?, ?, ?)').run(id, host, task.subtask_of);
+    // the lane that resumes it if it is lost, set in the same transaction (assigning first would let a tick start another)
+    if (assignee && assignee !== task.assignee) { db.prepare('UPDATE tasks SET assignee = ? WHERE id = ?').run(assignee, id); event(db, id, 'assigned', { assignee }); }
     if (dir && !(task.workspace_kind === 'dir' && task.workspace_path)) {
       db.prepare("UPDATE tasks SET workspace_kind = 'dir', workspace_path = ? WHERE id = ?").run(dir.replace(/^dir:/, ''), id);
     }
@@ -583,6 +670,9 @@ function send(from, label, to, body, key) {
 /** The board's own address: where its notices come from and where card updates are mailed. */
 export const boardAddress = (label) => `sc:${localMachine()}:board:${label.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
 
+/** Consecutive failed sends after which a subscription is dropped (Hermes's notifier drops a dead chat after 12). */
+const MAX_SEND_FAILURES = 12;
+
 function notify(board, fleet, report) {
   const from = boardAddress(board.label);
   for (const sub of subscriptions(board.db)) {
@@ -599,6 +689,7 @@ function notify(board, fleet, report) {
     if (!events.length) continue;
     const task = tx(board, (db) => getTask(db, sub.task_id));
     let cursor = Number(sub.last_event_id);
+    let failed = null;
     try {
       for (const ev of events) {
         const p = json(ev.payload, {}) ?? {};
@@ -615,16 +706,135 @@ function notify(board, fleet, report) {
         cursor = ev.id;
       }
     } catch (error) {
-      report.undelivered.push([sub.task_id, sub.chat_id, String(error.message).slice(-200)]);
+      failed = String(error.message).slice(-200);
+      report.undelivered.push([sub.task_id, sub.chat_id, failed]);
     }
     // the cursor moves past what was delivered (a failed delivery is retried next tick; the mail id dedupes)
     tx(board, (db) => {
-      db.prepare("UPDATE kanban_notify_subs SET last_event_id = ? WHERE task_id = ? AND platform = 'supercode' AND chat_id = ? AND last_event_id < ?").run(cursor, sub.task_id, sub.chat_id, cursor);
-      if (task?.status === 'archived' && cursor >= events.at(-1).id) db.prepare("DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?").run(sub.task_id, sub.chat_id);
+      const where = "WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?";
+      db.prepare(`UPDATE kanban_notify_subs SET last_event_id = ? ${where} AND last_event_id < ?`).run(cursor, sub.task_id, sub.chat_id, cursor);
+      const failures = failed ? Number(sub.delivery_metadata?.failures ?? 0) + 1 : 0;
+      if (failures >= MAX_SEND_FAILURES) { db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(sub.task_id, sub.chat_id); return; }
+      if (failures !== Number(sub.delivery_metadata?.failures ?? 0)) db.prepare(`UPDATE kanban_notify_subs SET delivery_metadata = ? ${where}`).run(JSON.stringify({ ...sub.delivery_metadata, failures }), sub.task_id, sub.chat_id);
+      if (task?.status === 'archived' && cursor >= events.at(-1).id) db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(sub.task_id, sub.chat_id);
     });
   }
 }
 
+// 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;
+ * `serve` hosts none, as a Hermes CLI without its gateway delivers none). Answers what was sent and what failed.
+ */
+export async function notifyChats(root, adapters, log = () => {}) {
+  const sent = [];
+  for (const slug of listBoards(root)) {
+    const board = openBoard(root, slug);
+    board.label = boardLabel(root, slug);
+    try {
+      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);
+        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');
+          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 })) : [];
+            try {
+              await adapter.send({ kind: 'explicit', platform: sub.platform, chat_id: sub.chat_id, ...(sub.thread_id ? { thread_id: sub.thread_id } : {}) }, { text: `${slug !== 'default' ? `[${slug}] ` : ''}${text}`, ...(files.length ? { files } : {}) });
+              sent.push([sub.task_id, ev.kind, `${sub.platform}:${sub.chat_id}`]);
+            } catch (error) {
+              failed = true;
+              log('warn', `board ${slug}: a notice for ${sub.task_id} to ${sub.platform}:${sub.chat_id} failed: ${error.message}`);
+              break;
+            }
+          }
+          cursor = ev.id;
+        }
+        tx(board, (db) => {
+          const where = 'WHERE task_id = ? AND platform = ? AND chat_id = ? AND thread_id = ?';
+          const key = [sub.task_id, sub.platform, sub.chat_id, sub.thread_id ?? ''];
+          db.prepare(`UPDATE kanban_notify_subs SET last_event_id = ? ${where} AND last_event_id < ?`).run(cursor, ...key, cursor);
+          const failures = failed ? Number(sub.delivery_metadata?.failures ?? 0) + 1 : 0;
+          if (failures >= MAX_SEND_FAILURES) db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(...key);
+          else if (failures !== Number(sub.delivery_metadata?.failures ?? 0)) db.prepare(`UPDATE kanban_notify_subs SET delivery_metadata = ? ${where}`).run(JSON.stringify({ ...sub.delivery_metadata, failures }), ...key);
+          if (task?.status === 'archived' && !failed) db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(...key);
+        });
+      }
+    } finally {
+      board.close();
+    }
+  }
+  return sent;
+}
+
+/** A completed card's artifact files: its completion's `artifacts`, then absolute paths its summary or result names that exist. */
+function artifactsOf(payload, task) {
+  const seen = new Set();
+  const out = [];
+  const add = (p) => {
+    const path = String(p ?? '').replace(/^~(?=\/)/, process.env.HOME ?? '~');
+    if (!path.startsWith('/') || seen.has(path)) return;
+    try { if (!statSync(path).isFile()) return; } catch { return; }
+    seen.add(path);
+    out.push(path);
+  };
+  for (const p of Array.isArray(payload.artifacts) ? payload.artifacts : []) add(p);
+  for (const text of [payload.summary, task?.result]) for (const m of String(text ?? '').matchAll(/(?:^|\s)(~?\/[^\s'"`]+\.[A-Za-z0-9]{1,8})/g)) add(m[1]);
+  return out;
+}
+
+// ------------------------------------------------------------------ hooks
+
+// Hermes's lifecycle hooks, from the board's own events (so a change any writer made fires them, Hermes's CLI's too)
+const HOOK_OF = {
+  claimed: 'kanban_task_claimed', completed: 'kanban_task_completed', blocked: 'kanban_task_blocked',
+  spawned: 'on_kanban_worker_spawned', session_started: 'on_kanban_worker_spawned', session_resumed: 'on_kanban_worker_spawned', session_replaced: 'on_kanban_worker_spawned', session_adopted: 'on_kanban_worker_spawned',
+  crashed: 'on_kanban_worker_exited', rate_limited: 'on_kanban_worker_exited', session_lost: 'on_kanban_worker_exited', timed_out: 'on_kanban_worker_exited',
+  stale: 'on_kanban_worker_stale_claim', reclaimed: 'on_kanban_worker_stale_claim',
+  assigned: 'on_kanban_task_updated', edited: 'on_kanban_task_updated', model_override_set: 'on_kanban_task_updated', machine_set: 'on_kanban_task_updated',
+  linked: 'on_kanban_task_updated', unlinked: 'on_kanban_task_updated', unblocked: 'on_kanban_task_updated', promoted: 'on_kanban_task_updated',
+  archived: 'on_kanban_task_updated', review_requested: 'on_kanban_task_updated', changes_requested: 'on_kanban_task_updated',
+};
+
+/**
+ * `kanban.hooks.<hook>: <command>` (or a list): each command runs with the event as one JSON object on its stdin, and
+ * nothing waits for it. Hermes runs Python plugins at these points; supercode runs any program.
+ */
+function fireHooks(board, settings, report) {
+  const hooks = settings.hooks ?? {};
+  if (!Object.keys(hooks).length) return;
+  const run = (hook, payload) => {
+    for (const command of [hooks[hook]].flat().filter((c) => typeof c === 'string' && c.trim())) {
+      const child = spawnChild('/bin/sh', ['-c', command], { detached: true, stdio: ['pipe', 'ignore', 'ignore'], cwd: board.root });
+      child.on('error', () => {});
+      child.stdin.on('error', () => {});
+      child.stdin.end(JSON.stringify({ hook, board: board.slug, ...payload }));
+      child.unref();
+    }
+  };
+  tx(board, (db) => {
+    db.exec('CREATE TABLE IF NOT EXISTS supercode_board_state (key TEXT PRIMARY KEY, value TEXT)');
+    const max = Number(db.prepare('SELECT COALESCE(MAX(id), 0) AS m FROM task_events').get().m);
+    const row = db.prepare("SELECT value FROM supercode_board_state WHERE key = 'hooks_cursor'").get();
+    const cursor = row ? Number(row.value) : max; // the first tick starts at the present, never replays history
+    for (const ev of db.prepare('SELECT e.id, e.task_id, e.run_id, e.kind, e.payload, e.created_at, t.assignee FROM task_events e LEFT JOIN tasks t ON t.id = e.task_id WHERE e.id > ? ORDER BY e.id').all(cursor)) {
+      const hook = HOOK_OF[ev.kind];
+      if (hook && hooks[hook]) run(hook, { task_id: ev.task_id, run_id: ev.run_id, event: ev.kind, assignee: ev.assignee, payload: json(ev.payload, null), at: ev.created_at });
+    }
+    db.prepare("INSERT INTO supercode_board_state (key, value) VALUES ('hooks_cursor', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(String(max));
+  });
+  if (hooks.on_kanban_dispatch_tick) run('on_kanban_dispatch_tick', { started: report.started.length, reclaimed: report.reclaimed.length, crashed: report.crashed.length, timed_out: report.timed_out.length, promoted: report.promoted });
+}
+
 // ------------------------------------------------------------------ the board's mailbox
 
 const ENTRY = fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url));
@@ -740,12 +950,32 @@ export function boardLabel(root, slug) {
  * One tick over every board of the home at `root`. `lanes` from `lanesOf`, `settings` from `boardSettings`.
  * `only` limits starting to one card (a create that answers whether its card started). Answers one report per board.
  */
-export function tick({ root, lanes, settings, only = null, slugs = null, dispatch = true }) {
+/** A board file's fingerprint: a corrupt board is skipped until the file changes (Hermes retries it then). */
+const fingerprint = (path) => { try { const st = statSync(path); return `${st.size}:${st.mtimeMs}`; } catch { return 'missing'; } };
+const CORRUPT = /malformed|not a database|corrupt|disk image/i;
+
+/**
+ * One tick over every board of the home at `root`. `lanes` from `lanesOf`, `settings` from `boardSettings`.
+ * `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 needFleet = Object.values(lanes).some((l) => l.surface === 'pane');
-  const fleet = needFleet ? observeFleet() : { ok: false, alive: new Set(), online: new Set(), error: 'no pane lanes' };
+  const fleet = needFleet ? observeFleet() : { ok: false, alive: new Set(), online: new Set(), sessions: [], error: 'no pane lanes' };
+  const boards = slugs ?? listBoards(root);
+  // the running cards of every board of the home, for kanban.max_in_progress (host-wide, as Hermes counts it)
+  let hostRunning = 0;
+  for (const slug of boards) {
+    try { const b = openBoard(root, slug); try { hostRunning += Number(b.db.prepare("SELECT COUNT(*) AS n FROM tasks WHERE status = 'running'").get().n); } finally { b.close(); } } catch { /* its own tick reports it */ }
+  }
   const out = [];
-  for (const slug of slugs ?? listBoards(root)) {
+  for (const slug of boards) {
     const report = { board: slug, mailed: [], started: [], queued: [], failed: [], lost: [], crashed: [], timed_out: [], reclaimed: [], auto_blocked: [], promoted: 0, unassigned: [], nonspawnable: [], notified: [], undelivered: [], fleet: fleet.ok ? 'read' : fleet.error };
+    const path = boardPath(root, slug);
+    const marker = `${path}.corrupt-seen`;
+    if (existsSync(marker) && readFileSync(marker, 'utf8').trim() === fingerprint(path)) { report.error = 'skipped: the board file was corrupt and has not changed since (`supercode workflow repair`)'; out.push(report); continue; }
+    let lock = null;
+    try { lock = await holdBoardTickLock(path); } catch (error) { report.skipped_locked = error.message; out.push(report); continue; }
     let board;
     try {
       board = openBoard(root, slug);
@@ -753,15 +983,23 @@ export function tick({ root, lanes, settings, only = null, slugs = null, dispatc
       readMailbox(board, boardAddress(board.label), report);
       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); }
+      const before = report.started.length;
+      if (dispatch) start(board, fleet, lanes, settings, report, { only, hostRunning });
+      hostRunning += report.started.length - before;
+      if (dispatch && !only && !report.paused) { pursueGoals(board, fleet, settings, report); autoDecompose(board, lanes, settings, report); }
       notify(board, fleet, report);
+      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);
       // 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);
+      if (existsSync(marker)) unlinkSync(marker);
     } catch (error) {
       report.error = error.message;
+      if (CORRUPT.test(error.message)) writeFileSync(marker, fingerprint(path));
     } finally {
       board?.close();
+      lock.release();
     }
     out.push(report);
   }

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'];
@@ -125,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');
@@ -150,6 +165,17 @@ 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,
@@ -314,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`);
@@ -325,7 +370,8 @@ 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));

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,18 +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)`); }
+        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.18",
+  "version": "0.4.20",
   "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": {