@volter/supercode-orchestrator 0.5.226 → 0.5.227

package/board/cli.mjs

@@ -12,15 +12,15 @@ import { BOARD_OPERATION_VERBS, boardHome, boardOwnerSocket, CALLER_FACTS } from
 import { current, isCallersCall, ownCall, within } from './call.mjs';
 import { cardState, holdDescription } from './card-state.mjs';
 import { detachSession } from './custody.mjs';
-import { taskStatusOf } from './published.mjs';
+import { reclaimSpace, taskStatusOf, trimDue, trimPublications } from './published.mjs';
 import { executionOf, readingContext } from './session-work.mjs';
 import { attachmentRecord, readAttachment } from './attachment-read.mjs';
 import { receiveAttachment } from './attachment-write.mjs';
 import { listCardsInTurns, READ_BY_OWNER, writeCardList } from './listing.mjs';
 import { redactGuardText as redactText, withCredentialGuard } from './credential-guard.mjs';
 import { openOwnerDoor } from './owner-door.mjs';
-import { inBoardGeneration, generationWork, admitGeneration, grantGenerationWriter, parkGeneration, stopGeneration, tellOwner } from './generation.mjs';
-import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+import { inBoardGeneration, generationWork, admitGeneration, grantGenerationWriter, parkGeneration, stopGeneration, tellOwner, admittedWork, GENERATION_STOPPED } from './generation.mjs';
+import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, statfsSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import { notRuntime, ownHome } from './owner-files.mjs';
 import { execFile, spawnSync } from 'node:child_process';
 import { supercodeInvocation } from '@volter/supercode-harness-sdk/supercode-program';
@@ -76,13 +76,13 @@ async function boardPublishing(root) {
   const board = listed?.boards?.find((b) => b.root === here);
   return board ? { ...board, refused: listed.refused ?? null } : null;
 }
-import { answerQuestion, dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, resumeDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
+import { answerQuestion, dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, closeEnded, lanesOf, localMachine, observeFleet, paused, plan, startCard, releaseClaims, stopDispatching, resumeDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
 import { watchBoard } from './wake.mjs';
 import { attachSideSession, releaseSideSession, sideArcs, sideSessions } from './side-sessions.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 { drainAgentCredentials, fileFleetNotice } from './dispatch.mjs';
 import { streamBoardPublications } from './event-stream.mjs';
 import { completionOwnerOf, followHome, isLatestReviewer, loadWorkflow, readHome, requestSessionClose, scopeOf, statusOf, timeOf, useWorkflow, workflowEntry, workflowFor, watchWorkflows } from './workflow.mjs';
 import { evaluate } from './expr.mjs';
@@ -101,18 +101,20 @@ const callerPath = (named) => notRuntime(resolve(current().cwd, named));
 const SAFE_SESSION = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
 
-A card is named by its id (t_4406c88a) or by its number, keyed or bare (VO-42, vo-42, #42 or 42): the short number the board
-gave it when it was made, read with the board's key, the first letters of the board's name.
+A card is named by its readable id (voice-calls), by its id (t_4406c88a) or by its number, keyed or bare (VO-42, vo-42, #42
+or 42): the short number the board gave it when it was made, read with the board's key, the first letters of the board's name.
+Its creator gives the readable id, a few lowercase words naming its outcome, unique on the board; it names the card's branch,
+worktree folder, sessions and agents.
 
 The board's verbs, with their flags:
   declaration [--json]   read the serving board declaration
   init [--backing sqlite|files|ztrack] [--document <arcs.md>] [--commit] [--manager <address>] [--dispatching on|off] [--archive-max-lines N] [--archive-period month]
   migrate --backing ztrack --document <arcs.md> --status-map <json>
   boards list|create|rm|switch|show|rename|set-default-workdir|export|import
-  create <title> [--readable-id ID] [--body | --body-file PATH|-] [--assignee] [--parent]... [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch] [--project]
+  create <title> --readable-id ID [--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] [--reviewer PROFILE] [--goal|--no-goal] [--goal-max-turns] [--initial-status blocked|running]
-  swarm <goal> --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
+  swarm <goal> --readable-id ID --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
   list [--mine] [--assignee] [--status] [--tenant] [--session] [--subtasks] [--archived] [--sort]   show <id>   context <id>   brief <id> [--run N]   runs <id>
   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)
@@ -120,11 +122,14 @@ The board's verbs, with their flags:
   comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)... | --pr none] [--source owner/repo:branch... | --source none]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   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]
+  person-done <id> --person person:<principal> (--result <answer> | --result-file PATH|-) [--workplace-task <Task id>]
+         a person's card (create/set --assignee person:<principal>) closes on that person's completion: the Workplace
+         integration reports it from the home; the board checks it names the card's person. Never a session's verb.
   finish <id> --result TEXT   (when declared: end your completed attempt; the board selects review)
   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] [--commit SHA]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>...   reopen <id>... [--reason]
