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

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
@@ -17,6 +17,10 @@
17
17
  "tools/colab",
18
18
  "tools/lib/*.js",
19
19
  "!tools/lib/*.test.js",
20
+ "tools/lib/codec/*.js",
21
+ "tools/lib/codec/*.d.ts",
22
+ "tools/lib/codec/samples.json",
23
+ "!tools/lib/codec/*.test.js",
20
24
  "templates/",
21
25
  "audit/audit.mjs"
22
26
  ],
@@ -27,5 +31,5 @@
27
31
  "engines": {
28
32
  "node": ">=18"
29
33
  },
30
- "version": "1.12.0-rc.56"
34
+ "version": "1.12.0-rc.58"
31
35
  }
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');
@@ -56,6 +57,7 @@ const axisAuthority = require('./lib/axis-authority');
56
57
  const writesAuthority = require('./lib/writes-authority');
57
58
  const claimIdentity = require('./lib/claim-identity');
58
59
  const claimComments = require('./lib/claim-comments');
60
+ const codec = require('./lib/codec');
59
61
  const machine = require('./lib/machine');
60
62
  const targetSync = require('./lib/ship-target-sync');
61
63
  const shipBatch = require('./lib/ship-batch');
@@ -242,9 +244,10 @@ function ghUnusableWhy(repoAbs) {
242
244
  // GitHub offers no atomic check-and-set on labels/assignees.
243
245
  // ---------------------------------------------------------------------------
244
246
 
245
- // The claim/release comment markers and parsers live in tools/lib/claim-comments.js (#369/#375) —
247
+ // The claim/release comment markers and their encode/decode pairs live in tools/lib/codec/claim.js
248
+ // (#497); the readers built on them (liveness, tie-break) in tools/lib/claim-comments.js (#369/#375) —
246
249
  // a STABLE WIRE FORMAT the refusal path, the tie-break and dashboards grep. Do not reword casually.
247
- const { CLAIM_MARK, RELEASE_MARK, liveClaimComments, tieBreakVerdict } = claimComments;
250
+ const { liveClaimComments, tieBreakVerdict } = claimComments; // the format itself: codec/claim.js (#497)
248
251
 
249
252
  /**
250
253
  * #369: may a comment colab posts to THIS repo's tracker name the host in its `host` field? The
@@ -435,14 +438,6 @@ function identityLegend(entries) {
435
438
  print(' Repair: colab worktree tag <worktree> --session <url>');
436
439
  }
437
440
 
438
- /** The ` · session …` comment suffix, or '' — keeps the no-identity comment byte-stable. */
439
- function sessionCommentSuffix(session, sessionName) {
440
- if (sessionName && session) return ` · session [${sessionName}](${session})`; // both → markdown link
441
- if (session) return ` · session ${session}`; // url only → legacy form
442
- if (sessionName) return ` · session ${sessionName}`; // name only
443
- return '';
444
- }
445
-
446
441
  /**
447
442
  * Worktree lifecycle status, backfilled-on-read: entries created before this field existed (or by
448
443
  * an older colab) render as `running`. Values: `running` (default, at create) → `merged` (branch
@@ -451,17 +446,18 @@ function sessionCommentSuffix(session, sessionName) {
451
446
  */
452
447
  function wtStatus(wt) { return (wt && wt.status) || 'running'; }
453
448
 
454
- /** The exact claim-comment body. Keep in lockstep with CLAIM_RE/parseSessionField and the README. */
449
+ /**
450
+ * The exact claim-comment body. The format itself is codec/claim.js `encodeClaim` (#497); this
451
+ * supplies what the codec deliberately does not hold — the clock and the machine digest. `-` stands
452
+ * for "no branch"/"no worktree" (#53, it used to be the word `trunk`). `host` is the raw hostname
453
+ * where the destination may name it, the `h:` token where it may not (#369, `commentHost`); the
454
+ * comparable identity is the machine digest beside it (#327), omitted when no id resolved.
455
+ */
455
456
  function claimCommentBody(wtName, branch, session, sessionName, host = HOST) {
456
- // `-` for "no branch", matching the worktree field beside it. It used to be the word `trunk`,
457
- // which read as a branch name that never existed (#53).
458
- const base = `${CLAIM_MARK} — worktree \`${wtName || '-'}\` · branch \`${branch || '-'}\` · host \`${host}\` · ${nowISO()}`;
459
- // #327: `host` is the raw hostname where the destination may name it, the `h:` token where it
460
- // may not (#369, `commentHost`); the comparable identity is the machine digest beside it.
461
- // Omitted when no id resolved.
462
- const token = machine.machineToken(myMachineId());
463
- const mach = token ? ` · machine \`${token}\`` : '';
464
- return base + mach + sessionCommentSuffix(session, sessionName);
457
+ return codec.encodeClaim({
458
+ worktree: wtName, branch, host, at: nowISO(),
459
+ machine: machine.machineToken(myMachineId()) || '', session, sessionName,
460
+ });
465
461
  }
466
462
 
467
463
  /** Issues whose EXISTING local claim sits on a different worktree than the one we're claiming onto. */
@@ -715,7 +711,7 @@ function postClaimComment(repoAbs, num, wtName, branch, session, sessionName) {
715
711
  function postReleaseComment(repoAbs, num) {
716
712
  const info = git.ghIssueView(repoAbs, num, ['state']);
717
713
  if (info && info.state === 'CLOSED') return true; // don't chatter on a closed issue
718
- const r = git.ghIssueComment(repoAbs, num, RELEASE_MARK);
714
+ const r = git.ghIssueComment(repoAbs, num, codec.encodeRelease());
719
715
  if (!r.ok) { warnDeferred(`could not post release comment on #${num} (${r.stderr.split('\n')[0] || r.code})`); return false; }
720
716
  return true;
721
717
  }
@@ -13648,7 +13644,8 @@ function shipBatchMemberTail({ repoAbs, doc, trunk, sess, sha, closeIssues, refs
13648
13644
  // trunk nobody owns" check and §5's "Trunk CI is alive" bullet call this instead of keeping a
13649
13645
  // `gh run list` filter of their own — two rules for one question disagreed, and the red went
13650
13646
  // 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]
13647
+ const TRUNK_CI_TTL_DEFAULT_SEC = 45;
13648
+ const HELP_TRUNK_CI = `colab trunk-ci [--repo <path>] [--fresh] [--json]
13652
13649
 
13653
13650
  Print the trunk-CI verdict \`colab ship\` would compute for the trunk's CURRENT remote head —
13654
13651
  the same read (shipCiCheck's readCiVerdict): by branch, re-read by commit when empty, runs from
@@ -13670,7 +13667,15 @@ A GREEN whose suite the CI guard skipped because a green run of the same workflo
13670
13667
  passed an identical tree (#493) names that run in its detail ("relied on <url>"). If the cited
13671
13668
  head is local and its tree differs from trunk's, the read is RED: trunk is untested.
13672
13669
 
13673
- --json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip] }
13670
+ Cost (#495): one REST read of the runs at the sha (\`actions/runs?head_sha=\`), plus one
13671
+ check-runs read on a GREEN. No auth probe in front of it — the read is the probe, and an
13672
+ UNREADABLE explains which credential/remote condition failed. The verdict is cached per
13673
+ trunk+sha for ${TRUNK_CI_TTL_DEFAULT_SEC}s in the repo's git dir, shared by every session on the
13674
+ checkout (COLAB_TRUNK_CI_TTL=<sec> overrides, 0 disables; --fresh skips the cache for one read).
13675
+ To WAIT for CI, use \`colab ci-wait\` — never a loop around this command.
13676
+
13677
+ --fresh ignore a cached verdict (still refreshes the cache)
13678
+ --json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip][, cachedAgeSec] }
13674
13679
  Exit 0 whenever a verdict was read (whatever it is); 2 on UNREADABLE.`;
13675
13680
 
13676
13681
  /** Map readCiVerdict's result to the closed trunk-ci vocabulary. Pure — exported for tests. */
@@ -13686,22 +13691,182 @@ function trunkCiToken(r) {
13686
13691
  function cmdTrunkCi(argv) {
13687
13692
  const opts = parseArgs(argv, {
13688
13693
  values: { '--repo': 'repo' },
13689
- flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
13694
+ flags: { '--json': 'json', '--fresh': 'fresh', '-h': 'help', '--help': 'help' },
13690
13695
  });
13691
13696
  if (opts.help) return print(HELP_TRUNK_CI);
13692
13697
  const repoAbs = resolveRepo(opts);
13693
13698
  if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo`);
13694
13699
  const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
13695
13700
  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;
13701
+
13702
+ // #495: the cache key is the trunk's CURRENT remote head — read with `git ls-remote`, which is the
13703
+ // git protocol, not the REST quota — so a new push is never answered from an older sha's verdict.
13704
+ const cache = trunkCiCache(repoAbs);
13705
+ const headSha = remoteHeadSha(repoAbs, trunk);
13706
+ const key = headSha ? `${trunk}@${headSha}` : null;
13707
+ let out = key && !opts.fresh ? cache.get(key) : null;
13708
+ if (!out) {
13709
+ // #495: no `gh auth status` probe in front of the read (it costs a REST + a GraphQL call per
13710
+ // process, and trunk-ci runs as a fresh process each time). The read itself proves the credential;
13711
+ // only an UNREADABLE pays for the explanation.
13712
+ const gh = git.ghInstalled() && !!git.remoteUrl(repoAbs);
13713
+ const r = readCiVerdict(repoAbs, gh, trunk, trunk);
13714
+ const verdict = trunkCiToken(r);
13715
+ const sha = r.run ? r.run.sha || null : null;
13716
+ let detail = r.verdict.detail;
13717
+ if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
13718
+ out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) };
13719
+ if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
13720
+ }
13699
13721
  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));
13722
+ print(JSON.stringify(out, null, 2));
13701
13723
  } else {
13702
- print(`${verdict} ${trunk}${sha ? `@${shortSha(sha)}` : ''} — ${r.verdict.detail}`);
13724
+ const age = out.cachedAgeSec !== undefined ? ` (cached ${out.cachedAgeSec}s ago)` : '';
13725
+ print(`${out.verdict} ${trunk}${out.sha ? `@${shortSha(out.sha)}` : ''} — ${out.detail}${age}`);
13726
+ }
13727
+ return out.verdict === 'UNREADABLE' ? 2 : 0;
13728
+ }
13729
+
13730
+ /** `git ls-remote <remote> refs/heads/<branch>` → sha, or null. Git protocol — no REST quota. */
13731
+ function remoteHeadSha(repoAbs, branch) {
13732
+ const remote = git.remoteInfo(repoAbs).name || 'origin';
13733
+ const r = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
13734
+ if (!r.ok) return null;
13735
+ return (r.stdout.split('\n')[0] || '').split('\t')[0].trim() || null;
13736
+ }
13737
+
13738
+ /**
13739
+ * #495: the trunk-ci verdict cache — `<git common dir>/colab-trunk-ci.json`, so every session and
13740
+ * worktree on one checkout shares it. Keyed by `<trunk>@<sha>`; an entry older than the TTL is a
13741
+ * miss. Best effort both ways: an unreadable/unwritable file is simply no cache.
13742
+ */
13743
+ function trunkCiCache(repoAbs) {
13744
+ const env = process.env.COLAB_TRUNK_CI_TTL;
13745
+ const ttl = env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : TRUNK_CI_TTL_DEFAULT_SEC;
13746
+ const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
13747
+ const file = dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-trunk-ci.json') : null;
13748
+ const load = () => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch (_) { return {}; } };
13749
+ return {
13750
+ get(key) {
13751
+ if (!file || ttl <= 0) return null;
13752
+ const e = load()[key];
13753
+ if (!e || !e.at || !e.out) return null;
13754
+ const age = Math.floor((Date.now() - e.at) / 1000);
13755
+ return age >= 0 && age < ttl ? { ...e.out, cachedAgeSec: age } : null;
13756
+ },
13757
+ put(key, out) {
13758
+ if (!file || ttl <= 0) return;
13759
+ const now = Date.now();
13760
+ const all = load();
13761
+ for (const k of Object.keys(all)) if (!all[k] || now - all[k].at > ttl * 1000) delete all[k];
13762
+ all[key] = { at: now, out };
13763
+ try {
13764
+ const tmp = `${file}.${process.pid}.tmp`;
13765
+ fs.writeFileSync(tmp, JSON.stringify(all));
13766
+ fs.renameSync(tmp, file);
13767
+ } catch (_) { /* no cache, not an error */ }
13768
+ },
13769
+ };
13770
+ }
13771
+
13772
+ // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
13773
+ // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
13774
+ // requests, a deadline, and a distinct exit code for every way a wait can end.
13775
+ const HELP_CI_WAIT = `colab ci-wait <run-id> | --sha <sha> [--branch <b>] [--repo <path>] [--timeout <dur>] [--json]
13776
+
13777
+ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand-roll a
13778
+ \`sleep N; gh run view\` loop, never run two waits for the same run, never hide gh's stderr.
13779
+
13780
+ <run-id> wait for one workflow run (actions/runs/<id>)
13781
+ --sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
13782
+ newest run per workflow, dynamic workflows dropped — #451/#461); a sha with no
13783
+ run yet counts as pending until the deadline
13784
+ --branch <b> narrow --sha to runs on that branch
13785
+ --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
13786
+
13787
+ Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
13788
+ conditional request (If-None-Match); a 304 is not counted against the REST rate limit. A 15-minute
13789
+ run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
13790
+
13791
+ Exit codes — branch on these, never on the text:
13792
+ 0 GREEN the run (every judged run at the sha) succeeded
13793
+ 1 RED completed and did not succeed
13794
+ 2 usage bad arguments
13795
+ 3 TIMEOUT the deadline passed while still pending
13796
+ 4 RATE_LIMITED GitHub refused for quota (403/429) — the wait ENDS, it does not retry
13797
+ 5 UNKNOWN a read failed or returned a state it cannot classify
13798
+ 6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
13799
+
13800
+ It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
13801
+ --json { outcome, exit, target, polls, notModified, waitedSec, detail, status, conclusion, url }`;
13802
+
13803
+ function cmdCiWait(argv) {
13804
+ const opts = parseArgs(argv, {
13805
+ values: { '--repo': 'repo', '--sha': 'sha', '--branch': 'branch', '--timeout': 'timeout' },
13806
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
13807
+ });
13808
+ if (opts.help) return print(HELP_CI_WAIT);
13809
+ const runId = opts._ && opts._[0];
13810
+ if ((runId ? 1 : 0) + (opts.sha ? 1 : 0) !== 1 || (runId && !/^\d+$/.test(runId)) || (opts.branch && !opts.sha)) {
13811
+ warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
13812
+ return ciWait.EXIT.USAGE;
13813
+ }
13814
+ const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
13815
+ if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
13816
+ const repoAbs = resolveRepo(opts);
13817
+ if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
13818
+
13819
+ const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
13820
+ const apiPath = runId
13821
+ ? `repos/{owner}/{repo}/actions/runs/${runId}`
13822
+ : `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
13823
+
13824
+ const gitDir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
13825
+ const lock = gitDir.ok ? ciWait.acquireLock(path.join(gitDir.stdout.trim(), 'colab-ci-wait'), runId || `${opts.sha}-${opts.branch || ''}`) : { ok: true, release: () => {} };
13826
+ if (!lock.ok) {
13827
+ warn(`another ci-wait (pid ${lock.holder}) is already waiting on ${target} in this checkout — read its result, do not start a second wait`);
13828
+ return ciWait.EXIT.ALREADY_WAITING;
13829
+ }
13830
+
13831
+ const poll = (etag) => {
13832
+ const r = git.ghApiConditional(repoAbs, apiPath, etag);
13833
+ if (r.kind !== 'ok') return r;
13834
+ let summary;
13835
+ if (runId) {
13836
+ summary = { status: r.json.status, conclusion: r.json.conclusion || null, url: r.json.html_url || null };
13837
+ } else {
13838
+ const rows = Array.isArray(r.json.workflow_runs) ? r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === opts.sha) : null;
13839
+ if (!rows) return { kind: 'error', status: r.status, detail: 'response has no workflow_runs' };
13840
+ summary = git.summarizeRunsForCommit(rows, opts.sha);
13841
+ const pick = rows.find((x) => x.databaseId === summary.databaseId);
13842
+ summary = { ...summary, url: pick ? pick.url : null };
13843
+ }
13844
+ return { ...r, summary, state: ciWait.runState(summary) };
13845
+ };
13846
+
13847
+ 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`);
13848
+ let res;
13849
+ try {
13850
+ res = ciWait.waitLoop({
13851
+ poll, sleep: ciWait.sleepSync, deadlineSec,
13852
+ 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`); },
13853
+ });
13854
+ } finally {
13855
+ lock.release();
13856
+ }
13857
+ const s = (res.last && res.last.summary) || {};
13858
+ const code = ciWait.EXIT[res.outcome];
13859
+ const out = {
13860
+ outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
13861
+ waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
13862
+ status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
13863
+ };
13864
+ if (opts.json) print(JSON.stringify(out, null, 2));
13865
+ else {
13866
+ print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
13867
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}`);
13703
13868
  }
13704
- return verdict === 'UNREADABLE' ? 2 : 0;
13869
+ return code;
13705
13870
  }
13706
13871
 
13707
13872
  const HELP_LANDED = `colab landed [--repo <path>] [--worktree <name> | --branch <br>] [--base <br>] [--all] [--json]
@@ -14527,8 +14692,12 @@ Commands:
14527
14692
  code-wrap Phase B → the branch's recorded base (trunk, or a
14528
14693
  declared line). --json (--dry only): machine-readable
14529
14694
  preconditions with a closed refusal-class vocabulary (#77)
14530
- trunk-ci [--json] the trunk-CI verdict ship computes, read-only (#463):
14695
+ trunk-ci [--fresh] [--json] the trunk-CI verdict ship computes, read-only (#463):
14531
14696
  GREEN | RED | PENDING | WEDGED | NONE | UNREADABLE
14697
+ (cached per sha ~45s in .git — #495)
14698
+ ci-wait <run-id> | --sha S [--branch B] [--timeout D] [--json]
14699
+ WAIT for CI with backoff + conditional requests (#495);
14700
+ exit 0 green · 1 red · 3 timeout · 4 rate-limited · 5 unknown
14532
14701
  landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
14533
14702
  (the shared rule behind code-sweep's buckets — correct
14534
14703
  across squash merges, where "commits ahead" is not)
@@ -14617,6 +14786,7 @@ function main(argv) {
14617
14786
  case 'ship': return cmdShip(rest);
14618
14787
  case 'landed': return cmdLanded(rest);
14619
14788
  case 'trunk-ci': return cmdTrunkCi(rest);
14789
+ case 'ci-wait': return cmdCiWait(rest);
14620
14790
  case 'holders': return cmdHolders(rest);
14621
14791
  case 'promote': return cmdPromote(rest);
14622
14792
  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
+ };
@@ -14,62 +14,15 @@
14
14
  const claimIdentity = require('./claim-identity');
15
15
  const machine = require('./machine');
16
16
 
17
- const CLAIM_MARK = '🔒 Claimed';
18
- const RELEASE_MARK = '✅ Released';
17
+ // The wire format itself — markers, regexes, the session/identity fields and the claim/release
18
+ // encode/decode pairs — lives in codec/claim.js (#497). Re-exported below under the names this
19
+ // module always had, so no caller breaks.
20
+ const codec = require('./codec/claim');
21
+ const { CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE, parseSessionField, parseIdentity } = codec;
19
22
  // #378: how far BEFORE our own claim a rival's live claim can be and still count as "simultaneous".
20
23
  // Racers post within seconds of each other; 10 minutes is deliberately generous so a slow `gh` never
21
24
  // splits a real race, while a claim weeks old — abandoned, or released only in prose — is not a race.
22
25
  const RACE_WINDOW_MS = 10 * 60 * 1000;
23
- // Parses a claim comment body back into {worktree, branch, host, date}. The `· <host>` field is
24
- // what lets the tie-break tell two machines of the SAME GitHub user apart. On a public destination
25
- // it carries an opaque `h:` token instead of the raw name (#369, machine.js `hostToken`) — same
26
- // field, same position, so this regex and every older parser read both shapes. The optional
27
- // trailing `· session <value>` (added 2026-07) is captured separately by SESSION_RE so this regex
28
- // stays byte-stable for session-less comments.
29
- const CLAIM_RE = /🔒 Claimed — worktree `([^`]*)` · branch `([^`]*)` · host `([^`]*)` · (\S+)/;
30
- // The `· session <field>` tail, captured as the rest of the line. parseSessionField() then decodes
31
- // the THREE shapes it can take — `[name](url)`, a bare URL, or a bare name — plus the legacy
32
- // plain-URL form written before sessionName existed.
33
- const SESSION_RE = /· session (.+)$/;
34
- // #327: the claimant's machine, as the public `m:` digest (tools/lib/machine.js `machineToken`),
35
- // written AFTER the timestamp and BEFORE the session suffix — so CLAIM_RE's four groups and
36
- // SESSION_RE's end anchor both parse a new comment exactly as they parse a legacy one, and a legacy
37
- // comment (no such field) simply has no machine and is compared by host.
38
- const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
39
- // A yield: the loser of a race releases, naming the winner by its identity string
40
- // (`claimIdentity.identityString` — `login@host`, or `login@host#session` under the fine setting).
41
- const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
42
-
43
- /**
44
- * Decode the `· session <field>` tail of a claim comment into { sessionName, session }. Accepts:
45
- * `[name](url)` → both; bare `https://…`/`session_…` → url only; any other bare token → name.
46
- * The bare-URL branch is exactly the LEGACY format written before sessionName existed, so old
47
- * comments keep parsing. Returns empty strings when there is no session tail.
48
- */
49
- function parseSessionField(body) {
50
- const m = String(body).match(SESSION_RE);
51
- if (!m) return { sessionName: '', session: '' };
52
- const v = m[1].trim();
53
- const link = v.match(/^\[([^\]]*)\]\((.*)\)$/);
54
- if (link) return { sessionName: link[1], session: link[2] };
55
- // #306: the shape test lives in claimIdentity.looksLikeSessionId — one copy of the rule.
56
- if (claimIdentity.looksLikeSessionId(v)) return { sessionName: '', session: v };
57
- return { sessionName: v, session: '' };
58
- }
59
-
60
- /** `login@host[#session]` → its parts. Logins cannot contain `@`, hosts cannot contain `#`. */
61
- function parseIdentity(s) {
62
- const str = String(s || '').trim();
63
- const at = str.indexOf('@');
64
- if (at <= 0) return null;
65
- const rest = str.slice(at + 1);
66
- const hash = rest.indexOf('#');
67
- return {
68
- login: str.slice(0, at),
69
- host: hash === -1 ? rest : rest.slice(0, hash),
70
- session: hash === -1 ? '' : rest.slice(hash + 1),
71
- };
72
- }
73
26
 
74
27
  /**
75
28
  * Is claim `c` the one a yield NAMED as its winner? Login exact, host by `sameHostName` (so a
@@ -91,11 +44,10 @@ function isNamedWinner(c, named) {
91
44
  function releaseComments(sorted) {
92
45
  const out = [];
93
46
  for (const c of sorted) {
94
- const body = String(c.body || '').trim();
95
- if (!body.startsWith(RELEASE_MARK)) continue;
47
+ const rel = codec.decodeRelease(c.body || '');
48
+ if (!rel) continue;
96
49
  const login = (c.author && c.author.login) || '';
97
- const y = body.match(YIELD_RE);
98
- if (y) out.push({ kind: 'yield', login, at: c.createdAt, winner: parseIdentity(y[1]) });
50
+ if (rel.kind === 'yield') out.push({ kind: 'yield', login, at: c.createdAt, winner: parseIdentity(rel.winner) });
99
51
  else out.push({ kind: 'release', login, at: c.createdAt });
100
52
  }
101
53
  return out;
@@ -133,14 +85,11 @@ function liveClaimComments(comments, comps) {
133
85
  const releases = releaseComments(sorted);
134
86
  const live = [];
135
87
  for (const c of sorted) {
136
- const body = String(c.body || '').trim();
137
- const m = body.match(CLAIM_RE);
138
- if (!m) continue;
88
+ const claim = codec.decodeClaim(c.body || ''); // [name](url) / url / name / legacy, machine or not
89
+ if (!claim) continue;
139
90
  const login = (c.author && c.author.login) || '';
140
- const host = m[3];
141
- const { session, sessionName } = parseSessionField(body); // handles [name](url) / url / name / legacy
142
- const mm = body.match(MACHINE_RE); // #327 — absent on a legacy comment: compared by host
143
- const machineTok = mm ? mm[1] : '';
91
+ const { host, session, sessionName } = claim;
92
+ const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
144
93
  const at = c.createdAt;
145
94
  const entry = { login, host, machine: machineTok, session, sessionName, at };
146
95
  const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
@@ -203,7 +152,7 @@ function yieldReleaseBody(winner, { redact = false } = {}) {
203
152
  const tail = id.startsWith(head) ? id.slice(head.length) : '';
204
153
  id = `${winner.login}@${machine.hostToken(winner.host)}${tail}`;
205
154
  }
206
- return `${RELEASE_MARK} (yielded — earlier claim by ${id} wins)`;
155
+ return codec.encodeRelease({ winner: id });
207
156
  }
208
157
 
209
158
  module.exports = {