@volter/supercode-orchestrator 0.5.222 → 0.5.223

package/board/ci.mjs

@@ -7,7 +7,7 @@ import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { branchCheckouts, checkoutOf, isLocalWorkspace, isWorkspacePath, resolveWorkspace, plainWorkspace } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
-import { githubFetch, githubDiscovery } from './github-rest.mjs';
+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
@@ -202,12 +202,22 @@ const pullRequest = (repository, p) => ({ url: p.html_url, number: p.number, sta
 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 });
-// Discovery is advisory. Already-merged sources are retained for an hour, others for a minute. Every transition
-// still uses readPullRequest and the fresh source checks in inspectCompletionEvidence, which bypass this cache and reads its current head.
+/** The advisory observation discovery already holds under `key`, or null (no wire attempt). */
+const heldRead = async (key) => githubDiscoveryHeld(await discoveryIdentity(key));
+const pullRequestKey = (url) => `pr:${repositoryOf(url).toLowerCase()}:${numberOf(url)}`;
+// Discovery is advisory. A merged source is final (its head, base and state never change again) and is retained for a
+// week; a closed one for six hours (a reopened PR is in its repository's open list, which discovery reads first); an
+// open one for a minute. Every transition still uses readPullRequest and the fresh source checks in
+// inspectCompletionEvidence, which bypass this cache and read its current head.
+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);
 export async function discoverPullRequest(url, { fresh = false } = {}) {
-  return discoveryRead(`pr:${repositoryOf(url).toLowerCase()}:${numberOf(url)}`, 60_000, async () => pullRequest(repositoryOf(url),
+  const key = pullRequestKey(url);
+  return 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' ? 3600_000 : 60_000 });
+  { fresh, ttlOf: pr => pr.state === 'MERGED' ? spread(MERGED_TTL, key) : pr.state === 'CLOSED' ? spread(CLOSED_TTL, key) : 60_000 });
 }
 
 /**
@@ -362,14 +372,16 @@ async function recreatedWorktree(workspace, resolved) {
 
 /** 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 } = {}) {
+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 });
+  return discoveryRead(`history:${key}`, 900_000, read, { fresh, ttlOf: () => ttl });
 }
 
 async function branchCheckout(board, id, repository, branch) {
@@ -399,24 +411,79 @@ function registeredBranches(board, id, sources = arcSources(board.db, id)) {
     if (!row.workspace_anchor || /^(\/|~|[A-Za-z]:[\\/])/.test(row.workspace_anchor)) continue;
     out.push({ repository: row.workspace_anchor.replace(/^github\.com\//i, '').replace(/\.git$/, ''), branch: row.branch_name });
   }
-  // and each repository and branch the arc declared as its own (arcSources, or the declaration about to replace it)
+  // and each repository and branch the arc declared as its own (arcSources, or the set with a declaration about to be added)
   for (const declared of sources) if (!out.some((r) => r.repository.toLowerCase() === declared.repository.toLowerCase() && r.branch === declared.branch)) out.push(declared);
   return out;
 }
 
-/** The repositories and branches the arc itself declares it changes: its latest `comment --source owner/repo:branch`
- *  declaration (engine.comment), the arc's complete set. A multi-repository arc carries them on the arc card, and its
+/** The arc's declarations of one kind, oldest first, as `{ id, items }`: `sources` (its `comment --pr` PRs) or
+ *  `branches` (its `comment --source` repositories and branches). Each declaration adds to the ones before it, from the
+ *  latest that declared none (`--pr none`, `--source none`): an arc declares its PRs and branches as it opens them, on
+ *  any run, and every one stays the arc's (t_918cc86e's review requests e73756 and e73845 named only the PR of the
+ *  latest declaration, dropping runhuman-2 #552, #553, #555, #556, volter-ai/volter #135 and open-autonomy #933). */
+function declarationsOf(db, id, field, adding = null) {
+  const rows = field === 'branches'
+    ? db.prepare("SELECT id, payload FROM task_events WHERE task_id=? AND kind='commented' AND json_valid(payload) AND json_type(payload,'$.branches')='array' ORDER BY id").all(id)
+    : db.prepare("SELECT id, payload FROM task_events WHERE task_id=? AND kind='commented' AND json_valid(payload) AND json_type(payload,'$.sources')='array' ORDER BY id").all(id);
+  const declarations = rows.map((row) => ({ id: row.id, items: JSON.parse(row.payload)[field] }));
+  if (adding) declarations.push({ id: Infinity, items: adding });
+  let from = 0;
+  declarations.forEach((declaration, i) => { if (!declaration.items.length) from = i + 1; });
+  return declarations.slice(from);
+}
+
+/** Each repository and branch the arc declared (`branches`), at its latest declaration (`at`, that declaration's id). */
+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 });
+  }
+  return out;
+}
+
+/** The repositories and branches the arc itself declares it changes: every `comment --source owner/repo:branch`
+ *  declaration (engine.comment) since the latest `--source none`, each adding to the ones before it; with `adding`, the
+ *  set once that declaration (an empty one clears) is added. A multi-repository arc carries them on the arc card, and its
  *  review discovers and accepts PRs from them with no subtask registered in that repository (VO-2858, VO-2860). */