+  unblock <id>... --on <blocker> --reason <what arrived>   request-review <id> [--plan] --pr URL --pr-head SHA [--summary] [--reviewer] [--force] [--commit SHA]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>... --reason <why> (voids the verdict, or restarts a review run that has none)   return-review <id> --reason <why> (manager: back to its coder, no verdict)   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... --reason <why> [--rm <id>...]
   specify <id> [--readable-id ID] [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
   decompose <id> [--child "<title>[@<profile>]"]... [--all]  file the card's subtasks atomically, if its workflow allows
@@ -132,7 +137,7 @@ The board's verbs, with their flags:
   github-usage [--since 1h]          local REST attempts by caller/endpoint; no GitHub read
   notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
   capacity   (each cap's count against its max, and why each card waits; docs/adr/0009-board-capacity.md)
-  dispatching [on|off] [--reason R]   dispatch [--dry-run] [--max N] [--failure-limit N]   daemon [--interval S] [--max N] [--failure-limit N] [--pidfile F] [--verbose]   gc [--event-retention-days] [--log-retention-days]   repair
+  dispatching [on|off] [--reason R]   dispatch [--dry-run] [--max N] [--failure-limit N]   daemon [--interval S] [--max N] [--failure-limit N] [--pidfile F] [--verbose]   gc [--event-retention-days] [--log-retention-days]   compact   repair
   pause [reason] · resume   (the board's emergency stop: new starts stop, running sessions go on)
 
 And:
@@ -154,7 +159,10 @@ And:
   handover --entry <orchestrator.mjs> --supercode <native>   prepare a board generation, retain its predecessor
   answer <id> <option>   choose an option (its number or label) of the question the card's session shows on its pane: the
       card's manager, its creator or a signed-in person; recorded on the card as question_answered with who answered
-  notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
+  notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency|participant]
+  notify-unsubscribe <id> [--address A]: stop following a card; the board says so on the card, and an @mention of you
+      (or your own comment) brings you back. A comment's author and everyone it @mentions (@manager, @sc:<address>,
+      @<agent>) follow the card; every comment reaches every follower but its author.
   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.
   Any verb … --at sc:<machine>:board:<home>: applied on that board through this machine's board door, as this session; its answer and exit code are the board's.
@@ -167,7 +175,8 @@ And:
   specify <id> --workspace … --machine M: declares the workspace on M and moves the card there, never asking the machine it leaves.
   comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the arc's repositories (its workspace, its declared sources, its tasks'), each followed at its current head; each declaration adds to the earlier ones, on any run, and --pr none alone clears them. This records evidence; only the board starts its review.
   comment <arc> TEXT --source owner/repo:branch...: the arc's implementer or the manager declares every repository and branch the arc changes, on the arc itself; its review discovers PRs from them and accepts --pr declarations in them, with no task registered there. Each declaration adds to the earlier ones, and --source none alone clears them.
-  request-review <id> (--pr URL --pr-head SHA)...: hand over every open PR the arc changed, each at its pushed head; one review covers them all.
+  request-review <id> --pr URL --pr-head SHA [--summary "<what the PR does>"]: hand one ready PR to its PR review at its pushed head, whatever other PRs the arc has; merge it at that head once the review passes. A request naming its PR is a PR review.
+  request-review <id> --plan --pr URL --pr-head SHA: a big arc's plan review, of the proposed ADR's PR at its pushed head, before any code. The arc's final review (of every PR not merged at a PR-reviewed head, with its Acceptance) is the board's.
   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.
