@volter/supercode-orchestrator 0.5.204 → 0.5.206

package/board/fleet-observer.mjs

@@ -0,0 +1,79 @@
+// A board owner's read side over admitted, committed machine records. The machine emits facts; this home supplies
+// role intent and its own card associations. No actor identity or authority is inferred from an observed payload.
+import { listBoards, openBoard, view } from './store.mjs';
+
+/** Associations in this home's current runs, observed when a notice is retained. Other homes' cards are unknown. */
+export function fleetCards(root, addresses) {
+  const cards = [];
+  for (const slug of listBoards(root)) {
+    const board = openBoard(root, slug);
+    try {
+      for (const address of addresses) {
+        const [, machine, harness, sessionId] = address.split(':');
+        const rows = view(board, db => db.prepare(`SELECT t.id,r.id AS run FROM tasks t JOIN task_runs r ON r.id=t.current_run_id
+          WHERE json_extract(r.metadata,'$.supercode.machine')=? AND json_extract(r.metadata,'$.supercode.harness')=?
+          AND json_extract(r.metadata,'$.supercode.session_id')=? LIMIT 65`).all(machine, harness, sessionId));
+        if (rows.length > 64 || cards.length + rows.length > 256) throw new Error('fleet card associations exceed the retained notice bound');
+        cards.push(...rows.map(row => ({ board: slug, card: row.id, run: row.run, address })));
+      }
+    } finally { board.close(); }
+  }
+  return cards;
+}
+
+export function enrichFleetEvent(root, event) {
+  if (event.card_associations) return event;
+  const addresses = [...new Set([event.session?.address, event.address, ...(event.sessions ?? []).map(row => row.address)].filter(Boolean))];
+  if (!addresses.length) return event;
+  let cards = null, unread = null;
+  try { cards = fleetCards(root, addresses); } catch (error) { unread = String(error.message).slice(0, 300); }
+  return { ...event, card_associations: { observed_at_ms: Date.now(), basis: 'current native session bindings in this owner home', cards, ...(unread ? { unread } : {}), other_homes: 'unknown' } };
+}
+
+export function observeRoleFleet(root, router, records, log = () => {}, { waiting = true } = {}) {
+  if (!router.enabled) return;
+  for (const [machine, held] of Object.entries(records ?? {})) {
+    if (!['self', 'open'].includes(held.stream) || !held.record) continue;
+    const record = held.record;
+    for (const [section, prefix, kinds] of [
+      ['fleet', 'machine-fleet', ['session_started', 'session_resumed', 'session_ended', 'duplicate_session_process']],
+      ['health_events', 'machine-health', ['machine_health_crit']],
+    ]) if (record[section] && !record.unread?.[section]) {
+      try {
+        const source = record[section];
+        if (typeof source.source !== 'string' || !source.source.startsWith(`${prefix}:${machine}:`)) throw new Error('fleet source is not scoped to its admitted machine and grant section');
+        if (source.events.some(event => event.machine !== machine || !kinds.includes(event.kind))) throw new Error('fleet event differs from its admitted machine or grant section');
+        router.follow(source);
+      } catch (error) { log(`fleet listener source ${machine}: ${String(error.message).slice(0, 300)}`); }
+    }
+    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
+      || 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 ?? []) {
+      if (activity?.presence !== 'running' || !activity.harness || !activity.session_id
+        || !(record.panes.panes ?? []).some(pane => pane.pid === pid && !pane.dead)) continue;
+      const address = `sc:${machine}:${activity.harness}:${activity.session_id}`;
+      const rows = grouped.get(address) ?? []; rows.push(activity); grouped.set(address, rows);
+    }
+    for (const [address, activities] of grouped) {
+      try {
+        const asked = activities.find(activity => activity.turn === 'needs_input');
+        if (!asked) {
+          if (activities.every(activity => ['idle', 'working'].includes(activity.turn))) router.cardWait(address, null);
+          continue;
+        }
+        const cards = fleetCards(root, [address]);
+        if (!cards.length) continue;
+        const evidence = asked.evidence ?? {};
+        router.cardWait(address, { kind: 'card_waiting_on_user', machine,
+          observed_at_ms: Number.isSafeInteger(evidence.observed_at_ms) ? evidence.observed_at_ms : record.at,
+          address, harness: asked.harness, session_id: asked.session_id, waiting_for: evidence.waiting_for ?? null,
+          since_ms: evidence.native_state_since_ms ?? null, native_state: evidence.native_state ?? null, native_source: evidence.source ?? null,
+          card_associations: { observed_at_ms: Date.now(), basis: 'current native session bindings in this owner home', cards, other_homes: 'unknown' } });
+      } catch (error) { log(`fleet listener card wait ${address}: ${String(error.message).slice(0, 300)}`); }
+    }
+  }
+}