-export function arcSources(db, id) {
-  const row = db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_valid(payload) AND json_type(payload,'$.branches')='array' ORDER BY id DESC LIMIT 1").get(id);
-  let declared = [];
-  try { declared = row ? JSON.parse(row.payload).branches : []; } catch { /* an unreadable declaration names none */ }
-  return declared.filter((b) => typeof b?.repository === 'string' && typeof b?.branch === 'string').map((b) => ({ repository: b.repository, branch: b.branch }));
+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}`));
+}
+
+/** 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). */
+export function declaredPullRequests(db, id) {
+  const latest = new Map();
+  for (const declaration of declarationsOf(db, id, 'sources')) for (const source of declaration.items) {
+    if (typeof source?.url !== 'string') continue;
+    latest.delete(source.url);
+    latest.set(source.url, { url: source.url, head: source.head });
+  }
+  return [...latest.values()];
 }
 
 /** The arc's repositories, the only ones its `--pr` declarations may name (ADR 0003): the card's own workspace's and each
- *  registered branch's (its tasks' and its `--source` declaration; `sources`, a declaration about to replace that one,
- *  stands in for it). Answers them lower-cased, with the workspace and registered branches they were read from. */
+ *  registered branch's (its tasks' and its `--source` declarations; `sources`, the set with a declaration about to be
+ *  added, stands in for them). Answers them lower-cased, with the workspace and registered branches they were read from. */
 export async function arcRepositories(board, id, sources = arcSources(board.db, id)) {
   const own = await repositoryWorkspace(board, id);
   const registered = registeredBranches(board, id, sources).map(r => ({ ...r, repository: r.repository.toLowerCase() }));
@@ -477,12 +544,12 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   // workspace, its declared sources, its tasks' registered branches) and, here, each repository where the board finds the
   // arc's own work branch (a wt/<card> PR in a sibling repository, discovered or declared). engine.comment refuses a PR
   // outside the first three when it is declared; a declaration still outside all of them (stored before that refusal,
-  // or left outside later by a --source change, a cancelled or retargeted task, or a changed workspace) is refused here,
+  // or left outside later by --source none, a cancelled or retargeted task, or a changed workspace) is refused here,
   // by every review request, verdict and acceptance, as `undeclared`, naming the PR and its repository, never dropped
   // (volter-ai/volter#134 left four t_ef2aa6ce review requests with no word). A PR the review already includes is never refused.
-  const declaration = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_type(payload,'$.sources')='array' ORDER BY id DESC LIMIT 1").get(id);
-  const declared = (declaration ? JSON.parse(declaration.payload).sources : []).filter(source => typeof source?.url === 'string');
-  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> (with every other source the arc changes), or declare the arc's PRs again without it (--pr none declares none).`)));
+  // 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 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);
@@ -506,6 +573,30 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   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.
+  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);
+  // what is left is read on later rounds, and until then the set is incomplete and says so. A fresh or strict scan reads
+  // everything.
+  let admitted = 0, deferred = 0, spent = false;
+  const admit = async (key) => {
+    if (fresh || strict || await heldRead(key)) return true;
+    if (admitted < NEW_READS_PER_ROUND) {
+      if (!spent && githubDiscoveryUsed() >= GITHUB_DISCOVERY_ATTEMPTS * FILL_SHARE) spent = true;
+      if (!spent || admitted === 0) { admitted += 1; return true; }
+    }
+    deferred += 1;
+    return false;
+  };
+  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 groups = await readTogether(repositoriesToRead, async repository => {
     const prs = [];
@@ -513,8 +604,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     // Advisory discovery is shared. Before a move, refresh the full set, including previously excluded PRs.
     let list;
     try {
-      const items = await 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 items = await openList(repository);
       // Empty unrelated repositories need no default metadata. Keep that lookup separate from the shared list,
       // so a card declaring the repository can acquire it without listing the same open PRs again.
       const needsDefault = items.length > 0 || hasWorkBranches;
@@ -528,6 +618,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     }
     // Include excluded drafts/other bases 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);
     // A repository holding the arc's own work branch is the arc's: a declared PR there is in scope.
     if (list.items.some(pr => !pr.isCrossRepository && mine(repository, pr.headRefName))) workRepositories.add(repository);
@@ -552,7 +643,11 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     // A judged merged head is passed over, except while an answered changes-requested verdict makes it due again.
     const histories = await readTogether(historical, async headBranch => {
       if (headBranch === list.defaultBranch || list.items.some(pr => pr.headRefName === headBranch)) return [];
-      return (await mergedBranchPullRequests(repository, headBranch, { fresh })).filter(pr =>
+      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 && (answered || !judgedHead(board, id, pr.headRefOid)));
     });
@@ -562,15 +657,31 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     return prs;
   });
   const prs = groups.flat();
