@volter/supercode-orchestrator 0.5.205 → 0.5.207

package/board/fleet-listeners.mjs

@@ -0,0 +1,268 @@
+// Fleet facts are mail obligations, independent of card transitions and dispatch ticks. Intent comes only from the
+// canonical workflow IR. The sender supplies observations from its admitted sources; this router grants nothing.
+import { DatabaseSync } from 'node:sqlite';
+import { chmodSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+const KINDS = new Set(['session_started', 'session_resumed', 'session_ended', 'duplicate_session_process', 'card_waiting_on_user', 'machine_health_crit']);
+const ADDRESS = /^sc:[^:\s]+:[^:\s]+:[^:\s]+$/;
+const MACHINE = /^[a-z0-9_-]+$/;
+const MAX_PENDING = 4096, MAX_PENDING_BYTES = 16 * 1024 * 1024, MAX_EVENT_BYTES = 64 * 1024;
+const digest = value => createHash('sha256').update(value).digest('hex');
+const refused = message => Object.assign(new Error(message), { code: 'fleet_listener_refused' });
+
+/** A retained mail outbox. `file` is the board's existing admitted mailbox filing door, never a transport or
+ *  provider selected from the observed payload. No runtime database is opened until the home opts into listeners. */
+export class FleetListenerRouter {
+  constructor({ root, file, enrich = event => event, retry = () => {}, log = () => {} }) {
+    if (typeof file !== 'function') throw refused('fleet listener router needs the admitted mailbox filing door');
+    this.root = root; this.file = file; this.enrich = enrich; this.retry = retry; this.log = log; this.definitions = {}; this.closed = false; this.suspended = false;
+  }
+
+  /** The workflow's decoded declarations. An invalid replacement refuses without discarding the prior outbox. */
+  configure(definitions = {}) {
+    if (this.closed) throw refused('fleet listener router is closed');
+    if (!definitions || typeof definitions !== 'object' || Array.isArray(definitions)) throw refused('listeners must be a role map');
+    const next = Object.create(null);
+    for (const [role, declaration] of Object.entries(definitions)) {
+      if (!role || !declaration || Object.keys(declaration).some(key => !['events', 'addresses', 'machines'].includes(key))) throw refused(`invalid fleet listener ${role}`);
+      const { events, addresses, machines } = declaration;
+      if (!Array.isArray(events) || !events.length || events.some(kind => !KINDS.has(kind))) throw refused(`fleet listener ${role} names unsupported events`);
+      if (!Array.isArray(addresses) || !addresses.length || addresses.some(address => typeof address !== 'string' || !ADDRESS.test(address) || /[\x00-\x1f\x7f]/.test(address))) throw refused(`fleet listener ${role} needs full mail addresses`);
+      if (machines != null && (!Array.isArray(machines) || machines.some(machine => typeof machine !== 'string' || !MACHINE.test(machine)))) throw refused(`fleet listener ${role} needs normalized machine names`);
+      next[role] = { events: [...new Set(events)], addresses: [...new Set(addresses)], machines: machines == null ? null : [...new Set(machines)] };
+    }
+    this.definitions = next;
+    this.suspended = false;
+    if (Object.keys(next).length) {
+      this.store();
+      if (!this.timer) { this.timer = setInterval(() => { if (!this.suspended) { try { this.retry(); } catch (error) { this.log(`fleet listener source: ${String(error.message).slice(0, 300)}`); } } this.wake(); }, 1000); this.timer.unref?.(); }
+      this.wake();
+    } else if (this.db) {
+      this.db.prepare('INSERT INTO fleet_listener_runtime(id,needs_baseline) VALUES(1,1) ON CONFLICT(id) DO UPDATE SET needs_baseline=1').run();
+    }
+  }
+
+  suspend() { this.suspended = true; }
+  get enabled() { return !this.closed && !this.suspended && Object.keys(this.definitions).length > 0; }
+
+  store() {
+    if (this.db) return this.db;
+    const directory = join(this.root, 'runtime');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, 'fleet-listeners.sqlite');
+    const db = new DatabaseSync(path);
+    try {
+      chmodSync(path, 0o600);
+      db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+      CREATE TABLE IF NOT EXISTS fleet_listener_mail (
+        id TEXT PRIMARY KEY, role TEXT NOT NULL, address TEXT NOT NULL,
+        kind TEXT NOT NULL, machine TEXT NOT NULL, digest TEXT NOT NULL,
+        body TEXT, bytes INTEGER NOT NULL, state TEXT NOT NULL,
+        created_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
+        next_at INTEGER NOT NULL DEFAULT 0, error TEXT, message_id TEXT, filed_at INTEGER
+      ) STRICT;
+      CREATE INDEX IF NOT EXISTS fleet_listener_due ON fleet_listener_mail(state,next_at,created_at,id);
+      CREATE TABLE IF NOT EXISTS fleet_listener_sources (
+        source TEXT PRIMARY KEY, sequence INTEGER NOT NULL, baseline INTEGER NOT NULL, error TEXT,
+        gaps INTEGER NOT NULL DEFAULT 0, last_gap TEXT, updated_at INTEGER NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS fleet_listener_waits (
+        address TEXT PRIMARY KEY, active INTEGER NOT NULL, wait_key TEXT, event TEXT, routed INTEGER NOT NULL DEFAULT 0
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS fleet_listener_runtime (id INTEGER PRIMARY KEY CHECK(id=1), needs_baseline INTEGER NOT NULL) STRICT;`);
+    } catch (error) { db.close(); throw error; }
+    this.db = db;
+    return db;
+  }
+
+  matches(role, event, address) {
+    const declaration = this.definitions[role];
+    return Boolean(declaration?.events.includes(event.kind) && declaration.addresses.includes(address)
+      && (declaration.machines == null || declaration.machines.includes(event.machine)));
+  }
+
+  /** Commit each matched obligation before a source advances its own cursor. A full outbox or a conflicting replay
+   *  throws; the source must retain/retry that event rather than mark it consumed. IDs come from the source's retained
+   *  observation, never from this process's current time. The same event/role/address keeps the same filing id. */
+  enqueue(event) {
+    if (this.closed) throw refused('fleet listener router is closed');
+    if (this.suspended) throw refused('fleet listener configuration is not current');
+    if (!Object.keys(this.definitions).length) return { queued: 0 };
+    if (!event || !KINDS.has(event.kind) || typeof event.source !== 'string' || !event.source
+      || typeof event.id !== 'string' || !event.id || typeof event.machine !== 'string' || !MACHINE.test(event.machine)
+      || !Number.isSafeInteger(event.observed_at_ms) || event.observed_at_ms < 0) throw refused('fleet event needs its kind, source, retained id, machine and observation time');
+    const original = JSON.stringify(event), hash = digest(original);
+    const body = JSON.stringify(this.enrich(event)), bytes = Buffer.byteLength(body);
+    if (bytes > MAX_EVENT_BYTES) throw refused('fleet event exceeds 64 KiB; source observation remains owed');
+    const db = this.store();
+    let queued = 0;
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const held = db.prepare("SELECT COUNT(*) AS count,COALESCE(SUM(bytes),0) AS bytes FROM fleet_listener_mail WHERE state='pending'").get();
+      for (const [role, declaration] of Object.entries(this.definitions)) for (const address of declaration.addresses) {
+        if (!this.matches(role, event, address)) continue;
+        const id = `fleet-${digest(JSON.stringify([event.source, event.id, role, address]))}`;
+        const previous = db.prepare('SELECT digest FROM fleet_listener_mail WHERE id=?').get(id);
+        if (previous) { if (previous.digest !== hash) throw refused('fleet event id was replayed with different contents'); continue; }
+        if (held.count + queued >= MAX_PENDING || held.bytes + (queued + 1) * bytes > MAX_PENDING_BYTES) throw refused('fleet listener outbox full; source observation remains owed');
+        db.prepare("INSERT INTO fleet_listener_mail(id,role,address,kind,machine,digest,body,bytes,state,created_at) VALUES(?,?,?,?,?,?,?,?, 'pending',?)")
+          .run(id, role, address, event.kind, event.machine, hash, body, bytes, Date.now());
+        queued++;
+      }
+      db.exec('COMMIT');
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+    this.wake();
+    return { queued };
+  }
+
+  /** Existing machines establish a baseline on first enrollment (or after all listeners were explicitly removed).
+   * An ordinary owner restart preserves its cursors. Machines first seen after enrollment offer their retained window. */
+  bootstrap(records) {
+    if (!this.enabled) return;
+    const db = this.store(), runtime = db.prepare('SELECT needs_baseline FROM fleet_listener_runtime WHERE id=1').get();
+    if (runtime?.needs_baseline === 0) return;
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      for (const [machine, held] of Object.entries(records)) {
+        for (const [section, prefix] of [['fleet', 'machine-fleet'], ['health_events', 'machine-health']]) {
+          const fleet = ['self', 'open'].includes(held.stream) && !held.record?.unread?.[section] ? held.record?.[section] : null;
+          if (!fleet || typeof fleet.source !== 'string' || !fleet.source.startsWith(`${prefix}:${machine}:`) || !Number.isSafeInteger(fleet.last) || fleet.last < 0) continue;
+          db.prepare(`INSERT INTO fleet_listener_sources(source,sequence,baseline,updated_at) VALUES(?,?,?,?)
+            ON CONFLICT(source) DO UPDATE SET sequence=excluded.sequence,baseline=excluded.baseline,error=NULL,updated_at=excluded.updated_at`).run(fleet.source, fleet.last, fleet.last, Date.now());
+        }
+      }
+      db.prepare('INSERT INTO fleet_listener_runtime(id,needs_baseline) VALUES(1,0) ON CONFLICT(id) DO UPDATE SET needs_baseline=0').run();
+      db.exec('COMMIT');
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  }
+
+  /** A source cursor moves only after every matched filing obligation is committed. Refusal retains the event and
+   * cursor for retry. A new machine starts with the first observation still available in its retained window. */
+  baseline(source, head) {
+    if (!this.enabled) return null;
+    const db = this.store();
+    if (typeof source !== 'string' || !source || !Number.isSafeInteger(head) || head < 0) throw refused('invalid fleet source cursor');
+    db.prepare('INSERT INTO fleet_listener_sources(source,sequence,baseline,updated_at) VALUES(?,?,?,?) ON CONFLICT(source) DO NOTHING').run(source, head, head, Date.now());
+    return db.prepare('SELECT * FROM fleet_listener_sources WHERE source=?').get(source);
+  }
+
+  consume(source, sequence, event = null) {
+    if (!this.enabled) return false;
+    const held = this.db?.prepare('SELECT sequence FROM fleet_listener_sources WHERE source=?').get(source);
+    if (!held || !Number.isSafeInteger(sequence) || sequence <= held.sequence) return false;
+    try {
+      if (event) this.enqueue(event);
+      this.db.prepare('UPDATE fleet_listener_sources SET sequence=?,error=NULL,updated_at=? WHERE source=?').run(sequence, Date.now(), source);
+      return true;
+    } catch (error) {
+      this.db.prepare('UPDATE fleet_listener_sources SET error=?,updated_at=? WHERE source=?').run(String(error.message).slice(0, 500), Date.now(), source);
+      throw error;
+    }
+  }
+
+  /** The machine's bounded sequence says precisely which older observations it cannot replay. Keep that gap as
+   * unknown in the status and log, then continue the retained window; never claim the missing events were filed. */
+  follow({ source, first, last, events }) {
+    if (!this.enabled) return;
+    if (!Number.isSafeInteger(first) || first < 1 || !Number.isSafeInteger(last) || last < first - 1 || !Array.isArray(events)
+      || events.length !== last - first + 1 || events.some((event, at) => event.source !== source || event.sequence !== first + at || event.id !== String(event.sequence))) throw refused('fleet source retained window is not contiguous');
+    let held = this.baseline(source, first - 1);
+    if (held.sequence > last) throw refused('fleet source head moved backwards');
+    if (held.sequence < first - 1) {
+      const gap = `upstream history pruned observations ${held.sequence + 1}..${first - 1}; their content and delivery remain unknown`;
+      this.db.prepare('UPDATE fleet_listener_sources SET sequence=?,gaps=gaps+1,last_gap=?,updated_at=? WHERE source=?').run(first - 1, gap, Date.now(), source);
+      this.log(`fleet listener ${source}: ${gap}`);
+      held = { ...held, sequence: first - 1 };
+    }
+    let count = 0;
+    for (const event of events) if (event.sequence > held.sequence) {
+      this.consume(source, event.sequence, event);
+      if (++count >= 64) break;
+    }
+  }
+
+  /** The prompt's retained episode, independent of card-dispatch rounds. Persist its payload/id before enqueue so a
+   * lost answer or outbox refusal retries the same observation. Only a fresh native idle/working reading clears it. */
+  cardWait(address, observation) {
+    if (!this.enabled) return;
+    const db = this.store();
+    if (!observation) { db.prepare('UPDATE fleet_listener_waits SET active=0 WHERE address=?').run(address); return; }
+    const key = JSON.stringify([observation.waiting_for, observation.since_ms]);
+    let held = db.prepare('SELECT * FROM fleet_listener_waits WHERE address=?').get(address);
+    if (!held?.active || held.wait_key !== key) {
+      // A previous episode whose filing was refused is still owed before a replacement can take its slot.
+      if (held?.event && !held.routed) this.enqueue(JSON.parse(held.event));
+      const event = { source: `card-wait:${this.root}`, id: randomUUID(), ...observation };
+      db.prepare(`INSERT INTO fleet_listener_waits(address,active,wait_key,event,routed) VALUES(?,1,?,?,0)
+        ON CONFLICT(address) DO UPDATE SET active=1,wait_key=excluded.wait_key,event=excluded.event,routed=0`).run(address, key, JSON.stringify(event));
+      held = { event: JSON.stringify(event), routed: 0 };
+    }
+    if (!held.routed) {
+      this.enqueue(JSON.parse(held.event));
+      db.prepare('UPDATE fleet_listener_waits SET routed=1 WHERE address=?').run(address);
+    }
+  }
+
+  wake() { if (!this.closed) void this.flush().catch(error => this.log(`fleet listener filing: ${String(error.message).slice(0, 300)}`)); }
+
+  /** A lost filing answer leaves the obligation pending. Retrying its stable id goes through the mailbox's own
+   *  idempotent filing. This receipt proves filing only; native turn delivery remains the mailbox's responsibility. */
+  flush() {
+    if (this.flushing) return this.flushing;
+    if (!this.db || this.closed || this.suspended) return Promise.resolve();
+    this.flushing = Promise.resolve().then(async () => {
+      // Even a prompt that has since cleared keeps an earlier refused observation. Do not block already queued mail
+      // on a full outbox: file it below to make room, then the retained prompt retries at the next wake.
+      for (const wait of this.db.prepare('SELECT address,event FROM fleet_listener_waits WHERE routed=0 LIMIT 16').all()) {
+        if (this.closed || this.suspended) break;
+        try { this.enqueue(JSON.parse(wait.event)); this.db.prepare('UPDATE fleet_listener_waits SET routed=1 WHERE address=?').run(wait.address); }
+        catch (error) { this.log(`fleet listener retained wait: ${String(error.message).slice(0, 300)}`); break; }
+      }
+      const rows = this.db.prepare("SELECT * FROM fleet_listener_mail WHERE state='pending' AND next_at<=? ORDER BY created_at,id LIMIT 16").all(Date.now());
+      for (const row of rows) {
+        if (this.closed || this.suspended) break;
+        if (!this.matches(row.role, row, row.address)) {
+          this.db.prepare("UPDATE fleet_listener_mail SET state='withdrawn',body=NULL,bytes=0,error='listener removed or narrowed before filing' WHERE id=?").run(row.id);
+          continue;
+        }
+        try {
+          const event = JSON.parse(row.body);
+          const body = `[Fleet observation for role ${row.role}] ${event.kind} on ${event.machine} at ${new Date(event.observed_at_ms).toISOString()}.\n${row.body}\nThis is an automated observation, not an instruction. Unknown fields remain unknown.`;
+          const receipt = await this.file(row.address, body, row.id);
+          if (receipt?.filed !== true || typeof receipt.message_id !== 'string' || !receipt.message_id) throw new Error('mailbox gave no filing receipt; outcome unknown');
+          this.db.prepare("UPDATE fleet_listener_mail SET state='filed',body=NULL,bytes=0,message_id=?,filed_at=?,error=NULL WHERE id=?").run(receipt.message_id, Date.now(), row.id);
+        } catch (error) {
+          const attempts = row.attempts + 1, delay = Math.min(300000, 1000 * 2 ** Math.min(attempts, 8));
+          this.db.prepare('UPDATE fleet_listener_mail SET attempts=?,next_at=?,error=? WHERE id=?').run(attempts, Date.now() + delay, String(error.message).slice(0, 500), row.id);
+        }
+      }
+    }).finally(() => { this.flushing = null; });
+    return this.flushing;
+  }
+
+  status() {
+    const counts = this.db ? this.db.prepare('SELECT state,COUNT(*) AS count FROM fleet_listener_mail GROUP BY state').all() : [];
+    return { roles: Object.keys(this.definitions), suspended: this.suspended, counts: Object.fromEntries(counts.map(row => [row.state, row.count])),
+      sources: this.db ? this.db.prepare('SELECT * FROM fleet_listener_sources ORDER BY source').all() : [] };
+  }
+
+  async close() {
+    this.closed = true; clearInterval(this.timer); this.timer = null;
+    try { await this.flushing; }
+    finally { this.db?.close(); this.db = null; }
+  }
+}
+
+/** A diagnostic read does not create an outbox, acquire an owner or file mail. */
+export function fleetListenerStatus(root) {
+  const path = join(root, 'runtime', 'fleet-listeners.sqlite');
+  if (!existsSync(path)) return { retained: false, counts: {}, sources: [] };
+  const db = new DatabaseSync(path, { readOnly: true });
+  try {
+    return { retained: true, counts: Object.fromEntries(db.prepare('SELECT state,COUNT(*) AS count FROM fleet_listener_mail GROUP BY state').all().map(row => [row.state, row.count])),
+      sources: db.prepare('SELECT * FROM fleet_listener_sources ORDER BY source').all(),
+      unrouted_waits: db.prepare('SELECT COUNT(*) AS count FROM fleet_listener_waits WHERE routed=0').get().count };
+  } finally { db.close(); }
+}

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; } };
@@ -63,11 +68,12 @@ export const LAST_BLOCK_SQL = `SELECT CASE WHEN kind = 'blocked' THEN payload EN
 
 export function listPageSql(detailed, tagCount = 0) {
   return `SELECT t.rowid AS list_order,${(detailed ? JSON_FIELDS : HUMAN_FIELDS).split(',').map(name => `t.${name}`).join(',')},
-    c.machine,c.stage${detailed ? ',c.subtask_of' : ''},
+    n.number,c.machine,c.stage${detailed ? ',c.subtask_of' : ''},
     r.id AS run_id,r.status AS run_status,r.started_at AS run_started_at,r.ended_at AS run_ended_at,${RUN_METADATA} AS run_metadata
     ${detailed ? `,(SELECT json_group_array(parent_id) FROM (SELECT parent_id FROM task_links WHERE child_id = t.id ORDER BY parent_id)) AS parents_json,
       (${LAST_BLOCK_SQL}) AS block_payload` : ''}
-    FROM tasks t ${detailed ? '' : `INDEXED BY ${TASK_SUMMARY_INDEX}`} LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN task_runs r ON r.id = t.current_run_id
+    FROM tasks t ${detailed ? '' : `INDEXED BY ${TASK_SUMMARY_INDEX}`} LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN supercode_card_numbers n ON n.task_id = t.id
+    LEFT JOIN task_runs r ON r.id = t.current_run_id
     WHERE t.id IN (SELECT value FROM json_each(?)) AND (? IS NULL OR t.status = ? OR c.stage = ?)
       AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? OR t.status != 'archived')
       AND (? IS NULL OR t.tenant = ?) AND (? IS NULL OR t.session_id = ?)

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/notices.mjs

@@ -1,3 +1,8 @@
+/** A notice's text or a mail's subject about a card, with the card's number first (`#42 …`; store.mjs layOutNumbers). */
+export const numbered = (number, text) => (number ? `#${number} ${text}` : text);
+/** The number of card `id` in the board's store, or null. */
+export const cardNumber = (db, id) => db.prepare('SELECT number FROM supercode_card_numbers WHERE task_id = ?').get(id)?.number ?? null;
+
 export function identifyNotice(event, text) {
   const time = new Date(Number(event.created_at) * 1000).toISOString();
   const kind = String(event.kind).replaceAll('_', ' ');