@volter/supercode-orchestrator 0.5.73 → 0.5.75

package/board/ci.mjs

@@ -1,79 +1,72 @@
 // Review candidates are observed before a board mutation. No network or Git
 // process runs inside the optimistic transaction. Deployment is not a completion gate.
-import { spawnSync } from 'node:child_process';
+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 { branchCheckouts, checkoutOf, isLocalWorkspace, resolveWorkspace } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 
-// GitHub is read through its REST API with Node's own fetch, not the gh binary: Node takes a World's trust bundle and
-// injector (NODE_EXTRA_CA_CERTS, NODE_OPTIONS), so a review World's GitHub twin answers it, where gh (Go) trusts only
-// the system keychain. The read runs in a child Node so the callers stay synchronous.
-const GITHUB_READ = `
-const [path, all] = process.argv.slice(1);
-const base = (process.env.GITHUB_API_URL || 'https://api.github.com').replace(/\\/$/, '');
-const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
-const headers = { accept: 'application/vnd.github+json', 'user-agent': 'supercode-board', ...(token ? { authorization: 'Bearer ' + token } : {}) };
-let url = base + path, out = [];
-for (let page = 0; url && page < 10; page += 1) {
-  const r = await fetch(url, { headers });
-  if (!r.ok) { process.stderr.write('GitHub ' + r.status + ' for ' + path + ': ' + (await r.text()).slice(0, 300)); process.exit(1); }
-  const body = await r.json();
-  if (all !== '1') { process.stdout.write(JSON.stringify(body)); process.exit(0); }
-  out = out.concat(body);
-  url = /<([^>]+)>;\\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null;
-}
-process.stdout.write(JSON.stringify(out));`;
+// 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
+// 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;
+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; }
+  return fixed ?? loginToken;
+}
 /** 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. */
-function github(path, all = false) {
-  const fixed = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || null;
-  const read = () => {
-    if (!fixed && !loginToken) try { loginToken = run('gh', ['auth', 'token']) || null; } catch { loginToken = null; }
-    const token = fixed ?? loginToken;
-    const env = token ? { ...process.env, GH_TOKEN: token } : process.env;
-    return spawnSync(process.execPath, ['--input-type=module', '-e', GITHUB_READ, path, all ? '1' : '0'], { env, encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
+async function github(path, all = false) {
+  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();
+      if (!all) return { body };
+      out = out.concat(body);
+      url = /<([^>]+)>;\s*rel="next"/.exec(r.headers.get('link') ?? '')?.[1] ?? null;
+    }
+    return { body: out };
   };
   const started = performance.now();
-  let result = read();
+  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) }; } }
   noteStep('github read', performance.now() - started);
-  if (result.status !== 0 && !fixed && loginToken && /^GitHub 401 /.test(result.stderr ?? '')) { loginToken = null; result = read(); }
-  if (result.status !== 0) throw new Error(`GitHub: ${(result.stderr || result.error?.message || 'read failed').trim().slice(-500)}`);
-  return JSON.parse(result.stdout);
+  if (result.error) throw new Error(`GitHub: ${result.error.trim().slice(-500)}`);
+  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]);
 /** A PR as the board reads it (gh's field names). */
 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 = (url) => pullRequest(repositoryOf(url), github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`));
+const readPullRequest = async (url) => pullRequest(repositoryOf(url), await github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`));
 
-const GITHUB_MERGE = `
-const [path, sha] = process.argv.slice(1);
-const base = (process.env.GITHUB_API_URL || 'https://api.github.com').replace(/\\/$/, '');
-const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
-const r = await fetch(base + path, { method: 'PUT', headers: { accept: 'application/vnd.github+json', 'content-type': 'application/json', 'user-agent': 'supercode-board', ...(token ? { authorization: 'Bearer ' + token } : {}) }, body: JSON.stringify({ sha, merge_method: 'merge' }) });
-const text = await r.text();
-process.stdout.write(JSON.stringify({ status: r.status, body: (() => { try { return JSON.parse(text); } catch { return { message: text.slice(0, 300) }; } })() }));`;
 /**
  * Merge a reviewed PR at the head its review judged, and only there: GitHub refuses the merge when the PR's head is no
  * longer that commit (409), so a head pushed after the verdict is never merged unreviewed. Answers
  * `{ merged, sha }` (already merged answers its merge commit), `{ moved, head }` when the head is not the reviewed one,
  * or throws on anything GitHub did not decide (the caller tries again).
  */