-  // Each declared PR discovery did not find is read and 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 from a fork, closed, or
-  // an open draft is left out. 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 refused as undeclared.
+  // 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
+  // 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
+  // refused as undeclared.
   const inScope = new Set([...arcScope, ...workRepositories]);
   const sources = declared.filter(source => !prs.some(known => known.url === source.url));
+  // A declared PR's repository discovery did not list is listed here, once, on that shared list, so its open PRs are
+  // looked up there instead of each being read every round; one that cannot be listed leaves its PRs to be read.
+  const unlisted = [...new Set(sources.map(source => repositoryOf(source.url).toLowerCase()))].filter(r => !repositoriesToRead.includes(r));
+  await readTogether(unlisted, async repository => {
+    try { for (const pr of await openList(repository)) openSeen.set(openKey(pr.url), pr); }
+    catch { /* read one by one below */ }
+  });
   const read = await readTogether(sources, async source => {
+    const listed = openSeen.get(openKey(source.url));
+    if (listed) return listed;
+    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 };
     const reading = fresh ? readPullRequest(source.url) : discoverPullRequest(source.url);
     if (inScope.has(repositoryOf(source.url).toLowerCase())) return reading;
     try { return await reading; } catch (error) {
@@ -578,14 +689,17 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
       return { unread: error };
     }
   });
-  read.forEach((pr, i) => { if (!pr.unread && !pr.isCrossRepository && mine(repositoryOf(sources[i].url).toLowerCase(), pr.headRefName)) inScope.add(repositoryOf(sources[i].url).toLowerCase()); });
-  const outside = outsideArcRepositories(sources.map(source => source.url), inScope);
+  read.forEach((pr, i) => { if (!pr.unread && !pr.deferred && !pr.isCrossRepository && mine(repositoryOf(sources[i].url).toLowerCase(), pr.headRefName)) inScope.add(repositoryOf(sources[i].url).toLowerCase()); });
+  const outside = outsideArcRepositories(sources.filter((_, i) => !read[i].deferred).map(source => source.url), inScope);
   if (outside.length) throw undeclared(outside);
   // Every source left unread is now in scope: its own read error is the answer.
   const unread = read.find(pr => pr.unread);
   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;
+    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 });
   }
   // Retain scope even when all matching PRs are excluded drafts/other bases,
@@ -755,6 +869,19 @@ export function judgedHead(board, id, head) {
       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.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));
+}
+
 export async function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
   return withFreshReviewReads(() => inspectCurrentCompletionEvidence(board, id, entry, payload, stage));
 }