package/board/fleet-targets.mjs

@@ -0,0 +1,82 @@
+// The machine universe must be complete before a fleet reading can decide presence.
+// Bound candidates before applying live/platform predicates: an all-inactive board still yields.
+import { setImmediate as nextTurn } from 'node:timers/promises';
+import { listBoards, openBoard } from './store.mjs';
+import { LIST_BATCH, TASK_SUMMARY_INDEX, listRevision } from './listing.mjs';
+
+const sameRevision = (a, b) => Object.keys(a).every(key => a[key] === b[key]);
+const rowPage = (db, table, fields, ceiling, after) => db.prepare(`SELECT rowid AS candidate_id, ${fields} FROM ${table}
+  WHERE rowid <= ?${after === null ? '' : ' AND rowid > ?'} ORDER BY rowid LIMIT ${LIST_BATCH}`)
+  .all(ceiling, ...(after === null ? [] : [after]));
+
+async function addBoardMachines(board, machines, normalise, unchanged) {
+  const db = board.db;
+  // Card rowids are indexed even in a TEMP document overlay, where supercode_cards has no task-id index.
+  // Tasks have the listing's covering ID index in both main and TEMP projections.
+  const ceiling = db.prepare('SELECT MAX(rowid) AS id FROM supercode_cards').get().id;
+  const liveCards = new Set();
+  let cursor = null;
+  while (ceiling !== null && (cursor === null || cursor < ceiling)) {
+    if (!unchanged()) return false;
+    const rows = rowPage(db, 'supercode_cards', 'task_id, machine, NOT COALESCE(archived, 0) AS visible', ceiling, cursor);
+    if (!rows.length) break;
+    const active = new Set(db.prepare(`SELECT id FROM tasks INDEXED BY ${TASK_SUMMARY_INDEX}
+      WHERE id IN (SELECT value FROM json_each(?)) AND status NOT IN ('done', 'cancelled', 'archived')`)
+      .all(JSON.stringify(rows.map(row => row.task_id))).map(row => row.id));
+    for (const row of rows) {
+      if (!row.visible || !active.has(row.task_id)) continue;
+      liveCards.add(row.task_id);
+      if (row.machine !== null && row.machine !== '') machines.add(normalise(row.machine));
+    }
+    cursor = rows.at(-1).candidate_id;
+    await nextTurn();
+  }
+  if (!unchanged()) return false;
+  // Subscriptions have an ordinary SQLite rowid in every board backing. Page all rows before filtering,
+  // rather than paging matching subscriptions with an unbounded search through nonmatching rows.
+  const last = db.prepare('SELECT MAX(rowid) AS id FROM kanban_notify_subs').get().id;
+  let after = null;
+  while (last !== null && (after === null || after < last)) {
+    if (!unchanged()) return false;
+    const rows = rowPage(db, 'kanban_notify_subs', "task_id, chat_id, platform = 'supercode' AND chat_id LIKE 'sc:%' AS supercode_address", last, after);
+    if (!rows.length) break;
+    for (const row of rows) {
+      if (liveCards.has(row.task_id) && row.supercode_address) machines.add(normalise(row.chat_id.split(':')[1]));
+    }
+    after = rows.at(-1).candidate_id;
+    await nextTurn();
+  }
+  return unchanged();
+}
+
+/** A stable union across all boards; no read transaction or native cursor survives a yield. */
+export async function homeFleetMachines(root, normalise) {
+  if (!root) return new Set();
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const slugs = listBoards(root).sort(), opened = [];
+      try {
+        for (const slug of slugs) {
+          const board = openBoard(root, slug);
+          const held = { board };
+          opened.push(held);
+          held.revision = listRevision(board.db);
+        }
+        const unchanged = () => opened.every(({ board, revision }) => sameRevision(revision, listRevision(board.db)));
+        const machines = new Set();
+        let stable = true;
+        for (const { board } of opened) {
+          if (!await addBoardMachines(board, machines, normalise, unchanged)) { stable = false; break; }
+          await nextTurn();
+        }
+        if (stable && unchanged() && JSON.stringify(slugs) === JSON.stringify(listBoards(root).sort())) return machines;
+      } finally { for (const { board } of opened) board.close(); }
+      await nextTurn();
+    }
+    throw new Error('The home changed during its fleet-target reading; retry the reading.');
+  } catch (error) {
+    // Do not pass an incomplete machine set to readMachineFleet, or publish presence from it.
+    error.fleetTargetsUnread = true;
+    throw error;
+  }
+}

package/board/incidents.mjs

@@ -1,5 +1,6 @@
 // Service supervision retains evidence; only a manager/creator act releases dispatch.
 import { event, json, now } from './store.mjs';
+import { detachedCard, detachedSession } from './custody.mjs';
 import { statusOf, creatorOf, requestSessionClose } from './workflow.mjs';
 
 export const recoversRuns = entry => entry?.params?.run_failure_policy === 'recover';
