@volter/supercode-orchestrator 0.5.228 → 0.5.230

package/board/resting-codec-qualifications.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "codec": "sources/ztrack",
+  "canonicalContract": "UTF-8 JSON.stringify(contract, null, 2) followed by LF",
+  "qualified": {
+    "c81532c89e45bf29c74f0a3a62be7e112df72c9f": {
+      "contractSha256": "6de082ba7ea63f1a5fc7529d81664a926e46a5770b044d5a3737e972c22a11d0",
+      "evidence": [
+        "VO-3783 attachment 25595: pinned Bun 1.2.20 build/pack and public-door proof index",
+        "VO-3783 attachment 25596: exact raw/artifact hash manifest",
+        "VO-3783 attachment 25592: c81532c applicability; all 388 source files and 15 packed public artifacts match the recorded 8133a03 build",
+        "https://github.com/volter-ai/ztrack/pull/77 at c81532c89e45bf29c74f0a3a62be7e112df72c9f: independent PASS, VO-3783 report 25611 and audit 25608"
+      ]
+    },
+    "6bb0ecb81aa0d6ac91dc51ee28fb572df0d382c6": {
+      "contractSha256": "6de082ba7ea63f1a5fc7529d81664a926e46a5770b044d5a3737e972c22a11d0",
+      "evidence": [
+        "https://github.com/volter-ai/ztrack/pull/79 at 4cbed24c07d08dc1df0b6d0ff07dc14accd2d4e1: independent PASS; merge 6bb0ecb81aa0d6ac91dc51ee28fb572df0d382c6 changes only build invocation and CONTRIBUTING",
+        "VO-3758 attachment 29417: exact 6bb0ecb Windows build with frozen dependencies and pinned Bun 1.2.20",
+        "VO-3758 attachment 29415: exact 6bb0ecb macOS build with frozen dependencies and pinned Bun 1.2.20",
+        "VO-3758 attachment 29416: all 15 public artifact records and canonical contract hash match qualified c81532c89; existing VO-3783 product-door evidence remains applicable to identical artifacts"
+      ]
+    },
+    "15244d929d317facaef3d1580b19b80be338f872": {
+      "contractSha256": "6de082ba7ea63f1a5fc7529d81664a926e46a5770b044d5a3737e972c22a11d0",
+      "evidence": [
+        "https://github.com/volter-ai/ztrack/pull/83 at 0fac4b2fff3f6ca8d526760efadddabae52fb3b5: independent PASS; build-node-cli.mjs places boilerplates/presets at dist/boilerplates/presets (no codec artifact)",
+        "https://github.com/volter-ai/ztrack/pull/84 at c63037efe9124abc2ab2d6f2cd0b1a88c3d60975: independent PASS; visualizerPresentation.ts packageRoot() looks for @volter/ztrack (no codec artifact); merge 15244d929d317facaef3d1580b19b80be338f872",
+        "exact 15244d9 Linux (WSL2 x64) build with frozen dependencies and pinned Bun 1.2.20 (node scripts/pinned-bun.mjs pnpm --filter @volter/ztrack build): all 15 public artifact records and the canonical contract hash match qualified c81532c89 and 6bb0ecb8"
+      ]
+    }
+  }
+}

package/board/resting-protocol.mjs

