@volter/supercode-orchestrator 0.5.200 → 0.5.202

package/README.md

@@ -42,6 +42,33 @@ 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 actions check their local role, guard and validator rules before GitHub.
+Fresh source observations are reused only within that action, with at most eight
+concurrent REST operations per process. Owner receipts retain the return code and
+redacted refusal even when a failed call is fast. See
+[acceptance latency readings](../../docs/evidence/board-acceptance-latency-2026-10-14.md).
+
+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

@@ -4,8 +4,10 @@ import { execFile } from 'node:child_process';
 import { readFileSync, realpathSync, writeFileSync, renameSync, statSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { 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,26 +22,60 @@ 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) {
+const actionReads = new AsyncLocalStorage();
+/** Fresh observations belong to one action only; callers and later actions never share this snapshot. */
+export const withFreshReviewReads = (fn) => actionReads.getStore() ? fn() : actionReads.run(new Map(), fn);
+async function github(path, all = false, { purpose = 'validation' } = {}) {
+  const reads = purpose === 'validation' && actionReads.getStore();
+  if (!reads) return githubUncached(path, all, { purpose });
+  const key = `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${all}\0${path}`;
+  if (!reads.has(key)) reads.set(key, githubUncached(path, all, { purpose }));
+  return reads.get(key);
+}
+// Bound actual HTTP/body I/O across all concurrent actions and discovery in this process.
+let activeReads = 0;
+const waitingReads = [];
+async function wireRead(fn) {
+  if (activeReads >= 8) await new Promise(resolve => waitingReads.push(resolve)); else activeReads++;
+  try { return await fn(); }
+  finally { const next = waitingReads.shift(); if (next) next(); else activeReads--; }
+}
+/** Preserve input order; after a failure drain active reads and issue no more work from this batch. */
+async function readTogether(items, read) {
+  const out = new Array(items.length); let cursor = 0, failure;
+  await Promise.all(Array.from({ length: Math.min(8, items.length) }, async () => {
+    while (!failure && cursor < items.length) {
+      const i = cursor++;
+      try { out[i] = await read(items[i], i); } catch (error) { failure ??= error; }
+    }
+  }));
+  if (failure) throw failure;
+  return out;
+}
+async function githubUncached(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) });
-      if (!r.ok) return { status: r.status, error: `GitHub ${r.status} for ${path}: ${(await r.text()).slice(0, 300)}` };
-      const body = await r.json();
+      const pageRead = await wireRead(async () => {
+        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)}` };
+        return { body: await r.json(), next: /<([^>]+)>;\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null };
+      });
+      if (pageRead.error) return pageRead;
+      const body = pageRead.body;
       if (!all) return { body };
       out = out.concat(body);
-      url = /<([^>]+)>;\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null;
+      url = pageRead.next;
     }
     return { body: out };
   };
   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 +84,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,9 +115,11 @@ 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 text = await r.text();
-    answer = { status: r.status, body: (() => { try { return JSON.parse(text); } catch { return { message: text.slice(0, 300) }; } })() };
+    answer = await wireRead(async () => {
+      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();
+      return { 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)}`); }
   if (answer.status === 200 && answer.body?.merged) return { merged: true, sha: answer.body.sha };
   if (answer.status === 409) return { moved: true, head: null, message: answer.body?.message ?? null };
@@ -165,20 +219,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 +293,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;
@@ -241,20 +304,21 @@ export async function openReviewPullRequests(board, id) {
   let branch = task?.branch_name ?? (current || null);
   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);
