@volter/supercode-orchestrator 0.5.228 → 0.5.229

package/board/workflow.mjs

@@ -17,12 +17,18 @@ import { randomBytes } from 'node:crypto';
 import { actorOf, appendRunObservation, boardKey, cardBranch, cardHandleOf, event as record, json, now } from './store.mjs';
 import { releaseAllSideSessions, sideSessions } from './side-sessions.mjs';
 import { evaluate, holds, render, needsSources } from './expr.mjs';
-import { completionEvidence, declaredWorkBranches, namedWorkBranch, reviewCandidate } from './ci.mjs';
+import { completionEvidence, declaredWorkBranches, namedWorkBranch, pendingReviewRequests, reviewCandidate } from './ci.mjs';
 import { branchClaim, cardCommitsOn, isLocalWorkspace, isWorkspacePath, unrecordedMaking } from './workspace.mjs';
 import { cardName, cardNumber, identifyNotice, numbered } from './notices.mjs';
-import { latestEvent } from './queries.mjs';
+import { dispatchWait, latestEvent } from './queries.mjs';
+import { PAUSE_DEADLINE, RESTING_WRITE_MODE, assertRestingWrite, assertBacklogQualified, deadlineUntil } from './resting-state.mjs';
+import { authorizeReplacement } from './session-continuity.mjs';
+import { endedHere } from '../agents.mjs';
 
 const loaded = new Map();