@@ -0,0 +1,71 @@
+// The source-bound reader declaration is checked against shipped modules and the public codec artifacts.
+// A source or codec edit invalidates it until regeneration and independent review qualify the new head.
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nativeJsonEqual } from '@volter/supercode-interchange/native-json';
+
+const RESTING_V1_CARD_FILES = ['store.mjs', 'files.mjs', 'ztrack.mjs', 'published.mjs', 'engine.mjs', 'workflow.mjs',
+  'capacity.mjs', 'card-state.mjs', 'dispatch.mjs', 'cli.mjs', 'generation-owner.mjs', 'fence.mjs', 'storage-contract.mjs',
+  'agent-declarations.mjs', 'listing.mjs', 'incidents.mjs', 'args.mjs', '../agents.mjs', '../kanban-worker.mjs',
+  'resting-state.mjs', 'session-continuity.mjs', 'resting-admission.mjs', 'resting-protocol.mjs'];
+export const RESTING_PROTOCOL_FILES = [...RESTING_V1_CARD_FILES, 'event-stream.mjs', 'publication-reader.mjs'];
+// The serving predecessor's exact inventory (4d2208fe): its declaration also bound execution.mjs, ci.mjs and tools.mjs.
+// This writer reads it to admit that reader as its rollback (ADR 0080); it declares the set above.
+const RESTING_PREDECESSOR_FILES = [...RESTING_PROTOCOL_FILES, 'execution.mjs', 'ci.mjs', 'tools.mjs'];
+const ownEntry = fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url));
+export function restingProtocolSources(entry = ownEntry, files = RESTING_PROTOCOL_FILES) {
+  const directory = resolve(dirname(entry), '../board');
+  return Object.fromEntries(files.map(file => [file, createHash('sha256').update(readFileSync(join(directory, file))).digest('hex')]));
+}
+export function restingCodecContract(entry = ownEntry) {
+  const resolver = createRequire(entry);
+  const codec = resolver('@volter/ztrack/board-protocol');
+  if (typeof codec.boardDocumentContract !== 'function') throw new Error('resting-state reader has no bound public codec contract');
+  const contract = codec.boardDocumentContract();
+  if (contract?.formatFeatures != null && (!Array.isArray(contract.formatFeatures)
+      || contract.formatFeatures.some(feature => typeof feature !== 'string')))
+    throw new Error('invalid public codec format feature inventory');
+  if (contract?.version !== 1 || !Array.isArray(contract.readModes) || !contract.readModes.includes('legacy-holds') ||
+      !contract.readModes.includes('backlog-bounded-pause-v1') || !['legacy-holds', 'backlog-bounded-pause-v1'].includes(contract.writer) ||
+      contract.preservation?.mode !== 'backlog-bounded-pause-v1' || contract.preservation?.requiresCompatibleAdmission !== true ||
+      !contract.artifacts || typeof contract.artifacts !== 'object') throw new Error('invalid public resting-state codec contract');
+  const directory = dirname(resolver.resolve('@volter/ztrack/board-protocol'));
+  const packageRoot = dirname(resolver.resolve('@volter/ztrack/package.json'));
+  const required = ['./boardProtocol.js', './boardMode.js', './boardDocument.js', './documentParser.js', './documentWriteBack.js',
+    './markdownDocument.js', './legacyBoard/boardDocument.js', './legacyBoard/documentParser.js', './legacyBoard/documentWriteBack.js',
+    './legacyBoard/markdownDocument.js', './legacyBoard/kanban.js', '../kanban-preset.cjs', '../preset-kit.cjs', '../../package.json'];
+  for (const name of required) if (!Object.hasOwn(contract.artifacts, name)) throw new Error(`codec contract omits ${name}`);
+  for (const [name, receipt] of Object.entries(contract.artifacts)) {
+    const path = resolve(directory, name);
+    if (!path.startsWith(packageRoot + sep)) throw new Error('codec artifact escapes its selected package');
+    const bytes = readFileSync(path);
+    if (receipt.bytes !== bytes.length || receipt.sha256 !== createHash('sha256').update(bytes).digest('hex'))
+      throw new Error(`codec artifact differs from its declared bytes: ${name}`);
+  }
+  for (const [name, path] of [['board-document', './boardDocument.js'], ['kanban-preset', '../kanban-preset.cjs'], ['preset-kit', '../preset-kit.cjs']])
+    if (resolver.resolve(`@volter/ztrack/${name}`) !== resolve(directory, path)) throw new Error(`codec public export ${name} changed`);
+  return contract;
+}
+export function restingContract(entry = ownEntry, { optional = false } = {}) {
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(resolve(dirname(entry), '../board/resting-state-protocol.json'), 'utf8')); }
+  catch (error) { if (optional && error.code === 'ENOENT') return null; throw error; }
+  const stateSource = readFileSync(resolve(dirname(entry), '../board/resting-state.mjs'), 'utf8');
+  // The first v1 readers already read the complete card format. Adding a pure publication reader to later source
+  // declarations must not invalidate their retained card-reader capability. Accept only these exact known source
+  // sets, checking every declared byte; the current writer's generated declaration always includes the newer pair.
+  const keys = Object.keys(manifest.sources ?? {}).sort();
+  const files = [RESTING_PROTOCOL_FILES, RESTING_PREDECESSOR_FILES, RESTING_V1_CARD_FILES].find(files => nativeJsonEqual([...files].sort(), keys));
+  const sourceWriter = /export const RESTING_WRITE_MODE = '(legacy-holds|backlog-bounded-pause-v1)';/.exec(stateSource)?.[1];
+  if (!sourceWriter || manifest.protocol?.writer !== sourceWriter || manifest.version !== 1 || manifest.protocol?.version !== 1 ||
+      !Array.isArray(manifest.protocol.readModes) || !manifest.protocol.readModes.includes('legacy-holds') ||
+      !manifest.protocol.readModes.includes('backlog-bounded-pause-v1') ||
+      !['legacy-holds', 'backlog-bounded-pause-v1'].includes(manifest.protocol.writer) ||
+      !files || !nativeJsonEqual(manifest.sources, restingProtocolSources(entry, files)) ||
+      !nativeJsonEqual(manifest.codec, restingCodecContract(entry)))
+    throw new Error('resting-state reader contract does not bind the selected source and public codec artifacts');
+  return manifest;
+}

package/board/resting-state-protocol.json

