@volter/supercode-orchestrator 0.5.205 → 0.5.206

package/board/cli.mjs

@@ -1,6 +1,6 @@
 // `supercode workflow <verb>` (docs/architecture/orchestrator.md §2.9): supercode's own board, in Hermes Kanban's
 // format, and its dispatcher. Every verb of `hermes kanban` is here under its own name, with its own flags and its own
-// output lines, so a caller of Hermes's CLI calls this one unchanged; supercode's own verbs (`set`, `adopt`, `close`,
+// output lines, so a caller of Hermes's CLI calls this one unchanged; supercode's own verbs (`set`, `adopt`, `detach`, `close`,
 // `serve`, `--at`) are added beside them. The Rust CLI hands every verb but `load` to `bin/orchestrator.mjs workflow`,
 // which lands here. The home is `--root`, else `SUPERCODE_ORCHESTRATOR_HOME`; the board is
 // `--board <slug>`, else `HERMES_KANBAN_BOARD`, else the home's current board (`kanban/current`), else `default`.
@@ -10,26 +10,28 @@ import { DatabaseSync } from 'node:sqlite';
 import { homeOf, parse } from './args.mjs';
 import { BOARD_OPERATION_VERBS, boardHome, boardOwnerSocket, CALLER_FACTS } from '@volter/teams/board-owner';
 import { current, isCallersCall, ownCall, within } from './call.mjs';
+import { detachSession } from './custody.mjs';
 import { taskStatusOf } from './published.mjs';
 import { executionOf } from './session-work.mjs';
-import { listCardsInTurns, writeCardList } from './listing.mjs';
-import { writeOwnerAnswer } from './reply.mjs';
+import { attachmentRecord, readAttachment } from './attachment-read.mjs';
+import { listCardsInTurns, READ_BY_OWNER, writeCardList } from './listing.mjs';
 import { redactText } from '@volter/teams/redact';
-import { createServer } from 'node:net';
-import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+import { openOwnerDoor } from './owner-door.mjs';
+import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import { notRuntime, ownHome } from './owner-files.mjs';
 import { execFile, spawnSync } from 'node:child_process';
 import { holdLock } from './lock-holder.mjs';
 import { takeEpoch } from './fence.mjs';
 import { dispatcherNotice, holdOwnerHealth, holdRound, holdSwitch } from './owner-health.mjs';
 import { boardTool } from './tools.mjs';
+import { assertSourceReceipt } from './ci.mjs';
 import { noteStep, recordSlow, takeSteps } from '@volter/supercode-harness-sdk/slow-log';
 // read by name, so an older harness SDK without them still loads: the owner then keeps no per-verb or loop lines
 import * as slowLog from '@volter/supercode-harness-sdk/slow-log';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, userInfo } from 'node:os';
