@volter/supercode-orchestrator 0.5.228 → 0.5.230

package/board/listing.mjs

@@ -3,6 +3,7 @@
 import { setImmediate as nextTurn } from 'node:timers/promises';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { executionOf } from './session-work.mjs';
+import { DISPATCH_WAIT_SQL } from './queries.mjs';
 import { CARD_VISIBILITY_SQL } from './visibility.mjs';
 import { cardState, cardStateSql } from './card-state.mjs';
 
@@ -14,6 +15,8 @@ export const READ_BY_OWNER = 'board_read_by_owner';
 export const byOwner = (reason) => Object.assign(new Error(`this listing is the board owner's to answer: ${reason}`), { code: READ_BY_OWNER });
 export const LIST_CONNECTION = Symbol.for('supercode.board.listing.connection');
 export const LIST_REVISION = Symbol.for('supercode.board.listing.revision');
+export const READ_BOUNDARY = Symbol.for('supercode.board.read.boundary');
+export const readBoundary = (db, fn) => db[READ_BOUNDARY] ? db[READ_BOUNDARY](fn) : fn();
 const parse = (text, fallback) => { try { return JSON.parse(text) ?? fallback; } catch { return fallback; } };
 const statements = new WeakMap();
 const prepared = (db, sql) => {
@@ -53,6 +56,8 @@ export const TASK_SUMMARY_INDEX = 'idx_tasks_list_summary_readable';
 export const TASK_SUMMARY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS ${TASK_SUMMARY_INDEX} ON tasks(${HUMAN_FIELDS},current_run_id,session_id,workflow_template_id,current_step_key)`;
 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'),
+  'pane',json_extract(r.metadata,'$.supercode.pane'),'pid',json_extract(r.metadata,'$.supercode.pid'),'launch_key',json_extract(r.metadata,'$.supercode.launch_key'),
+  'launch_deferred',json_extract(r.metadata,'$.supercode.launch_deferred'),'launch_deferred_error',json_extract(r.metadata,'$.supercode.launch_deferred_error'),'launched_at',json_extract(r.metadata,'$.supercode.launched_at'),
   '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'),
   'machine',json_extract(r.metadata,'$.supercode.machine'),'offline_since',json_extract(r.metadata,'$.supercode.offline_since'),
@@ -61,12 +66,13 @@ const RUN_METADATA = `CASE WHEN json_valid(r.metadata) THEN json_object('superco
 ), '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.
+// run. The dispatcher's applicable wait is read in any open lane with no current run.
 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`;
+    FROM task_runs l WHERE l.task_id = t.id ORDER BY l.id DESC LIMIT 1) END AS last_run,
+  (${DISPATCH_WAIT_SQL}) AS dispatch_wait`;
 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})`;
 
@@ -81,7 +87,7 @@ 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' : ''},
+    n.number,c.machine,c.stage,c.paused,c.backlog,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,
     ${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,
@@ -89,7 +95,7 @@ export function listPageSql(detailed, tagCount = 0, options = {}) {
     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
     LEFT JOIN task_runs r ON r.id = t.current_run_id
     WHERE t.id IN (SELECT value FROM json_each(?)) AND (? IS NULL OR ${cardStateSql(options)} = ? OR (? NOT IN ('paused','blocked') AND c.stage = ?))
-      AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND ${CARD_VISIBILITY_SQL}
+      AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? IS NULL OR (c.backlog IS NOT NULL AND c.backlog != 'null') = ?) AND ${CARD_VISIBILITY_SQL}
       AND (? IS NULL OR t.tenant = ?) AND (? IS NULL OR t.session_id = ?)
       AND (? IS NULL OR t.workflow_template_id = ?) AND (? IS NULL OR t.current_step_key = ?)
       ${Array.from({ length: tagCount }, () => `AND CASE WHEN json_valid(c.tags) THEN