@@ -812,7 +939,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       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 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} (with every other source the arc changes)`)));
+      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.

package/board/cli.mjs

@@ -116,7 +116,7 @@ The board's verbs, with their flags:
   set <id> <assignee|machine|model|every|reviewer> <value|none> [--provider] [--ids ...]   assign <id> <profile|none>   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
   reassign <id> --agent AGENT [--role implementer]   (moves a card role's assignment to another agent; sessions keep their identity)
   claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
-  comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)... | --pr none] [--source owner/repo:branch]...   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
+  comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)... | --pr none] [--source owner/repo:branch... | --source none]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   attachment-read <id> <attachment-id> [--offset N --length N --version V]   bounded base64/metadata JSON, including through --at
   complete <id>... [--result] [--summary] [--metadata JSON] [--commit SHA]   edit <id> --result [--summary] [--metadata]
   finish <id> --result TEXT   (when declared: end your completed attempt; the board selects review)
@@ -164,8 +164,8 @@ And:
 
   specify <id> --workspace dir:<repository> --branch NAME: the manager retargets a stopped card without replacing its history.
   specify <id> --workspace … --machine M: declares the workspace on M and moves the card there, never asking the machine it leaves.
-  comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the arc's repositories (its workspace, its declared sources, its tasks'), each followed at its current head; the latest declaration replaces the previous one, and --pr none alone replaces it with none. This records evidence; only the board starts its review.
-  comment <arc> TEXT --source owner/repo:branch...: the arc's implementer or the manager declares every repository and branch the arc changes, on the arc itself; its review discovers PRs from them and accepts --pr declarations in them, with no task registered there. The latest declaration is the complete set.
+  comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the arc's repositories (its workspace, its declared sources, its tasks'), each followed at its current head; each declaration adds to the earlier ones, on any run, and --pr none alone clears them. This records evidence; only the board starts its review.
+  comment <arc> TEXT --source owner/repo:branch...: the arc's implementer or the manager declares every repository and branch the arc changes, on the arc itself; its review discovers PRs from them and accepts --pr declarations in them, with no task registered there. Each declaration adds to the earlier ones, and --source none alone clears them.
   request-review <id> (--pr URL --pr-head SHA)...: hand over every open PR the arc changed, each at its pushed head; one review covers them all.
   request-state <id> --state done (--reviewed-sha SHA)...: record the verdict on every requested PR head.
   request-state <id>... --state STATE --reason REASON: request several decisions in one retained manager mail.

package/board/engine.mjs

@@ -287,6 +287,14 @@ export function createCard(board, spec) {
       spec.branch ?? null, tags[0] ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
       spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
+    // Only cards are numbered: a task (--subtask-of) is a row under its card, as a checklist item is, with no number of
+    // its own (the account manager's ruling, m-83f821fe). The store numbers every inserted row (store.mjs
+    // layOutNumbers); a task's number is taken back in this transaction, and the sequence with it when it was the last.
+    if (arc) {
+      const taken = numberOf(db, id);
+      run(db, `DELETE FROM ${CARD_NUMBERS} WHERE task_id = ?`, id);
+      if (taken != null) run(db, 'UPDATE sqlite_sequence SET seq = ? WHERE name = ? AND seq = ?', taken - 1, CARD_NUMBERS, taken);
+    }
     const readableId = allocateReadableId(db, title, spec.readableId ?? null, id);
     run(db, 'UPDATE tasks SET readable_id=? WHERE id=?', readableId, id);
     const handle = cardHandle(boardKey(board.root, board.slug), numberOf(db, id));
@@ -787,15 +795,18 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
   let sources, branches;
   // The repositories and branches an arc changes are the arc's own: declared on it (`--source owner/repo:branch`, each
   // repository the arc changes), never registered as a subtask's workspace to be reviewed (VO-2858 had to register
-  // volter-org and runhuman-2 on its tasks, VO-2860). The latest declaration is the arc's complete set.
+  // volter-org and runhuman-2 on its tasks, VO-2860). Each declaration adds to the earlier ones (ci.arcSources), and
+  // `--source none` alone clears them (a declared repository that can no longer be listed leaves the arc this way).
   if (source != null) {
     const named = [].concat(source).map((item) => String(item).trim());
-    branches = named.map((item) => {
+    const none = named.length === 1 && named[0] === 'none';
+    if (!none && named.includes('none')) throw new Error('--source none clears the arc\'s declared sources and is given alone; declare sources in a comment of their own.');
+    branches = none ? [] : named.map((item) => {
       const found = /^(?:https:\/\/github\.com\/|github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?:([^\s:]+)$/.exec(item);
       if (!found) throw new Error(`Declare each source as owner/repository:branch, not ${JSON.stringify(item)}.`);
       return { repository: found[1], branch: found[2] };
     });
-    if (!branches.length) throw new Error('Declare at least one source as owner/repository:branch.');
+    if (!none && !branches.length) throw new Error('Declare at least one source as owner/repository:branch, or clear them with --source none alone.');
     if (new Set(branches.map((b) => `${b.repository.toLowerCase()}:${b.branch}`)).size !== branches.length) throw new Error('Declare each source once.');
     const arc = one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of;
     if (arc) throw new Error(`${id} is a task of ${arc}: an arc's sources are declared on the arc (comment ${arc} … --source owner/repository:branch).`);
