@volter/supercode-orchestrator 0.5.228 → 0.5.230

package/board/published.mjs

@@ -6,7 +6,7 @@ import { readFileSync } from 'node:fs';
 // supercode_publication_dirty, whoever writes (this process, Hermes's native writer, a document import). A transaction
 // publishes the marked cards and clears their marks; one that marked nothing reads one row and publishes nothing.
 import { createHash, randomUUID } from 'node:crypto';
-import { executionOf, readingContext } from './session-work.mjs';
+import { executionOf, presenceFresh, readingContext } from './session-work.mjs';
 import { cardState } from './card-state.mjs';
 import { workflowFor } from './workflow.mjs';
 import { cardAgentScopeTransition } from '../agents.mjs';
@@ -40,8 +40,8 @@ CREATE INDEX IF NOT EXISTS supercode_publication_heads_sequence ON supercode_pub
 // is where a prune under way resumes, null when none is (prunePublications).
 export const PUBLICATION_COLUMNS = { supercode_publications: { snapshot_bytes: 'INTEGER' }, supercode_publication_heads: { fingerprint: 'TEXT' }, supercode_publication_log: { prune_from: 'INTEGER' } };
 
-// The snapshot's shape: 1 names the card as a person does (`ref`, VO-856); 5 lists the files attached to it (`attachments`).
-const SNAPSHOT_SHAPE = 5;
+// Snapshot shape: 1 names the card as a person does; 5 adds attachments; 6 adds attributed backlog and bounded pauses.
+const SNAPSHOT_SHAPE = 6;
 const SNAPSHOT_RELEASE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const REVIEW_KIND_LIST = ['review_requested', 'approved', 'review_approved', 'changes_requested', 'escalated'];
 export const AGENT_KIND_LIST = ['agent_declared', 'agent_assignment_ended', 'agent_assignment_reassigned', 'agent_assignment_adopted'];
@@ -115,7 +115,7 @@ 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();
-const kinds = {started:'started',created:'created',completed:'completed',cancelled:'cancelled',reopened:'reopened',blocked:'blocked',unblocked:'unblocked',paused:'paused',resumed:'resumed',assigned:'assigned',linked:'linked',unlinked:'unlinked',commented:'commented',specified:'specified',review_requested:'review_requested',changes_requested:'changes_requested'};
+const kinds = {started:'started',created:'created',completed:'completed',cancelled:'cancelled',reopened:'reopened',blocked:'blocked',unblocked:'unblocked',paused:'paused',pause_extended:'pause_extended',resumed:'resumed',backlogged:'backlogged',planned:'planned',assigned:'assigned',linked:'linked',unlinked:'unlinked',commented:'commented',specified:'specified',review_requested:'review_requested',changes_requested:'changes_requested'};
 
 /**
  * The ontology's Task status (contracts/ontology.md: todo, running, review, done, cancelled) of a card in a board lane.
@@ -229,16 +229,41 @@ const fingerprintReads=db=>({
   // a run's metadata changes in place (its session's observations), so every run's snapshot columns are read whole
   runs:db.prepare('SELECT id,profile,step_key,status,started_at,ended_at,outcome,summary,metadata,error FROM task_runs WHERE task_id=? ORDER BY id'),
 });
+/**
+ * A run as its card's snapshot reads it: its session's presence reading with whether it is current in place of when it
+ * was observed. The dispatcher renews an unchanged reading every minute (dispatch.mjs supervise); the snapshot carries
+ * what the reading says and whether it is current (publishedExecution), never the time it was renewed, so a renewal that
+ * changes neither is no change of the card. On the MacBook (2026-10-30) the renewal alone republished each running card
+ * whole every minute (1.95 MB for t_2a2ef475).
+ */
+function presenceRead(run,now){
+  if(typeof run.metadata!=='string'||!run.metadata.includes('"presence_observation"'))return run;
+  const metadata=parse(run.metadata,null),reading=metadata?.supercode?.presence_observation;
+  if(!reading||typeof reading!=='object')return run;
+  const {observed_at,...said}=reading;
+  return {...run,metadata:JSON.stringify({...metadata,supercode:{...metadata.supercode,presence_observation:{...said,current:presenceFresh(reading,now)}}})};
+}
 /**
  * A card's fingerprint: what its snapshot is built from, read cheaply (no comment text, review or agent event payloads,
  * and no snapshot built), with the snapshot's shape, its board's key and the options it is built with. Equal
- * fingerprints build equal snapshots, but for a run's session observation passing its freshness (executionOf), which a
- * snapshot's readers apply themselves.
+ * fingerprints build equal snapshots, but for a bounded wait (a heartbeat's `until`) passing, which a snapshot's readers
+ * apply themselves.
  */
 function fingerprintOf(reads,rows,row,key,options){
   const task={};for(const [column,value] of Object.entries(row))if(!UNREAD_TASK_COLUMNS.has(column))task[column]=value;
   return hash(JSON.stringify([SNAPSHOT_SHAPE,SNAPSHOT_RELEASE,key,Boolean(options.nativeHolds),task,rows.own(row.id)??null,rows.number(row.id),rows.parents(row.id),rows.children(row.id),
-    reads.facts.get(row.id)??null,reads.scope.get(row.id)??null,reads.runs.all(row.id)]));
+    reads.facts.get(row.id)??null,reads.scope.get(row.id)??null,reads.runs.all(row.id).map(run=>presenceRead(run,options.now))]));
+}
+/**
+ * A card's session reading as its snapshot publishes it: what the board last read of the session (its state, turn,
+ * machine and reason), without the time of that reading or when it stops being current. Those move with every renewal;
+ * the board's own doors (`workflow list`, `workflow show`: listing.mjs) read them live, and no reader of a published
+ * card reads them (the connector's publishableCard, the Workplace's cards, `workflow events`).
+ */
+export function publishedExecution(execution){
+  if(!execution||typeof execution!=='object')return execution;
+  const {observed_at,fresh_until,...said}=execution;
+  return said;
 }
 /** 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. */