@@ -112,7 +118,7 @@ export async function listCardsInTurns(db, options = {}) {
 }
 
 async function readCardsInTurns(db, { detailed = false, status = null, assignee = null, machine = null, includeArchived = false, includeSubtasks = false,
-  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [], nativeHolds = false }, revision, { inTurns = true } = {}) {
+  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [], nativeHolds = false, backlog = null }, revision, { inTurns = true } = {}) {
   const out = [];
   const page = prepared(db, listPageSql(detailed, tags.length, { nativeHolds })), candidates = prepared(db, LIST_CANDIDATES_SQL);
   const ceiling = measured('last candidate', () => prepared(db, "SELECT COALESCE(MAX(id), '') AS cursor FROM tasks").get().cursor);
@@ -122,13 +128,13 @@ async function readCardsInTurns(db, { detailed = false, status = null, assignee
     const range = measured('candidate range', () => candidates.get(cursor, ceiling));
     if (range.last == null) break;
     const rows = measured(detailed ? 'JSON task rows and latest blocks' : 'human task rows', () => page.all(range.ids,
-      status, status, status, status, assignee, assignee, machine, machine, includeSubtasks ? 1 : 0, includeArchived ? 1 : 0,
+      status, status, status, status, assignee, assignee, machine, machine, backlog == null ? null : Number(Boolean(backlog)), backlog == null ? null : Number(Boolean(backlog)), 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, heartbeat_event, last_run, 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, dispatch_wait, 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, { heartbeat: parse(heartbeat_event, null), last: parse(last_run, null) });
+        task.execution = executionOf(run, { heartbeat: parse(heartbeat_event, null), last: parse(last_run, null), queue: parse(dispatch_wait, null) });
         if (detailed) {
           task.skills = parse(task.skills, []);
           task.workflow_status = task.stage ?? task.status;

package/board/local-admission.mjs

@@ -0,0 +1,59 @@
+// A run-on-the-machine verb (client.mjs: boards, init, gc, repair, migrate, dispatch, watch, tail) runs in a process of its
+// own, never a board generation, so prepareBoardRestingAdmission (resting-admission.mjs) never binds its reader: every
+// fenced transaction it opened over a home holding a backlog or a bounded pause refused (`boards list`, a cold `init`).
+// It is admitted on the incumbent a generation is: a running owner's own status, else the record the home's stable owner
+// keeps (board-generation.json), which a cold owner lends its first generation (generation-owner.mjs). With neither, or
+// a legacy incumbent, it stays legacy and such a home still refuses it. selectedReader and recordedReader are the
+// owner's admission's (resting-admission.mjs), kept here so that storage module, and so the board format, stays as it is.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { askBoardOwner } from '@volter/teams/board-owner';
+import { nativeJsonEqual } from '@volter/supercode-interchange/native-json';
+import { readSourceCandidate } from '@volter/supercode-teams/source-selection'; // layer: the board's resting-reader admission reads the host's selected source and release (its source pins); owed: the host hands them in
+import { sourceLockPath } from '@volter/supercode-teams/source-lock'; // layer: the board's resting-reader admission reads the host's selected source and release (its source pins); owed: the host hands them in
+import { readRetainedRelease } from '@volter/supercode-teams/release-selection'; // layer: the board's resting-reader admission reads the host's selected source and release (its source pins); owed: the host hands them in
+import { restingContract } from './resting-protocol.mjs';
+import { bindRestingReader, restingReaderBound } from './resting-state.mjs';
+
+const MODE = 'backlog-bounded-pause-v1';
+
+function selectedReader(selected, env) {
+  if (!selected || typeof selected.entry !== 'string' || !isAbsolute(selected.entry)) return null;
+  const entry = realpathSync(selected.entry);
+  if (!selected.candidate === !selected.release) return null;
+  if (selected.candidate) {
+    const source = readSourceCandidate(realpathSync(selected.candidate), sourceLockPath(env));
+    if (entry !== realpathSync(join(source.value.lock.root, 'sdk/orchestrator/bin/orchestrator.mjs')) ||
+      realpathSync(selected.native) !== realpathSync(source.program)) return null;
+  } else {
+    const release = readRetainedRelease(selected.release);
+    if (entry !== realpathSync(release.board) || realpathSync(selected.native) !== realpathSync(release.program)) return null;
+  }
+  return restingContract(entry, { optional: true });
+}
+
+function recordedReader(status, env) {
+  const prior = status.restingReaderProtocol === 1 && status.lastRestingReader;
+  if (prior?.version !== 1 || !prior.selected || !prior.resting) return null;
+  const actual = selectedReader(prior.selected, env);
+  return actual && nativeJsonEqual(actual, prior.resting) ? prior.selected : null;
+}
+
+export async function admitLocalRestingReader(root, env = process.env) {
+  if (restingReaderBound()) return;
+  let compatible = false;
+  try {
+    root = realpathSync(root);
+    const answer = await askBoardOwner(root, { argv: ['handover', '--action', 'status'] }, { waitMs: 0, timeoutMs: 8000 });
+    let status = null;
+    if (answer.code === 0 && !answer.unanswered) status = JSON.parse(Array.isArray(answer.stdout) ? answer.stdout.join('') : answer.stdout);
+    else if (answer.down && existsSync(join(root, 'board-generation.json'))) {
+      const record = JSON.parse(readFileSync(join(root, 'board-generation.json'), 'utf8'));
+      if (record?.version === 1 && record.restingReaderProtocol === 1) status = { restingReaderProtocol: 1, lastRestingReader: record.lastRestingReader ?? null };
+    }
+    const selected = status?.selected ?? (status ? recordedReader(status, env) : null);
+    const reader = selected ? selectedReader(selected, env) : null;
+    compatible = reader?.protocol.readModes.includes(MODE) === true && reader.codec?.formatFeatures?.includes('acceptance-layout-v1') === true;
+  } catch { compatible = false; }
+  bindRestingReader(compatible);
+}

package/board/lock-holder.mjs

@@ -1,3 +1,4 @@
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 // The board owner's one-per-home lock, held by a process of its own. A POSIX record lock belongs to the process that took
 // it, and any open and close of the same file in that process drops it; no reader in the owner can reach a lock another
 // process holds. The holder takes SQLite's exclusive lock on `board.lock` (the default VFS), says so, and exits when its
@@ -11,7 +12,10 @@ let lock;
 try {
   lock = new DatabaseSync(process.argv[1]);
   lock.exec('PRAGMA busy_timeout = 0; PRAGMA locking_mode = EXCLUSIVE; BEGIN EXCLUSIVE');
-} catch (error) { process.stdout.write('held ' + String(error.message).replace(/\\n/g, ' ') + '\\n'); process.exit(1); }
+} catch (error) {
+  // SQLITE_BUSY (5) is another process holding the lock; any other failure (an unopenable path) is not an owner.
+  process.stdout.write(((error.errcode & 0xff) === 5 ? 'held ' : 'failed ') + String(error.message).replace(/\\n/g, ' ') + '\\n'); process.exit(1);
+}
 process.stdout.write('ready\\n');
 process.stdin.on('data', () => {});
 process.stdin.on('end', () => process.exit(0));
@@ -19,16 +23,18 @@ process.stdin.on('error', () => process.exit(0));
 `;
 
 /**
- * Hold `path` for this process's life. Resolves once the holder has the lock; rejects with its reason when another
- * owner holds it. `onLost` is told if the holder ends while this process still runs (the lock is then gone).
- * Returns `release()`, which ends the holder.
+ * Hold `path` for this process's life. Resolves once the holder has the lock; rejects with its reason otherwise, the
+ * rejection's `code` 'EHELD' only when another owner holds it. `onLost` is told if the holder ends while this process still runs (the lock is then gone).
+ * Returns idempotent `release()`, which joins the holder's exit.
  */
 export function holdLock(path, { onLost = () => {} } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, ['--no-warnings', '-e', HOLDER, path], { stdio: ['pipe', 'pipe', 'ignore'] });
+    const exited = new Promise(done => child.once('exit', done));
     let said = '';
     let ready = false;
     let released = false;
+    let releasing;
     child.stdout.setEncoding('utf8');
     child.stdout.on('data', (chunk) => {
       said += chunk;
@@ -37,8 +43,14 @@ export function holdLock(path, { onLost = () => {} } = {}) {
       if (line === 'ready') {
         ready = true;
         child.unref(); child.stdout.unref?.(); child.stdin.unref?.();
-        resolve({ release: () => { released = true; child.stdin.end(); } });
-      } else reject(new Error(line.replace(/^held /, '')));
+        resolve({ release: () => releasing ??= (async () => {
+          released = true;
+          // The lock is normally unreferenced. Keep its exit alive while its owner joins retirement.
+          child.ref(); child.stdin.ref?.();
+          stopWorkChild(child, () => child.stdin.end());
+          await exited;
+        })() });
+      } else reject(line.startsWith('held ') ? Object.assign(new Error(line.slice(5)), { code: 'EHELD' }) : new Error(line.replace(/^failed /, '')));
     });
     child.on('error', (error) => { if (!ready) reject(error); });
     child.on('exit', (code, signal) => {

package/board/machine-fleet.mjs

@@ -1,3 +1,5 @@
+import { measureSyncChild } from '@volter/supercode-harness-sdk/work-ledger';
+const execFileSync = (...args) => measureSyncChild(() => workLedgerNativeExecFileSync(...args));
 // The fleet as each machine the board works on keeps it: its panes, the harness session beneath each live pane's
 // process, and what a board launch needs of it (`capabilities`: its board process guard's harnesses, and whether it has
 // the keyed launch door). Each machine pushes this as its record (order 3 PR 3, @volter/teams machine-records): this
@@ -7,7 +9,7 @@
 // A machine whose record is current is `online`. One whose record is out of date (its stream closed, its panes or the
 // sessions under them not read) or was never read is `unknown` (its runs are kept, as an unread machine's always were), unless its record says it was unlinked from the
 // team: then it is offline. This machine's own record not being given is no reading at all.
-import { execFileSync } from 'node:child_process';
+import { execFileSync as workLedgerNativeExecFileSync } from 'node:child_process';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { machineCall, machineRecordStream } from './doors.mjs';
 import { RecordView } from './record-view.mjs';
@@ -19,9 +21,12 @@ const recordView = new RecordView(machineRecordStream);
 const paneFacts = (held) => {
   const record = held?.record;
   if (!record?.panes) return '';
-  const under = new Map((record.panes.activities ?? []).map(({ pid, activity }) => [pid, activity]));
+  const under = new Map((record.panes.activities ?? []).map((row) => [row.pid, row]));
   return JSON.stringify([
-    (record.panes.panes ?? []).map((pane) => [pane.pane, Boolean(pane.dead), under.get(pane.pid)?.session_id ?? null, under.get(pane.pid)?.presence === 'running']).sort(),
+    (record.panes.panes ?? []).map((pane) => {
+      const row = under.get(pane.pid);
+      return [pane.pane, Boolean(pane.dead), row?.activity?.harness ?? null, row?.activity?.session_id ?? null, row?.locator?.storage ?? null, row?.activity?.presence === 'running'];
+    }).sort(),
     (record.panes.ended ?? []).map((exit) => exit.pane).sort(),
   ]);
 };
@@ -45,23 +50,46 @@ export function onPanesChanged(listener) { paneListeners.add(listener); return (
 /** The admitted, committed records, including native turn/health changes which need not change a pane. */
 export function onRecordsChanged(listener) { recordListeners.add(listener); return () => recordListeners.delete(listener); }
 export async function readFleetRecords() { return recordView.read(DEADLINE_MS); }
+/**
+ * One machine's panes as its held record has them at this moment, with no door call and no wait: its pane rows (as
+ * panes.list gives them: pane, dead, pid, cwd, activeCommand) and the harness session under each live pane
+ * (`activities`, by pid, with its locator). Null when that record is not current (the record stream not open and
+ * caught up, the machine's own stream out of date, its panes or the sessions under them not read): the caller then
+ * asks the machine's door, as it did before the record was read here.
+ */
+export function heldPanes(machine) {
+  if (!fleetRecordsCurrent()) return null;
+  const held = recordView.records?.[machine];
+  if (notCurrent(held)) return null;
+  const panes = held.record.panes.panes ?? [];
+  // a record from a daemon that does not name each pane's foreground program (an older one) is no reading of what a
+  // closing pane runs: its door is asked, as before
+  if (panes.some((pane) => !Object.hasOwn(pane, 'activeCommand'))) return null;
+  return { panes, activities: held.record.panes.activities ?? [] };
+}
 export function fleetRecordsCurrent() { return Boolean(recordView.ready && recordView.stream && Date.now() - recordView.heardAt <= 45_000); }
 const DEADLINE_MS = 10_000;
 const within = (promise, ms) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error(`no answer within ${ms} ms`), { code: 'timeout' })), ms).unref?.())]);
 // One machine's reading, from its held record: its panes, what a board launch needs of it, and the session under each
 // live pane.
-function readOne(name, held) {
-  if (!held) return { machine: name, error: 'this machine follows no record of it (not linked to the team, or not yet read)', code: 'unavailable' };
-  if (held.stream === 'unlinked') return { machine: name, error: held.why ?? 'unlinked from the team', code: 'machine_offline' };
-  if (!held.record) return { machine: name, error: `its record was never read: ${held.why ?? 'no reason given'}`, code: 'unavailable' };
-  if (held.stream !== 'open' && held.stream !== 'self') return { machine: name, error: `its record may be out of date: its stream is ${held.stream} since ${held.since ? new Date(held.since).toISOString() : 'unknown'} (${held.why ?? 'no reason given'})`, code: 'stale' };
+/** Why a machine's held record is no current reading of its panes (`{ error, code }`), or null when it is one. */
+function notCurrent(held) {
+  if (!held) return { error: 'this machine follows no record of it (not linked to the team, or not yet read)', code: 'unavailable' };
+  if (held.stream === 'unlinked') return { error: held.why ?? 'unlinked from the team', code: 'machine_offline' };
+  if (!held.record) return { error: `its record was never read: ${held.why ?? 'no reason given'}`, code: 'unavailable' };
+  if (held.stream !== 'open' && held.stream !== 'self') return { error: `its record may be out of date: its stream is ${held.stream} since ${held.since ? new Date(held.since).toISOString() : 'unknown'} (${held.why ?? 'no reason given'})`, code: 'stale' };
   const record = held.record;
   // panes not read, or read without the sessions under them (or while the session index is lost), are no reading of
   // what runs there: the machine is unknown, never one whose panes or sessions are absent (refused is not absent). A
   // part the index could not read (`sessions_index_parts`) is not: it keeps the rows its last read committed, and the
   // sessions under the panes are read by their processes, not from it; the record names it.
-  const notCurrent = record.unread?.panes ?? record.unread?.sessions_index ?? record.unread?.claude_registry_watch ?? record.unread?.pane_exits_watch ?? record.panes?.activities_omitted ?? record.panes?.sessions_unread ?? (record.panes ? null : 'its record holds no pane list');
-  if (notCurrent) return { machine: name, error: `its panes are not current: ${notCurrent}`, code: 'stale' };
+  const unread = record.unread?.panes ?? record.unread?.sessions_index ?? record.unread?.claude_registry_watch ?? record.unread?.pane_exits_watch ?? record.panes?.activities_omitted ?? record.panes?.sessions_unread ?? (record.panes ? null : 'its record holds no pane list');
+  return unread ? { error: `its panes are not current: ${unread}`, code: 'stale' } : null;
+}
+function readOne(name, held) {
+  const why = notCurrent(held);
+  if (why) return { machine: name, ...why };
+  const record = held.record;
   const panes = record.panes?.panes ?? [];
   const capabilities = record.capabilities ?? { guard: [], launches: false };
   // Since when its record has been current without a break: this machine's own since it last woke (localWake), another's
@@ -80,6 +108,27 @@ export function localWake() {
   } catch { return null; }
 }
 
+/** The parts of a record its session rows and their activity come from: one not read leaves no row of it held. */
+const SESSION_SOURCES = ['sessions', 'sessions_index', 'sessions_index_parts', 'claude_registry_watch', 'sessions_activity'];
+/**
+ * The sessions a machine's held record lists with their activity, grouped by address without losing distinct stores,
+ * as a discovery row of each (`locator`,
+ * `cwd`, `updated_at_ms`, `activity`: the machine's follow of its live sessions), where that record is current with
+ * every source of its session list read; none otherwise. A session the record lists without an activity (one past the
+ * sessions the machine follows, or a follower not granted it) is not held.
+ */
+function heldSessions(name, held, into, transcripts) {
+  if (!held?.record || (held.stream !== 'open' && held.stream !== 'self') || !Array.isArray(held.record.sessions)) return;
+  if (SESSION_SOURCES.some((source) => held.record.unread?.[source])) return;
+  for (const row of held.record.sessions) {
+    if (!row?.locator || typeof row.address !== 'string' || !row.address.startsWith(`sc:${name}:`)) continue;
+    // `transcripts`: every listed session's transcript locator, activity or not
+    transcripts.set(row.address, [...(transcripts.get(row.address) ?? []), { locator: row.locator }]);
+    if (!row.activity) continue;
+    into.set(row.address, [...(into.get(row.address) ?? []), { locator: row.locator, cwd: row.cwd ?? null, updated_at_ms: row.last_message_at_ms ?? null, activity: row.activity }]);
+  }
+}
+
 /** One reading of `machines` (normalized names) and this machine, `local`: every record, from this machine's daemon. */
 export async function readMachineFleet(machines, local) {
   const names = [...new Set([local, ...machines])];
@@ -96,11 +145,16 @@ export async function readMachineFleet(machines, local) {
   }
   catch (error) { heldError = String(error?.message ?? error).slice(0, 300); }
   const rows = names.map((name) => heldError ? { machine: name, error: `this machine's daemon did not give the records it holds: ${heldError}`, code: 'unavailable' } : readOne(name, held[name]));
+  // `held`: each machine's live session rows with their activity, grouped by address (heldSessions);
+  // `transcripts`: each listed transcript locator, grouped by address, retaining distinct native stores
+  const heldRows = new Map(), transcripts = new Map();
+  if (!heldError) for (const name of names) heldSessions(name, held[name], heldRows, transcripts);
   noteStep(`fleet reading (${names.length} machine${names.length === 1 ? '' : 's'}, held records)`, performance.now() - started);
   // `panes`: each answering machine's live pane ids, whether or not a session was read in them
+  // `alive`: address-only presence for mail routing; retained conversations use the locators in `sessions`
   // `ended`: the panes each machine saw end (its tmux's exit log, or a pane its host keeps dead), with how each ended
   // `linkedSince`: each online machine's unbroken current reading began (epoch ms; this machine's last wake; null unknown)
-  const online = new Set(), offline = new Set(), unknown = new Set(), errors = new Map(), alive = new Set(), native = new Map(), sessions = [], capabilities = new Map(), panes = new Map(), ended = new Map(), linkedSince = new Map();
+  const online = new Set(), offline = new Set(), unknown = new Set(), errors = new Map(), alive = new Set(), sessions = [], capabilities = new Map(), panes = new Map(), ended = new Map(), linkedSince = new Map();
   let localError = null, localCode = null;
   for (const row of rows) {
     if (row.error) {
@@ -124,7 +178,6 @@ export async function readMachineFleet(machines, local) {
       const pane = live.find((item) => item.pid === pid);
       if (!pane || !activity?.session_id || !activity.harness) continue;
       const address = `sc:${row.machine}:${activity.harness}:${activity.session_id}`, running = activity.presence === 'running';
-      native.set(address, { alive: running ? true : null, states: [running ? true : null] });
       if (running) alive.add(address);
       sessions.push({ address, machine: row.machine, harness: activity.harness, session_id: activity.session_id, locator: locator ?? null, pane: pane.pane, name: pane.title ?? pane.label ?? null,
         starter_session: pane.starter_session ?? null,
@@ -142,5 +195,5 @@ export async function readMachineFleet(machines, local) {
   // why, as any other is: the machines that answered are current beside it. Only no record of this machine at all
   // leaves the whole reading untaken.
   const ok = online.has(local) || (!heldError && localCode === 'stale');
-  return { ok, presenceKnown: ok, online, offline, unknown, errors, alive, native, sessions, capabilities, panes, ended, linkedSince, error: ok ? null : `machine ${local}'s door did not answer: ${localError ?? 'no row'}` };
+  return { ok, presenceKnown: ok, online, offline, unknown, errors, alive, sessions, held: heldRows, transcripts, capabilities, panes, ended, linkedSince, error: ok ? null : `machine ${local}'s door did not answer: ${localError ?? 'no row'}` };
 }

package/board/owner-door-worker.mjs

@@ -1,3 +1,4 @@
+import { registerWorkService } from '@volter/supercode-harness-sdk/work-ledger';
 // The thread that serves the board owner's socket (owner-door.mjs). A listing is answered here, read on a connection of
 // its own; every other request is handed to the owner's thread and its answer written back.
 import { parentPort, workerData } from 'node:worker_threads';
@@ -7,19 +8,18 @@ import { boardOwnerSocket } from '@volter/teams/board-owner';
 import { parse } from './args.mjs';
 import { answerOne } from './cli.mjs';
 import { knowLocalMachine } from './dispatch.mjs';
-import { holdOwnerHealth } from './owner-health.mjs';
 import { ownHome } from './owner-files.mjs';
 import { writeOwnerAnswer } from './reply.mjs';
 import { holdWorkflow } from './workflow.mjs';
 
 const { root, machine, readListings = true } = workerData;
+registerWorkService({role:'board-door-worker',scope:{kind:'install',id:root},workerPurpose:'board-door'});
 const waiting = new Map(); // request id → its answer's resolve
 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);
+  if (frame.type === 'workflow') holdWorkflow(frame.root, frame.entry);
   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);

package/board/owner-door.mjs

@@ -1,11 +1,11 @@
+import { observeWorker, stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 // The board owner's socket, served on a thread of its own (owner-door-worker.mjs), so a caller is heard while the
 // owner's loop is held by a round. A listing (`list`, `ls`) is read on that thread, each on a connection of its own in
 // one SQLite read transaction (store.mjs openBoard, readOnly): WAL serves it beside the owner's writes, and neither
 // waits on the other. Every other request, and a listing that thread leaves to the owner (listing.mjs byOwner), comes
-// here and is answered by the board's one writer exactly as before. The thread holds what a listing says of the owner:
-// its dispatcher's health (owner-health.mjs) and the workflow it read (workflow.mjs), sent on each change.
+// here and is answered by the board's one writer exactly as before. The thread holds the workflow it read
+// (workflow.mjs), sent on each change.
 import { Worker } from 'node:worker_threads';
-import { watchOwnerHealth } from './owner-health.mjs';
 import { watchWorkflows } from './workflow.mjs';
 
 const failed = (error) => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` });
@@ -14,17 +14,24 @@ const failed = (error) => ({ code: 1, stdout: '', stderr: `supercode workflow: $
  * Serve the owner's socket for the home at `root` (the caller holds its lock and has removed any old socket): resolves
  * once the socket is bound. `answer(line)` answers a request here; `machine` is this machine's name as the owner learned
  * 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.
+ * start it again. Answers an idempotent close that joins the door worker's exit.
  */
 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 } });
+  observeWorker(worker,'worker');
   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 = [
-    watchOwnerHealth(({ boards, round }) => send({ type: 'health', boards, round })),
     watchWorkflows((at, { workflow, params, profiles }) => send({ type: 'workflow', root: at, entry: { workflow, params, profiles } })),
   ];
-  const close = () => { closing = true; for (const stop of stops) stop(); worker.terminate().catch(() => { /* ended */ }); };
+  let closingPromise;
+  const close = () => closingPromise ??= (async () => {
+    closing = true;
+    const errors = [];
+    for (const stop of stops) { try { stop(); } catch (error) { errors.push(error); } }
+    try { await stopWorkChild(worker, () => worker.terminate(), { exitCode: 1 }); } catch (error) { errors.push(error); }
+    if (errors.length) throw new AggregateError(errors, 'board door shutdown failed', { cause: errors[0] });
+  })();
   worker.on('message', (frame) => {
     if (frame?.type !== 'request') return;
     // one answer per request, whatever it did: a request that fails is a failed answer, never the owner's end
@@ -34,7 +41,10 @@ export async function openOwnerDoor(root, { machine, answer, log, readListings =
   await new Promise((resolve, reject) => {
     const ended = (error) => {
       if (closing) return;
-      if (!open) { close(); reject(error); return; }
+      if (!open) {
+        close().then(() => reject(error), cleanup => reject(new AggregateError([error, cleanup], 'board door startup and cleanup failed', { cause: error })));
+        return;
+      }
       log(`board door: ${error.message}; this home has no door now; stopping, for the keeper to start the owner again`);
       process.exit(1);
     };

package/board/owner-health.mjs

@@ -1,36 +1,33 @@
 // What the board owner knows of its own dispatcher, held in its memory: each board's dispatching switch (loaded once
 // when the owner starts, then set by the owner's own switch writes) and its last completed round (set as each round
-// completes). A verb's notice is formatted from this; nothing is read per call. Outside the owner nothing is held.
+// completes). Explicit diagnostics read this; nothing is read per ordinary call. Outside the owner nothing is held.
 const switches = new Map(); // board slug → { on, at, by, reason }
 let round = null; // { at, errors }
 let holding = false;
-// the owner's read door holds the same (owner-door.mjs), told of each change
-const watchers = new Set();
-const told = () => { for (const watcher of watchers) watcher({ boards: [...switches], round }); };
-/** `watcher` is told what the owner holds now and after each change; answers its stop. */
-export function watchOwnerHealth(watcher) { watchers.add(watcher); watcher({ boards: [...switches], round }); return () => watchers.delete(watcher); }
-
 /** The owner starts holding: each board's switch as stored, and the last round its predecessor recorded. */
 export function holdOwnerHealth(boards, lastRound) {
   holding = true;
   for (const [slug, state] of boards) switches.set(slug, state);
   round = lastRound;
-  told();
 }
 /** The owner wrote a board's switch. */
-export function holdSwitch(slug, state) { if (holding) { switches.set(slug, state); told(); } }
+export function holdSwitch(slug, state) { if (holding) switches.set(slug, state); }
 /** The owner completed a round. */
-export function holdRound(at, errors) { if (holding) { round = { at, errors }; told(); } }
+export function holdRound(at, errors) { if (holding) round = { at, errors }; }
 
-/** The notice for a verb on `slug`: dispatching off (a state), or a stalled round and its standing errors (failures). */
-export function dispatcherNotice(slug) {
+/** Board diagnostics from held dispatching state and the last completed round, separate from a command's outcome. */
+export function dispatcherDiagnostics(slug) {
   if (!holding) return [];
   const state = switches.get(slug);
   if (!state) return [];
-  if (!state.on) return [`board: dispatching is off on ${slug}${state.at ? ` since ${String(state.at).slice(0, 16)}Z` : ''}${state.by ? ` by ${state.by}` : ''}${state.reason ? ` (${state.reason})` : ''}; no round runs until \`supercode workflow dispatching on\``];
+  if (!state.on) return [{ kind: 'dispatching_off', severity: 'warning',
+    title: `dispatching is off on ${slug}${state.at ? ` since ${state.at}` : ''}${state.by ? ` by ${state.by}` : ''}${state.reason ? ` (${state.reason})` : ''}`,
+    data: state, actions: ['supercode workflow dispatching on'] }];
   if (!round) return [];
   return [
-    ...(Date.now() - Date.parse(round.at) > 300_000 ? [`board: error: the dispatcher has completed no round since ${String(round.at).slice(0, 16)}Z; nothing starts, moves or is supervised`] : []),
-    ...(round.errors ?? []).map((error) => `board: error: ${error}`),
+    ...(Date.now() - Date.parse(round.at) > 300_000 ? [{ kind: 'dispatcher_stalled', severity: 'error',
+      title: `the dispatcher has completed no round since ${round.at}`, data: { at: round.at }, actions: [] }] : []),
+    ...(round.errors ?? []).map((error) => ({ kind: 'dispatcher_round_error', severity: 'error',
+      title: `dispatcher round at ${round.at}: ${error}`, data: { at: round.at, error }, actions: [] })),
   ];
 }

package/board/owner-interface.mjs

@@ -0,0 +1,6 @@
+// The board package's interface for the board owner's host (generation-owner.mjs, docs/adr/0250-layered-packages.md):
+// the workflows a dispatcher generation reports, held by the owner for its door; this machine's name as the
+// dispatcher knows it; and the command line's parse. The same bindings their modules export; nothing of its own.
+export { holdWorkflow } from './workflow.mjs';
+export { knowLocalMachine, localMachine } from './dispatch.mjs';
+export { parse } from './args.mjs';

package/board/publication-reader.mjs

@@ -0,0 +1,50 @@
+// Retained publications are already serialized by the admitted writer. Observing them must not open a card
+// writer, migrate its layout, import documents or choose a codec interpretation in the follower process.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { backingOf, backingPaths } from './store.mjs';
+
+export function openPublicationReader(root, slug) {
+  const backing = backingOf(root, slug);
+  if (!backing) throw new Error(`no board ${slug} in ${root}`);
+  const paths = backingPaths(root, slug);
+  let db;
+  try {
+    if (backing === 'files') {
+      // The files writer replaces _board.json last. All three publication tables belong to this one atomic
+      // file, so their watermark and heads form one committed view without reading any card files.
+      const state = JSON.parse(readFileSync(join(paths.files, '_board.json'), 'utf8'));
+      if (state.format !== 'supercode-board-files' || state.format_version !== 1)
+        throw new Error(`board ${slug} has an unsupported files publication format`);
+      db = new DatabaseSync(':memory:');
+      const tables = {
+        supercode_publication_log: ['id', 'pruned_through'],
+        supercode_publications: ['sequence', 'id', 'kind', 'snapshot'],
+        supercode_publication_heads: ['resource_id', 'sequence'],
+      };
+      db.exec(`CREATE TABLE supercode_publication_log (id TEXT, pruned_through INTEGER);
+        CREATE TABLE supercode_publications (sequence INTEGER PRIMARY KEY, id TEXT, kind TEXT, snapshot TEXT);
+        CREATE TABLE supercode_publication_heads (resource_id TEXT PRIMARY KEY, sequence INTEGER);`);
+      for (const [name, columns] of Object.entries(tables)) {
+        const rows = state.tables?.[name];
+        if (!Array.isArray(rows)) throw new Error(`board ${slug} has no retained ${name}`);
+        const insert = db.prepare(`INSERT INTO ${name} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')})`);
+        for (const row of rows) insert.run(...columns.map(column => row[column]));
+      }
+    } else {
+      const path = backing === 'ztrack' ? `${paths.ztrack}.board.db` : paths.sqlite;
+      db = new DatabaseSync(path, { readOnly: true });
+      db.exec('PRAGMA busy_timeout=8000');
+    }
+    return {
+      db,
+      tx(work) {
+        db.exec('BEGIN');
+        try { return work(db); }
+        finally { db.exec('ROLLBACK'); }
+      },
+      close: () => db.close(),
+    };
+  } catch (error) { db?.close(); throw error; }
+}