@volter/supercode-orchestrator 0.5.225 → 0.5.227

package/board/ci.mjs

@@ -5,10 +5,9 @@ import { readFileSync, realpathSync, writeFileSync, renameSync, statSync } from
 import { dirname, join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { branchCheckouts, checkoutOf, isLocalWorkspace, isWorkspacePath, resolveWorkspace, plainWorkspace } from './workspace.mjs';
+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 { cardHandleOf } from './store.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
@@ -273,6 +272,9 @@ export function completionEvidence(board, id) {
 
 export function completionPhase(board, id, entry, verb, payload, roles = []) {
   if (verb === 'request_review') return 'request_review';
+  // A person's completion of their own card (person-done) is judged by no review and carries no source: its evidence is
+  // the person's act the Workplace reported, which the workflow checks names the card's person.
+  if (verb === 'complete' && payload.person && roles.includes('platform')) return 'person';
   if ((verb === 'request_state' && payload.state === 'done' || verb === 'complete') && roles.includes('reviewer')) return 'review_verdict';
   return verb === 'complete' ? 'acceptance' : 'completion';
 }
@@ -298,7 +300,7 @@ export function withCompletionEvidence(board, id, state, fn) {
 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);
   const payload = row && JSON.parse(row.payload);
-  return payload?.ci?.pr || payload?.ci?.no_code ? payload.ci : null;
+  return payload?.ci?.pr || payload?.ci?.no_code || payload?.ci?.pr_reviewed?.length ? payload.ci : null;
 }
 
 /** The PRs an evidence record covers: every PR of one arc review (the first is also its top-level PR). */
@@ -320,7 +322,7 @@ async function repositoryWorkspace(board, id) {
   const owner = workspaceOwner(board, id);
   if (!owner) return null;
   // the worktree's folder, when it is still to be made, is named for its card (workspace.mjs worktreeFolder)
-  const workspace = { ...owner, handle: cardHandleOf(board, owner.id) };
+  const workspace = workspaceTask(board, owner);
   const here = isLocalWorkspace(workspace);
   if (!here) {
     const identity = workspace.workspace_anchor ?? workspace.workspace_path;
@@ -328,10 +330,14 @@ async function repositoryWorkspace(board, id) {
     // A portable remote declaration supplies the source identity. Legacy paths
     // are resolved by their own machine, never read as paths on the board host.
     const resolved = plainWorkspace(workspace.workspace_kind, identity, workspace.branch_name) ?? await resolveWorkspace(workspace, false);
+    // a plain folder holding the arc's repositories (workspace.mjs plainFolder) has none of its own: the review reads
+    // the arc's recorded ones, as a scratch arc's does
+    if (resolved.folder) return null;
     return { ...resolved, branch: workspace.branch_name ?? resolved.branch, here: false };
   }
   if (workspace.workspace_anchor) {
     const resolved = await resolveWorkspace(workspace, false);
+    if (resolved.folder) return null;
     // Resolution without create names a solo worktree even before it exists on
     // this machine. Its portable repository and branch still identify the
     // pushed PR. Only an actual directory can supply local source evidence.
@@ -469,8 +475,8 @@ function earlierDeclaredBranches(db, id) {
 
 /** 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
- *  at its current head and leaves out only a closed one, an open draft, and a merged one whose merged head a passed
- *  review judged (discoverReviewSources). */
+ *  at its current head and leaves out only a closed one and an open draft: a merged one is in at its merged head
+ *  (discoverReviewSources). */
 export function declaredPullRequests(db, id) {
   const latest = new Map();
   for (const declaration of declarationsOf(db, id, 'sources')) for (const source of declaration.items) {
@@ -522,11 +528,14 @@ export function declaredWorkBranches(db, id) {
   return [...new Set([...declared, ...reviewed].filter(Boolean))];
 }
 
-/** Every opened PR of the arc, plus an unjudged merged PR on its declared branch, each proposed to its repository's default branch: an open PR whose head is the card's
+/** 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
+ *  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. One review covers them all; the caller decides the transition. */
+ *  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 });
   // Every authorization entry acquires the broad advisory scope, not only
@@ -572,7 +581,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()));
-  const answered = answeredChanges(board, id);
   // 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.
@@ -640,7 +648,8 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
       ...(repository === ownRepository ? branch ? [branch] : [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`] : []),
       ...registered.filter(r => r.repository === repository).map(r => r.branch),
     ])];
-    // A judged merged head is passed over, except while an answered changes-requested verdict makes it due again.
+    // 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);
@@ -649,7 +658,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
       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 && (answered || !judgedHead(board, id, pr.headRefOid)));
+        && 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 });
@@ -660,9 +669,8 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   // Each declared PR discovery did not find is followed at its current head (GitHub's), never pinned to the declared
   // one, so a push after the declaration is reviewed instead of failing every tick. One open in a repository listed above
   // is taken from that list, with no read of its own; any other is read (a merged answer already held is reused, in a
-  // fresh scan too: a merged PR never changes again). One from a fork, closed, or an open draft is left out, and so is
-  // a merged one whose merged head a passed review judged (it was reviewed at the head it merged at; one that moved
-  // after its pass and merged unreviewed is still in). One outside the arc's repositories is in scope only when it is
+  // fresh scan too: a merged PR never changes again). One from a fork, closed, or an open draft is left out; a merged one
+  // is in at its merged head, whatever verdicts it has. One outside the arc's repositories is in scope only when it is
   // itself on the arc's work branch in its own repository. One GitHub says is absent or denied (404, 403, 410) stays
   // outside and is refused with the rest, unless another declared PR brings its repository into scope, where its read
   // error is thrown as it is. Any other read failure (5xx, reset, timeout) is thrown as a transient failure, never
@@ -699,17 +707,23 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   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;
-    if (pr.state === 'MERGED' && !answered && passedHead(board, id, pr.headRefOid)) 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));
+  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,
-  // or judged merged sources, so a fresh scan cannot inherit that exclusion.
+  // 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 one review includes it.`)));
-  if (!prs.length && stacked.length) return { pr: [], pr_head: [], branch, review_repositories: [...reviewRepositories].sort(), stacked: stacked.map((pr) => pr.url) };
+  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 };
   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
@@ -720,7 +734,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) };
+  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 };
 }
 
 /** An arc that changed no code (a disposition, such as closing a PR with its reason): its work branch holds no commit
@@ -792,6 +806,9 @@ async function knownRepositories({ strict = false } = {}) {
  *  when the request was made. */
 export async function reviewDue(board, id, prs) {
   if (prs.length && answeredChanges(board, id)) 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));
   const unjudged = prs.filter((p) => !judgedHead(board, id, p.head));
   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);