@@ -269,6 +294,7 @@ function supersede(db,sequence){
 }
 
 export function cardSnapshot(db,row,rows=perCard(db),key=null,options={}) {
+  const now=options.now??Date.now()/1000;
   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)}));
   const verdicts={review_requested:'requested',approved:'approved',review_approved:'approved',changes_requested:'changes_requested',escalated:'escalated'};
@@ -278,16 +304,16 @@ export function cardSnapshot(db,row,rows=perCard(db),key=null,options={}) {
     const native=parse(run.metadata,{})?.supercode??null;
     const session=native?{machine:native.machine,harness:native.harness,session_id:native.session_id,address:native.address,pane:native.pane,surface:native.surface,state:native.state,closed_at:native.closed_at,detached_at:native.detached_at??null,detached_to:native.detached_to??null,agent:native.agent_id??null,counted:native.counted??null,profile_differences:native.agent_profile_mismatch?.differences??null}:null;
     const metadata=parse(run.metadata,{});delete metadata.supercode;
-    return {id:String(run.id),profile:run.profile,step:run.step_key,status:run.status,started_at:at(run.started_at),ended_at:at(run.ended_at),outcome:run.outcome,error:run.error,execution:executionOf(run),session,handoff:run.summary||Object.keys(metadata).length?{summary:run.summary,metadata}:null};
+    return {id:String(run.id),profile:run.profile,step:run.step_key,status:run.status,started_at:at(run.started_at),ended_at:at(run.ended_at),outcome:run.outcome,error:run.error,execution:publishedExecution(executionOf(run,{now})),session,handoff:run.summary||Object.keys(metadata).length?{summary:run.summary,metadata}:null};
   });
   const lane=own.stage??row.status;
   const archived=Boolean(own.archived || lane==='archived');
   // 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)),
+  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,backlog:own.backlog,blocked_by:own.blocked_by},options).status,lane,
+    execution:publishedExecution(executionOf(runs.find(run=>run.id===row.current_run_id),{...readingContext(db,row.id,row.current_run_id),now})),
     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,
-    blocked_by:parse(own.blocked_by,[]),paused:parse(own.paused),detached:parse(own.detached),every:own.every??null,
+    blocked_by:parse(own.blocked_by,[]),paused:parse(own.paused),backlog:parse(own.backlog),detached:parse(own.detached),every:own.every??null,
     workspace:{kind:row.workspace_kind,path:row.workspace_path,branch:row.branch_name,root:own.workspace_root,anchor:own.workspace_anchor},
     parents:rows.parents(row.id),
     agents:rows.agents(row.id),reviews,children:rows.children(row.id),comments,attempts,
