@volter/supercode-orchestrator 0.5.200 → 0.5.201

package/README.md

@@ -42,6 +42,27 @@ Rules the codec keeps (enforced in Rust, observed here):
   since import (UNI-22); it copies the store byte for byte when they did not.
 - Files the IR does not model are never touched by `save` and are carried by path on a migration.
 
+## Board GitHub REST receipts
+
+`supercode workflow github-usage --since 1h --json` reads this user's local
+`github-rest.sqlite` in `SUPERCODE_HOME` (default: `~/.config/supercode`, respecting
+`XDG_CONFIG_HOME`). It needs neither a running board nor a GitHub request. It
+groups retained wire attempts by caller and endpoint, includes their purposes
+and outcomes, and shows the latest 32 response-header receipts. Unknown transport
+completion remains counted. Tokens and response bodies are not retained.
+
+Board discovery caches advisory reads while waiting. Review requests, verdicts
+and acceptance refresh the complete source set, including previously draft or
+closed declared sources, and validate its current heads. An unread set defers
+the action. Unread commit dates also defer eligibility and are never cached as
+old work. Merge validation still reads the current head. Every request page, retry, redirect and merge PUT
+reserves its own attempt. All processes and credentials sharing this supercode
+home share a rolling-hour ceiling of 1,200 attempts, including at most 600
+discovery attempts. Endpoint exhaustion/Retry-After also defers subsequent work.
+A deferred source remains unknown, with its reason; it is not an empty success.
+Other homes and external GitHub clients are outside this ledger and ceiling.
+See [F104 evidence and qualification limits](../../docs/evidence/f104-github-2026-10-14.md).
+
 ## Local native session recovery
 
 `supercode sessions recover --once --retry-after 300` runs a bounded opt-in

package/board/ci.mjs