@@ -19,6 +20,7 @@ export function retainRecovery(db, id, name, evidence = {}, runId = null) {
   if (!row || row.ended_at != null) return;
   if (db.prepare("SELECT 1 FROM task_events WHERE task_id=? AND run_id=? AND kind='run_incident'").get(id, runId)) return;
   const session = json(row.metadata, {})?.supercode ?? {};
+  if (detachedCard(db, id) || detachedSession(db, session)) return;
   const reason = evidence.error ?? `run ${runId} needs continuation (${name})`;
   const payload = { observation: name, run: runId, reason, policy: 'recover',
     session: session.session_id ?? null, machine: session.machine ?? null, pane: session.pane ?? null,
@@ -35,6 +37,7 @@ export function surfaceIncident(db, board, entry, id, name, evidence = {}, runId
   const row = db.prepare('SELECT * FROM task_runs WHERE id=?').get(runId);
   if (!row || row.task_id !== id) return false;
   const meta = json(row.metadata, {}) ?? {}, session = meta.supercode ?? {};
+  if (detachedCard(db, id) || detachedSession(db, session)) return false;
   const prior = db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='run_incident' AND run_id=? ORDER BY id DESC LIMIT 1").get(id,runId);
   const continued = db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='session_continued' AND run_id=? ORDER BY id DESC LIMIT 1").get(id,runId);
   if (prior && !(continued?.id > prior.id)) return false;
@@ -69,6 +72,7 @@ export function auditEndedRuns(db, board, entry) {
       WHERE r.id=(SELECT MAX(id) FROM task_runs WHERE task_id=t.id) AND r.ended_at IS NOT NULL
       AND t.current_run_id IS NULL AND t.status NOT IN ('done','cancelled','archived')`).all()) {
       const metadata = json(row.metadata, {}), session = metadata.supercode;
+      if (detachedSession(db, session)) continue;
       if (session?.mode !== 'resume' || session.seen_at || session.resume_failed_before_live) continue;
       const exit = db.prepare("SELECT 1 FROM task_events WHERE run_id=? AND kind='run_incident' AND json_extract(payload,'$.observation')='exited' AND json_extract(payload,'$.evidence.code')=1").get(row.id);
       if (!exit) continue;
@@ -80,6 +84,7 @@ export function auditEndedRuns(db, board, entry) {
     for (const task of db.prepare(`SELECT t.id,c.paused FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
       WHERE t.current_run_id IS NULL AND t.status NOT IN ('done','cancelled','archived') AND c.paused IS NOT NULL AND NOT COALESCE(c.archived,0)`).all()) {
       const pause = json(task.paused, null);
+      if (detachedCard(db, task.id)) continue;
       const last = db.prepare("SELECT kind,payload FROM task_events WHERE task_id=? AND kind IN ('closed_by_hand','paused','resumed') ORDER BY id DESC LIMIT 1").get(task.id);
       const ended = json(last?.payload, {});
       // The machine may have moved since this run. Match the retained board
@@ -95,6 +100,7 @@ export function auditEndedRuns(db, board, entry) {
       ON r.id=(SELECT MAX(id) FROM task_runs WHERE task_id=t.id)
       WHERE t.current_run_id IS NULL AND r.ended_at IS NOT NULL AND t.status IN ('running','review')`).all()) {
       const session = json(task.run_metadata, {})?.supercode;
+      if (detachedCard(db, task.id) || detachedSession(db, session)) continue;
       if (!session?.monitor_held) continue;
       const state = db.prepare('SELECT paused,blocked_by,archived FROM supercode_cards WHERE task_id=?').get(task.id);
       if (json(state?.paused, null) || json(state?.blocked_by, [])?.length || state?.archived) continue;
@@ -110,6 +116,7 @@ export function auditEndedRuns(db, board, entry) {
   for (const task of db.prepare(`SELECT t.*,r.id run_id,r.outcome,r.error,r.metadata run_metadata FROM tasks t JOIN task_runs r ON r.id=(SELECT MAX(id) FROM task_runs WHERE task_id=t.id)
     WHERE t.current_run_id IS NULL AND r.ended_at IS NOT NULL AND t.status NOT IN ('done','archived')`).all()) {
     const session = json(task.run_metadata, {})?.supercode;
+    if (detachedCard(db, task.id) || detachedSession(db, session)) continue;
     const status = statusOf(db, task);
     if (session?.status && session.status !== status) continue; // a card transition intentionally advances its work
     const incident = db.prepare("SELECT id FROM task_events WHERE task_id=? AND run_id=? AND kind='run_incident'").get(task.id, task.run_id);

package/board/listing.mjs

@@ -5,6 +5,11 @@ import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { executionOf } from './session-work.mjs';
 
 export const LIST_BATCH = 64;
+// A listing on the owner's read door (owner-door.mjs) that can read no committed state without waiting on a writer (a
+// backing with no commit point a reader can take, a store not in WAL, SQLite's own contention) is answered by the
+// owner, as every other verb is.
+export const READ_BY_OWNER = 'board_read_by_owner';
+export const byOwner = (reason) => Object.assign(new Error(`this listing is the board owner's to answer: ${reason}`), { code: READ_BY_OWNER });
 export const LIST_CONNECTION = Symbol.for('supercode.board.listing.connection');
 export const LIST_REVISION = Symbol.for('supercode.board.listing.revision');
 const parse = (text, fallback) => { try { return JSON.parse(text) ?? fallback; } catch { return fallback; } };

package/board/machine-fleet.mjs

@@ -25,11 +25,14 @@ const paneFacts = (held) => {
   ]);
 };
 const paneListeners = new Set();
+const recordListeners = new Set();
+recordView.onUnavailable = () => { for (const listener of recordListeners) { try { listener({}); } catch { /* cursor retained for a current reading */ } } };
 let factsHeld = new Map();
 recordView.onApplied = (records) => {
   const next = new Map(Object.entries(records).map(([machine, held]) => [machine, paneFacts(held)]));
   const changed = [...next].filter(([machine, facts]) => factsHeld.has(machine) && factsHeld.get(machine) !== facts).map(([machine]) => machine);
   factsHeld = next;
+  for (const listener of recordListeners) { try { listener(records); } catch { /* its retained source cursor is retried */ } }
   if (changed.length) for (const listener of paneListeners) { try { listener(changed); } catch { /* a listener cannot stop the record's reading */ } }
 };
 /**
@@ -38,6 +41,10 @@ recordView.onApplied = (records) => {
  * opened by a round's first reading and held from then on.
  */
 export function onPanesChanged(listener) { paneListeners.add(listener); return () => paneListeners.delete(listener); }
+/** The admitted, committed records, including native turn/health changes which need not change a pane. */
+export function onRecordsChanged(listener) { recordListeners.add(listener); return () => recordListeners.delete(listener); }
+export async function readFleetRecords() { return recordView.read(DEADLINE_MS); }
+export function fleetRecordsCurrent() { return Boolean(recordView.ready && recordView.stream && Date.now() - recordView.heardAt <= 45_000); }
 const DEADLINE_MS = 10_000;
 const within = (promise, ms) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error(`no answer within ${ms} ms`), { code: 'timeout' })), ms).unref?.())]);
 // One machine's reading, from its held record: its panes, what a board launch needs of it, and the session under each

