@futurelastic/colab-handbook 1.12.0-rc.56 → 1.12.0-rc.57

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.56"
30
+ "version": "1.12.0-rc.57"
31
31
  }
package/tools/colab CHANGED
@@ -46,6 +46,7 @@ const ciCure = require('./lib/ci-cure');
46
46
  const ciVerdict = require('./lib/ci-verdict');
47
47
  const baseCiVerdict = require('./lib/base-ci-verdict');
48
48
  const treeGreen = require('./lib/tree-green');
49
+ const ciWait = require('./lib/ci-wait'); // #495
49
50
  const staleBase = require('./lib/stale-base');
50
51
  const dirtyOwner = require('./lib/dirty-owner');
51
52
  const scratchDirs = require('./lib/scratch-dirs');
@@ -13648,7 +13649,8 @@ function shipBatchMemberTail({ repoAbs, doc, trunk, sess, sha, closeIssues, refs
13648
13649
  // trunk nobody owns" check and §5's "Trunk CI is alive" bullet call this instead of keeping a
13649
13650
  // `gh run list` filter of their own — two rules for one question disagreed, and the red went
13650
13651
  // unowned (a sha with CI green and a release workflow red read GREEN to triage, not-green to ship).
13651
- const HELP_TRUNK_CI = `colab trunk-ci [--repo <path>] [--json]
13652
+ const TRUNK_CI_TTL_DEFAULT_SEC = 45;
13653
+ const HELP_TRUNK_CI = `colab trunk-ci [--repo <path>] [--fresh] [--json]
13652
13654
 
13653
13655
  Print the trunk-CI verdict \`colab ship\` would compute for the trunk's CURRENT remote head —
13654
13656
  the same read (shipCiCheck's readCiVerdict): by branch, re-read by commit when empty, runs from
@@ -13670,7 +13672,15 @@ A GREEN whose suite the CI guard skipped because a green run of the same workflo
13670
13672
  passed an identical tree (#493) names that run in its detail ("relied on <url>"). If the cited
13671
13673
  head is local and its tree differs from trunk's, the read is RED: trunk is untested.
13672
13674
 
13673
- --json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip] }
13675
+ Cost (#495): one REST read of the runs at the sha (\`actions/runs?head_sha=\`), plus one
13676
+ check-runs read on a GREEN. No auth probe in front of it — the read is the probe, and an
13677
+ UNREADABLE explains which credential/remote condition failed. The verdict is cached per
13678
+ trunk+sha for ${TRUNK_CI_TTL_DEFAULT_SEC}s in the repo's git dir, shared by every session on the
13679
+ checkout (COLAB_TRUNK_CI_TTL=<sec> overrides, 0 disables; --fresh skips the cache for one read).
13680
+ To WAIT for CI, use \`colab ci-wait\` — never a loop around this command.
13681
+
13682
+ --fresh ignore a cached verdict (still refreshes the cache)
13683
+ --json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip][, cachedAgeSec] }
13674
13684
  Exit 0 whenever a verdict was read (whatever it is); 2 on UNREADABLE.`;
13675
13685
 
13676
13686
  /** Map readCiVerdict's result to the closed trunk-ci vocabulary. Pure — exported for tests. */
@@ -13686,22 +13696,182 @@ function trunkCiToken(r) {
13686
13696
  function cmdTrunkCi(argv) {
13687
13697
  const opts = parseArgs(argv, {
13688
13698
  values: { '--repo': 'repo' },
13689
- flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
13699
+ flags: { '--json': 'json', '--fresh': 'fresh', '-h': 'help', '--help': 'help' },
13690
13700
  });
13691
13701
  if (opts.help) return print(HELP_TRUNK_CI);
13692
13702
  const repoAbs = resolveRepo(opts);
13693
13703
  if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo`);
13694
13704
  const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
13695
13705
  if (!trunk) throw new UserError('cannot resolve trunk — no `trunk:` in .github/project.yml and no origin/HEAD');
13696
- const r = readCiVerdict(repoAbs, isGhUsable(repoAbs), trunk, trunk);
13697
- const verdict = trunkCiToken(r);
13698
- const sha = r.run ? r.run.sha || null : null;
13706
+
13707
+ // #495: the cache key is the trunk's CURRENT remote head — read with `git ls-remote`, which is the
13708
+ // git protocol, not the REST quota — so a new push is never answered from an older sha's verdict.
13709
+ const cache = trunkCiCache(repoAbs);
13710
+ const headSha = remoteHeadSha(repoAbs, trunk);
13711
+ const key = headSha ? `${trunk}@${headSha}` : null;
13712
+ let out = key && !opts.fresh ? cache.get(key) : null;
13713
+ if (!out) {
13714
+ // #495: no `gh auth status` probe in front of the read (it costs a REST + a GraphQL call per
13715
+ // process, and trunk-ci runs as a fresh process each time). The read itself proves the credential;
13716
+ // only an UNREADABLE pays for the explanation.
13717
+ const gh = git.ghInstalled() && !!git.remoteUrl(repoAbs);
13718
+ const r = readCiVerdict(repoAbs, gh, trunk, trunk);
13719
+ const verdict = trunkCiToken(r);
13720
+ const sha = r.run ? r.run.sha || null : null;
13721
+ let detail = r.verdict.detail;
13722
+ if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
13723
+ out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) };
13724
+ if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
13725
+ }
13699
13726
  if (opts.json) {
13700
- print(JSON.stringify({ verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail: r.verdict.detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) }, null, 2));
13727
+ print(JSON.stringify(out, null, 2));
13701
13728
  } else {
13702
- print(`${verdict} ${trunk}${sha ? `@${shortSha(sha)}` : ''} — ${r.verdict.detail}`);
13729
+ const age = out.cachedAgeSec !== undefined ? ` (cached ${out.cachedAgeSec}s ago)` : '';
13730
+ print(`${out.verdict} ${trunk}${out.sha ? `@${shortSha(out.sha)}` : ''} — ${out.detail}${age}`);
13731
+ }
13732
+ return out.verdict === 'UNREADABLE' ? 2 : 0;
13733
+ }
13734
+
13735
+ /** `git ls-remote <remote> refs/heads/<branch>` → sha, or null. Git protocol — no REST quota. */
13736
+ function remoteHeadSha(repoAbs, branch) {
13737
+ const remote = git.remoteInfo(repoAbs).name || 'origin';
13738
+ const r = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
13739
+ if (!r.ok) return null;
13740
+ return (r.stdout.split('\n')[0] || '').split('\t')[0].trim() || null;
13741
+ }
13742
+
13743
+ /**
13744
+ * #495: the trunk-ci verdict cache — `<git common dir>/colab-trunk-ci.json`, so every session and
13745
+ * worktree on one checkout shares it. Keyed by `<trunk>@<sha>`; an entry older than the TTL is a
13746
+ * miss. Best effort both ways: an unreadable/unwritable file is simply no cache.
13747
+ */
13748
+ function trunkCiCache(repoAbs) {
13749
+ const env = process.env.COLAB_TRUNK_CI_TTL;
13750
+ const ttl = env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : TRUNK_CI_TTL_DEFAULT_SEC;
13751
+ const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
13752
+ const file = dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-trunk-ci.json') : null;
13753
+ const load = () => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch (_) { return {}; } };
13754
+ return {
13755
+ get(key) {
13756
+ if (!file || ttl <= 0) return null;
13757
+ const e = load()[key];
13758
+ if (!e || !e.at || !e.out) return null;
13759
+ const age = Math.floor((Date.now() - e.at) / 1000);
13760
+ return age >= 0 && age < ttl ? { ...e.out, cachedAgeSec: age } : null;
13761
+ },
13762
+ put(key, out) {
13763
+ if (!file || ttl <= 0) return;
13764
+ const now = Date.now();
13765
+ const all = load();
13766
+ for (const k of Object.keys(all)) if (!all[k] || now - all[k].at > ttl * 1000) delete all[k];
13767
+ all[key] = { at: now, out };
13768
+ try {
13769
+ const tmp = `${file}.${process.pid}.tmp`;
13770
+ fs.writeFileSync(tmp, JSON.stringify(all));
13771
+ fs.renameSync(tmp, file);
13772
+ } catch (_) { /* no cache, not an error */ }
13773
+ },
13774
+ };
13775
+ }
13776
+
13777
+ // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
13778
+ // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
13779
+ // requests, a deadline, and a distinct exit code for every way a wait can end.
13780
+ const HELP_CI_WAIT = `colab ci-wait <run-id> | --sha <sha> [--branch <b>] [--repo <path>] [--timeout <dur>] [--json]
13781
+
13782
+ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand-roll a
13783
+ \`sleep N; gh run view\` loop, never run two waits for the same run, never hide gh's stderr.
13784
+
13785
+ <run-id> wait for one workflow run (actions/runs/<id>)
13786
+ --sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
13787
+ newest run per workflow, dynamic workflows dropped — #451/#461); a sha with no
13788
+ run yet counts as pending until the deadline
13789
+ --branch <b> narrow --sha to runs on that branch
13790
+ --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
13791
+
13792
+ Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
13793
+ conditional request (If-None-Match); a 304 is not counted against the REST rate limit. A 15-minute
13794
+ run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
13795
+
13796
+ Exit codes — branch on these, never on the text:
13797
+ 0 GREEN the run (every judged run at the sha) succeeded
13798
+ 1 RED completed and did not succeed
13799
+ 2 usage bad arguments
13800
+ 3 TIMEOUT the deadline passed while still pending
13801
+ 4 RATE_LIMITED GitHub refused for quota (403/429) — the wait ENDS, it does not retry
13802
+ 5 UNKNOWN a read failed or returned a state it cannot classify
13803
+ 6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
13804
+
13805
+ It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
13806
+ --json { outcome, exit, target, polls, notModified, waitedSec, detail, status, conclusion, url }`;
13807
+
13808
+ function cmdCiWait(argv) {
13809
+ const opts = parseArgs(argv, {
13810
+ values: { '--repo': 'repo', '--sha': 'sha', '--branch': 'branch', '--timeout': 'timeout' },
13811
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
13812
+ });
13813
+ if (opts.help) return print(HELP_CI_WAIT);
13814
+ const runId = opts._ && opts._[0];
13815
+ if ((runId ? 1 : 0) + (opts.sha ? 1 : 0) !== 1 || (runId && !/^\d+$/.test(runId)) || (opts.branch && !opts.sha)) {
13816
+ warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
13817
+ return ciWait.EXIT.USAGE;
13818
+ }
13819
+ const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
13820
+ if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
13821
+ const repoAbs = resolveRepo(opts);
13822
+ if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
13823
+
13824
+ const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
13825
+ const apiPath = runId
13826
+ ? `repos/{owner}/{repo}/actions/runs/${runId}`
13827
+ : `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
13828
+
13829
+ const gitDir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
13830
+ const lock = gitDir.ok ? ciWait.acquireLock(path.join(gitDir.stdout.trim(), 'colab-ci-wait'), runId || `${opts.sha}-${opts.branch || ''}`) : { ok: true, release: () => {} };
13831
+ if (!lock.ok) {
13832
+ warn(`another ci-wait (pid ${lock.holder}) is already waiting on ${target} in this checkout — read its result, do not start a second wait`);
13833
+ return ciWait.EXIT.ALREADY_WAITING;
13834
+ }
13835
+
13836
+ const poll = (etag) => {
13837
+ const r = git.ghApiConditional(repoAbs, apiPath, etag);
13838
+ if (r.kind !== 'ok') return r;
13839
+ let summary;
13840
+ if (runId) {
13841
+ summary = { status: r.json.status, conclusion: r.json.conclusion || null, url: r.json.html_url || null };
13842
+ } else {
13843
+ const rows = Array.isArray(r.json.workflow_runs) ? r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === opts.sha) : null;
13844
+ if (!rows) return { kind: 'error', status: r.status, detail: 'response has no workflow_runs' };
13845
+ summary = git.summarizeRunsForCommit(rows, opts.sha);
13846
+ const pick = rows.find((x) => x.databaseId === summary.databaseId);
13847
+ summary = { ...summary, url: pick ? pick.url : null };
13848
+ }
13849
+ return { ...r, summary, state: ciWait.runState(summary) };
13850
+ };
13851
+
13852
+ if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}; polls at +0s, +30s, +60s, then every 120s)\n`);
13853
+ let res;
13854
+ try {
13855
+ res = ciWait.waitLoop({
13856
+ poll, sleep: ciWait.sleepSync, deadlineSec,
13857
+ onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}\n`); },
13858
+ });
13859
+ } finally {
13860
+ lock.release();
13861
+ }
13862
+ const s = (res.last && res.last.summary) || {};
13863
+ const code = ciWait.EXIT[res.outcome];
13864
+ const out = {
13865
+ outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
13866
+ waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
13867
+ status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
13868
+ };
13869
+ if (opts.json) print(JSON.stringify(out, null, 2));
13870
+ else {
13871
+ print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
13872
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}`);
13703
13873
  }
13704
- return verdict === 'UNREADABLE' ? 2 : 0;
13874
+ return code;
13705
13875
  }
13706
13876
 
13707
13877
  const HELP_LANDED = `colab landed [--repo <path>] [--worktree <name> | --branch <br>] [--base <br>] [--all] [--json]
@@ -14527,8 +14697,12 @@ Commands:
14527
14697
  code-wrap Phase B → the branch's recorded base (trunk, or a
14528
14698
  declared line). --json (--dry only): machine-readable
14529
14699
  preconditions with a closed refusal-class vocabulary (#77)
14530
- trunk-ci [--json] the trunk-CI verdict ship computes, read-only (#463):
14700
+ trunk-ci [--fresh] [--json] the trunk-CI verdict ship computes, read-only (#463):
14531
14701
  GREEN | RED | PENDING | WEDGED | NONE | UNREADABLE
14702
+ (cached per sha ~45s in .git — #495)
14703
+ ci-wait <run-id> | --sha S [--branch B] [--timeout D] [--json]
14704
+ WAIT for CI with backoff + conditional requests (#495);
14705
+ exit 0 green · 1 red · 3 timeout · 4 rate-limited · 5 unknown
14532
14706
  landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
14533
14707
  (the shared rule behind code-sweep's buckets — correct
14534
14708
  across squash merges, where "commits ahead" is not)
@@ -14617,6 +14791,7 @@ function main(argv) {
14617
14791
  case 'ship': return cmdShip(rest);
14618
14792
  case 'landed': return cmdLanded(rest);
14619
14793
  case 'trunk-ci': return cmdTrunkCi(rest);
14794
+ case 'ci-wait': return cmdCiWait(rest);
14620
14795
  case 'holders': return cmdHolders(rest);
14621
14796
  case 'promote': return cmdPromote(rest);
14622
14797
  case 'deliver': return cmdDeliver(rest);
@@ -0,0 +1,201 @@
1
+ 'use strict';
2
+ /**
3
+ * #495 — one CI-wait primitive, so no agent hand-rolls a `sleep N; gh run …` loop again.
4
+ *
5
+ * Measured over one hour on one fleet: ~88% of ~4,500 REST calls on a shared agent identity were
6
+ * agents waiting for CI in their own shell loops — `sleep 5`–`sleep 20` around `gh run view` /
7
+ * `gh run list` / `colab trunk-ci`, two loops on the same run, one orphaned loop polling for 5½ h
8
+ * with its stderr thrown away, and a loop that read a rate-limit error as "keep waiting". The quota
9
+ * (5,000/h) ran out and every agent's `gh` call failed for the rest of the hour.
10
+ *
11
+ * What this module fixes, by construction:
12
+ * - backoff, not a fixed interval: 30 s → 60 s → 120 s, then 120 s until a deadline. A 15-minute
13
+ * run costs ~10 polls instead of ~180 at `sleep 5`;
14
+ * - conditional requests: every poll after the first sends `If-None-Match`, and a `304 Not
15
+ * Modified` is not counted against the primary rate limit (GitHub REST docs, "conditional
16
+ * requests");
17
+ * - a rate limit (403 with remaining 0, or 429) ENDS the wait with its own outcome — never a retry;
18
+ * - an unreadable or unrecognised state ends it too (UNKNOWN), never "keep waiting";
19
+ * - one wait per run per checkout: a second waiter on the same key is refused (ALREADY_WAITING).
20
+ *
21
+ * The loop is pure over injected `poll` / `sleep` / `now`, so the cost of a 15-minute wait is a
22
+ * unit test, not a guess. The `gh` transport lives in git.js (`ghApiConditional`).
23
+ */
24
+
25
+ const fs = require('fs');
26
+ const path = require('path');
27
+
28
+ /** Exit codes of `colab ci-wait` — one per outcome, so a caller branches on `$?`, never on text. */
29
+ const EXIT = Object.freeze({
30
+ GREEN: 0,
31
+ RED: 1,
32
+ USAGE: 2,
33
+ TIMEOUT: 3,
34
+ RATE_LIMITED: 4,
35
+ UNKNOWN: 5,
36
+ ALREADY_WAITING: 6,
37
+ });
38
+
39
+ const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
40
+ const DEFAULT_DEADLINE_SEC = 45 * 60;
41
+
42
+ /** Seconds to sleep before poll number `i` (0-based, i ≥ 1); the last step repeats. */
43
+ function delayFor(i, schedule = DEFAULT_SCHEDULE_SEC) {
44
+ if (i <= 0) return 0;
45
+ return schedule[Math.min(i - 1, schedule.length - 1)];
46
+ }
47
+
48
+ /**
49
+ * Parse `gh api -i` stdout: status line, headers, blank line, body. gh prints the head to stdout
50
+ * on a non-2xx too (a 304 exits 1 with `gh: HTTP 304` on stderr — measured), so this is read
51
+ * whatever the exit code. Returns `{ status, headers, body }`; status null when no head was found.
52
+ */
53
+ function parseHttp(stdout) {
54
+ const text = String(stdout || '');
55
+ const m = /^HTTP\/[\d.]+\s+(\d{3})[^\n]*\n/.exec(text);
56
+ if (!m) return { status: null, headers: {}, body: text };
57
+ const rest = text.slice(m[0].length);
58
+ const split = rest.search(/\r?\n\r?\n/);
59
+ const head = split === -1 ? rest : rest.slice(0, split);
60
+ const body = split === -1 ? '' : rest.slice(split).replace(/^\r?\n\r?\n/, '');
61
+ const headers = {};
62
+ for (const line of head.split(/\r?\n/)) {
63
+ const i = line.indexOf(':');
64
+ if (i > 0) headers[line.slice(0, i).trim().toLowerCase()] = line.slice(i + 1).trim();
65
+ }
66
+ return { status: Number(m[1]), headers, body };
67
+ }
68
+
69
+ /**
70
+ * Classify one response: `ok` (2xx, body parsed) · `not-modified` (304) · `rate-limited` (429, or
71
+ * 403 with `x-ratelimit-remaining: 0`, or gh's own "rate limit" text) · `error` (anything else).
72
+ */
73
+ function classifyResponse({ status, headers = {}, body, stderr = '' }) {
74
+ const remaining = headers['x-ratelimit-remaining'];
75
+ const resetAt = headers['x-ratelimit-reset'] ? Number(headers['x-ratelimit-reset']) * 1000 : null;
76
+ if (status === 429 || (status === 403 && (remaining === '0' || /rate limit/i.test(String(body) + stderr)))
77
+ || (status === null && /rate limit/i.test(stderr))) {
78
+ return { kind: 'rate-limited', status, resetAt, detail: firstLine(stderr) || `HTTP ${status}` };
79
+ }
80
+ if (status === 304) return { kind: 'not-modified', status, etag: headers.etag || null };
81
+ if (status !== null && status >= 200 && status < 300) {
82
+ let json;
83
+ try { json = JSON.parse(body); } catch (_) { return { kind: 'error', status, detail: 'unparseable body' }; }
84
+ return { kind: 'ok', status, etag: headers.etag || null, json };
85
+ }
86
+ return { kind: 'error', status, detail: firstLine(stderr) || (status ? `HTTP ${status}` : 'no response') };
87
+ }
88
+
89
+ function firstLine(s) { return String(s || '').split('\n').map((x) => x.trim()).find(Boolean) || ''; }
90
+
91
+ /** A REST workflow-run object → the row shape git.summarizeRunsForCommit reads (`gh run list --json`). */
92
+ function restRow(x) {
93
+ return {
94
+ headSha: x.head_sha, status: x.status, conclusion: x.conclusion || null,
95
+ createdAt: x.created_at || null, databaseId: x.id, workflowName: x.name || null,
96
+ event: x.event || null, url: x.html_url || null,
97
+ };
98
+ }
99
+
100
+ /**
101
+ * The state of what is being waited on, from a summarized run (`{status, conclusion}`):
102
+ * `green` · `red` · `pending` · `unknown`. `none` (no run at the sha yet) is pending: runs appear
103
+ * seconds after a push, and the deadline bounds the wait if they never do.
104
+ */
105
+ function runState(s) {
106
+ if (!s) return 'unknown';
107
+ if (s.status === 'none') return 'pending';
108
+ if (s.status === 'completed') return s.conclusion === 'success' ? 'green' : 'red';
109
+ if (['queued', 'in_progress', 'waiting', 'requested', 'pending'].includes(s.status)) return 'pending';
110
+ return 'unknown';
111
+ }
112
+
113
+ /**
114
+ * The wait loop. `poll(etag)` returns a classifyResponse() result, plus `state` (runState) and
115
+ * `summary` on `ok`. `sleep(ms)` blocks; `now()` is epoch ms. A 304 keeps the previous state.
116
+ *
117
+ * Returns `{ outcome, polls, notModified, waitedMs, last, detail }`, outcome one of the EXIT keys.
118
+ */
119
+ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_SEC,
120
+ schedule = DEFAULT_SCHEDULE_SEC, onPoll = () => {} }) {
121
+ const start = now();
122
+ let etag = null;
123
+ let last = null;
124
+ let polls = 0;
125
+ let notModified = 0;
126
+ for (let i = 0; ; i++) {
127
+ const d = delayFor(i, schedule) * 1000;
128
+ if (d) {
129
+ const left = start + deadlineSec * 1000 - now();
130
+ if (left <= 0) return done('TIMEOUT', `still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
131
+ sleep(Math.min(d, left));
132
+ }
133
+ const r = poll(etag);
134
+ polls++;
135
+ if (r.kind === 'rate-limited') return done('RATE_LIMITED', r.detail + (r.resetAt ? ` — quota resets ${new Date(r.resetAt).toISOString()}` : ''), r);
136
+ if (r.kind === 'error') return done('UNKNOWN', `read failed: ${r.detail}`, r);
137
+ if (r.kind === 'not-modified') {
138
+ notModified++;
139
+ if (!last) return done('UNKNOWN', '304 on the first read — nothing to compare against', r);
140
+ } else {
141
+ etag = r.etag || etag;
142
+ last = r;
143
+ }
144
+ onPoll({ poll: polls, state: last.state, notModified: r.kind === 'not-modified', elapsedMs: now() - start });
145
+ if (last.state === 'green') return done('GREEN', null);
146
+ if (last.state === 'red') return done('RED', null);
147
+ if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
148
+ if (now() - start >= deadlineSec * 1000) return done('TIMEOUT', `still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
149
+ }
150
+ function done(outcome, detail, r) {
151
+ return { outcome, polls, notModified, waitedMs: now() - start, last: last || r || null, detail };
152
+ }
153
+ }
154
+
155
+ function fmtDuration(ms) {
156
+ const s = Math.round(ms / 1000);
157
+ const m = Math.floor(s / 60);
158
+ return m ? `${m}m${String(s % 60).padStart(2, '0')}s` : `${s}s`;
159
+ }
160
+
161
+ /** Parse `--timeout`: `45m`, `90s`, `1h`, or bare seconds. Null when unparseable. */
162
+ function parseDuration(v) {
163
+ const m = /^(\d+)\s*([smh]?)$/.exec(String(v || '').trim());
164
+ if (!m) return null;
165
+ return Number(m[1]) * ({ '': 1, s: 1, m: 60, h: 3600 })[m[2]];
166
+ }
167
+
168
+ /**
169
+ * One wait per key per checkout. The lock is `<dir>/ci-wait-<key>.lock` holding the waiter's pid;
170
+ * a lock whose pid is dead is taken over. Returns `{ ok, holder, release }`.
171
+ */
172
+ function acquireLock(dir, key, pid = process.pid, alive = pidAlive) {
173
+ const file = path.join(dir, `ci-wait-${String(key).replace(/[^A-Za-z0-9._-]/g, '_')}.lock`);
174
+ try { fs.mkdirSync(dir, { recursive: true }); } catch (_) { /* best effort */ }
175
+ for (let attempt = 0; attempt < 2; attempt++) {
176
+ try {
177
+ fs.writeFileSync(file, String(pid), { flag: 'wx' });
178
+ return { ok: true, file, release: () => { try { fs.unlinkSync(file); } catch (_) {} } };
179
+ } catch (e) {
180
+ if (e.code !== 'EEXIST') return { ok: true, file: null, release: () => {} }; // cannot lock: do not block the wait
181
+ const holder = Number(String(safeRead(file)).trim());
182
+ if (holder && holder !== pid && alive(holder)) return { ok: false, holder, file, release: () => {} };
183
+ try { fs.unlinkSync(file); } catch (_) {}
184
+ }
185
+ }
186
+ return { ok: true, file: null, release: () => {} };
187
+ }
188
+
189
+ function safeRead(f) { try { return fs.readFileSync(f, 'utf8'); } catch (_) { return ''; } }
190
+ function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } }
191
+
192
+ /** Blocking sleep without a busy loop — the CLI's main() is synchronous. */
193
+ function sleepSync(ms) {
194
+ if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
195
+ }
196
+
197
+ module.exports = {
198
+ EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC,
199
+ delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
200
+ acquireLock, sleepSync,
201
+ };
package/tools/lib/git.js CHANGED
@@ -858,6 +858,14 @@ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name ||
858
858
  function ghRunsForCommit(repo, branch, sha, limit = 10) {
859
859
  if (!sha) return null;
860
860
 
861
+ // #495: one REST call (`actions/runs?head_sha=&branch=`) instead of `gh run list`'s two (runs +
862
+ // workflows), and no `-L` window to fall out of. A rate limit is final — falling back would spend
863
+ // two more calls on a quota that is already gone. Any other failure (an old gh, a test stub that
864
+ // only answers `run list`, a non-GitHub remote) falls through to the `gh run list` read below.
865
+ const rest = ghRunsAtShaRest(repo, sha, branch);
866
+ if (rest.rows) return rest.rows;
867
+ if (rest.rateLimited) return null;
868
+
861
869
  // createdAt + databaseId are additive (#155): a NON-completed pick needs both to let a caller
862
870
  // judge whether it is merely slow or structurally WEDGED (tools/lib/ci-verdict.js) — createdAt for
863
871
  // the age backstop, databaseId to look up its job count (ghRunJobCount, below — a second call, made
@@ -884,6 +892,44 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
884
892
  return forSha;
885
893
  }
886
894
 
895
+ /**
896
+ * #495: `gh api -i <path>`, optionally conditional (`If-None-Match: <etag>`). Returns the
897
+ * classified response from tools/lib/ci-wait.js: `{ kind: ok|not-modified|rate-limited|error,
898
+ * status, etag, json?, detail? }`. A 304 does not count against the REST primary rate limit, so a
899
+ * poller that sends its last ETag pays for a read only when something changed. gh exits 1 on a 304
900
+ * and still prints the head to stdout (measured), so the head is parsed whatever the exit code.
901
+ */
902
+ function ghApiConditional(repo, apiPath, etag) {
903
+ const ciWait = require('./ci-wait');
904
+ const args = ['api', '-i', ...(etag ? ['-H', `If-None-Match: ${etag}`] : []), apiPath];
905
+ const r = run('gh', args, { cwd: repo, timeoutMs: 60000 });
906
+ const http = ciWait.parseHttp(r.stdout);
907
+ return ciWait.classifyResponse({ ...http, stderr: r.stderr });
908
+ }
909
+
910
+ /**
911
+ * Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
912
+ * rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
913
+ * rate limit, `{}` on any other failure (the caller decides whether to fall back).
914
+ */
915
+ function ghRunsAtShaRest(repo, sha, branch) {
916
+ if (!sha) return {};
917
+ const ciWait = require('./ci-wait');
918
+ const q = `head_sha=${encodeURIComponent(sha)}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}&per_page=100`;
919
+ const r = ghApiConditional(repo, `repos/{owner}/{repo}/actions/runs?${q}`);
920
+ if (r.kind === 'rate-limited') return { rateLimited: true, detail: r.detail };
921
+ if (r.kind !== 'ok' || !r.json || !Array.isArray(r.json.workflow_runs)) return {};
922
+ return { rows: r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === sha) };
923
+ }
924
+
925
+ /** Is a `gh` binary on PATH (#495)? No API call — cached per process. The credential is proven by
926
+ * the first real read, not by a probe in front of it (`gh auth status` costs a REST + a GraphQL). */
927
+ let _ghInstalled;
928
+ function ghInstalled() {
929
+ if (_ghInstalled === undefined) _ghInstalled = run('gh', ['--version']).ok;
930
+ return _ghInstalled;
931
+ }
932
+
887
933
  /**
888
934
  * Every run on `ref` at `sha`, WITH its `attempt` (#373). A sibling of ghRunsForCommit, not a change
889
935
  * to its field list: batch landing needs the attempt number to enforce "re-run a red:infra ONCE", and
@@ -1218,7 +1264,7 @@ module.exports = {
1218
1264
  claimRemote, remoteHeads,
1219
1265
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1220
1266
  dirtyTracked, dirtyUntracked, dirtyAny,
1221
- ghAvailable, ghState, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1267
+ ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1222
1268
  ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1223
1269
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1224
1270
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,