@@ -6,6 +6,7 @@ import { dirname, join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
 import { branchCheckouts, checkoutOf, isLocalWorkspace, resolveWorkspace, plainWorkspace } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
+import { githubFetch } 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
@@ -20,12 +21,12 @@ async function githubToken() {
 }
 /** One GitHub REST read (`all`: every page of a list). The token is the environment's, else gh's stored login: a failed
  *  read of the login is not kept, and a login token GitHub refuses (401, rotated or revoked) is read again once. */
-async function github(path, all = false) {
+async function github(path, all = false, { purpose = 'validation' } = {}) {
   const read = async () => {
     const token = await githubToken();
     let url = githubBase() + path, out = [];
     for (let page = 0; url && page < 10; page += 1) {
-      const r = await fetch(url, { headers: githubHeaders(token), signal: AbortSignal.timeout(30_000) });
+      const r = await githubFetch(url, { headers: githubHeaders(token), signal: AbortSignal.timeout(30_000) }, { purpose });
       if (!r.ok) return { status: r.status, error: `GitHub ${r.status} for ${path}: ${(await r.text()).slice(0, 300)}` };
       const body = await r.json();
       if (!all) return { body };
@@ -36,10 +37,10 @@ async function github(path, all = false) {
   };
   const started = performance.now();
   let result;
-  try { result = await read(); } catch (error) { result = { error: String(error.message) }; }
-  if (result.status === 401 && !(process.env.GH_TOKEN || process.env.GITHUB_TOKEN) && loginToken) { loginToken = null; try { result = await read(); } catch (error) { result = { error: String(error.message) }; } }
+  try { result = await read(); } catch (error) { result = { error: String(error.message), cause: error }; }
+  if (result.status === 401 && !(process.env.GH_TOKEN || process.env.GITHUB_TOKEN) && loginToken) { loginToken = null; try { result = await read(); } catch (error) { result = { error: String(error.message), cause: error }; } }
   noteStep('github read', performance.now() - started);
-  if (result.error) throw new Error(`GitHub: ${result.error.trim().slice(-500)}`);
+  if (result.error) throw Object.assign(new Error(`GitHub: ${result.error.trim().slice(-500)}`, { cause: result.cause }), result.cause?.code ? { code: result.cause.code } : {});
   return result.body;
 }
 const repositoryOf = (url) => new URL(url).pathname.split('/').slice(1, 3).join('/');
@@ -48,6 +49,22 @@ const numberOf = (url) => Number(new URL(url).pathname.split('/')[4]);
 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) });
 const readPullRequest = async (url) => pullRequest(repositoryOf(url), await github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`));
+// Discovery is advisory. Already-merged sources are retained for an hour, others for a minute. Every transition
+// still uses readPullRequest/verifyPullRequest above/below, which bypass this cache and reads its current head.
+const discoveredPullRequests = new Map();
+export async function discoverPullRequest(url) {
+  const key = `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${url}`;
+  let held = discoveredPullRequests.get(key);
+  if (held && Date.now() < held.until) return held.pending;
+  if (discoveredPullRequests.size >= 4096 && !held) discoveredPullRequests.delete(discoveredPullRequests.keys().next().value);
+  held = { until: Date.now() + 60_000 };
+  held.pending = github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`, false, { purpose: 'discovery' })
+    .then(body => { const pr = pullRequest(repositoryOf(url), body); held.until = Date.now() + (pr.state === 'MERGED' ? 3600_000 : 60_000); return pr; });
+  // Failed reads stay failed for a minute; no cached empty source or invented successful head.
+  void held.pending.catch(() => {});
+  discoveredPullRequests.set(key, held);
+  return held.pending;
+}
 
 /**
  * Merge a reviewed PR at the head its review judged, and only there: GitHub refuses the merge when the PR's head is no
@@ -63,7 +80,7 @@ export async function mergeReviewedPullRequest(url, reviewed) {
   const token = await githubToken();
   let answer;
   try {
-    const r = await fetch(`${githubBase()}/repos/${repositoryOf(url)}/pulls/${numberOf(url)}/merge`, { method: 'PUT', headers: githubHeaders(token, { 'content-type': 'application/json' }), body: JSON.stringify({ sha: reviewed, merge_method: 'merge' }), signal: AbortSignal.timeout(60_000) });
+    const r = await githubFetch(`${githubBase()}/repos/${repositoryOf(url)}/pulls/${numberOf(url)}/merge`, { method: 'PUT', headers: githubHeaders(token, { 'content-type': 'application/json' }), body: JSON.stringify({ sha: reviewed, merge_method: 'merge' }), signal: AbortSignal.timeout(60_000) }, { purpose: 'mutation' });
     const text = await r.text();
     answer = { status: r.status, body: (() => { try { return JSON.parse(text); } catch { return { message: text.slice(0, 300) }; } })() };
   } catch (error) { throw new Error(`GitHub merge: ${String(error.message).slice(-300)}`); }
@@ -165,20 +182,29 @@ async function recreatedWorktree(workspace, resolved) {
 
 const pullRequestLists = new Map();
 const mergedPullRequestLists = new Map();
+// Keep in-flight and failed list reads too, with room for the registered branch set. History changes rarely;
+// ordinary open work is discovered by the repository's open-PR listing.
+async function discoveryList(cache, key, ttl, read) {
+  key = `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${key}`;
+  let held = cache.get(key);
+  if (held && Date.now() < held.until) return held.pending;
+  if (cache.size >= 4096 && !held) cache.delete(cache.keys().next().value);
+  held = { until: Date.now() + ttl };
+  held.pending = Promise.resolve().then(read).catch(error => { held.until = Date.now() + 60_000; throw error; });
+  void held.pending.catch(() => {}); cache.set(key, held);
+  return held.pending;
+}
 
 /** 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) {
+async function mergedBranchPullRequests(repository, branch, { fresh = false } = {}) {
   const key = `${repository}:${branch}`;
-  let list = mergedPullRequestLists.get(key);
-  if (!list || Date.now() - list.at >= 60_000) {
+  const read = async () => {
     const head = encodeURIComponent(`${repository.split('/')[0]}:${branch}`);
-    const items = (await github(`/repos/${repository}/pulls?state=closed&head=${head}&per_page=100`, true))
+    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));
-    if (mergedPullRequestLists.size >= 64) mergedPullRequestLists.delete(mergedPullRequestLists.keys().next().value);
-    list = { at: Date.now(), items }; mergedPullRequestLists.set(key, list);
-  }
-  return list.items;
+  };
+  return fresh ? read() : discoveryList(mergedPullRequestLists, key, 900_000, read);
 }
 
 async function branchCheckout(board, id, repository, branch) {
@@ -230,7 +256,7 @@ export function declaredWorkBranches(db, id) {
  *  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. */