@@ -0,0 +1,120 @@
+{
+  "version": 1,
+  "protocol": {
+    "version": 1,
+    "readModes": [
+      "legacy-holds",
+      "backlog-bounded-pause-v1"
+    ],
+    "writer": "backlog-bounded-pause-v1"
+  },
+  "sources": {
+    "store.mjs": "bd9b997c6f9edb43a68487ab1cd4986dbe2d17d059fb308df30f10663337bca6",
+    "files.mjs": "73a523dc68e20cf6ffaae9c153dd050f5a8f5372d7e9f9ba25be3ed5476a62e8",
+    "ztrack.mjs": "ef2c61b3edf82c95301f0ac131e3ac5421141e494d6d64067643e0d524f3a4d9",
+    "published.mjs": "3036ec76f6cb12e6e9de422ad9fe034b0d38bd4dfe27072467c1242305884f5c",
+    "engine.mjs": "d71281edb326a62d639dce4be25a159d93a373a3132146dd0b543171925dfb52",
+    "workflow.mjs": "68d2c94a2a5094b7941d8150fb760ba0f5955df7d6e0e0f0047e300855341b84",
+    "capacity.mjs": "67c10c856c0705a9d39b79a86f0548cd7d4fbf1c4ab1682f8c0ad33e01d8211a",
+    "card-state.mjs": "1228f54a0ec6e2bd84954bb6a93acf9324214aec462a651bf0b03a1d91965ef2",
+    "dispatch.mjs": "019feb1a3f2b6739401d1c671bbfb921923a096b51db5fb5de32e00a74ac1794",
+    "cli.mjs": "b5ffebe93d70a49997039b50008494d5af5b38714edfcd1d02d8c2daa80f271e",
+    "generation-owner.mjs": "074c99e565e03bd6ace918aadc5eb7b353bbfcb0ed8d4d7f68c839eabb7016ed",
+    "fence.mjs": "e2fc0811e94634cd653d3d436611f67dc3f1068752c1d04617a8f9f1e35435f0",
+    "storage-contract.mjs": "581a059151b5443a95e38e5ee7dab9c77cddd59bdd407a16e0348ae5b7960c86",
+    "agent-declarations.mjs": "f44327c3ffaf71c91534030c62d4fa2e51717669eba91f33d7fb8269c1f0d101",
+    "listing.mjs": "546bde7cf7aaac5b9b198f31ea9c2fe8baf1d7256b398184bd2ea734c3614cd3",
+    "incidents.mjs": "4181db056fbf8dab8592984b20130fc7fb6dd316c54fba8e1cf76b9a15d7e224",
+    "args.mjs": "9f3e3707dc54d934f2326d12f000dc882f5a97980612413377f396b39fc755f4",
+    "../agents.mjs": "40eb279c5b0c618f103c2d28c9a777f344c6168ac6be0833b1e84d92b13e183f",
+    "../kanban-worker.mjs": "19e9f20ba9d95329b600516c350b1feaf8931dd62021596ded9f8be6f8fb4532",
+    "resting-state.mjs": "9c37266217ffcaa0d133118e3223a4ed28df5973c8b253cc1d3bd4df8dfb111c",
+    "session-continuity.mjs": "79adebb63c7851be6f95cf622df705afda8a9c0e6a9295315e8b8128c1c31518",
+    "resting-admission.mjs": "636d96991ec3aeb62cf2f415854f7ba2e85b435f28728677e18bb5ce6d3112ea",
+    "resting-protocol.mjs": "f25e6efe4e5dd31ccae92393d91b4d10f786aacececc43ae8680ffcf644e826c",
+    "event-stream.mjs": "23adb977d7123b90d151d35979138dfe7980dcbb523f738bb93a2fd01acfeda1",
+    "publication-reader.mjs": "1ffd82970ba927e2807bb27015c9a8a3f812157ac68c15612b8cd94ab26f0ef6"
+  },
+  "codec": {
+    "version": 1,
+    "readModes": [
+      "legacy-holds",
+      "backlog-bounded-pause-v1"
+    ],
+    "formatFeatures": [
+      "acceptance-layout-v1"
+    ],
+    "defaultReader": "legacy-holds",
+    "writer": "legacy-holds",
+    "legacySource": "be866b90b7b36ebf36ff998b510291a167a3ff2e",
+    "preservation": {
+      "option": {
+        "resting": "preserve"
+      },
+      "mode": "backlog-bounded-pause-v1",
+      "requiresCompatibleAdmission": true
+    },
+    "artifacts": {
+      "../../package.json": {
+        "sha256": "d552f041606f781d1e91c9ffe18aa80ccefac17b405e6cef2a3904f63672af4e",
+        "bytes": 5071
+      },
+      "./boardProtocol.js": {
+        "sha256": "a42bf525c129aacfab137743e8f35fddf1daafc1f6179705e26228266a50f0e1",
+        "bytes": 1688
+      },
+      "./boardMode.js": {
+        "sha256": "7605bc7f4184ee8c0a0df117cb9d1c88dced8901edad91de08e0e278fea5ee68",
+        "bytes": 625
+      },
+      "./boardDocument.js": {
+        "sha256": "4c7aed341de930dfa96c110e602aee47f0ab36d60c41777ddafee66dca68fb01",
+        "bytes": 14130
+      },
+      "./documentParser.js": {
+        "sha256": "6bb69da8c381ef6695fd27d63c88483dcadc7f506519d64a1d621e2eab07e906",
+        "bytes": 12228
+      },
+      "./documentWriteBack.js": {
+        "sha256": "5350ade8b30acaf48367751835eb761662d3a1f74ddf5c6a548894c9c56e9905",
+        "bytes": 23534
+      },
+      "./markdownDocument.js": {
+        "sha256": "1ac23c01b066b1f5aece80a6e6d7c5d74959759bbe3fa4934d0751adc1daefb4",
+        "bytes": 24064
+      },
+      "./legacyBoard/boardDocument.js": {
+        "sha256": "c0caac097a65fa6e7c8ba87bcb11aedeb9a5bdc31e9c3c295fd9ab7e44dd5029",
+        "bytes": 10213
+      },
+      "./legacyBoard/documentParser.js": {
+        "sha256": "3f1d5742ae8c0eaf311ea0564da5736607843233a00702c94b3a9c500a939579",
+        "bytes": 11431
+      },
+      "./legacyBoard/documentWriteBack.js": {
+        "sha256": "bd43dc7d32122b78f1fbbd73eee0a5b6bc38b65b2d23bf753b4492dfb806dc86",
+        "bytes": 17272
+      },
+      "./legacyBoard/markdownDocument.js": {
+        "sha256": "829848e792e95f4e6a24f9c7312db35c2a8ad6c1727447b4766c9600e8c2d705",
+        "bytes": 24242
+      },
+      "./legacyBoard/kanban.js": {
+        "sha256": "d583dc1890d9ad178ef9df34493db793e4a1fb93a4fc68c95a12f590701dcfcc",
+        "bytes": 26471
+      },
+      "../kanban-preset.cjs": {
+        "sha256": "47bb32dbbb11b3ab6aaadcd48abd6f5cd0840ad39c1351e8a69f467a23b6004c",
+        "bytes": 39901
+      },
+      "../preset-kit.cjs": {
+        "sha256": "729a85b3d9b19fe6f93bbb262f3d7ab56c4d07f6c3c4ea18b1f3b0f2aac8a8d6",
+        "bytes": 586547
+      },
+      "../../boilerplates/presets/kanban.ts": {
+        "sha256": "da48456687b655f0f8504cd54315ad5a99ca8833416b5efad03957d917a70e62",
+        "bytes": 52461
+      }
+    }
+  }
+}

package/board/resting-state.mjs

