@volter/supercode-orchestrator 0.5.226 → 0.5.227

package/board/fleet-listeners.mjs

@@ -1,5 +1,6 @@
 // Fleet facts are mail obligations, independent of card transitions and dispatch ticks. Intent comes only from the
 // canonical workflow IR. The sender supplies observations from its admitted sources; this router grants nothing.
+import { GENERATION_STOPPED } from './generation.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { chmodSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -213,7 +214,8 @@ export class FleetListenerRouter {
     }
   }
 
-  wake() { if (!this.closed) void this.flush().catch(error => this.log(`fleet listener filing: ${String(error.message).slice(0, 300)}`)); }
+  // A flush its stopping board generation refused never ran (GENERATION_STOPPED, generation.mjs): said as that.
+  wake() { if (!this.closed) void this.flush().catch(error => this.log(error?.code === GENERATION_STOPPED ? `fleet listener filing not run: ${error.message}` : `fleet listener filing: ${String(error.message).slice(0, 300)}`)); }
 
   /** A lost filing answer leaves the obligation pending. Retrying its stable id goes through the mailbox's own
    *  idempotent filing. This receipt proves filing only; native turn delivery remains the mailbox's responsibility. */

package/board/fleet-observer.mjs

@@ -48,8 +48,9 @@ export function observeRoleFleet(root, router, records, log = () => {}, { waitin
     }
     if (!waiting) continue;
     // The existing pane activity grant is still required (operator plus whole-machine view on a peer). A lost index,
-    // unread activity or absent record never clears a wait. Waiting on a live native session is not inferred from idle.
-    if (record.unread?.panes || record.unread?.sessions_index || record.unread?.sessions_index_parts
+    // unread activity or absent record never clears a wait (a part the index could not read is not a lost index: it
+    // keeps its rows, machine-fleet.mjs). Waiting on a live native session is not inferred from idle.
+    if (record.unread?.panes || record.unread?.sessions_index
       || record.unread?.sessions_activity || record.unread?.claude_registry_watch || record.panes?.activities_omitted || record.panes?.sessions_unread) continue;
     const grouped = new Map();
     for (const { pid, activity } of record.panes?.activities ?? []) {

package/board/generation-owner.mjs

@@ -19,6 +19,11 @@ 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` });
+// The card verbs that only read the board's store, and how long one waits on the serving generation: the bound this
+// owner gives a generation's own readback and drain. A generation answers `show` in well under a second; one that has
+// not answered in 8 s is not running, and its caller is told so instead of being held.
+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) {
   root = boardHome(root);
@@ -30,7 +35,7 @@ export async function serveBoardOwner(root, args) {
   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 });
+      selected: child?.selected ?? null, generation: child?.id ?? null, previous: previous && !previous.ended ? previous.process.pid : null, at_ms: Date.now() }) + '\n', { mode: 0o600 });
     renameSync(temporary, recordPath);
   };
   const changed = () => { for (const done of waiting) done(); waiting.clear(); };
@@ -52,7 +57,8 @@ 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, health: null, workflows: new Map(),
+      heard: Date.now(), silenceSaid: false };
     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'); };
@@ -60,18 +66,24 @@ export async function serveBoardOwner(root, args) {
     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;
+      // Preparation and routing are capped at 90 s overall, progress included. The first round ('serving') runs routed,
+      // answering card verbs, and is a full tick that waits on other machines' doors: on the MacBook, first rounds took
+      // 49.7 s, 62.8 s and over 65 s with one machine answering discovery in 10-15 s, and a 65 s budget for the whole
+      // round rolled back a successor that served (VO-3578, 3e8b6f0eb, 01:59:48Z). Its budget bounds progress instead:
+      // each step the round says re-arms it. The five-minute bound only ends a round that never finishes.
+      const waiter = { done, reject, timer: null }, expires = Date.now() + (event === 'serving' ? 300000 : 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 => {
+    // `late` is the answer given when `timeout` passes first: unknown, unless the caller says what a late answer means
+    generation.ask = (line, timeout = null, late = unknown) => 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);
+      if (timeout) timer = setTimeout(() => finish(late()), timeout);
       generation.calls.set(id, finish);
       try { tell({ type: 'request', id, line }); }
       catch { generation.calls.delete(id); done(unknown()); }
@@ -106,6 +118,7 @@ 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 === 'startup-step') {
         generation.startupStep = frame.step;
@@ -199,9 +212,11 @@ export async function serveBoardOwner(root, args) {
     const candidate = start(selected);
     try {
       const proof = await candidate.wait('prepared'), held = active.events.get('prepared');
-      // Both generations name their format (storage-contract.mjs): the formats are compared. A generation from before
-      // `format` names only its storage modules' source, which is then compared.
-      const same = proof.format && held?.format ? proof.format === held.format : Boolean(proof.storage) && proof.storage === held?.storage;
+      // Both generations name their format (storage-contract.mjs): the formats are compared, and a candidate whose format
+      // differs is admitted only when it names the predecessor's among the formats that read what it writes
+      // (`readableBy`), so the predecessor stays its rollback. A generation from before `format` names only its storage
+      // 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' };
       return status();
@@ -263,7 +278,10 @@ export async function serveBoardOwner(root, args) {
         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);
+      // 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);
       pending = null; record(active);
     } else if (!['prepare', 'activate'].includes(action)) throw new Error('unknown board handover action');
     return status();
@@ -285,7 +303,19 @@ export async function serveBoardOwner(root, args) {
       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);
+    if (stopping) return failed(new Error('the board owner is stopping'));
+    let verb = null;
+    // the generation answers what cannot be read as a verb here
+    try { if (!request?.tool && Array.isArray(request?.argv) && request.argv.every(arg => typeof arg === 'string')) verb = parse(request.argv)._[0]; } catch { /* not a read */ }
+    if (!READS.has(verb)) return routing.ask(line);
+    // A read waits on the serving generation for READ_MS at most. A generation whose process does not run answers
+    // nothing, and every read sent to it would otherwise wait for as long as it stands still; its late answer is dropped.
+    const serving = routing;
+    return serving.ask(line, READ_MS, () => {
+      const quiet = Math.round((Date.now() - serving.heard) / 1000);
+      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;
   const stop = () => {

package/board/generation.mjs

@@ -7,17 +7,30 @@ export const inBoardGeneration = typeof process.send === 'function'
 const nested = new AsyncLocalStorage();
 let admitting = !inBoardGeneration, writing = !inBoardGeneration, running = 0, ended = false;
 let waiters = [], drained = [];
+// Work refused because its generation stopped never ran: callers say it as that, not as a failure of the work (a
+// parked generation's queued round and delivery pass are refused when the transaction's finish stops it).
+export const GENERATION_STOPPED = 'GENERATION_STOPPED';
+const stoppedError = message => Object.assign(new Error(message), { code: GENERATION_STOPPED });
+// Each admitted unit of work by its name and when it was admitted, so a park that waits names what it waits on.
+const admitted = new Map();
+let nextWork = 0;
 
-export async function generationWork(work) {
+export async function generationWork(work, name = 'work') {
   if (!inBoardGeneration) return work();
   while (!admitting && !nested.getStore()?.active) {
-    if (ended) throw new Error('the board generation stopped before this work began');
+    if (ended) throw stoppedError('the board generation stopped before this work began');
     await new Promise((done, reject) => waiters.push({ done, reject }));
   }
   running++;
+  const id = ++nextWork; admitted.set(id, { name, at: Date.now() });
   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(); } }
+  finally { admitted.delete(id); scope.active = false; if (--running === 0) { for (const done of drained.splice(0)) done(); } }
+}
+
+/** The admitted work still running, each named with how long ago it was admitted. */
+export function admittedWork(now = Date.now()) {
+  return [...admitted.values()].map(work => `${work.name} (admitted ${now - work.at} ms before)`);
 }
 
 export function assertGenerationWriter() {
@@ -32,7 +45,7 @@ export function admitGeneration() {
 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'));
+  for (const { reject } of waiters.splice(0)) reject(stoppedError('the board generation is stopping'));
 }
 
 export async function parkGeneration(settle) {

package/board/machine-fleet.mjs

@@ -7,6 +7,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 { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { machineCall, machineRecordStream } from './doors.mjs';
 import { RecordView } from './record-view.mjs';
@@ -56,13 +57,29 @@ function readOne(name, held) {
   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' };
   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)
-  const notCurrent = record.unread?.panes ?? record.unread?.sessions_index ?? record.unread?.sessions_index_parts ?? 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');
+  // 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 panes = record.panes?.panes ?? [];
   const capabilities = record.capabilities ?? { guard: [], launches: false };
-  return { machine: name, panes, activities: record.panes?.activities ?? [], ended: record.panes?.ended ?? [], capabilities: { guard: capabilities.guard ?? [], launches: Boolean(capabilities.launches), launchesRefused: capabilities.launches ? null : 'its record names no keyed launch door' } };
+  // Since when its record has been current without a break: this machine's own since it last woke (localWake), another's
+  // since its stream last opened (the record holder's `since`), unknown (null) where neither was read.
+  const linkedSince = held.stream === 'self' ? localWake() : Number(held.since) > 0 ? Number(held.since) : null;
+  return { machine: name, panes, activities: record.panes?.activities ?? [], ended: record.panes?.ended ?? [], linked_since_ms: linkedSince, capabilities: { guard: capabilities.guard ?? [], launches: Boolean(capabilities.launches), launchesRefused: capabilities.launches ? null : 'its record names no keyed launch door' } };
 }
+/** When this machine last woke from sleep (epoch ms): a sleeping machine runs nothing, so no session on it was watched
+ *  idle while it slept. macOS keeps it as kern.waketime (0 when it has not slept since boot); a machine with no such
+ *  record is 0; null when the record could not be read. */
+export function localWake() {
+  if (process.platform !== 'darwin') return 0;
+  try {
+    const found = /sec = (\d+), usec = (\d+)/.exec(execFileSync('/usr/sbin/sysctl', ['-n', 'kern.waketime'], { encoding: 'utf8', timeout: 2_000 }));
+    return found ? Number(found[1]) * 1000 + Math.floor(Number(found[2]) / 1000) : null;
+  } catch { return null; }
+}
+
 /** 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])];
@@ -82,17 +99,20 @@ export async function readMachineFleet(machines, local) {
   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
   // `ended`: the panes each machine saw end (its tmux's exit log, or a pane its host keeps dead), with how each ended
-  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();
-  let localError = null;
+  // `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();
+  let localError = null, localCode = null;
   for (const row of rows) {
     if (row.error) {
       errors.set(row.machine, row.error);
-      if (row.machine === local) localError = row.error;
-      else if (row.code === 'machine_offline') offline.add(row.machine);
+      if (row.machine === local) { localError = row.error; localCode = row.code; }
+      if (row.machine === local && row.code !== 'stale') continue;
+      if (row.code === 'machine_offline') offline.add(row.machine);
       else unknown.add(row.machine);
       continue;
     }
     online.add(row.machine);
+    linkedSince.set(row.machine, row.linked_since_ms ?? null);
     capabilities.set(row.machine, row.capabilities ?? { guard: [], launches: false });
     const live = (row.panes ?? []).filter((pane) => !pane.dead && pane.pid);
     panes.set(row.machine, new Set((row.panes ?? []).filter((pane) => !pane.dead).map((pane) => pane.pane)));
@@ -117,6 +137,10 @@ export async function readMachineFleet(machines, local) {
         question: activity.evidence?.question ?? null });
     }
   }
-  const ok = online.has(local);
-  return { ok, presenceKnown: ok, online, offline, unknown, errors, alive, native, sessions, capabilities, panes, ended, error: ok ? null : `machine ${local}'s door did not answer: ${localError ?? 'no row'}` };
+  // The reading is taken once this machine's daemon gave the records it holds and one of them is this machine's. This
+  // machine's record held but not current (its panes not read, its stream out of date) is one unknown machine, with
+  // 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'}` };
 }

