@volter/supercode-orchestrator 0.5.228 → 0.5.229

package/board/engine.mjs

@@ -1,3 +1,5 @@
+import { latestEvent, latestEventIdSql } from './queries.mjs';
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 import { allocateReadableId, cardReadableId, requireReadableId, validateReadableId } from './readable-id.mjs';
 // The board's transitions (docs/architecture/orchestrator.md §2.9): what a card may do, written for supercode and
 // kept to Hermes Kanban's lifecycle so the two read each other's boards. Statuses: triage · todo · scheduled ·
@@ -8,22 +10,28 @@ import { allocateReadableId, cardReadableId, requireReadableId, validateReadable
 //
 // Each function takes an open board (`store.mjs`) and runs in one write transaction. Nothing here launches,
 // observes or sends: the dispatcher (`dispatch.mjs`) does, and records what it did through these.
-import { current } from './call.mjs';
+import { current, refuseUnreadManager } from './call.mjs';
+import { randomBytes } from 'node:crypto';
+import { redactValue } from '@volter/teams/redact';
+import { backlogQualification, deadlineUntil } from './resting-state.mjs';
 import { detachedCard, detachedSession, personCustody, personOf, sessionAddress, sessionOperation } from './custody.mjs';
 import { executionOf, readingContext } from './session-work.mjs';
 import { cardState, cardStateSql, holdDescription } from './card-state.mjs';
 import { spawn, execFile } from 'node:child_process';
 import { existsSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
-import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace, plainWorkspace } from './workspace.mjs';
+import { checkWorkspace, assertWorkspaceOwner, cardWorktrees, declareWorkspace, isLocalWorkspace, plainWorkspace } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { CARD_VISIBILITY_SQL } from './visibility.mjs';
-import { view, actorOf, principalOf, cardBranch, CARD_NUMBERS, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
-import { arcRepositories, arcSources, assertSourceReceipt, completionPhase, outsideArcRepositories, inspectCompletionEvidence, observeCompletionEvidence, recordedArcRepositories, withCompletionEvidence } from './ci.mjs';
-import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, reviewerOf, eventTo, fire, validateEvent, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, transitionsFor, workflowFor } from './workflow.mjs';
+import { view, actorOf, setActor, principalOf, cardBranch, CARD_NUMBERS, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
+import { preparePrEvidence, prDisposition, redeclaredSince, releaseReadback, arcRepositories, arcSources, assertSourceReceipt, completionPhase, outsideArcRepositories, inspectCompletionEvidence, observeCompletionEvidence, recordedArcRepositories, withCompletionEvidence, declaredPullRequests, candidatePullRequests, pendingReviewRequests, latestReviewRequest, openPrReviewFindings, prIdentity } from './ci.mjs';
+import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, reviewerOf, eventTo, fire, validateEvent, loadWorkflow, setStatus, settle, settleExpiringFlags, startNew, statusOf, runEvent, transitionsFor, workflowFor, scopeOf, ownerRule, requestDetail } from './workflow.mjs';
 import { refuseCredentialDump, withheldIfDump } from './credential-guard.mjs';
 import { AGENT_KIND_LIST, compactCardAgentEvents } from './published.mjs';
 
+const { toMdast } = createRequire(import.meta.url)('@volter/ztrack/preset-kit');
+
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'paused', 'review', 'done', 'archived'];
 export const WORKSPACE_KINDS = ['scratch', 'dir', 'worktree'];
 /** A card blocked this many times in a row for the same kind goes to triage for a person (Hermes's limit). */
@@ -70,7 +78,7 @@ export function getTask(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) return null;
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, number: numberOf(db, id), stage: ours?.stage ?? row.status, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), detached: json(ours?.detached, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null,
+  return { ...row, number: numberOf(db, id), stage: ours?.stage ?? row.status, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), backlog: json(ours?.backlog, null), detached: json(ours?.detached, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null,
     tags: json(ours?.tags, null) ?? (row.tenant ? [row.tenant] : []), requested_by_unverified: json(ours?.requested_by_unverified, null) };
 }
 
