@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1

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.
Files changed (73) hide show
  1. package/README.md +243 -213
  2. package/README.vi.md +246 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +6 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1691 -254
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +203 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +4 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +151 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +716 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +762 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +303 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +106 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/stamp.js +7 -0
  65. package/tools/lib/tracker-fake.js +195 -0
  66. package/tools/lib/tracker-github.js +106 -0
  67. package/tools/lib/tracker-scenarios.json +206 -0
  68. package/tools/lib/tracker.js +64 -0
  69. package/tools/lib/tree-green.js +88 -0
  70. package/tools/lib/util.js +17 -1
  71. package/tools/lib/verify-runs.js +104 -0
  72. package/tools/lib/wake.js +8 -90
  73. package/tools/lib/workflow-triggers.js +48 -0
package/tools/lib/git.js CHANGED
@@ -29,6 +29,15 @@ function run(cmd, args, opts = {}) {
29
29
  };
30
30
  }
31
31
 
32
+ /**
33
+ * Every `gh` spawn in this module goes through the tracker adapter (#500) — the one place the CLI
34
+ * talks to GitHub. Lazy require, deliberately: `module.exports = {…}` below REPLACES the exports
35
+ * object, so a top-level require cycle would hand tracker-github a stale empty `{}`.
36
+ */
37
+ function gh(args, opts = {}) {
38
+ return require('./tracker-github').exec(args, opts);
39
+ }
40
+
32
41
  function git(args, cwd, opts = {}) {
33
42
  return run('git', args, { ...(cwd ? { cwd } : {}), ...opts });
34
43
  }