package/board/notice-receipts.mjs

@@ -0,0 +1,67 @@
+// Locate filed/bounced notices outside the writer, without an unscoped JSON payload scan per expiry.
+import { setImmediate as nextTurn } from 'node:timers/promises';
+import { listRevision, LIST_BATCH } from './listing.mjs';
+
+const FILED = new Set(['notice_filed', 'session_notice_filed', 'actor_notice_filed']);
+const KINDS = "('notice_filed', 'session_notice_filed', 'actor_notice_filed', 'notice_bounced')";
+const same = (a, b, ownWrites = false) => Object.keys(a).every(key => (ownWrites && key === 'changes') || a[key] === b[key]);
+export const noticeKey = (taskId, messageId) => JSON.stringify([taskId, messageId]);
+const unread = () => Object.assign(new Error('Notice receipts changed during their reading; bounced notices will be retried next round.'), { code: 'board_notice_receipts_unread' });
+
+/** Check inside the write before any mutation. After our own synchronous write, only total_changes may differ. */
+export function requireNoticeBasis(board, revision, { ownWrites = false } = {}) {
+  const current = listRevision(board.db);
+  if (!same(revision, current, ownWrites)) throw unread();
+  return current;
+}
+
+/** Backing write preparation can clear TEMP bookkeeping or import card fields before the callback.
+ * Notice events are immutable log entries: a new filing/bounce must advance their primary-key ceiling.
+ * Check that ceiling in the transaction, and revalidate each selected filing by ID before using it. */
+export function noticeWriterBasis(board, revision, ceiling) {
+  const basis = listRevision(board.db);
+  if (['connection', 'data', 'mainSchema'].some(key => basis[key] !== revision[key])
+    || board.db.prepare('SELECT MAX(id) AS id FROM task_events').get().id !== ceiling) throw unread();
+  return basis;
+}
+
+export async function noticeReceiptsInTurns(board, messageIds) {
+  const wanted = new Set(messageIds);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const revision = listRevision(board.db);
+    const found = await readReceipts(board, wanted, revision);
+    if (found !== null && same(revision, listRevision(board.db))) return { ...found, revision };
+    await nextTurn();
+  }
+  throw unread();
+}
+
+async function readReceipts(board, wanted, revision) {
+  const db = board.db, filed = new Map(), bounced = new Set();
+  const ceiling = db.prepare('SELECT MAX(id) AS id FROM task_events').get().id;
+  let before = null;
+  while (ceiling !== null) {
+    if (!same(revision, listRevision(db))) return null;
+    // Bound every candidate, including unrelated event kinds. Return bodies only for notice receipts;
+    // filtering kinds or JSON in WHERE could scan unbounded history to find one matching page.
+    const rows = db.prepare(`SELECT id, task_id, kind, CASE WHEN kind IN ${KINDS} THEN payload END AS payload
+      FROM task_events WHERE id <= ?${before === null ? '' : ' AND id < ?'} ORDER BY id DESC LIMIT ${LIST_BATCH}`)
+      .all(ceiling, ...(before === null ? [] : [before]));
+    for (const row of rows) {
+      if (!FILED.has(row.kind) && row.kind !== 'notice_bounced') continue;
+      let payload;
+      try { payload = JSON.parse(row.payload ?? 'null') ?? {}; }
+      catch { throw new Error(`Notice receipt payload unread at event ${row.id}; bounced notices will be retried next round.`); }
+      const id = payload.message_id;
+      if (!wanted.has(id)) continue;
+      if (row.kind === 'notice_bounced') bounced.add(noticeKey(row.task_id, id));
+      else if (!filed.has(id)) filed.set(id, row); // descending IDs: preserve the latest filing
+    }
+    if (rows.length < LIST_BATCH) break;
+    // All requested messages have both their latest filing and an existing bounce: no older row can undo them.
+    if (filed.size === wanted.size && [...filed].every(([id, row]) => bounced.has(noticeKey(row.task_id, id)))) break;
+    before = rows.at(-1).id;
+    await nextTurn();
+  }
+  return { filed, bounced, ceiling };
+}