@@ -303,7 +329,9 @@ export function cardSnapshot(db,row,rows=perCard(db),key=null,options={}) {
  * compared again. The marks are cleared with it. Retention is the owner's (prunePublications), never a transaction's.
  */
 export function recordCardPublications(db,actor,root,key) {
-  const options={nativeHolds:Boolean(workflowFor(root,{optional:true})?.workflow.flags?.paused)};
+  // Fingerprint and snapshot must agree at the freshness boundary: caching a current fingerprint beside an expired
+  // snapshot would also skip the next unchanged renewal, leaving the card unknown after its session was read again.
+  const options={now:Date.now()/1000,nativeHolds:Boolean(workflowFor(root,{optional:true})?.workflow.flags?.paused)};
   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()}`);

package/board/queries.mjs

@@ -2,10 +2,30 @@
 import { setImmediate as yieldToOwner } from 'node:timers/promises';
 
 /** One reverse index seek per kind, then one payload read. ORDER BY id over an IN-kind filter can instead choose
- * the task/id index and read unrelated event payloads to reject their kinds. Kinds and columns are code constants. */
-export function latestEvent(db, task, kinds, columns = 'payload') {
-  const seeks = kinds.map(kind => `SELECT (SELECT id FROM task_events WHERE task_id=? AND kind='${kind}' ORDER BY id DESC LIMIT 1) AS id`);
-  return db.prepare(`SELECT ${columns} FROM task_events WHERE id=(SELECT MAX(id) FROM (${seeks.join(' UNION ALL ')}))`).get(...kinds.map(() => task));
+ * the task/id index and read unrelated event payloads to reject their kinds. SQL fragments are code constants. */
+export function latestEventIdSql(task, kinds, predicate = '1') {
+  const seeks = kinds.map(kind => `SELECT (SELECT id FROM task_events WHERE task_id=${task} AND kind='${kind}' AND (${predicate}) ORDER BY id DESC LIMIT 1) AS id`);
+  return `(SELECT MAX(id) FROM (${seeks.join(' UNION ALL ')}))`;
+}
+
+export function latestEvent(db, task, kinds, columns = 'payload', predicate = '1', args = []) {
+  return db.prepare(`SELECT ${columns} FROM task_events WHERE id=${latestEventIdSql('?', kinds, predicate)}`).get(...kinds.flatMap(() => [task, ...args]));
+}
+
+/** The latest dispatch wait for task `t` and card `c`, after its stage entry and latest run. Stage-entry and run event
+ * ids supply ordering when their timestamps and an older wait fall in the same second. Each history read is indexed. */
+export const DISPATCH_WAIT_SQL = `SELECT CASE WHEN json_valid(e.payload) THEN json_object('reason',json_extract(e.payload,'$.reason'),'at',e.created_at) END
+  FROM task_events e WHERE t.current_run_id IS NULL AND COALESCE(c.stage,t.status) NOT IN ('done','archived','cancelled')
+    AND e.id=(SELECT id FROM task_events WHERE task_id=t.id AND kind='respawn_guarded' ORDER BY id DESC LIMIT 1)
+    AND e.created_at>=COALESCE(c.since,0)
+    AND e.id>COALESCE((SELECT id FROM task_events WHERE task_id=t.id AND kind='stage_entered' ORDER BY id DESC LIMIT 1),0)
+    AND e.created_at>=COALESCE((SELECT COALESCE(ended_at,started_at) FROM task_runs WHERE task_id=t.id ORDER BY id DESC LIMIT 1),0)
+    AND e.id>COALESCE((SELECT id FROM task_events WHERE run_id=(SELECT id FROM task_runs WHERE task_id=t.id ORDER BY id DESC LIMIT 1) ORDER BY id LIMIT 1),0)`;
+
+/** The dispatcher's retained reason for a card whose next run cannot start, or null. */
+export function dispatchWait(db, taskId) {
+  const row = db.prepare(`SELECT (${DISPATCH_WAIT_SQL}) AS wait FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?`).get(taskId);
+  return JSON.parse(row?.wait ?? 'null');
 }
 
 /** Read run history in finite, indexed pages, yielding before each page. The candidate page precedes any JSON

package/board/record-view.mjs

@@ -1,12 +1,14 @@
 // Resident local consumer of the daemon's committed record rows. Disconnects
 // preserve the last applied cursor, but held data is stale until caught up.
 import { jsonObjectReader } from '@volter/teams/lines';
+import { SECTION_PARTS_CODEC, eventSection, sectionParts, hydrateSectionParts } from '@volter/supercode-teams/record-section-parts';
 
 export class RecordView {
   constructor(open, { progressMs = 10_000 } = {}) {
     this.open = open; this.records = {}; this.positions = new Map();
     this.cursor = null; this.stream = null; this.waiters = new Set();
     this.pending = [];
+    this.sectionRows = new Map(); this.dirtySections = new Map();
     this.ready = false; this.heardAt = 0;
     this.progressMs = progressMs; this.progressTimer = null;
   }
@@ -27,7 +29,7 @@ export class RecordView {
   }
   connect() {
     if (this.stream) return Promise.resolve();
-    return this.opening ??= Promise.resolve().then(() => this.open({ after: this.cursor })).then((stream) => {
+    return this.opening ??= Promise.resolve().then(() => this.open({ after: this.cursor, record_row_codecs: [SECTION_PARTS_CODEC] })).then((stream) => {
       this.stream = stream; this.ready = false; this.heardAt = Date.now();
       const readObject = jsonObjectReader();
       stream.on('data', (frame) => {
@@ -82,7 +84,12 @@ export class RecordView {
     if (frame.type === 'beat') { this.heardAt = Date.now(); return; }
     if (frame.type === 'snapshot') {
       this.self = frame.machine; this.records = frame.records; this.positions.clear(); this.pending = [];
-      for (const [machine, held] of Object.entries(this.records)) this.positions.set(machine, new Map((held.record?.sessions ?? []).map((row, at) => [row.address, at])));
+      this.sectionRows.clear(); this.dirtySections.clear();
+      for (const [machine, held] of Object.entries(this.records)) {
+        this.positions.set(machine, new Map((held.record?.sessions ?? []).map((row, at) => [row.address, at])));
+        this.sectionRows.set(machine, new Map(['fleet', 'health_events'].filter(section => Object.hasOwn(held.record ?? {}, section))
+          .map(section => [section, sectionParts(held.record[section])])));
+      }
       this.cursor = frame.cursor; this.ready = true;
     } else if (frame.type === 'changes') {
       if (!this.cursor || frame.cursor?.id !== this.cursor.id) throw new Error('record row changes name a different database; a new snapshot is required');
@@ -99,11 +106,12 @@ export class RecordView {
         if (change.sequence <= this.cursor.sequence || !this.own(change.key)) continue;
         const { machine, section, key, position } = change.key;
         if (change.topic === 'record-head') {
-          if (change.operation === 'delete') { delete this.records[machine]; this.positions.delete(machine); continue; }
+          if (change.operation === 'delete') { delete this.records[machine]; this.positions.delete(machine); this.sectionRows.delete(machine); this.dirtySections.delete(machine); continue; }
           const { record: summary, meta } = change.value;
           const previous = this.records[machine]?.record;
           const record = summary == null ? null : { sessions: [], mail: {}, panes: null, capabilities: null, unread: {}, ...previous, ...summary };
           if (record) { if (!summary.sessions_rows) record.sessions = null; delete record.sessions_rows; }
+          else this.sectionRows.delete(machine);
           this.records[machine] = { record, stream: machine === this.self ? 'self' : meta?.stream ?? 'closed', since: meta?.since ?? null, why: meta?.why ?? null, received_at: meta?.received_at ?? null };
         } else if (change.topic === 'record-row') {
           const held = this.records[machine] ??= { stream: 'closed', record: null };
@@ -118,6 +126,13 @@ export class RecordView {
             record.sessions = [...rows.values()]; moved.add(machine);
           } else if (section === 'mail') {
             if (deleted) delete record.mail[key]; else record.mail[key] = change.value;
+          } else if (eventSection(section)) {
+            const sections = this.sectionRows.get(machine) ?? new Map(); this.sectionRows.set(machine, sections);
+            let rows = sections.get(section) ?? sectionParts(record[section]);
+            if (key === '') { rows = new Map(); if (!deleted) rows.set('', { key, position, value: change.value }); }
+            else { rows.delete(''); if (deleted) rows.delete(key); else rows.set(key, { key, position, value: change.value }); }
+            sections.set(section, rows);
+            const dirty = this.dirtySections.get(machine) ?? new Set(); this.dirtySections.set(machine, dirty); dirty.add(section);
           } else record[section] = deleted ? null : change.value;
         }
       }
@@ -125,6 +140,18 @@ export class RecordView {
         const positions = this.positions.get(machine);
         this.records[machine]?.record?.sessions?.sort((a, b) => (positions.get(a.address) ?? 0) - (positions.get(b.address) ?? 0) || a.address.localeCompare(b.address));
       }
+      // A bounded page can end inside a writer transaction. Keep its row
+      // reconstruction until caught up, when every header/event change is in.
+      if (!frame.more) {
+        for (const [machine, sections] of this.dirtySections) {
+          const record = this.records[machine]?.record;
+          if (record) for (const section of sections) {
+            const rows = this.sectionRows.get(machine)?.get(section);
+            record[section] = rows?.size ? hydrateSectionParts([...rows.values()]) : null;
+          }
+        }
+        this.dirtySections.clear();
+      }
       this.cursor = frame.cursor; this.ready = !frame.more;
     } else throw new Error(`unrecognized record-view frame ${frame.type}`);
     this.heardAt = Date.now();

package/board/request-mail.mjs

@@ -1,13 +1,44 @@
 import { event, json, now } from './store.mjs';
+import { currentRecordChanges, currentRecordConnection } from './current-records.mjs';
+
+const heldMail = new WeakMap();
+const MAIL_KINDS = "('board_message','board_message_sent','board_message_passed','board_message_batch')";
+/** Unsettled mail and its retained envelopes; new events update this small set. */
+export function pendingRequestRows(db) {
+  let held = heldMail.get(currentRecordConnection(db));
+  const change = currentRecordChanges(db, held?.token);
+  const high = Number(db.prepare('SELECT MAX(id) AS id FROM task_events').get()?.id ?? 0);
+  if (!held || change.eventsRewritten || high < held.cursor) {
+    const pending = db.prepare(`SELECT id,task_id,payload,created_at FROM task_events original
+      WHERE kind='board_message' AND NOT EXISTS (SELECT 1 FROM task_events sent
+        WHERE sent.kind IN ('board_message_sent','board_message_passed') AND sent.task_id=original.task_id
+          AND json_extract(CASE WHEN json_valid(sent.payload) THEN sent.payload END,'$.event')=original.id) ORDER BY id`).all()
+      .map(row => ({ ...row, mail: json(row.payload, {}) ?? {} }));
+    const batches = pending.length ? db.prepare("SELECT id,payload FROM task_events WHERE kind='board_message_batch' AND id>=? ORDER BY id").all(pending[0].id) : [];
+    held = { pending: new Map(pending.map(row => [row.id,row])), batches: new Map(batches.map(row => [row.id,json(row.payload,{})])), cursor: high };
+    heldMail.set(currentRecordConnection(db), held);
+  } else {
+    while (held.cursor < high) {
+      const rows = db.prepare(`SELECT id,task_id,kind,payload,created_at FROM task_events
+        WHERE id>? AND id<=? AND kind IN ${MAIL_KINDS} ORDER BY id LIMIT 64`).all(held.cursor,high);
+      if (!rows.length) { held.cursor = high; break; }
+      for (const row of rows) {
+        const payload = json(row.payload,{}) ?? {};
+        if (row.kind === 'board_message') held.pending.set(row.id,{ ...row,mail: payload });
+        else if (row.kind === 'board_message_batch') held.batches.set(row.id,payload);
+        else if (held.pending.get(payload.event)?.task_id === row.task_id) held.pending.delete(payload.event);
+      }
+      held.cursor = rows.at(-1).id;
+    }
+  }
+  for (const [id,batch] of held.batches) if (!batch.members?.some(member => held.pending.has(member.id))) held.batches.delete(id);
+  held.token = change.token;
+  return { pending: [...held.pending.values()].sort((a,b) => a.id-b.id), batches: [...held.batches.values()] };
+}
 
 export function pendingRequestMail(db, taskId = null) {
-  const pending = db.prepare(`SELECT id, task_id, payload, created_at FROM task_events original
-    WHERE kind='board_message' AND NOT EXISTS (SELECT 1 FROM task_events sent WHERE sent.kind IN ('board_message_sent', 'board_message_passed')
-      AND sent.task_id=original.task_id AND json_extract(sent.payload,'$.event')=original.id) ORDER BY id`).all()
-    .map(row => ({ ...row, mail: json(row.payload, {}) ?? {} }));
+  const { pending, batches } = pendingRequestRows(db);
   if (!pending.length) return { ready: [], nextAt: Infinity };
-  const batches = db.prepare("SELECT payload FROM task_events WHERE kind='board_message_batch' AND id>=? ORDER BY id").all(pending[0].id)
-    .map(row => json(row.payload, {}));
   const assigned = new Set();
   const ready = [];
   let nextAt = Infinity;

package/board/resting-admission.mjs

@@ -0,0 +1,318 @@
+// Reader-first native hold admission. The actual stable owner's selected source, never a caller flag, decides
+// whether this generation may interpret fields that a legacy rollback would ignore or lose.
+import { createHash, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { askBoardOwner } from '@volter/teams/board-owner';
+import { nativeJsonEqual, parseNativeJson } from '@volter/supercode-interchange/native-json';
+import { readSourceCandidate, readSourceRecord } 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 { installJournalPath, readInstallJournal } from '@volter/supercode-teams/machine-install-journal'; // layer: the board's resting-reader admission reads the host's durable install decision; owed: the host hands it in
+import { restingContract } from './resting-protocol.mjs';
+import { assertGenerationWriter } from './generation.mjs';
+import { bindRestingReader, assertRestingInput, RESTING_WRITE_MODE } from './resting-state.mjs';
+
+const require = createRequire(import.meta.url);
+const MODE = 'backlog-bounded-pause-v1';
+let admission = null;
+const digest = path => createHash('sha256').update(readFileSync(path)).digest('hex');
+const coreSame = (left, right) => ['root', 'commit', 'supercode', 'binding', 'graph'].every(key =>
+  nativeJsonEqual(left?.[key] ?? null, right?.[key] ?? null));
+function optionalJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+function selectedReader(selected, env) {
+  if (!selected || typeof selected.entry !== 'string' || !isAbsolute(selected.entry))
+    throw new Error('board resting-state admission has no complete incumbent entry');
+  const entry = realpathSync(selected.entry);
+  // Unretained mutable checkout paths name no verified predecessor capability.
+  if (!selected.candidate && !selected.release) return null;
+  if (selected.candidate && selected.release) throw new Error('board incumbent names two source selections');
+  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)) throw new Error('board incumbent source binding changed');
+  } else if (selected.release) {
+    const release = readRetainedRelease(selected.release);
+    if (entry !== realpathSync(release.board) || realpathSync(selected.native) !== realpathSync(release.program))
+      throw new Error('board incumbent release binding changed');
+  }
+  return restingContract(entry, { optional: true });
+}
+
+// Only the current lock-holding owner lends this record, captured before it overwrites its predecessor's record.
+// An ef4 owner writes the older complete shape before activation and removes it on stop, so it cannot carry a stale
+// newer-reader claim through a legacy write, even when the next source has the same entry path or commit.
+function recordedReader(status, env) {
+  try {
+    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;
+  } catch { return null; }
+}
+
+function recordGrantedReader(env) {
+  const request = randomUUID();
+  return new Promise((done, reject) => {
+    let timer;
+    const finish = error => {
+      clearTimeout(timer); process.off('message', receive); process.off('disconnect', disconnected);
+      error ? reject(error) : done();
+    };
+    const receive = frame => {
+      if (frame?.type !== 'resting-reader-recorded' || frame.request !== request || frame.generation !== env.SUPERCODE_BOARD_GENERATION_ID) return;
+      finish(frame.error ? new Error(`board reader selection was not recorded: ${frame.error}`) : null);
+    };
+    const disconnected = () => finish(new Error('board owner disconnected before recording its actual reader'));
+    process.on('message', receive); process.once('disconnect', disconnected);
+    timer = setTimeout(() => finish(new Error('board owner did not record its actual reader within 8 seconds')), 8000);
+    try { process.send({ type: 'resting-writer-granted', request, generation: env.SUPERCODE_BOARD_GENERATION_ID }); }
+    catch (error) { finish(error); }
+  });
+}
+
+// A fresh stable owner has no active child yet. The install's durable source decision is existing selection
+// history, rather than an encoding-admitted boolean an old generation could leave behind on rollback. Source
+// commit follows every component's activation; restoration names the exact predecessor that recovery must start.
+// Cleanup can still be unfinished: it must not strand a cold owner on text the selected reader already supports.
+// The decision, actual primary, prepared home and this invocation's complete selection must all agree. A merely
+// prepared/uncommitted decision grants nothing, and missing/stale history falls back to the legacy collision scan.
+function installDecisionReader(root, env) {
+  const ledger = sourceLockPath(env), home = env.SUPERCODE_TEAMS_HOME ?? join(dirname(ledger), 'teams'), service = join(home, 'service');
+  const journal = readInstallJournal(installJournalPath(home), { optional: true });
+  if (!journal) return null;
+  try {
+    if (journal.preparedInputs === undefined) return null;
+    const rows = journal.boards.filter(board => board.home === root);
+    if (rows.length !== 1) return null;
+    const board = rows[0], prepared = journal.preparedInputs;
+    const recorded = prepared.boards?.filter(item => item?.home === board.home);
+    if (recorded?.length !== 1 || !nativeJsonEqual(recorded[0].before?.selected, board.before?.selected) ||
+      !nativeJsonEqual(recorded[0].predecessorReceipts, board.predecessorReceipts) ||
+      prepared.candidate !== journal.candidate || prepared.published !== journal.published ||
+      !/^[a-f0-9]{64}$/.test(prepared.candidateSha256 ?? '') || digest(journal.candidate) !== prepared.candidateSha256) return null;
+    let selected, committed;
+    if (journal.published) {
+      const release = readRetainedRelease(journal.candidate), decision = optionalJson(join(service, 'release-handover.json'));
+      if (decision?.transaction !== journal.transaction || decision.candidate !== journal.candidate ||
+        !['committed', 'restored'].includes(decision.state)) return null;
+      committed = decision.state === 'committed';
+      selected = committed ? { entry: release.board, native: release.program, release: journal.candidate, candidate: null } : board.before.selected;
+      if (!selected?.release || selected.candidate) return null;
+      const expected = readRetainedRelease(selected.release), primary = optionalJson(join(service, 'active-release.json'));
+      const outcome = committed ? decision.next : JSON.parse(decision.previous_text);
+      if (!nativeJsonEqual(primary, outcome) ||
+        !['root', 'native', 'entry', 'release'].every(key => primary?.release?.[key] === expected[key])) return null;
+      const own = env.SUPERCODE_RELEASE_RECEIPT && readRetainedRelease(env.SUPERCODE_RELEASE_RECEIPT);
+      if (!own || env.SUPERCODE_SOURCE_CANDIDATE || own.receipt !== expected.receipt) return null;
+    } else {
+      const candidate = readSourceCandidate(journal.candidate, ledger);
+      const decision = readSourceRecord(join(dirname(candidate.path), 'activation.json'));
+      if (decision.transaction !== journal.transaction || decision.candidate !== candidate.path ||
+        !['committed', 'restored'].includes(decision.state) || !coreSame(decision.next, candidate.value.lock)) return null;
+      committed = decision.state === 'committed';
+      selected = committed ? { entry: join(candidate.value.lock.root, 'sdk/orchestrator/bin/orchestrator.mjs'),
+        native: candidate.program, candidate: candidate.path, release: null } : board.before.selected;
+      if (!selected?.candidate || selected.release) return null;
+      const expected = readSourceCandidate(selected.candidate, ledger);
+      const primary = readSourceRecord(ledger), outcome = committed ? decision.next : parseNativeJson(decision.previous_text);
+      if (!nativeJsonEqual(primary, outcome) || !coreSame(primary, expected.value.lock)) return null;
+      const own = env.SUPERCODE_SOURCE_CANDIDATE && readSourceCandidate(env.SUPERCODE_SOURCE_CANDIDATE, ledger);
+      if (!own || env.SUPERCODE_RELEASE_RECEIPT || !coreSame(own.value.lock, expected.value.lock)) return null;
+    }
+    if (!committed) for (const receipt of Object.values(board.predecessorReceipts ?? {})) {
+      if (!receipt || !/^[a-f0-9]{64}$/.test(receipt.sha256 ?? '') || digest(receipt.path) !== receipt.sha256) return null;
+    }
+    if (!env.SUPERCODE_ORCHESTRATOR_ENTRY || realpathSync(env.SUPERCODE_ORCHESTRATOR_ENTRY) !== realpathSync(selected.entry) ||
+      !env.SUPERCODE_BIN || realpathSync(env.SUPERCODE_BIN) !== realpathSync(selected.native)) return null;
+    return selected;
+  } catch { return null; }
+}
+
+// Enumerate storage declarations, not dispatchable boards: an archived board and every rotated archive still
+// belong to the home. Read only the old projection's inventory and pending bytes, never openBoard or a new parser.
+function boardDocuments(root, inspect) {
+  const markers = [], base = join(root, 'kanban'), named = join(base, 'boards');
+  if (existsSync(join(base, 'ztrack.json'))) markers.push(join(base, 'ztrack.json'));
+  if (existsSync(named)) for (const slug of readdirSync(named)) {
+    const marker = join(named, slug, 'ztrack.json');
+    if (existsSync(marker)) markers.push(marker);
+  }
+  for (const marker of markers) {
+    const config = optionalJson(marker);
+    if (!config || typeof config.document !== 'string') throw new Error(`board resting-state admission: invalid document declaration ${marker}`);
+    const document = resolve(dirname(marker), config.document), directory = dirname(document);
+    const paths = new Set([document, `${document}.archive.md`]);
+    if (existsSync(directory)) for (const name of readdirSync(directory))
+      if (name.startsWith(`${basename(document)}.archive-`) && name.endsWith('.md')) paths.add(join(directory, name));
+    let pending = null;
+    const projection = `${marker}.board.db`;
+    if (existsSync(projection) && statSync(projection).size) {
+      const db = new DatabaseSync(projection, { readOnly: true });
+      try {
+        db.exec('BEGIN');
+        if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='board_state'").get()) {
+          const state = key => {
+            const row = db.prepare('SELECT value FROM board_state WHERE key=?').get(key);
+            return row ? JSON.parse(row.value) : null;
+          };
+          const archives = state('archives') ?? [];
+          if (!Array.isArray(archives)) throw new Error(`board resting-state admission: invalid archive inventory ${projection}`);
+          for (const archive of archives) {
+            if (!archive || typeof archive.name !== 'string' || archive.name !== basename(archive.name))
+              throw new Error(`board resting-state admission: invalid archive path ${projection}`);
+            paths.add(join(directory, archive.name));
+          }
+          pending = state('pending');
+        }
+      } finally { db.close(); }
+    }
+    for (const path of paths) {
+      let text;
+      try { text = readFileSync(path, 'utf8'); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+      inspect(text, path);
+    }
+    if (pending !== null) {
+      if (!Array.isArray(pending.files)) throw new Error(`board resting-state admission: invalid pending publication ${projection}`);
+      for (const file of pending.files) {
+        if (!file || typeof file.path !== 'string' || !paths.has(resolve(file.path)) || typeof file.base !== 'string' || typeof file.text !== 'string')
+          throw new Error(`board resting-state admission: invalid pending document ${projection}`);
+        inspect(file.base, `${file.path} (pending base)`);
+        inspect(file.text, `${file.path} (pending publication)`);
+      }
+    }
+  }
+}
+
+
+export function assertBoardRestingDocument(text, path) {
+  if (!admission || admission.compatible) return;
+  // Preparation and read-only snapshots inspect the same archived documents. Reuse only a successful
+  // observation of these exact text bytes at this path; a changed document is inspected again before use.
+  if (admission.inspected.get(path) === text) return;
+  const slots = admission.inspect(text, path);
+  if (!Array.isArray(slots)) throw new Error('board codec returned no resting-state slot inventory');
+  if (slots.length) throw new Error(`board resting-state admission: new reader metadata has no compatible incumbent reader in ${path}:${slots[0].line}`);
+  admission.inspected.set(path, text);
+}
+
+function inspectRows(db, path) {
+  if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='supercode_cards'").get()) return;
+  const hasBacklog = db.prepare('PRAGMA table_info(supercode_cards)').all().some(column => column.name === 'backlog');
+  for (const row of db.prepare(`SELECT task_id,paused,${hasBacklog ? 'backlog' : 'NULL AS backlog'} FROM supercode_cards`).all())
+    assertRestingInput(row.paused, row.backlog, { source: `${path}:${row.task_id}` });
+}
+
+// Scan every backing, archived board and pending publication before granting a writer. No schema migration or
+// modern parser runs here; the incumbent's raw declarations and rows are the inventory.
+function inspectHome(root) {
+  if (admission?.compatible) return;
+  const base = join(root, 'kanban'), named = join(base, 'boards');
+  const places = [{ directory: base, sqlite: join(root, 'kanban.db') }];
+  if (existsSync(named)) for (const name of readdirSync(named)) {
+    const directory = join(named, name);
+    if (statSync(directory).isDirectory()) places.push({ directory, sqlite: join(directory, 'kanban.db') });
+  }
+  for (const { directory, sqlite } of places) {
+    const files = join(directory, 'board');
+    if (existsSync(join(files, '_board.json'))) {
+      for (const name of readdirSync(files)) {
+        if (!name.endsWith('.json')) continue;
+        const path = join(files, name), card = optionalJson(path);
+        for (const row of card?.tables?.supercode_cards ?? []) assertRestingInput(row.paused, row.backlog, { source: path });
+      }
+    }
+    for (const path of [sqlite, join(directory, 'ztrack.json.board.db')]) {
+      if (!existsSync(path) || !statSync(path).size) continue;
+      const db = new DatabaseSync(path, { readOnly: true });
+      try { db.exec('BEGIN'); inspectRows(db, path); } finally { db.close(); }
+    }
+  }
+  boardDocuments(root, assertBoardRestingDocument);
+}
+
+// A retained final source can be its own first reader, before a board exists. An initialized or previously
+// used home is never inferred fresh from empty task rows. A fencing counter alone carries no resting data.
+// The only generation record allowed during activation is this
+// owner's provisional selection for this exact child; it is not itself a durable reader acknowledgement.
+export function pristineHome(root, { owner, generation, selected, provisional = false, epoch } = {}) {
+  if (['kanban', 'kanban.db', 'kanban.db-wal', 'kanban.db-shm'].some(name => existsSync(join(root, name)))) return false;
+  let recordedEpoch = null;
+  try {
+    const text = readFileSync(join(root, 'board.epoch'), 'utf8');
+    recordedEpoch = Number(text);
+    if (!Number.isSafeInteger(recordedEpoch) || recordedEpoch < 1 || text !== `${recordedEpoch}\n`) return false;
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  // Admission may encounter an abandoned pre-writer fence. Activation must name this invocation's new one.
+  if (epoch !== undefined && (!Number.isSafeInteger(epoch) || epoch < 1 || recordedEpoch !== epoch)) return false;
+  const recordPath = join(root, 'board-generation.json');
+  if (!existsSync(recordPath)) return true;
+  const record = optionalJson(recordPath);
+  return provisional && record?.version === 1 && record.owner === owner && record.active === process.pid && record.generation === generation &&
+    nativeJsonEqual(record.selected, selected) && record.lastRestingReader == null && record.previous == null &&
+    Array.isArray(record.unended) && record.unended.length === 0;
+}
+
+export async function prepareBoardRestingAdmission(root, env = process.env) {
+  if (admission) throw new Error('board resting-state admission is already captured for this generation');
+  root = realpathSync(root);
+  const answer = await askBoardOwner(root, { argv: ['handover', '--action', 'status'] }, { waitMs: 0, timeoutMs: 8000 });
+  if (answer.code !== 0 || answer.unanswered) throw new Error('board resting-state admission: incumbent owner status is unknown');
+  const status = JSON.parse(Array.isArray(answer.stdout) ? answer.stdout.join('') : answer.stdout);
+  if (status.protocol !== 1 || status.owner !== process.ppid || status.owner !== Number(env.SUPERCODE_BOARD_GENERATION_OWNER))
+    throw new Error('board resting-state admission: status does not name this generation’s own stable owner');
+  // Active selected source is authoritative. Recorded/journal history is usable only when the cold owner has no
+  // active generation, and every retained source and digest still binds to the actual selection.
+  const selected = status.selected ?? installDecisionReader(root, env) ?? recordedReader(status, env);
+  const reader = selected ? selectedReader(selected, env) : null;
+  // Earlier, unreleased v1 hold readers did not understand the richer Acceptance layout. A hold-mode claim alone
+  // cannot authorize a writer of that text; require its separately source-bound codec capability as well.
+  let compatible = reader?.protocol.readModes.includes(MODE) === true
+    && reader.codec?.formatFeatures?.includes('acceptance-layout-v1') === true;
+  const own = restingContract();
+  let firstReader = null;
+  if (!selected && !compatible && RESTING_WRITE_MODE !== 'legacy-holds' && status.restingReaderProtocol === 1) {
+    const ownSelected = { entry: env.SUPERCODE_ORCHESTRATOR_ENTRY, native: env.SUPERCODE_BIN,
+      candidate: env.SUPERCODE_SOURCE_CANDIDATE || null, release: env.SUPERCODE_RELEASE_RECEIPT || null };
+    const first = { owner: status.owner, generation: env.SUPERCODE_BOARD_GENERATION_ID, selected: ownSelected,
+      epoch: status.firstReaderEpoch ?? null };
+    if (pristineHome(root, first)) {
+      const actual = selectedReader(ownSelected, env);
+      if (actual?.codec?.formatFeatures?.includes('acceptance-layout-v1') === true
+          && nativeJsonEqual(actual, own)) { firstReader = first; compatible = true; }
+    }
+  }
+  const codec = require('@volter/ztrack/board-document');
+  if (typeof codec.inspectBoardRestingSlots !== 'function') throw new Error('board codec has no raw resting-state inspection door');
+  admission = Object.freeze({ compatible, selected, reader, inspect: codec.inspectBoardRestingSlots, inspected: new Map() });
+  bindRestingReader(compatible);
+  let activated = false;
+  const preflight = () => {
+    if (firstReader && !activated && !pristineHome(root, { ...firstReader, provisional: true }))
+      throw new Error('board first-reader admission is no longer pristine; no writer was granted');
+    inspectHome(root);
+  };
+  preflight();
+  // Field writers cannot be admitted against a legacy source, even on an empty board. A bridge only publishes the
+  // exact tested legacy-readable contract in that mode; rollback over a final reader makes no such claim.
+  if (RESTING_WRITE_MODE !== 'legacy-holds' && !compatible)
+    throw new Error('board resting-state writer requires an actually selected compatible reader bridge');
+  return {
+    compatible,
+    firstReader: Boolean(firstReader),
+    preflight,
+    async activateWriter() {
+      assertGenerationWriter();
+      if (status.restingReaderProtocol === 1) await recordGrantedReader(env);
+      else if (RESTING_WRITE_MODE !== 'legacy-holds')
+        throw new Error('board owner predates durable resting-state reader selections; restart it through its lifecycle before enabling hold writes');
+      activated = true;
+    },
+    contract: { restingReaderProtocol: 1, resting: own, restingAdmission: firstReader ? 'first-reader' : compatible ? 'compatible-reader' : 'legacy-reader' },
+  };
+}