@volter/supercode-orchestrator 0.5.205 → 0.5.207

package/board/ci.mjs

@@ -14,12 +14,92 @@ import { githubFetch } from './github-rest.mjs';
 // review World's GitHub twin answers it, where gh (Go) trusts only the system keychain.
 const githubBase = () => (process.env.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, '');
 const githubHeaders = (token, extra = {}) => ({ accept: 'application/vnd.github+json', 'user-agent': 'supercode-board', ...(token ? { authorization: `Bearer ${token}` } : {}), ...extra });
-let loginToken = null;
+let loginToken = null, loginRead = null;
 async function githubToken() {
   const fixed = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || null;
-  if (!fixed && !loginToken) try { loginToken = (await run('gh', ['auth', 'token'])) || null; } catch { loginToken = null; }
+  if (!fixed && !loginToken) {
+    loginRead ??= run('gh', ['auth', 'token']).then((value) => loginToken = value || null, () => null).finally(() => { loginRead = null; });
+    await loginRead;
+  }
   return fixed ?? loginToken;
 }
+// The provider's retry boundary is shared by this board owner's reads, including different PRs and pages.
+// The key holds only a credential digest. Refusals retain no PR body and cannot become review evidence.
+const githubReadContexts = new Map();
+function admitGithubContext(key) {
+  let context = githubReadContexts.get(key);
+  if (!context) {
+    // Only idle, expired holders are disposable. Reserve before sending so a
+    // refusal always has space, even when other credentials are in flight.
+    const now = Date.now();
+    for (const [heldKey, held] of githubReadContexts) {
+      if (!held.readers && (!held.rateLimit || now >= held.rateLimit.until)) githubReadContexts.delete(heldKey);
+    }
+    if (githubReadContexts.size >= 8) return null;
+    context = { readers: 0, rateLimit: null };
+    githubReadContexts.set(key, context);
+  }
+  context.readers += 1;
+  return context;
+}
+function githubRateResult(path, held, deferred = false) {
+  const until = new Date(held.until).toISOString();
+  return { status: held.status, rateLimit: { retryAt: held.until, deferred },
+    error: `GitHub ${held.status} for ${path}: ${deferred ? 'not requested; ' : ''}rate limited until ${until}; ${held.reason}` };
+}
+function holdGithubRateLimit(context, response, text) {
+  const retry = response.headers.get('retry-after');
+  const remaining = response.headers.get('x-ratelimit-remaining');
+  if (response.status !== 429 && !(response.status === 403
+    && (remaining === '0' || retry != null || /rate[ -]?limit/i.test(text)))) return null;
+  const now = Date.now(), deadlines = [];
+  if (retry != null) {
+    const seconds = /^\d+(?:\.\d+)?$/.test(retry.trim()) ? Number(retry) : null;
+    const date = seconds == null ? Date.parse(retry) : now + seconds * 1000;
+    if (Number.isFinite(date) && date > now && date <= 8.64e15) deadlines.push(date);
+  }
+  if (remaining === '0') {
+    const raw = response.headers.get('x-ratelimit-reset');
+    const reset = raw != null && /^\d+$/.test(raw.trim()) ? Number(raw) * 1000 : NaN;
+    if (Number.isFinite(reset) && reset > now && reset <= 8.64e15) deadlines.push(reset);
+  }
+  const previous = context.rateLimit;
+  const failures = (previous?.failures ?? 0) + 1;
+  // With no useful provider deadline, secondary refusals wait at least a minute, increasing to fifteen minutes.
+  // The caller gets an error immediately; there is no sleeping request, timer, or automatic retry loop.
+  const until = deadlines.length ? Math.max(...deadlines) : now + Math.min(900_000, 60_000 * 2 ** Math.min(failures - 1, 4));
+  // A shorter concurrent refusal cannot shorten the shared provider boundary
+  // or replace the diagnostics that explain the longer one.
+  const held = previous && previous.until >= until ? { ...previous, failures }
+    : { status: response.status, until, failures, reason: text.slice(0, 300) };
+  context.rateLimit = held;
+  return held;
+}
+const GITHUB_READS = 4, GITHUB_WAITERS = 64;
+let githubActive = 0;
+const githubWaiting = [];
+async function admitGithubRead() {
+  if (githubActive < GITHUB_READS) githubActive++;
+  else {
+    if (githubWaiting.length >= GITHUB_WAITERS) throw Object.assign(new Error('GitHub metadata admission is full; no read was started'), { code: 'github_metadata_capacity', deferred: true });
+    await new Promise((resolve) => githubWaiting.push(resolve));
+  }
+  return () => { const next = githubWaiting.shift(); if (next) next(); else githubActive--; };
+}
+async function mapGithubSources(items, work) {
+  const out = new Array(items.length);
+  let next = 0, failed = false, failure;
+  await Promise.all(Array.from({ length: Math.min(GITHUB_READS, items.length) }, async () => {
+    while (!failed && next < items.length) {
+      const index = next++;
+      try { out[index] = await work(items[index], index); }
+      catch (error) { if (!failed) { failed = true; failure = error; } }
+    }
+  }));
+  if (failed) throw failure;
+  return out;
+}
+const readTogether = mapGithubSources;
 /** 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. */
 const actionReads = new AsyncLocalStorage();
