@volter/supercode-orchestrator 0.5.215 → 0.5.216

package/board/dispatch.mjs

@@ -578,10 +578,16 @@ async function supervise(board, fleet, settings, report, entry, effects) {
           const row = nativeReading(nativeSessions(session.machine, session.harness ?? 'claude-code', session.session_id), session).row;
           native = { turn: row?.activity?.turn };
         } catch { /* an unread turn stays unknown */ }
-        const reading = { alive: alive ?? null, turn: alive === true ? native?.turn ?? null : null, observed_at: t };
+        // the session's machine as this round read it, so the card can say why a session reads unknown (executionOf)
+        // (a round that read no fleet, on a board with no pane lane, says nothing of any machine)
+        const where = session.surface !== 'headless' && session.machine && fleet.errors instanceof Map
+          ? fleet.online.has(session.machine) ? { machine_reading: 'online' }
+            : { machine_reading: fleet.offline?.has(normalMachine(session.machine)) ? 'offline' : 'unknown', machine_error: String(fleet.errors.get(normalMachine(session.machine)) ?? fleet.error ?? '').slice(0, 300) || null }
+          : {};
+        const reading = { alive: alive ?? null, turn: alive === true ? native?.turn ?? null : null, observed_at: t, ...where };
         const prior = session.presence_observation;
         // Keep state changes immediately and renew unchanged readings once a minute.