package/board/owner-door-worker.mjs

@@ -0,0 +1,61 @@
+// The thread that serves the board owner's socket (owner-door.mjs). A listing is answered here, read on a connection of
+// its own; every other request is handed to the owner's thread and its answer written back.
+import { parentPort, workerData } from 'node:worker_threads';
+import { createServer } from 'node:net';
+import { chmodSync } from 'node:fs';
+import { boardOwnerSocket } from '@volter/teams/board-owner';
+import { parse } from './args.mjs';
+import { answerOne } from './cli.mjs';
+import { knowLocalMachine } from './dispatch.mjs';
+import { holdOwnerHealth } from './owner-health.mjs';
+import { ownHome } from './owner-files.mjs';
+import { writeOwnerAnswer } from './reply.mjs';
+import { holdWorkflow } from './workflow.mjs';
+
+const { root, machine } = workerData;
+const waiting = new Map(); // request id → its answer's resolve
+let next = 0;
+parentPort.on('message', (frame) => {
+  if (frame.type === 'health') holdOwnerHealth(frame.boards, frame.round);
+  else if (frame.type === 'workflow') holdWorkflow(frame.root, frame.entry);
+  else if (frame.type === 'answer') { waiting.get(frame.id)?.(frame.answer); waiting.delete(frame.id); }
+});
+await knowLocalMachine(machine);
+ownHome(root);
+
+const byOwner = (line) => new Promise((resolve) => { const id = ++next; waiting.set(id, resolve); parentPort.postMessage({ type: 'request', id, line }); });
+const isListing = (line) => {
+  try {
+    const request = JSON.parse(line);
+    return !request?.tool && Array.isArray(request?.argv) && request.argv.every((arg) => typeof arg === 'string') && ['list', 'ls'].includes(parse(request.argv)._[0]);
+  } catch { return false; } // the owner answers what it cannot read
+};
+const answer = async (line) => {
+  if (!isListing(line)) return byOwner(line);
+  const read = await answerOne(root, line, { readOnly: true });
+  return read.byOwner ? byOwner(line) : read;
+};
+
+// allowHalfOpen: a caller that ends its side after its request still gets the answer, written when it is ready
+const server = createServer({ allowHalfOpen: true }, (socket) => {
+  let input = '';
+  socket.setEncoding('utf8');
+  socket.on('error', () => { /* the caller went away */ });
+  socket.on('data', (chunk) => {
+    if (input === null) return;
+    input += chunk;
+    const end = input.indexOf('\n');
+    if (end < 0) return;
+    const line = input.slice(0, end);
+    input = null;
+    // one answer per call, whatever the request did: a request that fails is a failed answer, never the door's end
+    answer(line)
+      .catch((error) => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` }))
+      .then((reply) => writeOwnerAnswer(socket, reply))
+      .catch(() => { socket.destroy(); }); // a disconnected caller leaves no queued reply
+  });
+});
+const path = boardOwnerSocket(root);
+await new Promise((done, fail) => { server.once('error', fail); server.listen(path, () => { server.off('error', fail); done(); }); });
+try { chmodSync(path, 0o600); } catch { /* the home is the user's own */ }
+parentPort.postMessage({ type: 'ready' });

package/board/owner-door.mjs

@@ -0,0 +1,46 @@
+// The board owner's socket, served on a thread of its own (owner-door-worker.mjs), so a caller is heard while the
+// owner's loop is held by a round. A listing (`list`, `ls`) is read on that thread, each on a connection of its own in
+// one SQLite read transaction (store.mjs openBoard, readOnly): WAL serves it beside the owner's writes, and neither
+// waits on the other. Every other request, and a listing that thread leaves to the owner (listing.mjs byOwner), comes
+// here and is answered by the board's one writer exactly as before. The thread holds what a listing says of the owner:
+// its dispatcher's health (owner-health.mjs) and the workflow it read (workflow.mjs), sent on each change.
+import { Worker } from 'node:worker_threads';
+import { watchOwnerHealth } from './owner-health.mjs';
+import { watchWorkflows } from './workflow.mjs';
+
+const failed = (error) => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` });
+
+/**
+ * Serve the owner's socket for the home at `root` (the caller holds its lock and has removed any old socket): resolves
+ * once the socket is bound. `answer(line)` answers a request here; `machine` is this machine's name as the owner learned
+ * it. A door that ends while the owner runs leaves the home with no door: the owner says so and exits, for its keeper to
+ * start it again. Answers the door's close.
+ */
+export async function openOwnerDoor(root, { machine, answer, log }) {
+  const worker = new Worker(new URL('./owner-door-worker.mjs', import.meta.url), { name: 'supercode board door', workerData: { root, machine } });
+  let open = false, closing = false;
+  const send = (frame) => { try { worker.postMessage(frame); } catch (error) { log(`board door: could not hand the door ${frame.type}: ${error.message}`); } };
+  const stops = [
+    watchOwnerHealth(({ boards, round }) => send({ type: 'health', boards, round })),
+    watchWorkflows((at, { workflow, params, profiles }) => send({ type: 'workflow', root: at, entry: { workflow, params, profiles } })),
+  ];
+  const close = () => { closing = true; for (const stop of stops) stop(); worker.terminate().catch(() => { /* ended */ }); };
+  worker.on('message', (frame) => {
+    if (frame?.type !== 'request') return;
+    // one answer per request, whatever it did: a request that fails is a failed answer, never the owner's end
+    Promise.resolve().then(() => answer(frame.line)).catch(failed)
+      .then((result) => { if (!closing) send({ type: 'answer', id: frame.id, answer: result }); });
+  });
+  await new Promise((resolve, reject) => {
+    const ended = (error) => {
+      if (closing) return;
+      if (!open) { close(); reject(error); return; }
+      log(`board door: ${error.message}; this home has no door now; stopping, for the keeper to start the owner again`);
+      process.exit(1);
+    };
+    worker.on('message', (frame) => { if (frame?.type === 'ready') { open = true; resolve(); } });
+    worker.on('error', ended);
+    worker.on('exit', (code) => ended(new Error(`the door's thread ended (${code})`)));
+  });
+  return close;
+}

package/board/owner-health.mjs

@@ -4,17 +4,23 @@
 const switches = new Map(); // board slug → { on, at, by, reason }
 let round = null; // { at, errors }
 let holding = false;
+// the owner's read door holds the same (owner-door.mjs), told of each change
+const watchers = new Set();
+const told = () => { for (const watcher of watchers) watcher({ boards: [...switches], round }); };
+/** `watcher` is told what the owner holds now and after each change; answers its stop. */
+export function watchOwnerHealth(watcher) { watchers.add(watcher); watcher({ boards: [...switches], round }); return () => watchers.delete(watcher); }
 
 /** The owner starts holding: each board's switch as stored, and the last round its predecessor recorded. */
 export function holdOwnerHealth(boards, lastRound) {
   holding = true;
   for (const [slug, state] of boards) switches.set(slug, state);
   round = lastRound;
+  told();
 }
 /** The owner wrote a board's switch. */
-export function holdSwitch(slug, state) { if (holding) switches.set(slug, state); }
+export function holdSwitch(slug, state) { if (holding) { switches.set(slug, state); told(); } }
 /** The owner completed a round. */
-export function holdRound(at, errors) { if (holding) round = { at, errors }; }
+export function holdRound(at, errors) { if (holding) { round = { at, errors }; told(); } }
 
 /** The notice for a verb on `slug`: dispatching off (a state), or a stalled round and its standing errors (failures). */
 export function dispatcherNotice(slug) {

package/board/published.mjs

@@ -177,7 +177,7 @@ export function cardSnapshot(db,row,rows=perCard(db)) {
   const runs=rows.attempts(row.id);
   const attempts=runs.map(run=>{
     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,agent:native.agent_id??null,counted:native.counted??null,profile_differences:native.agent_profile_mismatch?.differences??null}: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};
   });
@@ -186,7 +186,7 @@ export function cardSnapshot(db,row,rows=perCard(db)) {
     execution:executionOf(runs.find(run=>run.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]:[]),sponsor:own.sponsor??null,sponsor_evidence:parse(own.sponsor_evidence),requested_by_unverified:parse(own.requested_by_unverified),machine:own.machine??null,subtask_of:own.subtask_of??null,archived:!!own.archived,
-    blocked_by:parse(own.blocked_by,[]),paused:parse(own.paused),every:own.every??null,
+    blocked_by:parse(own.blocked_by,[]),paused:parse(own.paused),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};

package/board/record-view.mjs

@@ -62,9 +62,11 @@ export class RecordView {
     this.progressTimer.unref?.();
   }
   fail(error) {
+    this.ready = false;
     this.failure = error;
     for (const waiter of this.waiters) { clearTimeout(waiter.timer); waiter.reject(error); }
     this.waiters.clear();
+    try { this.onUnavailable?.(error); } catch { /* unavailable never becomes a fresh observation */ }
   }
   own(key) { return key.role === 'producer' ? key.machine === this.self : key.role === 'holder' && key.machine !== this.self; }
   apply(frame) {

package/board/store.mjs

@@ -19,7 +19,7 @@ import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { openZtrackBoard } from './ztrack.mjs';
-import { LIST_CONNECTION, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
+import { byOwner, LIST_CONNECTION, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
 import { isFilesBoard, openFilesBoard } from './files.mjs';
 import { signalBoardWrite } from './wake.mjs';
 import { PUBLICATION_SCHEMA, pruneDue, prunePublications, publicationTriggers, recordCardPublications } from './published.mjs';
@@ -76,14 +76,22 @@ CREATE INDEX IF NOT EXISTS idx_events_run ON task_events(run_id, id);
 // supercode's part of a card, beside Hermes's row: where its session runs, and the arc a subtask belongs to (a
 // subtask is worked by its arc's session and never started on its own).
 const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY KEY, machine TEXT, subtask_of TEXT, stage TEXT);
-CREATE TABLE IF NOT EXISTS supercode_effects (id INTEGER PRIMARY KEY AUTOINCREMENT, effect TEXT NOT NULL);`;
+CREATE TABLE IF NOT EXISTS supercode_effects (id INTEGER PRIMARY KEY AUTOINCREMENT, effect TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS supercode_session_custody (
+  address TEXT PRIMARY KEY, task_id TEXT NOT NULL, person TEXT NOT NULL,
+  detached_at INTEGER NOT NULL, detached_by TEXT NOT NULL, run_id INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS supercode_session_operations (
+  token TEXT PRIMARY KEY, card_ref TEXT, address TEXT, kind TEXT NOT NULL,
+  owner TEXT NOT NULL, started_at INTEGER NOT NULL
+);`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
 // `tags`: the card's ordered tags (Hermes's `tenant` holds the first); `sponsor`, `sponsor_evidence`, `requested_by_unverified`: C4
 // An effect's attempts: how many were made, when the next may be, and, once its attempts are spent, when it failed and
 // why (engine.mjs runEffects). A failed effect is kept as the record of its terminal state and never tried again.
 const EFFECT_COLUMNS = { attempts: 'INTEGER NOT NULL DEFAULT 0', next_at: 'INTEGER NOT NULL DEFAULT 0', failed_at: 'INTEGER', last_error: 'TEXT' };
-const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER', tags: 'TEXT', sponsor: 'TEXT', sponsor_evidence: 'TEXT', requested_by_unverified: 'TEXT' };
+const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', detached: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER', tags: 'TEXT', sponsor: 'TEXT', sponsor_evidence: 'TEXT', requested_by_unverified: 'TEXT' };
 
 // ------------------------------------------------------------------ backings
 //
@@ -151,6 +159,18 @@ const RUN_SESSION = "json_extract(metadata, '$.supercode.session_id')";
 const RUN_ADDRESS = "json_extract(metadata, '$.supercode.address')";
 const RUN_LAUNCH_PENDING = "json_extract(metadata, '$.supercode.launch_pending')";
 export const CALLER_RUN_ADDRESS = `SELECT ${RUN_ADDRESS} AS address FROM task_runs WHERE ${RUN_SESSION} = ? ORDER BY id DESC LIMIT 1`;
+// Launch/adoption commits the native address and its immutable role-agent together.
+// Pending/unissued launches are not an ownership receipt. Read only that identity,
+// never the current assignee, a profile hint, or mutable manager/admission state.
+export const CALLER_RUN_AGENT = `SELECT DISTINCT
+  json_extract(metadata, '$.supercode.agent_id') AS agent_id,
+  json_extract(metadata, '$.supercode.agent_org') AS org
+  FROM task_runs WHERE ${RUN_SESSION} = ? AND ${RUN_ADDRESS} = ?
+  AND COALESCE(${RUN_LAUNCH_PENDING}, 0) = 0
+  AND COALESCE(json_extract(metadata, '$.supercode.launch_deferred'), 0) = 0
+  AND json_extract(metadata, '$.supercode.mode') IN ('fresh', 'resume', 'adopt')
+  AND json_extract(metadata, '$.supercode.agent_id') IS NOT NULL
+  AND json_extract(metadata, '$.supercode.agent_org') IS NOT NULL`;
 const RUN_SESSION_INDEX = 'idx_runs_supercode_session';
 const RUN_LAUNCH_PENDING_INDEX = 'idx_runs_supercode_launch_pending';
 // The indexes on a run's metadata. The second holds only the runs whose launch is pending (7 of 1,387 on the store
@@ -371,6 +391,8 @@ export function heldConfigWatched(slug, source, watched) {
 }
 
 export function openBoard(root, slug = DEFAULT_BOARD, options = {}) {
+  // a listing on the owner's read door reads on a connection of its own, never the held board's (openReadOnly)
+  if (current().readOnly) return openReadOnly(root, slug);
   if (holding !== null && !options.create && realRoot(root) === holding && !untrustedConfig.get(slug)?.size) {
     let entry = heldBoards.get(slug);
     if (!entry) {
@@ -400,6 +422,33 @@ function heldHandle(entry, slug) {
     close() { if (closed) return; closed = true; entry.uses -= 1; if (entry.retired && !entry.uses) try { entry.board.close(); } catch { /* closed */ } } };
 }
 
+/**
+ * Board `slug` as one committed state, for a listing on the owner's read door: a connection of its own in one SQLite
+ * read transaction (WAL's snapshot, beside any writer, with no busy timeout), kept until `close`. It makes, lays out,
+ * recovers and writes nothing; a board it cannot read so (a `files` board, whose card files have no commit point a
+ * reader can take; a store not in WAL or not laid out; one it cannot begin reading, `unreadable`) is left to the owner
+ * (listing.mjs byOwner).
+ */
+function openReadOnly(root, slug) {
+  const use = backingOf(root, slug);
+  if (!use) throw new Error(`no board ${slug} in ${root} (${boardPath(root, slug)})`);
+  const path = backingPaths(root, slug)[use];
+  if (use === 'ztrack') return { ...openZtrackBoard(path, { init: layOut, root, slug, readOnly: true }), root, slug, path, backing: use };
+  if (use === 'files') throw byOwner(`board ${slug} is kept in files`);
+  let db;
+  try {
+    db = new DatabaseSync(path, { readOnly: true });
+    if (String(db.prepare('PRAGMA journal_mode').get()?.journal_mode).toLowerCase() !== 'wal') throw byOwner(`${path} is not in WAL mode`);
+    db.exec('BEGIN');
+    // the transaction's first read begins its snapshot
+    if (!indexed(db, TASK_SUMMARY_INDEX)) throw byOwner(`${path} is not laid out yet`);
+  } catch (error) {
+    db?.close();
+    throw unreadable(error) ? byOwner(error.message) : error;
+  }
+  return { db, root, slug, path, backing: use, tx: () => { throw new Error('a listing reads the board and writes nothing'); }, close: () => db.close() };
+}
+
 function openBoardNow(root, slug, { create = false, backing = null, document = null, declared = null, held = false } = {}) {
   noteOrigin(root);
   const kept = backingOf(root, slug);
@@ -477,6 +526,9 @@ export function publishMarked(root) {
 export const contention = (error) => [5, 6].includes(Number(error?.errcode) & 255)
   || ['SQLITE_BUSY', 'SQLITE_LOCKED'].includes(error?.code)
   || /^database (?:table |schema )?is locked$/i.test(error?.message ?? '');
+// What keeps a read-only connection from beginning its read where the owner's own would not: contention, or a store it
+// may not open or read as it stands (SQLite CANTOPEN, READONLY). The listing is then the owner's (openReadOnly).
+export const unreadable = (error) => contention(error) || [8, 14].includes(Number(error?.errcode) & 255);
 // The store's volume refusing a write (SQLite IOERR or FULL and their extended codes; ENOSPC or EIO from a file write):
 // a fault of the machine's storage at that minute, never of the card or the operation that met it. A transaction it
 // rolled back is tried again a bounded number of times (STORAGE_TRIES); one still refused fails cleanly, and its caller