@@ -32,51 +112,64 @@ async function github(path, all = false, { purpose = 'validation' } = {}) {
   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;
+  const release = await admitGithubRead();
+  try { return await fn(); } finally { release(); }
 }
 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 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 = pageRead.next;
-    }
-    return { body: out };
-  };
   const started = performance.now();
-  let result;
-  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 Object.assign(new Error(`GitHub: ${result.error.trim().slice(-500)}`, { cause: result.cause }), result.cause?.code ? { code: result.cause.code } : {});
-  return result.body;
+    const read = async () => {
+      const token = await githubToken();
+      const base = githubBase();
+      const rateKey = `${base}\0${createHash('sha256').update(token ?? '').digest('hex')}`;
+      const context = admitGithubContext(rateKey);
+      if (!context) return { code: 'github_read_admission_full', error: 'eight GitHub origin/credential contexts are active; not requested' };
+      try {
+        let url = base + path, out = [];
+        for (let page = 0; url && page < 10; page += 1) {
+          // No await separates admission from fetch. Every page observes a
+          // refusal retained while an earlier page or another read was in flight.
+          const held = context.rateLimit;
+          if (held && Date.now() < held.until) return githubRateResult(path, held, true);
+          const pageRead = await wireRead(async () => {
+          const held = context.rateLimit;
+          if (held && Date.now() < held.until) return { result: githubRateResult(path, held, true) };
+          const r = await githubFetch(url, { headers: githubHeaders(token), signal: AbortSignal.timeout(30_000) }, { purpose });
+          if (!r.ok) {
+            const text = (await r.text()).slice(0, 300), limited = holdGithubRateLimit(context, r, text);
+            return { result: limited ? githubRateResult(path, limited) : { status: r.status, token, error: `GitHub ${r.status} for ${path}: ${text}` } };
+          }
+          // An older in-flight success is not recovery from a newer refusal.
+          if (context.rateLimit && Date.now() >= context.rateLimit.until) context.rateLimit = null;
+          return { body: await r.json(), next: /<([^>]+)>;\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null };
+          });
+          if (pageRead.result) return pageRead.result;
+          const body = pageRead.body;
+          if (!all) return { body };
+          out = out.concat(body);
+          url = pageRead.next;
+        }
+        return { body: out };
+      } finally {
+        context.readers -= 1;
+        if (!context.readers && !context.rateLimit) githubReadContexts.delete(rateKey);
+      }
+    };
+    let result;
+    try { result = await read(); } catch (error) { result = { error: String(error?.message ?? error), cause: error }; }
+    if (result.status === 401 && !(process.env.GH_TOKEN || process.env.GITHUB_TOKEN) && (loginToken || loginRead)) {
+      if (loginToken === result.token) loginToken = null;
+      try { result = await read(); } catch (error) { result = { error: String(error?.message ?? error), cause: error }; }
+    }
+    noteStep('github read', performance.now() - started);
+    if (result.error) {
+      const nativeCode = result.cause?.cause?.code ?? result.cause?.code;
+      throw Object.assign(new Error(`GitHub: ${result.error.trim().slice(-500)}${nativeCode ? ` (${nativeCode})` : ''}`, { cause: result.cause }), result.rateLimit
+        ? { code: 'github_rate_limited', status: result.status, retry_at: result.rateLimit.retryAt, deferred: true }
+        : result.code ? { code: result.code, deferred: result.code === 'github_read_admission_full' }
+        : result.cause?.code ? { code: result.cause.code, deferred: result.cause.code === 'GITHUB_BUDGET' } : {});
+    }
+    return result.body;
 }
 const repositoryOf = (url) => new URL(url).pathname.split('/').slice(1, 3).join('/');
 const numberOf = (url) => Number(new URL(url).pathname.split('/')[4]);
@@ -141,8 +234,15 @@ const run = async (program, args, cwd) => {
   }));
 };
 