@@ -342,7 +351,7 @@ 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 = (key) => (t) => `${ICONS[t.status] ?? '?'} ${engine.cardLabel(key, t.number, t.id, t.readable_id).padEnd(18)}  ${(['paused','blocked'].includes(t.status) ? t.status : t.stage ?? t.status).padEnd(8)}${holdDescription(t) ? ` [${holdDescription(t)}]` : t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}${t.execution?.reason ? ` — ${t.execution.reason}` : ''}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
+const line = (key) => (t) => `${ICONS[t.status] ?? '?'} ${engine.cardLabel(key, t.number, t.id, t.number ? t.readable_id : null).padEnd(32)}  ${(['paused','blocked'].includes(t.status) ? t.status : t.stage ?? t.status).padEnd(8)}${holdDescription(t) ? ` [${holdDescription(t)}]` : t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}${t.execution?.reason ? ` — ${t.execution.reason}` : ''}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
 // `key` is the card's board's (store.mjs boardKey); `ref` the card as a person names it (`VO-856`)
 const stateOptions = root => ({ nativeHolds: Boolean(workflowFor(root).workflow.flags?.paused) });
 const cardDict = (raw, key, options) => { const t = cardState(raw, options); return ({
@@ -388,13 +397,14 @@ const metadataOf = (v) => {
 // included). A number no card here has, or a key that is not this board's, is refused. A key is two or more letters, so
 // a message id (`m-…`, `a-…`) is never read as one.
 const NO_CARD_WORDS = new Set(['create', 'new', 'swarm', 'list', 'ls', 'migrate', 'init', 'boards', 'usage', 'events', 'listeners', 'dispatch',
-  'capacity', 'deliver', 'daemon', 'serve', 'gc', 'repair', 'dispatching', 'attach-rm', 'run-session', 'stats', 'assignees', 'diagnostics', 'diag',
+  'capacity', 'deliver', 'daemon', 'serve', 'gc', 'compact', 'repair', 'dispatching', 'attach-rm', 'run-session', 'stats', 'assignees', 'diagnostics', 'diag',
   'watch', 'help', 'github-usage']);
 // the verbs that act on every positional as a card (each loops over them all)
 const ALL_CARD_WORDS = new Set(['complete', 'archive', 'request-state', 'request_state', 'set-goal', 'unblock', 'reopen', 'reopen-review']);
 const CARD_FLAGS = ['ids', 'subtask-of', 'parent', 'on', 'for-card', 'task', 'rm'];
 const CARD_NUMBER = /^(?:#|([A-Za-z][A-Za-z0-9]+)-)?([1-9]\d*)$/;
-function resolveCardNumbers(verb, rest, args, withBoard, keyOf) {
+const READABLE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function resolveCardNumbers(verb, rest, args, withBoard, keyOf, exists) {
   const words = NO_CARD_WORDS.has(verb) ? 0 : ALL_CARD_WORDS.has(verb) ? rest.length : ['link', 'unlink'].includes(verb) ? 2 : 1;
   const places = [];
   for (let i = 0; i < Math.min(words, rest.length); i++) places.push([rest, i]);
@@ -403,9 +413,12 @@ function resolveCardNumbers(verb, rest, args, withBoard, keyOf) {
     else if (typeof args[flag] === 'string') places.push([args, flag]);
   }
   const numbered = places.filter(([holder, key]) => CARD_NUMBER.test(String(holder[key])));
-  if (!numbered.length) return;
+  // a card named by its readable id (`voice-calls`) is that card, where one is; any other word stays as it was said
+  const named = exists() ? places.filter(([holder, key]) => !CARD_NUMBER.test(String(holder[key])) && READABLE_ID.test(String(holder[key]))) : [];
+  if (!numbered.length && !named.length) return;
   const own = keyOf();
   withBoard((b) => view(b, (db) => {
+    for (const [holder, at] of named) holder[at] = engine.cardByReadableId(db, String(holder[at])) ?? holder[at];
     for (const [holder, at] of numbered) {
       const [, named, digits] = CARD_NUMBER.exec(String(holder[at]));
       if (named && named.toUpperCase() !== own) throw new Error(`${holder[at]} names a card of board ${named.toUpperCase()}, not of this board (${own}); nothing was done`);
@@ -448,7 +461,7 @@ export async function runVerb(argv) {
   const withBoardAsync = async (fn, create = false) => { const b = open(create); try { return await fn(b); } finally { b.close(); } };
   // the board's key (store.mjs boardKey), read when a card is named or shown by its number
   const keyOf = () => boardKey(root, slug);
-  resolveCardNumbers(verb, rest, args, withBoard, keyOf);
+  resolveCardNumbers(verb, rest, args, withBoard, keyOf, () => boardExists(root, slug));
   const id = rest[0];
   const need = (n, what) => { if (rest.length < n) throw new Error(`${verb} needs ${what}`); };
   const ids = (first = rest) => [...first, ...(args.ids ?? [])];
@@ -600,7 +613,7 @@ export async function runVerb(argv) {
       // thread records the start. A create never runs a dispatch tick inline.
       // the creator hears what happens from here on; a start answered above is not told twice
       const address = args['no-notify'] ? null : args.notify ?? callerAddress();
-      if (address) withBoard((b) => engine.subscribe(b, created.id, address, 'creator'));
+      if (address) withBoard((b) => engine.subscribe(b, created.id, address, 'creator', { own: true }));
       const task = withBoard((b) => view(b, (db) => engine.getTask(db, created.id)));
       const recipients = withBoard(b => engine.subscriptions(b.db, created.id)).filter(s => s.platform === 'supercode').map(s => s.chat_id);
       if (args.json) { say(args, '', { ...cardDict(task, keyOf(), stateOptions(root)), ...answer, notify: address ?? null, recipients }); return answer.failed ? 1 : 0; }
@@ -617,7 +630,7 @@ export async function runVerb(argv) {
         return { profile, title, skills: skills ? skills.split(',').map((x) => x.trim()).filter(Boolean) : [] };
       });
       if (!args.verifier || !args.synthesizer) throw new Error('a swarm names its --verifier and --synthesizer');
-      const made = withBoard((b) => engine.swarm(b, { goal: rest.join(' '), workers, verifier: args.verifier, synthesizer: args.synthesizer, tenant: args.tenant ?? null, createdBy: args['created-by'] ?? null, priority: Number(args.priority) || 0, idempotencyKey: args['idempotency-key'] ?? null }), true);
+      const made = withBoard((b) => engine.swarm(b, { goal: rest.join(' '), readableId: args['readable-id'], workers, verifier: args.verifier, synthesizer: args.synthesizer, tenant: args.tenant ?? null, createdBy: args['created-by'] ?? null, priority: Number(args.priority) || 0, idempotencyKey: args['idempotency-key'] ?? null }), true);
       say(args, `Swarm root: ${made.root_id}\nWorkers: ${(made.worker_ids ?? []).join(', ')}\nVerifier: ${made.verifier_id}\nSynthesizer: ${made.synthesizer_id}`, made);
       return 0;
     }
@@ -672,10 +685,10 @@ export async function runVerb(argv) {
         say(args, '', { task: cardDict(t, keyOf(), stateOptions(root)), sources: withBoard((b) => arcSources(b.db, t.id)), side_sessions: withBoard((b) => sideSessions(b.db, t.id)), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, time: card.time, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
         return 0;
       }
-      const labels = withBoard((b) => view(b, (db) => engine.numbersOf(db, [t.subtask_of, ...card.parents.map((p) => p.id), ...card.children].filter(Boolean))));
       const boardKeyNow = keyOf();
-      const label = (cardId) => engine.cardLabel(boardKeyNow, labels.get(cardId), cardId);
-      const out = [`Task ${engine.cardLabel(boardKeyNow, t.number, t.id, t.readable_id)}: ${t.title}`, `  status:    ${['paused','blocked'].includes(t.status) ? t.status : taskStatusOf(card.stage, t.completed_at)} (lane ${card.stage})`, `  assignee:  ${t.assignee || '-'}`];
+      const labels = withBoard((b) => view(b, (db) => engine.labelsOf(db, boardKeyNow, [t.subtask_of, ...card.parents.map((p) => p.id), ...card.children].filter(Boolean))));
+      const label = (cardId) => labels.get(cardId) ?? cardId;
+      const out = [`Task ${engine.cardLabel(boardKeyNow, t.number, t.id, t.subtask_of ? null : t.readable_id)}: ${t.title}`, `  status:    ${['paused','blocked'].includes(t.status) ? t.status : taskStatusOf(card.stage, t.completed_at)} (lane ${card.stage})`, `  assignee:  ${t.assignee || '-'}`];
       if (holdDescription(t)) out.push(`  hold:      ${holdDescription(t)}`);
       if (t.machine) out.push(`  machine:   ${t.machine}`);
       if (t.reviewer) out.push(`  reviewer:  ${t.reviewer} (card override)`);
@@ -853,6 +866,8 @@ export async function runVerb(argv) {
 
     case 'comment': {
       need(args.file !== undefined ? 1 : 2, 'a card id and the text (or --file PATH, - for stdin)');
+      // A comment's text comes from --file or from its words, never both: words beside --file were dropped unread.
+      if (args.file !== undefined && rest.length > 1) throw new Error(`comment ${id} takes its text from --file or from words, not both; unexpected: ${JSON.stringify(rest.slice(1).join(' ').slice(0, 120))}. Nothing was recorded.`);
       let text = textFrom(args.file, rest.slice(1).join(' '));
       if (args['max-len']) text = text.slice(0, Number(args['max-len']));
       const n = await withBoardAsync((b) => engine.comment(b, id, isLatestReviewer(b.db, id, actorOf()) ? actorOf() : args.author ?? callerAddress() ?? callerName(), text, { pr: args.pr ?? null, pr_head: args['pr-head'] ?? null, source: args.source ?? null }));
@@ -908,6 +923,25 @@ export async function runVerb(argv) {
       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;
     }
+    // A person completed the card assigned to them, reported by the Workplace integration through the home it serves
+    // (sdk/teams/workplace/organization.mjs), as the board's own platform event; a session never reports one.
+    case 'person-done': {
+      need(1, 'a card id');
+      if (sid) throw new Error('A person\'s completion is reported by the Workplace integration from the home, never by a session; nothing was done.');
+      // The board's refusal (the card is no person's, or another person's, or already ended) is said with exit code 2: the
+      // reporter does not send it again. Any other failure is the reporter's to retry; the same report again is `already`.
+      let done;
+      try { done = await withBoardAsync((b) => engine.personDone(b, id, { person: args.person ?? null, result: textFrom(args['result-file'], args.result), task: args['workplace-task'] ?? null })); }
+      catch (error) {
+        // the card's refusal is final, as dispatch.mjs takes a moved card's (a transition that does not apply there), and
+        // so is an answer refused as a credential dump: sent again, it is refused again
+        if (!error.refusal && !error.noTransition && !/does not apply|there is for/.test(String(error.message)) && error.code !== 'credential_dump') throw error;
+        say(args, `${id} refused ${args.person ?? 'the person'}'s completion: ${error.message}`, { ok: false, card: id, person: args.person ?? null, refused: error.message });
+        return 2;
+      }
+      say(args, done.already ? `${id} was already completed by ${args.person}` : `Completed ${id} for ${args.person}`, { ok: true, card: id, person: args.person, already: done.already });
+      return 0;
+    }
     case 'edit': {
       need(1, 'a card id');
       if (args.result === undefined) throw new Error('edit needs --result');
@@ -935,7 +969,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, 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, plan: Boolean(args.plan), 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: the arc's review is due again once every one is closed (ci.mjs answeredChanges)
@@ -955,8 +989,17 @@ export async function runVerb(argv) {
     case 'reopen-review': {
       need(1, 'a card id');
       const results = [];
-      for (const t of ids()) results.push([t, (await withBoardAsync((b) => engine.reopenReview(b, t, { reason: args.reason ?? null }))).to]);
-      say(args, results.map(([t, s]) => `Reopened ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
+      for (const t of ids()) { const moved = await withBoardAsync((b) => engine.reopenReview(b, t, { reason: args.reason ?? null })); results.push([t, moved.to, moved.restarted_run ?? null]); }
+      // a review still running with no verdict is restarted, not voided: its run ends, its reviewer session is closed and
+      // the board's next review run resumes that same session with the round's brief
+      say(args, results.map(([t, s, run]) => run ? `Restarted ${t}'s review: run ${run} ended with no verdict and its reviewer session was closed; the board's next review run resumes it (${s}). No verdict was voided.` : `Reopened ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
+    }
+    case 'return-review': {
+      // the manager's door out of review: a card there by mistake goes back to its coder, its review run ending as returned
+      need(1, 'a card id');
+      const reason = args.reason ?? (rest.slice(1).join(' ') || null);
+      const moved = await withBoardAsync((b) => engine.returnReview(b, id, { reason }));
+      say(args, `Returned ${id} from review → ${moved.to}: its review run ended as returned with no verdict; its coder continues, and the board reviews again once a pushed PR head changes.`, { ok: true, ...moved }); return 0;
     }
     case 'promote': {
       need(1, 'a card id');
@@ -1000,7 +1043,7 @@ export async function runVerb(argv) {
       for (const t of targets) {
         if (verb === 'specify' && (args['readable-id'] !== undefined || args.title !== undefined || args.body !== undefined || args['body-file'] !== undefined || args.workspace !== undefined || args.branch !== undefined || args.machine !== undefined)) {
           const moved = await withBoardAsync((b) => engine.specify(b, t, { readableId: args['readable-id'] ?? null, title: args.title ?? null, body: textFrom(args['body-file'], args.body) ?? null, workspace: args.workspace ?? null, branch: args.branch ?? null, machine: args.machine ?? null, author: args.author ?? callerAddress() ?? callerName() }));
-          results.push({ id: t, specified: true, status: moved.to });
+          results.push({ id: t, specified: true, status: moved.to, from: moved.from, moved: Boolean(moved.moved) });
         } else if (verb === 'decompose' && args.child?.length) {
           const children = args.child.map((c) => { const [title, assignee] = c.split(/@(?=[^@]*$)/); return { title: title.trim(), assignee: assignee?.trim() || undefined }; });
           results.push({ id: t, children: await withBoardAsync((b) => engine.decompose(b, t, children, { author: args.author ?? callerAddress() ?? callerName() })) });
@@ -1009,7 +1052,7 @@ export async function runVerb(argv) {
           results.push({ id: t, session: session.address, mode: session.mode });
         }
       }
-      say(args, results.map((r) => (r.specified ? `Specified ${r.id} → ${r.status}` : r.children ? `Decomposed ${r.id} into ${r.children.join(', ')}` : `${r.id}: session ${r.session} (${r.mode}) is writing its ${verb === 'specify' ? 'spec' : 'breakdown'}`)).join('\n'), results);
+      say(args, results.map((r) => (r.specified ? (r.moved ? `Specified ${r.id}: ${r.from} → ${r.status}` : `Specified ${r.id}; it stays ${r.status}`) : r.children ? `Decomposed ${r.id} into ${r.children.join(', ')}` : `${r.id}: session ${r.session} (${r.mode}) is writing its ${verb === 'specify' ? 'spec' : 'breakdown'}`)).join('\n'), results);
       return 0;
     }
 
@@ -1050,7 +1093,7 @@ export async function runVerb(argv) {
       if (!existsSync(file)) {
         // a pane session keeps no log file: its transcript is the harness's own, named by the run
         const s = withBoard((b) => view(b, (db) => engine.lastSession(db, id)));
-        current().out(s ? `(${id} runs as session ${s.address}; its transcript is that session's: \`supercode sessions show ${s.session_id}\`)\n` : `(no log for ${id})\n`);
+        current().out(s ? `(${id} runs as session ${s.address}; its transcript is that session's, read on whichever machine holds it: \`supercode sessions show ${s.address ?? s.session_id}\`)\n` : `(no log for ${id})\n`);
         return 0;
       }
       const text = readFileSync(file, 'utf8');
@@ -1092,13 +1135,18 @@ export async function runVerb(argv) {
       const platform = args.platform ?? 'supercode';
       const chat = args['chat-id'] ?? args.address ?? (platform === 'supercode' ? callerAddress() : null);
       if (!chat) throw new Error(`${verb} names the subscriber: --platform P --chat-id C (a supercode session's address with --platform supercode)`);
+      // a supercode follower's unsubscribe is the card's (engine.unsubscribe: kept, said on the card); a chat's ends here
+      if (verb === 'notify-unsubscribe' && platform === 'supercode' && !args['thread-id']) {
+        const gone = withBoard((b) => engine.unsubscribe(b, id, chat));
+        say(args, gone ? `Unsubscribed ${chat} from ${id}; mention @${engine.mentionName(chat)} on the card to bring them back` : `${chat} was not subscribed to ${id}`, { ok: gone }); return gone ? 0 : 1;
+      }
       if (verb === 'notify-unsubscribe') {
         const gone = withBoard((b) => tx(b, (db) => db.prepare('DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = ? AND chat_id = ? AND thread_id = ?').run(id, platform, chat, args['thread-id'] ?? '').changes > 0));
         say(args, gone ? `Unsubscribed ${platform}:${chat} from ${id}` : `${platform}:${chat} was not subscribed to ${id}`, { ok: gone }); return gone ? 0 : 1;
       }
       withBoard((b) => tx(b, (db) => {
         if (!engine.getTask(db, id)) throw new Error(`no card ${id}`);
-        if (platform === 'supercode') return engine.subscribeIn(db, id, chat, args.role ?? 'creator');
+        if (platform === 'supercode') return engine.subscribeIn(db, id, chat, args.role ?? 'creator', { explicit: true });
         const cursor = db.prepare('SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?').get(id).c;
         db.prepare(`INSERT INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, user_id, user_id_alt, chat_type, notifier_profile, delivery_mode, created_at, last_event_id)
                     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(task_id, platform, chat_id, thread_id) DO UPDATE SET chat_type = COALESCE(excluded.chat_type, chat_type), delivery_mode = excluded.delivery_mode`)
@@ -1110,7 +1158,7 @@ export async function runVerb(argv) {
     case 'notify-list': {
       const subs = withBoard((b) => engine.subscriptions(b.db, id ?? null));
       if (args.json) { say(args, '', subs); return 0; }
-      current().out(subs.length ? `${subs.map((s) => `${s.task_id}  ${s.platform}:${s.chat_id}${s.thread_id ? `#${s.thread_id}` : ''}  ${s.platform === 'supercode' ? s.delivery_metadata?.role ?? 'creator' : s.delivery_mode}  cursor=${s.last_event_id}`).join('\n')}\n` : '(no subscriptions)\n');
+      current().out(subs.length ? `${subs.map((s) => `${s.task_id}  ${s.platform}:${s.chat_id}${s.thread_id ? `#${s.thread_id}` : ''}  ${s.platform === 'supercode' ? `${s.delivery_metadata?.role ?? 'creator'}${s.delivery_metadata?.unsubscribed ? ' (unsubscribed)' : ''}` : s.delivery_mode}  cursor=${s.last_event_id}`).join('\n')}\n` : '(no subscriptions)\n');
       return 0;
     }
 
@@ -1121,7 +1169,7 @@ export async function runVerb(argv) {
         // planned through the workflow's own dispatch (its start event, eligible, order and limits), writing nothing
         const reports = await plan({ root, lanes, settings, params, slugs: [slug] });
         const would = reports.flatMap((r) => r.would), reviews = reports.flatMap((r) => r.would_review ?? []);
-        const lines = [...reviews.map((r) => `would request review of ${r.id}: ${r.no_code ? r.no_code.kind === 'disposition' ? 'scratch operational disposition (card evidence and closed tasks)' : `no code changed (${r.no_code.repository} ${r.no_code.branch} holds no commit beyond ${r.no_code.base}, no PR from it)` : r.prs.map((url, i) => `${url} at ${r.heads[i]}`).join(', ')}`),
+        const lines = [...reviews.map((r) => `would request review of ${r.id}: ${r.no_code ? r.no_code.kind === 'disposition' ? 'scratch operational disposition (card evidence and closed tasks)' : `no code changed (${r.no_code.repository} ${r.no_code.branch} holds no commit beyond ${r.no_code.base}, no PR from it)` : [...r.prs.map((url, i) => `${url} at ${r.heads[i]}`), ...(r.pr_reviewed ?? []).map((p) => `${p.url} at ${p.head} (settled by its PR review)`)].join(', ')}`),
           ...would.map((w) => `would start ${w.id} (${w.status}${w.role ? `, its ${w.role}` : ''}) as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`)];
         say(args, lines.length ? lines.join('\n') : 'nothing would start', args.json ? { would, would_review: reviews, queued: reports.flatMap(r => r.queued ?? []) } : would);
         return 0;
@@ -1142,12 +1190,12 @@ export async function runVerb(argv) {
       const reports = await plan({ root, lanes, settings });
       const out = { capacity: reports.capacity, would: reports.flatMap((r) => r.would.map((w) => w.id)), waiting: reports.flatMap((r) => r.queued.map(([id, why]) => ({ id, why }))) };
       if (args.json) { say(args, '', out); return 0; }
-      // each card as a person reads it, by the number its own board gave it
+      // each card as a person reads it, by its readable id and the number its own board gave it
       const shown = [...out.would, ...out.waiting.map((w) => w.id), ...out.capacity.flatMap((cap) => cap.groups.flatMap((g) => g.cards))];
       const labels = new Map();
       for (const board of listBoards(root)) {
         const b = openBoard(root, board);
-        try { const own = boardKey(root, board); for (const [cardId, n] of view(b, (db) => engine.numbersOf(db, shown))) labels.set(cardId, engine.cardLabel(own, n, cardId)); } finally { b.close(); }
+        try { const own = boardKey(root, board); for (const [cardId, label] of view(b, (db) => engine.labelsOf(db, own, shown))) labels.set(cardId, label); } finally { b.close(); }
       }
       const label = (cardId) => labels.get(cardId) ?? cardId;
       const lines = [];
@@ -1200,6 +1248,44 @@ export async function runVerb(argv) {
       say(args, `GC complete: ${removedWs} workspace(s), ${events} event row(s), ${logs} log file(s) removed`, { workspaces: removedWs, events, logs });
       return 0;
     }
+    case 'compact': {
+      // The store gives its free pages back to the volume (published.mjs reclaimSpace), answered by the board's owner on
+      // its own connection: the first time a rebuild, which holds the board's writer (and the owner) while it copies
+      // every live page, later a slice; then its WAL is checkpointed and cut. It deletes nothing a reader reads.
+      const sized = (file) => { try { return statSync(file).size; } catch { return 0; } };
+      const report = await withBoardAsync(async (b) => {
+        // the store's own file, as its connection names it (a ztrack board's path is its marker; its store is beside it)
+        const path = b.db.prepare('PRAGMA database_list').all().find((d) => d.name === 'main')?.file;
+        if (!path) throw new Error(`board ${slug} has no store file to compact`);
+        const onDisk = () => sized(path) + sized(`${path}-wal`);
+        const vacuum = (sql) => (b.vacuum ? b.vacuum(sql) : b.db.exec(sql));
+        const pageSize = Number(b.db.prepare('PRAGMA page_size').get().page_size);
+        const pages = () => Number(b.db.prepare('PRAGMA page_count').get().page_count), free = () => Number(b.db.prepare('PRAGMA freelist_count').get().freelist_count);
+        const before = { pages: pages(), free: free(), bytes: onDisk() }, began = performance.now();
+        // The older changes still stored complete are cut first, one transaction a slice as the owner's wakes do, the
+        // owner answering other calls between slices, so the rebuild gives back what they held. A slice that moves the
+        // trim nowhere ends it.
+        let trimmed = 0;
+        const through = () => { try { return JSON.parse(b.db.prepare("SELECT value FROM supercode_board_state WHERE key = 'publication_trim'").get()?.value ?? 'null')?.through ?? null; } catch { return null; } };
+        while (trimDue(b.db)) {
+          const at = through();
+          trimmed += b.tx((db) => trimPublications(db));
+          if (through() === at) break;
+          await new Promise((done) => setImmediate(done));
+        }
+        // The rebuild writes a copy of every live page and a WAL as large: it runs only with twice that and 1 GB more free
+        // on the store's volume, and says so otherwise.
+        const live = (pages() - free()) * pageSize, room = statfsSync(dirname(path)), available = Number(room.bavail) * Number(room.bsize);
+        if (available < 2 * live + 1024 ** 3) return { trimmed, refused: `the rebuild needs ${Math.ceil((2 * live + 1024 ** 3) / 1048576)} MB free on the store's volume and ${Math.floor(available / 1048576)} MB are`, pages_before: before.pages, free_before: before.free };
+        reclaimSpace(b.db, vacuum);
+        // the WAL is cut once no reader holds it; a reader that does is waited for, a few times, then left to a later checkpoint
+        for (let tries = 0; tries < 5 && sized(`${path}-wal`) > 0; tries++) { vacuum('PRAGMA wal_checkpoint(TRUNCATE)'); if (sized(`${path}-wal`) > 0) await new Promise((done) => setTimeout(done, 1000)); }
+        return { trimmed, reclaimed_bytes: before.bytes - onDisk(), wal_bytes: sized(`${path}-wal`), pages_before: before.pages, free_before: before.free, pages_after: pages(), free_after: free(), seconds: Math.round((performance.now() - began) / 100) / 10 };
+      });
+      if (report.refused) { say(args, `${report.trimmed} older change(s) cut; no rebuild: ${report.refused}`, report); return 1; }
+      say(args, `${report.trimmed} older change(s) cut; the store and its WAL are ${Math.round(report.reclaimed_bytes / 1048576)} MB smaller on disk after ${report.seconds} s (${report.pages_before} pages, ${report.free_before} free, to ${report.pages_after}, ${report.free_after} free; WAL ${report.wal_bytes} bytes)`, report);
+      return 0;
+    }
     case 'repair': {
       const path = boardPath(root, slug);
       if (!existsSync(path)) { say(args, `No kanban DB at ${path} — nothing to repair.`, { status: 'missing', db_path: path }); return 0; }
@@ -1380,14 +1466,19 @@ async function boardsVerb(root, rest, args) {
       const slug = normalSlug(target);
       if (slug === DEFAULT_BOARD) throw new Error("the 'default' board cannot be removed");
       if (!existsSync(boardDir(root, slug))) throw new Error(`board '${slug}' does not exist`);
+      // Every machine this board handed an agent's own Workplace records keeps none of them from here; one that cannot
+      // be told now is named, and its lease there ends the copy while that machine's daemon runs (dispatch.mjs
+      // drainAgentCredentials).
+      const left = boardExists(root, slug) ? await drainAgentCredentials(root, slug) : [];
+      const leftLine = left.length ? `\n  Agent credentials not yet removed (each ends at its lease while that machine's daemon runs): ${left.map((each) => `${each.agent} on ${each.machine} by ${each.leaseUntil ?? 'a day after its last keep'}`).join('; ')}` : '';
       if (boardOf(root, {}) === slug) rmSync(currentFile(root), { force: true });
-      if (args.delete || action === 'delete') { rmSync(boardDir(root, slug), { recursive: true, force: true }); say(args, `Board '${slug}' deleted.`, { slug, action: 'deleted' }); return 0; }
+      if (args.delete || action === 'delete') { rmSync(boardDir(root, slug), { recursive: true, force: true }); say(args, `Board '${slug}' deleted.${leftLine}`, { slug, action: 'deleted', agent_credentials_left: left }); return 0; }
       const archive = join(root, 'kanban', 'boards', '_archived');
       mkdirSync(archive, { recursive: true });
       let dest = join(archive, `${slug}-${now()}`);
       for (let n = 1; existsSync(dest); n += 1) dest = join(archive, `${slug}-${now()}-${n}`);
       renameSync(boardDir(root, slug), dest);
-      say(args, `Board '${slug}' archived → ${dest}`, { slug, action: 'archived', new_path: dest });
+      say(args, `Board '${slug}' archived → ${dest}${leftLine}`, { slug, action: 'archived', new_path: dest, agent_credentials_left: left });
       return 0;
     }
     case 'switch': case 'use': {
@@ -1701,7 +1792,7 @@ function authorize(db, verb, rest, args, own, { copyServe = false } = {}) {
   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', 'detach', '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', 'compact', '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']) {
@@ -1736,7 +1827,7 @@ async function closeSession(board, id) {
 export function summary(r) {
   const parts = [`board ${r.board}:`];
   if (r.error) parts.push(`error ${r.error}`);
-  for (const [k, label] of [['mailed', 'mailed updates'], ['started', 'started'], ['queued', 'waiting'], ['failed', 'failed'], ['lost', 'lost'], ['crashed', 'crashed'], ['timed_out', 'timed out'], ['reclaimed', 'reclaimed'], ['auto_blocked', 'gave up'], ['notified', 'notices'], ['closed', 'closed sessions'], ['undelivered', 'undelivered (retrying)'], ['subscriptions_ended', 'worker subscriptions to ended sessions ended']]) {
+  for (const [k, label] of [['mailed', 'mailed updates'], ['started', 'started'], ['queued', 'waiting'], ['failed', 'failed'], ['lost', 'lost'], ['crashed', 'crashed'], ['timed_out', 'timed out'], ['reclaimed', 'reclaimed'], ['retired', 'retired unheld runs'], ['auto_blocked', 'gave up'], ['notified', 'notices'], ['closed', 'closed sessions'], ['undelivered', 'undelivered (retrying)'], ['subscriptions_ended', 'worker subscriptions to ended sessions ended']]) {
     if (r[k]?.length) parts.push(`${label} ${r[k].length}`);
   }
   if (r.promoted) parts.push(`promoted ${r.promoted}`);
@@ -1808,7 +1899,7 @@ async function answerVerbs(root, log) {
  * 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 } = {}) {
-  if (inBoardGeneration && !readOnly) return generationWork(() => answerOneAdmitted(root, line));
+  if (inBoardGeneration && !readOnly) return generationWork(() => answerOneAdmitted(root, line), 'a card verb');
   return answerOneAdmitted(root, line, { readOnly });
 }
 
@@ -1938,11 +2029,23 @@ export async function serveBoardGeneration(root, args = {}, argv = ['serve', '--
         // handles, nothing more, and the successor takes a fresh epoch that fences any older writer anyway.
         say('park: dispatching stopped; admission closes');
         stopDispatching();
-        await parkGeneration(async () => {
+        // The admitted work a park still waits on is named every 2 s, in the log and as the park's step to the owner, so
+        // a park that outlives the owner's wait says what held it: pin H's on 2026-10-24 (predecessor 25904, 20:38:29Z)
+        // said nothing after admission closed, and the owner's refusal named the generation's first round from 20:28.
+        const waiting = setInterval(() => {
+          const held = admittedWork();
+          if (!held.length) return;
+          say(`park: waiting on ${held.length} admitted work: ${held.join('; ')}`);
+          tellOwner({ type: 'startup-step', phase: 'parking', step: `park: waiting on ${held.join('; ')}` });
+        }, 2_000);
+        waiting.unref?.();
+        try { await parkGeneration(async () => {
           say('park: admitted work drained; settling documents');
           const { settleDocuments } = await import('./git-document.mjs'); await settleDocuments();
           say('park: documents settled');
-        });
+          // its claims end here, while it still writes: a parked generation outlives its park (dispatch.mjs releaseClaims)
+          try { say(`park: ${releaseClaims(root)} claim(s) released`); } catch (error) { say(`park: claims not released (${error.message}); they hold until their TTL`); }
+        }); } finally { clearInterval(waiting); }
         say('park: the writer given up');
         retireHeldBoards();
         tellOwner({ type: 'parked' });
@@ -2134,11 +2237,13 @@ async function serve(root, args = {}) {
     if (stopped || !fleetListeners.enabled || !listenerBootstrapped || !fleetRecordsCurrent()) return;
     const revision = listenerRevision;
     try {
-      await ownCall(() => {
+      await ownCall(function listenerScan() {
         if (stopped || revision !== listenerRevision || !fleetListeners.enabled || !fleetRecordsCurrent()) return;
         observeRoleFleet(root, fleetListeners, listenerRecords, listenerLog, { waiting });
       });
-    } catch {
+    } catch (error) {
+      // A scan its stopping generation refused never ran, and this generation scans nothing again: said as that.
+      if (error?.code === GENERATION_STOPPED) { listenerLog(`fleet listener scan not run: ${error.message}`); return; }
       // Every caller may schedule this without awaiting it. Preparation refusal leaves source cursors untouched;
       // the next admitted scan retries the retained observations, while the owner's public door stays available.
       listenerLog('fleet listener scan refused; retained observations wait for a prepared owner call');
@@ -2157,10 +2262,10 @@ async function serve(root, args = {}) {
     return listenerReading;
   };
   fleetListeners = new FleetListenerRouter({ root, log: listenerLog,
-    file: (to, body, key) => ownCall(() => fileFleetNotice(root, to, body, key)),
+    file: (to, body, key) => ownCall(() => fileFleetNotice(root, to, body, key), 'a fleet notice'),
     // The scan/flush prepares custody once; enqueue needs the event synchronously before committing its cursor.
     enrich: event => enrichFleetEvent(root, event),
-    work: ownCall,
+    work: fn => ownCall(fn, 'the listener flush'),
     retry: () => scanListeners({ waiting: false }),
   });
   const unfollowRecords = onRecordsChanged(records => { listenerRecords = records; scanListeners(); });
@@ -2172,11 +2277,14 @@ async function serve(root, args = {}) {
         listenerReloadDue = false;
         const revision = listenerRevision;
         try {
-          const orchestration = await ownCall(() => readHome(root));
+          const orchestration = await ownCall(() => readHome(root), 'the home read');
           if (revision !== listenerRevision || stopped) continue;
           fleetListeners.configure(orchestration.workflow?.listeners ?? {});
           if (fleetListeners.enabled) { scanListeners(); void readListenerRecords(); }
         } catch (error) {
+          // A home read its stopping generation refused never ran: nothing is suspended and nothing is retried here, as
+          // this generation serves no further round; its successor reads the configuration itself.
+          if (error?.code === GENERATION_STOPPED) { listenerLog(`fleet listener configuration not read: ${error.message}`); break; }
           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.
@@ -2223,22 +2331,33 @@ async function serve(root, args = {}) {
       wakeReason = null;
       const loopStep = async (name, fn) => { const at = performance.now(); try { return await fn(); } finally { noteStep(`owner loop: ${name}`, performance.now() - at); } };
       try {
-        const state = await loopStep('lane state', () => ownCall(() => laneState(root)));
+        const state = await loopStep('lane state', () => ownCall(() => laneState(root), 'the lane state'));
         const settings = { ...state.settings, ...override };
         interval = settings.interval;
         // Publishing is the owner's, dispatching or not: what a writer outside this process marked changed is published
         // on the wake its write caused, and the retained history kept bounded (store.mjs publishMarked).
-        const published = await loopStep('publish marked', () => ownCall(async () => publishMarked(root)));
+        const published = await loopStep('publish marked', () => ownCall(async () => publishMarked(root), 'publishing marked cards'));
         if (published && args.verbose) log(`published ${published} card(s) a writer outside the owner changed`);
         // Dispatching is a controller over the boards whose own state says it is on; the owner answers verbs either way.
         const dispatching = listBoards(root).filter((slug) => dispatchingOf(root, slug).on);
-        const reports = dispatching.length ? await ownCall(() => tick({ root, lanes: state.lanes, settings, params, slugs: dispatching, deploymentReceipt: true })) : [];
-        if (inBoardGeneration && generationServingDue && reports.every(report => !report.error)) {
+        // The first round's budget bounds its progress: each phase it ends and each door call that settles is a step, said
+        // with the step's budget, so a round slow only on another machine's answers is not ended for its length.
+        const progress = inBoardGeneration && generationServingDue
+          ? (step) => tellOwner({ type: 'startup-step', phase: 'serving', step: `completing the first native board round (${step})`, budget_ms: 65000 }) : null;
+        const reports = dispatching.length ? await ownCall(() => tick({ root, lanes: state.lanes, settings, params, slugs: dispatching, deploymentReceipt: true, progress }), 'the dispatch round') : [];
+        if (inBoardGeneration && generationServingDue && !reports.cut && reports.every(report => !report.error)) {
           activationSaid(`the first native board round is clean (${dispatching.length} dispatching board(s))`);
           generationServingDue = false;
           tellOwner({ type: 'serving', pid: process.pid, boards: listBoards(root) });
         }
-        // with dispatching off on every board the owner only answers verbs: no round, no delivery, nothing told
+        // A board whose dispatching is off runs no round and is delivered nothing; only its close pass runs, so an ended
+        // run's session still closes (dispatching off stops launches, not closes).
+        const resting = listBoards(root).filter((slug) => !dispatching.includes(slug));
+        const closes = resting.length && !stopped ? await loopStep('close pass', () => ownCall(() => closeEnded({ root, slugs: resting, settings }), 'the close pass')) : [];
+        for (const r of closes) {
+          if (r.error || r.closed.length || args.verbose) log(summary(r));
+          for (const [t, to, why] of r.undelivered) log(`  close of ${to} for ${t} waits: ${why}`);
+        }
         if (dispatching.length) {
           round += 1;
           // what the round recorded is delivered by a pass of its own, which this loop never waits for
@@ -2264,8 +2383,11 @@ async function serve(root, args = {}) {
           for (const [t, to, why, what] of r.undelivered) log(what === 'close' ? `  close of ${to} for ${t} waits: ${why}` : `  notice for ${t} to ${to} not filed: ${why}`);
         }
       } catch (error) {
-        log(`tick failed: ${error.message}`);
-        if (!stopped) await watchRounds([{ board: '*', error: `tick failed: ${error.message}` }], began);
+        if (error?.code === GENERATION_STOPPED) log(`round not run: ${error.message}`);
+        else {
+          log(`tick failed: ${error.message}`);
+          if (!stopped) await watchRounds([{ board: '*', error: `tick failed: ${error.message}` }], began);
+        }
       }
       // each round is a line of its own in the slow log, with the steps it spent its time on
       recordSlow({ kind: 'call', name: 'dispatch round', ms: Date.now() - began, slowest: null, extra: { steps: takeSteps() } });

package/board/custody.mjs

@@ -3,7 +3,11 @@ import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 import { actorOf, claimer, event, json, now, tx } from './store.mjs';
 
-export const sessionAddress = s => s?.address ?? (s?.machine && s?.harness && s?.session_id ? `sc:${s.machine}:${s.harness}:${s.session_id}` : null);
+/** The person a card is assigned to (`person:<Teams principal>`, the form callerPrincipal gives a signed-in person), or
+ * null for a card a profile works. A person's card is a dependency on that person: the board starts no session for it,
+ * no review judges it, and it closes when that person completes it (workflow `complete`, from `person-done`). */
+export const personOf = (assignee) => /^person:\S+$/.test(String(assignee ?? '')) ? String(assignee) : null;
+export const sessionAddress = s => s?.address ??(s?.machine && s?.harness && s?.session_id ? `sc:${s.machine}:${s.harness}:${s.session_id}` : null);
 export const detachedCard = (db, id) => json(db.prepare('SELECT detached FROM supercode_cards WHERE task_id=?').get(id)?.detached, null);
 export const personCustody = (db, address) => address ? db.prepare('SELECT * FROM supercode_session_custody WHERE address=?').get(address) ?? null : null;
 export const detachedSession = (db, session) => Boolean(session?.detached_at || personCustody(db, sessionAddress(session)));