-export function mergeReviewedPullRequest(url, reviewed) {
-  const pr = github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`);
+export async function mergeReviewedPullRequest(url, reviewed) {
+  const pr = await github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`);
   if (pr.merged_at) return { merged: true, sha: pr.merge_commit_sha, already: true };
   if (pr.head?.sha !== reviewed) return { moved: true, head: pr.head?.sha ?? null };
   if (String(pr.state).toLowerCase() !== 'open') return { closed: true };
-  const fixed = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || null;
-  if (!fixed && !loginToken) try { loginToken = run('gh', ['auth', 'token']) || null; } catch { loginToken = null; }
-  const token = fixed ?? loginToken;
-  const result = spawnSync(process.execPath, ['--input-type=module', '-e', GITHUB_MERGE, `/repos/${repositoryOf(url)}/pulls/${numberOf(url)}/merge`, reviewed], { env: token ? { ...process.env, GH_TOKEN: token } : process.env, encoding: 'utf8', timeout: 60_000 });
-  if (result.status !== 0) throw new Error(`GitHub merge: ${(result.stderr || result.error?.message || 'failed').trim().slice(-300)}`);
-  const answer = JSON.parse(result.stdout);
+  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) }; } })() };
+  } 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 };
   throw new Error(`GitHub merge ${answer.status}: ${answer.body?.message ?? 'not merged'}`);