+// Authority requests keep their named decision maker; ordinary missing detail stays with the requested act.
+export const ownerRule = message => Object.assign(new Error(message), { ownerRule: true });
+export const requestDetail = message => Object.assign(new Error(message), { boardDetail: true });
 // the owner's read door holds the workflow the owner reads (owner-door.mjs), told when it is read again
 const workflowWatchers = new Set();
 const hold = (root, entry) => {
@@ -76,6 +82,7 @@ export async function loadWorkflow(root) {
 // What the board's view of a home is decoded from: the workflow, each profile's config, credentials and the agent
 // layer, persona, and which profiles there are. A session store or a run log changing is no change to it.
 const DECODED = /^(?:(?:profiles\/[^/]+\/)?(?:config\.yaml|\.env|agents\.json|AGENTS\.md)|workflow\.yaml|profiles(?:\/[^/]+)?)$/;
+const homeFollowers = new Map();
 
 /**
  * Follow the home's own files, so the held view is read again on its next use after one it is decoded from changes:
@@ -85,6 +92,28 @@ const DECODED = /^(?:(?:profiles\/[^/]+\/)?(?:config\.yaml|\.env|agents\.json|AG
  * Answers a stop.
  */
 export function followHome(root, { onChange = () => {}, onLost = () => {} } = {}) {
+  let held = homeFollowers.get(root);
+  const follower = { onChange, onLost };
+  if (!held) {
+    held = { followers: new Set([follower]), stop: null };
+    homeFollowers.set(root, held);
+    try {
+      held.stop = watchHome(root, {
+        onChange: name => { for (const subscriber of held.followers) subscriber.onChange(name); },
+        onLost: error => { for (const subscriber of held.followers) subscriber.onLost(error); },
+      });
+    } catch (error) { homeFollowers.delete(root); throw error; }
+  } else held.followers.add(follower);
+  // Preparation and serving share one continuous watch. Attaching the serving callbacks must not invalidate the
+  // preparatory read: that read is already newer than this watch, and real file events alone make it stale.
+  return () => {
+    if (!held.followers.delete(follower) || held.followers.size) return;
+    held.stop();
+    if (homeFollowers.get(root) === held) homeFollowers.delete(root);
+  };
+}
+
+function watchHome(root, { onChange, onLost }) {
   let watcher = null;
   let stopped = false;
   // A decoded file that is a link (a workflow kept in another checkout) is watched at its real target too, in the
@@ -236,7 +265,7 @@ function pattern(p) {
 // running git here on a path of that machine (a Windows path read on a Mac answered no commits for as long as the card
 // ran: volter-org t_9a9c2a9c). A folder that is not there, a git that did not answer, a machine that could not be asked:
 // unknown, with why, and never "no commits".
-const commitTimes = new Map(); // `${path}:${id}` → { at, known, value, error }
+const commitTimes = new Map(); // `${path}:${id}` → { at, inputs, known, value, error }
 // A commit names the card by its id or by its keyed number (`VO-856`); a branch is the card's by its handle too.
 async function readCardCommit(path, id, branches, handle = null) {
   if (!existsSync(path)) return { known: false, value: null, error: `no folder ${path} on this machine` };
@@ -283,14 +312,16 @@ async function readCardCommit(path, id, branches, handle = null) {
 async function observeLastCommit(path, id, branches = [], machine = null, handle = null) {
   if (!path) return null;
   const key = `${path}:${id}`;
+  // Reuse a reading across rounds, while a changed declaration or machine is read immediately.
+  const inputs = JSON.stringify([machine, [...new Set(branches)].sort(), handle?.toUpperCase() ?? null]);
   const cached = commitTimes.get(key);
-  if (cached && now() - cached.at < 15) return cached.value;
+  if (cached?.inputs === inputs && now() - cached.at < 15) return cached.value;
   let reading;
   try {
     if (isLocalWorkspace({ machine })) reading = await readCardCommit(path, id, branches, handle);
     else reading = { known: true, value: (await cardCommitsOn(machine, path, id, branches, handle?.toUpperCase() ?? null)).at };
   } catch (error) { reading = { known: false, value: null, error: String(error?.message ?? error).slice(0, 300) }; }
-  commitTimes.set(key, { at: now(), ...reading });
+  commitTimes.set(key, { at: now(), inputs, ...reading });
   return reading.value;
 }
 
@@ -315,13 +346,15 @@ export function sessionProgress(db, task) {
   const read = path ? commitTimes.get(`${path}:${task.id}`) ?? { known: false, error: 'its checkout has not been read yet' } : { known: true, value: null };
   return { event: Number(event?.id ?? 0), commit: read.known ? Number(read.value ?? 0) : null, ...(read.known ? {} : { commit_unread: read.error ?? 'its checkout could not be read' }) };
 }
-/** Observe external facts before entering an optimistic board mutation. */
+/** Observe external facts before entering an optimistic board mutation. `commits: true` reads the card's commits
+ *  fresh, as every decision on them must; `commits: 'cached'` is the idle pass's alone and reuses a reading under 15 s
+ *  old with the same declaration, so a board of running cards does not spawn git for each card every round. */
 export async function refreshCardInputs(board, id, { commits = false } = {}) {
   const task=board.db.prepare('SELECT t.*,c.subtask_of FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
   if (!task)return;
   if (commits && !task.subtask_of) {
     const { path, machine } = commitSource(board.db, task);
-    if(path)commitTimes.delete(`${path}:${id}`);
+    if (path && commits !== 'cached') commitTimes.delete(`${path}:${id}`);
     await observeLastCommit(path,id,declaredWorkBranches(board.db,id),machine,cardHandleOf(board,id));
   }
 }
@@ -471,8 +504,9 @@ function bodyBlocks(body) {
   return blocks;
 }
 /** Whether `body` is `was` with only outcomes ticked: each changed outcome (a checkbox item under the Acceptance heading,
- *  read whole with its continuation lines) was `- [ ] X` and is now `- [x] X` or `- [x] X: <pointer>`, or was `- [x] X`
- *  and is now `- [x] X: <pointer>` (the pointer a tick needs, added after it); no other line added, removed or changed. */
+ *  read whole with its continuation lines) was `- [ ] X` and is now `- [x] X: <pointer>`, or was `- [x] X`
+ *  and is now `- [x] X: <pointer>` (the pointer a tick needs, added after it). The tick and pointer go on the outcome's
+ *  own line and its continuation lines stay unchanged; no other line added, removed or changed. */
 function onlyTicks(was, body) {
   if (typeof body !== 'string') return false;
   const before = bodyBlocks(was);
@@ -483,13 +517,18 @@ function onlyTicks(was, body) {
     const now = after[i];
     if (block.lines.join('\n') === now.lines.join('\n')) return true;
     if (block.section !== 'acceptance' || !block.item || !now.item) return false;
-    const pointed = (ticked) => now.text.startsWith(`${ticked}: `) && now.text.trim().length > ticked.trim().length + 1;
-    // Outcome prose may contain colons. Preserve the entire old item and permit only an appended pointer.
-    if (TICKED_OUTCOME.test(block.text)) return pointed(block.text);
-    const open = OPEN_OUTCOME.exec(block.text);
-    if (!open) return false;
-    const ticked = `${open[1]}[x] ${open[2]}`;
-    return now.text === ticked || pointed(ticked);
+    // Outcome prose may contain colons. Preserve the entire old outcome and permit only an appended pointer.
+    const ticks = (old, text) => {
+      const pointed = (ticked) => text.startsWith(`${ticked}: `) && text.slice(ticked.length + 2).trim().length > 0;
+      if (TICKED_OUTCOME.test(old)) return pointed(old);
+      const open = OPEN_OUTCOME.exec(old);
+      if (!open) return false;
+      const ticked = `${open[1]}[x] ${open[2]}`;
+      return pointed(ticked);
+    };
+    // The tick and its pointer go on the outcome's own line, its continuation lines (its `- source:` lines) unchanged,
+    // as a bare outcome is ticked.
+    return block.lines.slice(1).join('\n') === now.lines.slice(1).join('\n') && ticks(block.lines[0], now.lines[0]);
   });
 }
 
@@ -540,10 +579,10 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
   const coderProfile = once(() => entry?.profiles?.[codingProfile()]);
   const configuredCoder = once(() => coderProfile()?.worker);
   const changes = once(() => json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'changes_requested' ORDER BY id DESC LIMIT 1", task.id)?.payload, {}) ?? {});
-  const interruption = once(() => json(one(db, `SELECT payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'block_loop_detected', 'dependency_wait', 'gave_up',
-    'unblocked', 'changes_requested', 'review_reopened', 'status', 'reclaimed', 'stale', 'timed_out', 'crashed', 'spawn_failed', 'rate_limited', 'session_lost')
-    ORDER BY id DESC LIMIT 1`, task.id)?.payload, {}) ?? {});
-  const lastBlock = once(() => one(db, "SELECT kind, payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked', 'dependency_wait') ORDER BY id DESC LIMIT 1", task.id));
+  const interruption = once(() => json(latestEvent(db, task.id, ['blocked', 'block_loop_detected', 'dependency_wait', 'gave_up',
+    'unblocked', 'changes_requested', 'review_reopened', 'status', 'reclaimed', 'stale', 'timed_out', 'crashed', 'spawn_failed', 'rate_limited', 'session_lost'],
+    'payload')?.payload, {}) ?? {});
+  const lastBlock = once(() => latestEvent(db, task.id, ['blocked', 'unblocked', 'dependency_wait'], 'kind,payload'));
   const waitingOn = once(() => lastBlock()?.kind === 'blocked' ? json(lastBlock().payload, {})?.waiting_on ?? null : null);
   const currentRun = once(() => task.current_run_id ? one(db, 'SELECT metadata FROM task_runs WHERE id = ?', task.current_run_id) : null);
   const session = once(() => json(currentRun()?.metadata, {})?.supercode ?? {});
@@ -560,6 +599,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     status,
     blocked_by: blocks,
     paused: json(state.paused, null),
+    backlog: json(state.backlog, null),
     detached: json(state.detached, null),
     // the person the card is assigned to (custody.mjs personOf), or null: a person's card runs no session and closes on
     // that person's completion
@@ -592,8 +632,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     // `paused`: a paused subtask's pause (who and why), or null; a paused subtask holds no review of its arc
     get subtasks() { return all(db, `SELECT t.id, ${related}, t.title, t.assignee, c.paused FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at`, task.id)
       .map((t) => ({ ...t, paused: json(t.paused, null) })); },
-    get queue_reason() { return json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'respawn_guarded' AND created_at >= ? ORDER BY id DESC LIMIT 1",
-      task.id, Number(one(db, 'SELECT since FROM supercode_cards WHERE task_id = ?', task.id)?.since ?? 0))?.payload, {})?.reason ?? null; },
+    get queue_reason() { return dispatchWait(db, task.id)?.reason ?? null; },
     // the message whose answer the standing block waits for (`block --waiting-on`), and that answer's id once it has landed
     get waiting_on() { return waitingOn(); },
     get state_request() { return stateRequestOf(db, task.id); },
@@ -604,7 +643,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     // whether an edit of its text only ticks outcome lines (the card's own session's door to its acceptance)
     only_ticks: (body) => onlyTicks(task.body, body),
     asked_of: () => askedOf(waitingOn()),
-    get last_block_event() { return one(db, "SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked') ORDER BY id DESC LIMIT 1", task.id)?.kind ?? null; },
+    get last_block_event() { return latestEvent(db, task.id, ['blocked', 'unblocked'], 'kind')?.kind ?? null; },
     // where the latest interruption says the card resumes (any status the workflow declares); none recorded: null
     get resume_status() { const value = interruption(); return value.resume_status ?? value.retry_status ?? value.source_status ?? null; },
     get last_run() { return lastRun() ?? {}; },
@@ -688,7 +727,7 @@ function queueTransitionNotice(db, board, entry, task, from, name, payload, befo
   if (adopting) return;
   const after = cardOf(db, task.id), to = statusOf(db, after);
   const targetRun = beforeRun;
-  const state = (t, status) => JSON.stringify([status, t.current_run_id, t.paused, t.archived, t.blocked_by]);
+  const state = (t, status) => JSON.stringify([status, t.current_run_id, t.paused, t.backlog, t.archived, t.blocked_by]);
   const beforeState = json(beforeRun?.metadata, {})?.supercode?.state;
   const afterState = beforeRun && json(one(db, 'SELECT metadata FROM task_runs WHERE id=?', beforeRun.id)?.metadata, {})?.supercode?.state;
   if (!targetRun || (state(task, from) === state(after, to) && beforeState === afterState) || effects.some((e) => e.kind === 'session_notice' && e.runId === targetRun.id)) return;
@@ -756,24 +795,40 @@ function declaredStatus(db, board, entry, task) {
  * `{ from, to, effects }`; throws the refusal when no transition applies or a validator fails.
  */
 export function validateEvent(db, board, entry, id, name, { roles = [], payload = {}, extra = {}, localOnly = false } = {}) {
-  // A card ends with its reason: a cancel or archive that says nothing why is refused, whoever sends it, the manager
-  // included. The reason is all the next reader of an ended card has (an empty-reason cancel once ended an arc that had
-  // shipped half, and nothing on the card said so).
-  if ((name === 'cancel' || name === 'archive') && !String(payload?.reason ?? '').trim()) throw new Error(`${id}: ${name} needs a reason (--reason <why>)`);
+  // Attribute an omitted reason to the request itself; never invent evidence about the work.
+  if ((name === 'cancel' || name === 'archive') && !String(payload?.reason ?? '').trim())
+    payload = { ...payload, reason: 'none given' };
   // A card the document no longer lists (a removal the document cannot make) still takes the manager's cancel or
   // archive: that ends it the way the document already has, and is the one way a manager clears it.
-  if (db.boardErrors?.has(id) && !(/cannot change card removal/.test(db.boardErrors.get(id)) && ['cancel', 'archive'].includes(name) && roles.includes('manager'))) throw new Error(`${id}: ${db.boardErrors.get(id)}`);
+  if (db.boardErrors?.has(id) && !(/cannot change card removal/.test(db.boardErrors.get(id)) && ['cancel', 'archive'].includes(name) && roles.includes('manager'))) throw requestDetail(`${id}: ${db.boardErrors.get(id)}`);
   const { workflow, params } = entry;
   if (workflow.run && (workflow.run.on?.[name] || Object.values(workflow.run.states ?? {}).some((s) => s.on?.[name]))) return null;
   const task = cardOf(db, id);
   const from = localOnly ? statusOf(db, task) : declaredStatus(db, board, entry, task);
+  // Normalize relative durations on the board clock, before workflow guards see the event.
+  if (name === 'pause') {
+    if (!roles.includes('manager')) throw ownerRule('only the manager pauses a card');
+    assertRestingWrite('paused', payload, task.paused);
+    if (RESTING_WRITE_MODE !== 'legacy-holds') payload = { ...payload, until: deadlineUntil(payload.until ?? '1h', now(), 'pause') };
+  }
+  if (name === 'backlog' || name === 'plan') {
+    if (name === 'backlog') assertRestingWrite('backlog', payload);
+    if (name === 'backlog' && ['done', 'archived', 'cancelled'].includes(storedAs(workflow, from))) throw requestDetail('an ended card cannot enter backlog');
+    if (name === 'backlog' && payload.pause_revision != null && !task.paused) throw requestDetail('backlog migration refused: the named pause is no longer current');
+    if (name === 'backlog' && task.paused) {
+      const revision = task.paused.generation ?? latestEvent(db, id, ['paused'], 'id')?.id;
+      if (revision == null || String(payload.pause_revision ?? '') !== String(revision)) throw requestDetail('backlog migration requires --pause-revision naming the current pause generation (or its legacy paused event id)');
+    }
+  }
+  const expiry = workflow.flags?.paused?.expires;
+  if (payload.expired_generation != null && !dueFlagExpiry(task, name, roles, payload, expiry)) throw requestDetail('pause expiry is stale, early, or not authorized by this workflow');
   if (localOnly && !workflow.statuses[from]) return null; // only fire adopts an imported status
   const candidates = transitionsFor(workflow, from, name);
   // a refusal names the right form: each transition's description, its card placeholders filled with this card
   const said = (t) => t.description ? String(t.description).replaceAll('<arc>', id).replaceAll('<card>', id) : null;
   if (!candidates.length) {
     const elsewhere = (workflow.verbs?.[name] ?? []).filter((t) => t.from?.length && t.description);
-    throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} does not apply there.${elsewhere.map((t) => ` From ${t.from.join(' or ')}: ${said(t)}`).join('')}`);
+    throw requestDetail(`${id} is ${from}; ${name.replace(/_/g, '-')} does not apply there.${elsewhere.map((t) => ` From ${t.from.join(' or ')}: ${said(t)}`).join('')}`);
   }
   // `sender`: the roles the event was sent with (a validator can ask who is asking)
   const scope = scopeOf(db, board, task, { params, event: payload, lazy: localOnly, deferSources: localOnly, extra: { lanes: lanesIn(entry), ...extra, sender: roles, verb: name } });
@@ -782,7 +837,7 @@ export function validateEvent(db, board, entry, id, name, { roles = [], payload
     const state = name === 'complete' ? 'done' : name === 'cancel' ? 'cancelled' : null;
     const request = state && candidates.some(transition => transition.by?.includes('creator'))
       ? ` Ask the manager with workflow request-state ${id} --state ${state} --reason <why> --evidence <verdict-and-pointers>.` : '';
-    throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(candidates.flatMap((t) => t.by ?? []))].join(' or ')}. ${candidates.map(said).filter(Boolean).join(' ')}${request}`);
+    throw ownerRule(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(candidates.flatMap((t) => t.by ?? []))].join(' or ')}. ${candidates.map(said).filter(Boolean).join(' ')}${request}`);
   }
   // A source-dependent branch is undecidable before observation; preflight must not choose its fallback.
   const needsSource = expr => needsSources(expr, workflow.derived);
@@ -792,14 +847,12 @@ export function validateEvent(db, board, entry, id, name, { roles = [], payload
   // none of the sender's rules holds, but another role's does (one verb with a rule per case, as `set` has one per
   // field): it is that role's to send
   const theirs = taken ? [] : candidates.filter((t) => !allowed.includes(t) && holds(t.guard ?? null, scope));
-  if (theirs.length) throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(theirs.flatMap((t) => t.by ?? []))].join(' or ')}. ${theirs.map(said).filter(Boolean).join(' ')}${allowed.length ? ` Yours: ${allowed.map(said).filter(Boolean).join(' ')}` : ''}`);
+  if (theirs.length) throw ownerRule(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(theirs.flatMap((t) => t.by ?? []))].join(' or ')}. ${theirs.map(said).filter(Boolean).join(' ')}${allowed.length ? ` Yours: ${allowed.map(said).filter(Boolean).join(' ')}` : ''}`);
   if (!taken) {
-    const state = scope.card;
-    const reasons = [state.paused && `paused: ${state.paused.reason ?? 'manager pause'}`,
-      state.blocked_by.length && `blocked by ${state.blocked_by.map(b => b.id).join(', ')}`,
-      state.dispatch_hold && 'dispatch held', state.current_run_id && `current run ${state.current_run_id}`,
-      state.archived && 'archived'].filter(Boolean);
-    const none = new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} cannot proceed: ${reasons.join('; ') || `guard ${allowed.map(t => t.guard).join(' | ')}`}`);
+    // Only the evaluated rules explain a refusal. Incidental state, such as a current run, need not be a condition
+    // of any rule and must not be reported as its cause.
+    const reasons = allowed.map(t => `failed rule ${t.guard}${said(t) ? ` (${said(t)})` : ''}`);
+    const none = new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} cannot proceed: ${reasons.join(' | ')}`);
     none.noTransition = true; throw none;
   }
   for (const v of taken.validate ?? []) {
@@ -822,13 +875,18 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
   if (name === 'specify' && taken.target && (entry.workflow.statuses[from]?.run_role === 'reviewer' || ['done', 'archived'].includes(storedAs(entry.workflow, from))))
     taken = { ...taken, target: undefined };
   const to = take(db, board, entry, task, from, taken, scope, effects);
+  // A kept reviewer is closed by any set on the card, its end or its move to backlog, whatever its status (ADR 0019).
+  const after = cardOf(db, id);
+  if (name === 'set' || after.backlog || after.archived || ['done', 'cancelled', 'archived'].includes(storedAs(entry.workflow, statusOf(db, after))))
+    closeKeptReviewer(db, id, effects);
   settle(db, board, entry, id, effects);
   projectStatus(db, board, entry, id);
-  // A manager's or creator's explicit act releases a hold, and a run it ends is their decision: the ended-run audit
-  // never turns it into an incident that waits for a second act
+  // Explicit recovery or reconfiguration can release a hold, and a run it ends is their decision: the ended-run
+  // audit never turns it into an incident that waits for a second act. Resume clears only its pause, through the
+  // same declared actions whether the manager or deadline invokes it; independent dispatch holds remain.
   const ended = task.current_run_id && one(db, 'SELECT ended_at FROM task_runs WHERE id = ?', task.current_run_id)?.ended_at != null ? task.current_run_id : null;
   if ((scope.card.dispatch_hold || ended) && roles.some(role => ['manager','creator'].includes(role)) &&
-      (['resume','reclaim','replace_session','reopen','reopen_review','return_review'].includes(name) || (name === 'set' && ['assignee','machine','model'].includes(payload.field))))
+      (['reclaim','replace_session','reopen','reopen_review','return_review'].includes(name) || (name === 'set' && ['assignee','machine','model'].includes(payload.field))))
     record(db,id,'dispatch_released',{reason:`explicit ${name}`,incident:scope.card.last_events.run_incident?.payload?.run ?? null,...(ended ? { ended_run: ended } : {}),
       ...(ended && name === 'set' && payload.field === 'assignee' && (payload.value ?? null) !== (task.assignee ?? null)
         ? { reassigned_from: task.assignee ?? null, reassigned_to: payload.value ?? null, abandon_waiting_input: true } : {})});
@@ -863,7 +921,7 @@ function cardOf(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) throw new Error(`no card ${id}`);
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), detached: json(ours?.detached, null), archived: Boolean(ours?.archived), skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
+  return { ...row, 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), skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
 }
 
 // one transition: the old status's exit actions, the move, the transition's actions, the new status's entry actions
@@ -872,7 +930,6 @@ function take(db, board, entry, task, from, transition, scope, effects) {
   const target = transition.target ? String(templateValue(transition.target, scope) ?? '') : null;
   if (target && !workflow.statuses[target]) throw new Error(`the workflow moves ${task.id} to ${target}, which it does not declare`);
   const moves = target && target !== from;
-  if (moves && scope.card.paused) throw new Error('a paused card must be resumed before its stage can change');
   const ctx = { db, board, entry, id: task.id, scope: { ...scope, before: scope.card }, from, to: target ?? from, effects, runId: task.current_run_id ?? null };
   if (moves) for (const a of workflow.statuses[from].exit ?? []) act(ctx, a);
   if (moves) setStatus(db, workflow, task.id, target);
@@ -880,16 +937,34 @@ function take(db, board, entry, task, from, transition, scope, effects) {
   if (moves) {
     for (const a of workflow.statuses[target].entry ?? []) act(ctx, a);
     if (workflow.statuses[target].run || workflow.statuses[target].run_role) effects.push({ kind: 'run', id: task.id, status: target });
+    // a card's final close (done, cancelled, archived) retires the workspace the board made for it, whatever the
+    // workflow declares: removed only when that loses nothing, else kept and described on the card (engine cleanupWorkspace)
+    if (['done', 'cancelled', 'archived'].includes(storedAs(workflow, target))) queueCleanup(db, task.id);
   }
   return target ?? from;
 }
 
+/** Card `id`'s workspace cleanup recorded once for the delivery pass (engine runEffects), which reads its machine's git
+ *  outside any verb or round and tries again while that machine cannot answer; a card not closed when it runs is left.
+ *  Its kind is `retire_workspace`, which a reader from before this rule does not know and drops unread: that reader's
+ *  `cleanup_workspace` forces the worktree's removal, so a rollback leaves the folder rather than losing what is in it. */
+export function queueCleanup(db, id, { scratch = false } = {}) {
+  // one row per card: a workflow that declares cleanup_workspace also has its card's board-made scratch folder removed
+  // (engine cleanupWorkspace), so its ask turns a pending row's scratch on rather than queueing a second retirement
+  const plain = JSON.stringify({ kind: 'retire_workspace', id }), withScratch = JSON.stringify({ kind: 'retire_workspace', id, scratch: true });
+  if (one(db, 'SELECT 1 FROM supercode_effects WHERE effect = ? AND failed_at IS NULL', withScratch)) return;
+  const pending = one(db, 'SELECT id FROM supercode_effects WHERE effect = ? AND failed_at IS NULL', plain);
+  if (pending) { if (scratch) run(db, 'UPDATE supercode_effects SET effect = ? WHERE id = ?', withScratch, pending.id); return; }
+  run(db, 'INSERT INTO supercode_effects (effect) VALUES (?)', scratch ? withScratch : plain);
+}
+
 /** Put the card in `status`: kanban.db holds its `stored_as`, our table the exact name where they differ. */
 export function setStatus(db, workflow, id, status) {
   const stored = storedAs(workflow, status);
   run(db, 'UPDATE tasks SET status = ? WHERE id = ?', stored, id);
   run(db, `INSERT INTO supercode_cards (task_id, stage, since, after_fired) VALUES (?, ?, ?, NULL)
            ON CONFLICT(task_id) DO UPDATE SET stage = excluded.stage, since = excluded.since, after_fired = NULL`, id, stored === status ? null : status, now());
+  record(db, id, 'stage_entered', { status });
   // an arc that ends releases its side sessions with it (side-sessions.mjs)
   if (['done', 'archived'].includes(stored) && !db.prepare('SELECT subtask_of FROM supercode_cards WHERE task_id = ?').get(id)?.subtask_of) releaseAllSideSessions(db, id, `${id} is ${status}`);
 }
@@ -902,6 +977,11 @@ export function settle(db, board, entry, id, effects = []) {
   for (let hops = 0; hops < 16; hops += 1) {
     const task = cardOf(db, id);
     const from = statusOf(db, task);
+    // Backlog freezes runnable lifecycle movement, while relations and terminal cleanup still settle. An ended
+    // parent may retain its backlog attribution, but its open children must resume/cancel through their workflow.
+    if (task.backlog && !['done', 'archived'].includes(storedAs(workflow, from))) {
+      projectStatus(db, board, entry, id); return effects;
+    }
     const state = workflow.statuses[from];
     // An unchanged card with no automatic/timed moves needs no history scope at all. The organization's five
     // statuses have none, but recomputeReady used to read every history field on every unsettled card anyway.
@@ -944,6 +1024,42 @@ function dueAfter(db, workflow, task, status, scope) {
   return null;
 }
 
+// Expiry is a narrowly delegated ordinary event, not platform authority to clear arbitrary flags.
+function dueFlagExpiry(task, name, roles, payload, expiry) {
+  const pause = task.paused;
+  return Boolean(expiry?.at === 'card.paused.until' && expiry.event === name && roles.includes('platform') && pause?.generation
+    && payload.expired_generation === pause.generation && Number.isSafeInteger(pause.until) && pause.until <= now());
+}
+
+/** Indexed current deadlines only; called transactionally before admission and idle observation. */
+export function settleExpiringFlags(db, board, entry, effects = []) {
+  const expiry = entry.workflow.flags?.paused?.expires;
+  if (!expiry) return 0;
+  if (expiry.at !== 'card.paused.until' || !expiry.event) throw new Error('paused.expires must name card.paused.until and its ordinary resume event');
+  let count = 0;
+  for (;;) {
+    const due = all(db, `SELECT task_id,paused FROM supercode_cards WHERE paused IS NOT NULL AND ${PAUSE_DEADLINE} <= ?
+      AND json_type(paused,'$.until')='integer' AND length(json_extract(paused,'$.generation'))>0 ORDER BY ${PAUSE_DEADLINE},task_id LIMIT 64`, now());
+    if (!due.length) break;
+    for (const row of due) {
+      const pause = json(row.paused, null);
+      const result = fire(db, board, entry, row.task_id, expiry.event, { roles: ['platform'], payload: {
+        expired_generation: pause.generation, reason: `pause expired at ${new Date(pause.until * 1000).toISOString()}`,
+      } });
+      if (cardOf(db, row.task_id).paused) throw new Error(`${row.task_id}: declared pause expiry did not clear its flag`);
+      effects.push(...result.effects); count++;
+    }
+  }
+  return count;
+}
+
+/** The next current deadline drives the owner's wake even when launches are disabled. */
+export function nextFlagExpiry(db, entry) {
+  if (!entry.workflow.flags?.paused?.expires) return null;
+  return one(db, `SELECT ${PAUSE_DEADLINE} AS at FROM supercode_cards WHERE paused IS NOT NULL AND ${PAUSE_DEADLINE} IS NOT NULL
+    AND json_type(paused,'$.until')='integer' AND length(json_extract(paused,'$.generation'))>0 ORDER BY ${PAUSE_DEADLINE},task_id LIMIT 1`)?.at ?? null;
+}
+
 /**
  * Where a new card starts: the first `initial` transition that holds (`event` is the create's own words), its status
  * set and its actions run (a goal card by the workflow's default, for one). Answers the status. A validator that fails
@@ -982,6 +1098,11 @@ function act(ctx, action) {
 // what happens is the workflow's. A kind with no entry here carries the event's own fields.
 const firstLine = (text) => String(text ?? '').trim().split('\n')[0].slice(0, 400) || null;
 const FORMAT = {
+  paused: ({ e, after }) => ({ reason: after.paused?.reason ?? e.reason, until: after.paused?.until, generation: after.paused?.generation, by: after.paused?.by }),
+  pause_extended: ({ before, after }) => ({ ...after.paused, previous: before.paused }),
+  resumed: ({ e, before }) => ({ reason: e.reason ?? null, pause: before.paused, cause: e.expired_generation ? 'expired' : 'manager', ...(e.expired_generation ? { expired_generation: e.expired_generation } : {}) }),
+  backlogged: ({ after, before }) => ({ ...after.backlog, previous_lane: before.status }),
+  planned: ({ e, before }) => ({ reason: e.reason ?? null, backlog: before.backlog }),
   completed: ({ e }) => {
     const artifacts = Array.isArray(e.metadata?.artifacts) ? e.metadata.artifacts.filter((a) => typeof a === 'string' && a.trim()) : [];
     return { ci: e.ci ?? null, result_len: e.result ? String(e.result).length : 0, summary: firstLine(e.summary ?? e.result), ...(artifacts.length ? { artifacts } : {}) };
@@ -990,15 +1111,17 @@ const FORMAT = {
   block_loop_detected: ({ e, after, source, params }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), limit: params.block_recurrence_limit, source_status: source }),
   dependency_wait: ({ e, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, source_status: source }),
   review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), ci: e.ci ?? null, pr: e.ci?.pr ?? null, commit: e.ci?.commit ?? null,
+    requested_pr: e.pr ?? null, requested_pr_head: e.pr_head ?? null,
     implementer: before.assignee, implementer_machine: before.machine ?? null, implementer_model: before.implementer_model ?? null,
     implementer_model_override: before.model_override ?? null, implementer_provider_override: before.provider_override ?? null, reviewer: after.assignee }),
   // the reviewer is the lane that reviewed (the card's assignee while in review), unless the verdict names one
   changes_requested: ({ e, before, after }) => ({ reason: e.reason ?? null, reviewer: e.reviewer ?? before.assignee ?? null, implementer: after.assignee }),
   review_reopened: ({ after, to }) => ({ status: to, implementer: after.assignee }),
   // the manager's return of a review with no verdict: the request it returned and its run, so the next review's selection
-  // reads which heads it named (ci.mjs returnedReview)
+  // reads which heads it named (ci.mjs returnedReview); a reopen-review return names the re-declaration it answered
+  // (`redeclared`), and holds none
   review_returned: ({ e, before, after, to }) => ({ reason: e.reason ?? null, status: to, review_request: before.last_events.review_requested?.id ?? null,
-    review_run: before.current_run_id ?? null, implementer: after.assignee }),
+    review_run: before.current_run_id ?? null, implementer: after.assignee, ...(e.redeclared ? { redeclared: e.redeclared } : {}) }),
   review_voided: ({ e, before }) => ({ reason: e.reason, review_request: before.last_events.review_requested?.id ?? null,
     review_run: before.latest_review?.id ?? null, verdict: Math.max(before.last_events.review_pass?.id ?? 0, before.last_events.changes_requested?.id ?? 0) || null }),
   // what arrived (an unblock says it), and where the card resumes
@@ -1027,14 +1150,14 @@ const ACTIONS = {
     let blocks = json(row?.blocked_by, []) ?? [];
     if (add) {
       const id = String(add);
-      if (id === ctx.id) throw new Error('a card cannot block itself');
+      if (id === ctx.id) throw requestDetail('a card cannot block itself');
       const kind = id.startsWith('m-') ? 'message' : 'card';
-      if (kind === 'card' && !one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', id)) throw new Error(`no blocking card ${id}`);
+      if (kind === 'card' && !one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', id)) throw requestDetail(`no blocking card ${id}`);
       if (kind === 'card') {
         const seen = new Set(); const pending = [id];
         while (pending.length) {
           const node = pending.pop();
-          if (node === ctx.id) throw new Error('blocking relation would create a cycle');
+          if (node === ctx.id) throw requestDetail('blocking relation would create a cycle');
           if (seen.has(node)) continue;
           seen.add(node);
           const related = json(one(ctx.db, 'SELECT blocked_by FROM supercode_cards WHERE task_id = ?', node)?.blocked_by, []) ?? [];
@@ -1044,12 +1167,12 @@ const ACTIONS = {
       if (!blocks.some((b) => b.id === id)) blocks.push({ id, kind, reason, by: actorOf(), since: now() });
     }
     if (remove) {
-      if (!String(reason ?? '').trim()) throw new Error('unblock must say what arrived');
+      if (!String(reason ?? '').trim()) throw requestDetail('unblock must say what arrived');
       let resolved = remove;
       if (remove !== '*' && remove !== 'messages') {
         const matches = blocks.filter(b => b.id === remove || (b.kind === 'message' && String(remove).startsWith('m-') &&
           (String(remove).startsWith(b.id) || b.id.startsWith(String(remove)))));
-        if (matches.length !== 1) throw new Error(matches.length ? `ambiguous dependency ${remove}; name one of ${matches.map(b => b.id).join(', ')}` : `no dependency ${remove}; current blockers: ${blocks.map(b => b.id).join(', ') || 'none'}`);
+        if (matches.length !== 1) throw requestDetail(matches.length ? `ambiguous dependency ${remove}; name one of ${matches.map(b => b.id).join(', ')}` : `no dependency ${remove}; current blockers: ${blocks.map(b => b.id).join(', ') || 'none'}`);
         resolved = matches[0].id;
       }
       blocks = blocks.filter((b) => resolved === 'messages' ? b.kind !== 'message' : resolved !== '*' && b.id !== resolved);
@@ -1059,14 +1182,27 @@ const ACTIONS = {
     run(ctx.db, 'DELETE FROM task_links WHERE child_id = ?', ctx.id);
     for (const block of blocks.filter((b) => b.kind === 'card')) run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', block.id, ctx.id);
   },
-  flag(ctx, { name, value, reason = null }) {
-    if (!['paused', 'archived'].includes(name)) throw new Error(`unknown flag ${name}`);
+  flag(ctx, { name, value, reason = null, until = null }) {
+    if (!['paused', 'backlog', 'archived'].includes(name)) throw requestDetail(`unknown flag ${name}`);
     if (name === 'paused') {
       const was = json(one(ctx.db, 'SELECT paused FROM supercode_cards WHERE task_id = ?', ctx.id)?.paused, null);
       const clearBy = ctx.entry.workflow.flags?.paused?.clear_by ?? ['pauser', 'owner'];
-      if (!value && was && !clearBy.some((role) => role === 'pauser' ? was.by === actorOf() : ctx.scope.sender?.includes(role))) throw new Error(`only ${clearBy.join(' or ')} may resume this card; ask the manager with your reason`);
-      if (value && !String(reason ?? '').trim()) throw new Error('pause needs a reason');
-      cardField(ctx, name, value ? JSON.stringify({ by: actorOf(), reason }) : null);
+      const expiry = dueFlagExpiry({ paused: was }, ctx.scope.verb, ctx.scope.sender ?? [], ctx.scope.event ?? {}, ctx.entry.workflow.flags?.paused?.expires);
+      if (!value && was && !expiry && !clearBy.some((role) => role === 'pauser' ? was.by === actorOf() : ctx.scope.sender?.includes(role))) throw ownerRule(`only ${clearBy.join(' or ')} may resume this card; ask the manager with your reason`);
+      if (value && !ctx.scope.sender?.includes('manager')) throw ownerRule('only the manager pauses a card');
+      if (value && (typeof reason !== 'string' || !reason.trim())) throw requestDetail('pause needs a reason');
+      if (value) assertRestingWrite(name, { until: until ?? ctx.scope.event?.until }, was);
+      cardField(ctx, name, value ? JSON.stringify(RESTING_WRITE_MODE === 'legacy-holds' ? { by: actorOf(), reason }
+        : { by: actorOf(), reason, until: deadlineUntil(until ?? ctx.scope.event?.until, now(), 'pause'), generation: randomBytes(16).toString('hex') }) : null);
+    } else if (name === 'backlog') {
+      if (value && !String(reason ?? '').trim()) throw requestDetail('backlog needs a reason');
+      if (value) assertRestingWrite(name, {});
+      const backlog = value ? { by: actorOf(), reason, since: now() } : null;
+      if (value) assertBacklogQualified(ctx.db, ctx.id, { backlog });
+      cardField(ctx, name, backlog ? JSON.stringify(backlog) : null);
+      if (value && ctx.scope.before.paused) ctx.effects.push(...fire(ctx.db, ctx.board, ctx.entry, ctx.id, 'resume', {
+        roles: ['manager'], payload: { reason: 'manager migration from parked pause to backlog' },
+      }).effects);
     } else cardField(ctx, name, Number(Boolean(value)));
   },
   every(ctx, interval) {
@@ -1105,15 +1241,15 @@ const ACTIONS = {
   },
   assign(ctx, { field, value }) {
     if (field === 'reviewer') {
-      if (value != null && (typeof value !== 'string' || !ctx.entry.profiles?.[value]?.worker?.harness)) throw new Error('A card reviewer names a runnable profile in this home.');
+      if (value != null && (typeof value !== 'string' || !ctx.entry.profiles?.[value]?.worker?.harness)) throw requestDetail('A card reviewer names a runnable profile in this home.');
       record(ctx.db, ctx.id, 'reviewer_set', { reviewer: value ?? null }, ctx.runId);
       return;
     }
     if (field === 'machine') {
       const task = one(ctx.db, 'SELECT t.current_run_id,t.workspace_kind,c.workspace_anchor,c.machine FROM tasks t JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?', ctx.id);
-      if (task.current_run_id) throw new Error('End the current run before moving its card.');
+      if (task.current_run_id) throw requestDetail('End the current run before moving its card.');
       if ((value ?? null) === task.machine) return;
-      if (task.workspace_kind !== 'scratch' && (!task.workspace_anchor || isWorkspacePath(task.workspace_anchor))) throw new Error('declare the repository and branch with workflow specify --workspace before moving a legacy path card');
+      if (task.workspace_kind !== 'scratch' && (!task.workspace_anchor || isWorkspacePath(task.workspace_anchor))) throw requestDetail('declare the repository and branch with workflow specify --workspace before moving a legacy path card');
       ACTIONS.forget_session(ctx, '*');
       // a worktree the card made with only its path recorded (workspace.mjs unrecordedMaking) is recorded as made before
       // the move clears the path, so the branch it made stays its own on the new machine
@@ -1124,7 +1260,7 @@ const ACTIONS = {
       cardField(ctx, 'machine', value ?? null);
       return;
     }
-    if (!ASSIGNABLE.has(field)) throw new Error(`the workflow assigns ${field}, which is not a card field it may set`);
+    if (!ASSIGNABLE.has(field)) throw requestDetail(`the workflow assigns ${field}, which is not a card field it may set`);
     if (field === 'assignee') {
       // A model override names a model of the harness it was chosen for; a lane of another harness cannot run it
       // (a Claude model left on a Codex lane fails every turn), so it goes with the old lane, on the record
@@ -1169,6 +1305,8 @@ const ACTIONS = {
       // the card's own coder bound as its reviewer leaves the reviewer slot unclosed (handBackCoder), here or earlier in
       // this move (its close_session); the run being ended is the one it was handed back from
       const handed = handBackCoder(ctx.db, ctx.id, runId) || handedBackFrom(json(one(ctx.db, 'SELECT metadata FROM task_runs WHERE id = ?', runId)?.metadata, {})?.supercode, runId);
+      // the arc's reviewer keeps its session while a review is pending: the next review is its next round's brief
+      if (close_session && reviewerKept(ctx, runId)) close_session = false;
       if (!handed) runSession(ctx, session => ({ ...session, retain_after_run: !close_session }));
       // A declared completion may end the attempt while retaining its role session. In particular, its own caller
       // must be able to finish and return before the board starts the independent review.
@@ -1186,13 +1324,14 @@ const ACTIONS = {
     run(ctx.db, 'UPDATE tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?', ctx.id);
   },
   claim(ctx, role, scope) {
-    if (detachedCard(ctx.db, ctx.id)) throw new Error('a detached card must receive a verified adoption before starting another run');
+    if (detachedCard(ctx.db, ctx.id)) throw requestDetail('a detached card must receive a verified adoption before starting another run');
     const task = cardOf(ctx.db, ctx.id);
+    if (task.backlog) throw requestDetail('a backlog card cannot claim a run; the manager must plan it first');
     const t = now();
     const ttl = Number(ctx.entry.params.claim_ttl_seconds) || 900;
-    if (ctx.entry.workflow.run && (task.subtask_of || scope.card.paused || scope.card.archived || scope.card.blocked_by.length)) throw new Error('this card cannot run while blocked, paused, archived, or a subtask');
+    if (ctx.entry.workflow.run && (task.subtask_of || scope.card.paused || scope.card.archived || scope.card.blocked_by.length)) throw requestDetail('this card cannot run while blocked, paused, archived, or a subtask');
     const lock = ctx.scope.event?.lock;
-    if (!lock) throw new Error('a claim needs the dispatcher\'s lock');
+    if (!lock) throw requestDetail('a claim needs the dispatcher\'s lock');
     if (task.current_run_id) {
       run(ctx.db, "UPDATE task_runs SET status = 'reclaimed', outcome = 'reclaimed', summary = COALESCE(summary, 'invariant recovery on re-claim'), ended_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ? AND ended_at IS NULL", t, task.current_run_id);
     }
@@ -1227,7 +1366,7 @@ const ACTIONS = {
       given ? JSON.stringify({ ...was, ...given, ...(was.supercode ? { supercode: was.supercode } : {}) }) : (Object.keys(was).length ? JSON.stringify(was) : null), ctx.runId);
   },
   link(ctx, parent) {
-    if (!one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', parent)) throw new Error(`${parent} is no card on this board`);
+    if (!one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', parent)) throw requestDetail(`${parent} is no card on this board`);
     run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', parent, ctx.id);
   },
   unlink(ctx, parent) {
@@ -1236,13 +1375,14 @@ const ACTIONS = {
   specify(ctx, said) {
     if (said?.workspace) {
       const task = cardOf(ctx.db, ctx.id), ws = said.workspace;
-      if (task.current_run_id) throw new Error('end the current run before changing its workspace');
-      const moves = Object.hasOwn(ws, 'machine');
-      // A retarget lets go of the card's sessions, but never of the arc's own coder while it is open (openCoder): its
-      // next run, a review's return included, is delivered into that session, never a fresh one started beside it
-      // (VO-3755 t_c2d5d21b: a retarget forgot adopted coder c46c2896 at 06:51:01Z on 2026-10-27, and the run after its
-      // review's changes_requested, 2736, launched ee91b4d8 beside it). A move to another machine lets it go.
-      forgetSessions(ctx, '*', null, moves ? null : openCoder(ctx.db, ctx.id));
+      if (task.current_run_id) throw requestDetail('end the current run before changing its workspace');
+      const moves = Object.hasOwn(ws, 'machine') && (ws.machine ?? null) !== (task.machine ?? null);
+      // A same-machine retarget changes work, not conversation identity. Only an actual admitted machine move
+      // authorizes replacement; stopped coder and reviewer conversations are retained too (ADR 0248).
+      if (moves) {
+        if (ws.kind !== 'scratch' && (!ws.repository || isWorkspacePath(ws.repository))) throw requestDetail('a machine move requires a portable repository declaration');
+        forgetSessions(ctx, '*', null);
+      }
       const prior = one(ctx.db, 'SELECT workspace_anchor FROM supercode_cards WHERE task_id=?', ctx.id);
       record(ctx.db, ctx.id, 'workspace_changed', { from: { kind: task.workspace_kind, repository: prior?.workspace_anchor, branch: task.branch_name, ...(moves ? { machine: task.machine } : {}) }, to: { kind: ws.kind, repository: ws.repository, branch: ws.branch, ...(moves ? { machine: ws.machine } : {}) } }, null);
       run(ctx.db, 'UPDATE tasks SET workspace_kind=?,workspace_path=?,branch_name=? WHERE id=?', ws.kind, ws.path ?? null, ws.branch ?? null, ctx.id);
@@ -1293,7 +1433,7 @@ const ACTIONS = {
   comment(ctx, body) {
     run(ctx.db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', ctx.id, 'dispatcher', String(body), now());
   },
-  cleanup_workspace(ctx) { ctx.effects.push({ kind: 'cleanup_workspace', id: ctx.id }); },
+  cleanup_workspace(ctx) { queueCleanup(ctx.db, ctx.id, { scratch: true }); },
   stop_run(ctx) { ctx.effects.push({ kind: 'stop_run', id: ctx.id, runId: ctx.runId }); },
   // A review's pass is the work locked in: the dispatcher merges every PR the verdict judged, at the head it judged
   // (dispatch.mjs mergeReviewed), and sends the card `reviewed_merged` once all are, or `merge_refused` when a head moved.
@@ -1306,6 +1446,7 @@ const ACTIONS = {
   // the run leaving the status is the one whose session closes, never a run started after it (a reclaim's successor)
   close_session(ctx, slot) {
     const through = ctx.runId ?? one(ctx.db, 'SELECT MAX(id) AS id FROM task_runs WHERE task_id = ?', ctx.id)?.id ?? 0;
+    if (slot === 'reviewer' && reviewerKept(ctx)) return;
     requestSessionClose(ctx.db, ctx.id, { slot, through });
     ctx.effects.push({ kind: 'close_session', id: ctx.id, slot, runId: through });
   },
@@ -1332,7 +1473,7 @@ const ACTIONS = {
   // a question from the board to a session, sent under a message id chosen now: `{{asked}}` in the actions after it is
   // that id (what a block waits on), and the answer to it lands in the board's mailbox
   ask(ctx, { to, text }) {
-    if (!to) throw new Error(`the workflow asks nobody about ${ctx.id} (ask.to is empty)`);
+    if (!to) throw requestDetail(`the workflow asks nobody about ${ctx.id} (ask.to is empty)`);
     const id = `m-${randomBytes(12).toString('hex')}`;
     ctx.scope.asked = id;
     const batch = ctx.scope.verb === 'request_state' ? {
@@ -1395,13 +1536,40 @@ export function addDependency(db, entry, id, parent) {
 }
 
 /** Persist close intent in the same transaction as the transition; I/O can fail or never run. */
+/** The verdicts that keep the arc's reviewer: its own changes requested, pass or complete (ADR 0019). */
+const VERDICT_VERBS = new Set(['request_changes', 'request_state', 'complete']);
+/** Whether the arc's reviewer keeps its session as its run ends (`runId`, else its reviewer slot): only its own verdict,
+ *  while a review is pending, so the next one is delivered to that same session as its round's brief (ADR 0019).
+ *  Every other end of its run closes it. */
+function reviewerKept(ctx, runId = null) {
+  if (!VERDICT_VERBS.has(ctx.scope?.verb) || !ctx.scope?.sender?.includes('reviewer')) return false;
+  if (runId != null) {
+    const session = json(one(ctx.db, 'SELECT metadata FROM task_runs WHERE id = ?', runId)?.metadata, {})?.supercode;
+    if (session?.role !== 'reviewer' && session?.slot !== 'reviewer') return false;
+  }
+  return pendingReviewRequests(ctx.db, ctx.id).length > 0;
+}
+
+/** Close the arc's kept reviewer (ADR 0019): the latest reviewer-slot run whose session its verdict kept open. */
+export function closeKeptReviewer(db, id, effects = null) {
+  for (const row of all(db, 'SELECT id, metadata FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL ORDER BY id DESC', id)) {
+    const session = json(row.metadata, {})?.supercode;
+    if ((session?.slot ?? 'worker') !== 'reviewer') continue;
+    if (session.retain_after_run && !session.close_requested && !session.close_confirmed_at && !session.forgotten && !session.close_transferred_to) {
+      requestSessionClose(db, id, { runId: row.id });
+      effects?.push({ kind: 'close_session', id, slot: 'reviewer', runId: row.id });
+    }
+    return;
+  }
+}
+
 export function requestSessionClose(db, id, { runId = null, slot = null, through = null } = {}) {
   for (const row of all(db, 'SELECT id, metadata FROM task_runs WHERE task_id = ?', id)) {
     if ((runId != null && row.id !== runId) || (through != null && row.id > through)) continue;
     const whole = json(row.metadata, {}) ?? {};
     const session = whole.supercode;
     if (detachedSession(db, session)) continue;
-    if ((!session?.pane && !session?.launch_key && !(session?.surface === 'native' && session.session_id)) || session.close_transferred_to || session.close_confirmed_at || (slot != null && (session.slot ?? 'worker') !== slot)) continue;
+    if ((!session?.pane && !session?.launch_key && !(session?.surface === 'native' && session.session_id) && !(session?.surface === 'headless' && session.pid)) || session.close_transferred_to || session.close_confirmed_at || (slot != null && (session.slot ?? 'worker') !== slot)) continue;
     // A reviewer binding of the card's own coder is never the review's to close (handBackCoder)
     if ((session.slot ?? 'worker') === 'reviewer' && handBackCoder(db, id, row.id)) continue;
     if (session.close_requested && !session.closed_at) continue;
@@ -1413,15 +1581,38 @@ export function requestSessionClose(db, id, { runId = null, slot = null, through
 
 /**
  * Let go of card `ctx.id`'s sessions in slot `name` ('*': every slot), those of another harness than `harness` when it is
- * given: each is asked to close and is never continued; the slot's next run starts a new session. `keep` names a worker
- * session that stays the arc's (openCoder): it is neither closed nor forgotten, so its next run is delivered into it.
+ * given. Only the retained deliberate configuration/replacement decision permits its successor to launch.
  */
-function forgetSessions(ctx, name, harness, keep = null) {
+function forgetSessions(ctx, name, harness) {
+  const verb = ctx.scope.verb, said = ctx.scope.event ?? {};
+  const manager = ctx.scope.sender?.some(role => ['manager', 'owner'].includes(role));
+  const machineChange = verb === 'set' && said.field === 'machine' && (said.value ?? null) !== (ctx.scope.before.machine ?? null);
+  const workspaceMove = verb === 'specify' && Object.hasOwn(said.workspace ?? {}, 'machine')
+    && (said.workspace.machine ?? null) !== (ctx.scope.before.machine ?? null);
+  const harnessChange = verb === 'set' && said.field === 'assignee' && harness
+    && ctx.entry.profiles?.[ctx.scope.before.assignee]?.worker?.harness !== harness;
+  const replacement = verb === 'replace_session';
+  if (!machineChange && !workspaceMove && !harnessChange && !replacement) return;
+  if (!manager) throw new Error('only a deliberate manager or owner decision may replace an established role conversation');
+  const targetMachine = workspaceMove ? said.workspace.machine : machineChange ? said.value : ctx.scope.before.machine;
+  // A replacement's successor runs on the profile the card now assigns (in review, its reviewer), never the old session's
+  // harness: a slot whose profile moved to another harness could otherwise never be authorized.
+  const assigned = replacement ? ctx.entry.profiles?.[ctx.scope.before.assignee]?.worker?.harness : null;
+  ctx.replacementSource ??= { id: randomBytes(16).toString('hex'), kind: verb, field: said.field ?? null,
+    value: said.value ?? null, ...(workspaceMove ? { workspace: said.workspace } : {}) };
+  ctx.replacementSlots ??= new Map();
   for (const row of all(ctx.db, 'SELECT id, metadata FROM task_runs WHERE task_id = ? AND metadata IS NOT NULL ORDER BY id DESC', ctx.id)) {
     const whole = json(row.metadata, {}) ?? {};
     const session = whole.supercode;
-    if ((!session?.session_id && !session?.pane && !session?.launch_key) || (name !== '*' && (session.slot ?? 'worker') !== name) || (harness && (session.harness ?? 'claude-code') === harness)) continue;
-    if (keep && session.session_id === keep && (session.slot ?? 'worker') === 'worker') continue;
+    if ((!session?.session_id && !session?.pane && !session?.launch_key && !session?.pid) || (name !== '*' && (session.slot ?? 'worker') !== name) || (harness && (session.harness ?? 'claude-code') === harness)) continue;
+    const slot = session.slot ?? 'worker';
+    // An agent that ended here is never named as the successor: the decision names
+    // no agent, and the role's next generation is minted at launch (ADR 0248: an ended identity is not revived).
+    const ended = session.agent_id && session.agent_org && endedHere(ctx.board.root, session.agent_org, session.agent_id);
+    if (!ctx.replacementSlots.has(slot)) ctx.replacementSlots.set(slot, authorizeReplacement(ctx.db, ctx.id, slot, {
+      source: ctx.replacementSource, reason: said.reason ?? `deliberate ${verb}`,
+      target: { harness: harness ?? assigned ?? session.harness ?? 'claude-code', machine: targetMachine ?? null, agent: ended ? null : session.agent_id ?? null },
+    }));
     requestSessionClose(ctx.db, ctx.id, { runId: row.id });
     const latest = json(one(ctx.db, 'SELECT metadata FROM task_runs WHERE id=?', row.id)?.metadata, {}) ?? {};
     // a reviewer binding the close handed back to its coder's slot is the coder's, and is not forgotten with the review
@@ -1551,7 +1742,12 @@ export function runEvent(db, id, kind, payload) {
 export function fireRun(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
   const task = cardOf(db, id);
   const row = task.current_run_id && one(db, 'SELECT * FROM task_runs WHERE id = ?', task.current_run_id);
-  if (!row) throw new Error(`${id} has no current run for ${name}`);
+  if (!row && name === 'heartbeat') {
+    record(db, id, 'heartbeat', payload, null);
+    const status = statusOf(db, task);
+    return { from: status, to: status, moved: false, effects: [] };
+  }
+  if (!row) throw requestDetail(`${id} has no current run for ${name}`);
   const machine = entry.workflow.run;
   const meta = json(row.metadata, {}) ?? {};
   const from = meta.supercode?.state ?? machine.initial;
@@ -1559,7 +1755,7 @@ export function fireRun(db, board, entry, id, name, { roles = [], payload = {},
   const candidates = [...(machine.states[from]?.on?.[name] ?? []), ...(machine.on?.[name] ?? [])];
   const t = candidates.find((t) => (!t.from?.length || t.from.includes(from)) && (!t.by?.length || t.by.some((r) => roles.includes(r))) && holds(t.guard ?? null, scope));
   if (!t) { const error = new Error(`${id}: run event ${name} does not apply`); error.noTransition = true; throw error; }
-  for (const v of t.validate ?? []) if (!holds(v.expr, scope)) throw new Error(render(v.message, scope));
+  for (const v of t.validate ?? []) if (!holds(v.expr, scope)) throw requestDetail(render(v.message, scope));
   const to = t.target ? String(templateValue(t.target, scope)) : from;
   if (!machine.states[to]) throw new Error(`unknown run state ${to}`);
   const effects = [];
@@ -1624,10 +1820,16 @@ function settleRelations(db, board, entry, id, effects) {
 export function storedStatus(db, board, entry, id) {
   const task = cardOf(db, id);
   const status = statusOf(db, task);
+  // An ended card stores its end: a hold left on it (a block, a pause, a backlog) never outranks done or cancelled.
+  const ended = ['done', 'archived', 'cancelled'].includes(storedAs(entry.workflow, status));
+  if (task.backlog && !task.archived && !ended) {
+    assertBacklogQualified(db, id, { backlog: task.backlog });
+    return { status, stored: 'todo' };
+  }
   // Native holds are stored honestly. Hermes lowering is an export concern;
   // older homes may still declare a lossy paused -> blocked storage rule.
   const nativeHolds = Boolean(entry.workflow.flags?.paused);
-  if (nativeHolds && !task.archived) {
+  if (nativeHolds && !task.archived && !ended) {
     if (task.paused) return { status, stored: 'paused' };
     if (task.blocked_by.length) return { status, stored: 'blocked' };
   }
@@ -1639,7 +1841,7 @@ export function storedStatus(db, board, entry, id) {
 }
 
 export function projectStatus(db, board, entry, id) {
-  if (!entry.workflow.stored_as?.length && !entry.workflow.flags?.paused) return;
+  if (!entry.workflow.stored_as?.length && !entry.workflow.flags?.paused && !entry.workflow.flags?.backlog) return;
   const { status, stored } = storedStatus(db, board, entry, id);
   // Only a change is written: an unchanged write still commits, and a commit wakes the dispatcher that called this.
   run(db, 'UPDATE tasks SET status = ? WHERE id = ? AND status IS NOT ?', stored, id, stored);