@@ -438,8 +447,9 @@ function dirtyAny(wtPath) {
438
447
 
439
448
  /**
440
449
  * #344: is gh usable — and if not, WHY. `{ ok, reason }`, reason `null` | `'missing'` (no gh binary)
441
- * | `'no-credential'` (gh is there, but the credential it would actually use does not work). Cached
442
- * per process.
450
+ * | `'no-credential'` (gh is there, but the credential it would actually use does not work)
451
+ * | `'rate-limited'` (#516: the credential works, its quota is spent — `resetAt` epoch ms or null).
452
+ * Cached per process.
443
453
  *
444
454
  * A bare `gh auth status` is the wrong question: it exits 1 when ANY configured account is broken,
445
455
  * even when the one gh actually uses is fine (measured: a valid `GH_TOKEN` plus an expired, inactive
@@ -453,30 +463,50 @@ function dirtyAny(wtPath) {
453
463
  let _ghState = null;
454
464
  function ghState() {
455
465
  if (_ghState) return _ghState;
456
- if (!run('gh', ['--version']).ok) return (_ghState = { ok: false, reason: 'missing' });
457
- if (run('gh', ['auth', 'status', '--active']).ok) return (_ghState = { ok: true, reason: null });
458
- const who = run('gh', ['api', 'user', '-q', '.login']);
466
+ if (!gh(['--version']).ok) return (_ghState = { ok: false, reason: 'missing' });
467
+ if (gh(['auth', 'status', '--active']).ok) return (_ghState = { ok: true, reason: null });
468
+ const who = gh(['api', 'user', '-q', '.login']);
459
469
  if (who.ok && who.stdout) {
460
470
  if (_ghLogin === undefined) _ghLogin = who.stdout;
461
471
  return (_ghState = { ok: true, reason: null });
462
472
  }
473
+ // #516: a spent QUOTA is not a broken credential. `gh api user` answers 403/429 "API rate limit
474
+ // exceeded" (or a "secondary rate limit") for a token that is perfectly valid — and `gh auth status`
475
+ // then calls it invalid too. Reported as `no-credential`, that sent an operator hunting a broken
476
+ // token when the cure is to wait for the reset or switch account. Classified by the SAME rule
477
+ // ci-wait reads a REST response with (#495), so both name a rate limit identically.
478
+ const status = /\bHTTP (\d{3})\b/.exec(who.stderr || '');
479
+ const cls = require('./ci-wait').classifyResponse({ status: status ? Number(status[1]) : null, stderr: who.stderr || '' });
480
+ if (cls.kind === 'rate-limited') return (_ghState = { ok: false, reason: 'rate-limited', resetAt: ghRateLimitReset() });
463
481
  return (_ghState = { ok: false, reason: 'no-credential' });
464
482
  }
465
483
 
484
+ /**
485
+ * #516: when the REST core quota resets, as epoch ms — or null when it cannot be read or is not the
486
+ * limit in force (quota left means a SECONDARY rate limit, whose end GitHub does not publish).
487
+ * `GET /rate_limit` does not count against the quota, so it answers even while `api user` cannot.
488
+ */
489
+ function ghRateLimitReset() {
490
+ const r = gh(['api', 'rate_limit', '-q', '.resources.core | "\\(.remaining) \\(.reset)"']);
491
+ const m = r.ok ? /^(\d+)\s+(\d+)$/.exec((r.stdout || '').trim()) : null;
492
+ if (!m || Number(m[1]) > 0) return null;
493
+ return Number(m[2]) * 1000;
494
+ }
495
+
466
496
  function ghAvailable() {
467
497
  return ghState().ok;
468
498
  }
469
499
 
470
500
  /** gh issue edit — returns {ok, stderr}. cwd must be inside the repo so gh resolves the remote. */
471
501
  function ghIssueEdit(repo, issueNum, args) {
472
- return run('gh', ['issue', 'edit', String(issueNum), ...args], { cwd: repo });
502
+ return gh(['issue', 'edit', String(issueNum), ...args], { cwd: repo });
473
503
  }
474
504
 
475
505
  /** The current gh user's login (`gh api user`), or null if it can't be determined. Cached. */
476
506
  let _ghLogin;
477
507
  function ghCurrentLogin() {
478
508
  if (_ghLogin !== undefined) return _ghLogin;
479
- const r = run('gh', ['api', 'user', '-q', '.login']);
509
+ const r = gh(['api', 'user', '-q', '.login']);
480
510
  _ghLogin = r.ok && r.stdout ? r.stdout : null;
481
511
  return _ghLogin;
482
512
  }
@@ -484,7 +514,7 @@ function ghCurrentLogin() {
484
514
  /** Raw `gh api` call — returns {ok, stdout, stderr, code}. cwd must be inside the repo so `{owner}`
485
515
  * / `{repo}` placeholders resolve to the right remote. */
486
516
  function ghApi(repo, args) {
487
- return run('gh', ['api', ...args], { cwd: repo });
517
+ return gh(['api', ...args], { cwd: repo });
488
518
  }
489
519
 
490
520
  /**
@@ -562,7 +592,7 @@ function ghIssueRelease(repo, issueNum, opts = {}) {
562
592
  note = 'could not read who holds the claim — unassigned @me only';
563
593
  }
564
594
  }
565
- const r = run('gh', ['issue', 'edit', String(issueNum),
595
+ const r = gh(['issue', 'edit', String(issueNum),
566
596
  '--remove-assignee', ['@me', ...others].join(','), '--remove-label', 'in-progress'], { cwd: repo });
567
597
  if (r.ok || !isGraphqlRateLimit(r.stderr)) return { ...r, others: r.ok ? others : [], caller, note };
568
598
 
@@ -586,7 +616,7 @@ function ghIssueRelease(repo, issueNum, opts = {}) {
586
616
  * bad repo, network, unparseable). Callers treat null as "couldn't read" — never as "empty".
587
617
  */
588
618
  function ghIssueView(repo, issueNum, fields) {
589
- const r = run('gh', ['issue', 'view', String(issueNum), '--json', fields.join(',')], { cwd: repo });
619
+ const r = gh(['issue', 'view', String(issueNum), '--json', fields.join(',')], { cwd: repo });
590
620
  if (!r.ok) return null;
591
621
  try { return JSON.parse(r.stdout); }
592
622
  catch (_) { return null; }
@@ -604,7 +634,7 @@ function ghIssueView(repo, issueNum, fields) {
604
634
  * someone approved it?", so the core-path pause costs one read on the resume path.
605
635
  */
606
636
  function ghPrForBranch(repo, branch) {
607
- const r = run('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,state,author,headRefOid,reviews'], { cwd: repo });
637
+ const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,state,author,headRefOid,reviews'], { cwd: repo });
608
638
  if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
609
639
  try {
610
640
  const list = JSON.parse(r.stdout || '[]');
@@ -618,7 +648,7 @@ function ghPrForBranch(repo, branch) {
618
648
  * tools/lib/machine-trailer.js fails closed on it.
619
649
  */
620
650
  function ghRepoVisibility(repo) {
621
- const r = run('gh', ['repo', 'view', '--json', 'visibility', '-q', '.visibility'], { cwd: repo });
651
+ const r = gh(['repo', 'view', '--json', 'visibility', '-q', '.visibility'], { cwd: repo });
622
652
  if (!r.ok) return null;
623
653
  const v = (r.stdout || '').trim().toUpperCase();
624
654
  return /^[A-Z]+$/.test(v) ? v : null;
@@ -626,18 +656,18 @@ function ghRepoVisibility(repo) {
626
656
 
627
657
  /** #350: open a PR `head` → `base`. Returns {ok, url, stderr}; `url` is gh's printed PR URL. */
628
658
  function ghPrCreate(repo, { base, head, title, body }) {
629
- const r = run('gh', ['pr', 'create', '--base', base, '--head', head, '--title', title, '--body', body], { cwd: repo });
659
+ const r = gh(['pr', 'create', '--base', base, '--head', head, '--title', title, '--body', body], { cwd: repo });
630
660
  const url = (r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean).pop() || null;
631
661
  return { ok: r.ok, url, stderr: r.stderr };
632
662
  }
633
663
 
634
664
  /** #350: close a PR whose work landed by squash elsewhere, with a comment saying where. */
635
665
  function ghPrClose(repo, num, comment) {
636
- return run('gh', ['pr', 'close', String(num), '--comment', comment], { cwd: repo });
666
+ return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
637
667
  }
638
668
 
639
669
  function ghIssueComment(repo, issueNum, body) {
640
- const r = run('gh', ['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
670
+ const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
641
671
  if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
642
672
  return ghApi(repo, ['-X', 'POST', `repos/{owner}/{repo}/issues/${issueNum}/comments`, '-f', `body=${body}`]);
643
673
  }
@@ -677,7 +707,7 @@ function ghIssueLabelActors(repo, issueNum, label) {
677
707
  * contract as ghIssueView: a caller must not read absence as proof a label is missing.
678
708
  */
679
709
  function ghListLabels(repo) {
680
- const r = run('gh', ['label', 'list', '--limit', '500', '--json', 'name', '-q', '.[].name'], { cwd: repo });
710
+ const r = gh(['label', 'list', '--limit', '500', '--json', 'name', '-q', '.[].name'], { cwd: repo });
681
711
  if (!r.ok) return null;
682
712
  return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
683
713
  }
@@ -688,13 +718,32 @@ function ghListLabels(repo) {
688
718
  * the same contract as ghIssueView; a caller must not read a failed call as "no issues".
689
719
  */
690
720
  function ghIssueListByLabel(repo, label, state, fields) {
691
- const r = run('gh', ['issue', 'list', '--label', label, '--state', state,
721
+ const r = gh(['issue', 'list', '--label', label, '--state', state,
692
722
  '--json', fields.join(','), '--limit', '200'], { cwd: repo });
693
723
  if (!r.ok) return null;
694
724
  try { return JSON.parse(r.stdout); }
695
725
  catch (_) { return null; }
696
726
  }
697
727
 
728
+ /**
729
+ * #448: the open issues carrying `label`, as numbers, read through the REST issues list — NOT
730
+ * search. `gh issue list --label` (ghIssueListByLabel above) is served by GraphQL `search(...)`,
731
+ * whose index can lag a burst of closes and answer "0 open" for a label still on an open issue;
732
+ * this endpoint reads the issues table directly. Pull requests share the endpoint and are dropped.
733
+ * Null on any failure — "could not read", never "none open", same contract as ghIssueListByLabel.
734
+ * Used as the confirming read before a `group:` label is deleted (group-labels.js
735
+ * teardownSpentGroupLabel).
736
+ */
737
+ function ghOpenIssueNumbersByLabel(repo, label) {
738
+ const r = ghApi(repo, [
739
+ '--method', 'GET', '--paginate', 'repos/{owner}/{repo}/issues',
740
+ '-f', `labels=${label}`, '-f', 'state=open', '-f', 'per_page=100',
741
+ '--jq', '.[] | select(.pull_request == null) | .number',
742
+ ]);
743
+ if (!r.ok) return null;
744
+ return String(r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean).map(Number);
745
+ }
746
+
698
747
  /**
699
748
  * `gh label delete <name> --yes` — returns {ok, stderr}. Deletes the LABEL OBJECT from the
700
749
  * repo's tracker, not one issue's use of it — every issue that carried it loses it. Callers
@@ -702,7 +751,7 @@ function ghIssueListByLabel(repo, label, state, fields) {
702
751
  * instead; this is only for tearing down a spent `group:<key>` label (CONVENTIONS.md §5).
703
752
  */
704
753
  function ghLabelDelete(repo, name) {
705
- return run('gh', ['label', 'delete', name, '--yes'], { cwd: repo });
754
+ return gh(['label', 'delete', name, '--yes'], { cwd: repo });
706
755
  }
707
756
 
708
757
  /**
@@ -715,7 +764,7 @@ function ghLabelDelete(repo, name) {
715
764
  * ghListLabels and only calls this for a name confirmed missing.
716
765
  */
717
766
  function ghLabelCreate(repo, name, color, description) {
718
- return run('gh', ['label', 'create', name, '--color', color, '--description', description], { cwd: repo });
767
+ return gh(['label', 'create', name, '--color', color, '--description', description], { cwd: repo });
719
768
  }
720
769
 
721
770
  /**
@@ -725,7 +774,7 @@ function ghLabelCreate(repo, name, color, description) {
725
774
  * description has drifted from the handbook's (#364).
726
775
  */
727
776
  function ghListLabelsDetailed(repo) {
728
- const r = run('gh', ['label', 'list', '--limit', '500', '--json', 'name,description'], { cwd: repo });
777
+ const r = gh(['label', 'list', '--limit', '500', '--json', 'name,description'], { cwd: repo });
729
778
  if (!r.ok) return null;
730
779
  try {
731
780
  const rows = JSON.parse(r.stdout);
@@ -741,7 +790,7 @@ function ghListLabelsDetailed(repo) {
741
790
  * read with a differing description.
742
791
  */
743
792
  function ghLabelEditDescription(repo, name, description) {
744
- return run('gh', ['label', 'edit', name, '--description', description], { cwd: repo });
793
+ return gh(['label', 'edit', name, '--description', description], { cwd: repo });
745
794
  }
746
795
 
747
796
  /**
@@ -795,12 +844,12 @@ function ghLabelEditDescription(repo, name, description) {
795
844
  * when tools/lib/ci-verdict.js finds the run WEDGED rather than merely slow. Nothing here waits or
796
845
  * polls — it reports what is true at read time and lets the caller decide.
797
846
  */
798
- function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin') {
847
+ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin', opts = {}) {
799
848
  const head = run('git', ['ls-remote', remote, `refs/heads/${branch}`], { cwd: repo });
800
849
  if (!head.ok) return null;
801
850
  const sha = (head.stdout.split('\n')[0] || '').split('\t')[0].trim();
802
851
  if (!sha) return null; // branch does not exist on the remote
803
- return ghRunForCommit(repo, branch, sha, limit);
852
+ return ghRunForCommit(repo, branch, sha, limit, opts);
804
853
  }
805
854
 
806
855
  /**
@@ -839,19 +888,32 @@ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name ||
839
888
  function ghRunsForCommit(repo, branch, sha, limit = 10) {
840
889
  if (!sha) return null;
841
890
 
891
+ // #495: one REST call (`actions/runs?head_sha=&branch=`) instead of `gh run list`'s two (runs +
892
+ // workflows), and no `-L` window to fall out of. A rate limit is final — falling back would spend
893
+ // two more calls on a quota that is already gone. Any other failure (an old gh, a test stub that
894
+ // only answers `run list`, a non-GitHub remote) falls through to the `gh run list` read below.
895
+ const rest = ghRunsAtShaRest(repo, sha, branch);
896
+ if (rest.rows) return rest.rows;
897
+ if (rest.rateLimited) return null;
898
+
842
899
  // createdAt + databaseId are additive (#155): a NON-completed pick needs both to let a caller
843
900
  // judge whether it is merely slow or structurally WEDGED (tools/lib/ci-verdict.js) — createdAt for
844
901
  // the age backstop, databaseId to look up its job count (ghRunJobCount, below — a second call, made
845
902
  // lazily by the caller, never here: an ordinary green check must not pay for a read it never needs).
846
- const r = run('gh', ['run', 'list', '--branch', branch, '-L', String(limit),
903
+ const r = gh(['run', 'list', '--branch', branch, '-L', String(limit),
847
904
  // workflowName is additive (#338): `colab release cut`'s full-suite condition groups the rows by
848
905
  // workflow — a workflow whose only run at the sha was cancelled never ran its suite.
849
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName'], { cwd: repo });
906
+ // event is additive (#451): summarizeRunsForCommit drops `dynamic` rows (workflows the repo
907
+ // does not own) before it computes a verdict, and can only do that if the row says so.
908
+ // workflowDatabaseId is additive (#510): the cure rule's same-workflow test reads the workflow's
909
+ // id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
910
+ '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
850
911
  if (!r.ok) return null;
851
912
  let runs;
852
913
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
853
914
  if (!Array.isArray(runs)) return null;
854
- const forSha = runs.filter((x) => x && x.headSha === sha);
915
+ const forSha = runs.filter((x) => x && x.headSha === sha)
916
+ .map(({ workflowDatabaseId, ...x }) => ({ ...x, workflowId: workflowDatabaseId ?? null }));
855
917
  // #413: an empty filter over a sha that HAS a green run was measured intermittently and never
856
918
  // reproduced. Opt-in trace of what the read actually returned, so the next occurrence says
857
919
  // whether gh answered nothing, answered other shas, or failed in a way that parsed as [].
@@ -863,6 +925,44 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
863
925
  return forSha;
864
926
  }
865
927
 
928
+ /**
929
+ * #495: `gh api -i <path>`, optionally conditional (`If-None-Match: <etag>`). Returns the
930
+ * classified response from tools/lib/ci-wait.js: `{ kind: ok|not-modified|rate-limited|error,
931
+ * status, etag, json?, detail? }`. A 304 does not count against the REST primary rate limit, so a
932
+ * poller that sends its last ETag pays for a read only when something changed. gh exits 1 on a 304
933
+ * and still prints the head to stdout (measured), so the head is parsed whatever the exit code.
934
+ */
935
+ function ghApiConditional(repo, apiPath, etag) {
936
+ const ciWait = require('./ci-wait');
937
+ const args = ['api', '-i', ...(etag ? ['-H', `If-None-Match: ${etag}`] : []), apiPath];
938
+ const r = gh(args, { cwd: repo, timeoutMs: 60000 });
939
+ const http = ciWait.parseHttp(r.stdout);
940
+ return ciWait.classifyResponse({ ...http, stderr: r.stderr });
941
+ }
942
+
943
+ /**
944
+ * Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
945
+ * rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
946
+ * rate limit, `{}` on any other failure (the caller decides whether to fall back).
947
+ */
948
+ function ghRunsAtShaRest(repo, sha, branch) {
949
+ if (!sha) return {};
950
+ const ciWait = require('./ci-wait');
951
+ const q = `head_sha=${encodeURIComponent(sha)}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}&per_page=100`;
952
+ const r = ghApiConditional(repo, `repos/{owner}/{repo}/actions/runs?${q}`);
953
+ if (r.kind === 'rate-limited') return { rateLimited: true, detail: r.detail };
954
+ if (r.kind !== 'ok' || !r.json || !Array.isArray(r.json.workflow_runs)) return {};
955
+ return { rows: r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === sha) };
956
+ }
957
+
958
+ /** Is a `gh` binary on PATH (#495)? No API call — cached per process. The credential is proven by
959
+ * the first real read, not by a probe in front of it (`gh auth status` costs a REST + a GraphQL). */
960
+ let _ghInstalled;
961
+ function ghInstalled() {
962
+ if (_ghInstalled === undefined) _ghInstalled = gh(['--version']).ok;
963
+ return _ghInstalled;
964
+ }
965
+
866
966
  /**
867
967
  * Every run on `ref` at `sha`, WITH its `attempt` (#373). A sibling of ghRunsForCommit, not a change
868
968
  * to its field list: batch landing needs the attempt number to enforce "re-run a red:infra ONCE", and
@@ -870,7 +970,7 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
870
970
  */
871
971
  function ghRunsForRef(repo, ref, sha, limit = 20) {
872
972
  if (!sha) return null;
873
- const r = run('gh', ['run', 'list', '--branch', ref, '-L', String(limit),
973
+ const r = gh(['run', 'list', '--branch', ref, '-L', String(limit),
874
974
  '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,attempt'], { cwd: repo });
875
975
  if (!r.ok) return null;
876
976
  let runs;
@@ -879,8 +979,8 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
879
979
  return runs.filter((x) => x && x.headSha === sha);
880
980
  }
881
981
 
882
- function ghRunForCommit(repo, branch, sha, limit = 10) {
883
- return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha);
982
+ function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
983
+ return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
884
984
  }
885
985
 
886
986
  /**
@@ -890,7 +990,7 @@ function ghRunForCommit(repo, branch, sha, limit = 10) {
890
990
  */
891
991
  function ghRunsAtCommit(repo, sha, limit = 100) {
892
992
  if (!sha) return null;
893
- const r = run('gh', ['run', 'list', '--commit', sha, '-L', String(limit),
993
+ const r = gh(['run', 'list', '--commit', sha, '-L', String(limit),
894
994
  '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
895
995
  if (!r.ok) return null;
896
996
  let runs;
@@ -905,8 +1005,8 @@ function ghRunsAtCommit(repo, sha, limit = 100) {
905
1005
  * empty trunk read `none`: the branch-filtered list was measured returning nothing for a trunk sha
906
1006
  * whose green run existed, and clearing on its own a minute later. Null on failure, as elsewhere.
907
1007
  */
908
- function ghRunForCommitAnyRef(repo, sha, limit = 50) {
909
- return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha);
1008
+ function ghRunForCommitAnyRef(repo, sha, limit = 50, opts = {}) {
1009
+ return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha, opts);
910
1010
  }
911
1011
 
912
1012
  /**
@@ -928,7 +1028,7 @@ function commitTimeMs(repo, sha) {
928
1028
  * `truncated` is true when the read filled its limit, which a caller must treat as unread.
929
1029
  */
930
1030
  function ghRunsSince(repo, branch, sinceDay, limit = 1000) {
931
- const r = run('gh', ['run', 'list', '--branch', branch, '--created', `>=${sinceDay}`, '-L', String(limit),
1031
+ const r = gh(['run', 'list', '--branch', branch, '--created', `>=${sinceDay}`, '-L', String(limit),
932
1032
  '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
933
1033
  if (!r.ok) return null;
934
1034
  let runs;
@@ -937,15 +1037,133 @@ function ghRunsSince(repo, branch, sinceDay, limit = 1000) {
937
1037
  return { runs, truncated: runs.length >= limit };
938
1038
  }
939
1039
 
940
- /** ghRunForCommit's pick, over rows already read (null in -> null out). */
941
- function summarizeRunsForCommit(forSha, sha) {
942
- if (forSha === null) return null;
1040
+ /**
1041
+ * #451: a run whose `event` is `dynamic` comes from a workflow the repo does not own — GitHub's
1042
+ * dynamic workflows (Dependabot Updates, code scanning default setup, …), which never execute the
1043
+ * code at the sha they are filed against. Such a row is not evidence about that sha, so it is
1044
+ * dropped before any verdict is computed. A row with no `event` field (an older read, a hand-built
1045
+ * fixture) is kept: absence of the field never excludes anything.
1046
+ */
1047
+ function isRepoOwnedRun(x) {
1048
+ return !(x && x.event === 'dynamic');
1049
+ }
1050
+
1051
+ /** The dropped rows, in the compact shape a verdict detail names them by. */
1052
+ function excludedRunSummary(rows) {
1053
+ return rows.map((x) => ({
1054
+ workflowName: x.workflowName || null, status: x.status || null,
1055
+ conclusion: x.conclusion || null, databaseId: x.databaseId || null,
1056
+ ...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
1057
+ }));
1058
+ }
1059
+
1060
+ /**
1061
+ * ghRunForCommit's pick, over rows already read (null in -> null out).
1062
+ *
1063
+ * #451: rows from workflows the repo does not own (`event: dynamic`) are dropped first; when any
1064
+ * were, the result carries an additive `excluded` list naming them, so a caller can say what it
1065
+ * did not count. When nothing is left the sha reads `none`, exactly as if no run had existed —
1066
+ * a repo-owned red is never affected, since only `dynamic` rows are dropped.
1067
+ *
1068
+ * #461: the repo-owned rows are then reduced to the newest run per workflow (newestRunPerWorkflow,
1069
+ * below); the rows that reduction set aside ride along as an additive `superseded` list, same shape
1070
+ * as `excluded`, present only when non-empty. Every quantifier below runs over the reduced set.
1071
+ *
1072
+ * #503: `opts.verifying` (a tools/lib/verify-runs.js policy, `{gate, ignore}`) narrows the owned rows
1073
+ * to the runs that VERIFY the code — push / pull-request triggered, or the declared set — BEFORE the
1074
+ * per-workflow reduction; the rest (a `workflow_run` release, a scheduled finalize, a deploy) ride
1075
+ * along as `setAside`, each with its reason. Opt-in: without `opts.verifying` nothing changes, so
1076
+ * readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
1077
+ */
1078
+ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1079
+ if (allForSha === null) return null;
1080
+ const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
1081
+ let owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
1082
+ let setAside = [];
1083
+ if (opts && opts.verifying) {
1084
+ const split = require('./verify-runs').splitVerifying(owned, opts.verifying);
1085
+ owned = split.counted;
1086
+ setAside = split.setAside;
1087
+ }
1088
+ const { heads, superseded } = newestRunPerWorkflow(owned);
1089
+ const extra = {
1090
+ ...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
1091
+ ...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
1092
+ ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1093
+ };
1094
+ const r = summarizeRepoOwnedRuns(heads, sha);
1095
+ return { ...r, ...extra };
1096
+ }
1097
+
1098
+ /** Sort key for "which run of one workflow is newer": createdAt, then databaseId; null = unknown. */
1099
+ function runRecency(x) {
1100
+ const t = x && x.createdAt ? Date.parse(x.createdAt) : NaN;
1101
+ const id = x && x.databaseId != null ? Number(x.databaseId) : NaN;
1102
+ return { t: Number.isFinite(t) ? t : null, id: Number.isFinite(id) ? id : null };
1103
+ }
1104
+
1105
+ /** True when `a` is provably newer than `b`; false when older OR when neither key can tell. */
1106
+ function isNewerRun(a, b) {
1107
+ const ra = runRecency(a); const rb = runRecency(b);
1108
+ if (ra.t !== null && rb.t !== null && ra.t !== rb.t) return ra.t > rb.t;
1109
+ if (ra.id !== null && rb.id !== null && ra.id !== rb.id) return ra.id > rb.id;
1110
+ return false;
1111
+ }
1112
+
1113
+ /**
1114
+ * #461: each workflow is judged by its NEWEST run at the sha — an earlier attempt of the SAME
1115
+ * workflow that a later one superseded no longer vetoes it. Measured: a `workflow_run`-triggered
1116
+ * workflow fired once per CI attempt at one trunk sha; the two red CI attempts gave it two
1117
+ * `skipped` runs, the green third attempt a `success`, and the two stale rows held the sha
1118
+ * not-green forever (a re-run replays the original payload and skips again).
1119
+ *
1120
+ * Grouped by `workflowName` ONLY. A row with no workflowName (an older read, a hand-built fixture)
1121
+ * is its own group — absence of the field never collapses anything, so every verdict that could be
1122
+ * computed before #461 without the field is computed identically now. Rows of DIFFERENT workflows
1123
+ * are never reduced: a failing workflow beside a passing one still reads not-green (#146/#162).
1124
+ *
1125
+ * `cancelled` never supersedes: a cancelled run executed nothing and has always been neutral here
1126
+ * (#92), so it cannot stand for its workflow while that workflow has any non-cancelled run at the
1127
+ * sha — otherwise a cancel-in-progress straggler created after the passing run would turn #92's
1128
+ * green back into "every run was cancelled". It still counts when it is all a workflow has.
1129
+ *
1130
+ * Newest = later createdAt, then higher databaseId; when neither key separates two rows, gh's
1131
+ * newest-first order decides (the first row seen is kept). An unfinished newest run still blocks
1132
+ * green (#307): it is the head, so the all-finished quantifier sees it.
1133
+ *
1134
+ * Returns the heads in their original order (callers' newest-first `forSha[0]` pick relies on it)
1135
+ * plus the rows they superseded.
1136
+ */
1137
+ function newestRunPerWorkflow(rows) {
1138
+ const best = new Map();
1139
+ rows.forEach((x, i) => {
1140
+ const name = x && x.workflowName;
1141
+ if (!name) return;
1142
+ const cur = best.get(name);
1143
+ if (cur === undefined) { best.set(name, i); return; }
1144
+ const c = rows[cur];
1145
+ const xCancelled = x.conclusion === 'cancelled';
1146
+ const cCancelled = c.conclusion === 'cancelled';
1147
+ if (xCancelled !== cCancelled) { if (cCancelled) best.set(name, i); return; }
1148
+ if (isNewerRun(x, c)) best.set(name, i);
1149
+ });
1150
+ const heads = []; const superseded = [];
1151
+ rows.forEach((x, i) => {
1152
+ const name = x && x.workflowName;
1153
+ if (!name || best.get(name) === i) heads.push(x); else superseded.push(x);
1154
+ });
1155
+ return { heads, superseded };
1156
+ }
1157
+
1158
+ function summarizeRepoOwnedRuns(forSha, sha) {
943
1159
  if (forSha.length === 0) return { status: 'none', conclusion: null, sha, createdAt: null, databaseId: null, runCount: 0 };
944
1160
 
945
1161
  // runCount (#176) is additive: how many sibling workflow rows exist at this sha, so a caller can
946
1162
  // report "N runs at <sha>: all success" instead of a singular verdict that hides how many
947
1163
  // workflows actually agreed. It is the row count BEFORE any of the picks below, not "how many
948
1164
  // succeeded" — the picked row already tells the caller the conclusion; this tells it the sample size.
1165
+ // Since #461 that is the count of rows JUDGED (one per named workflow, after superseded attempts
1166
+ // are set aside) — "3 runs: all success" must never count two skipped attempts it did not judge.
949
1167
  const runCount = forSha.length;
950
1168
 
951
1169
  // A completed sibling whose conclusion is anything but success or cancelled makes the sha
@@ -988,7 +1206,7 @@ function summarizeRunsForCommit(forSha, sha) {
988
1206
  */
989
1207
  function ghRunJobCount(repo, runDatabaseId) {
990
1208
  if (runDatabaseId === null || runDatabaseId === undefined) return null;
991
- const r = run('gh', ['run', 'view', String(runDatabaseId), '--json', 'jobs', '-q', '.jobs | length'], { cwd: repo });
1209
+ const r = gh(['run', 'view', String(runDatabaseId), '--json', 'jobs', '-q', '.jobs | length'], { cwd: repo });
992
1210
  if (!r.ok) return null;
993
1211
  const n = Number(r.stdout);
994
1212
  return Number.isFinite(n) ? n : null;
@@ -1015,7 +1233,7 @@ function ghRunJobCount(repo, runDatabaseId) {
1015
1233
  */
1016
1234
  function ghRunJobs(repo, runDatabaseId) {
1017
1235
  if (runDatabaseId === null || runDatabaseId === undefined) return null;
1018
- const r = run('gh', ['run', 'view', String(runDatabaseId), '--json', 'jobs'], { cwd: repo });
1236
+ const r = gh(['run', 'view', String(runDatabaseId), '--json', 'jobs'], { cwd: repo });
1019
1237
  if (!r.ok) return null;
1020
1238
  let parsed;
1021
1239
  try { parsed = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -1032,12 +1250,54 @@ function ghRunJobs(repo, runDatabaseId) {
1032
1250
  }));
1033
1251
  }
1034
1252
 
1253
+ /**
1254
+ * Every check run at one commit, flattened for the #493 tree-skip read — `[{id, name, status,
1255
+ * conclusion, suite, annotations}]` (`suite` = check-suite id = one workflow run; `annotations` =
1256
+ * output.annotations_count), or null on a gh/parse failure. One call per green trunk read, made
1257
+ * lazily by readCiVerdict; `{owner}/{repo}` is resolved by gh from the cwd's remote.
1258
+ */
1259
+ function ghCommitCheckRuns(repo, sha) {
1260
+ if (!sha) return null;
1261
+ const r = gh(['api', `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
1262
+ '--jq', '[.check_runs[] | {id, name, status, conclusion, suite: .check_suite.id, annotations: .output.annotations_count}]'], { cwd: repo });
1263
+ if (!r.ok) return null;
1264
+ try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
1265
+ }
1266
+
1267
+ /** One check run's annotations as `[{title, message, level}]`, or null on failure (#493). */
1268
+ function ghCheckRunAnnotations(repo, checkRunId) {
1269
+ if (checkRunId === null || checkRunId === undefined) return null;
1270
+ const r = gh(['api', `repos/{owner}/{repo}/check-runs/${checkRunId}/annotations`,
1271
+ '--jq', '[.[] | {title, message, level: .annotation_level}]'], { cwd: repo });
1272
+ if (!r.ok) return null;
1273
+ try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
1274
+ }
1275
+
1276
+ /**
1277
+ * Dispatch `workflowFile` on `ref` (#474) — `gh workflow run <file> --ref <ref> -f k=v…`. Returns
1278
+ * `{ok, withInputs, detail}`. If the call with inputs is refused (GitHub can validate inputs against
1279
+ * a workflow file that does not declare them yet), it is retried ONCE without them: the release-auto
1280
+ * template forces dry mode on any ref other than main, so an input-less dispatch of a capable file is
1281
+ * still a dry run. The caller only ever dispatches a file it read as dry-run capable at that ref.
1282
+ * Never waits for the run.
1283
+ */
1284
+ function ghWorkflowDispatch(repo, workflowFile, ref, inputs = {}) {
1285
+ const flags = [];
1286
+ for (const [k, v] of Object.entries(inputs)) flags.push('-f', `${k}=${v}`);
1287
+ const first = gh(['workflow', 'run', workflowFile, '--ref', ref, ...flags], { cwd: repo });
1288
+ if (first.ok) return { ok: true, withInputs: true, detail: '' };
1289
+ if (!flags.length) return { ok: false, withInputs: false, detail: (first.stderr || first.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
1290
+ const second = gh(['workflow', 'run', workflowFile, '--ref', ref], { cwd: repo });
1291
+ if (second.ok) return { ok: true, withInputs: false, detail: (first.stderr || '').trim().split('\n')[0] || '' };
1292
+ return { ok: false, withInputs: false, detail: (second.stderr || second.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
1293
+ }
1294
+
1035
1295
  /**
1036
1296
  * Issues claimed by the current gh user in a repo = assigned to @me AND labeled in-progress
1037
1297
  * (that pairing is exactly what `colab claim` writes). Returns array of numbers, or null on failure.
1038
1298
  */
1039
1299
  function ghAssignedIssues(repo) {
1040
- const r = run('gh', ['issue', 'list', '--assignee', '@me', '--label', 'in-progress', '--state', 'open',
1300
+ const r = gh(['issue', 'list', '--assignee', '@me', '--label', 'in-progress', '--state', 'open',
1041
1301
  '--json', 'number', '--limit', '200'], { cwd: repo });
1042
1302
  if (!r.ok) return null;
1043
1303
  try { return JSON.parse(r.stdout).map((o) => o.number); }
@@ -1045,14 +1305,15 @@ function ghAssignedIssues(repo) {
1045
1305
  }
1046
1306
 
1047
1307
  module.exports = {
1308
+ ghCommitCheckRuns, ghCheckRunAnnotations,
1048
1309
  run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
1049
1310
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1050
1311
  claimRemote, remoteHeads,
1051
1312
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1052
1313
  dirtyTracked, dirtyUntracked, dirtyAny,
1053
- ghAvailable, ghState, ghIssueEdit, ghListLabels, ghAssignedIssues,
1054
- ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit,
1055
- ghRunJobCount, ghRunJobs,
1314
+ ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1315
+ ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1316
+ ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1056
1317
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1057
1318
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1058
1319
  ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,