@volter/supercode-orchestrator 0.5.227 → 0.5.229

package/board/generation-owner.mjs

@@ -1,21 +1,26 @@
+import { nativeJsonEqual } from '@volter/supercode-interchange/native-json';
+import { measureWork, registerWorkOperations, stopWorkChild } from "@volter/supercode-harness-sdk/work-ledger";
+registerWorkOperations([{"kind":"pass","operation":"board-owner.record"},{"kind":"pass","operation":"board-owner.activate"},{"kind":"pass","operation":"board-owner.prepare"},{"kind":"pass","operation":"board-owner.rollback"},{"kind":"pass","operation":"board-owner.switch"},{"kind":"door","operation":"board-owner.control"},{"kind":"door","operation":"board-owner.command"}]);
+import { registerWorkService, closeWorkLedger } from '@volter/supercode-harness-sdk/work-ledger';
 // 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 { dropOwnCallerIdentity } from '@volter/supercode-teams/service-environment';
 import { spawn } from 'node:child_process';
 import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { isAbsolute, 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 { sourceTransaction, readBoardSourceReservation } 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';
+import { holdWorkflow } from './owner-interface.mjs';
+import { knowLocalMachine, localMachine } from './owner-interface.mjs';
+import { parse } from './owner-interface.mjs';
+import { publishStandaloneDeclaration } from './standalone-declaration.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` });
@@ -25,21 +30,45 @@ const failed = error => ({ code: 1, stdout: '', stderr: `supercode workflow: ${e
 const READS = new Set(['show', 'list', 'ls', 'context', 'brief', 'runs', 'log', 'stats', 'assignees', 'attachments', 'attachment-read', 'notify-list']);
 const READ_MS = 8000;
 
-export async function serveBoardOwner(root, args) {
+export async function serveBoardOwner(root, args, firstReaderEpoch) {
+  // Service admission (runWorkflow) was the starting caller's act. The owner and every generation, lock holder and
+  // command it starts afterwards act as the install, never as that caller (ADR 0080, "Resident startup"; ADR 0013,
+  // "A service carries no caller's identity"): a card agent's context kept here would refuse every remote launch once
+  // that agent ended.
+  dropOwnCallerIdentity();
   root = boardHome(root);
+  registerWorkService({role:'board-owner',scope:{kind:'install',id:root}});
   mkdirSync(root, { recursive: true });
+  // The service owns its working directory; the file arguments stay the caller's. A path the starter named is bound
+  // against the starter's directory here, before the owner leaves it for its home: a removed starter directory would
+  // otherwise fail every generation it starts (and the harness service each runs) at process.cwd(), so no handover
+  // could prepare a successor.
+  const pidfile = args.pidfile ? resolve(args.pidfile) : null;
+  process.chdir(root);
   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;
+  let stopping = false, active = null, previous = null, transition = null, routing = null, pending = null, recoveryFailure = null, lastRestingReader = null;
   const generations = new Set(), waiting = new Set();
+  // Generations told to end that outlived TERM and KILL, by pid: named in the generation record and the status until
+  // their process exits, so a superseded worker is never left running silently.
+  const unended = new Map();
   const recordPath = join(root, 'board-generation.json');
-  const record = child => {
+  const record = (child, stopped = false) => {
+    return measureWork("pass", "board-owner.record", () => {
     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 && !previous.ended ? previous.process.pid : null, at_ms: Date.now() }) + '\n', { mode: 0o600 });
+    writeFileSync(temporary, JSON.stringify({ version: 1, owner: stopped ? null : process.pid, active: child?.process.pid ?? null,
+      selected: child?.selected ?? null, generation: child?.id ?? null, previous: stopped ? null : previous && !previous.ended ? previous.process.pid : null, unended: [...unended.values()], restingReaderProtocol: 1, lastRestingReader, stopped, 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); } });
+  // Only the lock holder lends actual acknowledged reader history. A candidate selected before writer grant
+  // cannot become this record; an older writer invalidates it before activation.
+  try {
+    const prior = JSON.parse(readFileSync(recordPath, 'utf8'));
+    if (prior.version === 1 && prior.restingReaderProtocol === 1 && prior.lastRestingReader?.version === 1) lastRestingReader = prior.lastRestingReader;
+  } catch { /* no retained reader: conservative legacy admission */ }
   await knowLocalMachine();
   const entry = resolve(process.env.SUPERCODE_ORCHESTRATOR_ENTRY || fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url)));
   const start = selected => {
@@ -57,7 +86,7 @@ export async function serveBoardOwner(root, args) {
       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(),
+    const generation = { process: processChild, selected, id: generationId, calls: new Map(), events: new Map(), ended: false, workflows: new Map(),
       heard: Date.now(), silenceSaid: false };
     generation.exited = new Promise(done => { processChild.once('exit', done); processChild.once('error', done); });
     generations.add(generation);
@@ -93,8 +122,8 @@ export async function serveBoardOwner(root, args) {
       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);
+        stopWorkChild(processChild, () => processChild.kill('SIGTERM'), { signal: 'SIGTERM' });
+        const bound = setTimeout(() => stopWorkChild(processChild, () => processChild.kill('SIGKILL'), { signal: 'SIGKILL' }), 2000);
         generation.exited.finally(() => clearTimeout(bound));
       }
       generations.delete(generation);
@@ -120,6 +149,21 @@ export async function serveBoardOwner(root, args) {
     processChild.on('message', frame => {
       generation.heard = Date.now(); generation.silenceSaid = false;
       if (!frame || typeof frame.type !== 'string') return;
+      if (frame.type === 'resting-writer-granted') {
+        try {
+          const proof = generation.events.get('prepared');
+          if (!generation.writerRequested || generation.ended || frame.generation !== generation.id ||
+              typeof frame.request !== 'string' || frame.request.length > 128 || proof?.restingReaderProtocol !== 1 || !proof.resting)
+            throw new Error('generation has no matching prepared resting-state writer grant');
+          const next = { version: 1, selected: generation.selected, resting: proof.resting };
+          if (!nativeJsonEqual(lastRestingReader, next)) lastRestingReader = next;
+          record(generation);
+          tell({ type: 'resting-reader-recorded', request: frame.request, generation: generation.id });
+        } catch (error) {
+          try { tell({ type: 'resting-reader-recorded', request: frame.request, generation: generation.id, error: error.message }); } catch { /* child disconnected */ }
+        }
+        return;
+      }
       if (frame.type === 'startup-step') {
         generation.startupStep = frame.step;
         if (Number.isSafeInteger(frame.budget_ms) && frame.budget_ms >= 1 && frame.budget_ms <= 65000)
@@ -127,7 +171,6 @@ export async function serveBoardOwner(root, args) {
         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); }
@@ -136,11 +179,32 @@ export async function serveBoardOwner(root, args) {
     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); }
-  };
+  // Ending a generation: TERM, KILL 2 s later, then 3 s for its exit. Each end is said in this owner's log with why;
+  // one that has not exited 5 s after TERM is said, kept in `unended` (record and status) until it exits, and resolves
+  // false, so no caller waits on it forever. Ending is idempotent: a generation already ended answers at once.
+  const terminate = (generation, why) => generation.ending ??= (async () => {
+    const child = generation.process, began = Date.now();
+    const exited = ms => {
+      let timer;
+      return Promise.race([generation.exited.then(() => true), new Promise(done => { timer = setTimeout(() => done(false), ms); })]).finally(() => clearTimeout(timer));
+    };
+    const name = `generation ${generation.id} (pid ${child.pid})`;
+    if (child.exitCode !== null || child.signalCode !== null || child.pid === undefined) { await generation.exited; return true; }
+    stopWorkChild(child, () => child.kill('SIGTERM'), { signal: 'SIGTERM' });
+    let by = 'TERM';
+    if (!await exited(2000)) {
+      by = 'KILL'; stopWorkChild(child, () => child.kill('SIGKILL'), { signal: 'SIGKILL' });
+      if (!await exited(3000)) {
+        unended.set(child.pid, { pid: child.pid, generation: generation.id, why, since_ms: began });
+        log(`${name} did not exit ${Date.now() - began} ms after TERM and KILL (${why}); it is still running and is named in board-generation.json until it exits`);
+        generation.exited.then(() => { if (unended.delete(child.pid)) { log(`${name} exited ${Date.now() - began} ms after it was told to end`); record(active); } });
+        generation.ending = null; record(active);
+        return false;
+      }
+    }
+    log(`${name} ended by ${by} in ${Date.now() - began} ms: ${why}`);
+    return true;
+  })();
   // Whether every request already sent to a generation was answered (or the generation ended) within the bound.
   // New requests are held at the door meanwhile, so nothing more is sent to it.
   const drained = (generation, ms = 8000) => {
@@ -150,8 +214,11 @@ export async function serveBoardOwner(root, args) {
     }), new Promise(done => { timer = setTimeout(() => done(false), ms); })]).finally(() => clearTimeout(timer));
   };
   const activate = async generation => {
+    return measureWork("pass", "board-owner.activate", async () => {
     if (stopping || generation.ended) throw new Error('cannot activate an ended board generation');
+    if (generation.events.get('prepared')?.restingReaderProtocol !== 1) lastRestingReader = null;
     record(generation);
+    generation.writerRequested = true;
     generation.events.delete('routable'); generation.events.delete('serving');
     generation.tell({ type: 'activate' });
     log(`generation ${generation.id} (pid ${generation.process.pid}) activates`);
@@ -171,13 +238,26 @@ export async function serveBoardOwner(root, args) {
     // 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']);
+    const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+    const count = value => Number.isSafeInteger(value) && value >= 0;
+    const counts = value => object(value) && Object.values(value).every(count);
+    const grouped = value => object(value) && Object.values(value).every(counts);
+    const declaration = await read(['declaration', '--json']);
+    if (!object(declaration) || typeof declaration.board !== 'string'
+      || ![null, 'sqlite', 'files', 'ztrack'].includes(declaration.backing)
+      || !(declaration.declared === null || object(declaration.declared)))
+      throw new Error('successor declaration readback was not a board declaration; predecessor retained');
     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]);
+      const stats = await read(['stats', '--json', '--board', slug]);
+      if (!object(stats) || !counts(stats.by_status) || !counts(stats.by_lane)
+        || !grouped(stats.by_assignee) || !grouped(stats.by_machine)
+        || !(stats.oldest_ready_age_seconds === null || Number.isFinite(stats.oldest_ready_age_seconds))
+        || !object(stats.backlog) || !count(stats.backlog.total)
+        || !counts(stats.backlog.by_assignee) || !counts(stats.backlog.by_machine) || !Number.isFinite(stats.now))
+        throw new Error(`successor ${slug} stats readback was not board statistics; predecessor retained`);
     }
     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} routed (pid ${generation.process.pid})`);
@@ -193,13 +273,26 @@ export async function serveBoardOwner(root, args) {
       }
       throw error;
     }
+    publishStandaloneDeclaration(root, generation.selected);
     log(`generation ${generation.id} serves (pid ${generation.process.pid})`);
+    // Its first clean round recorded, this generation is the board's one writer. No path resumes a parked or superseded
+    // generation (a rollback after parking starts a fresh one from the predecessor's selection), so every other
+    // generation ends here, never waiting on the transaction's finish: only a prepared candidate not yet activated stays.
+    for (const other of [...generations]) {
+      if (other === generation || (pending?.phase === 'prepared' && other === pending.candidate)) continue;
+      await terminate(other, `superseded by generation ${generation.id} (pid ${generation.process.pid}) after its first clean round`);
+    }
+    record(generation);
     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 status = () => ({ version: 1, protocol: 1, restingReaderProtocol: 1, lastRestingReader, owner: process.pid, state: routing ? 'serving' : 'transitioning',
+    firstReaderEpoch: !active && !lastRestingReader ? firstReaderEpoch : null,
+    generation: active?.id, pid: active?.process.pid, selected: active?.selected, previous: previous?.selected ?? pending?.before ?? null,
+    transaction: pending?.id ?? null, phase: pending?.phase ?? null, failure: recoveryFailure?.message ?? null, unended: [...unended.values()] });
   const prepare = async (id, selected) => {
+    return measureWork("pass", "board-owner.prepare", async () => {
     if (pending) {
       if (pending.id === id) {
         if (JSON.stringify(pending.candidate.selected) !== JSON.stringify(selected)) throw new Error('board transaction already names different inputs');
@@ -218,27 +311,33 @@ export async function serveBoardOwner(root, args) {
       // modules' source, which is then compared.
       const same = proof.format && held?.format ? proof.format === held.format || (Array.isArray(proof.readableBy) && proof.readableBy.includes(held.format)) : Boolean(proof.storage) && proof.storage === held?.storage;
       if (!same) throw new Error('board storage contract differs; predecessor retained without opening a writer');
-      pending = { id, candidate, predecessor: active, older: previous, phase: 'prepared' };
+      pending = { id, candidate, predecessor: active, before: active.selected, older: previous, phase: 'prepared' };
       return status();
-    } catch (error) { await terminate(candidate); throw error; }
+    } catch (error) { await terminate(candidate, `its preparation failed: ${error.message}`); throw error; }
+
+    });
   };
   const rollback = async () => {
+    return measureWork("pass", "board-owner.rollback", async () => {
     const held = pending;
     if (!held) return status();
-    await terminate(held.candidate);
+    await terminate(held.candidate, 'the handover rolls back');
     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);
+      if (held.predecessor) await terminate(held.predecessor, 'the handover rolls back after it parked; a fresh generation starts from its selection');
+      const replacement = start(held.before);
       try { await replacement.wait('prepared'); await activate(replacement); }
-      catch (error) { await terminate(replacement); throw error; }
+      catch (error) { await terminate(replacement, `its activation failed: ${error.message}`); throw error; }
     } else if (!held.predecessor.ended) { active = routing = held.predecessor; changed(); }
     pending = null; record(active); return status();
+
+    });
   };
   const switchPrepared = async () => {
+    return measureWork("pass", "board-owner.switch", 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');
@@ -256,44 +355,57 @@ export async function serveBoardOwner(root, args) {
       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 => {
+  // A handover's file operands are its caller's, read against the directory its request carries (board-owner.mjs).
+  const control = async (parsed, cwd) => {
+    // Every operand, absolute or relative, goes through one resolve, so a selection compares in one canonical form.
+    const callerPath = value => {
+      const base = typeof cwd === 'string' && isAbsolute(cwd) ? cwd : null;
+      if (!base && !isAbsolute(value)) throw new Error('a relative handover path needs the caller\'s working directory');
+      return base ? resolve(base, value) : resolve(value);
+    };
+    return measureWork("door", "board-owner.control", async () => {
     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 });
+      await prepare(id, { entry: callerPath(parsed.entry), native: callerPath(parsed.supercode), candidate: parsed.candidate ? callerPath(parsed.candidate) : null, release: parsed.release ? callerPath(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 (pending) sourceTransaction(id, pending.candidate.selected, pending.before, 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');
+      sourceTransaction(id, pending.candidate.selected, pending.before, 'finish', process.env, 'board');
       if (pending.phase !== 'activated') throw new Error('board successor was never activated');
       if (pending.candidate.ended) {
-        await terminate(pending.candidate);
+        await terminate(pending.candidate, 'the activated successor ended before the handover finished');
         const replacement = start(pending.candidate.selected);
         try { await replacement.wait('prepared'); await activate(replacement); pending.candidate = replacement; }
-        catch (error) { await terminate(replacement); throw error; }
+        catch (error) { await terminate(replacement, `its activation failed: ${error.message}`); throw error; }
       }
       if (routing !== pending.candidate || active.ended) throw new Error('board successor is not serving; handover cannot finish');
-      // The parked predecessor is no rollback once the transaction is finished: no path resumes a parked generation
-      // (a rollback after parking starts a fresh one from its selection), so every generation but the serving one ends
-      // here. `previous` keeps naming the selection it served.
-      for (const retained of generations) if (retained !== active) await terminate(retained);
+      // The successor's first clean round already ended its predecessor (activate); any generation still held but the
+      // serving one ends here too. `previous` keeps naming the selection it served.
+      for (const retained of [...generations]) if (retained !== active) await terminate(retained, `the handover ${id} finished`);
+      publishStandaloneDeclaration(root, active.selected);
       pending = null; record(active);
     } else if (!['prepare', 'activate'].includes(action)) throw new Error('unknown board handover action');
     return status();
+
+    });
   };
   const answer = async line => {
+    return measureWork("door", "board-owner.command", async () => {
     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);
+      transition = control(parsed, request.cwd);
       try { return { code: 0, stdout: JSON.stringify(await transition) + '\n', stderr: '' }; }
       catch (error) { return failed(error); }
       finally { transition = null; changed(); }
@@ -316,34 +428,57 @@ export async function serveBoardOwner(root, args) {
       if (!serving.silenceSaid) { serving.silenceSaid = true; log(`generation ${serving.id} (pid ${serving.process.pid}) did not answer a ${verb} within ${READ_MS / 1000} s; its last message came ${quiet} s before`); }
       return failed(new Error(`the board's serving generation (pid ${serving.process.pid}) did not answer this ${verb} within ${READ_MS / 1000} s (its last message to the board owner came ${quiet} s before); nothing was read: ask again`));
     });
+
+    });
   };
   let closeDoor;
+  let failure, hadFailure = false;
   const stop = () => {
     if (stopping) return;
     stopping = true; changed();
-    for (const generation of generations) if (!generation.ended) generation.process.kill('SIGTERM');
+    for (const generation of generations) if (!generation.ended) stopWorkChild(generation.process, () => generation.process.kill('SIGTERM'), { signal: '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) });
+    const selected = { entry, native: process.env.SUPERCODE_BIN, candidate: process.env.SUPERCODE_SOURCE_CANDIDATE || null, release: process.env.SUPERCODE_SOURCE_CANDIDATE ? null : retainedReceipt(entry) };
+    const reservation = await readBoardSourceReservation(root);
+    const first = start(reservation?.selected ?? selected);
     await first.wait('prepared');
+    if (reservation?.phase === 'activated') pending = { id: reservation.id, candidate: first,
+      predecessor: null, before: reservation.before, older: null, phase: 'activated' };
     await activate(first);
+    if (reservation?.phase === 'prepared') await prepare(reservation.id, reservation.target);
     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`);
+    if (pidfile) writeFileSync(pidfile, `${process.pid}\n`);
     while (!stopping) await new Promise(done => waiting.add(done));
+  } catch (error) {
+    hadFailure = true; failure = error; throw error;
   } 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();
+    const errors = [];
+    const attempt = async work => { try { await work(); } catch (error) { errors.push(error); } };
+    await attempt(() => stop());
+    for (const result of await Promise.allSettled([...generations].map(generation => terminate(generation, 'the board owner stops'))))
+      if (result.status === 'rejected') errors.push(result.reason);
+    await attempt(() => closeDoor?.());
+    await attempt(() => rmSync(boardOwnerSocket(root), { force: true }));
+    await attempt(() => {
+      try { if (JSON.parse(readFileSync(recordPath, 'utf8')).owner === process.pid) {
+        if (lastRestingReader || unended.size) record(null, true);
+        else rmSync(recordPath);
+      } }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    });
+    // Releasing the lock is attempted even when the public door failed to close. Join both owned exits before
+    // the final checkpoint, so their known completions and durations cannot remain in flight in a closed row.
+    await attempt(() => lock.release());
     for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(signal, stop);
-    if (args.pidfile) rmSync(args.pidfile, { force: true });
+    if (pidfile) await attempt(() => rmSync(pidfile, { force: true }));
+    await closeWorkLedger();
+    if (errors.length) throw new AggregateError([...(hadFailure ? [failure] : []), ...errors], 'board owner shutdown failed', { cause: hadFailure ? failure : errors[0] });
   }
   return 0;
 }

package/board/git-document.mjs

@@ -1,3 +1,5 @@
+import { measureSyncChild } from '@volter/supercode-harness-sdk/work-ledger';
+const execFileSync = (...args) => measureSyncChild(() => workLedgerNativeExecFileSync(...args));
 // THE BOARD DOCUMENT IN GIT (company RFC 0025 decision 3; ADR 0001 points 2 and 3): when the board's document lives in a
 // git checkout and the board says so (`"commit": true` in its ztrack.json), each write the manager does not make (its
 // `"manager"`) is committed with its doer as author and pushed, after the checkout has taken what others pushed. People edit the document both here
@@ -30,7 +32,7 @@
 // and the push error live in a linked worktree's own git dir) are read from `.git` itself, so a board open starts no
 // process. A write does start its commit's git processes, beside the loop (A41).
 import { current } from './call.mjs';
-import { execFile, execFileSync, spawn } from 'node:child_process';
+import { execFile, execFileSync as workLedgerNativeExecFileSync, spawn } from 'node:child_process';
 import { readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 

package/board/github-rest.mjs

@@ -35,12 +35,23 @@ function connection() {
       pid INTEGER NOT NULL, caller TEXT NOT NULL, purpose TEXT NOT NULL, method TEXT NOT NULL,
       endpoint TEXT NOT NULL, code TEXT NOT NULL, reason TEXT NOT NULL);
     CREATE INDEX IF NOT EXISTS github_refusals_window ON github_refusals(started_at,purpose);
+    CREATE TABLE IF NOT EXISTS github_source_facts (key TEXT PRIMARY KEY, value TEXT NOT NULL);
     CREATE TABLE IF NOT EXISTS github_observation_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);`);
   db.prepare("INSERT OR IGNORE INTO github_observation_meta(key,value) VALUES('refusals_since',?)").run(Date.now());
   connections.set(path, db);
   return db;
 }
 
+// Source facts have no discovery TTL. Merged heads are immutable; branch watermarks
+// retain complete seeded history and are advanced only after a successful incremental read.
+export function githubSourceFact(identity, value) {
+  const key = createHash('sha256').update(identity).digest('hex'), db = connection();
+  if (value !== undefined) db.prepare(`INSERT INTO github_source_facts(key,value) VALUES(?,?)
+    ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(key, JSON.stringify(value));
+  const row = db.prepare('SELECT value FROM github_source_facts WHERE key=?').get(key);
+  return row ? JSON.parse(row.value) : null;
+}
+
 const discoveryReads = new Map();
 const discoveryPending = () => Object.assign(new Error('GitHub discovery is already being read by another process; no duplicate read was started'), { code: 'github_discovery_pending', deferred: true });
 /** Advisory observations survive command/owner restarts. Fresh transition reads never consume a cached value,
@@ -60,6 +71,12 @@ export function githubDiscoveryHeld(identity) {
   return held && held.until_at > Date.now() && held.value != null ? JSON.parse(held.value) : null;
 }
 
+/** When the observation kept for `identity` was last read (ms), or 0; no claim, no wire attempt. */
+export function githubDiscoveryObservedAt(identity) {
+  const key = createHash('sha256').update(identity).digest('hex');
+  return Number(connection().prepare('SELECT observed_at FROM github_discovery WHERE key=?').get(key)?.observed_at ?? 0);
+}
+
 export async function githubDiscovery(identity, ttl, read, { fresh = false, ttlOf = () => ttl, cacheErrors = true } = {}) {
   const key = createHash('sha256').update(identity).digest('hex');
   const localKey = `${pathOf()}\0${key}`;
@@ -111,7 +128,7 @@ export async function githubDiscovery(identity, ttl, read, { fresh = false, ttlO
   }
   return pending;
 }
-const refusal = (message) => Object.assign(new Error(message), { code: 'GITHUB_BUDGET' });
+const refusal = (message, retry_at) => Object.assign(new Error(message), { code: 'GITHUB_BUDGET', deferred: true, retry_at });
 const integer = (value) => value != null && /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
 function endpointOf(url) {
   const safe = new URL(url); safe.username = ''; safe.password = '';
@@ -133,14 +150,19 @@ async function issue(url, options, { purpose }) {
   db.exec('BEGIN IMMEDIATE');
   try {
     const blocked = db.prepare('SELECT until_at,reason FROM github_cooldown WHERE credential=?').get(credential);
-    if (blocked?.until_at > at) throw refusal(`GitHub REST deferred until ${new Date(blocked.until_at).toISOString()}: ${blocked.reason}`);
     const count = db.prepare(`SELECT COUNT(*) total, COALESCE(SUM(purpose='discovery'),0) discovery
       FROM github_attempts WHERE started_at>?`).get(at - HOUR);
-    if (count.total >= GITHUB_HOURLY_ATTEMPTS || purpose === 'discovery' && count.discovery >= GITHUB_DISCOVERY_ATTEMPTS) {
-      const oldest = db.prepare(`SELECT MIN(started_at) at FROM github_attempts WHERE started_at>?
-        AND (?='total' OR purpose='discovery')`).get(at - HOUR, count.total >= GITHUB_HOURLY_ATTEMPTS ? 'total' : 'discovery');
-      throw refusal(`GitHub ${purpose} deferred by this home's REST budget (${count.total}/${GITHUB_HOURLY_ATTEMPTS} total, ${count.discovery}/${GITHUB_DISCOVERY_ATTEMPTS} discovery in the last hour); retry after ${new Date(oldest.at + HOUR + 1).toISOString()}`);
+    // Expire enough attempts to get below *every* applicable limit. MIN is wrong after an
+    // over-limit retained window, and the discovery and total counters may free at different times.
+    let retryAt = blocked?.until_at > at ? blocked.until_at : 0;
+    for (const [kind, used, limit] of [['total', count.total, GITHUB_HOURLY_ATTEMPTS],
+      ...(purpose === 'discovery' ? [['discovery', count.discovery, GITHUB_DISCOVERY_ATTEMPTS]] : [])]) {
+      if (used < limit) continue;
+      const expiry = db.prepare(`SELECT started_at FROM github_attempts WHERE started_at>?
+        AND (?='total' OR purpose='discovery') ORDER BY started_at LIMIT 1 OFFSET ?`).get(at - HOUR, kind, used - limit);
+      retryAt = Math.max(retryAt, expiry.started_at + HOUR + 1);
     }
+    if (retryAt) throw refusal(`GitHub ${purpose} deferred by this home's REST budget/provider hold (${count.total}/${GITHUB_HOURLY_ATTEMPTS} total, ${count.discovery}/${GITHUB_DISCOVERY_ATTEMPTS} discovery in the last hour); earliest eligibility ${new Date(retryAt).toISOString()}, subject to admission recheck${blocked?.until_at > at ? `: ${blocked.reason}` : ''}`, retryAt);
     db.prepare('INSERT INTO github_attempts(id,credential,started_at,machine,pid,caller,purpose,method,endpoint) VALUES(?,?,?,?,?,?,?,?,?)')
       .run(id, credential, at, hostname(), process.pid, caller, purpose, method, endpoint);
     db.exec('COMMIT');
@@ -169,7 +191,7 @@ async function issue(url, options, { purpose }) {
       (response?.status === 429 || response?.status === 403) && retry != null ? Date.now() + retry * 1000 : 0,
       remaining === 0 && reset == null ? Date.now() + 60_000 : 0);
     if (until > Date.now()) db.prepare(`INSERT INTO github_cooldown(credential,until_at,reason) VALUES(?,?,?)
-      ON CONFLICT(credential) DO UPDATE SET until_at=MAX(until_at,excluded.until_at),reason=excluded.reason`)
+      ON CONFLICT(credential) DO UPDATE SET reason=CASE WHEN excluded.until_at>until_at THEN excluded.reason ELSE reason END,until_at=MAX(until_at,excluded.until_at)`)
       .run(credential, until, remaining === 0 ? `${resource ?? 'REST'} remaining=0 on ${endpoint}` : `HTTP ${response.status} Retry-After on ${endpoint}`);
   }
 }

package/board/incidents.mjs

@@ -1,3 +1,4 @@
+import { latestEvent } from './queries.mjs';
 // Service supervision retains evidence; only a manager/creator act releases dispatch.
 import { event, json, now } from './store.mjs';
 import { detachedCard, detachedSession } from './custody.mjs';
@@ -65,27 +66,14 @@ export function surfaceIncident(db, board, entry, id, name, evidence = {}, runId
 /** Older ended runs are audited before eligibility: a completed run is not permission to repeat. */
 export function auditEndedRuns(db, board, entry) {
   if (recoversRuns(entry)) {
-    // Retained positive exit receipts from an earlier version qualify the same
-    // failed-before-live fallback as a newly supervised resume. An unknown
-    // reading, a mere ended row or a once-live resume does not qualify.
-    for (const row of db.prepare(`SELECT r.id,r.metadata FROM task_runs r JOIN tasks t ON t.id=r.task_id
-      WHERE r.id=(SELECT MAX(id) FROM task_runs WHERE task_id=t.id) AND r.ended_at IS NOT NULL
-      AND t.current_run_id IS NULL AND t.status NOT IN ('done','cancelled','archived')`).all()) {
-      const metadata = json(row.metadata, {}), session = metadata.supercode;
-      if (detachedSession(db, session)) continue;
-      if (session?.mode !== 'resume' || session.seen_at || session.resume_failed_before_live) continue;
-      const exit = db.prepare("SELECT 1 FROM task_events WHERE run_id=? AND kind='run_incident' AND json_extract(payload,'$.observation')='exited' AND json_extract(payload,'$.evidence.code')=1").get(row.id);
-      if (!exit) continue;
-      metadata.supercode = { ...session, resumable: false, resume_failed_before_live: true };
-      db.prepare('UPDATE task_runs SET metadata=? WHERE id=?').run(JSON.stringify(metadata), row.id);
-    }
+    // A failed native resume preserves its conversation. Historical failures grant no fresh-session permission.
     // The older organization workflow automatically paused a clean native exit.
     // Release only that exact platform outcome, never a person's later pause.
     for (const task of db.prepare(`SELECT t.id,c.paused FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
       WHERE t.current_run_id IS NULL AND t.status NOT IN ('done','cancelled','archived') AND c.paused IS NOT NULL AND NOT COALESCE(c.archived,0)`).all()) {
       const pause = json(task.paused, null);
       if (detachedCard(db, task.id)) continue;
-      const last = db.prepare("SELECT kind,payload FROM task_events WHERE task_id=? AND kind IN ('closed_by_hand','paused','resumed') ORDER BY id DESC LIMIT 1").get(task.id);
+      const last = latestEvent(db, task.id, ['closed_by_hand', 'paused', 'resumed'], 'kind,payload');
       const ended = json(last?.payload, {});
       // The machine may have moved since this run. Match the retained board
       // actor's exact label, never a user's actor or just the reason text.
@@ -101,10 +89,10 @@ export function auditEndedRuns(db, board, entry) {
       WHERE t.current_run_id IS NULL AND r.ended_at IS NOT NULL AND t.status IN ('running','review')`).all()) {
       const session = json(task.run_metadata, {})?.supercode;
       if (detachedCard(db, task.id) || detachedSession(db, session)) continue;
-      if (!session?.monitor_held) continue;
+      if (!session?.monitor_held || session.continuation_required) continue;
       const state = db.prepare('SELECT paused,blocked_by,archived FROM supercode_cards WHERE task_id=?').get(task.id);
       if (json(state?.paused, null) || json(state?.blocked_by, [])?.length || state?.archived) continue;
-      const last = db.prepare("SELECT kind,payload FROM task_events WHERE task_id=? AND kind IN ('dispatch_held','dispatch_released','session_adopted') ORDER BY id DESC LIMIT 1").get(task.id);
+      const last = latestEvent(db, task.id, ['dispatch_held','dispatch_released','session_adopted'], 'kind,payload');
       const hold = json(last?.payload, {});
       if (last?.kind !== 'dispatch_held' || hold.run !== task.run_id || hold.incident !== session.incident) continue;
       requestSessionClose(db, task.id, { runId: task.run_id });