@@ -803,9 +814,10 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
   }
   if (pr != null || pr_head != null) {
     const urls = [].concat(pr ?? []), heads = [].concat(pr_head ?? []);
-    // `--pr none` alone declares no PR: the arc's declaration becomes the empty set (a stored declaration no longer in
-    // the arc's repositories is cleared this way when no PR in them remains to declare in its place).
+    // Each declaration adds its PRs to the earlier ones (ci.declaredPullRequests). `--pr none` alone clears them (a
+    // stored declaration no longer in the arc's repositories leaves this way, before the rest are declared again).
     const none = urls.length === 1 && urls[0] === 'none' && !heads.length;
+    if (!none && urls.includes('none')) throw new Error('--pr none clears the arc\'s declared PRs and is given alone, with no --pr-head; declare PRs in a comment of their own.');
     if (!none && (!urls.length || urls.length !== heads.length)) throw new Error('Record every PR with --pr URL --pr-head SHA, one full head per URL, or declare none with --pr none alone.');
     if (new Set(urls).size !== urls.length) throw new Error('Record each PR once.');
     sources = none ? [] : urls.map((url, i) => {
@@ -815,10 +827,10 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
     // Only the card's own implementer or the board's manager declares its sources; the author text is not identity.
     if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw new Error(`Only ${id}'s implementer or the manager records its PR sources.`);
     // A declared PR is in one of the arc's repositories (its workspace, its declared sources, its tasks'; a `--source`
-    // in this same comment replaces the arc's declared sources): the review reads no other, so one outside them is
+    // in this same comment counts with the arc's declared sources): the review reads no other, so one outside them is
     // refused here and nothing is stored, never kept to be dropped from every review request (t_ef2aa6ce). The board's
     // own records are read first; the workspace is resolved (its daemon, its machine, git) only for a URL still outside.
-    const declaredSources = branches ?? arcSources(board.db, id);
+    const declaredSources = arcSources(board.db, id, branches);
     const urlsOf = (list) => list.map((s) => s.url);
     let outside = outsideArcRepositories(urlsOf(sources), recordedArcRepositories(board, id, declaredSources));
     if (outside.length) {
@@ -827,7 +839,7 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
       catch (error) { throw new Error(`${id}'s workspace could not be read to check the repository of ${outside.map((o) => o.url).join(', ')} (a --pr declaration is checked against the arc's repositories): ${error.message}. Nothing was recorded.`); }
       outside = outsideArcRepositories(urlsOf(outside), repositories);
     }
-    if (outside.length) throw new Error(outside.map(({ url, repository }) => `${url} is in ${repository}, which is not one of ${id}'s repositories (its workspace, its declared sources, its tasks'): declare ${repository} first with comment ${id} "<why>" --source ${repository}:<branch> (with every other source the arc changes), then record its PRs. Nothing was recorded.`).join(' '));
+    if (outside.length) throw new Error(outside.map(({ url, repository }) => `${url} is in ${repository}, which is not one of ${id}'s repositories (its workspace, its declared sources, its tasks'): declare ${repository} first with comment ${id} "<why>" --source ${repository}:<branch>, then record its PRs. Nothing was recorded.`).join(' '));
   }
   const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body, ...(sources ? { sources } : {}), ...(branches ? { branches } : {}) } });
   return result.commentId;

package/board/github-rest.mjs

@@ -46,6 +46,20 @@ const discoveryPending = () => Object.assign(new Error('GitHub discovery is alre
 /** Advisory observations survive command/owner restarts. Fresh transition reads never consume a cached value,
  * but publish their successful observation for discovery. A short transaction claims each advisory read; no
  * transaction spans I/O and a different process defers rather than waiting or duplicating its wire attempts. */
+/** How many discovery reads this home started in the last hour, of its GITHUB_DISCOVERY_ATTEMPTS: every arc's, so a
+ *  caller filling a cache it can defer reads by the home's use, not only its own. */
+export function githubDiscoveryUsed() {
+  return connection().prepare("SELECT COUNT(*) AS n FROM github_attempts WHERE started_at>? AND purpose='discovery'").get(Date.now() - HOUR).n;
+}
+
+/** The live advisory observation kept for `identity`, or null: read without a claim or a wire attempt, so a caller can
+ *  tell a read it already holds from one that spends the home's budget. */
+export function githubDiscoveryHeld(identity) {
+  const key = createHash('sha256').update(identity).digest('hex');
+  const held = connection().prepare('SELECT value, until_at FROM github_discovery WHERE key=?').get(key);
+  return held && held.until_at > Date.now() && held.value != null ? JSON.parse(held.value) : null;
+}
+
 export async function githubDiscovery(identity, ttl, read, { fresh = false, ttlOf = () => ttl, cacheErrors = true } = {}) {
   const key = createHash('sha256').update(identity).digest('hex');
   const localKey = `${pathOf()}\0${key}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.222",
+  "version": "0.5.223",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -36,10 +36,10 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.379",
+    "@volter/supercode-teams": "^0.3.380",
     "@volter/supercode-terminal": "^0.3.12",
     "@volter/supercode-harness-sdk": "^0.3.106",
-    "@volter/teams": "0.2.105",
+    "@volter/teams": "0.2.106",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },