@volter/supercode-orchestrator 0.4.15 → 0.4.16

package/board/dispatch.mjs

@@ -0,0 +1,556 @@
+// The board's dispatcher (docs/architecture/orchestrator.md §2.9): one tick reads the fleet through supercode,
+// supervises every running card, promotes cards whose parents are done, starts what capacity allows, and tells
+// subscribers what happened. Hermes's dispatcher is the behaviour it keeps parity with (claims, dependencies,
+// review lane, failure breaker, caps, notify); what it adds is how a session runs, which the IR decides per
+// profile (`worker.surface`):
+//
+// - `pane`: an interactive session on the card's machine (`supercode open --new … --on <machine>`), started with a
+//   session id the dispatcher chose (`--session-id`) and recorded on the run. It stays open. It is live while
+//   supercode's fleet lists it; one missing for the whole grace on an online machine is lost, and the next start
+//   resumes it (`--resume`) before it ever replaces it from the card. Nothing asks the session about itself.
+// - `headless`: the profile's worker for one query on this machine (`bin/hermes-worker.mjs`, Hermes's worker
+//   argv and task environment), watched by its pid as Hermes watches its own.
+//
+// Every side effect follows a committed transition: a card is claimed before its session is launched, and a
+// 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, readFileSync, openSync } 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 {
+  cardContext, claimIn, claimTtl, currentRun, DEFAULT_FAILURE_LIMIT, extendClaim, getTask, lastSession,
+  recomputeReady, recordFailure, release, setRunSession, subscribeIn, subscriptions,
+} from './engine.mjs';
+
+const WORKER = fileURLToPath(new URL('../bin/hermes-worker.mjs', import.meta.url));
+const MAIL_KINDS = {
+  creator: ['completed', 'blocked', 'gave_up', 'crashed', 'timed_out', 'status', 'archived', 'block_loop_detected', 'review_requested',
+    'changes_requested', 'session_started', 'session_resumed', 'session_replaced', 'session_adopted', 'session_lost', 'spawn_failed'],
+  worker: ['commented', 'assigned', 'machine_set', 'blocked', 'unblocked', 'completed', 'archived', 'changes_requested', 'linked', 'unlinked', 'promoted_manual', 'subtask_added'],
+  // a card the session's own card depends on: it sees it change
+  dependency: ['completed', 'blocked', 'unblocked', 'archived', 'review_requested', 'changes_requested', 'commented'],
+};
+
+// ------------------------------------------------------------------ names and the fleet
+
+/** supercode's `normal_machine_name`: the form a machine takes in session addresses. */
+export function normalMachine(name) {
+  const short = String(name ?? '').split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+  return short || 'localhost';
+}
+
+/** This machine's name as supercode's addresses spell it: its Teams enrollment, else its host name. */
+export function localMachine() {
+  const home = process.env.SUPERCODE_TEAMS_HOME || join(process.env.SUPERCODE_HOME || (process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, 'supercode') : join(process.env.HOME ?? '', '.config', 'supercode')), 'teams');
+  try {
+    const contexts = JSON.parse(readFileSync(join(home, 'workspaces', 'contexts.json'), 'utf8'));
+    const ctx = contexts.contexts?.[contexts.current];
+    const enrollment = JSON.parse(readFileSync(join(home, 'workspaces', 'connectors', ctx.server_id, ctx.team_id, 'enrollment.json'), 'utf8'));
+    if (enrollment?.machine?.name) return normalMachine(enrollment.machine.name);
+  } catch { /* not enrolled: the host name */ }
+  return normalMachine(hostname());
+}
+
+/** The supercode command the dispatcher drives. */
+export const supercodeBin = () => process.env.SUPERCODE_BIN || 'supercode';
+
+function sc(args, { input = null, timeout = 120_000 } = {}) {
+  // a neutral directory: `supercode teams …` resolves its entry from a checkout at the cwd
+  const r = spawnSync(supercodeBin(), args, { cwd: tmpdir(), input: input ?? undefined, encoding: 'utf8', timeout, env: process.env });
+  return { code: r.status, stdout: r.stdout ?? '', stderr: (r.stderr ?? '') + (r.error ? r.error.message : '') };
+}
+
+const lastJson = (text) => {
+  const line = text.split('\n').map((l) => l.trim()).filter((l) => l.startsWith('{') || l.startsWith('[')).pop();
+  return line ? json(line, null) : null;
+};
+
+/**
+ * What supercode reports about the fleet now: `{ ok, alive: Set<address>, online: Set<machine>, error }`. `alive` is
+ * every session that can be messaged on every machine; `online` every enrolled machine connected to the team.
+ */
+export function observeFleet() {
+  const list = sc(['message', 'list', '--json']);
+  const sessions = list.code === 0 ? json(list.stdout.trim(), null) : null;
+  if (!Array.isArray(sessions)) return { ok: false, alive: new Set(), online: new Set(), error: `message list: ${(list.stderr || list.stdout).trim().slice(-300)}` };
+  const machines = sc(['teams', 'machines', 'list', '--json']);
+  const rows = machines.code === 0 ? lastJson(machines.stdout)?.items : null;
+  const online = new Set([localMachine()]);
+  for (const m of rows ?? []) if (m.enrollment === 'active' && m.connection === 'online') online.add(normalMachine(m.name));
+  return { ok: true, sessions, alive: new Set(sessions.map((s) => s.address).filter(Boolean)), online, error: rows ? null : 'teams machines list gave no answer; only this machine counts as online' };
+}
+
+const sessionAlive = (fleet, session) => Boolean(session?.session_id) && [...fleet.alive].some((a) => a.endsWith(`:${session.session_id}`));
+
+function pidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+// ------------------------------------------------------------------ settings
+
+/** The board's settings: the home's `kanban:` block, Hermes's keys and supercode's own (`machines`, `session_grace_seconds`). */
+export function boardSettings(kanban = {}) {
+  const pos = (v) => (Number.isInteger(Number(v)) && Number(v) >= 1 ? Number(v) : null);
+  return {
+    failureLimit: pos(kanban.failure_limit) ?? DEFAULT_FAILURE_LIMIT,
+    maxInProgress: pos(kanban.max_in_progress),
+    perProfile: pos(kanban.max_in_progress_per_profile),
+    defaultAssignee: String(kanban.default_assignee ?? '').trim() || null,
+    reviewDispatch: kanban.review_dispatch !== false,
+    ttl: claimTtl(kanban.claim_ttl_seconds),
+    grace: pos(kanban.session_grace_seconds) ?? 120,
+    machines: Object.fromEntries(Object.entries(kanban.machines ?? {}).map(([name, m]) => [normalMachine(name), { capacity: pos(m?.capacity) }])),
+    interval: Math.max(Number(kanban.dispatch_interval_seconds) || 60, 1),
+  };
+}
+
+/** Each profile's lane, from the IR: how its cards' sessions run and how many at once. */
+export function lanesOf(profiles = {}) {
+  const out = {};
+  for (const [name, p] of Object.entries(profiles)) {
+    const w = p?.worker;
+    if (!w?.harness) continue;
+    out[name] = { name, dir: p.dir, harness: w.harness, model: w.model ?? null, surface: w.surface ?? 'headless', capacity: w.capacity ?? null };
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ supervise
+
+function supervise(board, fleet, settings, report) {
+  const rows = board.db.prepare("SELECT id FROM tasks WHERE status = 'running'").all();
+  const stop = [];
+  for (const { id } of rows) {
+    tx(board, (db) => {
+      const task = getTask(db, id);
+      if (task?.status !== 'running') return;
+      const runRow = currentRun(db, id);
+      const session = runRow?.metadata?.supercode ?? null;
+      const t = now();
+      // 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);
+        release(db, id, { outcome: 'timed_out', error: `ran past max_runtime ${task.max_runtime_seconds}s`, kind: 'timed_out', payload: { limit_seconds: task.max_runtime_seconds } });
+        if (recordFailure(db, id, `timed out after ${task.max_runtime_seconds}s`, { failureLimit: settings.failureLimit, outcome: 'timed_out' })) report.auto_blocked.push(id);
+        report.timed_out.push(id);
+        return;
+      }
+      if (session?.surface === 'headless') {
+        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;
+        }
+        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);
+        report.crashed.push(id);
+        return;
+      }
+      if (session?.session_id) {
+        if (!fleet.ok) return; // no reading, no verdict
+        const alive = sessionAlive(fleet, session);
+        const machineUp = fleet.online.has(session.machine);
+        const young = t - Number(session.launched_at ?? 0) < settings.grace;
+        const missing = !alive && machineUp && !young;
+        const next = { ...session };
+        if (alive) { next.seen_at ??= t; delete next.missing_since; }
+        if (missing) next.missing_since ??= t;
+        if (missing && t - next.missing_since >= settings.grace) {
+          // lost: gone from an online machine for the whole grace. A resume that never came up is not resumable;
+          // a fresh start that never came up is a failure. The card goes back to ready and the spawn resumes it.
+          if (next.mode === 'resume' && !next.seen_at) next.resumable = false;
+          const whole = { ...(runRow.metadata ?? {}), supercode: next };
+          release(db, id, { outcome: 'reclaimed', error: `session ${next.session_id} is gone from ${next.machine}`, metadata: whole, kind: 'session_lost',
+            payload: { session_id: next.session_id, machine: next.machine, pane: next.pane, mode: next.mode, seen: Boolean(next.seen_at) } });
+          report.lost.push(id);
+          if (next.mode === 'fresh' && !next.seen_at && recordFailure(db, id, `session ${next.session_id} never came up on ${next.machine}`, { failureLimit: settings.failureLimit, outcome: 'crashed' })) report.auto_blocked.push(id);
+          return;
+        }
+        if (JSON.stringify(next) !== JSON.stringify(session)) setRunSession(db, runRow.id, next);
+        if (Number(task.claim_expires) <= t + 60) {
+          extendClaim(db, id, { ttl: settings.ttl, reason: alive ? 'session_alive' : !machineUp ? 'machine_offline' : young ? 'session_starting' : 'session_missing', extra: { session_id: next.session_id, machine: next.machine } });
+        }
+        return;
+      }
+      // claimed with nothing launched (a dispatcher that died between the two, or another implementation's claim):
+      // the claim's own expiry answers it, as Hermes's does
+      if (task.claim_expires && Number(task.claim_expires) < t) {
+        release(db, id, { outcome: 'reclaimed', error: `stale_lock=${task.claim_lock}`, kind: 'reclaimed', payload: { stale_lock: task.claim_lock, claim_expires: task.claim_expires } });
+        report.reclaimed.push(id);
+      }
+    });
+  }
+  for (const session of stop) stopSession(session); // after the transaction: a close is a network call
+}
+
+function stopSession(session) {
+  if (!session) return;
+  if (session.surface === 'headless' && pidAlive(session.pid)) { try { process.kill(session.pid, 'SIGTERM'); } catch { /* gone */ } return; }
+  if (session.pane) sc(['teams', 'panes', 'close', session.pane, ...(session.machine ? ['--machine', session.machine] : [])], { timeout: 60_000 });
+}
+
+// ------------------------------------------------------------------ start
+
+const running = (db, sql, ...args) => Number(db.prepare(`SELECT COUNT(*) AS n FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.status = 'running' ${sql}`).get(...args).n);
+
+/**
+ * How many sessions the board has on `machine`: every running card's, and every other card's latest session that is
+ * still live (an idle session on a done or blocked card holds its place until it is closed).
+ */
+function machineLoad(db, machine, fleet) {
+  let n = 0;
+  for (const card of db.prepare("SELECT t.id, t.status, c.machine FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE c.machine IS NOT NULL AND t.status != 'archived'").all()) {
+    if (normalMachine(card.machine) !== machine) continue;
+    if (card.status === 'running' || (fleet.ok && sessionAlive(fleet, lastSession(db, card.id)))) n += 1;
+  }
+  return n;
+}
+
+/** 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)`;
+  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;
+  if (!task.machine) return 'the card names no machine; a pane session runs on the machine its card names';
+  const machine = normalMachine(task.machine);
+  const mcap = settings.machines[machine]?.capacity;
+  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}`;
+  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;
+}
+
+/** 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);
+  if (json(last?.payload, {})?.reason === reason) return;
+  event(db, id, 'respawn_guarded', { reason });
+}
+
+function start(board, fleet, lanes, settings, report, { only = null } = {}) {
+  const lanesWanted = settings.reviewDispatch ? "('ready', 'review')" : "('ready')";
+  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;
+    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;
+    if (!assignee) { report.unassigned.push(row.id); continue; }
+    const lane = lanes[assignee];
+    if (!lane) { report.nonspawnable.push(row.id); continue; }
+    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);
+      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);
+        event(db, row.id, 'assigned', { assignee, source: 'kanban.default_assignee' });
+      }
+      const runId = claimIn(db, row.id, { ttl: settings.ttl, expectStatus: row.status });
+      return runId ? { task: getTask(db, row.id), runId } : 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);
+      report.started.push([row.id, session.address ?? `pid ${session.pid}`, session.mode]);
+    } catch (error) {
+      tx(board, (db) => {
+        release(db, row.id, { outcome: 'spawn_failed', error: String(error.message).slice(-500), kind: 'spawn_failed', payload: { error: String(error.message).slice(-300) } });
+        if (recordFailure(db, row.id, error.message, { failureLimit: settings.failureLimit, outcome: 'spawn_failed' })) report.auto_blocked.push(row.id);
+      });
+      report.failed.push([row.id, String(error.message).slice(-300)]);
+    }
+  }
+}
+
+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(', ')}.` : '';
+  const at = `--root ${board.root}${board.slug !== 'default' ? ` --board ${board.slug}` : ''}`;
+  // the board's own door is on the machine that keeps it; a session elsewhere writes to its card through its manager
+  const door = normalMachine(task.machine) === localMachine()
+    ? `\nYour card is yours to keep current: \`supercode workflow show ${task.id} ${at}\` reads it; \`comment\`, \`block --kind <needs_input|capability|transient|dependency>\` `
+      + `and \`review\` update it; \`create <title> --subtask-of ${task.id}\` files a subtask, and \`complete <subtask>\` marks one done. 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) {
+  const machine = normalMachine(task.machine);
+  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];
+  const prev = tx(board, (db) => lastSession(db, task.id));
+  let session = null;
+  let replaced = null;
+  if (prev && prev.machine === machine) {
+    if (sessionAlive(fleet, prev)) {
+      session = { ...prev, mode: 'adopt', launched_at: now(), seen_at: now() };
+      delete session.missing_since;
+    } else if (prev.resumable !== false) {
+      const r = sc([...base, '--key', `board-${task.id}-r${runId}-resume`, '--input',
+        `The board resumed this session after it was lost; you are still on card ${task.id}: ${task.title}. Carry on.`, '--', '--resume', prev.session_id, ...tail], { timeout: 180_000 });
+      const pane = r.code === 0 ? lastJson(r.stdout)?.pane ?? null : null;
+      // a resume the harness refuses (its transcript is gone) ends the pane at once; another machine's launch
+      // answers before that shows, so the pane is looked for again a moment later
+      if (pane && paneSurvives(task.machine, pane)) session = { surface: 'pane', session_id: prev.session_id, machine, pane, mode: 'resume', launched_at: now() };
+      else replaced = { session_id: prev.session_id, why: r.code === 0 ? `its resume ended as soon as it started (pane ${pane})` : (r.stderr || r.stdout).trim().slice(-300) };
+    } else replaced = { session_id: prev.session_id, why: 'its resume never came up' };
+  } 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 });
+    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 } : {}) };
+  }
+  session.harness = 'claude-code';
+  session.address = `sc:${machine}:claude-code:${session.session_id}`;
+  const kind = { adopt: 'session_adopted', resume: 'session_resumed', fresh: replaced ? 'session_replaced' : 'session_started' }[session.mode];
+  tx(board, (db) => {
+    setRunSession(db, runId, session);
+    event(db, task.id, kind, { session_id: session.session_id, machine, pane: session.pane, address: session.address, mode: session.mode, ...(replaced ? { replaced } : {}) }, runId);
+    // the working session hears updates to its card; a session no longer working it does not
+    for (const s of subscriptions(db, task.id)) {
+      if (s.delivery_metadata?.role === 'worker' && s.chat_id !== session.address) db.prepare("DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?").run(task.id, s.chat_id);
+    }
+    subscribeIn(db, task.id, session.address, 'worker');
+    // it sees the cards its own depends on change, and works its subtasks
+    for (const p of db.prepare('SELECT parent_id FROM task_links WHERE child_id = ?').all(task.id)) subscribeIn(db, p.parent_id, session.address, 'dependency');
+    for (const t of db.prepare('SELECT task_id FROM supercode_cards WHERE subtask_of = ?').all(task.id)) subscribeIn(db, t.task_id, session.address, 'worker');
+  });
+  return session;
+}
+
+/** Whether a pane just launched on `machine` is still there after the harness had a moment to start. */
+function paneSurvives(machine, pane) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 6000);
+  const r = sc(['teams', 'panes', 'ls', '--machine', machine], { timeout: 60_000 });
+  const panes = r.code === 0 ? json(r.stdout.trim(), null) : null;
+  return Array.isArray(panes) ? panes.some((p) => p.pane === pane) : true; // no reading: the grace decides
+}
+
+/** 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]),
+    ...(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');
+  mkdirSync(logDir, { recursive: true });
+  const out = openSync(join(logDir, `${task.id}.log`), 'a');
+  const child = spawnChild(process.execPath, [WORKER, ...args], {
+    cwd: workspace, detached: true, stdio: ['ignore', out, out],
+    env: {
+      ...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 } : {}),
+      ...(task.branch_name ? { HERMES_KANBAN_BRANCH: task.branch_name } : {}),
+    },
+  });
+  child.unref();
+  const session = { surface: 'headless', pid: child.pid, machine: normalMachine(hostname()), mode: 'fresh', launched_at: now() };
+  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);
+    setRunSession(db, runId, session);
+    event(db, task.id, 'spawned', { pid: child.pid }, runId);
+  });
+  return session;
+}
+
+/** 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;
+  if (task.workspace_kind === 'dir') { mkdirSync(task.workspace_path, { recursive: true }); return task.workspace_path; }
+  if (task.workspace_kind === 'worktree') {
+    const anchor = task.workspace_path;
+    if (!anchor) throw new Error(`card ${task.id} is a worktree card with no repository (worktree:<path>)`);
+    const top = spawnSync('git', ['-C', anchor, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+    const repo = top.status === 0 ? top.stdout.trim() : null;
+    const target = repo && repo === anchor ? join(repo, '.worktrees', task.id) : anchor;
+    if (!existsSync(target)) {
+      const branch = task.branch_name || `wt/${task.id}`;
+      const made = spawnSync('git', ['-C', repo ?? dirname(anchor), 'worktree', 'add', '-B', branch, target], { encoding: 'utf8' });
+      if (made.status !== 0) throw new Error(`git worktree add ${target}: ${made.stderr.trim().slice(-300)}`);
+    }
+    return target;
+  }
+  const dir = task.workspace_path || (board.slug === 'default' ? join(root, 'kanban', 'workspaces', task.id) : join(root, 'kanban', 'boards', board.slug, 'workspaces', task.id));
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ------------------------------------------------------------------ attach
+
+/**
+ * Put a live session the board did not start on a card (a session started by hand before its card existed): the
+ * card is claimed and its run records the session as the fleet shows it (address, pane, the pane's directory),
+ * 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 } = {}) {
+  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);
+  if (!found) throw new Error(`the fleet lists no live session ${who}`);
+  const [, host, harness, sessionId] = found.address.split(':');
+  if (harness !== 'claude-code') throw new Error(`${found.address} is ${harness}; the board resumes claude-code sessions by id`);
+  let dir = workspace;
+  if (!dir && found.pane) {
+    const r = sc(['teams', 'panes', 'ls', '--machine', host], { timeout: 60_000 });
+    dir = (json(r.stdout.trim(), []) ?? []).find((p) => p.pane === found.pane)?.cwd ?? null;
+  }
+  return tx(board, (db) => {
+    const task = getTask(db, id);
+    if (!task) throw new Error(`no card ${id}`);
+    if (task.status === 'running') throw new Error(`${id} is running already`);
+    if (task.machine && normalMachine(task.machine) !== host) throw new Error(`${id} runs on ${task.machine}, and ${found.address} is on ${host}; move the card first`);
+    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);
+    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);
+    }
+    if (task.status !== 'ready') {
+      if (!['todo', 'blocked', 'scheduled', 'triage', 'review'].includes(task.status)) throw new Error(`${id} is ${task.status}; only an open card takes a session`);
+      db.prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(id);
+    }
+    const runId = claimIn(db, id, { ttl, expectStatus: 'ready' });
+    if (!runId) throw new Error(`${id} waits on parents that are not done`);
+    const session = { surface: 'pane', session_id: sessionId, harness, machine: host, pane: found.pane ?? null, address: found.address, mode: 'adopt', launched_at: now(), seen_at: now() };
+    setRunSession(db, runId, session);
+    event(db, id, 'session_adopted', { session_id: sessionId, machine: host, pane: session.pane, address: found.address, mode: 'adopt' }, runId);
+    subscribeIn(db, id, found.address, 'worker');
+    for (const p of db.prepare('SELECT parent_id FROM task_links WHERE child_id = ?').all(id)) subscribeIn(db, p.parent_id, found.address, 'dependency');
+    return { ...session, workspace: dir };
+  });
+}
+
+// ------------------------------------------------------------------ notify
+
+function notice(kind, task, p, role) {
+  const tid = task?.id ?? '?';
+  const who = task?.assignee ? `@${task.assignee} ` : '';
+  const title = task?.title ?? '';
+  switch (kind) {
+    case 'session_started': case 'session_resumed': case 'session_replaced': {
+      const verb = { session_started: 'started', session_resumed: 'resumed', session_replaced: 'could not resume the card\'s last session and started' }[kind];
+      return `▶ ${who}card ${tid} — ${title}: the board ${verb} session ${p.session_id} on ${p.machine} (pane ${p.pane}; ${p.address}).`;
+    }
+    case 'session_adopted': return `▶ ${who}card ${tid} — ${title}: the board found session ${p.session_id} still live on ${p.machine} and kept it (${p.address}).`;
+    case 'session_lost': return `✖ ${who}card ${tid}: session ${p.session_id} is gone from ${p.machine}; the board resumes it, and replaces it from the card only when it cannot.`;
+    case 'spawn_failed': return `✖ ${who}card ${tid}: its session did not start: ${String(p.error ?? '').slice(0, 300)}`;
+    case 'completed': return `✔ ${who}card ${tid} done — ${title}${p.summary ? `\n${String(p.summary).slice(0, 300)}` : ''}`;
+    case 'blocked': return `⏸ ${who}card ${tid} blocked${p.reason ? `: ${String(p.reason).slice(0, 300)}` : ''}`;
+    case 'unblocked': return `▶ card ${tid} unblocked`;
+    case 'gave_up': return `✖ ${who}card ${tid} gave up after ${p.failures} failures${p.error ? `\n${String(p.error).slice(0, 300)}` : ''}`;
+    case 'crashed': return `✖ ${who}card ${tid}: its worker exited without completing it; the board will retry`;
+    case 'timed_out': return `⏱ ${who}card ${tid} timed out (max_runtime ${p.limit_seconds}s); the board will retry`;
+    case 'status': return `🔄 ${who}card ${tid} → ${p.status}`;
+    case 'archived': return role === 'worker' ? `card ${tid} archived` : null;
+    case 'block_loop_detected': return `🛑 ${who}card ${tid} went to triage: blocked ${p.recurrences}x for the same cause${p.reason ? `: ${String(p.reason).slice(0, 200)}` : ''}`;
+    case 'review_requested': return `👀 ${who}card ${tid} ready for review — ${title}${p.summary ? `\n${String(p.summary).slice(0, 300)}` : ''}`;
+    case 'changes_requested': return `🛑 card ${tid}: review asked for changes: ${String(p.reason ?? 'reviewer feedback').slice(0, 300)}`;
+    case 'assigned': return `card ${tid} is now assigned to ${p.assignee ?? 'nobody'}`;
+    case 'machine_set': return `card ${tid} now runs on ${p.machine ?? 'no machine'}`;
+    case 'linked': case 'unlinked': return `card ${tid}: dependency ${kind} (${p.parent} → ${p.child})`;
+    case 'promoted_manual': return `card ${tid} promoted to ready by ${p.actor}`;
+    case 'subtask_added': return `card ${tid} has a new subtask ${p.subtask}: ${p.title}`;
+    default: return null;
+  }
+}
+
+function send(from, label, to, body, key) {
+  const request = {
+    op: 'send', from, from_name: `${label} board`, to, queue: false, id: key,
+    body: `[Board notice from the ${label} board] ${body}\n\n(An automated notice from the board's dispatcher; replies to this address go nowhere.)`,
+  };
+  const r = sc(['message', 'remote-deliver'], { input: JSON.stringify(request), timeout: 60_000 });
+  const answer = lastJson(r.stdout) ?? {};
+  if (r.code !== 0 || answer.code !== 0) throw new Error((answer.text || r.stderr || 'no answer').trim().slice(-300));
+}
+
+function notify(board, report) {
+  const from = `sc:${localMachine()}:board:${board.label.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
+  for (const sub of subscriptions(board.db)) {
+    if (sub.platform !== 'supercode') continue;
+    const role = ['worker', 'dependency'].includes(sub.delivery_metadata?.role) ? sub.delivery_metadata.role : 'creator';
+    const kinds = MAIL_KINDS[role];
+    const events = board.db.prepare(`SELECT id, kind, payload, created_at FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id`)
+      .all(sub.task_id, sub.last_event_id, ...kinds);
+    if (!events.length) continue;
+    const task = tx(board, (db) => getTask(db, sub.task_id));
+    let cursor = Number(sub.last_event_id);
+    try {
+      for (const ev of events) {
+        const p = json(ev.payload, {}) ?? {};
+        let text;
+        if (ev.kind === 'commented') {
+          if (p.author === sub.chat_id) { cursor = ev.id; continue; }
+          const c = board.db.prepare('SELECT body FROM task_comments WHERE task_id = ? AND author = ? AND created_at >= ? ORDER BY id LIMIT 1').get(sub.task_id, p.author, ev.created_at);
+          text = c ? `💬 card ${sub.task_id}, ${p.author}:\n${c.body}` : null;
+        } else text = notice(ev.kind, task, p, role);
+        if (text) {
+          send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`);
+          report.notified.push([sub.task_id, ev.kind, sub.chat_id]);
+        }
+        cursor = ev.id;
+      }
+    } catch (error) {
+      report.undelivered.push([sub.task_id, sub.chat_id, String(error.message).slice(-200)]);
+    }
+    // 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);
+    });
+  }
+}
+
+// ------------------------------------------------------------------ the tick
+
+/** The board's name in notices: the home's owner folder (`…/volter-manager/home` → `volter-manager`), and the slug. */
+export function boardLabel(root, slug) {
+  const home = basename(root) === 'home' ? basename(dirname(root)) : basename(root);
+  return slug && slug !== 'default' ? `${home}/${slug}` : home;
+}
+
+/**
+ * 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 }) {
+  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 out = [];
+  for (const slug of slugs ?? listBoards(root)) {
+    const report = { board: slug, started: [], queued: [], failed: [], lost: [], crashed: [], timed_out: [], reclaimed: [], auto_blocked: [], promoted: 0, unassigned: [], nonspawnable: [], notified: [], undelivered: [], fleet: fleet.ok ? 'read' : fleet.error };
+    let board;
+    try {
+      board = openBoard(root, slug);
+      board.label = boardLabel(root, slug);
+      supervise(board, fleet, settings, report);
+      report.promoted = recomputeReady(board, settings.failureLimit);
+      if (dispatch) start(board, fleet, lanes, settings, report, { only });
+      notify(board, 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 {
+      board?.close();
+    }
+    out.push(report);
+  }
+  return out;
+}