@volter/supercode-orchestrator 0.5.73 → 0.5.74

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`;

package/board/cli.mjs

@@ -14,7 +14,7 @@ import { taskStatusOf } from './published.mjs';
 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';
-import { spawnSync } from 'node:child_process';
+import { execFile, spawnSync } from 'node:child_process';
 import { holdLock } from './lock-holder.mjs';
 import { takeEpoch } from './fence.mjs';
 import { dispatcherNotice, holdOwnerHealth, holdRound, holdSwitch } from './owner-health.mjs';
@@ -28,19 +28,23 @@ import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
 
+// A mailbox read through the mailbox's own command, awaited (never a wait that holds the event loop). Gap A31: a
+// helper process until the daemon owns mail (order 3 PR 4).
+const mailRead = (verb) => new Promise((resolve) => execFile(supercodeBin(), ['message', verb, '--json'], { encoding: 'utf8', env: commandEnv(), timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }, (_, stdout) => resolve(stdout ?? '')));
+
 /** The messages on this machine the mailbox still has to deliver (`supercode message waiting`), by message id. */
-function mailWaiting() {
-  const r = spawnSync(supercodeBin(), ['message', 'waiting', '--json'], { encoding: 'utf8', env: commandEnv(), timeout: 15_000 });
-  try { return new Map((JSON.parse(r.stdout) ?? []).map((mail) => [mail.id, mail])); } catch { return new Map(); }
+async function mailWaiting() {
+  const stdout = await mailRead('waiting');
+  try { return new Map((JSON.parse(stdout) ?? []).map((mail) => [mail.id, mail])); } catch { return new Map(); }
 }
 
 /**
  * The messages on this machine whose delivery the mailbox gave up on (`supercode message expired`), by message id:
  * filed by the board, never delivered within the mailbox's bound, kept unread. Empty when the mailbox does not answer.
  */
-function mailExpiries() {
-  const r = spawnSync(supercodeBin(), ['message', 'expired', '--json'], { encoding: 'utf8', env: commandEnv(), timeout: 15_000 });
-  try { return new Map((JSON.parse(r.stdout) ?? []).map((expiry) => [expiry.id, expiry])); } catch { return new Map(); }
+async function mailExpiries() {
+  const stdout = await mailRead('expired');
+  try { return new Map((JSON.parse(stdout) ?? []).map((expiry) => [expiry.id, expiry])); } catch { return new Map(); }
 }
 
 /**
@@ -319,34 +323,6 @@ const metadataOf = (v) => {
   return got;
 };
 
-/**
- * What is wrong with this orchestrator's version, or null: a build no release names (a hand install of a branch) or one
- * older than npm's latest. Every workflow call says it and the dispatcher tells its managers; action is required until
- * the release is installed. The latest is read from the registry at most once an hour.
- */
-function releaseBehind() {
-  let running;
-  try { running = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version; } catch { return null; }
-  const cache = join(tmpdir(), 'supercode-orchestrator-latest.json');
-  let latest = null;
-  let fresh = false;
-  try { const seen = JSON.parse(readFileSync(cache, 'utf8')); if (Date.now() - seen.at < 3_600_000) { fresh = true; latest = seen.latest; } } catch { /* read below */ }
-  if (!fresh) {
-    // a failed read is kept for the hour too: offline, no call waits on the registry more than once an hour
-    const r = spawnSync('npm', ['view', '@volter/supercode-orchestrator', 'version'], { encoding: 'utf8', timeout: 5000 });
-    latest = r.status === 0 ? r.stdout.trim() || null : null;
-    try { writeFileSync(cache, JSON.stringify({ at: Date.now(), latest })); } catch { /* read again next call */ }
-  }
-  if (!latest || running === latest) return null;
-  const parts = (v) => v.split('-')[0].split('.').map(Number);
-  const [a, b] = [parts(running), parts(latest)];
-  const older = a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
-  const fix = `npm install -g @volter/supercode-orchestrator@${latest} (and each install's pinned copy)`;
-  if (running.includes('-')) return { key: `${running}>${latest}`, text: `orchestrator ${running} is not a published release (latest ${latest}); action required: ${fix}` };
-  if (older < 0) return { key: `${running}>${latest}`, text: `orchestrator ${running} is behind the published ${latest}; action required: ${fix}` };
-  return null;
-}
-
 /** One verb in full, in the call it runs in (call.mjs): a caller's in the owner, or the process's own here. */
 export async function runVerb(argv) {
   await knowLocalMachine();
@@ -362,7 +338,7 @@ export async function runVerb(argv) {
   const slug = viewTag ? DEFAULT_BOARD : named;
   const open = (create = false) => { const b = openBoard(root, slug, { create, document: args.document ?? null, backing: create ? args.backing ?? null : null }); b.label = boardLabel(root, slug); return b; };
   const withBoard = (fn, create = false) => { const b = open(create); try { return fn(b); } finally { b.close(); } };
-  const withBoardAsync = async (fn) => { const b = open(); try { return await fn(b); } finally { b.close(); } };
+  const withBoardAsync = async (fn, create = false) => { const b = open(create); try { return await fn(b); } finally { b.close(); } };
   const id = rest[0];
   const need = (n, what) => { if (rest.length < n) throw new Error(`${verb} needs ${what}`); };
   const ids = (first = rest) => [...first, ...(args.ids ?? [])];
@@ -380,7 +356,7 @@ export async function runVerb(argv) {
   if (sid && !READS.has(verb) && boardExists(root, slug)) {
     // binding the caller's launch is a write: only the owner, answering the caller's own verb, makes it (a local read
     // never writes)
-    withBoard((b) => { if (isCallersCall()) reconcileCallerLaunch(b, sid); const own = ownCard(b.db, sid); if (own) authorize(b.db, verb, rest, args, own); });
+    await withBoardAsync(async (b) => { if (isCallersCall()) await reconcileCallerLaunch(b, sid); const own = ownCard(b.db, sid); if (own) authorize(b.db, verb, rest, args, own); });
   }
   // the board's workflow (the IR's): what each verb does, and who may send it, is its
   // every verb reads the board through its workflow (a list settles cards too), so every verb loads it
@@ -472,7 +448,7 @@ export async function runVerb(argv) {
       // --goal / --no-goal are the create's words; without either, the workflow's initial decides
       // a person filing for themselves sponsors it; an agent filing a person's request names them (proven) or records them unverified
       const sponsorship = args.sponsor || args['requested-by'] ? await requestedSponsor(args) : principalOf()?.startsWith('person:') ? { sponsor: principalOf().slice('person:'.length) } : {};
-      const created = withBoard((b) => engine.createCard(b, {
+      const created = await withBoardAsync(async (b) => engine.createCard(b, await engine.prepareCard(b, {
         title: rest.join(' '), body: textFrom(args['body-file'], args.body), assignee: args.assignee === 'none' ? null : args.assignee, machine: args.machine,
         workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
         triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: duration(args['max-runtime']),
@@ -482,7 +458,7 @@ export async function runVerb(argv) {
         project: args.project ?? meta.project_id ?? null, goal: args.goal ? { maxTurns: args['goal-max-turns'] ? Number(args['goal-max-turns']) : null } : args['no-goal'] ? false : null,
         tags: [...(viewTag ? [viewTag] : []), ...(args.tag ?? [])],
         ...sponsorship,
-      }), true);
+      })), true);
       await withBoardAsync(b=>engine.runEffects(b,created.effects??[]));
       let answer = { id: created.id, existing: created.existing };
       if (args.adopt) {
@@ -881,10 +857,9 @@ export async function runVerb(argv) {
 
     case 'diagnostics': case 'diag': {
       const { settings } = await laneState(root).catch(() => ({ settings: boardSettings({}) }));
-      const fleet = observeFleet(root);
+      const fleet = await observeFleet(root);
       const publishing = await boardPublishing(root);
-      const expiredMail = mailExpiries();
-      const waitingMail = mailWaiting();
+      const [expiredMail, waitingMail] = await Promise.all([await mailExpiries(), await mailWaiting()]);
       const order = ['warning', 'error', 'critical'];
       const found = withBoard((b) => {
         const cards = args.task ? [engine.getTask(b.db, args.task)].filter(Boolean) : engine.listCards(b.db, {});
@@ -1146,7 +1121,7 @@ export async function runVerb(argv) {
     }
     case 'close': {
       need(1, 'a card id');
-      const closed = withBoard((b) => closeSession(b, id));
+      const closed = await withBoardAsync((b) => closeSession(b, id));
       say(args, closed ? closed.map((c) => `closed ${c.session_id} (pane ${c.pane} on ${c.machine})`).join('\n') : `${id} has no live session`, { ok: true, closed });
       return 0;
     }
@@ -1453,13 +1428,13 @@ function authorize(db, verb, rest, args, own) {
 }
 
 /** Close the live sessions of a card that is not running (its worker's and its reviewers'), freeing its machine's place. */
-function closeSession(board, id) {
+async function closeSession(board, id) {
   const task = engine.getTask(board.db, id);
   if (!task) throw new Error(`no card ${id}`);
   if (task.current_run_id != null) throw new Error(`${id} has an active run; pause, block or reclaim it before closing its session`);
   tx(board, (db) => requestSessionClose(db, id));
   const report = { undelivered: [], closed: [] };
-  closeRequested(board, report, { taskId: id, caller: callerSession() });
+  await closeRequested(board, report, { taskId: id, caller: callerSession() });
   if (report.undelivered.length) throw new Error(`close remains queued for retry: ${report.undelivered.map((r) => r[2]).join('; ')}`);
   return report.closed.length ? report.closed : null;
 }
@@ -1604,17 +1579,7 @@ async function serve(root, args = {}) {
   const FAILED_ROUNDS_ALERT = 5;
   const failing = new Map();
   let round = 0;
-  // A dispatcher that is not the published release is told up the chain, once per version pair: it keeps running, and
-  // its manager hears that action is required (a caller's stderr line alone reached no one).
-  const versionsTold = new Set();
-  const tellReleaseBehind = async () => {
-    const behind = releaseBehind();
-    if (!behind || versionsTold.has(behind.key)) return;
-    // the send's key makes a retry safe; a pair counts as told only once a manager got it
-    if (await alertManagers(root, 'default', `The dispatcher of ${root} runs ${behind.text}`, `release-behind-${behind.key}`) > 0) versionsTold.add(behind.key);
-  };
   const watchRounds = async (reports) => {
-    await tellReleaseBehind().catch(() => {});
     if (reports.every((r) => !r.error)) {
       // A publication the team refused holds this home's publishing where it is (nothing after it is skipped): a fact of
       // the same kind as rounds that stopped, so it goes where every board verb's error line reads it. Only a refusal
@@ -1660,6 +1625,9 @@ async function serve(root, args = {}) {
     onChange: (name) => log(`home changed (${name}): read again on its next use`),
     onLost: (error) => { log(`the home's files can no longer be watched (${error.message}); stopping, for the keeper to start the owner again`); stop(); },
   });
+  // Hermes's install is located once per process (a launch's memory snapshot reads it): here, before any verb is
+  // answered, so no verb or round waits on it
+  try { (await import('../hermes-cli.mjs')).hermesInstall(); } catch { /* none installed */ }
   let closeVerbs;
   try { closeVerbs = await answerVerbs(root, log); } catch (error) { unfollowHome(); throw error; }
   log(`owning the boards of ${root} on ${localMachine()} (orchestrator ${running ?? 'unknown'}); dispatching where a board's dispatching is on (\`supercode workflow dispatching\`)`);
@@ -1748,6 +1716,8 @@ async function serve(root, args = {}) {
       if (moved) { log(`orchestrator ${moved} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
     }
   } finally {
+    // a fetch in flight lands, and what it brought is merged, while this owner still holds the home's lock
+    try { const { settleDocuments } = await import('./git-document.mjs'); await settleDocuments(); } catch { /* nothing in flight */ }
     closeVerbs();
     unfollowHome();
     await closeDoors();