@@ -0,0 +1,113 @@
+// Resting cards retain conversations, never unresolved execution holdings (ADR 0248).
+// These checks also run at import boundaries; a raw flag is not proof that a session stopped.
+const parse = value => { try { return typeof value === 'string' ? JSON.parse(value) : value; } catch { return null; } };
+
+// This is a reviewed source decision, never an environment toggle. The second release changes it only after
+// the selected predecessor has demonstrated the complete native and codec reader contract.
+export const RESTING_WRITE_MODE = 'backlog-bounded-pause-v1';
+export const NEW_HOLD_SQL = "(backlog IS NOT NULL AND backlog != 'null') OR (json_type(CASE WHEN json_valid(paused) THEN paused END,'$.until') IS NOT NULL OR json_type(CASE WHEN json_valid(paused) THEN paused END,'$.generation') IS NOT NULL)";
+let compatibleReader = false, readerBound = false;
+export function bindRestingReader(compatible) {
+  if (readerBound) throw new Error('the native resting-state reader admission is already bound');
+  compatibleReader = compatible === true; readerBound = true;
+}
+export const restingReaderBound = () => readerBound;
+export const restingSerializationOptions = () => compatibleReader ? { resting: 'preserve' } : { resting: 'legacy' };
+export function assertRestingInput(pause, backlog, { source = 'store' } = {}) {
+  if (compatibleReader) return;
+  const held = parse(pause);
+  if ((backlog != null && backlog !== 'null') || (held && (Object.hasOwn(held, 'until') || Object.hasOwn(held, 'generation'))))
+    throw new Error(`${source}: new hold metadata has no compatible incumbent reader; predecessor retained`);
+}
+export function assertRestingRows(db, source = 'store') {
+  if (compatibleReader) return;
+  const row = db.prepare(`SELECT task_id,paused,backlog FROM supercode_cards WHERE ${NEW_HOLD_SQL} LIMIT 1`).get();
+  if (row) assertRestingInput(row.paused, row.backlog, { source: `${source}:${row.task_id}` });
+}
+export function assertRestingWrite(name, value, previous = null) {
+  if (!value) return;
+  if (RESTING_WRITE_MODE === 'legacy-holds') {
+    if (name === 'backlog' || value.until != null || value.generation != null || previous?.until != null || previous?.generation != null)
+      throw new Error('the reader bridge cannot create or extend bounded pauses or backlog; adopt the reviewed field writer first');
+  } else if (!compatibleReader) throw new Error('native hold writes require an actually selected compatible reader bridge');
+}
+
+export const PAUSE_DEADLINE = "json_extract(CASE WHEN json_valid(paused) THEN paused END,'$.until')";
+
+/** Normalize both waiting verbs on the board's clock. A pause requires an explicit future UTC deadline;
+ * a heartbeat may omit its deadline and retains invalid input as missing detail. */
+export function deadlineUntil(value, clock, verb) {
+  const pause = verb === 'pause';
+  if (!pause && (value == null || value === true || typeof value === 'string' && !value.trim())) return null;
+  let deadline;
+  if (typeof value === 'number') deadline = value;
+  else {
+    const text = String(value ?? '').trim();
+    const duration = /^(\d+(?:\.\d+)?)(\s*)([smhdw])$/i.exec(text);
+    if (duration && (!pause || !duration[2] && duration[3].toLowerCase() !== 'w'))
+      deadline = clock + Number(duration[1]) * { s: 1, m: 60, h: 3600, d: 86400, w: 604800 }[duration[3].toLowerCase()];
+    else if (!pause && /^\d+(?:\.\d+)?$/.test(text)) deadline = Number(text);
+    else if (!pause || /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|\+00:00)$/i.test(text)) {
+      deadline = Date.parse(text) / 1000;
+      // Date.parse normalizes impossible month days; those are typos, not authorization.
+      if (pause && Number.isFinite(deadline) && new Date(deadline * 1000).toISOString().slice(0, 10) !== text.slice(0, 10)) deadline = NaN;
+    }
+  }
+  const rounded = Math.ceil(deadline);
+  if (!Number.isSafeInteger(rounded) || !Number.isFinite(new Date(rounded * 1000).getTime()) || pause && deadline <= clock) {
+    if (pause) throw new Error('pause requires a finite future --until in UTC (2026-10-30T12:00Z) or a duration (2h)');
+    return NaN;
+  }
+  return rounded;
+}
+
+/** Old attributed pauses are readable; a new deadline always travels with its generation. */
+export function assertPauseRecord(pause, { id = 'card', source = 'store' } = {}) {
+  if (pause == null) return;
+  if (!pause || typeof pause !== 'object' || Array.isArray(pause) || typeof pause.by !== 'string' || !pause.by.trim() || typeof pause.reason !== 'string' || !pause.reason.trim()
+    || Object.keys(pause).some(key => !['by', 'reason', 'until', 'generation'].includes(key))
+    || ((Object.hasOwn(pause, 'until') || Object.hasOwn(pause, 'generation')) && (!Number.isSafeInteger(pause.until) || pause.until <= 0 || !Number.isFinite(new Date(pause.until * 1000).getTime()) || typeof pause.generation !== 'string' || !pause.generation.trim())))
+    throw new Error(`${id}: ${source} has malformed pause metadata`);
+}
+
+/** Current stopped/released evidence, including launches that never bound a native id. */
+export function backlogQualification(db, id) {
+  const task = db.prepare('SELECT current_run_id FROM tasks WHERE id=?').get(id);
+  if (!task) return { qualified: false, reason: `no card ${id}` };
+  if (task.current_run_id != null) return { qualified: false, reason: `current run ${task.current_run_id} must end before backlog entry` };
+  if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='supercode_side_sessions'").get()
+    && db.prepare('SELECT 1 FROM supercode_side_sessions WHERE task_id=? LIMIT 1').get(id))
+    return { qualified: false, reason: 'attached side sessions must be explicitly released before backlog entry' };
+  const custody = new Set(db.prepare('SELECT address FROM supercode_session_custody WHERE task_id=?').all(id).map(row => row.address));
+  for (const row of db.prepare('SELECT id,ended_at,worker_pid,metadata FROM task_runs WHERE task_id=? ORDER BY id DESC').all(id)) {
+    if (row.ended_at == null) return { qualified: false, reason: `run ${row.id} has not ended` };
+    const session = parse(row.metadata)?.supercode;
+    if (!session) {
+      if (row.worker_pid) return { qualified: false, reason: `run ${row.id}'s worker has no confirmed stop receipt` };
+      continue;
+    }
+    if (session.close_transferred_to) {
+      const successor = db.prepare('SELECT task_id,metadata FROM task_runs WHERE id=?').get(session.close_transferred_to);
+      const next = parse(successor?.metadata)?.supercode;
+      if (next && next.machine === session.machine && ((next.session_id && next.session_id === session.session_id) || (next.pane && next.pane === session.pane))) continue;
+      return { qualified: false, reason: `run ${row.id}'s execution transfer has no matching successor` };
+    }
+    const address = session.address ?? (session.machine && session.session_id ? `sc:${session.machine}:${session.harness ?? 'claude-code'}:${session.session_id}` : null);
+    if (session.detached_at || (address && custody.has(address))) continue;
+    if (session.close_confirmed_at) continue; // includes an adopted session's explicit release receipt
+    if (session.pane || session.launch_key || session.session_id || session.pid || session.launch_pending || row.worker_pid) return {
+      qualified: false, reason: `run ${row.id}'s ${session.slot ?? 'worker'} execution has no confirmed close/release receipt; unknown liveness is not absence`,
+    };
+  }
+  return { qualified: true, reason: null };
+}
+
+/** Importers call this after staging rows, before publication or dispatch can observe them. */
+export function assertBacklogQualified(db, id, { backlog, source = 'backlog' } = {}) {
+  if (backlog == null) return;
+  if (!backlog || typeof backlog !== 'object' || Array.isArray(backlog) || typeof backlog.by !== 'string' || !backlog.by.trim() || typeof backlog.reason !== 'string' || !backlog.reason.trim()
+      || Object.keys(backlog).some(key => !['by', 'reason', 'since'].includes(key))
+      || !Number.isSafeInteger(backlog.since) || backlog.since < 0) throw new Error(`${id}: ${source} has malformed backlog attribution`);
+  const result = backlogQualification(db, id);
+  if (!result.qualified) throw new Error(`${id}: ${source} refused: ${result.reason}`);
+}