@@ -800,7 +817,7 @@ export async function reviewDue(board, id, prs) {
       AND v.kind IN ('changes_requested', 'review_pass') AND v.id > r.id) 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'
+    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)
     ORDER BY r.id DESC LIMIT 1`).get(id);
   if (!last) return true;
@@ -817,6 +834,37 @@ export async function reviewDue(board, id, prs) {
   return false;
 }
 
+/** 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. */
+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);
+}
+
+/** 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) {
+  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');
+}
+
+/** 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';
+
 /** 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
@@ -832,6 +880,18 @@ export function answeredChanges(board, id) {
   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. */
+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 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) };
+}
+
 /** A commit's date and source tree, read once: both are immutable. Only a successful read is cached; an unread commit
  *  is unknown, never evidence of old work or of a changed tree. */
 async function commitRead({ url, head }) {
@@ -846,40 +906,71 @@ 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 cached exclusion must never hide a newly ready/reopened source from a committed review or acceptance. */
-async function requireCurrentReviewSet(board, id, urls, repositories = []) {
+/** A PR read for a committed review 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);
+};
+
+/** A cached exclusion must never hide a newly ready/reopened source from a committed review 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
+ *  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. */
+async function requireCurrentReviewSet(board, id, urls, repositories = [], { judged = false, single = false } = {}) {
   const current = await openReviewPullRequests(board, id, { fresh: true,
     repositories: [...repositories, ...urls.map(repositoryOf)] });
-  const omitted = (current?.pr ?? []).filter(url => !urls.includes(url));
+  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`);
   return current?.review_repositories ?? repositories;
 }
 
-/** The verdict already recorded on `head` of the card's PR: a changes-requested or pass that answered
- * a review request naming that head, before the next request. A head is reviewed once. */
-export function judgedHead(board, id, head) {
+/** The verdict already recorded on `head` of the card's PR: a changes-requested, a pass or a PR review's pass
+ * (`pr_review_pass`) that answered a review request naming that head, before the next request. A head is reviewed once. */
+export function judgedHead(board, id, head, of = ['pr', 'final']) {
+  return verdictOn(board, id, head, ['changes_requested', 'review_pass', 'pr_review_pass'], of);
+}
+
+/** The PR review's pass recorded on `head` (`pr_review_pass`), or null. A PR merged at such a head is settled: the
+ *  arc's final review neither names nor owes it (openReviewPullRequests). */
+export function prReviewedHead(board, id, head) {
+  return verdictOn(board, id, head, ['pr_review_pass'], ['pr']);
+}
+
+/** A pass recorded on `head` by its PR review or by the arc's final review, or null: a PR merged at such a head is
+ *  settled (openReviewPullRequests). */
+export function passedHead(board, id, head) {
+  return verdictOn(board, id, head, ['pr_review_pass', 'review_pass'], ['pr', 'final']);
+}
+
+/** 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
+ *  judges a head for a PR review or the final review. */
+const requestKindSql = (r) => `CASE
+  WHEN EXISTS (SELECT 1 FROM task_events k WHERE k.task_id = ${r}.task_id AND k.kind = 'plan_review_requested' AND k.id > ${r}.id
+    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 'plan'
+  WHEN EXISTS (SELECT 1 FROM task_events k WHERE k.task_id = ${r}.task_id AND k.kind = 'pr_review_requested' AND k.id > ${r}.id
+    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) {
   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
-    AND v.kind IN ('changes_requested', '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)
-    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') = ?)) ORDER BY v.id LIMIT 1`).get(id, head, head) ?? null;
-}
-
-/** Whether a passed review judged `head` of the card's PR: a pass that answered a review request naming that head,
- *  before the next request, and no void of that request since. Unlike judgedHead (the first verdict on a head), a head
- *  first sent back and passed in a later round counts. */
-export function passedHead(board, id, head) {
-  if (!head) return false;
-  return Boolean(board.db.prepare(`SELECT 1 FROM task_events r CROSS JOIN task_events v ON v.task_id = r.task_id
-    AND v.kind = 'review_pass' AND v.id > r.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') = ?)) LIMIT 1`).get(id, head, head));
+      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;
 }
 
 export async function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
