@volter/supercode-orchestrator 0.5.228 → 0.5.229

package/board/ci.mjs

@@ -1,13 +1,15 @@
 // Review candidates are observed before a board mutation. No network or Git
 // process runs inside the optimistic transaction. Deployment is not a completion gate.
-import { execFile } from 'node:child_process';
+import { runtimeDoor } from './runtime-door.mjs';
+import { execFile, spawn } from 'node:child_process';
 import { readFileSync, realpathSync, writeFileSync, renameSync, statSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { isDeepStrictEqual } from 'node:util';
 import { branchCheckouts, checkoutOf, isLocalWorkspace, isWorkspacePath, resolveWorkspace, plainWorkspace, workspaceTask } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
-import { githubFetch, githubDiscovery, githubDiscoveryHeld, githubDiscoveryUsed, GITHUB_DISCOVERY_ATTEMPTS } from './github-rest.mjs';
+import { githubFetch, githubDiscovery, githubDiscoveryHeld, githubDiscoveryObservedAt, githubDiscoveryUsed, githubSourceFact, GITHUB_DISCOVERY_ATTEMPTS } from './github-rest.mjs';
 
 // GitHub is read through its REST API with Node's own fetch, in this process and awaited (never a child the caller
 // waits on synchronously): Node takes a World's trust bundle and injector (NODE_EXTRA_CA_CERTS, NODE_OPTIONS), so a
@@ -127,12 +129,20 @@ const actionReads = new AsyncLocalStorage();
 /** Fresh observations belong to one action only; callers and later actions never share this snapshot. */
 export const withFreshReviewReads = (fn) => actionReads.getStore() ? fn() : actionReads.run(new Map(), fn);
 async function github(path, all = false, { purpose = 'validation' } = {}) {
-  const reads = purpose === 'validation' && actionReads.getStore();
+  const reads = actionReads.getStore();
   if (!reads) return githubUncached(path, all, { purpose });
   const key = `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${all}\0${path}`;
   if (!reads.has(key)) reads.set(key, githubUncached(path, all, { purpose }));
   return reads.get(key);
 }
+// Retain the provider's observation clock beside the returned object. Durable history
+// watermarks must share GitHub updated_at's clock, including when this action coalesces a read.
+const githubObservationTimes = new WeakMap();
+function historyObservedAt(list) {
+  const at = githubObservationTimes.get(list);
+  if (!Number.isFinite(at)) throw new Error('GitHub history has no provider Date observation; its completeness is unknown');
+  return at;
+}
 async function wireRead(fn) {
   const release = await admitGithubRead();
   try { return await fn(); } finally { release(); }
@@ -146,7 +156,7 @@ async function githubUncached(path, all = false, { purpose = 'validation' } = {}
       const context = admitGithubContext(rateKey);
       if (!context) return { code: 'github_read_admission_full', error: 'eight GitHub origin/credential contexts are active; not requested' };
       try {
-        let url = base + path, out = [];
+        let url = base + path, out = [], observedAt = Infinity;
         for (let page = 0; url && page < 10; page += 1) {
           // No await separates admission from fetch. Every page observes a
           // refusal retained while an earlier page or another read was in flight.
@@ -162,15 +172,17 @@ async function githubUncached(path, all = false, { purpose = 'validation' } = {}
           }
           // An older in-flight success is not recovery from a newer refusal.
           if (context.rateLimit && Date.now() >= context.rateLimit.until) context.rateLimit = null;
-          return { body: await r.json(), next: /<([^>]+)>;\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null };
+          return { observedAt: Date.parse(r.headers.get('date')), body: await r.json(), next: /<([^>]+)>;\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null };
           });
           if (pageRead.result) return pageRead.result;
           const body = pageRead.body;
-          if (!all) return { body };
+          observedAt = Math.min(observedAt, pageRead.observedAt);
+          if (!all) return { body, observedAt };
           out = out.concat(body);
           url = pageRead.next;
         }
-        return { body: out };
+        if (url) throw new Error('GitHub list exceeds ten pages; source set remains unknown');
+        return { body: out, observedAt };
       } finally {
         context.readers -= 1;
         if (!context.readers && !context.rateLimit) githubReadContexts.delete(rateKey);
@@ -188,16 +200,17 @@ async function githubUncached(path, all = false, { purpose = 'validation' } = {}
       throw Object.assign(new Error(`GitHub: ${result.error.trim().slice(-500)}${nativeCode ? ` (${nativeCode})` : ''}`, { cause: result.cause }), result.rateLimit
         ? { code: 'github_rate_limited', status: result.status, retry_at: result.rateLimit.retryAt, deferred: true }
         : result.code ? { code: result.code, deferred: result.code === 'github_read_admission_full' }
-        : result.cause?.code ? { code: result.cause.code, deferred: result.cause.code === 'GITHUB_BUDGET' }
+        : result.cause?.code ? { code: result.cause.code, deferred: Boolean(result.cause.deferred), retry_at: result.cause.retry_at }
         : result.status ? { status: result.status } : {});
     }
+    if (result.body && typeof result.body === 'object') githubObservationTimes.set(result.body, result.observedAt);
     return result.body;
 }
 const repositoryOf = (url) => new URL(url).pathname.split('/').slice(1, 3).join('/');
 const numberOf = (url) => Number(new URL(url).pathname.split('/')[4]);
 /** A PR as the board reads it (gh's field names). */
 const pullRequest = (repository, p) => ({ url: p.html_url, number: p.number, state: p.merged_at ? 'MERGED' : String(p.state).toUpperCase(), headRefOid: p.head.sha,
-  headRefName: p.head.ref, baseRefName: p.base.ref, defaultBranch: p.base.repo?.default_branch ?? null, isCrossRepository: p.head.repo?.full_name?.toLowerCase() !== repository.toLowerCase(), isDraft: Boolean(p.draft) });
+  headRefName: p.head.ref, baseRefName: p.base.ref, defaultBranch: p.base.repo?.default_branch ?? null, isCrossRepository: p.head.repo?.full_name?.toLowerCase() !== repository.toLowerCase(), isDraft: Boolean(p.draft), updatedAt: p.updated_at });
 const discoveryIdentity = async key => `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${key}`;
 const discoveryRead = async (key, ttl, read, options) => githubDiscovery(await discoveryIdentity(key), ttl, read, options);
 const readPullRequest = async (url) => discoverPullRequest(url, { fresh: true });
@@ -212,13 +225,44 @@ const MERGED_TTL = 7 * 86400_000, CLOSED_TTL = 6 * 3600_000;
 /** A long retention lengthened by up to a quarter, fixed for each key: entries one scan filled together (a cold strict
  *  scan reads an arc's every declared PR and earlier branch at once) end over that quarter, not in the same round. */
 const spread = (ttl, key) => ttl + Number.parseInt(createHash('sha256').update(key).digest('hex').slice(0, 8), 16) % Math.floor(ttl / 4);