-import { actorOf, CALLER_RUN_ADDRESS, SESSION_CURRENT_RUNS, SESSION_RUNS, sessionIndexed, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardPath, briefPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
+import { actorOf, CALLER_RUN_ADDRESS, CALLER_RUN_AGENT, SESSION_CURRENT_RUNS, SESSION_RUNS, sessionIndexed, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardCopyOf, boardPath, briefPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
 import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
@@ -69,9 +71,12 @@ async function boardPublishing(root) {
 import { dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
 import { watchBoard } from './wake.mjs';
 import { attachSideSession, releaseSideSession, sideArcs, sideSessions } from './side-sessions.mjs';
-import { onPanesChanged } from './machine-fleet.mjs';
+import { onPanesChanged, onRecordsChanged, readFleetRecords, fleetRecordsCurrent } from './machine-fleet.mjs';
+import { FleetListenerRouter, fleetListenerStatus } from './fleet-listeners.mjs';
+import { enrichFleetEvent, observeRoleFleet } from './fleet-observer.mjs';
+import { fileFleetNotice } from './dispatch.mjs';
 import { streamBoardPublications } from './event-stream.mjs';
-import { completionOwnerOf, followHome, isLatestReviewer, loadWorkflow, readHome, requestSessionClose, scopeOf, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
+import { completionOwnerOf, followHome, isLatestReviewer, loadWorkflow, readHome, requestSessionClose, scopeOf, statusOf, timeOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
 import { evaluate } from './expr.mjs';
 import { agentDoor,agentScope,activeAgentAssignments,reassignAgent,agentUsage,localAgentRecord,agentRunForSession } from '../agents.mjs';
 
@@ -94,18 +99,19 @@ The board's verbs, with their flags:
   boards list|create|rm|switch|show|rename|set-default-workdir|export|import
   create <title> [--body | --body-file PATH|-] [--assignee] [--parent]... [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch] [--project]
          [--tenant] [--priority] [--triage] [--idempotency-key] [--max-runtime 30m] [--created-by] [--skill]... [--max-retries]
-         [--model] [--provider] [--goal|--no-goal] [--goal-max-turns] [--initial-status blocked|running]
+         [--model] [--provider] [--reviewer PROFILE] [--goal|--no-goal] [--goal-max-turns] [--initial-status blocked|running]
   swarm <goal> --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
   list [--mine] [--assignee] [--status] [--tenant] [--session] [--archived] [--sort]   show <id>   context <id>   brief <id> [--run N]   runs <id>
-  set <id> <assignee|machine|model|every> <value|none> [--provider] [--ids ...]   assign <id> <profile|none>   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
+  set <id> <assignee|machine|model|every|reviewer> <value|none> [--provider] [--ids ...]   assign <id> <profile|none>   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
   reassign <id> --agent AGENT [--role implementer]   (moves a card role's assignment to another agent; sessions keep their identity)
   claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
   comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)...]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
-  complete <id>... [--result] [--summary] [--metadata JSON]   edit <id> --result [--summary] [--metadata]
+  attachment-read <id> <attachment-id> [--offset N --length N --version V]   bounded base64/metadata JSON, including through --at
+  complete <id>... [--result] [--summary] [--metadata JSON] [--commit SHA]   edit <id> --result [--summary] [--metadata]
   block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
   pause <id> --reason <why>   resume <id>   cancel <id> --reason <why>
   request-state <id> --state block|pause|done|cancelled --reason <why> [--on <card>|--waiting-on <message>] [--evidence <pointers>]
-  unblock <id>... --on <blocker> --reason <what arrived>   request-review <id> (--pr URL --pr-head SHA)... [--summary] [--reviewer] [--force]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>...   reopen <id>... [--reason]
+  unblock <id>... --on <blocker> --reason <what arrived>   request-review <id> (--pr URL --pr-head SHA)... [--summary] [--reviewer] [--force] [--commit SHA]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... --reason <why> [--rm <id>...]
   specify <id> [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
   decompose <id> [--child "<title>[@<profile>]"]... [--all]
@@ -131,7 +137,7 @@ And:
   create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
       waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
-  adopt <id> <session> [--assignee P] [--role ROLE]   adopt <arc> <session> --side · release <arc> <session>   close <id>   serve (= daemon)   list --machine M
+  adopt <id> <session> [--assignee P] [--role ROLE]   adopt <arc> <session> --side · release <arc> <session>   detach <id> [--to person:ID]   close <id>   serve (= daemon)   list --machine M
   notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
   notify-subscribe <dependency> --for-card <your-arc>: subscribe only your arc's session to dependency notices.
   notify-unsubscribe <dependency> --for-card <your-arc>: remove that arc's subscription only.
@@ -148,6 +154,7 @@ And:
   request-state <id> --state done (--reviewed-sha SHA)...: record the verdict on every requested PR head.
   request-state <id>... --state STATE --reason REASON: request several decisions in one retained manager mail.
   complete <id>: creator/manager accepts the independently reviewed arc; deployment CI is not a board gate.
+  listeners status [--json]: declared role fleet listeners, retained filing counts, source cursors and gaps.
   specify/decompose with no spec start a session on the triage card to write it. A card's own session may comment on,
   heartbeat and request review of its card, specify or decompose it in triage, and work its subtasks. A side session
   (adopt --side) works the arc's subtasks and comments on the arc; the arc's run and state stay its main session's. The home's
@@ -255,17 +262,40 @@ const callerName = () => current().facts.HERMES_PROFILE || current().facts.USER
  * automation running it, its own plain session, or the person its Teams login names. Never the OS user; null when
  * nothing names one.
  */
-async function callerPrincipal(root, sid, { teams = false } = {}) {
+async function ownerStep(name, fn) {
+  const began = performance.now();
+  try { return await fn(); }
+  finally { noteStep(`owner preparation: ${name}`, performance.now() - began); }
+}
+
+function recordedRunAgent(db, sid, address) {
+  const rows = db.prepare(CALLER_RUN_AGENT).all(sid, address);
+  const owners = new Map();
+  for (const row of rows) {
+    if (!/^agent_[0-9a-f]{32}$/.test(row.agent_id) || typeof row.org !== 'string' || !row.org) continue;
+    owners.set(JSON.stringify([row.org, row.agent_id]), row);
+  }
+  if (owners.size > 1) throw new Error('recorded native session has conflicting agent ownership');
+  return owners.values().next().value ?? null;
+}
+
+async function callerPrincipal(root, sid, { teams = false, recordedAgent = null } = {}) {
   const facts = current().facts;
+  if (recordedAgent && facts.SUPERCODE_AGENT_ID && facts.SUPERCODE_AGENT_ID !== recordedAgent.agent_id)
+    throw new Error('native session ownership does not match its launch identity');
+  if (recordedAgent && facts.SUPERCODE_AGENT_ORG && facts.SUPERCODE_AGENT_ORG !== recordedAgent.org)
+    throw new Error('native session Org does not match its launch identity');
   if (facts.SUPERCODE_AGENT_ID) return `agent:${facts.SUPERCODE_AGENT_ID}`;
   if (facts.SUPERCODE_AUTOMATION) return `automation:${facts.SUPERCODE_AUTOMATION}`;
   if (sid) {
     const harness = boardCaller()?.harness ?? (sid === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code');
-    const owner = agentRunForSession(root, [`${harness}:${sid}`]);
-    if (owner) return `agent:${owner.agent_id}`;
+    const owner = await ownerStep('local agent ownership', () => agentRunForSession(root, [`${harness}:${sid}`]));
+    if (owner && recordedAgent && (owner.agent_id !== recordedAgent.agent_id || owner.org !== recordedAgent.org))
+      throw new Error('local and recorded native session ownership conflict');
+    if (owner || recordedAgent) return `agent:${(owner ?? recordedAgent).agent_id}`;
     // a session an agent declared elsewhere owns (a manager's main session) is that agent's, as Teams records it
     let declared = null;
-    try { declared = (await agentDoor('session', [`${harness}:${sid}`], { context: current().facts.SUPERCODE_CONTEXT })).data?.agent?.id ?? null; } catch { /* no Teams: the session */ }
+    try { declared = (await ownerStep('Teams session ownership', () => agentDoor('session', [`${harness}:${sid}`], { context: current().facts.SUPERCODE_CONTEXT }))).data?.agent?.id ?? null; } catch { /* no Teams: the session */ }
     return declared ? `agent:${declared}` : `session:${callerAddress()}`;
   }
   if (!teams) return null;
@@ -299,14 +329,15 @@ const ts = (t) => {
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 };
 // a card's status is the workflow's (triaging, reviewing, …); kanban.db stores the Hermes status it maps to
-const line = (t) => `${ICONS[t.status] ?? '?'} ${t.id}  ${(t.stage ?? t.status).padEnd(8)}${['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
+const line = (t) => `${ICONS[t.status] ?? '?'} ${t.id}  ${(t.stage ?? t.status).padEnd(8)}${t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
 const cardDict = (t) => ({
   id: t.id, title: t.title, body: t.body, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant,
   workspace_kind: t.workspace_kind, repository: t.workspace_anchor ?? null, workspace_path: t.workspace_path, branch_name: t.branch_name, project_id: t.project_id,
   created_by: t.created_by, created_at: t.created_at, started_at: t.started_at, completed_at: t.completed_at, result: t.result,
   skills: t.skills ?? [], max_retries: t.max_retries, model_override: t.model_override, provider_override: t.provider_override,
   session_id: t.session_id, workflow_template_id: t.workflow_template_id, current_step_key: t.current_step_key,
-  machine: t.machine ?? null, subtask_of: t.subtask_of ?? null, execution: t.execution ?? null,
+  machine: t.machine ?? null, subtask_of: t.subtask_of ?? null, execution: t.execution ?? null, detached: t.detached ?? null,
+  reviewer: t.reviewer ?? null,
 });
 
 /** Hermes's durations: seconds, or 30s / 5m / 2h / 1d. */
@@ -337,12 +368,20 @@ const metadataOf = (v) => {
 
 /** One verb in full, in the call it runs in (call.mjs): a caller's in the owner, or the process's own here. */
 export async function runVerb(argv) {
-  await knowLocalMachine();
   const args = parse(argv);
+  assertSourceReceipt(args);
+  await ownerStep('machine identity', () => knowLocalMachine());
   const [verb, ...rest] = args._;
   if (!verb || verb === 'help' || args.help) { current().out(HELP); return 0; }
   const root = homeOf(args);
   if (verb === 'events') return streamBoardPublications({root,after:args.after,once:args.once});
+  if (verb === 'listeners') {
+    if (rest.length && rest[0] !== 'status') throw new Error('workflow listeners accepts status; declarations live in workflow.yaml listeners');
+    const orchestration = await readHome(root);
+    const status = { declarations: orchestration.workflow?.listeners ?? {}, ...fleetListenerStatus(root) };
+    say(args, JSON.stringify(status, null, 2), status);
+    return 0;
+  }
   // C4: one task store per Org. A named board without a store of its own is a saved view over it: its tag selects
   // the cards it shows, and a card filed through it carries that tag.
   const named = boardOf(root, args);
@@ -357,20 +396,35 @@ export async function runVerb(argv) {
 
   // a caller that is a card's own session (its harness names it; the board recorded which session it launched)
   const listing = ['list','ls'].includes(verb);
-  await loadWorkflow(root).catch((error) => { if (verb !== 'init' && verb !== 'boards') throw error; });
+  const readingDispatching = verb === 'dispatching' && rest.length === 0;
+  const reading = READS.has(verb) || readingDispatching;
+  // a listing on the owner's read door reads the workflow the owner holds (owner-door.mjs), and names no session: it
+  // records nothing, and `--mine` is the caller's profile
+  const readDoor = Boolean(current().readOnly);
+  if (!readDoor) await ownerStep('workflow', () => loadWorkflow(root)).catch((error) => { if (verb !== 'init' && verb !== 'boards') throw error; });
   // A listing does not authorize a transition and needs no manager's main session.
-  if (!listing) await readAgentMains(root);
-  const sid = listing && !args.mine ? null : callerSession();
+  if (!listing && !readingDispatching) await ownerStep('manager main sessions', () => readAgentMains(root));
+  const sid = listing && (!args.mine || readDoor) ? null : callerSession();
   // what this command records is the calling session's act (its address, as its subscriptions name it)
   current().recorded = sid && boardExists(root, slug) ? withBoard((b) => b.db.prepare(CALLER_RUN_ADDRESS).get(sid)?.address) ?? null : null;
   if (sid) setActor(callerAddress());
-  setPrincipal(await callerPrincipal(root, sid, { teams: !sid && !READS.has(verb) }));
+  const recordedAgent = sid && boardExists(root, slug)
+    ? await ownerStep('committed native agent ownership', () => withBoard((b) => recordedRunAgent(b.db, sid, callerAddress()))) : null;
+  setPrincipal(await ownerStep('caller principal', () => callerPrincipal(root, sid, { teams: !sid && !reading, recordedAgent })));
   // the dispatcher as the owner holds it, said once per call (owner-health.mjs; nothing is read for it)
   if (!current().said.has(`dispatcher:${slug}`)) { current().said.add(`dispatcher:${slug}`); for (const line of dispatcherNotice(slug)) current().err(`${line}\n`); }
-  if (sid && !READS.has(verb) && boardExists(root, slug)) {
+  if (sid && !reading && boardExists(root, slug)) {
     // binding the caller's launch is a write: only the owner, answering the caller's own verb, makes it (a local read
     // never writes)
-    await withBoardAsync(async (b) => { if (isCallersCall()) await reconcileCallerLaunch(b, sid); const own = { ...ownCards(b.db, sid), side: sideArcs(b.db, sid) }; if (own.worked.size || own.side.size) authorize(b.db, verb, rest, args, own); });
+    await withBoardAsync(async (b) => {
+      if (isCallersCall()) await reconcileCallerLaunch(b, sid);
+      const own = { ...ownCards(b.db, sid), side: sideArcs(b.db, sid) };
+      if (!own.worked.size && !own.side.size) return;
+      // A copied home owns no live sessions or manager addresses. Its owner may
+      // answer local verbs while every board's dispatching remains off.
+      const copyServe = verb === 'serve' && Boolean(boardCopyOf(b)) && listBoards(root).every(board => !dispatchingOf(root, board).on);
+      authorize(b.db, verb, rest, args, own, { copyServe });
+    });
   }
   // the board's workflow (the IR's): what each verb does, and who may send it, is its
   // every verb reads the board through its workflow (a list settles cards too), so every verb loads it
@@ -466,6 +520,7 @@ export async function runVerb(argv) {
       const sponsorship = args.sponsor || args['requested-by'] ? await requestedSponsor(args) : principalOf()?.startsWith('person:') ? { sponsor: principalOf().slice('person:'.length) } : {};
       const created = await withBoardAsync(async (b) => engine.createCard(b, await engine.prepareCard(b, {
         title: rest.join(' '), body: textFrom(args['body-file'], args.body), assignee: args.assignee === 'none' ? null : args.assignee, machine: args.machine,
+        reviewer: args.reviewer ?? null,
         workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
         triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: duration(args['max-runtime']),
         maxRetries, skills: args.skill, model: args.model, provider: args.provider, createdBy: args['created-by'] ?? null,
@@ -543,7 +598,12 @@ export async function runVerb(argv) {
         got.runs = got.runs.map(run => ({ ...run, execution: executionOf(run) }));
         got.diagnostics = engine.diagnose(b.db, got.task, { failureLimit: settings.failureLimit, launchWindowSeconds: settings.launchWindow });
         got.stage = statusOf(b.db, got.task);
-        got.time = scopeOf(b.db, b, got.task, { params: workflowFor(root).params }).card.time;
+        const entry = workflowFor(root);
+        // A workflow may explicitly replace the built-in time field. Keep its
+        // full derived scope; ordinary totals need only this card's runs.
+        got.time = Object.hasOwn(entry.workflow.derived ?? {}, 'time')
+          ? scopeOf(b.db, b, got.task, { params: entry.params }).card.time
+          : timeOf(b.db, got.task);
         return got;
       });
       const t = card.task;
@@ -554,6 +614,8 @@ export async function runVerb(argv) {
       }
       const out = [`Task ${t.id}: ${t.title}`, `  status:    ${taskStatusOf(card.stage, t.completed_at)} (lane ${card.stage}${card.stage !== t.status ? `, ${t.status} in kanban.db` : ''})`, `  assignee:  ${t.assignee || '-'}`];
       if (t.machine) out.push(`  machine:   ${t.machine}`);
+      if (t.reviewer) out.push(`  reviewer:  ${t.reviewer} (card override)`);
+      if (t.detached) out.push(`  session:   ${t.detached.session.address} belongs to ${t.detached.person} (detached ${ts(t.detached.at)}; dispatcher does not own it)`);
       // where the card's time went: each role's runs, and the rest waiting
       const mins = (sec) => `${Math.round(sec / 60)}m`;
       out.push(`  time:      ${Object.entries(card.time).filter(([, v]) => v > 0).map(([k, v]) => `${k} ${mins(v)}`).join(', ') || '-'}`);
@@ -587,7 +649,7 @@ export async function runVerb(argv) {
       if (card.comments.length) { out.push('', `Comments (${card.comments.length}):`); for (const c of card.comments) out.push(`  [${ts(c.created_at)}] ${c.author}: ${c.body}`); }
       // the card's history, without the board's own bookkeeping (a claim, a session kept or started, a goal ask, a
       // message queued); `--all` shows every event, `--json` always does
-      const PLUMBING = new Set(['claimed', 'session_started', 'session_resumed', 'session_adopted', 'session_replaced', 'session_closed',
+      const PLUMBING = new Set(['claimed', 'session_started', 'session_resumed', 'session_adopted', 'agent_session_queued', 'session_replaced', 'session_closed',
         'goal_set', 'goal_continued', 'decision_asked', 'board_message', 'board_message_sent', 'heartbeat', 'promoted', 'respawn_guarded',
         'claim_extended', 'reclaimed', 'reconciled', 'status']);
       const history = args.all ? card.events : card.events.filter((e) => !PLUMBING.has(e.kind));
@@ -600,7 +662,7 @@ export async function runVerb(argv) {
         for (const r of card.runs) {
           const s = r.metadata?.supercode;
           out.push(`  #${String(r.id).padEnd(3)} ${(r.outcome || r.status || 'active').padEnd(12)} @${r.profile || '-'}  ${r.ended_at ? `${Math.max(0, r.ended_at - r.started_at)}s` : 'active'}  ${ts(r.started_at)}`);
-          if (s) out.push(`        ⇢ ${s.session_id ? `session ${s.session_id}${s.pane ? ` in pane ${s.pane}` : ''}` : `worker pid ${s.pid}`} on ${s.machine} (${s.mode}); observed ${executionOf(r).state}`);
+          if (s) out.push(`        ⇢ ${s.session_id ? `session ${s.session_id}${s.pane ? ` in pane ${s.pane}` : ''}` : `worker pid ${s.pid}`} on ${s.machine} (${s.mode}); ${s.detached_at ? `handed to ${s.detached_to} at ${ts(s.detached_at)}` : `observed ${executionOf(r).state}`}`);
           if (r.summary) out.push(`        → ${r.summary.split('\n')[0].slice(0, 160)}`);
           if (r.error) out.push(`        ! ${r.error.split('\n')[0].slice(0, 160)}`);
         }
@@ -746,6 +808,14 @@ export async function runVerb(argv) {
       current().out(got.length ? `${got.map((a) => `#${a.id}  ${a.filename}  ${a.size} bytes  ${ts(a.created_at)}  ${a.stored_path}`).join('\n')}\n` : `(no attachments on ${id})\n`);
       return 0;
     }
+    case 'attachment-read': {
+      need(2, 'a card id and an attachment id');
+      const row = withBoard((b) => attachmentRecord(b.db, id, Number(rest[1])));
+      const range = await readAttachment(root, slug, row, { offset: args.offset === undefined ? 0 : Number(args.offset),
+        length: args.length === undefined ? undefined : Number(args.length), version: args.version ?? null });
+      current().out(`${JSON.stringify(range)}\n`);
+      return 0;
+    }
     case 'attach-rm': {
       need(1, 'an attachment id');
       const row = withBoard((b) => engine.removeAttachment(b, Number(id)));
@@ -756,7 +826,7 @@ export async function runVerb(argv) {
     case 'complete': {
       need(1, 'a card id');
       const metadata = metadataOf(args.metadata);
-      for (const t of rest) await withBoardAsync((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: metadata ?? null, commit: args.commit ?? null, ci_run: args['ci-run'] ?? null, pr: args.pr ?? null, pr_head: args['pr-head'] ?? null, reviewed_sha: args['reviewed-sha'] ?? null }));
+      for (const t of rest) await withBoardAsync((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: metadata ?? null, commit: args.commit ?? null, pr: args.pr ?? null, pr_head: args['pr-head'] ?? null, reviewed_sha: args['reviewed-sha'] ?? null }));
       say(args, rest.map((t) => `Completed ${t}`).join('\n'), { ok: true, completed: rest }); return 0;
     }
     case 'edit': {
@@ -786,7 +856,7 @@ export async function runVerb(argv) {
       if (args.reason) for (const [t] of results) await withBoardAsync((b) => engine.comment(b, t, callerName(), `UNBLOCK: ${args.reason}`));
       say(args, results.map(([t, s]) => `Unblocked ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
     }
-    case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, commit: args.commit ?? null, ci_run: args['ci-run'] ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args['pr-head'] ?? args.head ?? args.commit ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
+    case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, commit: args.commit ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args['pr-head'] ?? args.head ?? args.commit ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
     case 'request-changes': {
       need(2, 'a card id and the reason');
       // each finding is filed as a task on the arc first, so the arc stays open until a pushed head fixes it
@@ -1120,6 +1190,17 @@ export async function runVerb(argv) {
       const session = await withBoardAsync(b => startCard(b, id, { lanes, settings, roles: rolesFor(b.db, id, sid, workflowFor(root).params) }));
       say(args, `${id}: ${session?.address ?? 'started'}`, { ok: true, session }); return 0;
     }
+    case 'detach': {
+      need(1, 'a card id');
+      const person = args.to ?? (principalOf()?.startsWith('person:') ? principalOf() : null);
+      const detached = withBoard(b => {
+        const roles = rolesFor(b.db, id, sid, workflowFor(root).params);
+        if (!roles.includes('manager') && !(roles.includes('creator') && principalOf()?.startsWith('person:') && person === principalOf())) throw new Error('Only the manager or the signed-in person who created the card detaches its session.');
+        return detachSession(b, id, person);
+      });
+      say(args, `${id}: ${detached.session.address} belongs to ${detached.person}; the dispatcher no longer owns it`, { ok: true, detached });
+      return 0;
+    }
     case 'adopt': {
       need(2, 'a card id and a session');
       withBoard(b => { if (!rolesFor(b.db, id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager adopts an existing session.'); });
@@ -1161,7 +1242,7 @@ export async function runVerb(argv) {
       if (!declared) throw new Error(`no workflow verb ${verb}; \`supercode workflow help\` lists them`);
       need(1, 'a card id');
       const { _: _words, root: _r, board: _b, json: _j, at: _a, ids: _i, ...fields } = args;
-      const payload = { ...fields, ci_run: args['ci-run'] ?? fields.ci_run, deployed_sha: args['deployed-sha'] ?? fields.deployed_sha, reviewed_sha: args['reviewed-sha'] ?? fields.reviewed_sha, pr_head: args['pr-head'] ?? fields.pr_head, waiting_on: args['waiting-on'] ?? fields.waiting_on, reason: args.reason ?? (name === 'request_state' ? null : rest.slice(1).join(' ') || null) };
+      const payload = { ...fields, reviewed_sha: args['reviewed-sha'] ?? fields.reviewed_sha, pr_head: args['pr-head'] ?? fields.pr_head, waiting_on: args['waiting-on'] ?? fields.waiting_on, reason: args.reason ?? (name === 'request_state' ? null : rest.slice(1).join(' ') || null) };
       const results = [];
       if (name === 'request_state') results.push(...await withBoardAsync(board => engine.requestStateMany(board, [...rest, ...(args.ids ?? [])], payload)));
       else for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.act(b, t, name, { payload }))).to]);
@@ -1426,7 +1507,7 @@ function ownCards(db, sessionId) {
   return { worked, held };
 }
 
-const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'github-usage', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
+const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'attachment-read', 'github-usage', 'notify-list', 'capacity', 'help', 'init']);
 
 /** The main session of each agent the workflow names a manager (`sc:<machine>:agent:<name>`), asked of this machine's
  *  daemon, which keeps agents' records (mail step 1c), once per call before its verb runs: a manager named by its agent
@@ -1479,10 +1560,11 @@ function rolesFor(db, cardId, sessionId, params = {}) {
  * subtasks, and the subtasks of the arcs it is a side session of, and those arcs themselves only to comment on. What it
  * may do to them is the workflow's (rolesFor).
  */
-function authorize(db, verb, rest, args, own) {
+function authorize(db, verb, rest, args, own, { copyServe = false } = {}) {
   const cards = [...new Set([...own.worked, ...own.side])];
   const named = cards.join(', ');
   const refuse = (why) => { throw new Error(`the session working ${named} ${why}`); };
+  if (verb === 'serve' && copyServe) return;
   if (verb === 'create') {
     if (!own.worked.has(args['subtask-of']) && !own.side.has(args['subtask-of'])) refuse(`files subtasks of its own card only (--subtask-of ${cards.join(' or ')})`);
     return;
@@ -1490,7 +1572,7 @@ function authorize(db, verb, rest, args, own) {
   if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
   // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
   // (what a session may do to a card is its workflow's: each transition's `by`)
-  if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'release', 'close', 'claim', 'attach-rm', 'migrate'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
+  if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'release', 'detach', 'close', 'claim', 'attach-rm', 'migrate'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
   if (verb === 'set' && !(own.worked.has(rest[0]) && rest[1] === 'every')) refuse("sets only Every on its own auditor card; other properties are the manager's");
   if (args.all) refuse(`does not ${verb} every card; only its own`);
   if (['notify-subscribe', 'notify-unsubscribe'].includes(verb) && args['for-card']) {
@@ -1554,10 +1636,11 @@ function setDispatching(root, slug, on, reason) {
 
 /**
  * The owner's door: every card verb on this home's boards, from the CLI and the machine daemon's board door, answered
- * here in a call of its own (call.mjs), with the home this process holds. One owner per home, by an OS lock held for
- * its whole life by a holder process of its own (an exclusive SQLite lock on `<home>/board.lock`, released when the
- * owner ends and the holder's standard input closes): a second serve refuses, and only the lock's owner removes and
- * binds the socket.
+ * in a call of its own (call.mjs), with the home this process holds. The socket is served on a thread of its own
+ * (owner-door.mjs): a listing is read there, and every other verb is answered here, by the board's one writer. One owner
+ * per home, by an OS lock held for its whole life by a holder process of its own (an exclusive SQLite lock on
+ * `<home>/board.lock`, released when the owner ends and the holder's standard input closes): a second serve refuses,
+ * and only the lock's owner removes and binds the socket.
  */
 async function answerVerbs(root, log) {
   const home = boardHome(root);
@@ -1577,59 +1660,51 @@ async function answerVerbs(root, log) {
   log(`owner epoch ${epoch}`);
   const path = boardOwnerSocket(root);
   try { unlinkSync(path); } catch { /* none left */ }
-  // 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 owner's end
-      answerOne(root, line)
-        .catch((error) => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` }))
-        .then((answer) => writeOwnerAnswer(socket, answer))
-        .catch(() => { socket.destroy(); }); // a disconnected caller leaves no queued reply
-    });
-  });
-  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 */ }
+  let closeDoor;
+  try { closeDoor = await openOwnerDoor(root, { machine: localMachine(), answer: (line) => answerOne(root, line), log }); }
+  catch (error) { lock.release(); throw error; }
   log(`answering the card verbs of ${root} at ${path}`);
-  return () => { server.close(); try { unlinkSync(path); } catch { /* gone */ } lock.release(); };
+  return () => { closeDoor(); try { unlinkSync(path); } catch { /* gone */ } lock.release(); };
 }
 
-/** One request to the owner, answered whole: the verb run in the caller's call, its output kept for the answer. A
- *  verb that takes more than a second is a slow line of its own, with the steps that ended while it ran (its own and,
- *  in this one process, any other call's that held it) and what the whole process used over the verb's wall time
- *  (`whole_process`, slow-log.mjs processUse: every thread and every other call in flight, never the verb alone): its
- *  processor time beside the line's `ms` says whether the time was computed or waited for, and the block reads and
- *  major page faults say on what. */
-async function answerOne(root, line) {
-  const began = performance.now();
-  const before = slowLog.processCounters?.() ?? null;
-  let named = null, by = null;
-  let answer;
-  try { answer = await answerRequest(root, line, (verb, caller) => { named = verb; by = caller; }); return answer; }
-  finally {
-    const ms = performance.now() - began;
-    if (named) recordSlow({ kind: 'call', name: `owner verb ${named}`, ms, force: answer?.code !== 0,
-      outcome: answer ? answer.code === 0 ? 'ok' : `exit ${answer.code}` : 'unknown', slowest: null,
-      extra: { caller: by, response: { code: answer?.code ?? null, stderr: redactText([].concat(answer?.stderr ?? []).join('')).slice(0, 2000) },
-        steps: slowLog.stepsWithin?.(began, performance.now()) ?? null, whole_process: before ? slowLog.processUse(before) : null } });
-  }
+/** One request's own steps and the separate process activity during its wait.
+ * Show/list/comment/create also retain receipts below the slow-log threshold;
+ * absence from a slow-only log cannot prove those calls met the time bound. */
+export async function answerOne(root, line, { readOnly = false } = {}) {
+  const scoped = typeof slowLog.withStepScope === 'function';
+  const run = async () => {
+    const began = performance.now(), before = slowLog.processCounters?.() ?? null;
+    let named = null, by = null, answer = null, outcome = 'error';
+    try {
+      answer = await answerRequest(root, line, (verb, caller) => { named = verb; by = caller; }, { readOnly });
+      outcome = answer?.code === 0 ? 'ok' : `exit ${answer?.code ?? 'unknown'}`;
+      return answer;
+    } finally {
+      const ended = performance.now(), ms = ended - began;
+      // a listing the read door leaves to the owner is recorded there, as the owner answers it
+      if (named && !answer?.byOwner) {
+        const overlap = slowLog.stepsWithin?.(began, ended) ?? null;
+        const used = ms > slowLog.SLOW_MS && before ? slowLog.processUse(before) : null;
+        recordSlow({ kind: 'call', name: `owner verb ${named}`, ms, outcome, slowest: null, force: answer?.code !== 0,
+          includeFast: ['show', 'list', 'comment', 'create'].includes(named),
+          extra: { caller: by, code: answer?.code ?? null, response: { code: answer?.code ?? null, stderr: redactText([].concat(answer?.stderr ?? []).join('')).slice(0, 2000) }, step_scope: scoped ? 'request' : 'process_interval',
+            steps: scoped ? takeSteps() : overlap, ...(scoped ? { overlap_steps: overlap } : {}), ...(used ? { whole_process: used } : {}) } });
+      }
+    }
+  };
+  return scoped ? slowLog.withStepScope(run) : run();
 }
 
-async function answerRequest(root, line, naming) {
+/** One request answered in a call of its own; on the read door (`readOnly`) a listing only, and `{ byOwner: true }` for
+ *  one the owner is to answer (listing.mjs byOwner). */
+async function answerRequest(root, line, naming, { readOnly = false } = {}) {
   try {
     const request = JSON.parse(line);
     const tool = request?.tool && typeof request.tool.name === 'string' ? request.tool : null;
     const argv = tool ? ['tool'] : Array.isArray(request?.argv) && request.argv.every((arg) => typeof arg === 'string') ? request.argv : null;
     if (request?.v !== 1 || !argv?.length) return { code: 1, stdout: '', stderr: 'supercode workflow: a request names a verb\n' };
     const verb = parse(argv)._[0];
+    if (readOnly && (tool || !['list', 'ls'].includes(verb))) return { byOwner: true };
     if (BOARD_OPERATION_VERBS.has(verb)) return { code: 1, stdout: '', stderr: `supercode workflow: ${verb} is run on the board's machine as its own act, not sent to the owner\n` };
     const session = request.session && typeof request.session.id === 'string' && ['claude-code', 'codex'].includes(request.session.harness) ? request.session : null;
     const caller = typeof request.caller === 'string' ? request.caller : session ? `sc:${localMachine()}:${session.harness}:${session.id}` : null;
@@ -1642,13 +1717,17 @@ async function answerRequest(root, line, naming) {
     const stdin = typeof request.stdin === 'string' ? request.stdin : null;
     const stdout = [];
     const stderr = [];
-    let code;
-    await within({ caller, facts, cwd, stdin, out: (text) => { stdout.push(text); return true; }, err: (text) => { stderr.push(text); return true; } }, async () => {
+    let code, byOwner = false;
+    await within({ caller, facts, cwd, stdin, readOnly, out: (text) => { stdout.push(text); return true; }, err: (text) => { stderr.push(text); return true; } }, async () => {
       // a worker's board tool (mcp/server.mjs), answered by the board's tools in this call (board/tools.mjs)
       if (tool) { stdout.push(await boardTool(root, tool.name, tool.args && typeof tool.args === 'object' ? tool.args : {}, Object.fromEntries(Object.entries(tool.env ?? {}).filter(([key, value]) => /^HERMES_(KANBAN_TASK|KANBAN_RUN_ID|KANBAN_BOARD|PROFILE)$/.test(key) && typeof value === 'string')))); code = 0; return; }
       try { code = await runVerb([...argv, '--root', root, ...(typeof request.board === 'string' && request.board ? ['--board', request.board] : [])]); }
-      catch (error) { stderr.push(`supercode workflow: ${error?.message ?? error}\n`); code = 1; }
+      catch (error) {
+        if (readOnly && error?.code === READ_BY_OWNER) { byOwner = true; return; }
+        stderr.push(`supercode workflow: ${error?.message ?? error}\n`); code = 1;
+      }
     });
+    if (byOwner) return { byOwner: true };
     return { code: code ?? 0, stdout, stderr };
   } catch (error) {
     return { code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` };
@@ -1663,8 +1742,9 @@ async function serve(root, args = {}) {
   if (args.pidfile) writeFileSync(args.pidfile, `${process.pid}\n`);
   let stopped = false;
   let events;
+  let fleetListeners = null, reloadListeners = () => {}, listenerRevision = 0, listenerBootstrapped = false;
   // a signal ends the round in progress with nothing new started (dispatch.mjs stopDispatching) and no round after it
-  const stop = () => { stopped = true; stopDispatching(); events?.close(); };
+  const stop = () => { stopped = true; stopDispatching(); events?.close(); fleetListeners?.suspend(); };
   for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, stop);
   // what the serve says is kept in the home too (logs/workflow-serve.log), so why it stopped outlives its pane
   const kept = join(root, 'logs', 'workflow-serve.log');
@@ -1727,7 +1807,7 @@ async function serve(root, args = {}) {
   // the held home is read again on its next use after a file it is decoded from changes (file events, no interval),
   // watched before anything reads it; a watch that cannot be kept stops the owner, for its keeper to start it again
   const unfollowHome = followHome(root, {
-    onChange: (name) => log(`home changed (${name}): read again on its next use`),
+    onChange: (name) => { log(`home changed (${name}): read again on its next use`); listenerRevision++; listenerBootstrapped = false; fleetListeners?.suspend(); reloadListeners(); },
     onLost: (error) => { log(`the home's files can no longer be watched (${error.message}); stopping, for the keeper to start the owner again`); stop(); },
   });
   // Hermes's install is located once per process (a launch's memory snapshot reads it): here, before any verb is
@@ -1767,7 +1847,7 @@ async function serve(root, args = {}) {
   } });
   // a machine's panes changing in its record (a session came up under its pane, a pane or its session ended) is what a
   // round binds a launch, verifies an adoption and reads a session's end from: the next round is due then
-  onPanesChanged(() => events?.wake('machine-record'));
+  const unfollowPanes = onPanesChanged(() => events?.wake('machine-record'));
   // the owner holds its boards only now, its watch installed (watch before load): opened once, changed by events
   holdBoards(root);
   // a pause of the collector holds the loop like any synchronous step: each is a step, so a block line names it
@@ -1789,6 +1869,58 @@ async function serve(root, args = {}) {
   };
   await registerOwner();
   onLocalReopen(registerOwner);
+  let listenerRecords = {}, listenerReloading = null, listenerReloadDue = false, listenerReading = null;
+  const listenerErrors = new Set();
+  const listenerLog = text => { if (!listenerErrors.has(text)) { if (listenerErrors.size >= 128) listenerErrors.clear(); listenerErrors.add(text); log(text); } };
+  const scanListeners = ({ waiting = true } = {}) => listenerBootstrapped && fleetRecordsCurrent() && ownCall(() => observeRoleFleet(root, fleetListeners, listenerRecords, listenerLog, { waiting }));
+  const readListenerRecords = () => {
+    if (!fleetListeners.enabled || stopped || listenerReading) return listenerReading;
+    const revision = listenerRevision;
+    listenerReading = readFleetRecords().then(records => {
+      if (revision !== listenerRevision || !fleetListeners.enabled || stopped) return;
+      listenerRecords = records;
+      if (!listenerBootstrapped) { fleetListeners.bootstrap(records); listenerBootstrapped = true; scanListeners(); }
+    })
+      .catch(error => { listenerRecords = {}; listenerLog(`fleet listener records unread: ${String(error.message).slice(0, 300)}`); })
+      .finally(() => { listenerReading = null; });
+    return listenerReading;
+  };
+  fleetListeners = new FleetListenerRouter({ root, log: listenerLog,
+    file: (to, body, key) => ownCall(() => fileFleetNotice(root, to, body, key)),
+    enrich: event => ownCall(() => enrichFleetEvent(root, event)),
+    retry: () => scanListeners({ waiting: false }),
+  });
+  const unfollowRecords = onRecordsChanged(records => { listenerRecords = records; scanListeners(); });
+  reloadListeners = () => {
+    listenerReloadDue = true;
+    if (listenerReloading || stopped) return listenerReloading;
+    listenerReloading = (async () => {
+      while (listenerReloadDue && !stopped) {
+        listenerReloadDue = false;
+        const revision = listenerRevision;
+        try {
+          const orchestration = await ownCall(() => readHome(root));
+          if (revision !== listenerRevision || stopped) continue;
+          fleetListeners.configure(orchestration.workflow?.listeners ?? {});
+          if (fleetListeners.enabled) { scanListeners(); void readListenerRecords(); }
+        } catch (error) {
+          fleetListeners.suspend();
+          listenerLog(`fleet listener configuration unread; retained obligations wait: ${String(error.message).slice(0, 300)}`);
+          // A failed source read is retried by the next round; a failed home read also retains no stale intent.
+          listenerReloadDue = true; break;
+        }
+      }
+    })().finally(() => { listenerReloading = null; });
+    return listenerReloading;
+  };
+  await reloadListeners();
+  // Retry a failed home decode without waiting for a dispatch sweep. Reading the held stream also enforces its
+  // heartbeat deadline and reconnects after local caller loss, even when every board's dispatching is off.
+  let nextListenerRead = 0;
+  const listenerTimer = setInterval(() => {
+    if (listenerReloadDue) void reloadListeners();
+    if (Date.now() >= nextListenerRead) { nextListenerRead = Date.now() + 5000; void readListenerRecords(); }
+  }, 2000); listenerTimer.unref?.();
   log('dispatch wakes on board writes, document edits, board mail and a change of a machine\'s panes in its record; the interval sweep reads each machine\'s own door');
   const stuck = {};
   const warned = {};
@@ -1798,6 +1930,8 @@ async function serve(root, args = {}) {
   let wakeReason = null;
   try {
     while (!stopped) {
+      if (listenerReloadDue) void reloadListeners();
+      if (fleetListeners.enabled) scanListeners();
       // A serve never ticks on code older than the installed orchestrator: after its round it stops, and its keeper
       // starts the new one. Nothing waits for an installation; a second round, old or new, is harmless.
       const replaced = (() => { const now = installed(); return running && now && now !== running ? now : null; })();
@@ -1866,6 +2000,10 @@ async function serve(root, args = {}) {
       if (moved) { log(`orchestrator ${moved} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
     }
   } finally {
+    fleetListeners.suspend(); clearInterval(listenerTimer); unfollowRecords(); unfollowPanes();
+    await listenerReloading;
+    await listenerReading;
+    try { await fleetListeners.close(); } catch (error) { log(`fleet listener shutdown: retained filing outcome unknown (${String(error.message).slice(0, 300)})`); }
     // a fetch in flight lands, and what it brought is merged, while this owner still holds the home's lock
     try { const { settleDocuments } = await import('./git-document.mjs'); await settleDocuments(); } catch { /* nothing in flight */ }
     unwatchLoop?.(); releaseHeldBoards(); closeVerbs();