@@ -81,15 +74,17 @@ export function mergeReviewedPullRequest(url, reviewed) {
 
 const observations = new Map();
 const key = (board, id) => `${board.root}\0${board.slug}\0${id}`;
-const run = (program, args, cwd) => {
+// A git (or gh) command, awaited: never a wait that holds the event loop.
+const run = async (program, args, cwd) => {
   if (cwd) {
     let directory = false;
     try { directory = statSync(cwd).isDirectory(); } catch { /* reported below */ }
     if (!directory) throw new Error(`Repository checkout ${cwd} is unavailable; resolve the card's declared workspace before verifying its source.`);
   }
-  const result = spawnSync(program, args, { cwd, encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024 });
-  if (result.status !== 0) throw new Error(`${program}: ${(result.stderr || result.error?.message || 'command failed').trim().slice(-500)}`);
-  return result.stdout.trim();
+  return new Promise((resolve, reject) => execFile(program, args, { cwd, encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024 }, (error, stdout, stderr) => {
+    if (error) reject(new Error(`${program}: ${(stderr || error.message || 'command failed').trim().slice(-500)}`));
+    else resolve(String(stdout).trim());
+  }));
 };
 
 export function completionEvidence(board, id) {
@@ -102,8 +97,8 @@ export function completionPhase(board, id, entry, verb, payload, roles = []) {
   return verb === 'complete' ? 'acceptance' : 'completion';
 }
 
-export function observeCompletionEvidence(board, id, entry, payload = {}, phase = 'completion') {
-  const state = inspectCompletionEvidence(board, id, entry, payload, phase);
+export async function observeCompletionEvidence(board, id, entry, payload = {}, phase = 'completion') {
+  const state = await inspectCompletionEvidence(board, id, entry, payload, phase);
   observations.set(key(board, id), state);
   return state;
 }
@@ -129,26 +124,26 @@ export function reviewCandidate(board, id) {
 /** The PRs an evidence record covers: every PR of one arc review (the first is also its top-level PR). */
 export const candidatePullRequests = (ci) => ci?.prs ?? (ci?.pr ? [{ repository: ci.repository, branch: ci.branch, commit: ci.commit, source_sha: ci.source_sha ?? ci.commit, pr: ci.pr }] : []);
 // The repository a checkout declares (remote.origin.url), not where a URL rewrite sends its transport.
-const originOf = (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['config', '--get', 'remote.origin.url'], path))?.[1] ?? null;
+const originOf = async (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(await run('git', ['config', '--get', 'remote.origin.url'], path))?.[1] ?? null;
 
 /** The card's checkout as its machine answers for it (path, repository, branch), and whether it is on this machine:
  *  git runs only in a checkout here, and another machine's is known by what its door said. */
-function repositoryWorkspace(board, id) {
+async function repositoryWorkspace(board, id) {
   const task = board.db.prepare('SELECT t.*,c.subtask_of,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
   const parent = task?.subtask_of && board.db.prepare('SELECT t.*,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(task.subtask_of);
   const workspace = task?.workspace_kind === 'scratch' ? parent : task;
   if (!workspace || workspace.workspace_kind === 'scratch') return null;
   const here = isLocalWorkspace(workspace);
-  if (workspace.workspace_anchor) return { ...resolveWorkspace(workspace, false), here };
+  if (workspace.workspace_anchor) return { ...(await resolveWorkspace(workspace, false)), here };
   return workspace.workspace_path ? { path: workspace.workspace_path, here } : null;
 }
 
 const pullRequestLists = new Map();
 
-function branchCheckout(board, id, repository, branch) {
+async function branchCheckout(board, id, repository, branch) {
   const task = board.db.prepare('SELECT c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
   if (!isLocalWorkspace(task ?? {})) return null;
-  try { return checkoutOf(task?.machine, repository, branch)?.path ?? null; } catch { return null; }
+  try { return (await checkoutOf(task?.machine, repository, branch))?.path ?? null; } catch { return null; }
 }
 
 /** The sibling checkouts an arc registered: each subtask (and the card itself) that declares a repository
@@ -184,24 +179,24 @@ 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 function openReviewPullRequests(board, id) {
-  const own = repositoryWorkspace(board, id);
+export async function openReviewPullRequests(board, id) {
+  const own = await repositoryWorkspace(board, id);
   if (!own) return null;
   const task = board.db.prepare('SELECT branch_name FROM tasks WHERE id=?').get(id);
-  const ownRepository = own.repository ?? (own.here ? originOf(own.path) : null);
+  const ownRepository = own.repository ?? (own.here ? await originOf(own.path) : null);
   if (!ownRepository) return null;
-  const current = task?.branch_name ? null : own.branch ?? (own.here ? run('git', ['branch', '--show-current'], own.path) : null);
+  const current = task?.branch_name ? null : own.branch ?? (own.here ? await run('git', ['branch', '--show-current'], own.path) : null);
   let branch = task?.branch_name ?? (current || null);
   const registered = registeredBranches(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), ...knownRepositories()])) {
+  for (const repository of new Set([ownRepository, ...registered.map((r) => r.repository), ...(await knownRepositories())])) {
     // 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 = [];
-      try { items = github(`/repos/${repository}/pulls?state=open&per_page=100`, true).map((p) => pullRequest(repository, p)); }
+      try { items = (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true)).map((p) => pullRequest(repository, p)); }
       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 };
       if (pullRequestLists.size >= 64) pullRequestLists.delete(pullRequestLists.keys().next().value);
@@ -209,7 +204,7 @@ export function openReviewPullRequests(board, id) {
     }
     // 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) {
-      const defaultBranch = list.items.find((pr) => pr.defaultBranch)?.defaultBranch ?? (() => { try { return run('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], own.path).replace(/^origin\//, ''); } catch { return null; } })();
+      const defaultBranch = list.items.find((pr) => pr.defaultBranch)?.defaultBranch ?? (await (async () => { try { return (await run('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], own.path)).replace(/^origin\//, ''); } catch { return null; } })());
       if (branch === defaultBranch) branch = null;
     }
     // a draft is not handed over yet: its review starts when it is marked ready; a PR to another base (main→prod) is a release, not the arc's work
@@ -222,32 +217,32 @@ export function openReviewPullRequests(board, id) {
 /** An arc that changed no code (a disposition, such as closing a PR with its reason): its work branch holds no commit
  *  beyond its repository's default branch, locally or on origin, its checkout holds no uncommitted work, no PR was
  *  ever opened from it, and it registered no other branch. Answers what its review reads instead of a diff, or null when the arc carries (or may carry) code. */
-export function noCodeChange(board, id) {
-  const checkout = repositoryWorkspace(board, id);
+export async function noCodeChange(board, id) {
+  const checkout = await repositoryWorkspace(board, id);
   if (!checkout?.here) return null;
   const own = checkout.path;
   try {
-    const repository = originOf(own);
+    const repository = await originOf(own);
     const task = board.db.prepare('SELECT branch_name FROM tasks WHERE id=?').get(id);
-    const branch = task?.branch_name ?? (run('git', ['branch', '--show-current'], own) || null);
-    const base = run('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], own);
+    const branch = task?.branch_name ?? (await run('git', ['branch', '--show-current'], own) || null);
+    const base = await run('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], own);
     if (!repository || !branch || !base || branch === base.replace(/^origin\//, '')) return null;
     if (registeredBranches(board, id).some((r) => r.repository !== repository || r.branch !== branch)) return null;
     // Uncommitted work in the checkout is code not yet committed: a dirty worktree is never no-code.
-    if (run('git', ['status', '--porcelain', '--untracked-files=normal'], own)) return null;
+    if (await run('git', ['status', '--porcelain', '--untracked-files=normal'], own)) return null;
     // An unknown local or remote commit is code this checkout cannot see: run() throws and the arc waits.
-    if (run('git', ['for-each-ref', '--format=%(refname)', `refs/heads/${branch}`], own)) run('git', ['merge-base', '--is-ancestor', `refs/heads/${branch}`, base], own);
-    const remote = run('git', ['ls-remote', 'origin', `refs/heads/${branch}`], own).split(/\s+/)[0];
-    if (remote) run('git', ['merge-base', '--is-ancestor', remote, base], own);
+    if (await run('git', ['for-each-ref', '--format=%(refname)', `refs/heads/${branch}`], own)) await run('git', ['merge-base', '--is-ancestor', `refs/heads/${branch}`, base], own);
+    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];
-    if (github(`/repos/${repository}/pulls?state=all&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=1`).length) return null;
+    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; }
 }
 
 /** The repositories this machine keeps a checkout of. */
-function knownRepositories() {
-  try { return [...new Set(branchCheckouts(null, '*').map((row) => row.repository))]; } catch { return []; }
+async function knownRepositories() {
+  try { return [...new Set((await branchCheckouts(null, '*')).map((row) => row.repository))]; } catch { return []; }
 }
 
 /** Whether the arc's open PRs (`[{ url, head }]`) call for its review: some head no verdict judged that is new work.
@@ -255,7 +250,7 @@ function knownRepositories() {
  *  committed after that verdict (a new PR carrying the fixes, or any PR after a verdict that named none). A PR that
  *  joins with a head committed before the verdict is not: after changes are requested the next run is the
  *  implementer's until it pushes. */
-export function reviewDue(board, id, prs) {
+export async function reviewDue(board, id, prs) {
   const unjudged = prs.filter((p) => !judgedHead(board, id, p.head));
   if (!unjudged.length) return false;
   const voided = board.db.prepare("SELECT r.payload FROM task_events v JOIN task_events r ON r.id=json_extract(v.payload,'$.review_request') AND r.task_id=v.task_id WHERE v.task_id=? AND v.kind='review_voided' ORDER BY v.id DESC LIMIT 1").get(id);
@@ -268,16 +263,17 @@ export function reviewDue(board, id, prs) {
   if (!last) return true;
   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;
-  return unjudged.some((p) => (commitTime(p) ?? 0) > Number(last.verdict_at));
+  for (const p of unjudged) if (((await commitTime(p)) ?? 0) > 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. */
-function commitTime({ url, head }) {
+async function commitTime({ url, head }) {
   if (commitTimes.has(head)) return commitTimes.get(head);
   let at = null;
   try {
-    at = Math.floor(Date.parse(github(`/repos/${repositoryOf(url)}/commits/${head}`).commit.committer.date) / 1000) || null;
+    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);
   return at;
@@ -295,15 +291,15 @@ export function judgedHead(board, id, head) {
       OR EXISTS (SELECT 1 FROM json_each(r.payload, '$.ci.prs') p WHERE json_extract(p.value, '$.commit') = ?)) ORDER BY v.id LIMIT 1`).get(id, head, head) ?? null;
 }
 
-export function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
+export async function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
   const state = { required: false, ready: true, reason: null, phase: 'source', deployed_sha: null };
   try {
     if (stage === 'completion' || stage === 'acceptance') {
       const supplied = payload.commit ?? payload.metadata?.commit;
       if (supplied) {
-        const path = repositoryWorkspace(board, id)?.path;
+        const path = (await repositoryWorkspace(board, id))?.path;
         if (!path) throw new Error('The named commit needs a resolved repository workspace.');
-        Object.assign(state, { repository: originOf(path), commit: run('git', ['rev-parse', '--verify', `${supplied}^{commit}`], path) });
+        Object.assign(state, { repository: await originOf(path), commit: await run('git', ['rev-parse', '--verify', `${supplied}^{commit}`], path) });
       }
       const candidate = stage === 'acceptance' ? reviewCandidate(board, id) : null;
       if (candidate) {
@@ -314,14 +310,14 @@ export function inspectCompletionEvidence(board, id, entry, payload = {}, stage
         const wanted = candidatePullRequests(candidate);
         if (wanted.length !== passed.length || wanted.some((w) => !passed.some((p) => p.pr.url === w.pr.url && p.commit === w.commit))) throw new Error('The current PR heads need their independent verdict before acceptance.');
         for (const w of wanted) {
-          const pr = readPullRequest(w.pr.url);
+          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 own = repositoryWorkspace(board, id);
+    const own = await repositoryWorkspace(board, id);
     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 (!own) {
@@ -338,10 +334,10 @@ export function inspectCompletionEvidence(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 = urls.map((url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage));
+    const prs = await Promise.all(urls.map((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 (!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.');
+      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.');
     } else if (asked) {
       const requested = candidatePullRequests(asked);
       if (requested.length !== prs.length || requested.some((r) => !prs.some((p) => p.pr.url === r.pr.url && p.commit === r.commit))) throw new Error('The verdict covers the requested PRs at their requested heads; a PR whose head moved needs a new review request.');
@@ -356,14 +352,14 @@ export function inspectCompletionEvidence(board, id, entry, payload = {}, stage
 }
 
 /** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
-function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
+async function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
   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 = readPullRequest(url);
-  const path = !own.here ? null : originOf(own.path) === repository && run('git', ['branch', '--show-current'], own.path) === observed.headRefName ? own.path : branchCheckout(board, id, repository, observed.headRefName);
+  const observed = await readPullRequest(url);
+  const path = !own.here ? null : 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.
   const merged = observed.state === 'MERGED';
@@ -377,11 +373,11 @@ function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
   // 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) {
-    run('git', ['check-ref-format', '--branch', branch], path);
-    if (run('git', ['rev-parse', 'HEAD'], path) !== head) throw new Error(`The head named for ${url} must be its worktree head.`);
-    const uncommitted = run('git', ['status', '--porcelain', '--untracked-files=normal'], path).split('\n').filter(Boolean);
+    await run('git', ['check-ref-format', '--branch', branch], path);
+    if (await run('git', ['rev-parse', 'HEAD'], path) !== head) throw new Error(`The head named for ${url} must be its worktree head.`);
+    const uncommitted = (await run('git', ['status', '--porcelain', '--untracked-files=normal'], path)).split('\n').filter(Boolean);
     if (uncommitted.length) throw new Error(`Commit the work in ${path} before requesting review: ${uncommitted.length} uncommitted path(s): ${uncommitted.slice(0, 5).map((l) => l.replace(/^\s*\S+\s+/, '')).join(', ')}${uncommitted.length > 5 ? ', …' : ''}`);
-    const pushed = run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path).split(/\s+/)[0];
+    const pushed = (await run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path)).split(/\s+/)[0];
     if (pushed !== head) throw new Error(`Push the exact head of ${url} before requesting review.`);
   }
   return { repository, branch, commit: head, source_sha: head, pr: { url: observed.url, number: observed.number, head, branch, base: observed.baseRefName } };
@@ -389,25 +385,25 @@ function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
 
 const digest = bytes => createHash('sha256').update(bytes).digest('hex');
 /** Read the tracked workflow revision the next serve tick will load. */
-export function workflowRevision(root) {
+export async function workflowRevision(root) {
   try {
     const workflow = realpathSync(join(root, 'workflow.yaml'));
-    const checkout = run('git', ['rev-parse', '--show-toplevel'], dirname(workflow));
-    const head = run('git', ['rev-parse', 'HEAD'], checkout);
-    const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['config', '--get', 'remote.origin.url'], checkout))?.[1];
+    const checkout = await run('git', ['rev-parse', '--show-toplevel'], dirname(workflow));
+    const head = await run('git', ['rev-parse', 'HEAD'], checkout);
+    const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(await run('git', ['config', '--get', 'remote.origin.url'], checkout))?.[1];
     const name = relative(checkout, workflow).replaceAll('\\', '/');
     const source = readFileSync(workflow, 'utf8').trimEnd();
-    if (run('git', ['show', `${head}:${name}`], checkout) !== source) return null;
+    if (await run('git', ['show', `${head}:${name}`], checkout) !== source) return null;
     // Prompts are loaded with the workflow and must belong to the same revision.
-    run('git', ['diff', '--quiet', 'HEAD', '--', name, join(dirname(name), 'prompts')], checkout);
+    await run('git', ['diff', '--quiet', 'HEAD', '--', name, join(dirname(name), 'prompts')], checkout);
     return { checkout, repository, head, workflow_hash: digest(source), started_at: Date.now(), pid: process.pid };
   } catch { return null; }
 }
 
 /** Only the retained serve loop calls this after a successful tick. */
-export function retainWorkflowTick(root, before) {
+export async function retainWorkflowTick(root, before) {
   if (!before) return null;
-  const after = workflowRevision(root);
+  const after = await workflowRevision(root);
   if (!after || after.head !== before.head || after.workflow_hash !== before.workflow_hash) return null;
   const receipt = { ...before, completed_at: Date.now() };
   const path = join(root, 'runtime-deployment.json'), temporary = `${path}.${process.pid}.tmp`;