@@ -889,6 +980,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
   const state = { required: false, ready: true, reason: null, phase: 'source' };
   try {
     assertSourceReceipt(payload);
+    if (stage === 'person') return { ...state, phase: 'person' };
     if (stage === 'completion' || stage === 'acceptance') {
       const supplied = payload.commit ?? payload.metadata?.commit;
       if (supplied) {
@@ -896,7 +988,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       }
       const candidate = stage === 'acceptance' ? reviewCandidate(board, id) : null;
       if (candidate) {
-        await requireCurrentReviewSet(board, id, candidatePullRequests(candidate).map(p => p.pr.url));
+        await requireCurrentReviewSet(board, id, candidatePullRequests(candidate).map(p => p.pr.url), [], { judged: true });
         const row = board.db.prepare("SELECT id,payload FROM task_events WHERE task_id=? AND kind='review_pass' ORDER BY id DESC LIMIT 1").get(id);
         if (!row) throw new Error('The current candidate needs its independent verdict before acceptance.');
         const voided = board.db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='review_voided' ORDER BY id DESC LIMIT 1").get(id);
@@ -905,7 +997,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
         const wanted = candidatePullRequests(candidate);
         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 readPullRequest(w.pr.url);
+          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.`);
         });
         Object.assign(state, { ...candidate, ready: true, reason: null });
@@ -918,26 +1010,38 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     // 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))
-      && !await reviewDue(board, id, urls.map((url, i) => ({ url, head: proposed[i] })))) {
-      throw new Error('Every proposed PR head already has a verdict or carries no new source; no review is due.');
+      && !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.');
     }
-    if (stage === 'request_review' || stage === 'review_verdict') state.review_repositories = await requireCurrentReviewSet(board, id, urls, payload.review_repositories ?? []);
+    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 };
+    // 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;
+    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.
-    const read = await mapGithubSources(urls, readPullRequest);
+    const read = await mapGithubSources(urls, readSource);
     const mergedOnly = urls.length && read.every(pr => pr.state === 'MERGED');
     const own = mergedOnly ? null : await repositoryWorkspace(board, id);
     if (!own && !urls.length) {
       return state;
     }
-    // A card with no repository of its own (scratch) is reviewed through the branches it registered: each unmerged PR
-    // on one of them (or on its wt/<card> branch) is read at its pushed head, and needs no checkout to exist here.
+    // A card with no repository of its own (scratch, or a plain folder holding the arc's repositories: workspace.mjs plainFolder)
+    // is reviewed through the branches it registered and the PRs it declared (declaredPullRequests, each already bounded
+    // to the arc's repositories): each unmerged PR on one of them (or on its wt/<card> branch) is read at its pushed
+    // head, and needs no checkout to exist here.
     if (!own && !mergedOnly) {
-      const registered = registeredBranches(board, id);
-      const declared = (pr) => namedWorkBranch(id, pr.headRefName) || registered.some((r) => r.branch === pr.headRefName && r.repository.toLowerCase() === repositoryOf(pr.url).toLowerCase());
+      const registered = registeredBranches(board, id), key = (url) => `${repositoryOf(url).toLowerCase()}#${numberOf(url)}`;
+      const recorded = new Set(declaredPullRequests(board.db, id).map((source) => key(source.url)));
+      const declared = (pr) => recorded.has(key(pr.url)) || namedWorkBranch(id, pr.headRefName) || registered.some((r) => r.branch === pr.headRefName && r.repository.toLowerCase() === repositoryOf(pr.url).toLowerCase());
       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}`)));
     }
@@ -956,8 +1060,8 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     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.
-      if (!await reviewDue(board, id, prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw new Error('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.');
+      // 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.');
@@ -966,7 +1070,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       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.');
     }
-    Object.assign(state, { ...prs[0], ready: true, reason: null, ...(prs.length > 1 ? { prs } : {}) });
+    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) });
     if (error?.code) Object.assign(state, { code: error.code, retryable: error.code === 'GITHUB_BUDGET' });