package/board/notices.mjs

@@ -1,7 +1,15 @@
-/** A notice's text or a mail's subject about a card, with the card's keyed number first (`VO-42 …`; store.mjs boardKey). */
-export const numbered = (key, number, text) => (number ? `${key}-${number} ${text}` : text);
+/** A notice's text or a mail's subject about a card, with the card's readable id first and its keyed number after it
+ *  (`voice-calls (VO-42) …`; store.mjs boardKey), or its keyed number alone where it has no readable id (`VO-42 …`). */
+export const numbered = (key, number, text, readableId = null) => {
+  const ref = number ? `${key}-${number}` : null;
+  return readableId ? `${readableId}${ref ? ` (${ref})` : ''} ${text}` : ref ? `${ref} ${text}` : text;
+};
 /** The number of card `id` in the board's store, or null. */
 export const cardNumber = (db, id) => db.prepare('SELECT number FROM supercode_card_numbers WHERE task_id = ?').get(id)?.number ?? null;
+/** The readable id a notice names card `task` by (a getTask row); null for a subtask, which no person names. */
+export const noticeName = (task) => (task && !task.subtask_of ? task.readable_id ?? null : null);
+/** The readable id a notice names card `id` by (noticeName), read from the board's store. */
+export const cardName = (db, id) => db.prepare('SELECT t.readable_id FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.id = ? AND c.subtask_of IS NULL').get(id)?.readable_id ?? null;
 
 export function identifyNotice(event, text) {
   const time = new Date(Number(event.created_at) * 1000).toISOString();

package/board/published.mjs

@@ -103,6 +103,15 @@ const RETAINED_CHANGES = 1024;
 // every pruned change in one statement held the owner's event loop for 291 s (2026-10-21).
 const PRUNE_BATCH = 16;
 const PRUNE_BYTES = 1024 * 1024;
+// A card's head is its complete snapshot (a `workflow events` reading's snapshot frames are complete); a change a newer
+// one supersedes keeps only the history the connector carries (storedSnapshot): on the MacBook (2026-10-27) changes of
+// busy cards ran to 1.7 MB each (1.1 MB of it comments, 0.6 MB attempts), and 4,951 older changes held 2.5 GB of a
+// 3 GB board, while the 4,153 heads held 43 MB. The older changes stored before are trimmed by the owner in place, this
+// many bytes read per wake (trimPublications); the space is given back by `workflow compact` (reclaimSpace).
+const TRIM_BYTES = 8 * 1024 * 1024;
+const TRIM_STATE = 'publication_trim';
+// Free pages over this many bytes and a quarter of the store are worth giving back.
+const RECLAIM_BYTES = 256 * 1024 * 1024;
 const hash = value => createHash('sha256').update(value).digest('hex');
 const parse = (value,fallback=null) => {try{return JSON.parse(value)??fallback;}catch{return fallback;}};
 const at = value => value == null ? null : new Date(Number(value)*1000).toISOString();
@@ -233,6 +242,32 @@ function fingerprintOf(reads,rows,row,key,options){
 }
 /** A card's snapshot; `key` is its board's key (store.mjs boardKey), with which `ref` names the card as a person does
  *  (`VO-856`, store.mjs cardRef), null for a card with no number. */
+/**
+ * What an older change keeps of a card (a change a newer head supersedes): the card as cardSnapshot read it, its
+ * history cut to what a reader of the board's events carries (the connector's publishableCard): the newest comment (the one a `task.commented` is about),
+ * the latest attempt and the latest one that names its session's agent, and the latest review. `omitted` counts what
+ * was left out, added to what an earlier cut counted, so cutting a stored snapshot again changes nothing. The whole card
+ * stays behind the board's own doors (`workflow show`).
+ */
+export function storedSnapshot(card) {
+  if (!card || card.removed) return card;
+  const comments=Array.isArray(card.comments)?card.comments:[],attempts=Array.isArray(card.attempts)?card.attempts:[],reviews=Array.isArray(card.reviews)?card.reviews:[];
+  const agent=attempts.findLast(attempt=>attempt?.session?.agent);
+  const keptAttempts=attempts.filter((attempt,at)=>at===attempts.length-1||attempt===agent);
+  const prior=card.omitted&&typeof card.omitted==='object'?card.omitted:{};
+  return {...card,comments:comments.slice(-1),attempts:keptAttempts,reviews:reviews.slice(-1),
+    omitted:{...prior,comments:Number(prior.comments??0)+Math.max(0,comments.length-1),attempts:Number(prior.attempts??0)+attempts.length-keptAttempts.length,reviews:Number(prior.reviews??0)+Math.max(0,reviews.length-1)}};
+}
+
+/** Cut the history of the change at `sequence`, which a newer head of its card superseded (storedSnapshot). */
+function supersede(db,sequence){
+  const row=db.prepare('SELECT snapshot FROM supercode_publications WHERE sequence=?').get(sequence);
+  const card=row?parse(row.snapshot,null):null;
+  if(!card||card.removed)return;
+  const text=JSON.stringify(storedSnapshot(card));
+  if(text!==row.snapshot)db.prepare('UPDATE supercode_publications SET snapshot=?,snapshot_bytes=? WHERE sequence=?').run(text,Buffer.byteLength(text),sequence);
+}
+
 export function cardSnapshot(db,row,rows=perCard(db),key=null,options={}) {
   const own=rows.own(row.id)??{},number=rows.number(row.id);
   const comments=rows.comments(row.id).map(comment=>({...comment,created_at:at(comment.created_at)}));
@@ -247,7 +282,8 @@ export function cardSnapshot(db,row,rows=perCard(db),key=null,options={}) {
   });
   const lane=own.stage??row.status;
   const archived=Boolean(own.archived || lane==='archived');
-  return {id:row.id,readable_id:row.readable_id??null,number,ref:key&&number?`${key}-${number}`:null,title:row.title,body:row.body??'',assignee:row.assignee,status:taskStatusOf(lane,row.completed_at),board_status:cardState({...row,stage:lane,paused:own.paused,blocked_by:own.blocked_by},options).status,lane,
+  // a subtask, a row under its card that no person names, is published with no readable id, as the board shows it
+  return {id:row.id,readable_id:own.subtask_of?null:row.readable_id??null,number,ref:key&&number?`${key}-${number}`:null,title:row.title,body:row.body??'',assignee:row.assignee,status:taskStatusOf(lane,row.completed_at),board_status:cardState({...row,stage:lane,paused:own.paused,blocked_by:own.blocked_by},options).status,lane,
     execution:executionOf(runs.find(run=>run.id===row.current_run_id),readingContext(db,row.id,row.current_run_id)),
     priority:row.priority,created_by:row.created_by,created_at:at(row.created_at),started_at:at(row.started_at),completed_at:at(row.completed_at),result:row.result,skills:parse(row.skills,[]),model:row.model_override,provider:row.provider_override,
     tags:parse(own.tags,null)??(row.tenant?[row.tenant]:[]),requested_by_unverified:parse(own.requested_by_unverified),machine:own.machine??null,subtask_of:own.subtask_of??null,archived,archive_reason:archived?rows.archiveReason(row.id):null,
@@ -271,7 +307,7 @@ export function recordCardPublications(db,actor,root,key) {
   const marked=db.prepare('SELECT DISTINCT task_id FROM supercode_publication_dirty').all().map(row=>row.task_id);
   if(!marked.length)return 0;
   db.prepare('INSERT INTO supercode_publication_log(id,pruned_through) SELECT ?,0 WHERE NOT EXISTS (SELECT 1 FROM supercode_publication_log)').run(`log_${randomUUID()}`);
-  const rows=perCard(db),reads=fingerprintReads(db),task=db.prepare('SELECT * FROM tasks WHERE id=?'),head=db.prepare('SELECT resource_id,digest,last_event_id,fingerprint FROM supercode_publication_heads WHERE resource_id=?');
+  const rows=perCard(db),reads=fingerprintReads(db),task=db.prepare('SELECT * FROM tasks WHERE id=?'),head=db.prepare('SELECT resource_id,digest,sequence,last_event_id,fingerprint FROM supercode_publication_heads WHERE resource_id=?');
   const lastEvent=db.prepare('SELECT id,kind FROM task_events WHERE task_id=? ORDER BY id DESC LIMIT 1');
   const insert=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at,snapshot_bytes) VALUES (?,?,?,?,?,?,?)');
   const upsert=db.prepare('INSERT INTO supercode_publication_heads(resource_id,digest,sequence,last_event_id,fingerprint) VALUES (?,?,?,?,?) ON CONFLICT(resource_id) DO UPDATE SET digest=excluded.digest,sequence=excluded.sequence,last_event_id=excluded.last_event_id,fingerprint=excluded.fingerprint');
@@ -290,6 +326,8 @@ export function recordCardPublications(db,actor,root,key) {
       const kind=`task.${previous&&previous.digest!=='removed'?(last?.id!==previous.last_event_id?kinds[last?.kind]??'changed':'changed'):'created'}`;
       const inserted=insert.run(`event_${randomUUID()}`,id,kind,snapshot,actor,Date.now(),Buffer.byteLength(snapshot));
       upsert.run(id,digest,Number(inserted.lastInsertRowid),last?.id??null,`${fingerprint}:${digest}`);changed++;
+      // the head it replaces is an older change now: it keeps only the history its readers carry
+      if(previous&&previous.digest!=='removed')supersede(db,previous.sequence);
     }else if(previous&&previous.digest!=='removed'){
       const snapshot=JSON.stringify({id,removed:true});
       const inserted=insert.run(`event_${randomUUID()}`,id,'task.changed',snapshot,actor,Date.now(),Buffer.byteLength(snapshot));
@@ -300,6 +338,73 @@ export function recordCardPublications(db,actor,root,key) {
   return changed;
 }
 
+/** The trim's progress (`{through, high}`), or null before it began; a read only. */
+function trimState(db) {
+  try { return parse(db.prepare('SELECT value FROM supercode_board_state WHERE key=?').get(TRIM_STATE)?.value,null); } catch { return null; }
+}
+/**
+ * Whether stored rows from before storedSnapshot are still to be trimmed, read without writing: true before the trim
+ * began on a store that holds publications, then until it reached the newest change stored when it began.
+ */
+export function trimDue(db) {
+  const state=trimState(db);
+  if(!state)return Boolean(db.prepare('SELECT 1 FROM supercode_publications LIMIT 1').get());
+  return Number(state.through)<Number(state.high);
+}
+
+/**
+ * Trim the older changes stored complete before, oldest first, at most TRIM_BYTES read per call, in the caller's
+ * transaction. A card's head stays complete and is not touched; each trimmed change keeps its id, kind and sequence, so
+ * a reader reads the same events. Answers the rows trimmed.
+ */
+export function trimPublications(db) {
+  db.exec('CREATE TABLE IF NOT EXISTS supercode_board_state (key TEXT PRIMARY KEY, value TEXT)');
+  // the first trim records the newest change stored then: every row after it was stored trimmed
+  if(!trimState(db))db.prepare('INSERT INTO supercode_board_state(key,value) VALUES (?,?) ON CONFLICT(key) DO NOTHING')
+    .run(TRIM_STATE,JSON.stringify({through:0,high:Number(db.prepare('SELECT MAX(sequence) AS n FROM supercode_publications').get()?.n??0)}));
+  const state=trimState(db);
+  if(!state||Number(state.through)>=Number(state.high))return 0;
+  // a few rows a call: a row ran to 4.5 MB, and each is read whole before the byte bound can count it
+  const rows=db.prepare(`SELECT sequence,snapshot FROM supercode_publications p WHERE sequence>? AND sequence<=? AND ${OLDER} ORDER BY sequence LIMIT 8`).all(Number(state.through),Number(state.high));
+  const update=db.prepare('UPDATE supercode_publications SET snapshot=?,snapshot_bytes=? WHERE sequence=?');
+  let through=Number(state.through),read=0,trimmed=0;
+  for(const row of rows){
+    if(read&&read+row.snapshot.length>TRIM_BYTES)break;
+    read+=row.snapshot.length;through=Number(row.sequence);
+    const card=parse(row.snapshot,null);
+    if(!card||card.removed)continue;
+    const text=JSON.stringify(storedSnapshot(card));
+    if(text===row.snapshot)continue;
+    update.run(text,Buffer.byteLength(text),row.sequence);trimmed++;
+  }
+  if(!rows.length)through=Number(state.high);
+  db.prepare('UPDATE supercode_board_state SET value=? WHERE key=?').run(JSON.stringify({...state,through}),TRIM_STATE);
+  return trimmed;
+}
+
+/** Whether the store holds free pages worth giving back: over RECLAIM_BYTES and a quarter of the store. */
+export function reclaimDue(db) {
+  const size=Number(db.prepare('PRAGMA page_size').get().page_size),pages=Number(db.prepare('PRAGMA page_count').get().page_count),free=Number(db.prepare('PRAGMA freelist_count').get().freelist_count);
+  return free*size>RECLAIM_BYTES&&free*4>pages;
+}
+/** Whether the store gives back free pages a slice at a time (incremental vacuum, set by reclaimSpace's rebuild). */
+export const incrementalStore = (db) => Number(db.prepare('PRAGMA auto_vacuum').get().auto_vacuum)===2;
+/** Give back a slice of the free pages (64 MB) of a store in incremental vacuum, in the owner's transaction. */
+export function reclaimSlice(db) { db.exec('PRAGMA incremental_vacuum(16384)'); }
+
+/**
+ * Give the store's free pages back to the volume, once, by an operator's `workflow compact`: the store is rebuilt
+ * (VACUUM) with incremental vacuum on, so later frees go back a slice at a time on the owner's wakes (reclaimSlice).
+ * The rebuild copies every live page and holds the board's writer while it runs; `vacuum` runs SQL on the store's own
+ * connection outside any transaction (a backing's own method where it wraps writes). Answers the bytes it shrank by.
+ */
+export function reclaimSpace(db,vacuum=(sql)=>db.exec(sql)) {
+  const size=Number(db.prepare('PRAGMA page_size').get().page_size),before=Number(db.prepare('PRAGMA page_count').get().page_count);
+  if(incrementalStore(db))vacuum('PRAGMA incremental_vacuum');
+  else vacuum('PRAGMA auto_vacuum=INCREMENTAL; VACUUM;');
+  return (before-Number(db.prepare('PRAGMA page_count').get().page_count))*size;
+}
+
 // An older change: one no card's head is (the heads' sequence index answers it per change).
 const OLDER='NOT EXISTS (SELECT 1 FROM supercode_publication_heads h WHERE h.sequence=p.sequence)';
 /** Whether retention has work: a prune under way, or an upper bound on the older changes kept (sequences above the floor

package/board/readable-id.mjs

@@ -1,11 +1,33 @@
-// A mutable name for people, separate from the immutable t_* identity and sequential number.
+// A card's name for people (`voice-calls`), separate from its immutable t_* identity and sequential number. It names
+// the card's branch, worktree folder, sessions and agents.
 export function validateReadableId(value) {
   if (typeof value !== 'string' || value.length > 32 || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value)) {
-    throw new Error('readable_id is kebab-case, starts with a letter and has at most 32 characters');
+    throw new Error(`readable_id ${JSON.stringify(value)} is not a few lowercase words joined by hyphens, starting with a letter, of at most 32 characters (voice-calls)`);
   }
   return value;
 }
 
+/** A card's readable id as its creator names it: given and valid, neither a repository's default or publication branch
+ *  name nor shaped like a card number (`vo-42`, which a verb reads as one). */
+export function requireReadableId(requested) {
+  if (requested == null || requested === '') {
+    throw new Error("a card is named by its creator: --readable-id <a few lowercase words naming its outcome, such as voice-calls>; it names the card's branch, worktree, sessions and agents");
+  }
+  const value = validateReadableId(requested);
+  if (['main', 'master', 'publish'].includes(value)) throw new Error(`readable_id ${value} names a repository's default or publication branch; name the card's outcome`);
+  if (/^[a-z][a-z0-9]+-[1-9]\d*$/.test(value)) throw new Error(`readable_id ${value} reads as a card number; name the card's outcome in words`);
+  return value;
+}
+
+/** A card's readable id as its creator or editor names it (requireReadableId), held by no other card on the board, open
+ *  or ended (an ended card's branch and worktree keep its name). */
+export function cardReadableId(db, requested, except = '') {
+  const value = requireReadableId(requested);
+  const holder = db.prepare('SELECT id,status FROM tasks WHERE readable_id=? AND id<>? LIMIT 1').get(value, except);
+  if (holder) throw new Error(`readable_id ${value} belongs to card ${holder.id} (${holder.status}); a card's readable id is unique on its board`);
+  return value;
+}
+
 export function readableIdFromTitle(title) {
   const text = String(title).replace(/^(?:\[[^\]]+\]\s*)+/, '');
   const named = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\s*:/.exec(text)?.[1];
@@ -14,6 +36,7 @@ export function readableIdFromTitle(title) {
   return (words.replace(/^[^a-z]+/, '') || 'card').slice(0, 32).replace(/-+$/, '');
 }
 
+// A row no person named (a card's subtask, or a row a document gave none) is named from its title.
 export function allocateReadableId(db, title, requested = null, except = '') {
   const base = requested == null ? readableIdFromTitle(title) : validateReadableId(requested);
   const occupied = value => db.prepare("SELECT id FROM tasks WHERE readable_id=? AND id<>? AND status NOT IN ('done','cancelled','archived') LIMIT 1").get(value, except);

package/board/runtime-door.mjs

@@ -9,14 +9,14 @@ import { machineCall } from './doors.mjs';
  * daemon registered for its home); to another machine, the board's name as the caller, which that machine takes from
  * this machine's link (machine.mjs #callerOf).
  */
-export async function runtimeDoor(machine, method, params = {}, { timeout = 60_000, as = null } = {}) {
+export async function runtimeDoor(machine, method, params = {}, { timeout = 60_000, as = null, signal = null } = {}) {
   try {
     if (!method.startsWith('harness.v1.')) throw Object.assign(new Error('the runtime door accepts harness.v1 methods'), { code: 'invalid_request' });
     const acting = as && !method.startsWith('harness.v1.sessions.');
     const named = !acting ? params
       : machine ? { ...params, caller: as }
       : { ...params, claim: { pid: process.pid, ppid: process.ppid, session: null, named: as, owner: String(process.pid) } };
-    const result = await machineCall(machine, method, named, { timeoutMs: timeout });
+    const result = await machineCall(machine, method, named, { timeoutMs: timeout, signal });
     return { code: 0, stdout: `${JSON.stringify(result ?? null)}\n`, stderr: '' };
   } catch (error) {
     return { code: 1, stdout: '', stderr: `${JSON.stringify({ code: error?.code ?? 'unavailable', message: String(error?.message ?? error) })}\n` };

package/board/session-work.mjs

@@ -112,7 +112,7 @@ export function delegatedWork(address, edges, sessions) {
 
 /** Idle time belongs to a native idle interval, never to transcript freshness, and only to time the board watched:
  * it starts no earlier than `session.watch_since`, where the board's unbroken reading of the run began (its machine
- * linked again, the board restarted or resumed). Quiet the board could not see is not idleness. */
+ * linked again, or where resumedWatch put it after a stretch unread). Quiet the board could not see is not idleness. */
 export function idleInterval(session, live, observedAt) {
   const nativeSince = Number(live?.turn_since_ms);
   const read = nativeSince > 0 && nativeSince <= observedAt * 1000
@@ -121,6 +121,20 @@ export function idleInterval(session, live, observedAt) {
   return { since, quiet: Math.max(0, observedAt - since) };
 }
 
+/** Where the board's watch of a run resumes after a stretch this process did not read it (the board restarted, or read
+ * nothing of the run for a while). The harness's own idle-since (its native state, read on the session's machine) is a
+ * reading of that stretch, not a guess about it: when the session reads idle with one, the watch resumes from it, but
+ * never before the run began, before its machine's record was last current without a break (`linkedSinceMs`: the
+ * board's own machine's last wake from sleep, null when unknown), or before a bound the board recorded (`watch_since`: its machine linked
+ * again, its card held). With no native idle-since, or its machine's link unknown, it resumes from this reading: quiet
+ * the board could not see is not idleness. Epoch seconds. */
+export function resumedWatch(session, live, run, linkedSinceMs, observedAt) {
+  const nativeSince = Number(live?.turn_since_ms);
+  if (live?.turn !== 'idle' || !(nativeSince > 0) || nativeSince > observedAt * 1000 || linkedSinceMs == null) return observedAt;
+  return Math.min(observedAt, Math.max(Math.floor(nativeSince / 1000), Number(run?.started_at ?? 0),
+    Math.ceil(Number(linkedSinceMs) / 1000), Number(session?.watch_since ?? 0)));
+}
+
 /** A question a run's session shows on its pane (VO-3395), as one line: its words and each option, numbered. */
 export function questionText(question) {
   if (!question) return '';

package/board/storage-contract.mjs

@@ -8,10 +8,34 @@
 //   writer reads (the property sets, a file name, a number's form) alike.
 // - `storage` is the earlier contract, the modules' whole source. An owner from before `format` compares it alone, so a
 //   candidate keeps sending it; an owner that knows `format` compares that when both generations send one.
+// - `format` also digests what the documents' codec (@volter/ztrack) writes for a fixed card set: a codec writes the
+//   documents every reader parses, and a 2.x codec reads a numbered heading (`## VO-154 t_… — title`) as a card whose id
+//   is VO-154, so a codec change is a format change, refused at the handover like any other.
+// - `readableBy` names earlier formats whose generations read what this one writes, so the owner can keep such a
+//   predecessor as the rollback of a format change (generation-owner.mjs). The claim is keyed on the format it was
+//   reviewed for (READABLE_BY): a writer change moves the format, which then names none until its own claim is reviewed.
+//   2bfde37a… (the card-number release) is read by c23c3ca4… (release/0.5.482-fixes through 7510457a3), which passes
+//   over the preamble's kept-numbers line as text and reads every card of its documents (VO-3578 take61: the old code
+//   rebuilt from them names no VO-n card).
+//   2964acd1… (the store drops the numbers its tasks were given before only cards were numbered, a bounded batch a transaction) is read by 2bfde37a…:
+//   only rows of supercode_card_numbers go, the sequence stays, and 2bfde37a numbers no task and gives none back.
+//   04bc6948… (cards named by their readable id, #2452) is read by 2964acd1…: it adds no table, column or document text.
+//   Its new rows are task_events kinds (branch_named, worktree_made) that 2964acd1 stores and reads only by named kinds,
+//   so it ignores them; only its `gc` verb deletes them (an ended card's, past the retention), and the card's recorded
+//   path, while it has one, still names its folder. A branch_name (`voice-calls`) is text it reads as any branch,
+//   making that card's worktree in a folder named for its id; a subtask's snapshot carries the nullable readable_id the
+//   snapshot already had. A worktree 2964acd1 makes records only its path, which ends the claim (workspace.mjs branchClaim).
+//   f5dca0f9… (#2507: a change a newer head supersedes keeps only the history the connector carries) is read by
+//   04bc6948…: it adds no table or column. Its supersede and trim rewrite older supercode_publications rows' snapshot
+//   text to the same JSON card with fewer comments, attempts and reviews and an `omitted` object, which 04bc6948 reads
+//   as any snapshot (workflow events yields it; its connector counts omitted from the lists it holds); a card's head,
+//   which every snapshot frame reads, stays complete. Its supercode_board_state key (publication_trim) is one 04bc6948
+//   never reads. A store `workflow compact` rebuilt is in incremental auto-vacuum, which SQLite opens and writes the
+//   same for any release.
 // `format` is null when a member READS names occurs more than once (the owner then compares `storage`).
 import { createHash } from 'node:crypto';
 import fs, { readFileSync } from 'node:fs';
-import { syncBuiltinESMExports } from 'node:module';
+import { createRequire, syncBuiltinESMExports } from 'node:module';
 import { DatabaseSync } from 'node:sqlite';
 import { layOut } from './store.mjs';
 
@@ -26,6 +50,13 @@ const READS = {
 };
 
 const source = (file) => readFileSync(new URL(file, import.meta.url), 'utf8');
+const require = createRequire(import.meta.url);
+// What the codec writes for two cards, one open and one ended, each given a number as a numbering codec would show it.
+function renders() {
+  const codec = require('@volter/ztrack/board-document');
+  const cards = [{ id: 't_00000000', title: 'format', status: 'todo', body: 'A card.' }, { id: 't_00000001', title: 'ended', status: 'done', body: '' }];
+  return cards.map((card, i) => codec.renderBoardCard({ ...card, number: i + 1, key: 'KB' }, 2));
+}
 // A member's lines in its module: from its first line (`  name(` in a class, `function name(` or `const name =` at the
 // top) to the line that closes it at the same indent, or that line alone when it ends the member. None when absent.
 function without(text, name) {
@@ -72,14 +103,21 @@ function format() {
     const layout = db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name, tbl_name").all()
       .map(({ type, name, tbl_name: table, sql }) => [type, name, table, sql]);
     const modules = MODULES.map((file) => [file, code((READS[file] ?? []).reduce(without, source(file)))]);
-    return createHash('sha256').update(JSON.stringify({ layout, modules })).digest('hex');
+    return createHash('sha256').update(JSON.stringify({ layout, modules, renders: renders() })).digest('hex');
   } finally { db.close(); }
 }
 
+const READABLE_BY = {
+  '2bfde37add33506a56e910c49c9643e91a4f96d36378daeb8cdae3018835a089': ['c23c3ca4bd184cd9c6d9312f4c3fd0ab7f8bc5bde4926f01d32951a641ebde7d'],
+  '2964acd14bca601e85ffaccc160bf058ee327f4aafb9ee5a0d8559fe509632e1': ['2bfde37add33506a56e910c49c9643e91a4f96d36378daeb8cdae3018835a089'],
+  '04bc6948582c8de470a7c5301ede239bcf26730f7a1d725ccde7fb03aecf9ba5': ['2964acd14bca601e85ffaccc160bf058ee327f4aafb9ee5a0d8559fe509632e1'],
+  'f5dca0f9a1337a7f807b8a21c39826bfd5c165bcb6a3d847fb9fb31a9d620afb': ['04bc6948582c8de470a7c5301ede239bcf26730f7a1d725ccde7fb03aecf9ba5'],
+};
+
 export function storageContract() {
   const storage = createHash('sha256');
   for (const file of MODULES) storage.update(file).update(readFileSync(new URL(file, import.meta.url)));
   let formatDigest = null;
   try { formatDigest = format(); } catch (error) { process.stderr.write(`board storage contract: no format digest (${error.message}); the owner compares storage\n`); }
-  return { storage: storage.digest('hex'), format: formatDigest };
+  return { storage: storage.digest('hex'), format: formatDigest, readableBy: (formatDigest && READABLE_BY[formatDigest]) || [] };
 }