-        if (!prior || prior.alive !== reading.alive || prior.turn !== reading.turn || t - prior.observed_at >= 60) {
+        if (!prior || prior.alive !== reading.alive || prior.turn !== reading.turn || prior.machine_reading !== reading.machine_reading || t - prior.observed_at >= 60) {
           setRunSession(db, runRow.id, { presence_observation: reading });
           session = { ...session, presence_observation: reading };
         }
@@ -3592,6 +3598,8 @@ export { boardLabel };
 // board, card start, board message or notice. What it leaves unfiled is not a failure; the next dispatcher files it.
 let stopping = false;
 export function stopDispatching() { stopping = true; }
+// Only the stable owner's parked generation is resumed; it takes a fresh fencing epoch first.
+export function resumeDispatching() { stopping = false; }
 
 /** 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'; } };
@@ -3754,7 +3762,8 @@ export async function activatePullRequestReviews(board, entry, report, effects,
         stalls.push({ id, key: `no_work_branch:${lastReviewEvent(board, id)}`, why: `its review waits: ${payload.waits}` });
         payload = null; continue;
       }
-      if (!payload.no_code && !await reviewDue(board, id, payload.pr.map((url, index) => ({ url, head: payload.pr_head[index] })))) {
+      // A PR of the arc proposed to a branch other than main is refused below, whatever the others' verdicts.
+      if (!payload.no_code && !payload.stacked?.length && !await reviewDue(board, id, payload.pr.map((url, index) => ({ url, head: payload.pr_head[index] })))) {
         const why = `every open PR head (${payload.pr.join(', ')}) has a verdict, carries the source tree its verdict judged, or predates it; push a commit that changes the source, or close the tasks that own the last verdict's findings`;
         report.queued.push([id, `review waits: ${why}`]);
         // After a pass the arc's own session merges and asks for done; any other verdict nothing answered waits on an act
@@ -3772,12 +3781,20 @@ export async function activatePullRequestReviews(board, entry, report, effects,
         continue;
       }
       // A stable PR-property or local refusal must not spend a full fresh REST scan every round. Advisory
-      // discovery is sufficient to refuse, never to authorize; the scan below still owns that.
-      if (!payload.no_code) await openReviewPullRequests(board, id, { checkWorkspaces: true });
+      // discovery is sufficient to refuse, never to authorize; the scan below still owns that. Nor is it enough to
+      // tell: its PR heads, bases and states come from the shared discovery cache (up to five minutes old), so a push
+      // or retarget since may already have cleared what it refuses. It refuses without the fresh scan only when it is
+      // the wait already told; a new one goes on to the fresh read below, which tells it only if it still stands.
+      if (!payload.no_code) {
+        try { await openReviewPullRequests(board, id, { checkWorkspaces: true }); }
+        catch (error) {
+          if (error?.code !== 'review_refused' || view(board, (db) => toldReviewWait(db, id)) === refusalKey(board, id, error)) throw error;
+        }
+      }
       if (!dry) await refreshCardInputs(board, id, { commits: true });
       // Cached draft/closed exclusions are useful while waiting, but cannot define a committed review's set.
       const observed = await withFreshReviewReads(async () => {
-        const candidate = await openReviewPullRequests(board, id, { fresh: true, repositories: payload.review_repositories ?? [] })
+        const candidate = await openReviewPullRequests(board, id, { fresh: true, refuseStacked: true, repositories: payload.review_repositories ?? [] })
           ?? (noCodeReviewDue(board, id) ? await noCodeChange(board, id, { fresh: true }) : null);
         const evidence = !candidate || candidate.waits ? null : candidate.no_code
           ? { required: false, ready: true, reason: null, phase: 'source', no_code: candidate.no_code }
@@ -3787,7 +3804,7 @@ export async function activatePullRequestReviews(board, entry, report, effects,
       payload = observed.candidate;
       if (!payload || payload.waits) { report.queued.push([id, `review waits: ${payload?.waits ?? 'the current source set has no review candidate'}`]); payload = null; continue; }
       const evidence = observed.evidence;
-      if (!evidence.ready) throw new Error(evidence.reason);
+      if (!evidence.ready) throw Object.assign(new Error(evidence.reason), { code: evidence.code, refusals: evidence.refusals });
       // A dry run names the complete validated review a tick would request and writes nothing.
       if (dry) { (report.would_review ??= []).push({ id, prs: payload.pr, heads: payload.pr_head, no_code: payload.no_code ?? null }); continue; }
       const moved = tx(board, db => {
@@ -3804,7 +3821,14 @@ export async function activatePullRequestReviews(board, entry, report, effects,
         effects.push(...moved.effects);
         (report.review_requested ??= []).push({ id, prs: payload.pr, heads: payload.pr_head });
       }
-    } catch (error) { report.queued.push([id, `PR review waits${payload ? ` (${payload.pr.join(', ')})` : ''}: ${error.message}`]); }
+    } catch (error) {
+      report.queued.push([id, `PR review waits${payload?.pr?.length ? ` (${payload.pr.join(', ')})` : ''}: ${error.message}`]);
+      // A refusal only the arc's act clears (a PR proposed to a branch other than main, a draft, an unpushed or
+      // uncommitted checkout) is a review wait like any other: every task is closed, so no session of the arc is told
+      // by its tasks, and a refusal only logged left VO-3602 t_918cc86e unreviewed for its whole idle session. Its key
+      // is its refused PRs and kinds alone (refusalKey); the detail is in `why`.
+      if (error?.code === 'review_refused') stalls.push({ id, key: refusalKey(board, id, error), why: `its review waits: ${error.message} Every task is closed, so no session of the arc is due to act on it.` });
+    }
   }
   if (!dry) surfaceReviewStalls(board, entry, stalls, settled, report);
 }
@@ -3813,6 +3837,18 @@ export async function activatePullRequestReviews(board, entry, report, effects,
  *  carries it, so the wait a new verdict or request leaves is a new wait. */
 const lastReviewEvent = (board, id) => board.db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass', 'review_voided')").get(id)?.id ?? 0;
 
+/** A review refusal's wait key: the arc's last review event and the sorted kinds and PRs it refused (ci.mjs refusalOf),
+ *  never a count or a path, so the same refusal is the same wait however its detail or read order changes. */
+const refusalKey = (board, id, error) => `refused:${lastReviewEvent(board, id)}:${(error.refusals ?? []).map((r) => `${r.kind}:${r.url}`).join(' ')}`;
+
+/** The key of the card's told review wait not cleared since, or null. */
+function toldReviewWait(db, id) {
+  const last = db.prepare("SELECT id, json_extract(payload, '$.review_wait') AS key FROM task_events WHERE task_id = ? AND kind = 'board_message' AND json_extract(payload, '$.review_wait') IS NOT NULL ORDER BY id DESC LIMIT 1").get(id);
+  if (!last) return null;
+  const cleared = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind = 'review_wait_cleared'").get(id)?.id ?? 0;
+  return cleared > last.id ? null : last.key;
+}
+
 /** At most this many review waits are told per round; the rest are told in the rounds after, in candidate order. */
 const REVIEW_WAITS_TOLD_PER_ROUND = 8;
 /**
@@ -3832,13 +3868,7 @@ const REVIEW_WAITS_TOLD_PER_ROUND = 8;
 function surfaceReviewStalls(board, entry, stalls, settled, report) {
   const to = [].concat(entry.params.managers ?? []).find(Boolean);
   if (!to || (!stalls.length && !settled.length)) return;
-  // the key of the card's told review wait not cleared since, or null
-  const told = (db, id) => {
-    const last = db.prepare("SELECT id, json_extract(payload, '$.review_wait') AS key FROM task_events WHERE task_id = ? AND kind = 'board_message' AND json_extract(payload, '$.review_wait') IS NOT NULL ORDER BY id DESC LIMIT 1").get(id);
-    if (!last) return null;
-    const cleared = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind = 'review_wait_cleared'").get(id)?.id ?? 0;
-    return cleared > last.id ? null : last.key;
-  };
+  const told = toldReviewWait;
   // read first: a round with nothing to tell or clear opens no write
   const plan = view(board, (db) => ({
     clear: settled.filter((id) => told(db, id)),

package/board/engine.mjs

@@ -10,7 +10,7 @@ import { allocateReadableId } from './readable-id.mjs';
 // observes or sends: the dispatcher (`dispatch.mjs`) does, and records what it did through these.
 import { current } from './call.mjs';
 import { detachedCard, detachedSession, personCustody, sessionAddress, sessionOperation } from './custody.mjs';
-import { executionOf } from './session-work.mjs';
+import { executionOf, readingContext } from './session-work.mjs';
 import { cardState, cardStateSql, holdDescription } from './card-state.mjs';
 import { spawn, execFile } from 'node:child_process';
 import { existsSync, rmSync } from 'node:fs';
@@ -927,7 +927,7 @@ export function listCards(db, { status = null, assignee = null, machine = null,
   const rows = all(db, `SELECT t.*, n.number, c.machine, c.subtask_of, c.stage, c.tags, c.paused, c.blocked_by FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id
     WHERE (? IS NULL OR ${stateSql} = ? OR (? NOT IN ('paused','blocked') AND c.stage = ?)) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND ${CARD_VISIBILITY_SQL}
     ORDER BY t.priority DESC, t.created_at ASC`, status, status, status, status, assignee, assignee, machine, machine, includeSubtasks ? 1 : 0, includeArchived ? 1 : 0);
-  return rows.map((r) => cardState({ ...r, skills: json(r.skills, []) ?? [], execution: executionOf(r.current_run_id ? one(db, 'SELECT metadata,ended_at FROM task_runs WHERE id=?', r.current_run_id) : null) }, { nativeHolds }));
+  return rows.map((r) => cardState({ ...r, skills: json(r.skills, []) ?? [], execution: executionOf(r.current_run_id ? one(db, 'SELECT id,metadata,ended_at FROM task_runs WHERE id=?', r.current_run_id) : null, readingContext(db, r.id, r.current_run_id)) }, { nativeHolds }));
 }
 
 export function showCard(db, id, options = {}) {

package/board/fence.mjs

@@ -9,6 +9,7 @@
 import { renameSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { boardHome } from '@volter/teams/board-owner';
+import { assertGenerationWriter } from './generation.mjs';
 
 let mine = null;
 const STATE = 'CREATE TABLE IF NOT EXISTS supercode_board_state (key TEXT PRIMARY KEY, value TEXT)';
@@ -32,6 +33,7 @@ export function takeEpoch(root, boards) {
 
 /** At a write transaction's start: in the owner, store its epoch unless a newer one is stored, and exit when it is. */
 export function fenced(db) {
+  assertGenerationWriter();
   if (mine === null) return;
   db.exec(STATE);
   const r = db.prepare(`INSERT INTO supercode_board_state (key, value) VALUES ('owner_epoch', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value

package/board/generation-owner.mjs

@@ -0,0 +1,293 @@
+// The stable board owner: one OS lock and public door, with replaceable, fenced dispatcher generations behind it.
+// A request already sent to a generation is never replayed. Only unsent requests wait at the handover boundary.
+import { readSourceCandidate } from '@volter/supercode-teams/source-selection';
+import { sourceLockPath } from '@volter/supercode-teams/source-lock';
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { boardHome, boardOwnerSocket } from '@volter/teams/board-owner';
+import { retainedReceipt } from '@volter/supercode-teams/release-selection';
+import { sourceTransaction } from '@volter/supercode-teams/serving-source-transaction';
+import { holdLock } from './lock-holder.mjs';
+import { openOwnerDoor } from './owner-door.mjs';
+import { holdOwnerHealth } from './owner-health.mjs';
+import { holdWorkflow } from './workflow.mjs';
+import { knowLocalMachine, localMachine } from './dispatch.mjs';
+import { parse } from './args.mjs';
+
+const unknown = () => ({ code: 1, unanswered: true, stdout: '', stderr: 'the board generation ended after taking this request; its outcome is unknown\n' });
+const failed = error => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error.message}\n` });
+
+export async function serveBoardOwner(root, args) {
+  root = boardHome(root);
+  mkdirSync(root, { recursive: true });
+  const log = line => process.stdout.write(`${new Date().toISOString()} board owner: ${line}\n`);
+  let stopping = false, active = null, previous = null, transition = null, routing = null, pending = null, recoveryFailure = null;
+  const generations = new Set(), waiting = new Set();
+  const recordPath = join(root, 'board-generation.json');
+  const record = child => {
+    const temporary = `${recordPath}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ version: 1, owner: process.pid, active: child?.process.pid ?? null,
+      selected: child?.selected ?? null, generation: child?.id ?? null, previous: previous?.process.pid ?? null, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    renameSync(temporary, recordPath);
+  };
+  const changed = () => { for (const done of waiting) done(); waiting.clear(); };
+  const lock = await holdLock(join(root, 'board.lock'), { onLost: error => { log(error.message); process.exit(1); } });
+  await knowLocalMachine();
+  const entry = resolve(process.env.SUPERCODE_ORCHESTRATOR_ENTRY || fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url)));
+  const start = selected => {
+    const generationId = randomUUID();
+    const env = { ...process.env, SUPERCODE_BOARD_GENERATION_OWNER: String(process.pid), SUPERCODE_BOARD_GENERATION_ID: generationId,
+      SUPERCODE_BOARD_GENERATION_MACHINE: localMachine(), SUPERCODE_ORCHESTRATOR_ENTRY: selected.entry, SUPERCODE_BIN: selected.native };
+    delete env.SUPERCODE_SOURCE_CANDIDATE; delete env.SUPERCODE_RELEASE_RECEIPT; delete env.SUPERCODE_RELEASE_VERSION;
+    if (selected.candidate) env.SUPERCODE_SOURCE_CANDIDATE = selected.candidate;
+    if (selected.release) env.SUPERCODE_RELEASE_RECEIPT = selected.release;
+    const runtime = selected.candidate ? readSourceCandidate(selected.candidate, sourceLockPath()).node : process.execPath;
+    env.SUPERCODE_NODE_BIN = runtime;
+    const processChild = spawn(runtime, [selected.entry, 'workflow', 'serve', '--root', root,
+      ...(args.interval ? ['--interval', String(args.interval)] : []), ...(args.max ? ['--max', String(args.max)] : []),
+      ...(args['failure-limit'] ? ['--failure-limit', String(args['failure-limit'])] : []), ...(args.verbose ? ['--verbose'] : [])], {
+      stdio: ['ignore', 'inherit', 'inherit', 'ipc'], serialization: 'advanced',
+      env,
+    });
+    const generation = { process: processChild, selected, id: generationId, calls: new Map(), events: new Map(), ended: false, health: null, workflows: new Map() };
+    generation.exited = new Promise(done => { processChild.once('exit', done); processChild.once('error', done); });
+    generations.add(generation);
+    const tell = frame => { if (processChild.connected) processChild.send(frame); else throw new Error('board generation disconnected'); };
+    generation.tell = tell;
+    generation.wait = (event, ms = 8000) => new Promise((done, reject) => {
+      if (generation.ended) return reject(new Error('board generation ended'));
+      if (generation.events.has(event)) return done(generation.events.get(event));
+      const waiter = { done, reject, timer: null }, expires = Date.now() + 90000;
+      waiter.arm = budget => {
+        clearTimeout(waiter.timer);
+        waiter.timer = setTimeout(() => { generation.events.delete(event); reject(new Error(`board generation did not report ${event}; last preparation step: ${generation.startupStep ?? 'entry loading'}; predecessor retained`)); }, Math.min(budget, Math.max(1, expires - Date.now())));
+      };
+      waiter.arm(ms); generation.events.set(event, waiter);
+    });
+    generation.ask = (line, timeout = null) => new Promise(done => {
+      const id = randomUUID();
+      let timer;
+      const finish = answer => { clearTimeout(timer); generation.calls.delete(id); done(answer); };
+      if (timeout) timer = setTimeout(() => finish(unknown()), timeout);
+      generation.calls.set(id, finish);
+      try { tell({ type: 'request', id, line }); }
+      catch { generation.calls.delete(id); done(unknown()); }
+    });
+    const ended = () => {
+      if (generation.ended) return;
+      generation.ended = true;
+      // IPC loss revokes the child but does not prove its process ended. End that exact owned child before recovery.
+      if (processChild.exitCode === null && processChild.signalCode === null) {
+        processChild.kill('SIGTERM');
+        const bound = setTimeout(() => processChild.kill('SIGKILL'), 2000);
+        generation.exited.finally(() => clearTimeout(bound));
+      }
+      generations.delete(generation);
+      for (const done of generation.calls.values()) done(unknown());
+      generation.calls.clear();
+      for (const value of generation.events.values()) if (value.reject) { clearTimeout(value.timer); value.reject(new Error('board generation ended')); }
+      generation.events.clear();
+      changed();
+      if (!stopping && routing === generation) {
+        routing = null;
+        // Only a parked predecessor can resume. A failed first generation leaves the public door up and names why.
+        if (pending) recoveryFailure = new Error('prepared board generation ended; the coordinating transaction must roll back');
+        if (!transition && !pending) {
+          transition = (async () => {
+            await generation.exited;
+            const replacement = start(generation.selected);
+            await replacement.wait('prepared');
+            return activate(replacement);
+          })().catch(error => { recoveryFailure = error; log(`generation recovery refused: ${error.message}`); }).finally(() => { transition = null; changed(); });
+        }
+      }
+    };
+    processChild.on('message', frame => {
+      if (!frame || typeof frame.type !== 'string') return;
+      if (frame.type === 'startup-step') {
+        generation.startupStep = frame.step;
+        if (Number.isSafeInteger(frame.budget_ms) && frame.budget_ms >= 1 && frame.budget_ms <= 65000)
+          generation.events.get(frame.phase === 'serving' ? 'serving' : 'prepared')?.arm?.(frame.budget_ms);
+        return;
+      }
+      if (frame.type === 'answer') { generation.calls.get(frame.id)?.(frame.answer); generation.calls.delete(frame.id); changed(); return; }
+      if (frame.type === 'health') { generation.health = frame; if (routing === generation) holdOwnerHealth(frame.boards, frame.round); return; }
+      if (frame.type === 'workflow') { generation.workflows.set(frame.root, frame.entry); if (routing === generation) holdWorkflow(frame.root, frame.entry); return; }
+      const waiter = generation.events.get(frame.type);
+      if (waiter?.done) { clearTimeout(waiter.timer); waiter.done(frame); }
+      generation.events.set(frame.type, frame);
+    });
+    processChild.once('error', ended); processChild.once('exit', ended); processChild.once('disconnect', ended);
+    return generation;
+  };
+  const terminate = async generation => {
+    generation.process.kill('SIGTERM');
+    const timer = setTimeout(() => generation.process.kill('SIGKILL'), 2000);
+    try { await generation.exited; } finally { clearTimeout(timer); }
+  };
+  const activate = async generation => {
+    if (stopping || generation.ended) throw new Error('cannot activate an ended board generation');
+    record(generation);
+    generation.events.delete('serving');
+    generation.tell({ type: 'activate' });
+    const serving = await generation.wait('serving');
+    const read = async argv => {
+      const proof = await generation.ask(JSON.stringify({ v: 1, argv, cwd: root,
+        facts: { SUPERCODE_CONTEXT: process.env.SUPERCODE_CONTEXT || 'local' } }), 8000);
+      if (proof.code !== 0 || proof.unanswered) throw new Error(`successor ${argv[0]} readback failed: ${Array.isArray(proof.stderr) ? proof.stderr.join('') : proof.stderr || 'answer unknown'}; predecessor retained`);
+      return JSON.parse(Array.isArray(proof.stdout) ? proof.stdout.join('') : proof.stdout);
+    };
+    // A newly rendered home can have no initialized board, or several named boards. Read the actual inventory
+    // before asking each store for stats; an assumed default would refuse an otherwise serving empty home.
+    const boards = serving.boards;
+    if (!Array.isArray(boards)) throw new Error('successor board inventory was unreadable; predecessor retained');
+    await read(['declaration', '--json']);
+    for (const slug of boards) {
+      if (typeof slug !== 'string') throw new Error('successor board inventory has no slug; predecessor retained');
+      await read(['stats', '--json', '--board', slug]);
+    }
+    active = generation; routing = generation; recoveryFailure = null;
+    if (generation.health) holdOwnerHealth(generation.health.boards, generation.health.round);
+    for (const [at, value] of generation.workflows) holdWorkflow(at, value);
+    changed();
+    log(`generation ${generation.id} serves (pid ${generation.process.pid})`);
+    return generation;
+  };
+  const status = () => ({ version: 1, protocol: 1, owner: process.pid, state: routing ? 'serving' : 'transitioning',
+    generation: active?.id, pid: active?.process.pid, selected: active?.selected, previous: previous?.selected ?? null,
+    transaction: pending?.id ?? null, phase: pending?.phase ?? null, failure: recoveryFailure?.message ?? null });
+  const prepare = async (id, selected) => {
+    if (pending) {
+      if (pending.id === id) {
+        if (JSON.stringify(pending.candidate.selected) !== JSON.stringify(selected)) throw new Error('board transaction already names different inputs');
+        return status();
+      }
+      throw new Error('another board generation is prepared');
+    }
+    if (!active || active.ended) throw new Error('no serving predecessor can hand over this board');
+    sourceTransaction(id, selected, active.selected, 'prepare', process.env, 'board');
+    const candidate = start(selected);
+    try {
+      const proof = await candidate.wait('prepared'), held = active.events.get('prepared');
+      if (!proof.storage || proof.storage !== held?.storage) throw new Error('board storage contract differs; predecessor retained without opening a writer');
+      pending = { id, candidate, predecessor: active, older: previous, phase: 'prepared' };
+      return status();
+    } catch (error) { await terminate(candidate); throw error; }
+  };
+  const rollback = async () => {
+    const held = pending;
+    if (!held) return status();
+    await terminate(held.candidate);
+    previous = held.older;
+    if (held.phase !== 'prepared') {
+      routing = null;
+      // A timed-out park may still be executing. End that exact child before a fresh predecessor takes an epoch;
+      // an activate sent to a child still parking can otherwise race its final writer revocation.
+      await terminate(held.predecessor);
+      const replacement = start(held.predecessor.selected);
+      try { await replacement.wait('prepared'); await activate(replacement); }
+      catch (error) { await terminate(replacement); throw error; }
+    } else if (!held.predecessor.ended) { active = routing = held.predecessor; changed(); }
+    pending = null; record(active); return status();
+  };
+  const switchPrepared = async () => {
+    const held = pending;
+    if (held.phase === 'activated' && routing === held.candidate) return status();
+    if (held.phase !== 'prepared' || active !== held.predecessor) throw new Error('board preparation is no longer current');
+    try {
+      const requireCandidate = () => {
+        if (held.candidate.ended || !held.candidate.process.connected)
+          throw new Error('prepared board candidate ended before activation; predecessor retained');
+      };
+      requireCandidate();
+      routing = null;
+      let drainTimer;
+      try { await Promise.race([new Promise(done => {
+        const inspect = () => { if (!held.predecessor.calls.size || held.predecessor.ended) done(); else waiting.add(inspect); }; inspect();
+      }), new Promise((_, reject) => { drainTimer = setTimeout(() => reject(new Error('board requests did not drain; predecessor retained')), 8000); })]); }
+      finally { clearTimeout(drainTimer); }
+      requireCandidate();
+      held.phase = 'parking';
+      held.predecessor.events.delete('parked'); held.predecessor.tell({ type: 'park' });
+      await held.predecessor.wait('parked'); previous = held.predecessor;
+      await activate(held.candidate); held.phase = 'activated'; return status();
+    } catch (error) { await rollback(); throw error; }
+  };
+  const control = async parsed => {
+    const action = parsed.action ?? 'replace', id = parsed.transaction;
+    if (action === 'status') return status();
+    if (typeof id !== 'string' || !id) throw new Error('board handover needs --transaction');
+    if (action === 'prepare' || action === 'replace') {
+      if (!parsed.entry || !parsed.supercode) throw new Error('handover needs --entry and --supercode from one prepared machine release');
+      await prepare(id, { entry: resolve(parsed.entry), native: resolve(parsed.supercode), candidate: parsed.candidate ? resolve(parsed.candidate) : null, release: parsed.release ? resolve(parsed.release) : null });
+    } else if (pending?.id !== id) throw new Error('this board holds no matching handover transaction');
+    if (pending) sourceTransaction(id, pending.candidate.selected, pending.predecessor.selected, action === 'replace' ? 'activate' : action, process.env, 'board');
+    if (action === 'activate' || action === 'replace') await switchPrepared();
+    if (action === 'rollback' || action === 'abort') return rollback();
+    if (action === 'finish' || action === 'replace') {
+      sourceTransaction(id, pending.candidate.selected, pending.predecessor.selected, 'finish', process.env, 'board');
+      if (pending.phase !== 'activated') throw new Error('board successor was never activated');
+      if (pending.candidate.ended) {
+        await terminate(pending.candidate);
+        const replacement = start(pending.candidate.selected);
+        try { await replacement.wait('prepared'); await activate(replacement); pending.candidate = replacement; }
+        catch (error) { await terminate(replacement); throw error; }
+      }
+      if (routing !== pending.candidate || active.ended) throw new Error('board successor is not serving; handover cannot finish');
+      for (const retained of generations) if (retained !== active && retained !== previous) await terminate(retained);
+      pending = null; record(active);
+    } else if (!['prepare', 'activate'].includes(action)) throw new Error('unknown board handover action');
+    return status();
+  };
+  const answer = async line => {
+    let request;
+    try { request = JSON.parse(line); } catch { /* generation answers malformed input */ }
+    if (request?.v === 1 && Array.isArray(request.argv) && request.argv[0] === 'handover') {
+      const parsed = parse(request.argv);
+      if (parsed.action === 'status') return { code: 0, stdout: JSON.stringify(status()) + '\n', stderr: '' };
+      if (transition) return failed(new Error('a board handover is already in progress'));
+      transition = control(parsed);
+      try { return { code: 0, stdout: JSON.stringify(await transition) + '\n', stderr: '' }; }
+      catch (error) { return failed(error); }
+      finally { transition = null; changed(); }
+    }
+    while (!routing && !stopping) {
+      if (recoveryFailure && !transition) return failed(recoveryFailure);
+      if (active?.ended && (!previous || previous.ended) && !transition) return failed(new Error('board generation ended; no rollback generation is available'));
+      await new Promise(done => waiting.add(done));
+    }
+    return stopping ? failed(new Error('the board owner is stopping')) : routing.ask(line);
+  };
+  let closeDoor;
+  const stop = () => {
+    if (stopping) return;
+    stopping = true; changed();
+    for (const generation of generations) if (!generation.ended) generation.process.kill('SIGTERM');
+  };
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, stop);
+  try {
+    // Only this lock's holder publishes/removes the public socket, for its entire lifetime.
+    rmSync(boardOwnerSocket(root), { force: true });
+    closeDoor = await openOwnerDoor(root, { machine: localMachine(), answer, log, readListings: false });
+    const first = start({ entry, native: process.env.SUPERCODE_BIN, candidate: process.env.SUPERCODE_SOURCE_CANDIDATE || null, release: process.env.SUPERCODE_SOURCE_CANDIDATE ? null : retainedReceipt(entry) });
+    await first.wait('prepared');
+    await activate(first);
+    if (typeof process.send === 'function' && Number(process.env.SUPERCODE_BOARD_START_OWNER) === process.ppid)
+      process.send({ type: 'board-owner-ready', owner: process.pid });
+    if (args.pidfile) writeFileSync(args.pidfile, `${process.pid}\n`);
+    while (!stopping) await new Promise(done => waiting.add(done));
+  } finally {
+    stop();
+    await Promise.all([...generations].map(terminate));
+    closeDoor?.();
+    rmSync(boardOwnerSocket(root), { force: true });
+    try { if (JSON.parse(readFileSync(recordPath, 'utf8')).owner === process.pid) rmSync(recordPath); } catch { /* absent */ }
+    lock.release();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(signal, stop);
+    if (args.pidfile) rmSync(args.pidfile, { force: true });
+  }
+  return 0;
+}

package/board/generation.mjs

@@ -0,0 +1,49 @@
+// A board generation's cooperative writer boundary. The stable owner holds board.lock and its public socket;
+// only its active child may enter work. Parking drains admitted work before acknowledging loss of authority.
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const inBoardGeneration = typeof process.send === 'function'
+  && Number(process.env.SUPERCODE_BOARD_GENERATION_OWNER) === process.ppid;
+const nested = new AsyncLocalStorage();
+let admitting = !inBoardGeneration, writing = !inBoardGeneration, running = 0, ended = false;
+let waiters = [], drained = [];
+
+export async function generationWork(work) {
+  if (!inBoardGeneration) return work();
+  while (!admitting && !nested.getStore()?.active) {
+    if (ended) throw new Error('the board generation stopped before this work began');
+    await new Promise((done, reject) => waiters.push({ done, reject }));
+  }
+  running++;
+  const scope = { active: true };
+  try { return await nested.run(scope, work); }
+  finally { scope.active = false; if (--running === 0) { for (const done of drained.splice(0)) done(); } }
+}
+
+export function assertGenerationWriter() {
+  if (inBoardGeneration && !writing) throw new Error('this board generation is parked; no write was made');
+}
+
+export function admitGeneration() {
+  writing = true; admitting = true;
+  for (const { done } of waiters.splice(0)) done();
+}
+
+export function grantGenerationWriter() { writing = true; }
+export function stopGeneration() {
+  ended = true; admitting = false;
+  for (const { reject } of waiters.splice(0)) reject(new Error('the board generation is stopping'));
+}
+
+export async function parkGeneration(settle) {
+  admitting = false;
+  if (running) await new Promise(done => drained.push(done));
+  // Document settlement can enter ownCall itself. It is admitted as the final writer scope, never queued behind
+  // the admission boundary it is settling. Detached children of that scope must drain before authority is revoked.
+  const scope = { active: true };
+  try { await nested.run(scope, settle); } finally { scope.active = false; }
+  if (running) await new Promise(done => drained.push(done));
+  writing = false;
+}
+
+export const tellOwner = frame => { if (inBoardGeneration && process.connected) process.send(frame); };

package/board/listing.mjs

@@ -54,8 +54,19 @@ export const TASK_SUMMARY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS ${TASK_SUMMARY
 const RUN_METADATA = `CASE WHEN json_valid(r.metadata) THEN json_object('supercode', json_object(
   'address',json_extract(r.metadata,'$.supercode.address'),'session_id',json_extract(r.metadata,'$.supercode.session_id'),
   'close_confirmed_at',json_extract(r.metadata,'$.supercode.close_confirmed_at'),'released',json_extract(r.metadata,'$.supercode.released'),
-  'presence_observation',json_extract(r.metadata,'$.supercode.presence_observation'),'idle_observation',json_extract(r.metadata,'$.supercode.idle_observation')
-)) END`;
+  'presence_observation',json_extract(r.metadata,'$.supercode.presence_observation'),'idle_observation',json_extract(r.metadata,'$.supercode.idle_observation'),
+  'machine',json_extract(r.metadata,'$.supercode.machine'),'offline_since',json_extract(r.metadata,'$.supercode.offline_since'),
+  'idle_since',json_extract(r.metadata,'$.supercode.idle_since'),'unknown_since',json_extract(r.metadata,'$.supercode.unknown_since'),
+  'question',json_extract(r.metadata,'$.supercode.question.question')
+), 'last_events', json_object('heartbeat', json_extract(r.metadata,'$.last_events.heartbeat'))) END`;
+// What a working card's session reading needs beside its current run (session-work.mjs executionOf, readingContext reads
+// the same): the current run's latest heartbeat event (a declared wait, --until) and, with no current run, its latest
+// run. Read only for the working lanes.
+const WORKING_LANE = "COALESCE(c.stage,t.status) IN ('running','review')";
+const READING_CONTEXT = `CASE WHEN ${WORKING_LANE} THEN (SELECT json_object('payload',CASE WHEN json_valid(e.payload) THEN json(e.payload) END,'at',e.created_at,'run_id',e.run_id)
+    FROM task_events e WHERE e.task_id = t.id AND e.kind = 'heartbeat' AND e.run_id = t.current_run_id ORDER BY e.id DESC LIMIT 1) END AS heartbeat_event,
+  CASE WHEN ${WORKING_LANE} AND t.current_run_id IS NULL THEN (SELECT json_object('status',l.status,'outcome',l.outcome,'ended_at',l.ended_at,'error',substr(l.error,1,300))
+    FROM task_runs l WHERE l.task_id = t.id ORDER BY l.id DESC LIMIT 1) END AS last_run`;
 export const LIST_CANDIDATES_SQL = `SELECT MAX(id) AS last, json_group_array(id) AS ids FROM (
   SELECT id FROM tasks WHERE id > ? AND id <= ? ORDER BY id LIMIT ${LIST_BATCH})`;
 
@@ -71,7 +82,8 @@ export const LAST_BLOCK_SQL = `SELECT CASE WHEN kind = 'blocked' THEN payload EN
 export function listPageSql(detailed, tagCount = 0, options = {}) {
   return `SELECT t.rowid AS list_order,${(detailed ? JSON_FIELDS : HUMAN_FIELDS).split(',').map(name => `t.${name}`).join(',')},
     n.number,c.machine,c.stage,c.paused,c.blocked_by,c.detached${detailed ? ',c.subtask_of' : ''},
-    r.id AS run_id,r.status AS run_status,r.started_at AS run_started_at,r.ended_at AS run_ended_at,${RUN_METADATA} AS run_metadata
+    r.id AS run_id,r.status AS run_status,r.started_at AS run_started_at,r.ended_at AS run_ended_at,${RUN_METADATA} AS run_metadata,
+    ${READING_CONTEXT}
     ${detailed ? `,(SELECT json_group_array(parent_id) FROM (SELECT parent_id FROM task_links WHERE child_id = t.id ORDER BY parent_id)) AS parents_json,
       (${LAST_BLOCK_SQL}) AS block_payload` : ''}
     FROM tasks t ${detailed ? '' : `INDEXED BY ${TASK_SUMMARY_INDEX}`} LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN supercode_card_numbers n ON n.task_id = t.id
@@ -108,10 +120,10 @@ async function readCardsInTurns(db, { detailed = false, status = null, assignee
       status, status, status, status, assignee, assignee, machine, machine, includeSubtasks ? 1 : 0, includeArchived ? 1 : 0,
       tenant, tenant, session, session, workflowTemplateId, workflowTemplateId, stepKey, stepKey, ...tags.flatMap(tag => [tag, tag, tag])));
     measured('row projection', () => {
-      for (const { run_id, run_status, run_started_at, run_ended_at, run_metadata, parents_json, block_payload, ...task } of rows) {
+      for (const { run_id, run_status, run_started_at, run_ended_at, run_metadata, heartbeat_event, last_run, parents_json, block_payload, ...task } of rows) {
         const metadata = run_id ? parse(run_metadata, {}) : null;
         const run = run_id ? { id: run_id, status: run_status, started_at: run_started_at, ended_at: run_ended_at, metadata } : null;
-        task.execution = executionOf(run);
+        task.execution = executionOf(run, { heartbeat: parse(heartbeat_event, null), last: parse(last_run, null) });
         if (detailed) {
           task.skills = parse(task.skills, []);
           task.workflow_status = task.stage ?? task.status;

package/board/owner-door-worker.mjs

@@ -12,18 +12,24 @@ import { ownHome } from './owner-files.mjs';
 import { writeOwnerAnswer } from './reply.mjs';
 import { holdWorkflow } from './workflow.mjs';
 
-const { root, machine } = workerData;
+const { root, machine, readListings = true } = workerData;
 const waiting = new Map(); // request id → its answer's resolve
-let next = 0;
+const MAX_REQUEST = 8 * 1024 * 1024, MAX_PENDING = 64 * 1024 * 1024;
+let next = 0, pendingBytes = 0, inputBytes = 0, connections = 0;
+const refused = message => ({ code: 1, stdout: '', stderr: `supercode workflow: ${message}; no operation was submitted\n` });
 parentPort.on('message', (frame) => {
   if (frame.type === 'health') holdOwnerHealth(frame.boards, frame.round);
   else if (frame.type === 'workflow') holdWorkflow(frame.root, frame.entry);
-  else if (frame.type === 'answer') { waiting.get(frame.id)?.(frame.answer); waiting.delete(frame.id); }
+  else if (frame.type === 'answer') { const held = waiting.get(frame.id); if (held) { pendingBytes -= held.bytes; waiting.delete(frame.id); held.resolve(frame.answer); } }
 });
 await knowLocalMachine(machine);
 ownHome(root);
 
-const byOwner = (line) => new Promise((resolve) => { const id = ++next; waiting.set(id, resolve); parentPort.postMessage({ type: 'request', id, line }); });
+const byOwner = line => {
+  const bytes = Buffer.byteLength(line);
+  if (waiting.size >= 256 || pendingBytes + inputBytes + bytes > MAX_PENDING) return Promise.resolve(refused('the owner request queue reached its bound'));
+  return new Promise(resolve => { const id = ++next; pendingBytes += bytes; waiting.set(id, { resolve, bytes }); parentPort.postMessage({ type: 'request', id, line }); });
+};
 const isListing = (line) => {
   try {
     const request = JSON.parse(line);
@@ -31,23 +37,32 @@ const isListing = (line) => {
   } catch { return false; } // the owner answers what it cannot read
 };
 const answer = async (line) => {
-  if (!isListing(line)) return byOwner(line);
+  if (!readListings || !isListing(line)) return byOwner(line);
   const read = await answerOne(root, line, { readOnly: true });
   return read.byOwner ? byOwner(line) : read;
 };
 
 // allowHalfOpen: a caller that ends its side after its request still gets the answer, written when it is ready
 const server = createServer({ allowHalfOpen: true }, (socket) => {
-  let input = '';
+  if (connections >= 256) { socket.destroy(); return; }
+  connections++;
+  let input = '', heldBytes = 0;
+  const release = () => { inputBytes -= heldBytes; heldBytes = 0; };
+  socket.once('close', () => { release(); connections--; });
   socket.setEncoding('utf8');
   socket.on('error', () => { /* the caller went away */ });
   socket.on('data', (chunk) => {
     if (input === null) return;
+    const bytes = Buffer.byteLength(chunk);
+    if (heldBytes + bytes > MAX_REQUEST || pendingBytes + inputBytes + bytes > MAX_PENDING) {
+      release(); input = null; void writeOwnerAnswer(socket, refused('the request exceeded its byte bound')).catch(() => socket.destroy()); return;
+    }
+    heldBytes += bytes; inputBytes += bytes;
     input += chunk;
     const end = input.indexOf('\n');
     if (end < 0) return;
     const line = input.slice(0, end);
-    input = null;
+    input = null; release();
     // one answer per call, whatever the request did: a request that fails is a failed answer, never the door's end
     answer(line)
       .catch((error) => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` }))

package/board/owner-door.mjs

@@ -16,8 +16,8 @@ const failed = (error) => ({ code: 1, stdout: '', stderr: `supercode workflow: $
  * it. A door that ends while the owner runs leaves the home with no door: the owner says so and exits, for its keeper to
  * start it again. Answers the door's close.
  */
-export async function openOwnerDoor(root, { machine, answer, log }) {
-  const worker = new Worker(new URL('./owner-door-worker.mjs', import.meta.url), { name: 'supercode board door', workerData: { root, machine } });
+export async function openOwnerDoor(root, { machine, answer, log, readListings = true }) {
+  const worker = new Worker(new URL('./owner-door-worker.mjs', import.meta.url), { name: 'supercode board door', workerData: { root, machine, readListings } });
   let open = false, closing = false;
   const send = (frame) => { try { worker.postMessage(frame); } catch (error) { log(`board door: could not hand the door ${frame.type}: ${error.message}`); } };
   const stops = [