+const sourceFact = async (key, value) => githubSourceFact(await discoveryIdentity(key), value);
+const mergedFact = async (url, value) => {
+  const key = `merged:${pullRequestKey(url)}`;
+  const held = await sourceFact(key);
+  if (value?.state === 'MERGED') {
+    if (held && held.headRefOid !== value.headRefOid) throw new Error(`Inconsistent merged head for ${url}; source remains unknown`);
+    return sourceFact(key, value);
+  }
+  return held;
+};
 export async function discoverPullRequest(url, { fresh = false } = {}) {
+  const immutable = await mergedFact(url);
+  if (immutable) return immutable;
   const key = pullRequestKey(url);
-  return discoveryRead(key, 60_000, async () => pullRequest(repositoryOf(url),
+  const pr = await discoveryRead(key, 60_000, async () => pullRequest(repositoryOf(url),
     await github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`, false, { purpose: fresh ? 'validation' : 'discovery' })),
   { fresh, ttlOf: pr => pr.state === 'MERGED' ? spread(MERGED_TTL, key) : pr.state === 'CLOSED' ? spread(CLOSED_TTL, key) : 60_000 });
+  if (pr.state === 'MERGED') await mergedFact(url, pr);
+  return pr;
 }
 
+/** The repository list precedes retained closed observations, so a reopened PR
+ *  is visible without polling every queued PR through fresh validation. */
+export async function discoverQueuedPullRequest(url) {
+  const immutable = await mergedFact(url);
+  if (immutable) return immutable;
+  const list = await openPullRequests(repositoryOf(url));
+  return list.find(pr => pr.number === numberOf(url)) ?? discoverPullRequest(url);
+}
+/** When the shared open-PR list of `url`'s repository was last read (ms), or 0: what a queued request whose
+ *  admission failed for no reason of its own waits to see move (ADR 0252). */
+export async function openListObservedAt(url) {
+  return githubDiscoveryObservedAt(await discoveryIdentity(`open:${repositoryOf(url).toLowerCase()}`));
+}
+// Every discovery caller shares this complete, paged five-minute list.
+const openPullRequests = (repository, { fresh = false } = {}) => discoveryRead(`open:${repository.toLowerCase()}`, 300_000, async () =>
+  (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' })).map(p => pullRequest(repository, p)), { fresh });
+
 /**
  * Merge a reviewed PR at the head its review judged, and only there: GitHub refuses the merge when the PR's head is no
  * longer that commit (409), so a head pushed after the verdict is never merged unreviewed. Answers
@@ -296,6 +340,27 @@ export function withCompletionEvidence(board, id, state, fn) {
   }
 }
 
+/** Unsettled requests in FIFO order. Explicit replacements inherit the named request's slot; a settlement can
+ *  give an already queued replacement that slot without rewriting either immutable request. */
+export function pendingReviewRequests(db, id) {
+  return db.prepare(`SELECT q.id,q.payload,
+    MIN(COALESCE(json_extract(CASE WHEN json_valid(q.payload) THEN q.payload END,'$.queue_order'),q.id),
+      COALESCE((SELECT MIN(json_extract(CASE WHEN json_valid(s.payload) THEN s.payload END,'$.queue_order'))
+        FROM task_events s WHERE s.task_id=q.task_id AND s.kind='review_queue_settled'
+        AND json_extract(CASE WHEN json_valid(s.payload) THEN s.payload END,'$.replacement_event')=q.id),q.id)) AS queue_order
+    FROM task_events q WHERE q.task_id=? AND q.kind='review_queued'
+    AND NOT EXISTS (SELECT 1 FROM task_events settled WHERE settled.task_id=q.task_id
+      AND settled.kind IN ('review_queue_started','review_queue_settled')
+      AND json_extract(CASE WHEN json_valid(settled.payload) THEN settled.payload END,'$.queued_event')=q.id)
+    ORDER BY queue_order,q.id`).all(id).map(row => ({ ...JSON.parse(row.payload ?? '{}'), id: row.id, queue_order: row.queue_order }));
+}
+
+/** The oldest retained review request not yet applied. The existing card event stream is its queue. */
+export const pendingReviewRequest = (db, id) => pendingReviewRequests(db, id)[0] ?? null;
+
+/** A PR's identity across spellings of its URL (a trailing slash, letter case). */
+export const prIdentity = url => String(url).replace(/\/$/, '').toLowerCase();
+
 /** The latest explicitly requested PRs are the reviewer's candidate, never the deployment tip. */
 export function reviewCandidate(board, id) {
   const row = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='review_requested' ORDER BY id DESC LIMIT 1").get(id);
@@ -303,6 +368,48 @@ export function reviewCandidate(board, id) {
   return payload?.ci?.pr || payload?.ci?.no_code || payload?.ci?.pr_reviewed?.length ? payload.ci : null;
 }
 
+/** A source declaration, as SQL over its `commented` event row `c`: `comment --pr` or `--pr none` (`sources`), and
+ *  `--source` or `--source none` (`branches`). A PR disposition or release readback comment carries its one `--pr` too
+ *  (engine.comment) but declares nothing: it is the comment whose evidence event (`pr_disposition_recorded`,
+ *  `pr_release_readback`) is recorded after it in the same write, before the card's next comment. */
+const declaringSql = (c) => `${c}.kind='commented' AND json_valid(${c}.payload) AND (json_type(${c}.payload,'$.branches')='array'
+  OR (json_type(${c}.payload,'$.sources')='array' AND NOT EXISTS (SELECT 1 FROM task_events k WHERE k.task_id=${c}.task_id
+    AND k.kind IN ('pr_disposition_recorded','pr_release_readback') AND k.id>${c}.id
+    AND k.id<COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id=${c}.task_id AND n.kind='commented' AND n.id>${c}.id), 9223372036854775807))))`;
+
+/** The first source declaration (declaringSql) the arc made after event `sinceId` (every declaration when there is none),
+ *  or null. A review request's frozen candidate no longer states the arc's declared set once one follows it, so the next
+ *  review is built from the declarations (VO-3775 t_1daf732e: its PRs #2596 and #2606 moved to another card and the arc
+ *  was re-declared, and every later reviewer run stayed bound to request 121444 naming them). */
+export function redeclaredSince(db, id, sinceId) {
+  return db.prepare(`SELECT c.id FROM task_events c WHERE c.task_id=? AND c.id>? AND ${declaringSql('c')} ORDER BY c.id LIMIT 1`).get(id, sinceId ?? 0)?.id ?? null;
+}
+/** What the arc cleared after its latest review request, as a test of one of that request's PRs (`{ url, repository,
+ *  branch }`): when it cleared its PR declarations (`comment --pr none`), the PR URLs it had itself declared (`--pr`)
+ *  before that clear; when it cleared its source declarations (`comment --source none`), the PRs found on the
+ *  `--source` branches it had declared before that clear and has not declared again since. The declarations since are
+ *  the complete declared set, so those are not carried into it from that request's candidate; the other PRs the board
+ *  discovered (a merged `wt/<card>` PR in a sibling repository, which discovery can no longer list) are. */
+function clearedDeclarations(db, id) {
+  const asked = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id=? AND kind='review_requested'").get(id)?.id ?? 0;
+  const clearedAt = (field) => db.prepare(`SELECT MAX(id) AS id FROM task_events WHERE task_id=? AND id>? AND kind='commented' AND json_valid(payload)
+    AND json_type(payload,'$.${field}')='array' AND json_array_length(payload,'$.${field}')=0`).get(id, asked)?.id;
+  const before = (field, at) => db.prepare(`SELECT payload FROM task_events WHERE task_id=? AND id<? AND kind='commented' AND json_valid(payload)
+    AND json_type(payload,'$.${field}')='array'`).all(id, at).flatMap((row) => JSON.parse(row.payload)[field]);
+  const branchKey = (repository, branch) => `${repository.toLowerCase()}:${branch}`;
+  const urls = new Set(), branches = new Set();
+  const prs = clearedAt('sources');
+  if (prs) for (const source of before('sources', prs)) if (typeof source?.url === 'string') urls.add(source.url);
+  const sources = clearedAt('branches');
+  if (sources) {
+    const kept = new Set(arcSources(db, id).map((b) => branchKey(b.repository, b.branch)));
+    for (const b of before('branches', sources)) {
+      if (typeof b?.repository === 'string' && typeof b?.branch === 'string' && !kept.has(branchKey(b.repository, b.branch))) branches.add(branchKey(b.repository, b.branch));
+    }
+  }
+  return (source) => urls.has(source.url) || (typeof source.branch === 'string' && branches.has(branchKey(source.repository, source.branch)));
+}
+
 /** The PRs an evidence record covers: every PR of one arc review (the first is also its top-level PR). */
 export const candidatePullRequests = (ci) => ci?.prs ?? (ci?.pr ? [{ repository: ci.repository, branch: ci.branch, commit: ci.commit, source_sha: ci.source_sha ?? ci.commit, pr: ci.pr }] : []);
 // The repository a checkout declares (remote.origin.url), not where a URL rewrite sends its transport.
@@ -376,18 +483,52 @@ async function recreatedWorktree(workspace, resolved) {
   try { const made = await resolveWorkspace(workspace, true); return made.path === resolved.path && checkoutPresent(made.path); } catch { return false; }
 }
 
-/** Historical work can already be merged when an outage prevented the board's
- * review request. Read only the arc's declared branch, never all closed PRs. */
-async function mergedBranchPullRequests(repository, branch, { fresh = false, ttl = 900_000 } = {}) {
-  // `ttl` is how long an answer is kept; a failed read is kept only the usual fifteen minutes, never the long lifetime
-  // an earlier branch's answer gets (a cached failure is re-thrown to every round until it ends).
-  const key = `${repository.toLowerCase()}:${branch}`;
-  const read = async () => {
-    const head = encodeURIComponent(`${repository.split('/')[0]}:${branch}`);
-    return (await github(`/repos/${repository}/pulls?state=closed&head=${head}&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' }))
-      .filter(p => p.merged_at).map(p => pullRequest(repository, p));
-  };
-  return discoveryRead(`history:${key}`, 900_000, read, { fresh, ttlOf: () => ttl });
+/** Seed a branch once, then discover subsequent closed/merged work with one repository
+ * listing, sorted by update time. The durable watermark survives cache expiry/restart.
+ * Open-list discovery independently follows branch reuse, including drafts. */
+async function branchHistories(repository, branches, { fresh = false, admit }) {
+  const unique = [...new Set(branches)];
+  const snapshots = await readTogether(unique, async branch => {
+    const key = `branch-history:${repository}:${branch}`;
+    let held = await sourceFact(key);
+    if (!held) {
+      if (!await admit(`history:${repository}:${branch}`)) return null;
+      const head = encodeURIComponent(`${repository.split('/')[0]}:${branch}`);
+      const path = `/repos/${repository}/pulls?state=closed&head=${head}&per_page=100`;
+      const list = await github(path, true, { purpose: fresh ? 'validation' : 'discovery' });
+      const at = historyObservedAt(list), prs = list.filter(p => p.merged_at).map(p => pullRequest(repository, p));
+      held = { at, prs };
+      await sourceFact(key, held);
+      for (const pr of prs) await mergedFact(pr.url, pr);
+    }
+    return { key, branch, ...held };
+  });
+  const held = snapshots.filter(Boolean);
+  if (!held.length) return [];
+  const cutoff = Math.min(...held.map(h => h.at)) - 2000;
+  if (fresh || Date.now() - cutoff > 300_000) {
+    let began = Infinity;
+    const updates = [];
+    let complete = false;
+    for (let page = 1; page <= 10; page++) {
+      const path = `/repos/${repository}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`;
+      const list = await github(path, false,
+        { purpose: fresh ? 'validation' : 'discovery' });
+      began = Math.min(began, historyObservedAt(list));
+      if (!Array.isArray(list) || list.some(p => !Number.isFinite(Date.parse(p.updated_at)))) throw new Error(`Unreadable closed-PR history for ${repository}`);
+      updates.push(...list.filter(p => p.merged_at && Date.parse(p.updated_at) >= cutoff).map(p => pullRequest(repository, p)));
+      if (list.length < 100 || list.some(p => Date.parse(p.updated_at) < cutoff)) { complete = true; break; }
+    }
+    if (!complete) throw new Error(`Closed-PR history for ${repository} exceeds ten pages since its watermark; source set remains unknown`);
+    for (const snapshot of held) {
+      const prs = new Map(snapshot.prs.map(pr => [pr.url, pr]));
+      for (const pr of updates) if (pr.headRefName === snapshot.branch) prs.set(pr.url, pr);
+      snapshot.prs = [...prs.values()];
+      await sourceFact(snapshot.key, { at: began, prs: snapshot.prs });
+    }
+    for (const pr of updates) await mergedFact(pr.url, pr);
+  }
+  return held.flatMap(h => h.prs);
 }
 
 async function branchCheckout(board, id, repository, branch) {
@@ -438,14 +579,13 @@ function declarationsOf(db, id, field, adding = null) {
   return declarations.slice(from);
 }
 
-/** Each repository and branch the arc declared (`branches`), at its latest declaration (`at`, that declaration's id). */
+/** Stable membership identity: an equivalent declaration never changes the member's first declaration. */
 function declaredBranches(db, id, adding = null) {
   const out = [];
   for (const declaration of declarationsOf(db, id, 'branches', adding)) for (const b of declaration.items) {
     if (typeof b?.repository !== 'string' || typeof b?.branch !== 'string') continue;
     const known = out.find((r) => r.repository.toLowerCase() === b.repository.toLowerCase() && r.branch === b.branch);
-    if (known) known.at = declaration.id;
-    else out.push({ repository: b.repository, branch: b.branch, at: declaration.id });
+    if (!known) out.push({ repository: b.repository, branch: b.branch, at: declaration.id });
   }
   return out;
 }
@@ -458,20 +598,7 @@ export function arcSources(db, id, adding = null) {
   return declaredBranches(db, id, adding).map(({ repository, branch }) => ({ repository, branch }));
 }
 
-/** How long the merged history of an earlier-declared branch is kept, how many reads an advisory discovery starts for
- *  one arc that it does not already hold (declared PRs and earlier branches' histories; the rest are read on later
- *  rounds), and the share of the home's discovery budget (GITHUB_DISCOVERY_ATTEMPTS an hour, every arc's) past which it
- *  starts none: an arc's declarations add up for as long as it runs, and several arcs filling their caches at once
- *  (three at four reads a round would start 720 an hour) leave the rest of that budget to every arc's routine reads. */
-const EARLIER_BRANCH_TTL = 6 * 3600_000, NEW_READS_PER_ROUND = 4, FILL_SHARE = 0.7;
-
-/** The declared branches (`repository:branch`, the repository lower-cased) the arc's latest `--source` declaration does
- *  not name: work it declared earlier. Their merged history is read on a long cache (EARLIER_BRANCH_TTL), never skipped. */
-function earlierDeclaredBranches(db, id) {
-  const declared = declaredBranches(db, id);
-  const last = Math.max(0, ...declared.map((b) => b.at));
-  return new Set(declared.filter((b) => b.at !== last).map((b) => `${b.repository.toLowerCase()}:${b.branch}`));
-}
+const NEW_READS_PER_ROUND = 4, FILL_SHARE = 0.7;
 
 /** The PRs the arc declared (`comment --pr URL --pr-head SHA`), each at its latest declaration: every declaration since
  *  the latest `--pr none` adds to the ones before it, in any of the arc's repositories, on any run. Discovery reads each
@@ -484,6 +611,12 @@ export function declaredPullRequests(db, id) {
     latest.delete(source.url);
     latest.set(source.url, { url: source.url, head: source.head });
   }
+  for (const row of db.prepare(`SELECT payload FROM task_events WHERE task_id=? AND kind='pr_disposition_recorded' AND json_valid(payload) ORDER BY id`).all(id)) {
+    const source = JSON.parse(row.payload);
+    // Only a release-only PR is kept once closed: its release readback settles it. A closed PR left to merge can never
+    // merge, so it leaves the set as any closed declared PR does.
+    latest.set(source.url, { url: source.url, head: source.head, retained: source.disposition === 'release-only' });
+  }
   return [...latest.values()];
 }
 
@@ -528,25 +661,26 @@ export function declaredWorkBranches(db, id) {
   return [...new Set([...declared, ...reviewed].filter(Boolean))];
 }
 
-/** Every PR of the arc, open (not a draft) or merged, at its current head, each proposed to its repository's default
- *  branch, but for one merged at a head its PR review passed (`pr_reviewed`, settled): the arc's final review request
+/** Every PR of the arc, open (not a draft) or merged, at its current head, whatever its base, but for one merged at a head its PR review passed (`pr_reviewed`, settled): the arc's final review request
  *  names them all, and whether a review is due depends only on the heads no verdict judged (reviewDue). A PR review
  *  names one ready PR of them (requireCurrentReviewSet). A PR of the arc is one it declared (declaredPullRequests) or one whose head is the card's
  *  work branch in the card's own repository, a `wt/<card id>` branch in any repository this machine keeps a checkout
  *  of, or a sibling checkout the arc registered (`registeredBranches`). The repository's default branch, declared or
  *  checked out (or no branch), is not a work branch: such a card's PRs are only its `wt/<card>` and registered ones, and with none it
  *  answers `{ waits }` saying so. The final review covers them all; the caller decides the transition. */
-export async function openReviewPullRequests(board, id, { fresh = false, checkWorkspaces = false, refuseStacked = false, repositories = [] } = {}) {
-  if (!fresh) return discoverReviewSources(board, id, { checkWorkspaces, refuseStacked, repositories });
+export async function openReviewPullRequests(board, id, { fresh = false, checkWorkspaces = false, repositories = [] } = {}) {
+  if (!fresh) return discoverReviewSources(board, id, { checkWorkspaces, repositories });
   // Every authorization entry acquires the broad advisory scope, not only
   // dispatch. An older receipt and a checkout now on main still have to see
   // implicit wt/<card> PRs. Discovery failures leave that scope unknown.
-  const scope = new Set(repositories);
-  await discoverReviewSources(board, id, { repositories, strict: true }, scope);
-  return discoverReviewSources(board, id, { fresh: true, checkWorkspaces, refuseStacked, repositories: [...scope] });
+  return withFreshReviewReads(async () => {
+    const scope = new Set(repositories);
+    await discoverReviewSources(board, id, { repositories, strict: true }, scope);
+    return discoverReviewSources(board, id, { fresh: true, checkWorkspaces, repositories: [...scope] });
+  });
 }
 
-async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces = false, refuseStacked = false, repositories = [], strict = false } = {}, scope = null) {
+async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces = false, repositories = [], strict = false } = {}, scope = null) {
   const { own, registered, ownRepository, repositories: arcScope } = await arcRepositories(board, id);
   // A source declaration (an implementer's or manager's card comment, engine.comment) adds merged or moved PRs that
   // discovery cannot see; it never hides what discovery found. Its PRs are bounded by the arc's repositories (the card's
@@ -558,7 +692,27 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   // (volter-ai/volter#134 left four t_ef2aa6ce review requests with no word). A PR the review already includes is never refused.
   // Every PR the arc declared, on any run and in any repository, is one of them (declaredPullRequests), not only its latest declaration's.
   const declared = declaredPullRequests(board.db, id);
-  const undeclared = (outside) => refusalOf(outside.map(({ url, repository }) => refused('undeclared', url, `${url} is declared as a source of ${id}, but ${repository} is not one of the arc's repositories (its workspace, its declared sources, its tasks', or one holding its wt/${id} branch), so a declaration cannot name it: declare the repository on the arc: comment ${id} "<why>" --source ${repository}:<branch>, or clear the arc's PR declarations with --pr none and declare its PRs again without it.`)));
+  // A sibling source can leave the open list by merging between reviews. Keep the
+  // exact previously observed URL, including settled sources whose pass can be voided. A `--pr none` or `--source none`
+  // since that request re-declared the complete set: a PR the arc had declared, or one found on a `--source` branch it
+  // cleared, is not carried into it from the frozen candidate (VO-3775 kept PRs moved to another card); another one the
+  // board discovered is (clearedDeclarations).
+  const previous = reviewCandidate(board, id);
+  const dropped = clearedDeclarations(board.db, id);
+  const priorSources = [
+    ...candidatePullRequests(previous).map(p => ({ url: p.pr.url, head: p.commit, repository: p.repository ?? repositoryOf(p.pr.url), branch: p.branch })),
+    ...(previous?.pr_reviewed ?? []).map(p => ({ url: p.url, head: p.head, repository: repositoryOf(p.url), branch: p.branch })),
+  ].filter(source => !dropped(source));
+  // The PRs only the frozen candidate carries, not a `--pr` declaration: `--pr none` does not drop them.
+  const carried = new Map();
+  for (const source of priorSources) if (!declared.some(p => p.url === source.url)) { declared.push({ url: source.url, head: source.head }); carried.set(source.url, source); }
+  const scopeWords = `not one of the arc's repositories (its workspace, its declared sources, its tasks', or one holding its wt/${id} branch)`;
+  const undeclared = (outside) => refusalOf(outside.map(({ url, repository }) => {
+    const found = carried.get(url);
+    return refused('undeclared', url, found
+      ? `${url} is in ${id}'s last review request${found.branch ? `, found on ${repository}:${found.branch}` : ''}, but ${repository} is now ${scopeWords}, so the review cannot include it: declare the repository on the arc again: comment ${id} "<why>" --source ${repository}:${found.branch ?? '<branch>'}. To leave it out instead, declare that branch with --source and then clear the arc's source declarations with --source none, which drops the PRs the last review found on each --source branch it clears, and declare again the sources the arc keeps.`
+      : `${url} is declared as a source of ${id}, but ${repository} is ${scopeWords}, so a declaration cannot name it: declare the repository on the arc: comment ${id} "<why>" --source ${repository}:<branch>, or clear the arc's PR declarations with --pr none and declare its PRs again without it.`);
+  }));
   // A card with no repository of its own and none registered (scratch) has no discovery: every declared PR is outside.
   if (!ownRepository && !registered.length) {
     const outside = outsideArcRepositories(declared.map(source => source.url), arcScope);
@@ -573,7 +727,6 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   // Broad discovery finds wt/<card> work in sibling repositories. Authorization
   // refreshes only this arc's repositories, including siblings already found or
   // requested; an unrelated checkout is never a validation-purpose PR scan.
-  const previous = reviewCandidate(board, id);
   const requested = [...candidatePullRequests(previous).map(p => p.repository ?? repositoryOf(p.pr.url)),
     ...(previous?.review_repositories ?? [])];
   const siblings = fresh ? [] : await knownRepositories({ strict });
@@ -581,11 +734,6 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     ...repositories, ...siblings].filter(Boolean).map(r => r.toLowerCase()))];
   const reviewRepositories = new Set([ownRepository, ...registered.map(r => r.repository), ...requested, ...repositories]
     .filter(Boolean).map(r => r.toLowerCase()));