package/board/runtime-door.mjs

@@ -1,4 +1,4 @@
-// A machine's public door (`harness.v1.*`), called in this process through the held channel to its daemon (doors.mjs):
+// A machine's public doors (`harness.v1.*`, or `files.stat` for physical sources), called through the held channel to its daemon (doors.mjs):
 // no helper process, nothing that waits on this process's event loop. Answered as the helper it replaces answered,
 // `{code, stdout, stderr}`, so a caller reads a door's refusal as it always did.
 import { machineCall } from './doors.mjs';
@@ -11,7 +11,7 @@ import { machineCall } from './doors.mjs';
  */
 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' });
+    if (!method.startsWith('harness.v1.') && method !== 'files.stat') throw Object.assign(new Error('the runtime door accepts harness.v1 methods or files.stat'), { code: 'invalid_request' });
     const acting = as && !method.startsWith('harness.v1.sessions.');
     const named = !acting ? params
       : machine ? { ...params, caller: as }

package/board/session-continuity.mjs

@@ -0,0 +1,127 @@
+// An established role slot is continued unless a retained deliberate act authorizes its successor (ADR 0248).
+// Authorization lives with the old execution references, not in a second scheduling database.
+import { randomUUID } from 'node:crypto';
+import { actorOf, event, json, now, runField } from './store.mjs';
+
+const slotSql = () => `COALESCE(${runField('slot')},'worker')`;
+const identified = () => `(${runField('session_id')} IS NOT NULL OR ${runField('launch_key')} IS NOT NULL OR ${runField('pid')} IS NOT NULL OR ${runField('pane')} IS NOT NULL)
+  AND NOT (COALESCE(${runField('launch_not_issued')},0)=1 AND ${runField('mode')}='fresh' AND ${runField('close_confirmed_at')} IS NOT NULL)`;
+export const slotGeneration = (session, run) => session?.slot_generation
+  ?? `${session?.harness ?? 'claude-code'}:${session?.session_id ?? session?.launch_key ?? `run-${run}`}`;
+
+/** The latest execution reference, including launches whose native id was never returned. */
+export function establishedSlot(db, task, slot = 'worker', beforeRun = null) {
+  const row = db.prepare(`SELECT id,metadata FROM task_runs WHERE task_id=? AND ${slotSql()}=? AND ${identified()}
+    ${beforeRun == null ? '' : 'AND id<?'} ORDER BY id DESC LIMIT 1`).get(task, slot, ...(beforeRun == null ? [] : [beforeRun]));
+  if (!row) return null;
+  const session = json(row.metadata, {})?.supercode;
+  return { run: row.id, session, generation: slotGeneration(session, row.id) };
+}
+
+/** Called only by an admitted workflow action or an authenticated assignment-change receipt. */
+export function authorizeReplacement(db, task, slot, { source, target, reason = null }, beforeRun = null) {
+  const prior = establishedSlot(db, task, slot, beforeRun);
+  if (!prior) return null;
+  const existing = prior.session.replacement_authorization;
+  if (existing?.source?.id != null && existing.source.id === source.id
+    && existing.generation === prior.generation && JSON.stringify(existing.target) === JSON.stringify(target)) return existing;
+  const authorization = { id: randomUUID(), slot, generation: prior.generation, prior_run: prior.run,
+    prior_session: prior.session.session_id ?? null, prior_agent: prior.session.agent_id ?? null,
+    source, target, reason, by: actorOf(), at: now(), issued: null };
+  authorization.event = event(db, task, 'session_replacement_authorized', authorization);
+  for (const row of db.prepare(`SELECT id,metadata FROM task_runs WHERE task_id=? AND ${slotSql()}=? AND ${identified()}
+    ${beforeRun == null ? '' : 'AND id<?'}`).all(task, slot, ...(beforeRun == null ? [] : [beforeRun]))) {
+    const whole = json(row.metadata, {});
+    whole.supercode = { ...whole.supercode, replacement_authorization: authorization };
+    db.prepare('UPDATE task_runs SET metadata=? WHERE id=?').run(JSON.stringify(whole), row.id);
+  }
+  return authorization;
+}
+
+export function continuationRefusal(prior, why) {
+  const session = prior?.session?.session_id ?? prior?.session?.launch_key ?? `run ${prior?.run}`;
+  const error = new Error(`session ${session} (${prior?.session?.slot ?? 'worker'}) could not be continued: ${why}. A retained deliberate manager decision is required before creating a fresh conversation`);
+  error.resumeFailed = { session_id: prior?.session?.session_id ?? null, slot: prior?.session?.slot ?? 'worker', why };
+  error.continuationRequired = true;
+  return error;
+}
+
+/** An old forgotten marker alone grants nothing. Recheck the current intended configuration on every use. */
+export function replacementFor(db, task, slot, { harness, cardMachine, agent = undefined, assignment = null, beforeRun = null } = {}) {
+  const prior = establishedSlot(db, task, slot, beforeRun);
+  const authorization = prior?.session?.replacement_authorization;
+  if (!authorization || authorization.generation !== prior.generation) return { prior, authorization: null };
+  const target = authorization.target ?? {};
+  if (target.harness != null && target.harness !== harness) return { prior, authorization: null };
+  if (Object.hasOwn(target, 'machine') && (target.machine ?? null) !== (cardMachine ?? null)) return { prior, authorization: null };
+  if (agent !== undefined && target.agent != null && target.agent !== agent) return { prior, authorization: null };
+  if (target.assignment != null && (!assignment || assignment.id !== target.assignment || assignment.agent_id !== target.agent
+    || assignment.state !== 'active')) return { prior, authorization: null };
+  if (target.assignment_event != null) {
+    const latest = db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='agent_assignment_reassigned' AND json_extract(payload,'$.assignment')=? ORDER BY id DESC LIMIT 1").get(task, target.assignment);
+    if (latest?.id !== target.assignment_event) return { prior, authorization: null };
+  }
+  // An issued authorization is never reinterpreted as permission for the next run.
+  if (authorization.issued && authorization.issued.run !== beforeRun) return { prior, authorization: null };
+  return { prior, authorization };
+}
+
+/** Commit before the launch door. A retry may recover this one key, never choose another conversation. */
+export function issueReplacement(db, task, slot, authorization, { run, key, session, harness, cardMachine, agent, assignment }) {
+  const current = replacementFor(db, task, slot, { harness, cardMachine, agent, assignment, beforeRun: run });
+  if (!current.authorization || current.authorization.id !== authorization.id) throw continuationRefusal(current.prior, 'the replacement decision changed before issuance');
+  const issued = current.authorization.issued;
+  if (issued && (issued.key !== key || issued.session !== session)) throw continuationRefusal(current.prior, 'this replacement decision already issued a different launch');
+  if (issued) return issued;
+  const next = { ...current.authorization, issued: { run, key, session, at: now() } };
+  for (const row of db.prepare(`SELECT id,metadata FROM task_runs WHERE task_id=? AND ${slotSql()}=? AND id<?`).all(task, slot, run)) {
+    const whole = json(row.metadata, {});
+    if (whole.supercode?.replacement_authorization?.id !== authorization.id) continue;
+    whole.supercode.replacement_authorization = next;
+    db.prepare('UPDATE task_runs SET metadata=? WHERE id=?').run(JSON.stringify(whole), row.id);
+  }
+  event(db, task, 'session_replacement_issued', { authorization: authorization.id, source: authorization.source, ...next.issued }, run);
+  return next.issued;
+}
+
+/** A close the machine refused for good (not deferred): the board will not try it again, and the session runs on. */
+export const closeRefused = (s) => Boolean(s?.close_failed_at && s.close_error && !/^close deferred/.test(s.close_error) && !s.close_confirmed_at);
+
+/** No previous board-owned process may survive beside a replacement; adopted references release rather than close.
+ *  A close under way is waited for (deferred, retried next round); only one never requested, or refused for good, refuses. */
+export function requireReplacementTeardown(db, task, slot, run) {
+  for (const row of db.prepare(`SELECT id,metadata FROM task_runs WHERE task_id=? AND ${slotSql()}=? AND id<? AND ${identified()}`).all(task, slot, run)) {
+    const session = json(row.metadata, {})?.supercode;
+    if (session?.close_confirmed_at || session?.close_transferred_to) continue;
+    if (session?.close_requested && !closeRefused(session))
+      throw Object.assign(new Error(`run ${row.id}'s execution is still closing; its close must be confirmed before its replacement starts`), { launchDeferred: true });
+    throw continuationRefusal({ run: row.id, session }, 'its previous execution has no confirmed close or release');
+  }
+}
+
+/** Consume an assignment owner's durable manager decision. Automatic identity generations carry no such decision. */
+export function authorizeAgentHandoff(db, task, change, sourceEvent, assignment, requestClose) {
+  if (change.decision?.kind !== 'reassign_agent' || change.from === change.to || !assignment
+    || assignment.agent_id !== change.to || assignment.state !== 'active' || assignment.id !== change.assignment) return;
+  const fallback = { implementer: 'worker', reviewer: 'reviewer', auditor: 'auditor' }[change.role] ?? change.role;
+  const slots = db.prepare(`SELECT DISTINCT ${slotSql()} AS slot FROM task_runs WHERE task_id=?
+    AND COALESCE(${runField('role')},CASE ${slotSql()} WHEN 'worker' THEN 'implementer' ELSE ${slotSql()} END)=?
+    AND ${identified()}`).all(task, change.role).map(row => row.slot);
+  if (!slots.length) slots.push(fallback);
+  const machine = db.prepare('SELECT machine FROM supercode_cards WHERE task_id=?').get(task)?.machine ?? null;
+  for (const slot of slots) {
+    const previous = establishedSlot(db, task, slot);
+    if (!previous) continue;
+    const authorization = authorizeReplacement(db, task, slot, { source: { kind: 'reassign_agent', id: sourceEvent, receipt: change.receipt },
+      target: { harness: previous.session.harness ?? 'claude-code', machine, agent: change.to, assignment: change.assignment,
+        assignment_event: sourceEvent }, reason: `role reassigned from ${change.from} to ${change.to}` });
+    for (const row of db.prepare(`SELECT id,metadata FROM task_runs WHERE task_id=? AND ${slotSql()}=? AND ${identified()}`).all(task, slot)) {
+      requestClose(db, task, { runId: row.id });
+      const whole = json(db.prepare('SELECT metadata FROM task_runs WHERE id=?').get(row.id)?.metadata, {});
+      whole.supercode = { ...whole.supercode, forgotten: now(), resumable: false, replacement_authorization: authorization };
+      db.prepare("UPDATE task_runs SET metadata=?,ended_at=COALESCE(ended_at,?),status=CASE WHEN ended_at IS NULL THEN 'reconfigured' ELSE status END,outcome=CASE WHEN ended_at IS NULL THEN 'reconfigured' ELSE outcome END,claim_lock=NULL,claim_expires=NULL,worker_pid=NULL WHERE id=?").run(JSON.stringify(whole), now(), row.id);
+      db.prepare('UPDATE tasks SET current_run_id=NULL,claim_lock=NULL,claim_expires=NULL,worker_pid=NULL WHERE id=? AND current_run_id=?').run(task, row.id);
+    }
+    event(db, task, 'dispatch_released', { reason: 'deliberate role owner reassignment', source: sourceEvent, authorization: authorization.id });
+  }
+}