-export async function openReviewPullRequests(board, id) {
+export async function openReviewPullRequests(board, id, { fresh = false } = {}) {
   const own = await repositoryWorkspace(board, id);
   const registered = registeredBranches(board, id);
   if (!own && !registered.length) return null;
@@ -242,19 +268,19 @@ export async function openReviewPullRequests(board, id) {
   const mine = (repository, head) => (repository === ownRepository && head === branch) || namedWorkBranch(id, head)
     || registered.some((r) => r.repository === repository && r.branch === head);
   const prs = [];
-  for (const repository of new Set([ownRepository, ...registered.map((r) => r.repository), ...(await knownRepositories())].filter(Boolean))) {
-    // Discovery is shared per repository for one minute; each selected PR/head is re-read before it authorizes a move.
-    let list = pullRequestLists.get(repository);
-    if (!list || Date.now() - list.at >= 60_000) {
-      let items = [], defaultBranch = null;
-      try {
-        items = (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true)).map((p) => pullRequest(repository, p));
-        defaultBranch = items.find(pr => pr.defaultBranch)?.defaultBranch ?? (await github(`/repos/${repository}`)).default_branch;
-      }
-      catch (error) { if (repository === ownRepository || registered.some((r) => r.repository === repository)) throw error; } // another repository unreachable here is not this arc's
-      list = { at: Date.now(), items, defaultBranch };
-      if (pullRequestLists.size >= 64) pullRequestLists.delete(pullRequestLists.keys().next().value);
-      pullRequestLists.set(repository, list);
+  for (const repository of new Set([ownRepository, ...registered.map((r) => r.repository), ...(await knownRepositories({ fresh }))].filter(Boolean))) {
+    // Advisory discovery is shared. Before a move, refresh the full set, including previously excluded PRs.
+    let list;
+    try {
+      const read = async () => {
+        const items = (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' })).map((p) => pullRequest(repository, p));
+        const defaultBranch = items.find(pr => pr.defaultBranch)?.defaultBranch ?? (await github(`/repos/${repository}`, false, { purpose: fresh ? 'validation' : 'discovery' })).default_branch;
+        return { items, defaultBranch };
+      };
+      list = fresh ? await read() : await discoveryList(pullRequestLists, repository, 300_000, read);
+    } catch (error) {
+      if (fresh || repository === ownRepository || registered.some(r => r.repository === repository)) throw error;
+      continue; // An unread sibling stays unread: do not cache an empty successful result.
     }
     // The repository's default branch is not a work branch, declared or checked out (a card working in a `dir` on main).
     if (repository === ownRepository && branch) {
@@ -273,7 +299,7 @@ export async function openReviewPullRequests(board, id) {
     for (const headBranch of historical) {
       if (headBranch === list.defaultBranch) continue;
       if (list.items.some(pr => pr.headRefName === headBranch)) continue;
-      for (const pr of await mergedBranchPullRequests(repository, headBranch)) {
+      for (const pr of await mergedBranchPullRequests(repository, headBranch, { fresh })) {
         if (!pr.isCrossRepository && pr.headRefName === headBranch && pr.headRefName !== pr.defaultBranch
           && pr.baseRefName === pr.defaultBranch && !judgedHead(board, id, pr.headRefOid)
           && !prs.some(known => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid });
@@ -288,7 +314,7 @@ export async function openReviewPullRequests(board, id) {
   const repositories = new Set([ownRepository, ...registered.map((r) => r.repository)].filter(Boolean).map((r) => r.toLowerCase()));
   for (const source of declaration ? JSON.parse(declaration.payload).sources : []) {
     if (!repositories.has(repositoryOf(source.url).toLowerCase()) || prs.some((known) => known.url === source.url)) continue;
-    const pr = await readPullRequest(source.url);
+    const pr = await (fresh ? readPullRequest(source.url) : discoverPullRequest(source.url));
     if (pr.isCrossRepository || !['OPEN', 'MERGED'].includes(pr.state) || (pr.state === 'OPEN' && pr.isDraft)) continue;
     if (!prs.some((known) => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid });
   }
@@ -325,14 +351,16 @@ export async function noCodeChange(board, id) {
     const remote = (await run('git', ['ls-remote', 'origin', `refs/heads/${branch}`], own)).split(/\s+/)[0];
     if (remote) await run('git', ['merge-base', '--is-ancestor', remote, base], own);
     const owner = repository.split('/')[0];
+    // An empty PR history can authorize a no-code review; keep this validation fresh too.
     if ((await github(`/repos/${repository}/pulls?state=all&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=1`)).length) return null;
     return { pr: [], pr_head: [], branch, no_code: { repository, branch, base, branch_head: remote || null } };
-  } catch { return null; }
+  } catch (error) { if (error.code === 'GITHUB_BUDGET') throw error; return null; }
 }
 
 /** The repositories this machine keeps a checkout of. */
-async function knownRepositories() {
-  try { return [...new Set((await branchCheckouts(null, '*')).map((row) => row.repository))]; } catch { return []; }
+async function knownRepositories({ fresh = false } = {}) {
+  try { return [...new Set((await branchCheckouts(null, '*')).map((row) => row.repository))]; }
+  catch (error) { if (fresh) throw error; return []; }
 }
 
 /** Whether the arc's open PRs (`[{ url, head }]`) call for its review: some head no verdict judged that is new work.
@@ -358,22 +386,28 @@ export async function reviewDue(board, id, prs) {
   const judged = candidatePullRequests(JSON.parse(last.payload)?.ci);
   if (judged.some((j) => prs.some((p) => p.url === j.pr.url && p.head !== j.commit))) return true;
   if (last.verdict === 'review_pass' && unjudged.some((p) => !judged.some((j) => j.pr.url === p.url))) return true;
-  for (const p of unjudged) if (((await commitTime(p)) ?? 0) > Number(last.verdict_at)) return true;
+  for (const p of unjudged) if ((await commitTime(p)) > Number(last.verdict_at)) return true;
   return false;
 }
 
 const commitTimes = new Map();
-/** When a PR's head was committed (seconds), read from GitHub once per head; null when it cannot be read. */
+/** Cache successful immutable commit dates only. An unread date is unknown, never evidence of old work. */
 async function commitTime({ url, head }) {
-  if (commitTimes.has(head)) return commitTimes.get(head);
-  let at = null;
-  try {
-    at = Math.floor(Date.parse((await github(`/repos/${repositoryOf(url)}/commits/${head}`)).commit.committer.date) / 1000) || null;
-  } catch { /* unreadable: not counted as new */ }
-  commitTimes.set(head, at);
+  const key = `${githubBase()}\0${repositoryOf(url)}\0${head}`;
+  if (commitTimes.has(key)) return commitTimes.get(key);
+  const at = Math.floor(Date.parse((await github(`/repos/${repositoryOf(url)}/commits/${head}`)).commit?.committer?.date) / 1000);
+  if (!Number.isFinite(at)) throw new Error(`GitHub commit date for ${url} at ${head} is unreadable; review eligibility is unknown`);
+  commitTimes.set(key, at);
   return at;
 }
 
+/** A cached exclusion must never hide a newly ready/reopened source from a committed review or acceptance. */
+async function requireCurrentReviewSet(board, id, urls) {
+  const current = await openReviewPullRequests(board, id, { fresh: true });
+  const omitted = (current?.pr ?? []).filter(url => !urls.includes(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`);
+}
+
 /** 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) {
@@ -400,6 +434,7 @@ export async function inspectCompletionEvidence(board, id, entry, payload = {},
       }
       const candidate = stage === 'acceptance' ? reviewCandidate(board, id) : null;
       if (candidate) {
+        await requireCurrentReviewSet(board, id, candidatePullRequests(candidate).map(p => p.pr.url));
         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);
@@ -417,6 +452,7 @@ export async function inspectCompletionEvidence(board, id, entry, payload = {},
     }
     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 === 'request_review' || stage === 'review_verdict') await requireCurrentReviewSet(board, id, urls);
     if (!urls.length && asked?.no_code) return { ...state, no_code: asked.no_code };
     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.');
     // Merged source is immutable and needs no surviving workspace. Resolve an
@@ -459,7 +495,8 @@ export async function inspectCompletionEvidence(board, id, entry, payload = {},
       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 } : {}) });
-  } catch (error) { Object.assign(state, { required: true, ready: false, reason: error.message }); }
+  } catch (error) { Object.assign(state, { required: true, ready: false, reason: error.message,
+    ...(error.code ? { code: error.code, retryable: error.code === 'GITHUB_BUDGET' } : {}) }); }
   return state;
 }
 

package/board/cli.mjs

@@ -109,6 +109,7 @@ The board's verbs, with their flags:
   specify <id> [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
   decompose <id> [--child "<title>[@<profile>]"]... [--all]
   diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
+  github-usage [--since 1h]          local REST attempts by caller/endpoint; no GitHub read
   notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
   capacity   (each cap's count against its max, and why each card waits; docs/adr/0009-board-capacity.md)
   dispatching [on|off] [--reason R]   dispatch [--dry-run] [--max N] [--failure-limit N]   daemon [--interval S] [--max N] [--failure-limit N] [--pidfile F] [--verbose]   gc [--event-retention-days] [--log-retention-days]   repair
@@ -1424,7 +1425,7 @@ function ownCards(db, sessionId) {
   return { worked, held };
 }
 
-const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
+const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'github-usage', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
 
 /** The main session of each agent the workflow names a manager (`sc:<machine>:agent:<name>`), asked of this machine's
  *  daemon, which keeps agents' records (mail step 1c), once per call before its verb runs: a manager named by its agent

package/board/client.mjs

@@ -17,6 +17,16 @@ import { processSession } from './caller-session.mjs';
 export async function runWorkflow(argv) {
   const args = parse(argv);
   const [verb] = args._;
+  // This home's REST ledger is a local diagnostic, not a card verb. It needs neither a running board owner nor
+  // a workflow/identity/network read just to explain which callers already issued requests.
+  if (verb === 'github-usage') {
+    const value = String(args.since ?? '1h'), relative = /^(\d+)([smhd])$/.exec(value);
+    const since = relative ? Date.now() - Number(relative[1]) * { s: 1000, m: 60_000, h: 3600_000, d: 86400_000 }[relative[2]] : Date.parse(value);
+    if (!Number.isFinite(since)) throw new Error('github-usage --since takes 30m, 1h or an ISO date');
+    const { githubUsage } = await import('./github-rest.mjs');
+    process.stdout.write(`${JSON.stringify(githubUsage({ since }), null, 2)}\n`);
+    return 0;
+  }
   const help = !verb || verb === 'help' || args.help;
   const root = help ? null : homeOf(args);
   if (help || BOARD_OPERATION_VERBS.has(verb)) {

package/board/dispatch.mjs

@@ -3172,10 +3172,8 @@ async function activatePullRequestReviews(board, entry, report, effects, { only
         report.queued.push([id, `review waits: every open PR head (${payload.pr.join(', ')}) has a verdict or predates the last one; push a commit that answers it`]);
         continue;
       }
-      const evidence = payload.no_code ? { required: false, ready: true, reason: null, phase: 'source', no_code: payload.no_code } : await inspectCompletionEvidence(board, id, entry, payload, 'request_review');
-      if (!evidence.ready) throw new Error(evidence.reason);
-      // Due in every other respect: only the session's turn may still hold it. The first round that finds it so is
-      // recorded on the run (`review_held`), with what it was due on, so a goal turn can be told to have started after.
+      // A native turn holds the advisory proposal before authoritative source reads. Retain the proposal on the run
+      // (`review_held`) so a goal turn can be told to have started after that work was first observed.
       const heldRun = currentRun(board.db, id), dueKey = reviewDueKey(board, id, payload);
       const held = heldRun?.metadata?.supercode?.review_held?.key === dueKey ? heldRun.metadata.supercode.review_held : null;
       const inTurn = await turnInFlight(board, id, fleet, held ? Number(held.since) : null);
@@ -3184,9 +3182,15 @@ async function activatePullRequestReviews(board, entry, report, effects, { only
         report.queued.push([id, `review waits: ${inTurn.why}`]);
         continue;
       }
-      // a dry run names the review a tick would request and writes nothing
+      if (!dry) await refreshCardInputs(board, id, { commits: true });
+      // Cached draft/closed exclusions are useful while waiting, but cannot define a committed review's set.
+      payload = await openReviewPullRequests(board, id, { fresh: true });
+      if (!payload && noCodeReviewDue(board, id)) payload = await noCodeChange(board, id);
+      if (!payload || payload.waits) { report.queued.push([id, `review waits: ${payload?.waits ?? 'the current source set has no review candidate'}`]); payload = null; continue; }
+      const evidence = payload.no_code ? { required: false, ready: true, reason: null, phase: 'source', no_code: payload.no_code } : await inspectCompletionEvidence(board, id, entry, payload, 'request_review');
+      if (!evidence.ready) throw new Error(evidence.reason);
+      // A dry run names the complete validated review a tick would request and writes nothing.
       if (dry) { (report.would_review ??= []).push({ id, prs: payload.pr, heads: payload.pr_head, no_code: payload.no_code ?? null }); continue; }
-      await refreshCardInputs(board, id, { commits: true });
       const moved = tx(board, db => {
         const task = getTask(db, id);
         if (eligible(db) !== true) return null;

package/board/github-rest.mjs

@@ -0,0 +1,119 @@
+// Every REST wire attempt, including fast calls, belongs to a durable caller/endpoint receipt. Admission is shared
+// by all processes using this supercode home; it never pretends to account for another machine or an external gh.
+import { DatabaseSync } from 'node:sqlite';
+import { createHash, randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { current } from './call.mjs';
+
+export const GITHUB_HOURLY_ATTEMPTS = 1200;
+export const GITHUB_DISCOVERY_ATTEMPTS = 600;
+const HOUR = 3600_000;
+const pathOf = () => join(process.env.SUPERCODE_HOME || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode'), 'github-rest.sqlite');
+const connections = new Map();
+function connection() {
+  const path = pathOf();
+  if (connections.has(path)) return connections.get(path);
+  mkdirSync(join(path, '..'), { recursive: true, mode: 0o700 });
+  const db = new DatabaseSync(path);
+  chmodSync(path, 0o600);
+  db.exec(`PRAGMA busy_timeout=50; PRAGMA journal_mode=WAL;
+    CREATE TABLE IF NOT EXISTS github_attempts (
+      id TEXT PRIMARY KEY, credential TEXT NOT NULL, started_at INTEGER NOT NULL, ended_at INTEGER,
+      machine TEXT NOT NULL, pid INTEGER NOT NULL, caller TEXT NOT NULL, purpose TEXT NOT NULL,
+      method TEXT NOT NULL, endpoint TEXT NOT NULL, status INTEGER, outcome TEXT,
+      resource TEXT, used INTEGER, remaining INTEGER, reset_at INTEGER, retry_after INTEGER);
+    CREATE INDEX IF NOT EXISTS github_attempts_window ON github_attempts(credential,started_at,purpose);
+    CREATE INDEX IF NOT EXISTS github_attempts_home_window ON github_attempts(started_at,purpose);
+    CREATE TABLE IF NOT EXISTS github_cooldown (credential TEXT PRIMARY KEY, until_at INTEGER NOT NULL, reason TEXT NOT NULL);`);
+  connections.set(path, db);
+  return db;
+}
+const refusal = (message) => Object.assign(new Error(message), { code: 'GITHUB_BUDGET' });
+const integer = (value) => value != null && /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
+function endpointOf(url) {
+  const safe = new URL(url); safe.username = ''; safe.password = '';
+  for (const key of [...safe.searchParams.keys()]) if (!['state', 'head', 'per_page', 'page'].includes(key)) safe.searchParams.set(key, '[redacted]');
+  return safe.pathname + safe.search;
+}
+
+/** A reservation counts even when transport completion is unknown; retries and pagination reserve separately. */
+async function issue(url, options, { purpose }) {
+  const db = connection(), at = Date.now(), id = randomUUID();
+  const headers = new Headers(options.headers);
+  const credential = createHash('sha256').update(new URL(url).origin + '\0' + (headers.get('authorization') ?? '')).digest('hex').slice(0, 24);
+  const call = current(), caller = JSON.stringify({ address: call.caller ?? call.facts.SUPERCODE_CALLER ?? null,
+    principal: call.principal ?? null, actor: call.actor ?? null, agent: call.facts.SUPERCODE_AGENT_ID ?? null,
+    session: call.facts.CLAUDE_CODE_SESSION_ID ? `claude-code:${call.facts.CLAUDE_CODE_SESSION_ID}`
+      : call.facts.CODEX_SESSION_ID ? `codex:${call.facts.CODEX_SESSION_ID}` : null,
+    command: process.argv[2] ?? null });
+  const method = options.method ?? 'GET', endpoint = endpointOf(url);
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const blocked = db.prepare('SELECT until_at,reason FROM github_cooldown WHERE credential=?').get(credential);
+    if (blocked?.until_at > at) throw refusal(`GitHub REST deferred until ${new Date(blocked.until_at).toISOString()}: ${blocked.reason}`);
+    const count = db.prepare(`SELECT COUNT(*) total, COALESCE(SUM(purpose='discovery'),0) discovery
+      FROM github_attempts WHERE started_at>?`).get(at - HOUR);
+    if (count.total >= GITHUB_HOURLY_ATTEMPTS || purpose === 'discovery' && count.discovery >= GITHUB_DISCOVERY_ATTEMPTS) {
+      const oldest = db.prepare(`SELECT MIN(started_at) at FROM github_attempts WHERE started_at>?
+        AND (?='total' OR purpose='discovery')`).get(at - HOUR, count.total >= GITHUB_HOURLY_ATTEMPTS ? 'total' : 'discovery');
+      throw refusal(`GitHub ${purpose} deferred by this home's REST budget (${count.total}/${GITHUB_HOURLY_ATTEMPTS} total, ${count.discovery}/${GITHUB_DISCOVERY_ATTEMPTS} discovery in the last hour); retry after ${new Date(oldest.at + HOUR + 1).toISOString()}`);
+    }
+    db.prepare('INSERT INTO github_attempts(id,credential,started_at,machine,pid,caller,purpose,method,endpoint) VALUES(?,?,?,?,?,?,?,?,?)')
+      .run(id, credential, at, hostname(), process.pid, caller, purpose, method, endpoint);
+    db.exec('COMMIT');
+  } catch (error) { db.exec('ROLLBACK'); throw error; }
+  let response, outcome = 'unknown';
+  try { response = await fetch(url, { ...options, redirect: 'manual' }); outcome = response.ok ? 'ok' : `HTTP_${response.status}`; return response; }
+  catch (error) { outcome = error.code ?? error.name ?? 'transport_error'; throw error; }
+  finally {
+    const resource = response?.headers.get('x-ratelimit-resource') ?? null;
+    const used = integer(response?.headers.get('x-ratelimit-used'));
+    const remaining = integer(response?.headers.get('x-ratelimit-remaining'));
+    const reset = integer(response?.headers.get('x-ratelimit-reset'));
+    const retry = integer(response?.headers.get('retry-after'));
+    db.prepare('UPDATE github_attempts SET ended_at=?,status=?,outcome=?,resource=?,used=?,remaining=?,reset_at=?,retry_after=? WHERE id=?')
+      .run(Date.now(), response?.status ?? null, String(outcome), resource, used, remaining, reset == null ? null : reset * 1000, retry, id);
+    // Stop at the actual endpoint's headers, never call rate_limit to guess its account's allowance.
+    const until = Math.max(remaining === 0 && reset != null ? reset * 1000 : 0,
+      (response?.status === 429 || response?.status === 403) && retry != null ? Date.now() + retry * 1000 : 0,
+      remaining === 0 && reset == null ? Date.now() + 60_000 : 0);
+    if (until > Date.now()) db.prepare(`INSERT INTO github_cooldown(credential,until_at,reason) VALUES(?,?,?)
+      ON CONFLICT(credential) DO UPDATE SET until_at=MAX(until_at,excluded.until_at),reason=excluded.reason`)
+      .run(credential, until, remaining === 0 ? `${resource ?? 'REST'} remaining=0 on ${endpoint}` : `HTTP ${response.status} Retry-After on ${endpoint}`);
+  }
+}
+
+export async function githubFetch(url, options, { purpose = 'validation' } = {}) {
+  const origin = new URL(url).origin;
+  for (let hop = 0; hop < 10; hop++) {
+    const response = await issue(url, options, { purpose });
+    if (![301, 302, 303, 307, 308].includes(response.status) || !response.headers.get('location')) return response;
+    const next = new URL(response.headers.get('location'), url);
+    await response.body?.cancel();
+    if (next.origin !== origin) throw new Error('GitHub REST redirect leaves the configured API origin; credential forwarding refused');
+    // Match fetch's method conversion, but count every redirected wire attempt separately.
+    const method = options.method ?? 'GET';
+    if (response.status === 303 && !['GET', 'HEAD'].includes(method) || [301, 302].includes(response.status) && method === 'POST') {
+      const { body: _body, ...rest } = options; options = { ...rest, method: 'GET' };
+    }
+    url = next.href;
+  }
+  throw new Error('GitHub REST redirect chain exceeded 10 attempts');
+}
+
+/** Only retained product attempts are counted. No network read and no inference about uninstrumented callers. */
+export function githubUsage({ since = Date.now() - HOUR } = {}) {
+  const path = pathOf();
+  if (!existsSync(path)) return { path, recorded: false, callers: [], endpoints: [] };
+  const db = new DatabaseSync(path, { readOnly: true });
+  try {
+    return { path, recorded: true, since, limits: { hourly: GITHUB_HOURLY_ATTEMPTS, discovery: GITHUB_DISCOVERY_ATTEMPTS },
+      callers: db.prepare(`SELECT credential,machine,pid,caller,purpose,COUNT(*) attempts,SUM(status IS NULL) unanswered
+        FROM github_attempts WHERE started_at>=? GROUP BY credential,machine,pid,caller,purpose`).all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })),
+      endpoints: db.prepare(`SELECT credential,machine,pid,caller,purpose,method,endpoint,status,COUNT(*) attempts
+        FROM github_attempts WHERE started_at>=? GROUP BY credential,machine,pid,caller,purpose,method,endpoint,status`).all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })),
+      recent: db.prepare('SELECT id,credential,started_at,ended_at,machine,pid,caller,purpose,method,endpoint,status,outcome,resource,used,remaining,reset_at,retry_after FROM github_attempts WHERE started_at>=? ORDER BY started_at DESC,rowid DESC LIMIT 32').all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })) };
+  } finally { db.close(); }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.200",
+  "version": "0.5.201",
   "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": {