+/** Deployment receipts were retired. Refuse them before any board or source operation. */
+export function assertSourceReceipt(payload = {}) {
+  for (const field of ['ci_run', 'ci-run', 'deployed_sha', 'deployed-sha']) {
+    if (Object.hasOwn(payload, field)) throw new Error(`${field} is retired; board completion and review use source/PR facts, not deployment CI receipts.`);
+  }
+}
+
 export function completionEvidence(board, id) {
-  return observations.get(key(board, id)) ?? { required: false, ready: true, phase: 'source', deployed_sha: null };
+  return observations.get(key(board, id)) ?? { required: false, ready: true, phase: 'source' };
 }
 
 export function completionPhase(board, id, entry, verb, payload, roles = []) {
@@ -472,8 +572,9 @@ export async function inspectCompletionEvidence(board, id, entry, payload = {},
   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 };
+  const state = { required: false, ready: true, reason: null, phase: 'source' };
   try {
+    assertSourceReceipt(payload);
     if (stage === 'completion' || stage === 'acceptance') {
       const supplied = payload.commit ?? payload.metadata?.commit;
       if (supplied) {
@@ -507,7 +608,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     // 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 readTogether(urls, readPullRequest);
+    const read = await mapGithubSources(urls, readPullRequest);
     const mergedOnly = urls.length && read.every(pr => pr.state === 'MERGED');
     const own = mergedOnly ? null : await repositoryWorkspace(board, id);
     if (!own && !urls.length) {
@@ -522,7 +623,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       if (stray) throw new Error(`An unmerged PR candidate needs a repository workspace: ${stray.url} (${stray.headRefName}) is on no branch the card or its tasks declare; register it with create "<what>" --subtask-of ${id} --workspace worktree:${repositoryOf(stray.url)} --branch ${stray.headRefName}`);
     }
     // A verdict with no requested PR (a scratch arc) keeps its own contract. An arc's review
-    // always names every opened PR it changed, independent of completion_ci.
+    // always names every opened PR it changed, independent of deployment.
     if (stage === 'review_verdict' && !asked && !urls.length) return state;
     Object.assign(state, { required: true, ready: false });
     if (!urls.length) throw new Error('Name each opened PR with --pr.');
@@ -531,7 +632,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       : 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 readTogether(urls, (url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage));
+    const prs = await mapGithubSources(urls, (url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage, read[index]));
     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.');
@@ -544,19 +645,22 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       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,
-    ...(error.code ? { code: error.code, retryable: error.code === 'GITHUB_BUDGET' } : {}) }); }
+  } catch (error) {
+    Object.assign(state, { required: true, ready: false, reason: String(error?.message ?? error) });
+    if (error?.code) Object.assign(state, { code: error.code, retryable: error.code === 'GITHUB_BUDGET' });
+    if (['GITHUB_BUDGET', 'github_rate_limited', 'github_metadata_capacity', 'github_read_admission_full'].includes(error?.code))
+      Object.assign(state, { deferred: true, deferred_code: error.code, retry_at: error.retry_at ?? null });
+  }
   return state;
 }
 
 /** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
-async function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
+async function verifyPullRequest(board, id, entry, own, url, supplied, stage, observed) {
   if (typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url)) throw new Error('Name the opened PR URL with --pr.');
   const repository = new URL(url).pathname.split('/').slice(1, 3).join('/');
   // An arc may change several repositories. A PR is read from GitHub; its pushed head is the reviewed one. The
   // card's own checkout, and this machine's checkout of the PR's branch when it keeps one, must also hold that head
   // with nothing uncommitted. A card on another machine is reviewed at its pushed head: its checkout is not read from here.
-  const observed = await readPullRequest(url);
   const path = observed.state === 'MERGED' || (own && !own.here) ? null : !own ? await branchCheckout(board, id, repository, observed.headRefName) : await originOf(own.path) === repository && await run('git', ['branch', '--show-current'], own.path) === observed.headRefName ? own.path : await branchCheckout(board, id, repository, observed.headRefName);
   // A PR merged before its review (an outage fix landed first) is still reviewed: its head is fixed for good, so the
   // verdict is recorded on that head, and nothing about a worktree or its base can move under it any more.
@@ -567,7 +671,7 @@ async function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
   if (!/^[a-f0-9]{40}$/.test(head)) throw new Error('Name the full PR head commit with --pr-head (reviewer: --reviewed-sha).');
   if (observed.headRefOid !== head) throw new Error(`The head of ${url} changed to ${observed.headRefOid}; request review of that head before recording a verdict.`);
   const branch = observed.headRefName;
-  const mainBranch = entry.params.completion_ci?.main_branches?.[repository] ?? 'main';
+  const mainBranch = observed.defaultBranch ?? 'main';
   // A merged hotfix may have landed on another base (prod); a PR from the main branch itself is a release, never arc work.
   if (branch === mainBranch || (!merged && observed.baseRefName !== mainBranch)) throw new Error(`${url} must propose its worktree branch to the repository main branch.`);
   if (stage === 'request_review' && path && !merged) {