package/board/session-work.mjs

@@ -1,5 +1,6 @@
 // The dispatcher observes native turns and explicit session delegation. A
 // transcript write, a reminder reply, or sharing a profile proves no progress.
+import { dispatchWait } from './queries.mjs';
 
 const parsed = (value) => {
   if (typeof value !== 'string') return value ?? null;
@@ -7,6 +8,11 @@ const parsed = (value) => {
 };
 const iso = (seconds) => Number(seconds) > 0 ? `${new Date(Number(seconds) * 1000).toISOString().slice(0, 16)}Z` : null;
 const oneLine = (text, max = 200) => String(text ?? '').trim().split('\n')[0].slice(0, max);
+/** How long a session's presence reading stays current after it was observed: the dispatcher renews an unchanged
+ *  reading once a minute (dispatch.mjs supervise), so one older than this was not renewed by a running dispatcher. */
+export const PRESENCE_FRESH_SECONDS = 90;
+/** Whether a presence reading (`{ observed_at }`, in seconds) is still current at `now` (in seconds). */
+export const presenceFresh = (reading, now = Date.now() / 1000) => now <= Number(reading?.observed_at) + PRESENCE_FRESH_SECONDS;
 
 /**
  * A retained reading of the card's session, beside the card's workflow lane and apart from its launch receipt (ADR 0024).
@@ -15,13 +21,14 @@ const oneLine = (text, max = 200) => String(text ?? '').trim().split('\n')[0].sl
  * heartbeat `--until`), waiting on its user, or idle since a time. An ended attempt is never a live session; an unread
  * live attempt is unknown.
  * `heartbeat` is the current run's latest heartbeat event on the card ({ payload: { note, until }, at, run_id }) beside the
- * run's own, `last` its latest run when it has no current one; both are optional (readingContext reads them).
+ * run's own, `last` its latest run when it has no current one, and `queue` the dispatcher's applicable wait
+ * ({ reason, at }); each is optional (readingContext reads them).
  */
-export function executionOf(run, { heartbeat = null, last = null } = {}) {
+export function executionOf(run, { heartbeat = null, last = null, queue = null, now = Date.now() / 1000 } = {}) {
   if (!run) {
     const ended = last?.ended_at != null ? last : null;
-    return { state: 'awaiting_session', alive: false, observed_at: null, since: ended ? Number(ended.ended_at) : null,
-      reason: ended ? `no session works it; its last run ended${ended.outcome ?? ended.status ? ` (${ended.outcome ?? ended.status})` : ''} at ${iso(ended.ended_at)}${ended.error ? `: ${oneLine(ended.error)}` : ''}`
+    return { state: 'awaiting_session', alive: false, observed_at: null, since: queue?.reason ? Number(queue.at) : ended ? Number(ended.ended_at) : null,
+      reason: queue?.reason ? oneLine(queue.reason, 300) : ended ? `no session works it; its last run ended${ended.outcome ?? ended.status ? ` (${ended.outcome ?? ended.status})` : ''} at ${iso(ended.ended_at)}${ended.error ? `: ${oneLine(ended.error)}` : ''}`
         : 'no session works it' };
   }
   const session = parsed(run.metadata)?.supercode;
@@ -31,12 +38,17 @@ export function executionOf(run, { heartbeat = null, last = null } = {}) {
     return { state: 'ended', alive: false, observed_at: session?.presence_observation?.observed_at ?? null, since: at == null ? null : Number(at),
       reason: `its session ended${at ? ` at ${iso(at)}` : ''}` };
   }
+  if (session?.launch_deferred && !session.session_id && !session.pane && !session.pid && !session.launch_key) {
+    return { state: 'awaiting_session', alive: false, observed_at: null, since: Number(session.launched_at ?? run.started_at) || null,
+      reason: session.launch_deferred_error ? oneLine(session.launch_deferred_error, 300) : 'its launch is deferred' };
+  }
   const reading = session?.presence_observation;
   if (!reading) return { state: 'unknown', alive: null, observed_at: null, reason: 'the board has not read its session yet' };
-  const freshUntil = Number(reading.observed_at) + 90;
+  const freshUntil = Number(reading.observed_at) + PRESENCE_FRESH_SECONDS;
   // A stopped dispatcher cannot keep advertising its last reading, its machine wait included: every round renews the
-  // observation (supervise), so one older than its freshness is unknown. Cached snapshot consumers use the same expiry.
-  if (Date.now() / 1000 > freshUntil) return { state: 'unknown', alive: null, observed_at: reading.observed_at, fresh_until: freshUntil,
+  // observation (supervise), so one older than its freshness is unknown. A card's published snapshot carries neither
+  // time (published.mjs publishedExecution); the reading's time and freshness are the board's own doors' (listing.mjs).
+  if (!presenceFresh(reading, now)) return { state: 'unknown', alive: null, observed_at: reading.observed_at, fresh_until: freshUntil,
     reason: `the board has not read its session since ${iso(reading.observed_at)}` };
   const read = { ...reading, fresh_until: freshUntil };
   // the run's machine wait: the board read the session's machine as unlinked from the team (supervise, machine_offline)
@@ -66,7 +78,7 @@ export function executionOf(run, { heartbeat = null, last = null } = {}) {
   const card = heartbeat && run.id != null && heartbeat.run_id != null && Number(heartbeat.run_id) === Number(run.id) ? heartbeat : null;
   const beat = own && !(Number(card?.at) > Number(own.at)) ? own : card;
   const wait = parsed(beat?.payload);
-  if (Number(wait?.until) > Date.now() / 1000) {
+  if (Number(wait?.until) > now) {
     return { ...read, state: 'waiting', until: Number(wait.until), since: Number(beat.at) || null,
       reason: `waiting until ${iso(wait.until)}${wait.note ? `: ${oneLine(wait.note)}` : ''}` };
   }
@@ -79,15 +91,15 @@ export function executionOf(run, { heartbeat = null, last = null } = {}) {
     reason: reading.turn ? null : `its session's turn is not known${unknownSince ? ` since ${iso(unknownSince)}` : ''}` };
 }
 
-/** What executionOf reads beside a card's current run, for a card in a working lane (running or review) only, as the
- * listing reads it (listing.mjs READING_CONTEXT): the current run's latest heartbeat event, and the latest run when
- * none is current. Any other lane reads none. */
+/** What executionOf reads beside a card's current run, as the listing reads it (listing.mjs READING_CONTEXT): the
+ * dispatcher's wait when none is current, and in a working lane the latest heartbeat and run. */
 export function readingContext(db, taskId, currentRunId) {
+  const queue = currentRunId ? null : dispatchWait(db, taskId);
   const lane = db.prepare('SELECT COALESCE(c.stage,t.status) AS lane FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(taskId)?.lane;
-  if (!['running', 'review'].includes(lane)) return { heartbeat: null, last: null };
+  if (!['running', 'review'].includes(lane)) return { heartbeat: null, last: null, queue };
   const heartbeat = currentRunId ? db.prepare("SELECT payload,created_at AS at,run_id FROM task_events WHERE task_id=? AND kind='heartbeat' AND run_id=? ORDER BY id DESC LIMIT 1").get(taskId, currentRunId) ?? null : null;
   const last = currentRunId ? null : db.prepare('SELECT status,outcome,ended_at,error FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(taskId) ?? null;
-  return { heartbeat, last };
+  return { heartbeat, last, queue };
 }
 
 /** Sessions this session started, transitively. Cycles never imply work. */

package/board/standalone-declaration.mjs

@@ -0,0 +1,24 @@
+// A standalone home's command routing follows its committed native generation. Kits keep their own declaration.
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readSourceLock, enforceSourceLock } from '@volter/supercode-teams/source-lock';
+import { readSourceRecord, saveSourceRecord, sourceProgramBinding } from '@volter/supercode-teams/source-selection';
+
+export function publishStandaloneDeclaration(root, selected, env = process.env) {
+  if (!selected?.candidate || existsSync(join(root, 'running-kit.json'))) return;
+  // A generation's scoped candidate may be activated before source commit. Only the primary selection may change
+  // the durable command route; the same reading repairs a committed route after its owner restarts.
+  const primaryEnv = { ...env };
+  delete primaryEnv.SUPERCODE_SOURCE_CANDIDATE;
+  const primary = readSourceLock(primaryEnv);
+  if (!primary || realpathSync(selected.entry) !== realpathSync(join(primary.root, 'sdk/orchestrator/bin/orchestrator.mjs'))
+    || realpathSync(selected.native) !== sourceProgramBinding(primary).program) return;
+  enforceSourceLock(selected.entry, 'the standalone board declaration', primaryEnv);
+  enforceSourceLock(selected.native, 'the standalone board program', primaryEnv);
+  const path = join(root, 'orchestrator.json');
+  const held = existsSync(path) ? readSourceRecord(path) : {};
+  if (held.entry === selected.entry && held.supercode?.entry === selected.native) return;
+  const version = entry => readSourceRecord(join(dirname(entry), '..', 'package.json')).version ?? null;
+  saveSourceRecord(path, { ...held, package: '@volter/supercode-orchestrator', version: version(selected.entry),
+    entry: selected.entry, supercode: { ...held.supercode, entry: selected.native, version: version(selected.native) } });
+}