+  const repositoriesToRead = [...new Set([ownRepository, ...registered.map((r) => r.repository), ...(await knownRepositories({ fresh }))].filter(Boolean))];
+  const groups = await readTogether(repositoriesToRead, async repository => {
+    const prs = [];
+    // 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;
+      return []; // 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) {
@@ -270,25 +334,26 @@ export async function openReviewPullRequests(board, id) {
       ...(repository === ownRepository ? branch ? [branch] : [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`] : []),
       ...registered.filter(r => r.repository === repository).map(r => r.branch),
     ])];
-    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)) {
-        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 });
-      }
+    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 =>
+        !pr.isCrossRepository && pr.headRefName === headBranch && pr.headRefName !== pr.defaultBranch
+        && pr.baseRefName === pr.defaultBranch && !judgedHead(board, id, pr.headRefOid));
+    });
+    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 });
     }
-  }
+    return prs;
+  });
+  const prs = groups.flat();
   // A source declaration (an implementer's or manager's card comment, engine.comment) adds merged or moved PRs that
   // discovery cannot see; it never hides what discovery found. Only repositories the card's workspace or registered
   // branches name count, and each declared PR 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.
   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 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 sources = (declaration ? JSON.parse(declaration.payload).sources : []).filter(source => repositories.has(repositoryOf(source.url).toLowerCase()) && !prs.some(known => known.url === source.url));
+  for (const pr of await readTogether(sources, source => 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 +390,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 +425,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) {
@@ -389,6 +462,9 @@ export function judgedHead(board, id, head) {
 }
 
 export async function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
+  return withFreshReviewReads(() => inspectCurrentCompletionEvidence(board, id, entry, payload, stage));
+}
+async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage) {
   const state = { required: false, ready: true, reason: null, phase: 'source', deployed_sha: null };
   try {
     if (stage === 'completion' || stage === 'acceptance') {
@@ -400,6 +476,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);
@@ -407,22 +484,23 @@ export async function inspectCompletionEvidence(board, id, entry, payload = {},
         const passed = candidatePullRequests(row && JSON.parse(row.payload)?.ci);
         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.');
-        for (const w of wanted) {
+        await readTogether(wanted, async w => {
           const pr = await readPullRequest(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 });
       }
       return state;
     }
     const asked = stage === 'review_verdict' ? reviewCandidate(board, id) : null;
     const urls = [].concat(payload.pr ?? payload.metadata?.pr ?? candidatePullRequests(asked).map((c) => c.pr.url)).filter(Boolean);
+    if (stage === '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
     // unmerged candidate's checkout as before; a broken legacy path never
     // prevents a verdict on already merged commits.
-    const read = await Promise.all(urls.map(readPullRequest));
+    const read = await readTogether(urls, readPullRequest);
     const mergedOnly = urls.length && read.every(pr => pr.state === 'MERGED');
     const own = mergedOnly ? null : await repositoryWorkspace(board, id);
     if (!own && !urls.length) {
@@ -446,7 +524,7 @@ export async function inspectCompletionEvidence(board, id, entry, payload = {},
       : payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
     if (stage === 'request_review' && named.length !== urls.length) throw new Error('Name each PR head with --pr-head, one for each --pr, in the same order.');
     if (stage === 'review_verdict' && !named.length) throw new Error('Name every reviewed PR head with --reviewed-sha.');
-    const prs = await Promise.all(urls.map((url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage)));
+    const prs = await readTogether(urls, (url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage));
     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('The PRs the last verdict judged have no new head; push a new head before requesting review.');
@@ -459,7 +537,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

@@ -14,6 +14,7 @@ import { taskStatusOf } from './published.mjs';
 import { executionOf } from './session-work.mjs';
 import { listCardsInTurns, writeCardList } from './listing.mjs';
 import { writeOwnerAnswer } from './reply.mjs';
+import { redactText } from '@volter/teams/redact';
 import { createServer } from 'node:net';
 import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import { notRuntime, ownHome } from './owner-files.mjs';
@@ -109,6 +110,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 +1426,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
@@ -1610,10 +1612,14 @@ async function answerOne(root, line) {
   const began = performance.now();
   const before = slowLog.processCounters?.() ?? null;
   let named = null, by = null;
-  try { return await answerRequest(root, line, (verb, caller) => { named = verb; by = caller; }); }
+  let answer;
+  try { answer = await answerRequest(root, line, (verb, caller) => { named = verb; by = caller; }); return answer; }
   finally {
     const ms = performance.now() - began;
-    if (named && ms > slowLog.SLOW_MS) recordSlow({ kind: 'call', name: `owner verb ${named}`, ms, slowest: null, extra: { caller: by, steps: slowLog.stepsWithin?.(began, performance.now()) ?? null, whole_process: before ? slowLog.processUse(before) : null } });
+    if (named) recordSlow({ kind: 'call', name: `owner verb ${named}`, ms, force: answer?.code !== 0,
+      outcome: answer ? answer.code === 0 ? 'ok' : `exit ${answer.code}` : 'unknown', slowest: null,
+      extra: { caller: by, response: { code: answer?.code ?? null, stderr: redactText([].concat(answer?.stderr ?? []).join('')).slice(0, 2000) },
+        steps: slowLog.stepsWithin?.(began, performance.now()) ?? null, whole_process: before ? slowLog.processUse(before) : null } });
   }
 }
 

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

@@ -28,7 +28,8 @@ import { localSessionDelegations } from '../agents.mjs';
 import { creatorOf, sessionProgress } from './workflow.mjs';
 import { boardLabel, boardName } from '@volter/teams/board-name';
 let fleetRoot = null;
-import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
+import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, withFreshReviewReads, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
+import { setImmediate as yieldToOwner } from 'node:timers/promises';
 import { runtimeDoor } from './runtime-door.mjs';
 import { agentScope, localCardAgent, localReaderContext, localAgentSessions, runBudgetRefusal, runsAwaitingUsage, recordRunUsage, recordUsageUnread, agentPreamble, agentEnvironment, recordAgentRun, cardAgentAssignments,handOffAgents, agentRunForSession } from '../agents.mjs';
 import { finishCardAgentAssignment, recordCardAgentAssignment } from './agent-declarations.mjs';
@@ -1936,6 +1937,7 @@ async function synchronizeAgents(board, report) {
     }
   }
   for(const assignment of cardAgentAssignments(board.root)){
+    await yieldToOwner();
     const task=getTaskNow(board,assignment.target);
     if(task&&(assignment.state==='ended'||task.archived||['done','cancelled'].includes(task.status)))finishCardAgentAssignment(board,assignment,`card ${assignment.target} ${task.archived?'archived':task.status}`);
     else if(task)recordCardAgentAssignment(board,assignment);
@@ -2351,8 +2353,10 @@ const latestAnswer = (db, id) => db.prepare(`SELECT id, kind, payload FROM task_
  * only while that claim is the card's latest.
  */
 export async function completeAdoptions(board, fleet, settings, report, lanes = null) {
-  const pending = view(board, db => db.prepare(`SELECT e.id, e.task_id, e.kind, e.payload, e.created_at FROM task_events e
-    WHERE ((e.kind = 'dispatch_held' AND json_extract(e.payload, '$.reason') = 'adoption requested') OR e.kind = 'adoption_claimed')
+  const pending = view(board, db => db.prepare(`SELECT e.id, e.task_id, e.kind, e.payload, e.created_at
+    FROM (SELECT DISTINCT task_id FROM task_events) cards CROSS JOIN task_events e ON e.task_id=cards.task_id
+    WHERE e.kind IN ('dispatch_held','adoption_claimed')
+    AND ((e.kind = 'dispatch_held' AND json_extract(e.payload, '$.reason') = 'adoption requested') OR e.kind = 'adoption_claimed')
     AND e.id = (SELECT MAX(id) FROM task_events l WHERE l.task_id = e.task_id AND l.kind IN ${ADOPTION_ANSWERS})`).all());
   for (const row of pending) {
     // a request another round has claimed is that round's while its claim holds; a claim whose round died is open again
@@ -2788,6 +2792,7 @@ async function notify(board, fleet, report, entry) {
   await endWorkerSubscriptions(board, fleet, report);
   const record = view(board, (db) => sessionRecord(db));
   for (const sub of subscriptions(board.db).filter((s) => s.platform === 'supercode')) {
+    await yieldToOwner();
     if (stopping) break;
     if (sub.delivery_metadata?.dependent_card && sub.delivery_metadata.waiting_recipient) continue;
     const role = ['worker', 'dependency', 'manager'].includes(sub.delivery_metadata?.role) ? sub.delivery_metadata.role : 'creator';
@@ -2803,7 +2808,8 @@ async function notify(board, fleet, report, entry) {
     } else if (ended) continue; // no fleet reading: nothing is filed unread to a session recorded as ended
     const kinds = heardBy(entry, role);
     if (!kinds.length) continue;
-    const events = board.db.prepare(`SELECT id, kind, payload, created_at, run_id FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id`)
+    // The retained cursor resumes the next page; one native read never materializes the whole unread history.
+    const events = board.db.prepare(`SELECT id, kind, payload, created_at, run_id FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id LIMIT 64`)
       .all(sub.task_id, sub.last_event_id, ...kinds);
     if (!events.length) continue;
     // the card as the workflow names it (its status the workflow's: triaging, reviewing, stopped; `stored_as` kanban.db's)
@@ -2857,7 +2863,17 @@ async function notify(board, fleet, report, entry) {
     // a subscription past its card's last event ends with the card: a worker's when the card is done or archived (its
     // work is over, and its session may never run again), anyone's when it is archived
     const over = task && (task.stored_as === 'archived' || (role === 'worker' && task.stored_as === 'done'));
-    if (over && cursor >= events.at(-1).id) tx(board, (db) => db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(...identity));
+    if (over) tx(board, (db) => {
+      const durable = db.prepare(`SELECT last_event_id FROM kanban_notify_subs ${where}`).get(...identity);
+      if (!durable) return;
+      // A page's final event is not the end of the backlog. Check past the persisted cursor in the same
+      // transaction as retirement, so another page (including the card's completion) is never abandoned.
+      const remaining = db.prepare(`SELECT 1 FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) LIMIT 1`)
+        .get(sub.task_id, durable.last_event_id, ...kinds);
+      const current = getTask(db, sub.task_id);
+      if (!remaining && current && (current.status === 'archived' || (role === 'worker' && current.status === 'done')))
+        db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(...identity);
+    });
   }
 }
 
@@ -3172,10 +3188,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 +3198,22 @@ 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.
+      const observed = await withFreshReviewReads(async () => {
+        const candidate = await openReviewPullRequests(board, id, { fresh: true })
+          ?? (noCodeReviewDue(board, id) ? await noCodeChange(board, id) : null);
+        const evidence = !candidate || candidate.waits ? null : candidate.no_code
+          ? { required: false, ready: true, reason: null, phase: 'source', no_code: candidate.no_code }
+          : await inspectCompletionEvidence(board, id, entry, candidate, 'request_review');
+        return { candidate, evidence };
+      });
+      payload = observed.candidate;
+      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 = observed.evidence;
+      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/engine.mjs

@@ -16,7 +16,7 @@ import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspac
 import { DatabaseSync } from 'node:sqlite';
 import { view, actorOf, principalOf, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
 import { completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
-import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
+import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, eventTo, fire, validateEvent, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 import { refuseCredentialDump, withheldIfDump } from './credential-guard.mjs';
 import { AGENT_KIND_LIST, compactCardAgentEvents } from './published.mjs';
 
@@ -432,6 +432,8 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
   if (name === 'comment' && (!String(payload.body ?? '').trim() || !String(payload.author ?? '').trim())) throw new Error('a comment has an author and body');
   refuseCredentialDump(name === 'comment' ? `the comment on ${id}` : `${name.replace(/_/g, '-')} on ${id}`, payload);
   await refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
+  if (['complete', 'request_review', 'request_state'].includes(name)) view(board, db => validateEvent(db, board, entry, id, name,
+    { roles: roles ?? callerRoles(db, id), payload, extra, localOnly: true }));
   const evidencePhase = ['complete', 'request_review', 'request_state'].includes(name) ? completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id)) : null;
   if (evidencePhase) payload = { ...payload, ci: await observeCompletionEvidence(board, id, entry, payload, evidencePhase) };
   if (payload.ci?.required && !payload.ci.ready && (name !== 'request_state' || evidencePhase === 'review_verdict')) throw new Error(payload.ci.reason ?? 'The PR candidate could not be verified.');
@@ -459,6 +461,7 @@ export async function requestStateMany(board, ids, payload = {}) {
   const prepared = new Map(await Promise.all(targets.map(async id => {
     const roles = callerRoles(board.db, id);
     const phase = completionPhase(board, id, entry, 'request_state', payload, roles);
+    view(board, db => validateEvent(db, board, entry, id, 'request_state', { roles, payload, localOnly: true }));
     const evidence = await inspectCompletionEvidence(board, id, entry, payload, phase);
     // An ordinary request mails a decision to the manager, not a completion.
     // Keep a failed source observation in that mail. A reviewer recording an

package/board/expr.mjs

@@ -129,6 +129,45 @@ function compiled(text) {
 
 const own = (o, k) => o !== null && o !== undefined && (typeof o === 'object' || typeof o === 'function') && Object.prototype.hasOwnProperty.call(o, k);
 
+/** Whether an expression may read observed sources, including through derived card fields. Unknown access waits. */
+export function needsSources(text, derived = {}) {
+  const visiting = new Set();
+  const field = (root, key) => {
+    if (key === 'ci') return true;
+    if (root !== 'card' || !own(derived, key)) return false;
+    if (visiting.has(key)) return true;
+    visiting.add(key);
+    const dependent = expression(derived[key]);
+    visiting.delete(key);
+    return dependent;
+  };
+  const root = e => e.k === 'name' && ['card', 'event'].includes(e.v);
+  const visit = e => {
+    switch (e.k) {
+      case 'lit': return false;
+      case 'name': return root(e); // passing the whole object can expose its sources
+      case 'get': return root(e.on)
+        ? e.key.k !== 'lit' || field(e.on.v, e.key.v)
+        : visit(e.on) || visit(e.key);
+      case 'method': return (root(e.on)
+        ? e.m === 'size' || field(e.on.v, e.m)
+        : visit(e.on)) || e.args.some(visit);
+      case 'list': return e.items.some(visit);
+      case 'call': return e.args.some(visit);
+      case 'macro': return visit(e.on) || visit(e.body);
+      case 'not': case 'neg': return visit(e.e);
+      case 'bin': return visit(e.l) || visit(e.r);
+      case 'if': return visit(e.c) || visit(e.a) || visit(e.b);
+      default: return true;
+    }
+  };
+  const expression = value => {
+    if (value === null || value === undefined || String(value).trim() === '') return false;
+    try { return visit(compiled(String(value))); } catch { return true; }
+  };
+  return expression(text);
+}
+
 function run(e, scope) {
   switch (e.k) {
     case 'lit': return e.v;

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/board/workflow.mjs

@@ -14,7 +14,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'nod
 import { randomBytes } from 'node:crypto';
 import { actorOf, appendRunObservation, event as record, json, now } from './store.mjs';
 import { releaseAllSideSessions } from './side-sessions.mjs';
-import { evaluate, holds, render } from './expr.mjs';
+import { evaluate, holds, render, needsSources } from './expr.mjs';
 import { completionEvidence, declaredWorkBranches, namedWorkBranch, reviewCandidate } from './ci.mjs';
 import { cardCommitsOn, isLocalWorkspace, isWorkspacePath } from './workspace.mjs';
 import { identifyNotice } from './notices.mjs';
@@ -383,7 +383,7 @@ function timeOf(db, task) {
 function askedOf(id) { return mailboxAnswers.get(id)?.askedOf ?? null; }
 
 /** The scope an expression is evaluated in: the card (with its relations), the event, params, time, extras. */
-export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy = false } = {}) {
+export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy = false, deferSources = false } = {}) {
   // Only read-only guards opt into demand reads. Mutation scopes materialize before any write,
   // keeping `before` and run-history fields pinned to their original snapshot.
   const once = (read) => { let done = false, value; return () => { if (!done) { value = read(); done = true; } return value; }; };
@@ -486,8 +486,10 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     Object.defineProperty(card, key, { get: read, enumerable: true, configurable: true });
     if (!lazy) read();
   }
-  for (const [key, expr] of Object.entries(loaded.get(board.root)?.workflow?.derived ?? {})) {
-    const value = evaluate(expr, { card, event, params, now: now() });
+  const derived = loaded.get(board.root)?.workflow?.derived ?? {};
+  for (const [key, expr] of Object.entries(derived)) {
+    // Preflight neither evaluates nor exposes a derived source value from a stale/missing observation.
+    const value = deferSources && needsSources(expr, derived) ? undefined : evaluate(expr, { card, event, params, now: now() });
     Object.defineProperty(card, key, { value, writable: true, enumerable: true, configurable: true });
   }
   return {
@@ -594,7 +596,7 @@ function declaredStatus(db, board, entry, task) {
  * takes only a sender in one of its roles; `platform` for the dispatcher's own observations). Answers
  * `{ from, to, effects }`; throws the refusal when no transition applies or a validator fails.
  */
-export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
+export function validateEvent(db, board, entry, id, name, { roles = [], payload = {}, extra = {}, localOnly = false } = {}) {
   // A card ends with its reason: a cancel or archive that says nothing why is refused, whoever sends it, the manager
   // included. The reason is all the next reader of an ended card has (an empty-reason cancel once ended an arc that had
   // shipped half, and nothing on the card said so).
@@ -603,14 +605,14 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
   // archive: that ends it the way the document already has, and is the one way a manager clears it.
   if (db.boardErrors?.has(id) && !(/cannot change card removal/.test(db.boardErrors.get(id)) && ['cancel', 'archive'].includes(name) && roles.includes('manager'))) throw new Error(`${id}: ${db.boardErrors.get(id)}`);
   const { workflow, params } = entry;
-  if (workflow.run && (workflow.run.on?.[name] || Object.values(workflow.run.states ?? {}).some((s) => s.on?.[name]))) return fireRun(db, board, entry, id, name, { roles, payload, extra });
+  if (workflow.run && (workflow.run.on?.[name] || Object.values(workflow.run.states ?? {}).some((s) => s.on?.[name]))) return null;
   const task = cardOf(db, id);
-  const beforeRun = noticeRun(db, task);
-  const from = declaredStatus(db, board, entry, task);
+  const from = localOnly ? statusOf(db, task) : declaredStatus(db, board, entry, task);
+  if (localOnly && !workflow.statuses[from]) return null; // only fire adopts an imported status
   const candidates = transitionsFor(workflow, from, name);
   if (!candidates.length) throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} does not apply there`);
   // `sender`: the roles the event was sent with (a validator can ask who is asking)
-  const scope = scopeOf(db, board, task, { params, event: payload, extra: { lanes: lanesIn(entry), ...extra, sender: roles, verb: name } });
+  const scope = scopeOf(db, board, task, { params, event: payload, lazy: localOnly, deferSources: localOnly, extra: { lanes: lanesIn(entry), ...extra, sender: roles, verb: name } });
   const allowed = candidates.filter((t) => !t.by?.length || t.by.some((r) => roles.includes(r)));
   if (!allowed.length) {
     const state = name === 'complete' ? 'done' : name === 'cancel' ? 'cancelled' : null;
@@ -618,6 +620,10 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
       ? ` Ask the manager with workflow request-state ${id} --state ${state} --reason <why> --evidence <verdict-and-pointers>.` : '';
     throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(candidates.flatMap((t) => t.by ?? []))].join(' or ')}. ${candidates.map((t) => t.description).filter(Boolean).join(' ')}${request}`);
   }
+  // A source-dependent branch is undecidable before observation; preflight must not choose its fallback.
+  const needsSource = expr => needsSources(expr, workflow.derived);
+  // Other roles' guards also determine the refusal below; none may decide it using stale sources.
+  if (localOnly && candidates.some(t => needsSource(t.guard))) return null;
   const taken = allowed.find((t) => holds(t.guard ?? null, scope));
   // none of the sender's rules holds, but another role's does (one verb with a rule per case, as `set` has one per
   // field): it is that role's to send
@@ -633,8 +639,17 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
     none.noTransition = true; throw none;
   }
   for (const v of taken.validate ?? []) {
+    if (localOnly && needsSource(v.expr)) continue;
     if (!holds(v.expr, scope)) { const reason = render(v.message, scope); const refusal = new Error(reason); refusal.refusal = reason; throw refusal; }
   }
+  return { task, from, taken, scope, beforeRun: localOnly ? null : noticeRun(db, task) };
+}
+
+export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
+  const checked = validateEvent(db, board, entry, id, name, { roles, payload, extra });
+  if (!checked) return fireRun(db, board, entry, id, name, { roles, payload, extra });
+  const { task, from, taken, scope, beforeRun } = checked;
+  const { params } = entry;
   const effects = [];
   const to = take(db, board, entry, task, from, taken, scope, effects);
   settle(db, board, entry, id, effects);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.200",
+  "version": "0.5.202",
   "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": {
@@ -28,9 +28,9 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.333",
+    "@volter/supercode-teams": "^0.3.334",
     "@volter/supercode-terminal": "^0.3.8",
-    "@volter/supercode-harness-sdk": "^0.3.101",
+    "@volter/supercode-harness-sdk": "^0.3.102",
     "@volter/teams": "0.2.93",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"