-  // A branch an earlier `--source` declaration named, and no task or the latest declaration names, keeps its merged
-  // history on a long cache: it is read, never skipped, but a lane card's weeks of branches stay a small share of the
-  // home's discovery budget. A task's branch and the latest declaration's are read as before.
-  const earlier = earlierDeclaredBranches(board.db, id);
-  if (earlier.size) for (const r of registeredBranches(board, id, [])) earlier.delete(`${r.repository.toLowerCase()}:${r.branch}`);
   // An advisory discovery starts at most NEW_READS_PER_ROUND reads it does not already hold for the arc's earlier
   // branches and declared PRs, and only one once the home has spent FILL_SHARE of its hour's discovery budget (every
   // arc's reads), so an arc still advances through a long busy stretch (issue() still refuses past the budget itself);
@@ -603,9 +751,8 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   };
   const openSeen = new Map(), openKey = (url) => `${repositoryOf(url).toLowerCase()}#${numberOf(url)}`;
   // A repository's open PRs, every page, on the five-minute list every arc reading that repository shares.
-  const openList = (repository) => discoveryRead(`open:${repository.toLowerCase()}`, 300_000, async () =>
-    (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' })).map(p => pullRequest(repository, p)), { fresh });
-  const stacked = [], workRepositories = new Set();
+  const openList = (repository) => openPullRequests(repository, { fresh });
+  const workRepositories = new Set();
   const groups = await readTogether(repositoriesToRead, async repository => {
     const prs = [];
     const hasWorkBranches = repository === ownRepository || registered.some(r => r.repository === repository);
@@ -624,7 +771,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
       if (fresh || strict || repository === ownRepository || registered.some(r => r.repository === repository)) throw error;
       return []; // An unread sibling stays unread: do not cache an empty successful result.
     }
-    // Include excluded drafts/other bases in the fresh scope: becoming ready
+    // Include excluded drafts in the fresh scope: becoming ready
     // must not let a sibling source escape the complete-set check.
     for (const pr of list.items) openSeen.set(openKey(pr.url), pr);
     if (list.items.some(pr => mine(repository, pr.headRefName))) reviewRepositories.add(repository);
@@ -634,34 +781,21 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     if (repository === ownRepository && branch) {
       if (branch === list.defaultBranch) branch = null;
     }
-    // a draft is not handed over yet: its review starts when it is marked ready; a PR to another base (main→prod) is a release, not the arc's work
-    for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.baseRefName === pr.defaultBranch && mine(repository, pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
-    // A ready PR on one of the arc's branches proposed to any branch but the default (stacked on another PR, or a wrong
-    // base) would leave the arc's one review set without a word: it is kept as stacked, and a review request refuses
-    // and tells it until it is retargeted to the default branch. A PR from the default branch itself is a release.
-    for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.defaultBranch && pr.headRefName !== pr.defaultBranch && pr.baseRefName !== pr.defaultBranch && mine(repository, pr.headRefName)) stacked.push(pr);
+    // a draft is not handed over yet: its review starts when it is marked ready; a ready PR on one of the arc's branches
+    // is the arc's work whatever its base, and is reviewed against that base; a PR from the default branch itself
+    // (main→prod) is a release, not the arc's work
+    for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.headRefName !== list.defaultBranch && mine(repository, pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
     // A manual review and merge during a dispatcher outage may predate any
     // board request. The source-review door already accepts merged heads; make
     // them discoverable so the ordinary independent verdict can be retained.
-    // An open PR (including a draft or wrong base) on that branch takes priority.
+    // An open PR (including a draft) on that branch takes priority.
     const historical = [...new Set([
       ...(repository === ownRepository ? branch ? [branch] : [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`] : []),
       ...registered.filter(r => r.repository === repository).map(r => r.branch),
     ])];
-    // A merged PR stays in the set at its merged head, judged or not: the review reads the arc's whole diff in every
-    // round, and only an unjudged head makes that review due (reviewDue).
-    const histories = await readTogether(historical, async headBranch => {
-      if (headBranch === list.defaultBranch || list.items.some(pr => pr.headRefName === headBranch)) return [];
-      const older = earlier.has(`${repository}:${headBranch}`) && !(repository === ownRepository && headBranch === branch);
-      // An earlier branch's history already held is its answer, in a fresh scan too, until its long cache ends.
-      const held = older ? await heldRead(`history:${repository}:${headBranch}`) : null;
-      if (older && !held && !await admit(`history:${repository}:${headBranch}`)) return [];
-      return (held ?? await mergedBranchPullRequests(repository, headBranch, { fresh, ...(older ? { ttl: spread(EARLIER_BRANCH_TTL, `history:${repository}:${headBranch}`) } : {}) })).filter(pr =>
-        !pr.isCrossRepository && pr.headRefName === headBranch && pr.headRefName !== pr.defaultBranch
-        && pr.baseRefName === pr.defaultBranch);
-    });
-    for (const history of histories) for (const pr of history) {
-      if (!prs.some(known => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
+    const histories = await branchHistories(repository, historical.filter(head => head !== list.defaultBranch), { fresh, admit });
+    for (const pr of histories) {
+      if (!pr.isCrossRepository && !prs.some(known => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
     }
     return prs;
   });
@@ -687,6 +821,8 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   const read = await readTogether(sources, async source => {
     const listed = openSeen.get(openKey(source.url));
     if (listed) return listed;
+    const immutable = await mergedFact(source.url);
+    if (immutable) return immutable;
     const held = await heldRead(pullRequestKey(source.url));
     if (held && (!fresh || held.state === 'MERGED')) return held;
     if (!held && !await admit(pullRequestKey(source.url))) return { deferred: true };
@@ -705,28 +841,31 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   if (unread) throw unread.unread;
   // Reads this round did not start leave the set incomplete: the review waits for them, never runs without them.
   if (deferred) throw Object.assign(new Error(`${deferred} of ${id}'s earlier-declared PRs and branches are not read yet (${spent ? `the home has spent ${Math.round(FILL_SHARE * 100)}% of its hour's ${GITHUB_DISCOVERY_ATTEMPTS} discovery reads, so an arc starts one new read a round` : `an advisory round starts at most ${NEW_READS_PER_ROUND} new reads for an arc`}); the rest are read on the next rounds`), { code: 'github_read_admission_full', deferred: true });
-  for (const pr of read) {
-    if (pr.isCrossRepository || !['OPEN', 'MERGED'].includes(pr.state) || (pr.state === 'OPEN' && pr.isDraft)) continue;
+  for (const [i, pr] of read.entries()) {
+    if (pr.isCrossRepository || (!['OPEN', 'MERGED'].includes(pr.state) && !sources[i].retained) || (pr.state === 'OPEN' && pr.isDraft && !sources[i].retained)) continue;
     if (!prs.some((known) => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
   }
   // A PR merged at a head a review passed (its PR review, or an earlier final review: passedHead) is settled: the arc's
   // final review neither names nor owes it. It is kept apart as `pr_reviewed`, so an arc whose every PR is settled still
   // gets its final review, of its Acceptance against them (VO-3766: PRs merged at the heads a final review passed, then
   // PR-reviewed PRs merged, left no PR the final review could name, and its open Acceptance waited forever).
-  const settled = prs.filter((p) => p.observed?.state === 'MERGED' && passedHead(board, id, p.head));
+  const settled = prs.filter(p => prDisposition(board, id, p.url, p.head).disposition === 'release-only'
+    ? Boolean(releaseReadback(board, id, p.url, p.head))
+    : p.observed?.state === 'MERGED' && passedHead(board, id, p.head));
   for (const p of settled) prs.splice(prs.indexOf(p), 1);
-  const reviewed = settled.length ? { pr_reviewed: settled.map((p) => ({ url: p.url, head: p.head })) } : {};
-  // Retain scope even when all matching PRs are excluded drafts/other bases,
+  const dispositions = [...prs, ...settled].map(p => ({ url: p.url, head: p.head, ...prDisposition(board, id, p.url, p.head) })).filter(p => p.event != null);
+  // Each settled PR keeps the branch it was found on, so a `--source none` clearing that branch drops it (clearedDeclarations).
+  const reviewed = { ...(settled.length ? { pr_reviewed: settled.map(p => ({ url: p.url, head: p.head, ...(p.observed?.headRefName ? { branch: p.observed.headRefName } : {}), ...prDisposition(board, id, p.url, p.head) })) } : {}),
+    ...(dispositions.length ? { pr_dispositions: dispositions } : {}) };
+  // Retain scope even when all matching PRs are excluded drafts,
   // so a fresh scan cannot inherit that exclusion.
-  if (scope) for (const repository of reviewRepositories) scope.add(repository);
-  stacked.sort((a, b) => a.url.localeCompare(b.url));
-  // Advisory discovery can be up to five minutes old: the dispatcher tells a stacked refusal only once a fresh read
-  // (refuseStacked) confirms it.
-  if (stacked.length && (checkWorkspaces || refuseStacked)) throw refusalOf(stacked.map((pr) => refused('base', pr.url, `${pr.url} proposes ${pr.headRefName} to ${pr.baseRefName}, not ${pr.defaultBranch}: retarget it to ${pr.defaultBranch} so the arc's review includes it.`)));
-  if (!prs.length && (stacked.length || settled.length)) return { pr: [], pr_head: [], branch, review_repositories: [...reviewRepositories].sort(), stacked: stacked.map((pr) => pr.url), ...reviewed };
+  // The fresh phase must inspect every enumerated sibling: an advisory empty list
+  // cannot prove it still has no matching ready source.
+  if (scope) for (const repository of repositoriesToRead) scope.add(repository);
+  if (!prs.length && settled.length) return { pr: [], pr_head: [], branch, review_repositories: [...reviewRepositories].sort(), ...reviewed };
   if (!prs.length) return branch || !ownRepository ? null : { waits: `the card has no work branch (${task?.branch_name ? `it declares ${task.branch_name}, its repository's default` : current ? `its checkout ${own.path} is on ${current}, its repository's default` : `its checkout ${own.path} is on no branch`}): give it one with --branch, or open its PR from a wt/${id} branch` };
   // Advisory facts can refuse an attempt before its authoritative REST scan. Check every PR's properties before
-  // doing checkout work: a wrong base cannot be repaired by revalidating the whole arc every round. Discovery
+  // doing checkout work: a refused PR cannot be repaired by revalidating the whole arc every round. Discovery
   // refreshes changed heads/bases/states; local readiness is read each round. Neither check authorizes a move:
   // inspectCompletionEvidence repeats both, in the same order, against fresh metadata and the pushed head. Each
   // collects every PR's refusal, so the same state always refuses with the same set.
@@ -734,7 +873,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     await refuseTogether(prs, pr => requireReviewPullRequestProperties(pr.url, pr.head, pr.observed));
     await refuseTogether(prs, pr => requireReviewWorkspaceHead(board, id, own, pr.observed, pr.head));
   }
-  return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch, review_repositories: [...reviewRepositories].sort(), stacked: stacked.map((pr) => pr.url), ...reviewed };
+  return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch, review_repositories: [...reviewRepositories].sort(), ...reviewed };
 }
 
 /** An arc that changed no code (a disposition, such as closing a PR with its reason): its work branch holds no commit
@@ -805,7 +944,8 @@ async function knownRepositories({ strict = false } = {}) {
  *  the current heads), and a PR that verdict's request did not name is due at whatever head it has: one that was a draft
  *  when the request was made. */
 export async function reviewDue(board, id, prs) {
-  if (prs.length && answeredChanges(board, id)) return true;
+  // Only a final review's verdict is answered here: a PR review requested since (a fix's own PR) must not hide it.
+  if (prs.length && answeredChanges(board, id, ['final'])) return true;
   // A review the manager returned with no verdict is due again only for new work: a PR head its request did not name.
   const returned = returnedReview(board, id);
   if (returned) return prs.some((p) => !returned.heads.some((h) => h.pr.url === p.url && h.commit === p.head));
@@ -813,12 +953,15 @@ export async function reviewDue(board, id, prs) {
   if (!unjudged.length) return false;
   const voided = board.db.prepare("SELECT r.payload FROM task_events v JOIN task_events r ON r.id=json_extract(v.payload,'$.review_request') AND r.task_id=v.task_id WHERE v.task_id=? AND v.kind='review_voided' ORDER BY v.id DESC LIMIT 1").get(id);
   if (candidatePullRequests(voided && JSON.parse(voided.payload)?.ci).some(j => unjudged.some(p => p.url === j.pr.url && p.head === j.commit))) return true;
+  // The last final review's own verdict, the one that answered it before the next request (as verdictOn reads it): a
+  // PR or plan review's verdict, or a later review's, never dates the arc's PRs for its final review.
+  const answered = `v.id > r.id AND v.id < COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id = r.task_id AND n.kind = 'review_requested' AND n.id > r.id), 9223372036854775807)`;
   const last = board.db.prepare(`SELECT r.payload, (SELECT MIN(v.created_at) FROM task_events v WHERE v.task_id = r.task_id
-      AND v.kind IN ('changes_requested', 'review_pass') AND v.id > r.id) AS verdict_at,
+      AND v.kind IN ('changes_requested', 'review_pass') AND ${answered}) AS verdict_at,
       (SELECT v.kind FROM task_events v WHERE v.task_id = r.task_id
-      AND v.kind IN ('changes_requested', 'review_pass') AND v.id > r.id ORDER BY v.id LIMIT 1) AS verdict
-    FROM task_events r WHERE r.task_id = ? AND r.kind = 'review_requested' AND (${requestKindSql('r')}) != 'plan'
-    AND EXISTS (SELECT 1 FROM task_events v WHERE v.task_id = r.task_id AND v.kind IN ('changes_requested', 'review_pass') AND v.id > r.id)
+      AND v.kind IN ('changes_requested', 'review_pass') AND ${answered} ORDER BY v.id LIMIT 1) AS verdict
+    FROM task_events r WHERE r.task_id = ? AND r.kind = 'review_requested' AND (${requestKindSql('r')}) = 'final'
+    AND EXISTS (SELECT 1 FROM task_events v WHERE v.task_id = r.task_id AND v.kind IN ('changes_requested', 'review_pass') AND ${answered})
     ORDER BY r.id DESC LIMIT 1`).get(id);
   if (!last) return true;
   const judged = candidatePullRequests(JSON.parse(last.payload)?.ci);
@@ -835,61 +978,139 @@ export async function reviewDue(board, id, prs) {
 }
 
 /** Whether a PR review is due for one ready PR at `head` (`[{ url, head }]` as reviewDue takes them): no PR review
- *  passed at that head, and no verdict judged it or the last verdict's findings are answered (answeredChanges). The
- *  arc's other PRs neither hold it nor make it due: each is reviewed when its coder marks it ready. */
+ *  passed at that head, and no verdict judged it or the last PR or final review verdict on that head has its findings
+ *  answered (answeredHead; a plan review's findings neither hold it nor admit it). The
+ *  arc's other PRs and their verdicts neither hold it nor make it due: each is reviewed when its coder marks it ready. */
 export function prReviewDue(board, id, { head }) {
   if (prReviewedHead(board, id, head)) return false;
   // a PR review's or the final review's verdict on this head stands in its way; a plan review's never does (requestKindSql)
-  return !judgedHead(board, id, head) || answeredChanges(board, id);
+  return !judgedHead(board, id, head) || answeredHead(board, id, head, ['pr', 'final']);
+}
+
+/** Whether a plan review is due for the proposed ADR's PR at `head`: no plan review passed at that head, and no plan
+ *  review's verdict judged it or the last plan verdict's findings are answered (answeredChanges). Only plan verdicts count:
+ *  a PR review's or the final review's verdict, on this PR or any other of the arc, neither holds it nor makes it due
+ *  (an ADR amendment pushed before an unrelated PR's findings is still a plan never reviewed at that head). */
+export function planReviewDue(board, id, { head }) {
+  if (verdictOn(board, id, head, ['plan_review_pass'], ['plan'])) return false;
+  return !verdictOn(board, id, head, ['changes_requested'], ['plan']) || answeredChanges(board, id, ['plan']);
 }
 
 /** Whether an arc whose every PR is settled (merged at the head its PR review passed: `pr_reviewed`) is due its final
- *  review, of its Acceptance against them: its last review event is a PR review's request (that review is over, and the
- *  arc is back with its implementer), a voided verdict, or changes requested whose tasks are all closed. After a pass,
- *  or a final review the manager returned, nothing is new until another PR review is requested. */
-export function settledReviewDue(board, id) {
+ *  review, of its Acceptance against them: its last review event is a PR or plan review's request (that review is over, and the
+ *  arc is back with its implementer), a voided verdict, or changes requested whose tasks are all closed. A review the
+ *  manager returned gave no verdict, and its arc can reach none by a push once every PR is merged: it is due again once
+ *  the settled set (`current`, the round's `pr_reviewed`) is not the one the returned request named, or the arc
+ *  re-declared its sources after the return (returnedReview). After a pass nothing is new until another PR review is requested. */
+export function settledReviewDue(board, id, current = []) {
   const last = board.db.prepare("SELECT id, kind FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass', 'review_voided', 'review_returned') ORDER BY id DESC LIMIT 1").get(id);
   if (!last || last.kind === 'review_voided') return true;
   if (last.kind === 'changes_requested') return answeredChanges(board, id);
-  return last.kind === 'review_requested' && Boolean(board.db.prepare("SELECT 1 FROM task_events WHERE task_id = ? AND kind = 'pr_review_requested' AND id > ? LIMIT 1").get(id, last.id));
-}
-
-/** Whether the review in progress on the arc is a PR review: its `pr_review_requested` is newer than its last
- *  `review_requested` (the PR review's request records both, in that order; the final review's records only the latter). */
-export function prReviewInProgress(board, id) {
-  const at = (kind) => board.db.prepare('SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind = ?').get(id, kind)?.id ?? 0;
-  return at('pr_review_requested') > at('review_requested');
+  if (last.kind === 'review_returned') {
+    const returned = returnedReview(board, id);
+    if (!returned) return true;
+    const named = new Set([...returned.heads.map((h) => `${h.pr.url}@${h.commit}`), ...returned.settled.map((p) => `${p.url}@${p.head}`)]);
+    const held = new Set(current.map((p) => `${p.url}@${p.head}`));
+    return named.size !== held.size || [...held].some((k) => !named.has(k));
+  }
+  return last.kind === 'review_requested' && Boolean(board.db.prepare("SELECT 1 FROM task_events WHERE task_id = ? AND kind IN ('pr_review_requested', 'plan_review_requested') AND id > ? LIMIT 1").get(id, last.id));
 }
 
 /** A PR review's request: a session's request-review naming its PR (engine.requestReview's `review`), as the
  *  workflow's PR review clause selects it. The board's own final review request never carries one. */
 const asksPrReview = (payload) => payload?.review === 'pr';
+/** A plan review's request: a session's `request-review --plan` naming its proposed ADR's PR (engine.requestReview). */
+const asksPlanReview = (payload) => payload?.review === 'plan';
 
 /** Whether the arc's last review event is changes requested and every task that verdict owns is closed now. A verdict
  *  owns the tasks filed or reopened between the request it answered and itself (`request-changes --finding` files each
  *  finding as a task just before the verdict; a reviewer may reopen one instead). A verdict that owns no task is never
  *  answered this way: only a new head is. Task state is read as every board reader reads it (statusOf: the card's
- *  workflow stage over its stored status). */
-export function answeredChanges(board, id) {
+ *  workflow stage over its stored status).
+ *  With `of` (request kinds, as requestKindSql names them) only those requests' verdicts count: the latest verdict on a
+ *  request of those kinds, neither voided nor followed by another such request, must be changes requested, so a finding
+ *  on one kind of review neither holds back nor re-admits another. */
+export function answeredChanges(board, id, of = null) {
   const db = board.db;
-  const verdict = db.prepare("SELECT id, kind FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass', 'review_voided') ORDER BY id DESC LIMIT 1").get(id);
+  let verdict, asked;
+  if (of) {
+    verdict = db.prepare(`SELECT v.id, v.kind, r.id AS asked FROM task_events r CROSS JOIN task_events v ON v.task_id = r.task_id
+      AND v.kind IN ('changes_requested', 'review_pass', 'pr_review_pass', 'plan_review_pass') AND v.id > r.id
+      AND v.id < COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id = r.task_id AND n.kind = 'review_requested' AND n.id > r.id), 9223372036854775807)
+      WHERE r.task_id = ? AND r.kind = 'review_requested' AND (${requestKindSql('r')}) IN (${of.map((kind) => `'${kind}'`).join(', ')})
+      ORDER BY v.id DESC LIMIT 1`).get(id);
+    if (verdict?.kind !== 'changes_requested') return false;
+    // a newer request of these kinds is a review in progress, not findings to answer
+    if (db.prepare(`SELECT 1 FROM task_events r WHERE r.task_id = ? AND r.kind = 'review_requested' AND r.id > ?
+      AND (${requestKindSql('r')}) IN (${of.map((kind) => `'${kind}'`).join(', ')}) LIMIT 1`).get(id, verdict.id)) return false;
+    if (db.prepare("SELECT 1 FROM task_events WHERE task_id = ? AND kind = 'review_voided' AND id > ? AND json_extract(payload, '$.review_request') = ? LIMIT 1").get(id, verdict.id, verdict.asked)) return false;
+    asked = verdict.asked;
+  } else {
+    verdict = db.prepare("SELECT id, kind FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass', 'review_voided') ORDER BY id DESC LIMIT 1").get(id);
+    if (verdict?.kind !== 'changes_requested') return false;
+    asked = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind = 'review_requested' AND id < ?").get(id, verdict.id)?.id ?? 0;
+  }
+  return findingsClosed(db, id, asked, verdict.id);
+}
+
+/** Whether the findings on one PR `head` are answered: the latest verdict on a request of the kinds `of` that named that
+ *  head (verdictOn, so not a voided one) is changes requested, no later such request naming the head is still without a
+ *  verdict (a review in progress or returned, not findings to answer), and every task the verdict owns is closed, as
+ *  answeredChanges reads them. Only the head's own verdicts count: a later verdict on another PR of the arc neither hides
+ *  nor answers its findings (t_c1e92c46: #2680's pass at 7cc79ffc1 hid the answered findings on #2679 at 364911e9c, whose
+ *  PR review could then never be requested again). */
+export function answeredHead(board, id, head, of) {
+  const db = board.db;
+  const verdict = verdictOn(board, id, head, ['changes_requested', 'review_pass', 'pr_review_pass'], of, null, { latest: true });
   if (verdict?.kind !== 'changes_requested') return false;
-  const asked = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind = 'review_requested' AND id < ?").get(id, verdict.id)?.id ?? 0;
+  if (db.prepare(`SELECT 1 FROM task_events r WHERE r.task_id = ? AND r.kind = 'review_requested' AND r.id > ? AND ${namesHeadSql('r')}
+    AND (${requestKindSql('r')}) IN (${of.map((kind) => `'${kind}'`).join(', ')})
+    AND NOT EXISTS (SELECT 1 FROM task_events v WHERE v.task_id = r.task_id AND v.kind IN ('changes_requested', 'review_pass', 'pr_review_pass') AND v.id > r.id
+      AND v.id < COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id = r.task_id AND n.kind = 'review_requested' AND n.id > r.id), 9223372036854775807))
+    LIMIT 1`).get(id, verdict.id, head, head)) return false;
+  return findingsClosed(db, id, verdict.asked, verdict.id);
+}
+
+/** Whether the verdict `verdictId`, answering the request `asked`, owns a task and every one is closed now: the tasks
+ *  filed or reopened between the two (answeredChanges). */
+/** This PR's open findings, across its review rounds: the arc's open tasks filed or reopened between a request naming
+ *  the PR and the changes_requested verdict that answered it (the ownership findingsClosed reads). */
+export function openPrReviewFindings(db, id, request) {
+  const urls = new Set(candidatePullRequests(JSON.parse(request.payload ?? '{}').ci).map(p => prIdentity(p.pr.url)));
+  const asked = db.prepare("SELECT id,payload FROM task_events WHERE task_id=? AND id<=? AND kind='review_requested'").all(id, request.id)
+    .filter(r => candidatePullRequests(JSON.parse(r.payload ?? '{}').ci).some(p => urls.has(prIdentity(p.pr.url)))).map(r => r.id);
+  if (!asked.length) return [];
+  return db.prepare(`SELECT t.id,t.title,t.body,COALESCE(c.stage,t.status) AS status FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
+    WHERE c.subtask_of=? AND COALESCE(c.stage,t.status) NOT IN ('done','cancelled','archived') AND EXISTS (
+      SELECT 1 FROM task_events r JOIN task_events v ON v.task_id=r.task_id AND v.kind='changes_requested' AND v.id>r.id
+        AND v.id<COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id=r.task_id AND n.kind='review_requested' AND n.id>r.id),9223372036854775807)
+      JOIN task_events e ON e.task_id=t.id AND e.kind IN ('created','reopened') AND e.id>r.id AND e.id<v.id
+      WHERE r.task_id=? AND r.id IN (SELECT value FROM json_each(?))) ORDER BY t.created_at`).all(id, id, JSON.stringify(asked));
+}
+
+function findingsClosed(db, id, asked, verdictId) {
   const owned = db.prepare(`SELECT COALESCE(c.stage, t.status) AS status FROM supercode_cards c JOIN tasks t ON t.id = c.task_id
-    WHERE c.subtask_of = ? AND EXISTS (SELECT 1 FROM task_events e WHERE e.task_id = c.task_id AND e.kind IN ('created', 'reopened') AND e.id > ? AND e.id < ?)`).all(id, asked, verdict.id);
+    WHERE c.subtask_of = ? AND EXISTS (SELECT 1 FROM task_events e WHERE e.task_id = c.task_id AND e.kind IN ('created', 'reopened') AND e.id > ? AND e.id < ?)`).all(id, asked, verdictId);
   return owned.length > 0 && owned.every((t) => ['done', 'cancelled', 'archived'].includes(t.status));
 }
 
 /** The manager's return of the arc's review (`review_returned`, no verdict) while it is the arc's latest review event, with
- *  the PR heads its review request named (`heads`, as candidatePullRequests answers them); else null. */
+ *  the PR heads its review request named (`heads`, as candidatePullRequests answers them); else null. A return holds
+ *  nothing when it was made because the arc re-declared its sources after the review request (reopenReview's
+ *  `redeclared`), or once the arc re-declares them after the return (redeclaredSince): its next review is built from the
+ *  declarations by the ordinary rules. A declaration made while the review ran, before the manager returned it, is
+ *  part of what the return answered and does not undo it. */
 export function returnedReview(board, id) {
   const db = board.db;
   const last = db.prepare("SELECT id, kind, payload FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass', 'review_voided', 'review_returned') ORDER BY id DESC LIMIT 1").get(id);
   if (last?.kind !== 'review_returned') return null;
-  const asked = JSON.parse(last.payload ?? '{}')?.review_request;
+  const returned = JSON.parse(last.payload ?? '{}') ?? {};
+  if (returned.redeclared || redeclaredSince(db, id, last.id)) return null;
+  const asked = returned.review_request;
   const request = asked ? db.prepare("SELECT payload FROM task_events WHERE task_id = ? AND id = ? AND kind = 'review_requested'").get(id, asked)
     : db.prepare("SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' AND id < ? ORDER BY id DESC LIMIT 1").get(id, last.id);
-  return { id: last.id, heads: candidatePullRequests(request ? JSON.parse(request.payload)?.ci : null) };
+  const ci = request ? JSON.parse(request.payload)?.ci : null;
+  return { id: last.id, heads: candidatePullRequests(ci), settled: ci?.pr_reviewed ?? [] };
 }
 
 /** A commit's date and source tree, read once: both are immutable. Only a successful read is cached; an unread commit
@@ -906,28 +1127,36 @@ const commitTime = async (p) => (await commitRead(p)).at;
 /** Whether the PR's head carries the same source tree as `commit` of the same PR. */
 const sameTree = async (p, commit) => (await commitRead(p)).tree === (await commitRead({ url: p.url, head: commit })).tree;
 
-/** A PR read for a committed review or acceptance: a merged one already held is its answer (its head, base and state
+/** A PR read for review admission or acceptance: a merged one already held is its answer (its head, base and state
  *  never change again), any other is read fresh. */
 const readSource = async (url) => {
-  const held = await heldRead(pullRequestKey(url));
-  return held?.state === 'MERGED' ? held : readPullRequest(url);
+  return await mergedFact(url) ?? readPullRequest(url);
 };
 
-/** A cached exclusion must never hide a newly ready/reopened source from a committed review or acceptance. The final
+/** A cached exclusion must never hide a newly ready/reopened source from review admission or acceptance. The final
  *  review's request names the whole current set, which leaves out each PR merged at the head its PR review passed
- *  (openReviewPullRequests: `pr_reviewed`). A verdict or acceptance of a request also stands beside a PR the request
+ *  (openReviewPullRequests: `pr_reviewed`). Acceptance of a request also stands beside a PR the request
  *  did not name when that PR is merged at a head an earlier verdict of the arc judged (`judged`): it was reviewed at the
  *  head it merged at, and no review is due for it (reviewDue). A PR review (`single`) names one ready PR of the set, and
- *  its request and verdict stand beside every other PR of the arc, open or merged. */
+ *  its request stands beside every other PR of the arc, open or merged. */
 async function requireCurrentReviewSet(board, id, urls, repositories = [], { judged = false, single = false } = {}) {
+  if (single) {
+    // A PR review needs its named PR's repository to belong to the arc's workspace, tasks or declared sources,
+    // read from the card without GitHub. Its repositories are the ones already known plus that PR's repository;
+    // requireReviewPullRequestProperties separately reads the named PR at its current head.
+    const { repositories: arc } = await arcRepositories(board, id);
+    const known = new Set([...arc].map((r) => r.toLowerCase()));
+    const outside = urls.map(repositoryOf).filter((r) => !known.has(r.toLowerCase()));
+    if (outside.length) throw new Error(`A PR review names a PR of the arc's repositories; ${[...new Set(outside)].join(', ')} is not one of them (declare it: comment ${id} --source owner/repo:branch).`);
+    return [...new Set([...repositories, ...urls.map(repositoryOf)].map((r) => r.toLowerCase()))].sort();
+  }
   const current = await openReviewPullRequests(board, id, { fresh: true,
     repositories: [...repositories, ...urls.map(repositoryOf)] });
-  if (single) return current?.review_repositories ?? repositories;
   const unnamed = (current?.pr ?? []).map((url, i) => ({ url, head: current.pr_head[i] })).filter(p => !urls.includes(p.url));
   const settled = judged ? await readTogether(unnamed, async p => judgedHead(board, id, p.head) !== null
     && (await readSource(p.url)).state === 'MERGED') : unnamed.map(() => false);
   const omitted = unnamed.filter((_, i) => !settled[i]).map(p => p.url);
-  if (omitted.length) throw new Error(`The current review source set also includes ${omitted.join(', ')}; refresh the complete candidate before requesting review, recording its verdict or accepting it`);
+  if (omitted.length) throw new Error(`The current review source set also includes ${omitted.join(', ')}; refresh the complete candidate before requesting review or accepting it`);
   return current?.review_repositories ?? repositories;
 }
 
@@ -949,6 +1178,71 @@ export function passedHead(board, id, head) {
   return verdictOn(board, id, head, ['pr_review_pass', 'review_pass'], ['pr', 'final']);
 }
 
+/** Current exact-head disposition; a new declaration withdraws all older readbacks. */
+export function prDisposition(board, id, url, head) {
+  const row = board.db.prepare(`SELECT id,payload FROM task_events WHERE task_id=? AND kind='pr_disposition_recorded'
+    AND json_valid(payload) AND json_extract(payload,'$.url')=? ORDER BY id DESC LIMIT 1`).get(id, url);
+  const value = row ? JSON.parse(row.payload) : null;
+  return value?.head === head ? { ...value, event: row.id } : { disposition: 'merge', event: null };
+}
+export function releaseReadback(board, id, url, head) {
+  const disposition = prDisposition(board, id, url, head);
+  const pass = verdictOn(board, id, head, ['pr_review_pass', 'review_pass'], ['pr', 'final'], url);
+  if (disposition.disposition !== 'release-only' || !pass) return null;
+  const row = board.db.prepare(`SELECT payload FROM task_events WHERE task_id=? AND kind='pr_release_readback'
+    AND json_valid(payload) AND json_extract(payload,'$.url')=? AND json_extract(payload,'$.head')=? ORDER BY id DESC LIMIT 1`).get(id, url, head);
+  const value = row ? JSON.parse(row.payload) : null;
+  if (value?.disposition_event !== disposition.event || value?.verdict !== pass.id
+    || value?.target !== disposition.target || value?.artifact !== head || value?.verification?.source !== head || value?.verification?.target !== value.target
+    || !['machine', 'manager-attestation'].includes(value?.verification?.kind)) return null;
+  return value;
+}
+/** A retained readback becomes settlement only beside a fresh observation of its PR head. */
+export async function verifiedReleaseReadback(board, id, url, head) {
+  const readback = releaseReadback(board, id, url, head);
+  if (!readback) return null;
+  const pr = await readPullRequest(url);
+  return pr.headRefOid === head && !pr.isCrossRepository ? releaseReadback(board, id, url, head) : null;
+}
+/** Prepare evidence outside the write. The engine checks its event bindings again at commit. */
+export async function preparePrEvidence(board, id, source, options, { manager = false, actor } = {}) {
+  const { url, head } = source;
+  if (typeof actor !== 'string' || !actor.trim()) throw new Error('PR evidence needs the authenticated actor identity.');
+  const pr = await readPullRequest(url);
+  if (pr.headRefOid !== head || pr.isCrossRepository) throw new Error('PR evidence must name the current exact repository PR head.');
+  const reason = String(options.reason ?? '').trim();
+  if (!reason) throw new Error('PR disposition/readback needs a reason.');
+  if (options.disposition != null) {
+    if (!['merge', 'release-only'].includes(options.disposition)) throw new Error('PR disposition is merge or release-only.');
+    const target = options.disposition === 'release-only' ? String(options.target ?? '').trim() : null;
+    if (options.disposition === 'release-only' && !target) throw new Error('Release-only disposition names its intended --release-target.');
+    return { kind: 'pr_disposition_recorded', url, head, disposition: options.disposition, target, actor, reason };
+  }
+  const disposition = prDisposition(board, id, url, head);
+  const pass = verdictOn(board, id, head, ['pr_review_pass', 'review_pass'], ['pr', 'final'], url);
+  if (disposition.disposition !== 'release-only' || !pass) throw new Error('Release readback needs an active release-only disposition and a valid independent pass of this exact PR/head.');
+  const { target, artifact, evidence } = options.readback ?? {};
+  if (typeof target !== 'string' || target !== disposition.target || artifact !== head || typeof evidence !== 'string' || !evidence.trim()) throw new Error('Release readback needs its target, exact released head as artifact, and evidence pointer.');
+  let verification;
+  if (target.startsWith('machine:')) {
+    if (options.readback.attest) throw new Error('A machine target uses its status verifier, not an attestation.');
+    const machine = target.slice('machine:'.length);
+    if (!machine) throw new Error('Name the released machine.');
+    const answer = await runtimeDoor(machine, 'harness.v1.machine.describe', {}, { timeout: 9000 });
+    if (answer.code !== 0) throw new Error(`Release target could not be verified: ${answer.stderr}`);
+    const receipt = JSON.parse(answer.stdout), selected = receipt.runtime_release?.source;
+    const source = selected?.binding === 'node' ? selected.node : selected?.native;
+    if (![receipt.name, receipt.id, receipt.machineId].includes(machine) || selected?.binding_verdict !== 'matches'
+      || selected?.commit !== head || source?.commit !== head || source?.dirty !== false || source?.observation_error) throw new Error('Machine status does not confirm this exact reviewed source/artifact.');
+    verification = { kind: 'machine', source: head, target, observed_at: Date.now(), receipt };
+  } else {
+    if (!manager || options.readback.attest !== true) throw new Error('This target has no machine verifier; an explicit manager attestation of the observed target and source is required.');
+    verification = { kind: 'manager-attestation', source: head, target, observed_at: Date.now(), actor };
+  }
+  return { kind: 'pr_release_readback', url, head, actor, reason, target, artifact, evidence,
+    disposition_event: disposition.event, verdict: pass.id, verification };
+}
+
 /** A review request's kind, as SQL over its `review_requested` row `r`: a PR review's and a plan review's request each
  *  record their own marker right after it (pr_review_requested, plan_review_requested), before the next request; the
  *  board's final review records none. Each kind keeps its own verdicts: a plan review, which grades no code head, never
@@ -960,17 +1254,30 @@ const requestKindSql = (r) => `CASE
     AND k.id < COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id = ${r}.task_id AND n.kind = 'review_requested' AND n.id > ${r}.id), 9223372036854775807)) THEN 'pr'
   ELSE 'final' END`;
 
-function verdictOn(board, id, head, kinds, of) {
+/** The latest requested candidate and its kind, using the same marker ordering as verdict selection. */
+export function latestReviewRequest(db, id) {
+  return db.prepare(`SELECT r.id,r.payload,${requestKindSql('r')} AS kind FROM task_events r
+    WHERE r.task_id=? AND r.kind='review_requested' ORDER BY r.id DESC LIMIT 1`).get(id) ?? null;
+}
+
+/** Whether review request `r` named a head, as SQL binding that head twice: its one PR's commit or any of its PRs'. */
+const namesHeadSql = (r) => `(json_extract(${r}.payload, '$.ci.commit') = ?
+      OR EXISTS (SELECT 1 FROM json_each(${r}.payload, '$.ci.prs') p WHERE json_extract(p.value, '$.commit') = ?))`;
+
+/** The first verdict of `kinds` (the latest with `latest`) that answered a request of the kinds `of` naming `head` (of
+ *  `url`, when given) and was not voided, with the request it answered (`asked`), or null. */
+function verdictOn(board, id, head, kinds, of, url = null, { latest = false } = {}) {
   if (!head) return null;
   // A request's JSON head list is checked once before visiting its verdicts. Without CROSS JOIN SQLite starts
   // from every verdict and reparses the same older requests for each of them (including heads never requested).
-  return board.db.prepare(`SELECT v.id, v.kind FROM task_events r CROSS JOIN task_events v ON v.task_id = r.task_id
+  return board.db.prepare(`SELECT v.id, v.kind, r.id AS asked FROM task_events r CROSS JOIN task_events v ON v.task_id = r.task_id
     AND v.kind IN (${kinds.map((kind) => `'${kind}'`).join(', ')}) AND v.id > r.id
     AND v.id < COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id = r.task_id AND n.kind = 'review_requested' AND n.id > r.id), 9223372036854775807)
     AND NOT EXISTS (SELECT 1 FROM task_events x WHERE x.task_id=r.task_id AND x.kind='review_voided' AND x.id>v.id AND json_extract(x.payload,'$.review_request')=r.id)
-    WHERE r.task_id = ? AND r.kind = 'review_requested' AND (json_extract(r.payload, '$.ci.commit') = ?
-      OR EXISTS (SELECT 1 FROM json_each(r.payload, '$.ci.prs') p WHERE json_extract(p.value, '$.commit') = ?))
-      AND (${requestKindSql('r')}) IN (${of.map((kind) => `'${kind}'`).join(', ')}) ORDER BY v.id LIMIT 1`).get(id, head, head) ?? null;
+    WHERE r.task_id = ? AND r.kind = 'review_requested' AND ${namesHeadSql('r')}
+      AND (? IS NULL OR (json_extract(r.payload,'$.ci.pr.url')=? AND json_extract(r.payload,'$.ci.commit')=?)
+        OR EXISTS (SELECT 1 FROM json_each(r.payload,'$.ci.prs') p WHERE json_extract(p.value,'$.pr.url')=? AND json_extract(p.value,'$.commit')=?))
+      AND (${requestKindSql('r')}) IN (${of.map((kind) => `'${kind}'`).join(', ')}) ORDER BY v.id ${latest ? 'DESC' : 'ASC'} LIMIT 1`).get(id, head, head, url, url, head, url, head) ?? null;
 }
 
 export async function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
@@ -998,36 +1305,54 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
         if (wanted.length !== passed.length || wanted.some((w) => !passed.some((p) => p.pr.url === w.pr.url && p.commit === w.commit))) throw new Error('The current PR heads need their independent verdict before acceptance.');
         await readTogether(wanted, async w => {
           const pr = await readSource(w.pr.url);
-          if (!['OPEN', 'MERGED'].includes(pr.state) || pr.headRefOid !== w.commit) throw new Error(`The head of ${w.pr.url} changed after its verdict; request a new review.`);
+          if ((!['OPEN', 'MERGED'].includes(pr.state) && !releaseReadback(board, id, w.pr.url, w.commit)) || pr.headRefOid !== w.commit) throw new Error(`The head of ${w.pr.url} changed after its verdict; request a new review.`);
         });
         Object.assign(state, { ...candidate, ready: true, reason: null });
       }
       return state;
     }
-    const asked = stage === 'review_verdict' ? reviewCandidate(board, id) : null;
-    const urls = [].concat(payload.pr ?? payload.metadata?.pr ?? candidatePullRequests(asked).map((c) => c.pr.url)).filter(Boolean);
+    if (stage === 'review_verdict') {
+      // The verdict judges the review run's frozen candidate: the arc's latest run is its reviewer's while it reviews.
+      const asked = reviewCandidate(board, id);
+      const latest = board.db.prepare('SELECT metadata FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(id);
+      const bound = latest ? JSON.parse(latest.metadata ?? '{}')?.supercode?.review_candidate : null;
+      if (bound && !isDeepStrictEqual(bound, asked)) throw new Error('This reviewer run was launched for a different review candidate.');
+      const requested = candidatePullRequests(asked);
+      const urls = [].concat(payload.pr ?? payload.metadata?.pr ?? requested.map(p => p.pr.url));
+      const named = [].concat(payload.reviewed_sha ?? payload.pr_head ?? payload.commit ?? []);
+      const sameSet = (left, right) => {
+        const wanted = new Set(right);
+        return new Set(left).size === wanted.size && left.every(value => wanted.has(value));
+      };
+      if (urls.some(url => typeof url !== 'string')
+        || !sameSet(urls.map(prIdentity), requested.map(p => prIdentity(p.pr.url)))) throw new Error('The verdict must cover exactly the PRs its review request named.');
+      if (named.some(head => typeof head !== 'string' || !/^[a-f0-9]{40}$/.test(head))
+        || !sameSet(named, requested.map(p => p.commit))) throw new Error('Name exactly the requested PR heads with --reviewed-sha.');
+      return { ...state, ...asked, ready: true, reason: null };
+    }
+    const urls = [].concat(payload.pr ?? payload.metadata?.pr ?? []).filter(Boolean);
     if (urls.some(url => typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url))) throw new Error('Name each GitHub PR URL with --pr.');
     // Advisory heads can refuse a redundant request, never authorize one. Do
     // this before a fresh source scan, including for callers outside dispatch.
     const proposed = [].concat(payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
-    // A PR review (its request names its PR; its verdict answers the PR review in progress) names one
-    // ready PR, whatever other PRs the arc has, open or merged.
-    const single = stage === 'request_review' ? asksPrReview(payload) : stage === 'review_verdict' && prReviewInProgress(board, id);
-    if (single && stage === 'request_review' && urls.length !== 1) throw new Error('A PR review names one PR: --pr URL --pr-head SHA.');
-    const due = (prs) => single ? prs.every((p) => prReviewDue(board, id, p)) : reviewDue(board, id, prs);
-    if (stage === 'request_review' && urls.length && proposed.length === urls.length && proposed.every(head => typeof head === 'string' && /^[a-f0-9]{40}$/.test(head))
+    // A PR review and a plan review each name one PR, whatever other PRs the arc has, open or merged, and each is due
+    // by its own kind's verdicts alone (prReviewDue, planReviewDue). Only the final review is due by the whole set (reviewDue).
+    const plan = asksPlanReview(payload);
+    const single = plan || asksPrReview(payload);
+    if (single && urls.length !== 1) throw new Error(plan ? 'A plan review names its proposed ADR\'s PR: --plan --pr URL --pr-head SHA.' : 'A PR review names one PR: --pr URL --pr-head SHA.');
+    const due = (prs) => plan ? prs.every((p) => planReviewDue(board, id, p)) : single ? prs.every((p) => prReviewDue(board, id, p)) : reviewDue(board, id, prs);
+    const kind = plan ? 'plan review' : 'PR review';
+    if (urls.length && proposed.length === urls.length && proposed.every(head => typeof head === 'string' && /^[a-f0-9]{40}$/.test(head))
       && !await due(urls.map((url, i) => ({ url, head: proposed[i] })))) {
-      throw new Error(single ? 'The proposed PR head already has a verdict (a pass, or findings not yet answered); no PR review is due.' : 'Every proposed PR head already has a verdict or carries no new source; no review is due.');
+      throw refused('judged', urls[0], single ? `The proposed PR head already has a ${kind}'s verdict (a pass, or findings not yet answered); no ${kind} is due.` : 'Every proposed PR head already has a verdict or carries no new source; no review is due.');
     }
-    if (stage === 'request_review' || stage === 'review_verdict') state.review_repositories = await requireCurrentReviewSet(board, id, urls, payload.review_repositories ?? [], { judged: stage === 'review_verdict', single });
-    if (!urls.length && asked?.no_code) return { ...state, no_code: asked.no_code };
+    state.review_repositories = await requireCurrentReviewSet(board, id, urls, payload.review_repositories ?? [], { single });
     // The final review of an arc whose every PR is settled by its PR review names no PR: it reviews the arc's Acceptance
     // against them (settledReviewDue).
-    const settled = stage === 'request_review' ? payload.pr_reviewed : asked?.pr_reviewed;
+    const settled = payload.pr_reviewed;
     if (!urls.length && settled?.length && !single) return { ...state, pr_reviewed: settled };
     // Merged source is immutable and needs no surviving workspace. Resolve an
-    // unmerged candidate's checkout as before; a broken legacy path never
-    // prevents a verdict on already merged commits.
+    // unmerged candidate's checkout before admitting its review.
     const read = await mapGithubSources(urls, readSource);
     const mergedOnly = urls.length && read.every(pr => pr.state === 'MERGED');
     const own = mergedOnly ? null : await repositoryWorkspace(board, id);
@@ -1045,31 +1370,18 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       const strays = read.filter((pr) => pr.state !== 'MERGED' && !declared(pr));
       if (strays.length) throw refusalOf(strays.map((stray) => refused('undeclared', stray.url, `An unmerged PR candidate needs a repository workspace: ${stray.url} (${stray.headRefName}) is on no branch the card or its tasks declare; declare it on the arc: comment ${id} "<why>" --source ${repositoryOf(stray.url)}:${stray.headRefName}`)));
     }
-    // A verdict with no requested PR (a scratch arc) keeps its own contract. An arc's review
-    // always names every opened PR it changed, independent of deployment.
-    if (stage === 'review_verdict' && !asked && !urls.length) return state;
+    // An arc's review always names every opened PR it changed, independent of deployment.
     Object.assign(state, { required: true, ready: false });
     if (!urls.length) throw new Error('Name each opened PR with --pr.');
-    const named = [].concat(stage === 'review_verdict'
-      ? payload.reviewed_sha ?? payload.pr_head ?? payload.commit ?? []
-      : payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
-    if (stage === 'request_review' && named.length !== urls.length) throw new Error('Name each PR head with --pr-head, one for each --pr, in the same order.');
-    if (stage === 'review_verdict' && !named.length) throw new Error('Name every reviewed PR head with --reviewed-sha.');
-    // Every PR's properties, then (for a review request) every PR's checkout at its pushed head, as the advisory pass
+    const named = [].concat(payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
+    if (named.length !== urls.length) throw new Error('Name each PR head with --pr-head, one for each --pr, in the same order.');
+    // Every PR's properties, then every PR's checkout at its pushed head, as the advisory pass
     // checks them; each collects every refusal (refuseTogether).
-    const prs = await refuseTogether(urls, (url, index) => requireReviewPullRequestProperties(url, stage === 'request_review' ? named[index] : null, read[index]));
-    if (stage === 'request_review') await refuseTogether(prs, (source, index) => requireReviewWorkspaceHead(board, id, own, read[index], source.commit, { pushed: true }));
-    if (stage === 'request_review') {
-      // A review is asked for only while some PR has a head no verdict has judged; a PR review, while its one PR's is.
-      if (!await due(prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw new Error(single ? 'That PR head already has a verdict (a pass, or findings not yet answered): push a commit that changes the source, or close the tasks that own the last verdict\'s findings, before requesting its PR review.' : 'Every PR head has a verdict, carries the source tree its verdict judged, or predates it: push a commit that changes the source, or close the tasks that own the last verdict\'s findings, before requesting review.');
-    } else if (asked) {
-      const requested = candidatePullRequests(asked);
-      if (requested.length !== prs.length || requested.some((r) => !prs.some((p) => p.pr.url === r.pr.url && p.commit === r.commit))) throw new Error('The verdict covers the requested PRs at their requested heads; a PR whose head moved needs a new review request.');
-      if (requested.some((r) => !named.includes(r.commit))) throw new Error('Name every reviewed PR head with --reviewed-sha.');
-      const latest = board.db.prepare('SELECT metadata FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(id);
-      const bound = candidatePullRequests(latest && JSON.parse(latest.metadata ?? '{}')?.supercode?.review_candidate);
-      if (bound.length && (bound.length !== requested.length || bound.some((b) => !requested.some((r) => r.pr.url === b.pr.url && r.commit === b.commit)))) throw new Error('This reviewer run was launched for different PR heads.');
-    }
+    const prs = await refuseTogether(urls, (url, index) => requireReviewPullRequestProperties(url, named[index], read[index]));
+    await refuseTogether(prs, (source, index) => requireReviewWorkspaceHead(board, id, own, read[index], source.commit, { pushed: true }));
+    // A review is asked for only while some PR has a head no verdict has judged; a PR or plan review, while its one PR's
+    // head has no verdict of its own kind.
+    if (!await due(prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw refused('judged', prs[0].pr.url, single ? `That PR head already has a ${kind}'s verdict (a pass, or findings not yet answered): push a commit that changes the source, or close the tasks that own the last verdict's findings, before requesting its ${kind}.` : 'Every PR head has a verdict, carries the source tree its verdict judged, or predates it: push a commit that changes the source, or close the tasks that own the last verdict\'s findings, before requesting review.');
     Object.assign(state, { ...prs[0], ready: true, reason: null, ...(prs.length > 1 ? { prs } : {}), ...(settled?.length && !single ? { pr_reviewed: settled } : {}) });
   } catch (error) {
     Object.assign(state, { required: true, ready: false, reason: String(error?.message ?? error) });
@@ -1081,6 +1393,36 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
   return state;
 }
 
+// Quiet tracked predicates produce no path list. Untracked detection streams only a bounded
+// sample and terminates that owned Git child once one dirty fact is known. A Git failure
+// before a dirty fact is an error, never a clean checkout or an uncommitted-state refusal.
+async function gitState(path, args, { stream = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd: path, stdio: ['ignore', 'pipe', 'pipe'] });
+    let sample = '', diagnostic = '', found = false, timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 9000);
+    child.stdout.on('data', bytes => {
+      if (!stream || found) return;
+      sample = (sample + bytes.toString('utf8')).slice(0, 512);
+      if (sample.length) { found = true; child.kill('SIGTERM'); }
+    });
+    child.stderr.on('data', bytes => { diagnostic = (diagnostic + bytes.toString('utf8')).slice(-500); });
+    child.once('error', error => { clearTimeout(timer); reject(error); });
+    child.once('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) return reject(new Error('git clean-state check exceeded 9 seconds'));
+      if (found) return resolve(`untracked path(s): ${JSON.stringify(sample.split('\0')[0])}${sample.includes('\0') ? ' (sample; more may exist)' : '…'}`);
+      if (code === 0) return resolve(null);
+      if (!stream && code === 1) return resolve('tracked index/worktree changes (paths omitted)');
+      reject(new Error(`git clean-state check failed (${code}): ${diagnostic}`));
+    });
+  });
+}
+export async function reviewWorkspaceDirty(path) {
+  return await gitState(path, ['diff', '--quiet', '--no-ext-diff', '--ignore-submodules=none', 'HEAD', '--'])
+    ?? await gitState(path, ['ls-files', '--others', '--exclude-standard', '-z'], { stream: true });
+}
+
 /** Local review readiness, also usable with advisory metadata to refuse before spending REST admission. */
 async function requireReviewWorkspaceHead(board, id, own, observed, head, { pushed = false } = {}) {
   const url = observed.url, repository = repositoryOf(url), branch = observed.headRefName;
@@ -1091,8 +1433,8 @@ async function requireReviewWorkspaceHead(board, id, own, observed, head, { push
   if (!path) return;
   await run('git', ['check-ref-format', '--branch', branch], path);
   if (await run('git', ['rev-parse', 'HEAD'], path) !== head) throw refused('head', url, `The head named for ${url} must be its worktree head.`);
-  const uncommitted = (await run('git', ['status', '--porcelain', '--untracked-files=normal'], path)).split('\n').filter(Boolean);
-  if (uncommitted.length) throw refused('uncommitted', url, `Commit the work in ${path} before requesting review: ${uncommitted.length} uncommitted path(s): ${uncommitted.slice(0, 5).map((l) => l.replace(/^\s*\S+\s+/, '')).join(', ')}${uncommitted.length > 5 ? ', …' : ''}`);
+  const dirty = await reviewWorkspaceDirty(path);
+  if (dirty) throw refused('uncommitted', url, `Commit the work in ${path} before requesting review: ${dirty}`);
   if (pushed) {
     const remote = (await run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path)).split(/\s+/)[0];
     if (remote !== head) throw refused('unpushed', url, `Push the exact head of ${url} before requesting review.`);
@@ -1100,21 +1442,22 @@ async function requireReviewWorkspaceHead(board, id, own, observed, head, { push
 }
 
 /** PR-only readiness, shared by advisory refusals and fresh source validation. */
-function requireReviewPullRequestProperties(url, supplied, observed) {
+export function requireReviewPullRequestProperties(url, supplied, observed) {
   if (typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url)) throw new Error('Name the opened PR URL with --pr.');
   const repository = new URL(url).pathname.split('/').slice(1, 3).join('/');
   // A PR merged before its review (an outage fix landed first) is still reviewed: its head is fixed for good, so the
   // verdict is recorded on that head, and nothing about a worktree or its base can move under it any more.
   const merged = observed.state === 'MERGED';
-  if ((observed.state !== 'OPEN' && !merged) || observed.isCrossRepository) throw refused('state', url, `Source review needs an open or merged PR from its repository (${url}).`);
+  if (observed.isCrossRepository) throw refused('foreign', url, `Source review needs a PR from its own repository (${url}).`);
+  if (observed.state !== 'OPEN' && !merged) throw refused('state', url, `Source review needs an open or merged PR (${url}).`);
   if (!merged && observed.isDraft) throw refused('draft', url, `${url} is a draft; its review starts when it is marked ready for review.`);
   const head = supplied ?? observed.headRefOid;
   if (!/^[a-f0-9]{40}$/.test(head)) throw new Error('Name the full PR head commit with --pr-head (reviewer: --reviewed-sha).');
-  if (observed.headRefOid !== head) throw new Error(`The head of ${url} changed to ${observed.headRefOid}; request review of that head before recording a verdict.`);
+  if (observed.headRefOid !== head) throw refused('moved', url, `The head of ${url} changed to ${observed.headRefOid}; request review of that head before recording a verdict.`);
   const branch = observed.headRefName;
-  const mainBranch = observed.defaultBranch ?? 'main';
-  // A merged hotfix may have landed on another base (prod); a PR from the main branch itself is a release, never arc work.
-  if (branch === mainBranch || (!merged && observed.baseRefName !== mainBranch)) throw refused('base', url, `${url} must propose its worktree branch to the repository main branch.`);
+  // A PR whose head is the default branch (main → prod) is a release, never an arc's work.
+  if (branch === (observed.defaultBranch ?? 'main')) throw refused('release', url, `${url} proposes the default branch ${branch}; it is a release, not an arc's work.`);
+  // Any base: the review reads the PR's whole diff against its own base (pr.base).
   return { repository, branch, commit: head, source_sha: head, pr: { url: observed.url, number: observed.number, head, branch, base: observed.baseRefName } };
 }