@@ -100,8 +108,23 @@ export function parseWorkspace(word = 'scratch') {
  * seconds later. The wait runs in a detached shell, so the board's write lock is never held through it.
  */
 function terminate(pid) {
-  try { process.kill(-pid, 'SIGTERM'); } catch { try { process.kill(pid, 'SIGTERM'); } catch { return; } }
-  spawn('/bin/sh', ['-c', 'for i in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$0" 2>/dev/null || exit 0; sleep 0.5; done; kill -KILL -"$0" 2>/dev/null || kill -KILL "$0" 2>/dev/null', String(pid)], { detached: true, stdio: 'ignore' }).unref();
+  try { stopWorkChild(pid, () => process.kill(-pid, 'SIGTERM'), { signal: 'SIGTERM' }); } catch { try { stopWorkChild(pid, () => process.kill(pid, 'SIGTERM'), { signal: 'SIGTERM' }); } catch { return; } }
+  stopWorkChild(pid, () => new Promise((accepted) => {
+    // Starting the delayed shell is not acceptance of its eventual signal. It
+    // reports only a successful kill; disappearing during the wait is a no-op.
+    const escalation = spawn('/bin/sh', ['-c', 'for i in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$0" 2>/dev/null || exit 0; sleep 0.5; done; if kill -KILL -"$0" 2>/dev/null || kill -KILL "$0" 2>/dev/null; then printf "stopped\\n" >&3; else exit 1; fi', String(pid)], { detached: true, stdio: ['ignore', 'ignore', 'ignore', 'pipe'] });
+    let result = '';
+    escalation.stdio[3].on('data', (chunk) => {
+      if (result.length + chunk.length > 8) { accepted(false); return; }
+      result += chunk;
+      if (result === 'stopped\n') accepted(true);
+    });
+    escalation.stdio[3].once('error', () => accepted(false));
+    escalation.once('error', () => accepted(false));
+    escalation.once('close', () => accepted(false));
+    escalation.stdio[3].unref();
+    escalation.unref();
+  }), { signal: 'SIGKILL' });
 }
 
 /** Close the card's open run; answers its id, or null when none was open. */
@@ -155,7 +178,7 @@ export function lastSession(db, taskId, slot = 'worker') {
   // a session slot's own last session (runs recorded before slots existed are the worker's)
   for (const row of all(db, 'SELECT metadata FROM task_runs WHERE task_id = ? AND metadata IS NOT NULL ORDER BY id DESC', taskId)) {
     const s = json(row.metadata, {})?.supercode;
-    if (s?.session_id && (s.slot ?? 'worker') === slot) return detachedSession(db, s) ? null : s;
+    if (s?.session_id && !(s.launch_not_issued && s.mode === 'fresh' && s.close_confirmed_at) && (s.slot ?? 'worker') === slot) return detachedSession(db, s) ? null : s;
   }
   return null;
 }
@@ -194,17 +217,27 @@ function projectOf(root, idOrSlug) {
  * its subtasks, and leave the body. A Tasks section with no task line is the body's own text.
  */
 export function bodyTasks(body) {
-  const lines = String(body ?? '').split('\n');
-  const at = lines.findIndex((line) => /^#{2,3}\s+Tasks\s*$/i.test(line));
+  const text = String(body ?? ''), lines = text.split('\n'), literal = new Set();
+  // Section/filed-task syntax belongs to prose. Rent CommonMark's literal ranges so fenced or indented examples
+  // and HTML blocks keep their text, including headings and checkbox lines that only look like filing instructions.
+  const walk = node => {
+    if ((node.type === 'code' || node.type === 'html') && node.position) {
+      for (let i = node.position.start.line - 1; i < node.position.end.line; i++) literal.add(i);
+      return;
+    }
+    for (const child of node.children ?? []) walk(child);
+  };
+  walk(toMdast(text));
+  const at = lines.findIndex((line, i) => !literal.has(i) && /^#{2,3}\s+Tasks\s*$/i.test(line));
   if (at < 0) return { body, tasks: [] };
-  let end = lines.findIndex((line, i) => i > at && /^#{1,3}\s/.test(line));
+  let end = lines.findIndex((line, i) => i > at && !literal.has(i) && /^#{1,3}\s/.test(line));
   if (end < 0) end = lines.length;
   const section = lines.slice(at + 1, end);
-  if (!section.some((line) => /^[-*] \[[ xX]\]/.test(line))) return { body, tasks: [] };
+  if (!section.some((line, i) => !literal.has(at + 1 + i) && /^[-*] \[[ xX]\]/.test(line))) return { body, tasks: [] };
   const tasks = [];
-  for (const line of section) {
+  for (const [i, line] of section.entries()) {
     if (!line.trim()) continue;
-    const step = /^[-*] \[ \]\s+(\S.*)$/.exec(line);
+    const step = !literal.has(at + 1 + i) && /^[-*] \[ \]\s+(\S.*)$/.exec(line);
     if (step) tasks.push({ title: step[1].trim(), body: [] });
     else if (/^\s+\S/.test(line) && tasks.length) tasks.at(-1).body.push(line.replace(/^\s{1,4}/, ''));
     else throw new Error("A card's Tasks section holds open task lines ('- [ ] <step>', each filed as a subtask, with its own indented lines); record finished work as a comment and move other text out of the section");
@@ -276,7 +309,7 @@ export function createCard(board, spec) {
       throw new Error('A card reviewer names a runnable profile in this home.');
     }
     if (spec.subtaskOf && !arc) throw new Error(`no card ${spec.subtaskOf} to be a subtask of`);
-    if (arc?.subtask_of) throw new Error(`${arc.id} is itself a subtask of ${arc.subtask_of}; a subtask belongs to an arc`);
+    if (arc?.subtask_of) throw new Error(`${arc.id} is itself a subtask of ${arc.subtask_of}; subtasks are one level deep, so file it with --subtask-of ${arc.subtask_of}`);
     let id = newTaskId();
     while (one(db, 'SELECT 1 FROM tasks WHERE id = ?', id)) id = newTaskId();
     // where a card's blocks are relations, a card created blocked names what it waits on: one that names nothing is
@@ -441,22 +474,96 @@ export function extendClaim(db, id, { ttl, reason, extra = {} }) {
 }
 
 /**
- * A completed card's workspace goes, as Hermes cleans up on completion: a scratch directory under the board's own
- * workspaces, or a worktree (its branch stays); never while a child still waits on it or another open card works in
- * it, never a `dir`.
+ * A closed card's workspace goes, as Hermes cleans up on completion: the solo worktree the board made for it (its
+ * branch stays), and with `scratch` a scratch directory under the board's own workspaces; never while a child still
+ * waits on it or another open card works in it, never a `dir`. A close the board queues on its own (retire_workspace)
+ * retires only the worktree; a scratch folder goes where a workflow declares cleanup_workspace, or at gc. The worktree
+ * goes only through its machine's git, and only when that loses nothing (retireWorktree): its branch merged into origin's
+ * default branch (by ancestry, `git cherry`, a squash reading, or within a head the card's or its arc's
+ * `reviewed_merged` merged), its tree clean apart from ignored files, and no repository nested inside it. One that is
+ * not is kept, and the card says once which path holds what. Answers whether a worktree was removed.
  */
-async function cleanupWorkspace(board, id) {
+export async function cleanupWorkspace(board, id, { scratch = true } = {}) {
   const task = view(board, (db) => getTask(db, id));
-  if (!task?.workspace_path || !isLocalWorkspace(task) || !['scratch', 'worktree'].includes(task.workspace_kind)) return;
-  const waiting = view(board, (db) => one(db, "SELECT 1 FROM task_links l JOIN tasks t ON t.id = l.child_id WHERE l.parent_id = ? AND t.status NOT IN ('done', 'archived') LIMIT 1", id)
+  if (!task || !(scratch ? ['scratch', 'worktree'] : ['worktree']).includes(task.workspace_kind)) return;
+  // a card reopened before its cleanup ran keeps its workspace
+  if (!['done', 'cancelled', 'archived'].includes(task.status)) return;
+  const waiting = view(board, (db) => one(db, "SELECT 1 FROM task_links l JOIN tasks t ON t.id = l.child_id WHERE l.parent_id = ? AND t.status NOT IN ('done', 'archived', 'cancelled') LIMIT 1", id)
     ?? one(db, "SELECT 1 FROM tasks WHERE workspace_path = ? AND id <> ? AND status NOT IN ('done', 'archived', 'cancelled') LIMIT 1", task.workspace_path, id));
-  if (waiting || !existsSync(task.workspace_path)) return;
-  // awaited, never a wait that holds the event loop
-  if (task.workspace_kind === 'worktree') { await new Promise((resolve) => execFile('git', ['-C', task.workspace_path, 'worktree', 'remove', '--force', task.workspace_path], { encoding: 'utf8' }, () => resolve())); return; }
+  if (waiting) return;
+  if (task.workspace_kind === 'worktree') {
+    let removed = false;
+    for (const allocation of view(board, db => cardWorktrees(db, task))) {
+      const shared = view(board, db => one(db, "SELECT 1 FROM tasks WHERE workspace_path=? AND id<>? AND status NOT IN ('done','archived','cancelled') LIMIT 1", allocation.path, id));
+      if (shared) continue;
+      removed = await retireCardWorktreeOf(board, { ...task, machine: allocation.machine, workspace_path: allocation.path, branch_name: allocation.branch }) || removed;
+    }
+    return removed;
+  }
+  if (!task.workspace_path) return;
+  if (!isLocalWorkspace(task) || !existsSync(task.workspace_path)) return;
   const managed = resolve(board.slug === 'default' ? join(board.root, 'kanban', 'workspaces') : join(board.root, 'kanban', 'boards', board.slug, 'workspaces'));
   if (resolve(task.workspace_path).startsWith(`${managed}/`)) rmSync(task.workspace_path, { recursive: true, force: true });
 }
 
+/** Card `task`'s worktree retired on its machine (cleanupWorkspace), once the card's sessions are closed and no live
+ *  pane there works in it: `worktree_removed` when it went, else the card's comment naming the path, its branch's
+ *  unmerged commits by subject and its changed files by count (or why the folder is never removed), written once for each
+ *  such reading. A session is closed when its record says so or its machine reads its pane and process gone (one held
+ *  after its run, monitored, or closed by hand). Throws while a session may still work there or the machine could not
+ *  answer, so the effect is tried again. A recorded merge counts only where it merged (`merge`), never a release-only
+ *  settlement. Answers whether it removed the worktree. */
+async function retireCardWorktreeOf(board, task) {
+  const { panesUnder, sessionGone } = await import('./dispatch.mjs');
+  const { retireWorktree, worktreePresent } = await import('./workspace.mjs');
+  // a folder already gone is nothing to read panes or sessions for; it is recorded so, once, and gc reads it no more
+  const gone = () => tx(board, (db) => {
+    const last = latestEvent(db, task.id, ['worktree_kept', 'worktree_removed'], 'kind', "json_extract(payload,'$.path')=?", [task.workspace_path]);
+    if (last?.kind !== 'worktree_removed') event(db, task.id, 'worktree_removed', { path: task.workspace_path, gone: true });
+    return false;
+  });
+  const resolved = await worktreePresent(task.machine, task.workspace_path);
+  if (!resolved) return gone();
+  const recorded = view(board, (db) => {
+    if (getTask(db, task.id)?.current_run_id) return { current: true, open: [] };
+    const latest = new Map();
+    for (const row of db.prepare('SELECT metadata FROM task_runs WHERE task_id = ? ORDER BY id DESC').all(task.id)) {
+      const s = json(row.metadata, {})?.supercode;
+      if (s && !latest.has(s.slot ?? 'worker')) latest.set(s.slot ?? 'worker', s);
+    }
+    return { current: false, open: [...latest.values()].filter((s) => (s.pane || s.session_id || s.pid || s.launch_key) && !(s.close_confirmed_at || s.close_transferred_to || s.forgotten || s.detached_at)) };
+  });
+  if (recorded.current) throw new Error(`${task.id}: worktree ${task.workspace_path} waits: its run is still current`);
+  const live = [];
+  for (const s of recorded.open) if (!(await sessionGone(s))) live.push(s.address ?? s.pane ?? s.session_id ?? s.pid);
+  if (live.length) throw new Error(`${task.id}: worktree ${task.workspace_path} waits: its session ${live.join(', ')} is not closed`);
+  const panes = await panesUnder(task.machine, task.workspace_path, [resolved]);
+  if (panes.length) throw new Error(`${task.id}: worktree ${task.workspace_path} waits: live pane ${panes.join(', ')} works in it`);
+  const merged = view(board, (db) => db.prepare("SELECT payload FROM task_events WHERE task_id IN (?, ?) AND kind = 'reviewed_merged'").all(task.id, task.subtask_of ?? task.id))
+    .flatMap((row) => json(row.payload, {})?.merges ?? []).filter((m) => m?.merge && !m.release_only).map((m) => m.reviewed)
+    .filter((sha) => typeof sha === 'string' && /^[0-9a-f]{40}$/.test(sha));
+  // reopened while its machine was read: it keeps its worktree
+  if (!['done', 'cancelled', 'archived'].includes(view(board, (db) => getTask(db, task.id))?.status)) return false;
+  const answer = await retireWorktree(task.machine, task.workspace_path, { merged: [...new Set(merged)], branch: task.branch_name ?? null });
+  if (answer.gone) return gone();
+  const held = { path: answer.path, branch: answer.branch ?? null, base: answer.base ?? null, unmerged: answer.unmerged ?? [], modified: answer.modified ?? 0, untracked: answer.untracked ?? 0, reason: answer.reason ?? null, refused: Boolean(answer.refused) };
+  tx(board, (db) => {
+    if (answer.removed) { event(db, task.id, 'worktree_removed', { path: held.path, branch: held.branch, base: held.base }); return; }
+    const previous = latestEvent(db, task.id, ['worktree_kept', 'worktree_removed'], 'kind,payload', "json_extract(payload,'$.path')=?", [task.workspace_path]);
+    const last = json(previous?.payload, null);
+    if (previous?.kind === 'worktree_kept' && last && Object.keys(held).every((key) => JSON.stringify(last[key]) === JSON.stringify(held[key]))) return;
+    event(db, task.id, 'worktree_kept', held);
+    const shown = held.unmerged.slice(0, 20).map((subject) => `\n- ${subject}`).join('') + (held.unmerged.length > 20 ? `\n- … and ${held.unmerged.length - 20} more` : '');
+    const body = `Worktree ${held.path} is kept${task.machine ? ` on ${task.machine}` : ''}: ${held.reason}.`
+      + (held.branch ? ` Branch ${held.branch}${held.base ? ` against origin/${held.base}` : ''}.` : '')
+      + (held.unmerged.length ? ` Unmerged commits:${shown}` : '')
+      + (held.modified || held.untracked ? `${held.unmerged.length ? '\n' : ' '}Files: ${held.modified} tracked change(s), ${held.untracked} untracked.` : '');
+    event(db, task.id, 'commented', { author: 'board', len: body.length, by: 'board' });
+    run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', task.id, 'board', body, now());
+  });
+  return Boolean(answer.removed);
+}
+
 
 
 
@@ -475,40 +582,239 @@ async function cleanupWorkspace(board, id) {
  * Send card `id` the event `name` (the board's workflow decides what it does: `workflow.mjs`), then settle the cards
  * that wait on it (Hermes's recompute_ready) and run what the move asked for once it is committed. `roles` are who
  * sends it: `manager` for a person or the fleet's manager at the CLI, the card's own role for its session,
- * `platform` for the dispatcher. Answers `{ from, to, moved }`; throws the workflow's refusal.
+ * `platform` for the dispatcher. Answers `{ from, to, moved }` or a retained manager request.
  */
 // who is sending, when a caller does not say: the CLI answers with the caller's role on the card (setCaller)
 /** How the engine learns who a caller is on a card: `fn(db, cardId)` answers the caller's roles there (the call's own). */
+const preparedPrEvidence = new WeakSet();
+const completionEvidenceRefusal = (evidence, fallback) => Object.assign(new Error(evidence.reason ?? fallback),
+  { boardDetail: true }, Object.fromEntries(['code', 'retryable', 'deferred', 'deferred_code', 'retry_at', 'refusals']
+    .filter(key => Object.hasOwn(evidence, key)).map(key => [key, evidence[key]])));
 export function setCaller(fn) { current().roles = fn; }
 const callerRoles = (db, cardId) => current().roles(db, cardId);
+const withhold = value => typeof value === 'string' ? withheldIfDump(value)
+  : Array.isArray(value) ? value.map(withhold)
+  : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, withhold(item)])) : value;
+
+/** Record an incomplete or already satisfied ordinary act without claiming a transition or asking for permission. */
+export async function acceptRequest(board, { id = null, name, payload = {}, reason = null } = {}) {
+  const review = ['request_review', 'request-review', 'kanban_request_review'].includes(name);
+  const safe = redactValue({ requested: name, payload: withhold(payload), reason: String(reason?.message ?? reason ?? 'Recorded with the detail supplied.') });
+  const receipt = tx(board, db => {
+    const task = id ? getTask(db, id) : null, from = task ? statusOf(db, task) : null;
+    const queued = payload.queued_event ?? payload.queuedEvent;
+    if (review && queued != null) {
+      const pending = pendingReviewRequests(db, id).find(request => request.id === Number(queued));
+      if (pending) return { queued: true, disposition: 'pending', requested: name, id, pr: pending.pr, pr_head: pending.pr_head,
+        from, to: from, moved: false, pending: true, already: true, event: pending.id, queue_event: pending.id, reason: safe.reason,
+        ...(Array.isArray(reason?.refusals) ? { refusals: reason.refusals } : {}), ...(reason?.retry_at ? { retry_at: reason.retry_at } : {}) };
+    }
+    if (review) {
+      const detail = { ...safe, reason: `Nothing was queued. ${safe.reason}` };
+      const recorded = event(db, id == null ? '' : String(id), 'review_not_queued', detail, null);
+      return { ok: false, queued: false, disposition: 'not_queued', requested: name, from, to: from, moved: false, event: recorded, reason: detail.reason };
+    }
+    const recorded = queued ?? event(db, id == null ? '' : String(id), 'request_accepted', safe, null);
+    return { accepted: true, disposition: queued != null ? 'pending' : 'accepted', requested: name, from, to: from, moved: false, needs_detail: true, ...(queued != null ? { pending: true } : {}), event: recorded, reason: safe.reason };
+  });
+  (receipt.queued ? current().queuedRequests ??= [] : review ? current().unqueuedReviews ??= [] : current().acceptedRequests ??= []).push(receipt);
+  return receipt;
+}
+
+/** Retain the requested act for the configured manager without borrowing that manager's authority. A caller that
+ *  might be that manager, unread this call (call.mjs refuseUnreadManager), gets the identity error instead. */
+export async function routeRequest(board, { id = null, name, payload = {}, reason = null } = {}) {
+  refuseUnreadManager();
+  const entry = await loadWorkflow(board.root);
+  const manager = [].concat(entry.params?.managers ?? []).find(Boolean) ?? 'manager';
+  const requester = actorOf() ?? current().caller ?? principalOf() ?? 'board caller';
+  const messageId = `m-${randomBytes(12).toString('hex')}`;
+  const safe = redactValue({ requested: name, payload: withhold(payload), reason: String(reason?.message ?? reason ?? 'This act needs the manager.'), requester });
+  const verb = String(name ?? '').replace(/^kanban_/, '').replaceAll('-', '_');
+  const state = ({ complete: 'done', cancel: 'cancelled', archive: 'cancelled' })[verb] ?? payload.state ?? verb;
+  const rule = entry.params?.request_rules?.[state];
+  const denial = entry.params?.request_denial;
+  const receipt = tx(board, db => {
+    const task = id ? getTask(db, id) : null;
+    const from = task ? statusOf(db, task) : null;
+    const taskId = id == null ? '' : String(id);
+    const queued = payload.queued_event ?? payload.queuedEvent;
+    if (queued != null) {
+      const previous = one(db, "SELECT payload FROM task_events WHERE task_id=? AND kind='request_routed' AND COALESCE(json_extract(payload,'$.payload.queued_event'),json_extract(payload,'$.payload.queuedEvent'))=? ORDER BY id DESC LIMIT 1", taskId, queued);
+      const prior = json(previous?.payload, null);
+      if (prior) return { routed: true, disposition: 'routed', requested: name, manager: prior.manager, message_id: prior.message_id, from, to: from, moved: false, reason: prior.reason, already: true };
+    }
+    event(db, taskId, 'request_routed', { ...safe, manager, message_id: messageId }, null);
+    if (manager) event(db, taskId, 'board_message', { to: manager, message_id: messageId,
+      text: `${taskId || 'Board'}: ${requester} requested ${String(name ?? 'an act').replaceAll('_', '-')}.\n${safe.reason}\nOriginal request: ${JSON.stringify(safe.payload)}\nCarry out the request through its ordinary board door, applying any decision it needs.\n${rule ? `\n${rule}\n${denial ?? ''}\n` : ''}\nAnswer with reply_to ${messageId}.` }, null);
+    return { routed: true, disposition: 'routed', requested: name, manager, message_id: messageId, from, to: from, moved: false, reason: safe.reason };
+  });
+  (current().routedRequests ??= []).push(receipt);
+  // board_message is the existing durable mail queue. Its delivery pass retries a failed filing.
+  return receipt;
+}
 
 /**
- * Fire `name` on card `id` as its caller (or `roles`), in one board write with what the move settles around it.
- * `instead(db, error)`, when given, is asked in that same write when the event is refused: it answers another event's
- * name to fire in its place (read and decided against the same state the refusal was), or null to keep the refusal.
+ * Apply `name` as the real caller, supplying ordinary missing defaults. A request that needs another decision is
+ * retained for the manager. `instead(db, error)`, when present, selects a workflow alternative in the same write.
  */
 export async function act(board, id, name, { roles = null, payload = {}, extra = {}, instead = null } = {}) {
+  const original = payload;
+  try {
+    const sender = roles ?? callerRoles(board.db, id);
+    let backlogEvent = null;
+    if ((Object.hasOwn(payload, 'reason') || name === 'backlog') && !String(payload.reason ?? '').trim()) payload = { ...payload, reason: 'none given' };
+    if (name === 'pause' && payload.until == null) payload = { ...payload, until: '1h' };
+    if (name === 'unblock' && !payload.on) {
+      // A bare unblock means the dependencies the manager can see now, never a wildcard over later additions.
+      const blockers = getTask(board.db, id)?.blocked_by ?? [];
+      if (!blockers.length) {
+        const task = getTask(board.db, id), from = task ? statusOf(board.db, task) : null;
+        if (task) return { from, to: from, moved: false, already: true };
+      }
+      let result;
+      for (const blocker of blockers) result = await applyAct(board, id, name, { roles, payload: { ...payload, on: blocker.id }, extra, instead });
+      if (result) return result;
+    }
+    if (name === 'backlog') {
+      const task = getTask(board.db, id);
+      if (task?.backlog) return { from: statusOf(board.db, task), to: statusOf(board.db, task), moved: false, already: true };
+      if (task?.paused && payload.pause_revision == null) payload = { ...payload,
+        pause_revision: task.paused.generation ?? one(board.db, "SELECT id FROM task_events WHERE task_id=? AND kind='paused' ORDER BY id DESC LIMIT 1", id)?.id };
+      const entry = await loadWorkflow(board.root);
+      view(board, db => validateEvent(db, board, entry, id, name, { roles: sender, payload, extra, localOnly: true }));
+      const pendingHold = latestEvent(board.db, id, ['dispatch_held', 'dispatch_released', 'session_adopted'], 'id,kind,payload');
+      if (pendingHold?.kind === 'dispatch_held' && json(pendingHold.payload, {})?.backlog_request) backlogEvent = pendingHold.id;
+      if (task && !['done', 'archived', 'cancelled'].includes(task.status) && !backlogQualification(board.db, id).qualified) {
+        backlogEvent = tx(board, db => {
+          const hold = latestEvent(db, id, ['dispatch_held', 'dispatch_released', 'session_adopted'], 'id,kind,payload');
+          const held = json(hold?.payload, {}) ?? {};
+          const marker = event(db, id, 'dispatch_held', { reason: 'backlog requested; ending its execution before placement', backlog_request: true,
+            requester: actorOf() ?? current().caller ?? principalOf(), sender, backlog_payload: payload, backlog_extra: extra,
+            previous_hold: hold?.kind === 'dispatch_held' ? held.backlog_request ? held.previous_hold ?? null : { id: hold.id, payload: held } : null });
+          if (getTask(db, id)?.current_run_id) endRun(db, id, { outcome: 'backlogged', summary: payload.reason });
+          requestSessionClose(db, id);
+          return marker;
+        });
+        const { closeRequested } = await import('./dispatch.mjs');
+        await closeRequested(board, { undelivered: [] }, { taskId: id });
+        // The close pass can finish this exact request once it has the real stop receipt.
+        if (getTask(board.db, id)?.backlog) return { from: statusOf(board.db, task), to: statusOf(board.db, getTask(board.db, id)), moved: false };
+        const qualification = backlogQualification(board.db, id);
+        if (!qualification.qualified) throw requestDetail(qualification.reason);
+      }
+    }
+    return await applyAct(board, id, name, { roles, payload, extra, instead, backlogEvent });
+  } catch (error) {
+    if (error.ownerRule) return await routeRequest(board, { id, name, payload: original, reason: error });
+    if (error.boardDetail || error.noTransition || error.refusal) return await acceptRequest(board, { id, name, payload: original, reason: error });
+    throw error;
+  }
+}
+
+/** Finish retained backlog requests only after the native close pass has made them qualified. */
+export async function completeBacklogRequests(board, { taskId = null } = {}) {
+  const pending = view(board, db => all(db, `SELECT e.id,e.task_id,e.payload FROM tasks t JOIN task_events e ON e.id=${latestEventIdSql('t.id', ['dispatch_held', 'dispatch_released', 'session_adopted'])}
+    WHERE e.kind='dispatch_held' AND json_extract(e.payload,'$.backlog_request')=1 ${taskId ? 'AND t.id=?' : ''}
+    ORDER BY e.id`, ...(taskId ? [taskId] : [])));
+  const completed = [];
+  for (const request of pending) {
+    if (!backlogQualification(board.db, request.task_id).qualified) continue;
+    const held = json(request.payload, {}) ?? {};
+    // Complete only with the original sender's roles.
+    if (!Array.isArray(held.sender) || !held.backlog_payload) continue;
+    const previousActor = actorOf();
+    try {
+      setActor(held.requester ?? held.by ?? null);
+      const result = await applyAct(board, request.task_id, 'backlog', { roles: held.sender, payload: held.backlog_payload,
+        extra: held.backlog_extra ?? {}, backlogEvent: request.id });
+      if (result.backlog_event === request.id) completed.push(request.task_id);
+    } catch (error) {
+      // A changed workflow or card retains its request; a later close pass can reconsider it without duplicate mail.
+      if (!error.ownerRule && !error.boardDetail && !error.noTransition && !error.refusal) throw error;
+    } finally { setActor(previousActor); }
+  }
+  return completed;
+}
+
+async function applyAct(board, id, name, { roles = null, payload = {}, extra = {}, instead = null, backlogEvent = null } = {}) {
   assertSourceReceipt(payload);
   const entry = await loadWorkflow(board.root);
-  if (name === 'comment' && (!String(payload.body ?? '').trim() || !String(payload.author ?? '').trim())) throw new Error('a comment has an author and body');
+  const sender = roles ?? callerRoles(board.db, id), task = getTask(board.db, id);
+  if (task && !task.subtask_of && sender.includes('implementer') && !sender.includes('manager') && ['complete', 'cancel', 'archive'].includes(name))
+    throw ownerRule('The manager closes an arc; its own implementer requests that decision.');
+  if (task && name === 'request_review') {
+    const card = scopeOf(board.db, board, task, { params: entry.params, lazy: true, deferSources: true }).card;
+    if (card.reviewer_profile != null && (card.reviewer_profile === card.implementer || card.reviewer_profile === entry.params?.org_layer))
+      throw ownerRule('A review uses an independent reviewer profile; the manager selects it.');
+  }
+  if (task && name === 'set' && payload.field === 'reviewer' && payload.value != null
+      && [task.assignee, entry.params?.org_layer].includes(payload.value)) throw ownerRule('A review uses an independent reviewer profile; the manager selects it.');
   refuseCredentialDump(name === 'comment' ? `the comment on ${id}` : `${name.replace(/_/g, '-')} on ${id}`, payload);
   await refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
   if (['complete', 'request_review', 'request_state'].includes(name)) view(board, db => validateEvent(db, board, entry, id, name,
     { roles: roles ?? callerRoles(db, id), payload, extra, localOnly: true }));
   const evidencePhase = ['complete', 'request_review', 'request_state'].includes(name) ? completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id)) : null;
   if (evidencePhase) payload = { ...payload, ci: await observeCompletionEvidence(board, id, entry, payload, evidencePhase) };
-  if (payload.ci?.required && !payload.ci.ready && (name !== 'request_state' || evidencePhase === 'review_verdict')) throw new Error(payload.ci.reason ?? 'The PR candidate could not be verified.');
+  // act retains missing review detail without firing the transition or consuming a queued request.
+  if (payload.ci?.required && !payload.ci.ready && (name !== 'request_state' || evidencePhase === 'review_verdict')) throw completionEvidenceRefusal(payload.ci, 'The PR candidate could not be verified.');
   const result = tx(board, (db) => {
     roles ??= callerRoles(db, id);
+    let backlogHold = null;
+    if (name === 'backlog' && backlogEvent != null) {
+      backlogHold = latestEvent(db, id, ['dispatch_held', 'dispatch_released', 'session_adopted'], 'id,kind,payload');
+      if (backlogHold?.id !== backlogEvent || backlogHold.kind !== 'dispatch_held' || !json(backlogHold.payload, {})?.backlog_request
+          || !backlogQualification(db, id).qualified) {
+        const from = statusOf(db, getTask(db, id));
+        return { from, to: from, moved: false, effects: [] };
+      }
+    }
+    if (name === 'request_review' && payload.queued_event != null) {
+      const queued = one(db, "SELECT payload FROM task_events WHERE task_id=? AND id=? AND kind='review_queued'", id, payload.queued_event);
+      const taken = one(db, "SELECT 1 FROM task_events WHERE task_id=? AND kind IN ('review_queue_started','review_queue_settled') AND json_extract(payload,'$.queued_event')=?", id, payload.queued_event);
+      if (!queued || taken) throw requestDetail('This queued review was already handled.');
+    }
     let r;
     try { r = fire(db, board, entry, id, name, { roles, payload, extra }); }
     catch (error) {
       const other = (error.refusal || error.noTransition) && instead ? instead(db, error, entry) : null;
       if (!other) throw error;
-      r = { ...fire(db, board, entry, id, other.name, { roles, payload, extra }), instead: other };
+      r = { ...fire(db, board, entry, id, other.name, { roles, payload: other.payload ?? payload, extra }), instead: other };
+    }
+    if (backlogHold && getTask(db, id)?.backlog) {
+      const previous = json(backlogHold.payload, {})?.previous_hold;
+      event(db, id, 'dispatch_released', { reason: 'backlog placement completed', backlog_request: backlogEvent });
+      if (previous?.payload) event(db, id, 'dispatch_held', { ...previous.payload, restored_after_backlog_request: backlogEvent, restored_by: actorOf() });
+      r.backlogEvent = backlogEvent;
     }
     // Authorization and the comment row share one transaction: a refusal stores nothing.
+    if (name === 'request_review' && payload.queued_event != null && r.moved && r.to === 'review') event(db, id, 'review_queue_started', { queued_event: payload.queued_event });
+    // The review now running replaces every other pending request for its PR (ADR 0252).
+    if (name === 'request_review' && r.moved && r.to === 'review' && payload.review === 'pr' && [].concat(payload.pr ?? []).length === 1) {
+      const active = one(db, "SELECT id FROM task_events WHERE task_id=? AND kind='review_requested' ORDER BY id DESC LIMIT 1", id)?.id ?? null;
+      for (const row of pendingReviewRequests(db, id)) {
+        const named = [].concat(row.pr ?? []);
+        if (row.id === Number(payload.queued_event) || named.length !== 1 || prIdentity(named[0]) !== prIdentity([].concat(payload.pr)[0])) continue;
+        event(db, id, 'review_queue_settled', { queued_event: row.id, disposition: 'superseded', active_review_event: active,
+          queue_order: row.queue_order, review: 'pr', requested_pr: payload.pr, requested_pr_head: payload.pr_head });
+      }
+    }
     if (name === 'comment') {
+      if (payload.pr_evidence) {
+        const proof = payload.pr_evidence;
+        if (!preparedPrEvidence.has(proof)) throw new Error('PR evidence must enter through the verified comment door.');
+        const sender = roles ?? callerRoles(db, id);
+        if (!sender.some(role => ['implementer', 'manager'].includes(role))) throw ownerRule('PR evidence authority changed before commit.');
+        if (proof.kind === 'pr_release_readback') {
+          if (proof.verification?.kind === 'manager-attestation' && !sender.includes('manager')) throw ownerRule('Manager attestation authority changed.');
+          const disposition = prDisposition(board, id, proof.url, proof.head);
+          if (disposition.event !== proof.disposition_event || disposition.disposition !== 'release-only') throw new Error('PR disposition changed during readback.');
+          // Re-check the current verdict with the same binding validation used by readers.
+          const probe = { ...proof };
+          event(db, id, proof.kind, probe);
+          if (!releaseReadback(board, id, proof.url, proof.head)) throw new Error('The PR pass changed during readback.');
+        } else event(db, id, proof.kind, proof);
+      }
       r.commentId = Number(run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', id, payload.author.trim(), payload.body.trim(), now()).lastInsertRowid);
       joinThread(db, entry, id, payload.author.trim(), payload.body);
     }
@@ -522,25 +828,38 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
   await runEffects(board, result.effects);
   // A card this verb closed ends its agents' assignments; the verb hands the ends on itself (agent-declarations.mjs).
   if (result.moved) { const { endFinishedAgents } = await import('./agent-declarations.mjs'); await endFinishedAgents(board, [id]); }
-  return { from: result.from, to: result.to, moved: result.moved, ...(result.commentId ? { commentId: result.commentId } : {}), ...(result.instead ? { instead: result.instead } : {}) };
+  return { from: result.from, to: result.to, moved: result.moved, ...(result.commentId ? { commentId: result.commentId } : {}), ...(result.instead ? { instead: result.instead } : {}), ...(result.backlogEvent != null ? { backlog_event: result.backlogEvent } : {}) };
 }
 
 export async function requestStateMany(board, ids, payload = {}) {
+  try { return await applyStateMany(board, ids, payload); }
+  catch (error) {
+    const results = [];
+    for (const id of [...new Set(ids.map(String))]) {
+      if (!error.ownerRule && !error.boardDetail && !error.noTransition && !error.refusal) throw error;
+      const receipt = await (error.ownerRule ? routeRequest : acceptRequest)(board, { id, name: 'request_state', payload, reason: error });
+      results.push([id, receipt.to]);
+    }
+    if (!results.length) await acceptRequest(board, { name: 'request_state', payload, reason: error });
+    return results;
+  }
+}
+
+async function applyStateMany(board, ids, payload = {}) {
   assertSourceReceipt(payload);
+  if (!String(payload.reason ?? '').trim()) payload = { ...payload, reason: 'none given' };
   const targets = [...new Set(ids.map(String))];
   if (!targets.length) throw new Error('A state request names at least one card.');
   const entry = await loadWorkflow(board.root);
   const prepared = new Map(await Promise.all(targets.map(async id => {
     const roles = callerRoles(board.db, id);
     const phase = completionPhase(board, id, entry, 'request_state', payload, roles);
-    // As in complete: only a reviewer's verdict reads PRs from a state request; anyone else's would be dropped unread.
-    if (phase !== 'review_verdict' && [].concat(payload.pr ?? [], payload.pr_head ?? []).length) throw new Error(`A state request records no PRs: declare the arc's PRs on it with comment <arc> "<why>" --pr URL --pr-head SHA (one pair per PR), then request the state without them. Nothing was requested.`);
     view(board, db => validateEvent(db, board, entry, id, 'request_state', { roles, payload, localOnly: true }));
     const evidence = await inspectCompletionEvidence(board, id, entry, payload, phase);
     // An ordinary request mails a decision to the manager, not a completion.
     // Keep a failed source observation in that mail. A reviewer recording an
     // actual verdict still has to verify the requested PR head.
-    if (phase === 'review_verdict' && evidence.required && !evidence.ready) throw new Error(evidence.reason ?? 'The reviewed PR head could not be verified.');
+    if (phase === 'review_verdict' && evidence.required && !evidence.ready) throw completionEvidenceRefusal(evidence, 'The reviewed PR head could not be verified.');
     return [id, evidence];
   })));
   const result = tx(board, db => {
@@ -569,7 +888,10 @@ export async function goto(board, id, status, { roles = null, payload = {} } = {
     return { ...eventTo(db, board, entry, id, status, { roles, payload }), from: statusOf(db, getTask(db, id)) };
   })();
   if (from === status) return { from, to: status, moved: false, event: null };
-  if (!name) throw new Error(refusal ?? `${id} is ${from}; no event you may send takes it to ${status}`);
+  if (!name) {
+    refuseUnreadManager();
+    return await acceptRequest(board, { id, name: 'goto', payload: { ...payload, status }, reason: refusal ?? `no workflow event admits moving ${id} from ${from} to ${status} for ${roles.length ? roles.join(', ') : 'this caller'}.` });
+  }
   return { ...(await act(board, id, name, { roles, payload })), event: name };
 }
 
@@ -580,7 +902,7 @@ export async function goto(board, id, status, { roles = null, payload = {} } = {
 // it keeps trying at the capped wait, and at EFFECT_ATTEMPTS failed attempts its card records `effect_stalled` and the
 // managers are mailed once, so a passed card whose merge keeps failing is seen, and still heals when the cause clears.
 export const EFFECT_ATTEMPTS = 6;
-const OWNED = new Set(['merge_reviewed', 'cleanup_workspace', 'rename_card_agents']);
+const OWNED = new Set(['merge_reviewed', 'retire_workspace', 'cleanup_workspace', 'rename_card_agents']);
 const effectWait = (attempts) => Math.min(1800, 30 * 2 ** Math.max(0, attempts - 1));
 // A delivery pass claims a row by compare-and-set on its next_at (set ahead only while the row is due) before trying it,
 // so two passes (serve's, the hosted loop's, a person's `workflow deliver`, a verb's own) never try one effect at once.
@@ -666,7 +988,8 @@ export async function runEffects(board, effects = [], { pending: due = false, el
 /** One effect's I/O: true when it is done, false when it is not done yet (the caller counts the attempt). */
 async function runEffect(board, e) {
   if (e.kind === 'session_notice') { const { sessionNotice } = await import('./dispatch.mjs'); return await sessionNotice(board, e) !== false; }
-  if (e.kind === 'cleanup_workspace') { await cleanupWorkspace(board, e.id); return true; }
+  // retire_workspace is what this release queues; cleanup_workspace rows are a predecessor's, retired by the same rule
+  if (e.kind === 'retire_workspace' || e.kind === 'cleanup_workspace') { await cleanupWorkspace(board, e.id, { scratch: e.kind === 'cleanup_workspace' || e.scratch === true }); return true; }
   if (e.kind === 'declare_card_agent') { const { declareCardAgentEffect } = await import('./agent-declarations.mjs'); return (await declareCardAgentEffect(board, e)) !== false; }
   if (e.kind === 'rename_card_agents') { const { renameCardAgentsEffect } = await import('./agent-declarations.mjs'); return await renameCardAgentsEffect(board, e); }
   // a verb's own ask files its card's mail at once (a local write; the mailbox delivers it)
@@ -701,7 +1024,7 @@ export function recomputeReady(board, effects = [], errors = []) {
   // what the moves ask for is handed on only once the write commits: a retried write starts its lists again
   const { moved, asked, failed } = tx(board, (db) => {
     const asked = [], failed = [];
-    let moved = 0;
+    let moved = settleExpiringFlags(db, board, entry, asked);
     for (const { id } of all(db, "SELECT id FROM tasks WHERE status NOT IN ('done', 'archived')")) {
       const before = statusOf(db, getTask(db, id));
       // another writer's commit is the whole write's to retry, never one card's failure
@@ -747,11 +1070,7 @@ export const complete = async (board, id, options = {}) => {
   // A person's card closes only on that person's completion (personDone, as the board's platform event): no session,
   // creator or manager completes it through this verb.
   const person = view(board, (db) => personOf(getTask(db, id)?.assignee));
-  if (person) throw Object.assign(new Error(`${id} is assigned to ${person}: it closes when that person completes it in the Workplace (person-done), never by complete. Nothing was completed.`), { refusal: true });
-  if ([].concat(pr ?? [], pr_head ?? []).length && !view(board, (db) => roles ?? callerRoles(db, id)).includes('reviewer')) {
-    const arc = view(board, (db) => one(db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id))?.subtask_of ?? id;
-    throw new Error(`complete records no PRs: declare the arc's PRs on it with comment ${arc} "<why>" --pr URL --pr-head SHA (one pair per PR), then complete ${id} without them. Nothing was completed.`);
-  }
+  if (person) return await routeRequest(board, { id, name: 'complete', payload: options, reason: `${id} is assigned to ${person}; obtain their completion through the Workplace person-done door.` });
   return await act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, branch, pr, pr_head, reviewed_sha } });
 };
 /**
@@ -780,14 +1099,129 @@ export const block = async (board, id, { reason = null, on = null, waitingOn = n
   await act(board, id, 'block', { roles, payload: { reason, on, kind, waiting_on: waitingOn, run_id: runId } });
 export const unblock = (board, id, { reason = null, on = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason, on } });
 export const requestReview = async (board, id, options = {}) => {
+  try { return await applyRequestReview(board, id, options); }
+  catch (error) {
+    if (error.ownerRule) return await routeRequest(board, { id, name: 'request_review', payload: options, reason: error });
+    if (error.boardDetail || error.noTransition || error.refusal) return await acceptRequest(board, { id, name: 'request_review', payload: options, reason: error });
+    throw error;
+  }
+};
+const applyRequestReview = async (board, id, options = {}) => {
   assertSourceReceipt(options);
-  const { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, branch = null, pr = null, pr_head = null, plan = false } = options;
+  const { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, branch = null, plan = false, queuedEvent = null } = options;
+  const sender = roles ?? callerRoles(board.db, id), entry = await loadWorkflow(board.root);
+  const declared = declaredPullRequests(board.db, id);
+  const previous = one(board.db, "SELECT id,payload FROM task_events WHERE task_id=? AND kind='review_requested' ORDER BY id DESC LIMIT 1", id);
+  const previousPayload = json(previous?.payload, {});
+  const requestedUrls = [].concat(previousPayload.requested_pr ?? []), requestedHeads = [].concat(previousPayload.requested_pr_head ?? []);
+  const reviewed = [...candidatePullRequests(previousPayload.ci).map(source => ({ url: source.pr.url, head: source.commit })),
+    ...requestedUrls.map((url, i) => ({ url, head: requestedHeads[i] })).filter(source => source.url && source.head)];
+  const declaration = one(board.db, "SELECT MAX(id) AS id FROM task_events WHERE task_id=? AND kind='commented' AND json_type(payload,'$.sources')='array'", id)?.id ?? 0;
+  const known = [...new Map((declaration > (previous?.id ?? 0) ? [...reviewed, ...declared] : [...declared, ...reviewed]).map(source => [source.url, source])).values()];
+  const pr = options.pr ?? (known.length === 1 ? known[0].url : null);
+  const named = [].concat(pr ?? []);
+  const pr_head = options.pr_head ?? (named.length && named.every(url => known.some(source => source.url === url && source.head))
+    ? named.map(url => known.find(source => source.url === url).head) : null);
   // What a session's request asks for is what it says, never its summary's words: `--plan` asks the plan review of the
   // proposed ADR's PR it names, and one PR named with its head (--pr, --pr-head) is that PR's review. The workflow's
   // clauses read `review`; a request naming several PRs asks neither.
-  const one = [].concat(pr ?? []).length === 1 && [].concat(pr_head ?? []).length === 1;
-  const review = plan ? 'plan' : one ? 'pr' : null;
-  return await act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, branch, pr, pr_head, review, plan: Boolean(plan) } });
+  const singlePr = [].concat(pr ?? []).length === 1;
+  const review = plan ? 'plan' : singlePr || !sender.includes('platform') ? 'pr' : null;
+  const payload = { summary, metadata, reviewer, force, run_id: expectedRunId, commit, branch, pr, pr_head, review, plan: Boolean(plan),
+    ...(queuedEvent != null ? { queued_event: queuedEvent, ...(options.requester ? { requester: options.requester } : {}) } : {}) };
+  const candidateUrls = urls => [].concat(urls ?? []).map(url => typeof url === 'string' ? url.replace(/\/$/, '').toLowerCase() : url);
+  const samePr = urls => [].concat(urls ?? []).length === 1 && candidateUrls(urls)[0] === candidateUrls(pr)[0];
+  const sameCandidate = (urls, heads) => JSON.stringify(candidateUrls(urls)) === JSON.stringify(candidateUrls(pr)) && JSON.stringify([].concat(heads ?? [])) === JSON.stringify([].concat(pr_head ?? []));
+  const activeCandidate = db => {
+    const active = latestReviewRequest(db, id);
+    const candidate = json(active?.payload, {}), sources = candidatePullRequests(candidate.ci);
+    return active && active.kind === (review ?? 'final') && sameCandidate(candidate.requested_pr ?? sources.map(source => source.pr.url), candidate.requested_pr_head ?? sources.map(source => source.commit)) ? active.id : null;
+  };
+  // Recovery is explicit and names one unsettled receipt on this card. Inspect B without replacing the active
+  // review's observation, then append B and settle A together. A failed fresh admission leaves A pending.
+  if (options.supersedes != null && queuedEvent == null) {
+    const supersedes = Number(options.supersedes);
+    if (!Number.isSafeInteger(supersedes) || supersedes <= 0) throw requestDetail('--supersedes names a positive queued review event ID.');
+    if (!singlePr) throw requestDetail('A queued PR replacement names one PR and its head: --pr URL --pr-head SHA.');
+    const authorize = db => {
+      const task = getTask(db, id);
+      if (!task) throw requestDetail(`No card ${id} holds that queued review.`);
+      const currentSender = roles ?? callerRoles(db, id);
+      if (!currentSender.some(role => ['implementer', 'reviewer', 'auditor', 'arc', 'creator', 'manager'].includes(role))) throw ownerRule('A card\'s own role or manager supersedes its queued PR review.');
+      const from = statusOf(db, task);
+      const assignee = from === 'review' ? scopeOf(db, board, task, { params: entry.params, lazy: true, deferSources: true }).card.implementer : task.assignee;
+      const pending = pendingReviewRequests(db, id), original = pending.find(row => row.id === supersedes);
+      if (!original) {
+        const settled = one(db, "SELECT id,payload FROM task_events WHERE task_id=? AND kind='review_queue_settled' AND json_extract(payload,'$.queued_event')=? ORDER BY id DESC LIMIT 1", id, supersedes);
+        const prior = json(settled?.payload, {});
+        if (prior.disposition === 'superseded' && prior.review === review
+            && sameCandidate(prior.requested_pr, prior.requested_pr_head)) return { retry: {
+          disposition: 'already', requested: 'request_review', id, pr, pr_head, supersedes,
+          settlement_event: settled.id, ...(prior.replacement_event != null ? { event: prior.replacement_event, queue_event: prior.replacement_event, queue_order: prior.queue_order } : {}),
+          ...(prior.active_review_event != null ? { active_review_event: prior.active_review_event, in_review: from === 'review' && activeCandidate(db) === prior.active_review_event } : {}),
+          from, to: from, moved: false, already: true, reason: 'This correction was already recorded; nothing new was queued. Its original replacement receipt is retained.' } };
+        throw requestDetail(`Queued review ${supersedes} is not pending on this card; its original receipt is retained.`);
+      }
+      return { task, from, assignee, currentSender, pending, original };
+    };
+    const checked = view(board, authorize);
+    if (checked.retry) { (current().acceptedRequests ??= []).push(checked.retry); return checked.retry; }
+    const evidence = await inspectCompletionEvidence(board, id, entry, payload, 'request_review');
+    if (!evidence.ready || !candidatePullRequests(evidence).length) throw completionEvidenceRefusal(evidence, 'The replacement PR candidate could not be verified.');
+    const receipt = tx(board, db => {
+      const authorized = authorize(db);
+      if (authorized.retry) return authorized.retry;
+      const { from, assignee, currentSender, pending, original } = authorized;
+      const requester = actorOf() ?? current().caller;
+      const active = from === 'review' ? activeCandidate(db) : null;
+      if (active) {
+        const settlement = event(db, id, 'review_queue_settled', { queued_event: supersedes, disposition: 'superseded',
+          active_review_event: active, queue_order: original.queue_order, requester, sender: currentSender, assignee, review,
+          requested_pr: pr, requested_pr_head: pr_head, ci: evidence });
+        return { accepted: true, disposition: 'already', requested: 'request_review', id, pr, pr_head, supersedes,
+          active_review_event: active, settlement_event: settlement, in_review: true, from, to: from, moved: false, already: true,
+          reason: `Queued review ${supersedes} is superseded by the candidate already under review.` };
+      }
+      const same = pending.find(row => row.review === review && sameCandidate(row.pr, row.pr_head));
+      if (same?.id === supersedes) return { queued: true, disposition: 'queued', requested: 'request_review', id, pr, pr_head,
+        event: same.id, queue_event: same.id, queue_order: same.queue_order, from, to: from, moved: false, already: true };
+      const queued = same?.id ?? event(db, id, 'review_queued', { ...payload, superseded_event: supersedes, queue_order: original.queue_order,
+        sender: currentSender, requester, assignee });
+      const queueOrder = Math.min(original.queue_order, same?.queue_order ?? original.queue_order);
+      const settlement = event(db, id, 'review_queue_settled', { queued_event: supersedes, disposition: 'superseded',
+        replacement_event: queued, queue_order: queueOrder, requester, sender: currentSender, assignee, review,
+        requested_pr: pr, requested_pr_head: pr_head, ci: evidence });
+      return { queued: true, disposition: 'queued', requested: 'request_review', id, pr, pr_head, supersedes,
+        event: queued, queue_event: queued, settlement_event: settlement, queue_order: queueOrder,
+        from, to: from, moved: false, already: Boolean(same) };
+    });
+    (receipt.queued ? current().queuedRequests ??= [] : current().acceptedRequests ??= []).push(receipt);
+    return receipt;
+  }
+  const receipt = tx(board, db => {
+    const task = getTask(db, id);
+    if (!task || statusOf(db, task) !== 'review') return null;
+    if (!sender.some(role => ['implementer', 'reviewer', 'auditor', 'arc', 'creator', 'manager'].includes(role))) throw ownerRule('A card\'s own role or manager requests its PR review.');
+    const assignee = scopeOf(db, board, task, { params: entry.params, lazy: true, deferSources: true }).card.implementer;
+    if (activeCandidate(db))
+      return { accepted: true, already: true, disposition: 'already', requested: 'request_review', id, from: 'review', to: 'review', moved: false, reason: 'This candidate is already under review.' };
+    const pending = pendingReviewRequests(db, id);
+    const same = pending.find(row => row.review === review && sameCandidate(row.pr, row.pr_head));
+    if (same) return { queued: true, disposition: 'queued', requested: 'request_review', id, pr, pr_head, event: same.id, queue_event: same.id, queue_order: same.queue_order, from: 'review', to: 'review', moved: false, already: true };
+    // A newer request for the same PR replaces its pending ones at the earliest of their positions (ADR 0252).
+    const replaced = review === 'pr' && singlePr ? pending.filter(row => samePr(row.pr)) : [];
+    const queueOrder = replaced.length ? Math.min(...replaced.map(row => row.queue_order)) : null;
+    const requester = actorOf() ?? current().caller;
+    const queued = event(db, id, 'review_queued', { ...payload, ...(queueOrder != null ? { queue_order: queueOrder } : {}), sender, requester, assignee });
+    let settlement = null;
+    for (const row of replaced) settlement = event(db, id, 'review_queue_settled', { queued_event: row.id, disposition: 'superseded',
+      replacement_event: queued, queue_order: queueOrder, requester, sender, assignee, review, requested_pr: pr, requested_pr_head: pr_head });
+    return { queued: true, disposition: 'queued', requested: 'request_review', id, pr, pr_head, event: queued, queue_event: queued,
+      queue_order: queueOrder ?? queued, ...(settlement != null ? { settlement_event: settlement, superseded: replaced.map(row => row.id) } : {}),
+      from: 'review', to: 'review', moved: false, already: false };
+  });
+  if (receipt) { (receipt.queued ? current().queuedRequests ??= [] : current().acceptedRequests ??= []).push(receipt); return receipt; }
+  return await act(board, id, 'request_review', { roles, payload });
 };
 export const requestChanges = (board, id, { reason = null, reviewer = null, roles } = {}) => act(board, id, 'request_changes', { roles, payload: { reason, reviewer } });
 export const reopen = (board, id, { author = 'user', reason = null, roles } = {}) => act(board, id, 'reopen', { roles, payload: { author, reason } });
@@ -805,11 +1239,20 @@ export async function reopenReview(board, id, { roles, reason = null } = {}) {
   // the refusal, the check that the open run is a reviewer's and the restart are one write: no verdict lands between
   const moved = await act(board, id, 'reopen_review', { roles, payload: { reason }, instead: (db, _error, entry) => {
     const run = currentRun(db, id);
+    if (!run || run.ended_at != null || run.metadata?.supercode?.slot !== 'reviewer') return null;
+    // An arc re-declared since its review request (redeclaredSince) is not restarted on that request's frozen candidate:
+    // the review is returned to its coder with no verdict, naming the declaration (`redeclared`), so the return holds
+    // no returned set (returnedReview): the next review is requested from the declared set when the ordinary rules make
+    // one due (reviewDue, settledReviewDue), as a new review_requested its reviewer binds (VO-3775).
+    const asked = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id=? AND kind='review_requested'").get(id)?.id ?? null;
+    const redeclared = asked ? redeclaredSince(db, id, asked) : null;
+    if (redeclared && transitionsFor(entry.workflow, 'review', 'return_review').length)
+      return { name: 'return_review', run: run.id, returned: true, payload: { reason: reason ?? 'the arc re-declared its sources after its review request', redeclared } };
     const stays = transitionsFor(entry.workflow, 'review', 'reclaim').some((t) => !t.target || t.target === 'review');
-    return run && run.ended_at == null && run.metadata?.supercode?.slot === 'reviewer' && stays ? { name: 'reclaim', run: run.id } : null;
+    return stays ? { name: 'reclaim', run: run.id } : null;
   } });
   const { instead, ...rest } = moved;
-  return instead ? { ...rest, restarted_run: instead.run } : rest;
+  return instead ? { ...rest, ...(instead.returned ? { returned_run: instead.run } : { restarted_run: instead.run }) } : rest;
 }
 export const schedule = (board, id, reason = null, { roles } = {}) => act(board, id, 'schedule', { roles, payload: { reason } });
 export const promote = (board, id, { actor = 'user', reason = null, force = false, roles } = {}) => act(board, id, 'promote', { roles, payload: { actor, reason, force } });
@@ -841,11 +1284,19 @@ export async function specify(board, id, { title = null, body = null, readableId
   // an arc's new task lines are filed as its subtasks once the specify itself is accepted
   const steps = body != null && !one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of ? bodyTasks(body) : { body, tasks: [] };
   const done = await act(board, id, 'specify', { roles, payload: { title, body: steps.body, readable_id: readableId, author, ...(declaration ? { workspace: declaration } : {}) } });
+  if (done.routed || done.accepted) return done;
   for (const step of steps.tasks) createCard(board, { ...step, subtaskOf: id, assignee: getTask(board.db, id)?.assignee || null });
   return done;
 }
 export const editResult = (board, id, { result, summary = null, metadata = undefined, roles } = {}) => act(board, id, 'edit', { roles, payload: { result, summary, metadata } });
-export const heartbeat = (board, id, note = null, { roles, until = null } = {}) => act(board, id, 'heartbeat', { roles, payload: { note, until } });
+export const heartbeat = async (board, id, note = null, { roles, until = null } = {}) => {
+  const deadline = deadlineUntil(until, now(), 'heartbeat');
+  if (Number.isNaN(deadline)) {
+    await act(board, id, 'heartbeat', { roles, payload: { note, until: null } });
+    return await acceptRequest(board, { id, name: 'heartbeat', payload: { note, until }, reason: 'Heartbeat recorded; its wait deadline was left blank because the supplied time was unreadable or outside the supported date range.' });
+  }
+  return await act(board, id, 'heartbeat', { roles, payload: { note, until: deadline } });
+};
 export const setGoal = (board, id, { on = true, maxTurns = null, roles } = {}) => act(board, id, 'set_goal', { roles, payload: { goal: Boolean(on), max_turns: on ? maxTurns : null } });
 
 /** File the named card's tasks only if its workflow accepts decompose; refusal leaves no cards behind. */
@@ -884,14 +1335,14 @@ export function link(board, parent, child, { roles } = {}) {
 export async function unlink(board, parent, child, { roles } = {}) {
   const linked = view(board, (db) => one(db, 'SELECT 1 FROM task_links WHERE parent_id = ? AND child_id = ?', parent, child));
   if (!linked) return false;
-  await act(board, child, 'unlink', { roles, payload: { parent, child } });
-  return true;
+  const result = await act(board, child, 'unlink', { roles, payload: { parent, child } });
+  return result.routed || result.accepted ? result : true;
 }
 
 /** A comment on the card's thread; answers its id. */
-export async function comment(board, id, author, body, { roles, pr = null, pr_head = null, source = null } = {}) {
-  if (!String(body ?? '').trim()) throw new Error('a comment has a body');
-  if (!String(author ?? '').trim()) throw new Error('a comment has an author');
+export async function comment(board, id, author, body, { roles, pr = null, pr_head = null, source = null, disposition = null, release_target = null, readback = null, reason = null } = {}) {
+  body = String(body ?? '');
+  author = String(author ?? actorOf() ?? current().caller ?? 'board caller');
   let sources, branches;
   // The repositories and branches an arc changes are the arc's own: declared on it (`--source owner/repo:branch`, each
   // repository the arc changes), never registered as a subtask's workspace to be reviewed (VO-2858 had to register
@@ -910,7 +1361,7 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
     if (new Set(branches.map((b) => `${b.repository.toLowerCase()}:${b.branch}`)).size !== branches.length) throw new Error('Declare each source once.');
     const arc = one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of;
     if (arc) throw new Error(`${id} is a task of ${arc}: an arc's sources are declared on the arc (comment ${arc} … --source owner/repository:branch).`);
-    if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw new Error(`Only ${id}'s implementer or the manager declares its sources.`);
+    if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw ownerRule(`Only ${id}'s implementer or the manager declares its sources.`);
   }
   if (pr != null || pr_head != null) {
     const urls = [].concat(pr ?? []), heads = [].concat(pr_head ?? []);
@@ -925,7 +1376,7 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
       return { url: url.replace(/\/$/, ''), head: heads[i] };
     });
     // Only the card's own implementer or the board's manager declares its sources; the author text is not identity.
-    if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw new Error(`Only ${id}'s implementer or the manager records its PR sources.`);
+    if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw ownerRule(`Only ${id}'s implementer or the manager records its PR sources.`);
     // A declared PR is in one of the arc's repositories (its workspace, its declared sources, its tasks'; a `--source`
     // in this same comment counts with the arc's declared sources): the review reads no other, so one outside them is
     // refused here and nothing is stored, never kept to be dropped from every review request (t_ef2aa6ce). The board's
@@ -941,8 +1392,19 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
     }
     if (outside.length) throw new Error(outside.map(({ url, repository }) => `${url} is in ${repository}, which is not one of ${id}'s repositories (its workspace, its declared sources, its tasks'): declare ${repository} first with comment ${id} "<why>" --source ${repository}:<branch>, then record its PRs. Nothing was recorded.`).join(' '));
   }
-  const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body, ...(sources ? { sources } : {}), ...(branches ? { branches } : {}) } });
-  return result.commentId;
+  let prEvidence;
+  if (disposition != null || readback != null) {
+    const sender = roles ?? callerRoles(board.db, id);
+    if (!sender.some(role => ['implementer', 'manager'].includes(role))) throw ownerRule('Only the implementer or manager records PR disposition/readback.');
+    if (sources?.length !== 1) throw new Error('PR disposition/readback names one --pr and --pr-head.');
+    if (disposition != null && readback != null) throw new Error('Declare the disposition before recording its readback.');
+    prEvidence = await preparePrEvidence(board, id, sources[0], { disposition, target: release_target, readback, reason }, { manager: sender.includes('manager'), actor: actorOf() });
+    preparedPrEvidence.add(prEvidence);
+  }
+  try {
+    const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body, ...(sources ? { sources } : {}), ...(branches ? { branches } : {}), ...(prEvidence ? { pr_evidence: prEvidence } : {}) } });
+    return result.routed || result.accepted ? result : result.commentId;
+  } finally { if (prEvidence) preparedPrEvidence.delete(prEvidence); }
 }
 
 // ------------------------------------------------------------------ subscriptions
@@ -951,10 +1413,19 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
  * Subscribe `address` (a supercode session address) to a card's events from now on. `role` is `creator` (told of
  * starts, completion and blocks) or `worker` (told of updates to the card it works).
  */
-export function subscribeIn(db, id, address, role = 'creator', { explicit = false, own = false } = {}) {
+export function subscribeIn(db, id, address, role = 'creator', { explicit = false, own = false, check = false } = {}) {
   // a session that is an agent's main follows a card under its agent's address: one follower, one subscription
   if (!['worker', 'dependency'].includes(role)) address = followerAddress(address);
   if (personCustody(db, address)) return;
+  const outranked = FOLLOWER_RANKS.includes(role) ? FOLLOWER_RANKS.slice(FOLLOWER_RANKS.indexOf(role) + 1) : ['participant'];
+  if (check) {
+    const held = one(db, "SELECT delivery_metadata FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND chat_id=? AND thread_id=''", id, address);
+    if (!held) return true;
+    const metadata = json(held.delivery_metadata, {}) ?? {};
+    return Boolean(role === 'worker' && metadata.role !== 'worker' && ![].concat(metadata.also ?? []).includes('worker')
+      || (own || explicit) && metadata.own !== true || explicit && metadata.unsubscribed
+      || outranked.includes(metadata.role));
+  }
   const cursor = one(db, 'SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?', id).c;
   run(db, `INSERT OR IGNORE INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, chat_type, delivery_mode, delivery_metadata, created_at, last_event_id)
            VALUES (?, 'supercode', ?, '', 'dm', 'notify+wake', ?, ?, ?)`, id, address, JSON.stringify({ role, ...(own ? { own: true } : {}) }), now(), cursor);
@@ -970,7 +1441,6 @@ export function subscribeIn(db, id, address, role = 'creator', { explicit = fals
   // participant or creator that is the board's manager hears it as the manager, never as both. What the new role hears
   // is told from now on, never the card's history (the cursor moves to the card's last event).
   // A worker or a dependency follower takes over a participant's subscription, as before.
-  const outranked = FOLLOWER_RANKS.includes(role) ? FOLLOWER_RANKS.slice(FOLLOWER_RANKS.indexOf(role) + 1) : ['participant'];
   // the role it held is kept beside it (`also`): what that role heard, the follower still hears (a manager that created
   // a card is told its audit rounds as its creator was)
   // (only a follower's role is kept so, appended to what it kept before; a worker or dependency hears its own kinds)
@@ -1068,7 +1538,7 @@ export function unsubscribe(board, id, address) {
 }
 
 /** Reconcile only the current worker's audience, inside the binding transaction. */
-export function replaceWorkerSubscriptions(db, id, address) {
+export function replaceWorkerSubscriptions(db, id, address, { check = false } = {}) {
   const active = currentRun(db, id), session = active?.metadata?.supercode;
   const bound = session?.address ?? (session?.session_id && session.machine ? `sc:${session.machine}:${session.harness ?? 'claude-code'}:${session.session_id}` : null);
   if (!address || bound !== address || active.ended_at) return false;
@@ -1079,15 +1549,17 @@ export function replaceWorkerSubscriptions(db, id, address) {
   const removed = [];
   for (const { task_id: card } of family) {
     for (const old of replaces ? all(db, "SELECT chat_id,thread_id FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND json_extract(delivery_metadata,'$.role')='worker' AND chat_id!=?", card, address) : []) {
+      if (check) return true;
       run(db, "DELETE FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND chat_id=? AND thread_id=? AND json_extract(delivery_metadata,'$.role')='worker'", card, old.chat_id, old.thread_id);
       removed.push({ card, address: old.chat_id });
     }
     // INSERT OR IGNORE preserves an independent creator/manager subscription
     // and the current worker's existing cursor on repeated reconciliation.
-    subscribeIn(db, card, address, 'worker');
+    const needed = subscribeIn(db, card, address, 'worker', { check });
+    if (check && needed) return true;
   }
   if (removed.length) event(db, id, 'notice_subscriptions_replaced', { address, role: 'worker', superseded: removed, reason: 'the current worker binding replaced its audience' }, active.id);
-  return true;
+  return !check;
 }
 
 export function subscribe(board, id, address, role = 'creator', { own = false } = {}) {
@@ -1122,21 +1594,30 @@ export function subscribeDependency(board, ownerId, sourceId, { remove = false }
   });
 }
 
-export function reconcileDependencySubscriptions(db) {
-  for (const row of all(db, "SELECT * FROM kanban_notify_subs WHERE platform='supercode' AND json_extract(delivery_metadata,'$.dependent_card') IS NOT NULL")) {
+export function reconcileDependencySubscriptions(db, id, { check = false } = {}) {
+  for (const row of all(db, "SELECT * FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND json_extract(delivery_metadata,'$.dependent_card') IS NOT NULL", id)) {
     const metadata = json(row.delivery_metadata, {});
     const owner = getTask(db, metadata.dependent_card);
     const address = owner ? dependencyRecipient(db, owner.id) : null;
     const where = "WHERE task_id=? AND platform='supercode' AND chat_id=? AND thread_id=?";
     const identity = [row.task_id, row.chat_id, row.thread_id];
-    if (!owner || owner.detached || owner.archived || ['done', 'cancelled', 'archived'].includes(owner.status)) run(db, `DELETE FROM kanban_notify_subs ${where}`, ...identity);
+    if (!owner || owner.detached || owner.archived || ['done', 'cancelled', 'archived'].includes(owner.status)) {
+      if (check) return true;
+      run(db, `DELETE FROM kanban_notify_subs ${where}`, ...identity);
+    }
     // a subscription moved to its arc's new session starts from the card's last event: the new session is told what
     // happens from now on, never the card's history the old one was told or missed
     // (a subscription that waited for its arc to have a session keeps its cursor: what it waited to tell is still told)
-    else if (address && (address !== row.chat_id || metadata.waiting_recipient)) run(db, `UPDATE kanban_notify_subs SET chat_id=?,delivery_metadata=?,last_event_id=CASE WHEN ? THEN MAX(last_event_id,(SELECT COALESCE(MAX(id),0) FROM task_events WHERE task_id=?)) ELSE last_event_id END ${where}`,
-      address, JSON.stringify({ ...metadata, notice_wait: undefined, waiting_recipient: false, failures: 0 }), address !== row.chat_id ? 1 : 0, row.task_id, ...identity);
-    else if (!address && !metadata.waiting_recipient) run(db, `UPDATE kanban_notify_subs SET delivery_metadata=? ${where}`, JSON.stringify({ ...metadata, waiting_recipient: true }), ...identity);
+    else if (address && (address !== row.chat_id || metadata.waiting_recipient)) {
+      if (check) return true;
+      run(db, `UPDATE kanban_notify_subs SET chat_id=?,delivery_metadata=?,last_event_id=CASE WHEN ? THEN MAX(last_event_id,(SELECT COALESCE(MAX(id),0) FROM task_events WHERE task_id=?)) ELSE last_event_id END ${where}`,
+        address, JSON.stringify({ ...metadata, notice_wait: undefined, waiting_recipient: false, failures: 0 }), address !== row.chat_id ? 1 : 0, row.task_id, ...identity);
+    } else if (!address && !metadata.waiting_recipient) {
+      if (check) return true;
+      run(db, `UPDATE kanban_notify_subs SET delivery_metadata=? ${where}`, JSON.stringify({ ...metadata, waiting_recipient: true }), ...identity);
+    }
   }
+  return false;
 }
 
 /** A child hears what its parents' subscribers hear (Hermes copies them at link time); a subtask only its arc's session. */
@@ -1163,21 +1644,29 @@ export const subscriptions = (db, id = null) => (id ? all(db, 'SELECT * FROM kan
 
 // ------------------------------------------------------------------ reading
 
-export function listCards(db, { status = null, assignee = null, machine = null, includeArchived = false, includeSubtasks = true, nativeHolds = false } = {}) {
+export function listCards(db, { status = null, assignee = null, machine = null, includeArchived = false, includeSubtasks = true, nativeHolds = false, backlog = null } = {}) {
   const stateSql = cardStateSql({ nativeHolds });
-  const rows = all(db, `SELECT t.*, n.number, c.machine, c.subtask_of, c.stage, c.tags, c.paused, c.blocked_by FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id
-    WHERE (? IS NULL OR ${stateSql} = ? OR (? NOT IN ('paused','blocked') AND c.stage = ?)) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND ${CARD_VISIBILITY_SQL}
-    ORDER BY t.priority DESC, t.created_at ASC`, status, status, status, status, assignee, assignee, machine, machine, includeSubtasks ? 1 : 0, includeArchived ? 1 : 0);
+  const rows = all(db, `SELECT t.*, n.number, c.machine, c.subtask_of, c.stage, c.tags, c.paused, c.backlog, c.blocked_by FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id
+    WHERE (? IS NULL OR ${stateSql} = ? OR (? NOT IN ('paused','blocked') AND c.stage = ?)) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? IS NULL OR (c.backlog IS NOT NULL AND c.backlog != 'null') = ?) AND ${CARD_VISIBILITY_SQL}
+    ORDER BY t.priority DESC, t.created_at ASC`, status, status, status, status, assignee, assignee, machine, machine, backlog == null ? null : Number(Boolean(backlog)), backlog == null ? null : Number(Boolean(backlog)), includeSubtasks ? 1 : 0, includeArchived ? 1 : 0);
   return rows.map((r) => cardState({ ...r, skills: json(r.skills, []) ?? [], execution: executionOf(r.current_run_id ? one(db, 'SELECT id,metadata,ended_at FROM task_runs WHERE id=?', r.current_run_id) : null, readingContext(db, r.id, r.current_run_id)) }, { nativeHolds }));
 }
 
 export function showCard(db, id, options = {}) {
   const task = cardState({ ...must(db, id), reviewer: reviewerOf(db, id) }, options);
+  const review = options.review ? reviewedPullRequest(db, id) : null;
+  if (review) return {
+    task: { ...task, body: cardContext(db, id, options), result: null },
+    review_request: { id: review.id, kind: review.kind, payload: json(review.payload, {}) },
+    parents: [], children: [], subtasks: openPrReviewFindings(db, id, review),
+    pr_evidence: [], comments: [], events: [], runs: [], subscriptions: [],
+  };
   return {
     task,
     parents: parentsOf(db, id),
     children: childrenOf(db, id),
-    subtasks: all(db, `SELECT t.id, n.number, t.status, t.title, c.stage, c.paused, c.blocked_by FROM tasks t JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at`, id).map(row => cardState(row, options)),
+    subtasks: all(db, `SELECT t.id, n.number, t.status, t.title, c.stage, c.paused, c.backlog, c.blocked_by FROM tasks t JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at`, id).map(row => cardState(row, options)),
+    pr_evidence: all(db, "SELECT id,kind,payload FROM task_events WHERE task_id=? AND kind IN ('pr_disposition_recorded','pr_release_readback') ORDER BY id", id).map(row => ({ ...row, payload: json(row.payload, null) })),
     comments: all(db, 'SELECT author, body, created_at FROM task_comments WHERE task_id = ? ORDER BY id', id),
     runs: all(db, 'SELECT * FROM task_runs WHERE task_id = ? ORDER BY id', id).map((r) => ({ ...r, metadata: json(r.metadata, null) })),
     events: all(db, 'SELECT id, kind, payload, created_at, run_id FROM task_events WHERE task_id = ? ORDER BY id', id).map((e) => ({ ...e, payload: json(e.payload, null) })),
@@ -1189,13 +1678,49 @@ export function showCard(db, id, options = {}) {
 // existed is withheld there, naming why, so no prompt carries it.
 const cap = (text, n) => { text = text ? withheldIfDump(text) : text; return text && text.length > n ? `${text.slice(0, n)}… (${text.length - n} more characters)` : text; };
 
-/** What a session starting on a card reads first: the card, its parents' results, earlier attempts and the thread. */
+/** The PR review request the card's current reviewer run judges, or null: a plan or final review reads the whole arc. */
+export function reviewedPullRequest(db, id) {
+  const session = currentRun(db, id)?.metadata?.supercode;
+  if (session?.role !== 'reviewer' && session?.slot !== 'reviewer') return null;
+  const request = latestReviewRequest(db, id);
+  return request?.kind === 'pr' ? request : null;
+}
+
+/** Whether the calling session or run is the card's current reviewer: its brief, context and show are its review's. */
+export function reviewsCard(db, id, { sessionId = null, runId = null } = {}) {
+  const run = currentRun(db, id), session = run?.metadata?.supercode;
+  if (!run || run.ended_at != null || (session?.role !== 'reviewer' && session?.slot !== 'reviewer')) return false;
+  return (runId != null && Number(runId) === run.id) || (sessionId != null && session?.session_id === sessionId);
+}
+
+function reviewBody(request) {
+  const payload = json(request.payload, {});
+  return [
+    `PR review request ${request.id}. Review the named diff against its base, judged against the card's purpose above and the ADRs the change falls under, whether or not the diff edits them.`,
+    ...candidatePullRequests(payload.ci).map(p => `${p.pr.url} at ${p.commit ?? p.pr.head}${p.pr.base ? ` against ${p.pr.base}` : ''}${p.repository ? ` (${p.repository})` : ''}.`),
+    ...(payload.summary ? [`Summary: ${withheldIfDump(payload.summary)}`] : []),
+  ].join('\n');
+}
+
+/** What a session starting on a card reads first: the card, its parents' results, earlier attempts and the thread. A PR
+ *  review's reviewer (`review`) reads the card itself, then that PR's frozen candidate and its open findings in place of
+ *  the rest; each brief replaces the last in its retained conversation. */
 export function cardContext(db, id, options = {}) {
   const task = cardState(must(db, id), options);
   const out = [`# Card ${task.id}: ${task.title}`, ''];
   out.push(`Readable id: ${task.readable_id}.`);
   out.push(`Status: ${task.status}. Machine: ${task.machine ?? 'unset'}. Workspace: ${task.workspace_kind}${task.workspace_anchor ? ` ${task.workspace_anchor}` : task.workspace_path ? ` ${task.workspace_path}` : ''}${task.branch_name ? ` (branch ${task.branch_name})` : ''}.${task.subtask_of ? ` A subtask of ${task.subtask_of}.` : ''}`);
   if (task.body) out.push('', cap(task.body, 8 * 1024));
+  const review = options.review ? reviewedPullRequest(db, id) : null;
+  if (review) {
+    out.push('', reviewBody(review));
+    const findings = openPrReviewFindings(db, id, review);
+    if (findings.length) {
+      out.push('', '## This PR\'s open findings');
+      for (const finding of findings) out.push(`- ${finding.id} [${finding.status}] ${withheldIfDump(finding.title)}${finding.body ? `\n${withheldIfDump(finding.body)}` : ''}`);
+    }
+    return out.join('\n');
+  }
   const parents = all(db, 'SELECT t.id, t.title, t.result FROM tasks t JOIN task_links l ON l.parent_id = t.id WHERE l.child_id = ?', id);
   if (parents.length) {
     out.push('', '## Parent cards');
@@ -1285,9 +1810,17 @@ export function stats(db, options = {}) {
   for (const r of all(db, `SELECT t.assignee, ${stateSql} AS board_status, COUNT(*) AS n ${rows} WHERE t.status != 'archived' AND t.assignee IS NOT NULL GROUP BY t.assignee, board_status`)) (byAssignee[r.assignee] ??= {})[r.board_status] = Number(r.n);
   const byMachine = {};
   for (const r of all(db, `SELECT c.machine, ${stateSql} AS board_status, COUNT(*) AS n ${rows} WHERE t.status != 'archived' AND c.machine IS NOT NULL GROUP BY c.machine, board_status`)) (byMachine[r.machine] ??= {})[r.board_status] = Number(r.n);
-  const oldest = one(db, `SELECT MIN(t.created_at) AS ts ${rows} WHERE ${stateSql} = 'ready'`)?.ts;
+  const byLane = {};
+  for (const row of all(db, `SELECT COALESCE(c.stage,t.status) AS lane,COUNT(*) AS n ${rows} WHERE t.status != 'archived' GROUP BY lane`)) byLane[row.lane] = Number(row.n);
+  const backlog = { total: 0, by_assignee: {}, by_machine: {} };
+  for (const row of all(db, `SELECT t.assignee,c.machine,COUNT(*) AS n ${rows} WHERE t.status != 'archived' AND c.backlog IS NOT NULL AND c.backlog != 'null' GROUP BY t.assignee,c.machine`)) {
+    const count = Number(row.n); backlog.total += count;
+    if (row.assignee != null) backlog.by_assignee[row.assignee] = (backlog.by_assignee[row.assignee] ?? 0) + count;
+    if (row.machine != null) backlog.by_machine[row.machine] = (backlog.by_machine[row.machine] ?? 0) + count;
+  }
+  const oldest = one(db, `SELECT MIN(t.created_at) AS ts ${rows} WHERE ${stateSql} = 'ready' AND (c.backlog IS NULL OR c.backlog = 'null')`)?.ts;
   const t = now();
-  return { by_status: byStatus, by_assignee: byAssignee, by_machine: byMachine, oldest_ready_age_seconds: oldest ? t - Number(oldest) : null, now: t };
+  return { by_status: byStatus, by_lane: byLane, by_assignee: byAssignee, by_machine: byMachine, oldest_ready_age_seconds: oldest ? t - Number(oldest) : null, backlog, now: t };
 }
 
 export function runs(db, id, { stateType = null, stateName = null } = {}) {
@@ -1297,13 +1830,14 @@ export function runs(db, id, { stateType = null, stateName = null } = {}) {
 }
 
 /** Retain assignment facts in checkpoints, then delete old thread events of done and archived cards; their creation and
- *  branch records (branch_named, worktree_made) stay, by which a reopened card finds its worktree folder. */
+ *  branch records (branch_named, worktree_made) stay, by which a reopened card finds its worktree folder, and so do its
+ *  worktree's retirement records (worktree_kept, worktree_removed), by which gc reads a kept worktree again. */
 export function gcEvents(board, seconds) {
   return tx(board, db=>{
     const cut=now()-seconds;
     const cards=all(db,`SELECT DISTINCT task_id FROM task_events WHERE kind IN (${AGENT_KIND_LIST.map(()=>'?').join(',')}) AND created_at<? AND task_id IN (SELECT id FROM tasks WHERE status IN ('done','archived'))`,...AGENT_KIND_LIST,cut);
     let compacted=0;for(const card of cards)compacted+=compactCardAgentEvents(db,card.task_id);
-    return compacted+Number(run(db,"DELETE FROM task_events WHERE kind NOT IN ('created','branch_named','worktree_made') AND created_at<? AND task_id IN (SELECT id FROM tasks WHERE status IN ('done','archived'))",cut).changes);
+    return compacted+Number(run(db,"DELETE FROM task_events WHERE kind NOT IN ('created','branch_named','worktree_made','worktree_kept','worktree_removed') AND created_at<? AND task_id IN (SELECT id FROM tasks WHERE status IN ('done','archived'))",cut).changes);
   });
 }
 
@@ -1352,6 +1886,7 @@ export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, stran
   if (lost >= 2) out.push({ kind: 'repeated_session_loss', severity: 'warning', title: `its session was lost ${lost}x in 24h`, data: { lost }, actions: [`supercode workflow set ${task.id} machine <machine>`] });
   const crashes = events.filter((e) => e.kind === 'crashed' && t - e.created_at < 24 * 3600).length;
   if (crashes >= 2) out.push({ kind: 'repeated_crashes', severity: 'error', title: `its worker crashed ${crashes}x in 24h`, data: { crashes }, actions: [`supercode workflow log ${task.id}`] });
+  if (task.backlog) out.push({ kind: 'backlog', severity: 'info', title: holdDescription(task), data: { backlog: task.backlog, lane: task.stage ?? task.workflow_status ?? task.status }, actions: [`supercode workflow plan ${task.id}`] });
   if (task.status === 'paused') out.push({ kind: 'paused', severity: 'info', title: holdDescription(task), data: { paused: task.paused }, actions: [`supercode workflow resume ${task.id}`] });
   if (task.status === 'blocked' && (!nativeHolds || task.blocked_by.length)) {
     const since = [...events].reverse().find((e) => e.kind === 'blocked' || e.kind === 'gave_up')?.created_at ?? task.created_at;
@@ -1359,7 +1894,7 @@ export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, stran
     const cycles = events.filter((e) => e.kind === 'unblocked' && t - e.created_at < 24 * 3600).length;
     if (cycles >= 3) out.push({ kind: 'block_unblock_cycling', severity: 'warning', title: `block→unblock cycled ${cycles}x in 24h`, data: { cycles }, actions: [] });
   }
-  if (!task.detached && task.status === 'ready' && task.assignee) {
+  if (!task.detached && !task.backlog && task.status === 'ready' && task.assignee) {
     const since = [...events].reverse().find((e) => ['created', 'promoted', 'unblocked', 'reclaimed', 'session_lost', 'promoted_manual'].includes(e.kind))?.created_at ?? task.created_at;
     const age = t - since;
     if (age >= strandedSeconds) {
@@ -1394,8 +1929,11 @@ export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, stran
     for (const row of all(db, "SELECT kind, payload FROM task_events WHERE task_id = ? AND kind IN ('notice_filed', 'session_notice_filed', 'actor_notice_filed', 'board_message_sent') ORDER BY id DESC LIMIT 200", task.id)) {
       const p = json(row.payload, {}) ?? {};
       const what = row.kind === 'notice_filed' ? `its ${p.kind} notice` : row.kind === 'board_message_sent' ? 'its board mail' : `its ${row.kind.replace('_filed', '').replace('_', ' ')}`;
-      const expiry = p.message_id && expiredMail?.get(p.message_id), waiting = p.message_id && waitingMail?.get(p.message_id);
-      if (expiry) out.push({ kind: 'mail_expired', severity: 'warning', title: `${what} to ${expiry.to} was never delivered: ${expiry.reason} (${expiry.attempts} attempts); it stays unread in that mailbox`, data: { message_id: p.message_id, to: expiry.to, attempts: expiry.attempts, expired_at_ms: expiry.expired_at_ms }, actions: [] });
+      const recorded = p.message_id && expiredMail?.get(p.message_id), waiting = p.message_id && waitingMail?.get(p.message_id);
+      // a held failure its carrier later saw delivered is over (mail/carrier.mjs `delivered_at_ms`)
+      const expiry = recorded && !(recorded.held && recorded.delivered_at_ms != null) ? recorded : null;
+      if (expiry?.held) out.push({ kind: 'mail_expired', severity: 'warning', title: `${what} to ${expiry.to} is unconfirmed since ${at(expiry.held_since_ms ?? expiry.expired_at_ms)}: ${expiry.reason}; its recipient's input queue still holds it`, data: { message_id: p.message_id, to: expiry.to, held: true }, actions: [] });
+      else if (expiry) out.push({ kind: 'mail_expired', severity: 'warning', title: `${what} to ${expiry.to} was never delivered: ${expiry.reason} (${expiry.attempts} attempts); it stays unread in that mailbox`, data: { message_id: p.message_id, to: expiry.to, attempts: expiry.attempts, expired_at_ms: expiry.expired_at_ms }, actions: [] });
       else if (waiting) out.push({ kind: 'mail_waiting', severity: 'warning', title: waiting.waiting_for ? `${what} to ${waiting.to} is waiting for ${waiting.waiting_for} since ${at(waiting.since_ms)} (offline)` : `${what} to ${waiting.to} is waiting since ${at(waiting.since_ms)}: ${waiting.last_error ?? 'not delivered yet'}`, data: { message_id: p.message_id, to: waiting.to, waiting_for: waiting.waiting_for, since_ms: waiting.since_ms }, actions: [] });
     }
   }