@feigi/fleet-ctl 0.0.0

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 (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,1640 @@
1
+ // Regression gate for the no-CI portability fix (#111): a repo with no
2
+ // workflow file must get its own `no-ci` verdict rather than sharing exit 2
3
+ // with "the question could not be answered", the workflow file must be
4
+ // discovered by the workflow's `name:` rather than assumed to be
5
+ // `.github/workflows/ci.yml`, and absence must never silently pass — only
6
+ // `--declare-no-ci` flips the gate.
7
+ //
8
+ // `gh` is stubbed on PATH and logs every call it receives, so a test can
9
+ // assert `run list`/`run view` were never reached under no-ci — the point of
10
+ // skipping them (#262's REST budget) is unverifiable without that log. `git`
11
+ // is real, and the repo fixture IS `git init`-ed: discovery anchors itself to
12
+ // `git rev-parse --show-toplevel`, so a non-repo fixture would exit 2 before
13
+ // reaching any of this. No `origin` is added, so `git remote get-url origin`
14
+ // still fails on its own and the behind-count block degrades to `null`,
15
+ // exactly the path it already has a contract for.
16
+
17
+ import { test } from "node:test";
18
+ import assert from "node:assert/strict";
19
+ import { spawnSync } from "node:child_process";
20
+ import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, readFileSync, statSync, openSync, closeSync } from "node:fs";
21
+ import { tmpdir } from "node:os";
22
+ import { join } from "node:path";
23
+ import { fileURLToPath } from "node:url";
24
+ import { stripComments } from "./strip-comments.mjs";
25
+
26
+ const SCRIPT = fileURLToPath(new URL("./ci-state.mjs", import.meta.url));
27
+
28
+ // A `gh` failure carries a MESSAGE, not just an exit code, and the cause a
29
+ // caller can act on lives only in that message. `$GH_FAIL_MSG` is how a test
30
+ // picks which cause this stub refuses with; empty — the default every fixture
31
+ // above already relies on — keeps the bare `exit 1` with a silent stderr.
32
+ const GH_STUB = `#!/bin/sh
33
+ echo "$*" >> "$GH_LOG"
34
+ fail() { [ -n "$GH_FAIL_MSG" ] && echo "$GH_FAIL_MSG" >&2; exit 1; }
35
+ case "$1 $2" in
36
+ "pr view") [ -f "$PR_VIEW_FILE" ] && cat "$PR_VIEW_FILE" || fail ;;
37
+ "run list") [ -f "$RUN_LIST_FILE" ] && cat "$RUN_LIST_FILE" || fail ;;
38
+ "run view") [ -f "$RUN_VIEW_FILE" ] && cat "$RUN_VIEW_FILE" || fail ;;
39
+ "repo view") [ -f "$REPO_VIEW_FILE" ] && cat "$REPO_VIEW_FILE" || fail ;;
40
+ *) fail ;;
41
+ esac
42
+ `;
43
+
44
+ const PR_HEAD = "abc123def";
45
+ const BRANCH = "fix/1";
46
+ const PR_VIEW = JSON.stringify({
47
+ headRefName: BRANCH,
48
+ headRefOid: PR_HEAD,
49
+ state: "OPEN",
50
+ mergeStateStatus: "CLEAN",
51
+ });
52
+ const RUN_LIST = JSON.stringify([
53
+ { databaseId: 1, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt: "2026-01-01T00:00:00Z" },
54
+ ]);
55
+ const RUN_VIEW = JSON.stringify({
56
+ jobs: [{ name: "check", status: "completed", conclusion: "success" }],
57
+ attempt: 1,
58
+ status: "completed",
59
+ conclusion: "success",
60
+ headSha: PR_HEAD,
61
+ });
62
+
63
+ // repoFiles: { "relative/path": "content" }, written under a fresh cwd.
64
+ // unreadable: repo-relative files OR directories chmod'ed 0o000 for the run and
65
+ // restored after, so a permission probe cannot leave an undeletable tmpdir.
66
+ // cwd: repo-relative directory to run from, for the repo-root anchoring test.
67
+ // git: `false` leaves the fixture outside any repo, for the routes that have to
68
+ // answer without a repo root.
69
+ // pr: the `--pr` value, defaulting to the digits every other fixture wants;
70
+ // `null` omits the flag entirely, for the tests that probe how the argument
71
+ // itself is refused rather than what it selects.
72
+ // gh responses default to the green fixtures above; pass `null` to make that gh
73
+ // subcommand fail (exit 1) if reached, so an unexpected call surfaces as a
74
+ // crash rather than silently serving the wrong fixture.
75
+ function run(args, { repoFiles = {}, unreadable = [], cwd = ".", pr = "42", prView = PR_VIEW, runList = RUN_LIST, runView = RUN_VIEW, ghFailMsg = "", tolerateUnparsedStdout = false, readOnlyStdout = false, nonBlockingStdout = false, git = true, origin = null, repoView = null, spawnEnv = {} } = {}) {
76
+ const repoDir = mkdtempSync(join(tmpdir(), "ci-state-repo-"));
77
+ // Discovery resolves `.github/workflows` off `git rev-parse --show-toplevel`,
78
+ // never the cwd, so a fixture that reaches discovery has to be a real repo.
79
+ // No remote is added by default: the behind-count block still degrades to
80
+ // null as before. `origin` opts a fixture in, for the behind-count block's
81
+ // own tests.
82
+ if (git) spawnSync("git", ["init", "-q", repoDir], { stdio: "ignore" });
83
+ if (origin !== null) spawnSync("git", ["remote", "add", "origin", origin], { cwd: repoDir, stdio: "ignore" });
84
+ const binDir = mkdtempSync(join(tmpdir(), "ci-state-bin-"));
85
+ for (const [rel, content] of Object.entries(repoFiles)) {
86
+ const full = join(repoDir, rel);
87
+ mkdirSync(join(full, ".."), { recursive: true });
88
+ writeFileSync(full, content);
89
+ }
90
+ mkdirSync(join(repoDir, cwd), { recursive: true });
91
+ const gh = join(binDir, "gh");
92
+ writeFileSync(gh, GH_STUB);
93
+ chmodSync(gh, 0o755);
94
+ const ghLog = join(binDir, "gh.log");
95
+ writeFileSync(ghLog, "");
96
+
97
+ const fixtureFile = (name, content) => {
98
+ if (content === null) return "";
99
+ const p = join(binDir, name);
100
+ writeFileSync(p, content);
101
+ return p;
102
+ };
103
+ const env = {
104
+ ...process.env,
105
+ PATH: `${binDir}:${process.env.PATH}`,
106
+ GH_LOG: ghLog,
107
+ GH_FAIL_MSG: ghFailMsg,
108
+ PR_VIEW_FILE: fixtureFile("pr-view.json", prView),
109
+ RUN_LIST_FILE: fixtureFile("run-list.json", runList),
110
+ RUN_VIEW_FILE: fixtureFile("run-view.json", runView),
111
+ REPO_VIEW_FILE: fixtureFile("repo-view.json", repoView),
112
+ // Last, so a test can deliberately put back a var #1599's scrub in
113
+ // tryRun() removes — that is the whole point of the ambient GIT_DIR/
114
+ // GIT_WORK_TREE tests below.
115
+ ...spawnEnv,
116
+ };
117
+ const restore = [];
118
+ for (const rel of unreadable) {
119
+ const full = join(repoDir, rel);
120
+ restore.push([full, statSync(full).mode & 0o777]);
121
+ chmodSync(full, 0o000);
122
+ }
123
+ // readOnlyStdout: hand the child a stdout it cannot write to, so its first
124
+ // write fails with EBADF rather than by racing a reader. CLOSING fd 1 does
125
+ // not do it — libuv reopens a closed standard fd onto /dev/null and the write
126
+ // then succeeds (measured), which is why this opens /dev/null read-only and
127
+ // passes that fd instead. spawnSync then reports no stdout for the child at
128
+ // all, so the eager parse below has nothing to read and skips.
129
+ const roStdout = readOnlyStdout ? openSync("/dev/null", "r") : null;
130
+ // nonBlockingStdout: the child's fd 1 starts out blocking and the script
131
+ // never opens a stream on it, so its writes there wait for the reader and
132
+ // cannot raise EAGAIN. This preloads a module whose whole body touches
133
+ // process.stdout, which opens that stream and puts fd 1 in O_NONBLOCK, the
134
+ // same as one console.log anywhere in the script would.
135
+ const preload = nonBlockingStdout ? ["--import", "data:text/javascript,process.stdout"] : [];
136
+ let r;
137
+ try {
138
+ // maxBuffer: spawnSync's default 1 MiB kills the child mid-write once its
139
+ // output passes it, and the pipe-survival fixtures below write past it on
140
+ // purpose.
141
+ r = spawnSync(process.execPath, [...preload, SCRIPT, ...(pr === null ? [] : ["--pr", pr]), ...args], {
142
+ cwd: join(repoDir, cwd),
143
+ encoding: "utf8",
144
+ env,
145
+ maxBuffer: 8 * 1024 * 1024,
146
+ ...(roStdout === null ? {} : { stdio: ["ignore", roStdout, "pipe"] }),
147
+ });
148
+ } finally {
149
+ if (roStdout !== null) closeSync(roStdout);
150
+ for (const [full, mode] of restore.reverse()) chmodSync(full, mode);
151
+ }
152
+ const log = readFileSync(ghLog, "utf8");
153
+ // Parsing eagerly is what lets every other test assert straight off `payload`,
154
+ // and a parse failure throwing here is the right default: it names a malformed
155
+ // payload at the test that produced it. The pipe-survival tests are the one
156
+ // exception — unparsed stdout is precisely their subject, so they opt out and
157
+ // assert on the raw bytes themselves.
158
+ let payload = null;
159
+ if (r.stdout && r.stdout.trim()) {
160
+ try {
161
+ payload = JSON.parse(r.stdout.trim().split("\n").pop());
162
+ } catch (e) {
163
+ if (!tolerateUnparsedStdout) throw e;
164
+ }
165
+ }
166
+ rmSync(repoDir, { recursive: true, force: true });
167
+ rmSync(binDir, { recursive: true, force: true });
168
+ return { ...r, payload, log };
169
+ }
170
+
171
+ const CI_WORKFLOW = `name: CI
172
+ on: [pull_request]
173
+ jobs:
174
+ check:
175
+ runs-on: ubuntu-latest
176
+ steps:
177
+ - run: echo hi
178
+ `;
179
+ const OTHER_WORKFLOW = `name: Release Label
180
+ on: [push]
181
+ jobs:
182
+ label:
183
+ runs-on: ubuntu-latest
184
+ steps:
185
+ - run: echo hi
186
+ `;
187
+
188
+ test("no .github/workflows directory: no-ci verdict, exit 1, never reads run list/view", () => {
189
+ const r = run([]);
190
+ assert.equal(r.status, 1);
191
+ assert.equal(r.payload.verdict, "no-ci");
192
+ assert.equal(r.payload.reasons.length, 1);
193
+ assert.match(r.payload.reasons[0], /declare-no-ci/);
194
+ assert.doesNotMatch(r.log, /run list/);
195
+ assert.doesNotMatch(r.log, /run view/);
196
+ });
197
+
198
+ test("no CI + --declare-no-ci: still no-ci verdict, but gate satisfied — exit 0", () => {
199
+ const r = run(["--declare-no-ci"]);
200
+ assert.equal(r.status, 0);
201
+ assert.equal(r.payload.verdict, "no-ci");
202
+ assert.match(r.payload.reasons[0], /gating on the caller's verified suite run/);
203
+ });
204
+
205
+ test("workflow file discovered by name, not the hard-coded ci.yml path — repo behaviour unchanged", () => {
206
+ const r = run([], {
207
+ repoFiles: {
208
+ ".github/workflows/pipeline.yml": CI_WORKFLOW, // not named ci.yml
209
+ ".github/workflows/release-label.yml": OTHER_WORKFLOW, // sibling, different name — must not confuse discovery
210
+ },
211
+ });
212
+ assert.equal(r.status, 0, r.stdout + r.stderr);
213
+ assert.equal(r.payload.verdict, "green");
214
+ assert.deepEqual(r.payload.reasons, []);
215
+ });
216
+
217
+ test("two workflow files share the target name: ambiguous, dies (exit 2) rather than guessing", () => {
218
+ const r = run([], {
219
+ repoFiles: {
220
+ ".github/workflows/a.yml": CI_WORKFLOW,
221
+ ".github/workflows/b.yml": CI_WORKFLOW,
222
+ },
223
+ });
224
+ assert.equal(r.status, 2);
225
+ assert.match(r.stderr, /pass --workflow-file to pick one/);
226
+ });
227
+
228
+ // Both routes to an unreadable workflow file refuse with exit 2, and they
229
+ // refuse at different depths: discovery opens each candidate as it scans, while
230
+ // an explicit --workflow-file target is not read until expectedJobs(). Kept as
231
+ // two cases because that difference is the point — a fix that closes only the
232
+ // scan leaves the explicit route reading the file as absent, and absent is the
233
+ // one shape that can be declared away as no-ci.
234
+ //
235
+ // The explicit route also runs OUTSIDE a repo — the second discrimination these
236
+ // two cases carry. Naming the file answers the question without a repo root, so
237
+ // a root lookup made eager again refuses a caller who never asked for
238
+ // discovery, and nothing else in this file runs the script from a non-repo cwd.
239
+ // The refusal is asserted down to its errno because `cannot read` alone is also
240
+ // what a path that never existed produces: drift between the argument and the
241
+ // fixture would leave this case pinning absence, the shape above.
242
+ for (const [route, args, opts] of [
243
+ ["the discovery scan", [], {}],
244
+ ["an explicit --workflow-file", ["--workflow-file", ".github/workflows/ci.yml"], { git: false }],
245
+ ]) {
246
+ test(`an unreadable workflow file reached through ${route}: exit 2, never no-ci`, (t) => {
247
+ if (process.getuid?.() === 0) return t.skip("root reads every file");
248
+ const r = run(args, {
249
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
250
+ unreadable: [".github/workflows/ci.yml"],
251
+ ...opts,
252
+ });
253
+ assert.equal(r.status, 2, r.stdout + r.stderr);
254
+ assert.match(r.stderr, /cannot read [^\n]*: EACCES: permission denied/);
255
+ });
256
+ }
257
+
258
+ // --- Error policy (#111): only a genuinely absent workflow set is `no-ci` ---
259
+ // The verdict must be reachable one way only: `.github/workflows/` absent, or
260
+ // present and holding no workflow files. Every other outcome — the directory
261
+ // unreadable, the target unreadable, files present under other names — is exit
262
+ // 2, "the question could not be answered", and `--declare-no-ci` must not
263
+ // convert any of them to exit 0. The four tests below pin one branch each,
264
+ // because the first review of this file reached merge with two of them wrong.
265
+
266
+ const CI_WORKFLOW_COMMENTED = CI_WORKFLOW.replace("name: CI", `name: "CI" # main pipeline`);
267
+
268
+ test("unreadable .github/workflows directory: exit 2, never no-ci — --declare-no-ci cannot let it through", (t) => {
269
+ if (process.getuid?.() === 0) return t.skip("root reads every directory");
270
+ for (const args of [[], ["--declare-no-ci"]]) {
271
+ // Same repo, same real CI: only the directory's mode differs. Reading this
272
+ // as no-ci reported "no CI configured" for a repo whose run was `failure`.
273
+ const r = run(args, {
274
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
275
+ unreadable: [".github/workflows"],
276
+ });
277
+ assert.equal(r.status, 2, r.stdout + r.stderr);
278
+ assert.match(r.stderr, /cannot read/);
279
+ assert.equal(r.payload, null);
280
+ }
281
+ });
282
+
283
+ test("workflow name with a trailing YAML comment (and quotes) still matches — a configured repo never reads as no-ci", () => {
284
+ const r = run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW_COMMENTED } });
285
+ assert.equal(r.status, 0, r.stdout + r.stderr);
286
+ assert.equal(r.payload.verdict, "green");
287
+ });
288
+
289
+ test("workflow files present but none named CI: exit 2 naming them, never a declarable no-ci", () => {
290
+ for (const args of [[], ["--declare-no-ci"]]) {
291
+ const r = run(args, {
292
+ repoFiles: {
293
+ ".github/workflows/release-label.yml": OTHER_WORKFLOW,
294
+ ".github/workflows/release.yml": OTHER_WORKFLOW.replace("Release Label", "Release"),
295
+ },
296
+ });
297
+ assert.equal(r.status, 2, r.stdout + r.stderr);
298
+ assert.match(r.stderr, /none named 'CI'/);
299
+ assert.match(r.stderr, /release-label\.yml/);
300
+ // The false statement this replaced: "no workflows configured under
301
+ // .github/workflows/" said of a directory full of workflows.
302
+ assert.doesNotMatch(r.stderr, /no workflows configured/);
303
+ }
304
+ });
305
+
306
+ test("an unreadable irrelevant sibling does not blind discovery to a readable target", (t) => {
307
+ if (process.getuid?.() === 0) return t.skip("root reads every file");
308
+ const r = run([], {
309
+ repoFiles: {
310
+ ".github/workflows/ci.yml": CI_WORKFLOW,
311
+ ".github/workflows/zz-other.yml": OTHER_WORKFLOW,
312
+ },
313
+ unreadable: [".github/workflows/zz-other.yml"],
314
+ });
315
+ assert.equal(r.status, 0, r.stdout + r.stderr);
316
+ assert.equal(r.payload.verdict, "green");
317
+ });
318
+
319
+ test("discovery is anchored to the repo root, not the cwd — a subdirectory answers the same", () => {
320
+ const r = run([], {
321
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
322
+ cwd: "scripts",
323
+ });
324
+ assert.equal(r.status, 0, r.stdout + r.stderr);
325
+ assert.equal(r.payload.verdict, "green");
326
+ });
327
+
328
+ // #1599: tryRun()'s single spawn primitive (used for both this script's git
329
+ // AND gh calls) passed no env at all before this fix, and #1020's own census
330
+ // could not see either of its two git call sites — its scan is `.sh`-only.
331
+ // Measured directly: an ambient GIT_DIR or GIT_WORK_TREE (a git hook,
332
+ // `rebase --exec`, `bisect run`) corrupts each call in its own distinct way,
333
+ // silently, at exit 0.
334
+ test("workflowsPath()'s rev-parse: an inherited GIT_WORK_TREE must not substitute a foreign toplevel for the caller's own repo root", () => {
335
+ const other = mkdtempSync(join(tmpdir(), "ci-state-other-"));
336
+ spawnSync("git", ["init", "-q", other], { stdio: "ignore" });
337
+ try {
338
+ const r = run([], {
339
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
340
+ // A subdirectory, the realistic shape: workflowsPath() never receives
341
+ // a repo root as an argument, it derives one from wherever the process
342
+ // happens to be running — measured, unscrubbed, an ambient
343
+ // GIT_WORK_TREE answers `--show-toplevel` with the AMBIENT path
344
+ // outright regardless of the real cwd, which then sends discovery
345
+ // looking for `.github/workflows` in a directory that is not this
346
+ // repository at all.
347
+ cwd: "scripts",
348
+ spawnEnv: { GIT_WORK_TREE: other },
349
+ });
350
+ assert.equal(r.status, 0, r.stdout + r.stderr);
351
+ assert.equal(r.payload.verdict, "green",
352
+ "an ambient GIT_WORK_TREE must not relocate workflow discovery into a foreign directory that has no .github/workflows");
353
+ } finally {
354
+ rmSync(other, { recursive: true, force: true });
355
+ }
356
+ });
357
+
358
+ test("the behind-count probe: an inherited GIT_DIR must not bind gh's --hostname to another repository's origin", () => {
359
+ // The real repository's own origin, and the OTHER (ambient) repository's —
360
+ // deliberately different hosts, so the logged `--hostname` argument tells
361
+ // the two apart unambiguously. `gh repo view` is stubbed to answer for the
362
+ // real repository regardless (it consults no git state at all), so the
363
+ // only way the wrong host can reach the logged `gh api` call is through
364
+ // `git remote get-url origin` answering for the ambient repository instead
365
+ // of the real one — measured, unscrubbed, that is exactly what an ambient
366
+ // GIT_DIR does.
367
+ const other = mkdtempSync(join(tmpdir(), "ci-state-other-"));
368
+ spawnSync("git", ["init", "-q", other], { stdio: "ignore" });
369
+ spawnSync("git", ["remote", "add", "origin", "https://ghe-other.example/other/other-repo.git"], { cwd: other, stdio: "ignore" });
370
+ try {
371
+ const r = run([], {
372
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
373
+ origin: "https://ghe-real.example/acme/real-repo.git",
374
+ repoView: JSON.stringify({ nameWithOwner: "acme/real-repo" }),
375
+ spawnEnv: { GIT_DIR: join(other, ".git") },
376
+ });
377
+ assert.equal(r.status, 0, r.stdout + r.stderr);
378
+ assert.match(r.log, /api --hostname ghe-real\.example /,
379
+ "an ambient GIT_DIR must not substitute the OTHER repository's origin host for this repository's own");
380
+ assert.doesNotMatch(r.log, /ghe-other\.example/,
381
+ `the ambient repository's host must never reach gh at all, and the log reads: ${r.log}`);
382
+ } finally {
383
+ rmSync(other, { recursive: true, force: true });
384
+ }
385
+ });
386
+
387
+ // expectedJobs() refuses on the assumption its derivation rests on, and that
388
+ // refusal has to land before the run query — the answer it would otherwise
389
+ // spend a REST read on is one it has already decided it cannot give. Nothing
390
+ // else in this file reaches the derivation's die() at all, so the gh log is
391
+ // what pins the order rather than the refusal alone.
392
+ const CI_WORKFLOW_NAMED_JOB = CI_WORKFLOW.replace(" check:\n", " check:\n name: Check\n");
393
+
394
+ test("an invalid job derivation refuses before the run list is ever requested", () => {
395
+ const r = run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW_NAMED_JOB } });
396
+ assert.equal(r.status, 2, r.stdout + r.stderr);
397
+ assert.match(r.stderr, /derivation invalid/);
398
+ assert.doesNotMatch(r.log, /run list/, `the derivation must refuse before the query, and gh was asked: ${r.log}`);
399
+ });
400
+
401
+ // --- The not-green detectors, one negative case each ------------------------
402
+ // No fixture above enters the `reasons.push` branches in the `else` arm, so
403
+ // none of them can catch one being deleted — and each such deletion is a silent
404
+ // false green reaching board.mjs's mapCi() and the merge bot's gate.
405
+
406
+ const TWO_JOB_WORKFLOW = `name: CI
407
+ on: [pull_request]
408
+ jobs:
409
+ check:
410
+ runs-on: ubuntu-latest
411
+ steps:
412
+ - run: echo hi
413
+ integration:
414
+ runs-on: ubuntu-latest
415
+ steps:
416
+ - run: echo hi
417
+ `;
418
+
419
+ const notGreen = (overrides, repoFiles = { ".github/workflows/ci.yml": CI_WORKFLOW }) =>
420
+ run([], { repoFiles, runView: JSON.stringify({ ...JSON.parse(RUN_VIEW), ...overrides }) });
421
+
422
+ test("run bound to another commit: not-green, exit 1 — the cancelled-run-on-a-superseded-SHA case", () => {
423
+ const r = notGreen({ headSha: "0000000" });
424
+ assert.equal(r.status, 1);
425
+ assert.equal(r.payload.verdict, "not-green");
426
+ assert.match(r.payload.reasons.join("; "), /run headSha 0000000 != PR head abc123def/);
427
+ });
428
+
429
+ test("run still in progress: not-green, exit 1 — an incomplete run is not a pass", () => {
430
+ const r = notGreen({ status: "in_progress" });
431
+ assert.equal(r.status, 1);
432
+ assert.equal(r.payload.verdict, "not-green");
433
+ assert.match(r.payload.reasons.join("; "), /run status is in_progress, not completed/);
434
+ });
435
+
436
+ test("expected job absent from the run: not-green, exit 1 — an absent job reads as pending, never as green", () => {
437
+ const r = notGreen({}, { ".github/workflows/ci.yml": TWO_JOB_WORKFLOW });
438
+ assert.equal(r.status, 1);
439
+ assert.equal(r.payload.verdict, "not-green");
440
+ assert.match(r.payload.reasons.join("; "), /expected jobs absent from the run: integration/);
441
+ });
442
+
443
+ test("`skipped` is not `passed`: a skipped job is not-green, exit 1", () => {
444
+ const r = notGreen({ jobs: [{ name: "check", status: "completed", conclusion: "skipped" }] });
445
+ assert.equal(r.status, 1);
446
+ assert.equal(r.payload.verdict, "not-green");
447
+ assert.match(r.payload.reasons.join("; "), /job check is skipped, not success/);
448
+ });
449
+
450
+ // gh's REAL shape for an in-progress job is conclusion:"" (empty string),
451
+ // never null — the same shape #1566 fixed in rank()'s tie-break. `??`
452
+ // only falls through on null/undefined, so `j.conclusion ?? j.status`
453
+ // would print the unreadable "job check is , not success" instead of
454
+ // naming the job's actual status.
455
+ test("in-progress job (conclusion \"\") not success: reason names the status, not an empty string", () => {
456
+ const r = notGreen({ jobs: [{ name: "check", status: "in_progress", conclusion: "" }] });
457
+ assert.equal(r.status, 1);
458
+ assert.equal(r.payload.verdict, "not-green");
459
+ assert.match(r.payload.reasons.join("; "), /job check is in_progress, not success/);
460
+ });
461
+
462
+ // The fifth reasons.push site in this arm — the one the "one negative case
463
+ // each" comment above missed (#930). It fires before notGreen's override even
464
+ // applies: matching.length === 0 short-circuits past the run-view read
465
+ // entirely, so this needs the run LIST overridden, not the run VIEW —
466
+ // notGreen only overrides the latter and cannot reach this branch at all.
467
+ test("no run in the list matches the PR head at all: not-green, exit 1 — the unbound-PR case", () => {
468
+ const [current] = JSON.parse(RUN_LIST);
469
+ const r = run([], {
470
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
471
+ runList: JSON.stringify([{ ...current, headSha: "0000000" }]),
472
+ });
473
+ assert.equal(r.status, 1);
474
+ assert.equal(r.payload.verdict, "not-green");
475
+ assert.match(r.payload.reasons.join("; "), /no CI run whose headSha equals the PR head abc123def/);
476
+ });
477
+
478
+ // --- #1410: two runs tied on head SHA AND createdAt to the second ----------
479
+ // A stable sort with no tie-break keeps gh's own (unspecified) API order on
480
+ // an exact createdAt tie. Measured live on PR #1402: two runs on the same
481
+ // head, started the same second, one cancelled and one completed, both 6
482
+ // jobs green — the tool bound to the cancelled duplicate. Recency (createdAt,
483
+ // truncated to the second) stays the PRIMARY key; conclusion only breaks a
484
+ // tie, so a newer in-progress run on an unrelated pair still beats an older
485
+ // completed one (see the untied-path test below) — promoting conclusion to
486
+ // primary would be a fresh regression, not a fix.
487
+ //
488
+ // Fixtures use gh's REAL run shape: a cancelled run reports
489
+ // status:"completed", conclusion:"cancelled" — its LIFECYCLE (status) is
490
+ // "completed", same as a successful run; only its OUTCOME (conclusion)
491
+ // differs. A comparator ranking on status alone (an earlier draft of this
492
+ // fix did exactly that) can never tell them apart, since both share
493
+ // status:"completed" — the original #1402 bug would stay unfixed for real
494
+ // GitHub data.
495
+
496
+ test("two runs share head SHA and createdAt to the second, one cancelled one completed: the completed run wins and a tie-break note reaches stderr — PR #1402, cancelled listed first", () => {
497
+ const createdAt = "2026-03-01T10:00:00Z";
498
+ const cancelled = { databaseId: 2, headSha: PR_HEAD, status: "completed", conclusion: "cancelled", event: "pull_request", createdAt };
499
+ const completed = { databaseId: 1, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt };
500
+ const r = run([], {
501
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
502
+ // Cancelled listed FIRST: with no tie-break, a stable sort on an exact
503
+ // createdAt tie keeps this API order and picks it — the exact shape
504
+ // measured on PR #1402.
505
+ runList: JSON.stringify([cancelled, completed]),
506
+ });
507
+ assert.equal(r.status, 0, r.stdout + r.stderr);
508
+ assert.equal(r.payload.verdict, "green");
509
+ assert.equal(r.payload.runId, completed.databaseId, "must bind to the completed run, not the cancelled sibling sharing its head and createdAt");
510
+ assert.match(r.log, new RegExp(`run view ${completed.databaseId}\\b`));
511
+ assert.match(r.stderr, new RegExp(`run selection tie-break.*chose #${completed.databaseId} \\(completed/success\\) over #${cancelled.databaseId} \\(completed/cancelled\\)`));
512
+ });
513
+
514
+ test("two runs share head SHA and createdAt to the second, one cancelled one completed: the completed run wins regardless of array order — mirrored order", () => {
515
+ const createdAt = "2026-03-01T10:00:00Z";
516
+ const cancelled = { databaseId: 2, headSha: PR_HEAD, status: "completed", conclusion: "cancelled", event: "pull_request", createdAt };
517
+ const completed = { databaseId: 1, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt };
518
+ const r = run([], {
519
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
520
+ // Completed listed FIRST this time. A stable sort would already pick it
521
+ // by accident in this order alone, so this test never proves the
522
+ // comparator does anything by itself — it only proves the reversed-order
523
+ // test above isn't vacuously passing because of array order.
524
+ runList: JSON.stringify([completed, cancelled]),
525
+ });
526
+ assert.equal(r.status, 0, r.stdout + r.stderr);
527
+ assert.equal(r.payload.verdict, "green");
528
+ assert.equal(r.payload.runId, completed.databaseId, "must bind to the completed run regardless of gh's response order");
529
+ });
530
+
531
+ test("two runs share head SHA, createdAt to the second, and conclusion rank: the numerically higher databaseId wins, not the lexicographically greater one", () => {
532
+ const createdAt = "2026-03-01T10:00:00Z";
533
+ // databaseId 9 and 10: "9" sorts ahead of "10" under a STRING compare
534
+ // (localeCompare), backwards from the numerically higher/newer id. Listed
535
+ // with the lexicographically-winning id first so a lingering string
536
+ // compare would pick it by accident too.
537
+ const lowerId = { databaseId: 9, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt };
538
+ const higherId = { databaseId: 10, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt };
539
+ const r = run([], {
540
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
541
+ runList: JSON.stringify([lowerId, higherId]),
542
+ });
543
+ assert.equal(r.status, 0, r.stdout + r.stderr);
544
+ assert.equal(r.payload.verdict, "green");
545
+ assert.equal(r.payload.runId, higherId.databaseId, "the numerically higher databaseId must win the final tie-break, not the lexicographically greater one");
546
+ assert.match(r.stderr, new RegExp(`run selection tie-break.*chose #${higherId.databaseId} \\(completed/success\\) over #${lowerId.databaseId} \\(completed/success\\)`));
547
+ });
548
+
549
+ test("two runs' createdAt differs only in the fractional-second component: still treated as a tie, not two distinct instants", () => {
550
+ // GitHub's createdAt is documented as whole-second precision, but the
551
+ // comparator truncates via bySecond() defensively. If the comparator
552
+ // instead compared full-precision strings, these two would never be
553
+ // grouped as tied — the cancelled run's fractionally-LATER createdAt would
554
+ // win on recency alone, and conclusion would never even be consulted.
555
+ const cancelled = { databaseId: 2, headSha: PR_HEAD, status: "completed", conclusion: "cancelled", event: "pull_request", createdAt: "2026-03-01T10:00:00.900Z" };
556
+ const completed = { databaseId: 1, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt: "2026-03-01T10:00:00.100Z" };
557
+ const r = run([], {
558
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
559
+ runList: JSON.stringify([cancelled, completed]),
560
+ });
561
+ assert.equal(r.status, 0, r.stdout + r.stderr);
562
+ assert.equal(r.payload.verdict, "green");
563
+ assert.equal(r.payload.runId, completed.databaseId, "sub-second createdAt drift must not hide a genuine tie; conclusion still decides");
564
+ assert.match(r.stderr, /run selection tie-break/);
565
+ });
566
+
567
+ test("untied path: a newer non-completed run still beats an older completed one on the same head — conclusion never outranks recency", () => {
568
+ const older = { databaseId: 5, headSha: PR_HEAD, status: "completed", conclusion: "success", event: "pull_request", createdAt: "2026-01-01T00:00:00Z" };
569
+ const newer = { databaseId: 6, headSha: PR_HEAD, status: "in_progress", conclusion: null, event: "pull_request", createdAt: "2026-01-02T00:00:00Z" };
570
+ const r = run([], {
571
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
572
+ runList: JSON.stringify([older, newer]),
573
+ runView: JSON.stringify({ jobs: [{ name: "check", status: "in_progress", conclusion: null }], attempt: 1, status: "in_progress", conclusion: null, headSha: PR_HEAD }),
574
+ });
575
+ assert.equal(r.status, 1);
576
+ assert.equal(r.payload.verdict, "not-green");
577
+ assert.equal(r.payload.runId, newer.databaseId, "recency stays primary: a newer in-progress run must still beat an older completed one when createdAt is NOT tied");
578
+ assert.doesNotMatch(r.stderr, /run selection tie-break/, "createdAt differs here, so no tie-break note should fire");
579
+ });
580
+
581
+ // --- #1566: rank()'s middle tier must match live gh data --------------------
582
+ // `gh run list --json conclusion` reports an empty string `""` for a
583
+ // non-completed run, never `null`. An earlier version of rank()'s middle
584
+ // tier required `r.conclusion === null`, so it silently never matched real
585
+ // data and a still-running run fell into the SAME bottom tier as a
586
+ // failed/cancelled one, losing an exact-createdAt tie it should win.
587
+ test("two runs share head SHA and createdAt to the second, one in-progress (conclusion \"\") one cancelled: the in-progress run wins the tie-break, not the cancelled one", () => {
588
+ const createdAt = "2026-03-01T10:00:00Z";
589
+ // In-progress listed with the LOWER databaseId: under the pre-fix bug both
590
+ // runs fall to the bottom tier (conclusion:"" never matches `=== null`),
591
+ // so the final databaseId tie-break picks the cancelled run (higher id) —
592
+ // the wrong winner. Only the fixed middle tier makes the in-progress run
593
+ // win despite its lower id.
594
+ const inProgress = { databaseId: 1, headSha: PR_HEAD, status: "in_progress", conclusion: "", event: "pull_request", createdAt };
595
+ const cancelled = { databaseId: 2, headSha: PR_HEAD, status: "completed", conclusion: "cancelled", event: "pull_request", createdAt };
596
+ const r = run([], {
597
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
598
+ runList: JSON.stringify([cancelled, inProgress]),
599
+ runView: JSON.stringify({ jobs: [{ name: "check", status: "in_progress", conclusion: "" }], attempt: 1, status: "in_progress", conclusion: "", headSha: PR_HEAD }),
600
+ });
601
+ assert.equal(r.status, 1);
602
+ assert.equal(r.payload.verdict, "not-green");
603
+ assert.equal(r.payload.runId, inProgress.databaseId, "still-running (conclusion \"\") must outrank a settled cancelled run in the tie-break, not lose to it on databaseId");
604
+ assert.match(r.stderr, new RegExp(`run selection tie-break.*chose #${inProgress.databaseId} \\(in_progress/\\) over #${cancelled.databaseId} \\(completed/cancelled\\)`));
605
+ });
606
+
607
+ // --- #169: a flag given with no value must die, never read as absent -------
608
+ // `base`/`workflow`/`workflow-file` all read via `arg(name) || default`, so a
609
+ // trailing flag previously fell straight through to the DEFAULT — the caller
610
+ // asked to gate on a specific base/workflow and silently got a real verdict
611
+ // against the wrong one instead of a refusal. Pinned as the priority site
612
+ // (feigi's PR #167 review comment): `ci-state.mjs --pr 5 --base` used to
613
+ // compare against `main` with no signal anything was wrong.
614
+
615
+ test("trailing --base (no value) dies (exit 2) rather than silently comparing against the default base", () => {
616
+ const r = run(["--base"]);
617
+ assert.equal(r.status, 2);
618
+ assert.match(r.stderr, /--base needs a value/);
619
+ assert.doesNotMatch(r.log, /pr view/, "must die before ever asking gh anything");
620
+ });
621
+
622
+ test("--workflow=CI form dies by name, not silently read as absent (indexOf cannot see it)", () => {
623
+ const r = run(["--workflow=CI"]);
624
+ assert.equal(r.status, 2);
625
+ assert.match(r.stderr, /--workflow needs a space-separated value/);
626
+ });
627
+
628
+ // #364: has() used exact argv.includes, so a boolean flag written --name=value
629
+ // (in ANY form the value takes) silently read as absent — dropping the
630
+ // caller's declared no-CI opt-out with no signal. The wording has to say
631
+ // "boolean flag", distinct from arg()'s "needs a space-separated value" above:
632
+ // a boolean has no value to give in the first place.
633
+ for (const flag of ["declare-no-ci", "quiet"]) {
634
+ for (const v of ["=true", "=false", "="]) {
635
+ test(`--${flag}${v} dies as a boolean flag, never silently read as absent`, () => {
636
+ const r = run([`--${flag}${v}`]);
637
+ assert.equal(r.status, 2);
638
+ assert.match(r.stderr, new RegExp(`--${flag} is a boolean flag, not --${flag}=`));
639
+ assert.doesNotMatch(r.log, /pr view/, "must die before ever asking gh anything");
640
+ });
641
+ }
642
+ }
643
+
644
+ // Position, not just spelling — and run()'s fixed `--pr 42` prepend does NOT
645
+ // supply it: a fixed prepend gives a FIXED offset, so all six cases in the
646
+ // loop above land their flag at process.argv[4] and a guard narrowed to that
647
+ // one index passes every one of them. Robustness needs the flag at DIFFERENT offsets across
648
+ // cases (#462 review); this is the only case that supplies one. --declare-no-ci
649
+ // is the flag worth spending it on: read as absent, it drops the caller's
650
+ // opt-out and the gate answers on a suite nobody ran.
651
+ test("--declare-no-ci=true dies behind another flag too, not only at the front of argv", () => {
652
+ const r = run(["--quiet", "--declare-no-ci=true"]);
653
+ assert.equal(r.status, 2);
654
+ assert.match(r.stderr, /--declare-no-ci is a boolean flag, not --declare-no-ci=/);
655
+ assert.doesNotMatch(r.log, /pr view/, "must die before ever asking gh anything");
656
+ });
657
+
658
+ // The control: the new `=` guard must not touch the bare spelling. --quiet's
659
+ // STDERR effect is what pins it here (--declare-no-ci's bare form is already
660
+ // pinned above, by its effect on verdict/exit code): vlog's command echoes
661
+ // vanish from stderr, though the same gh calls still ran (r.log is written by
662
+ // the stub itself, unconditionally). Its PAYLOAD effect is the next test's.
663
+ test("--quiet still reads as present in its bare spelling — the = refusal is not a blanket one", () => {
664
+ const loud = run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW } });
665
+ assert.equal(loud.status, 0, loud.stdout + loud.stderr);
666
+ assert.match(loud.stderr, /\$ gh pr view/);
667
+
668
+ const quiet = run(["--quiet"], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW } });
669
+ assert.equal(quiet.status, 0, quiet.stdout + quiet.stderr);
670
+ assert.doesNotMatch(quiet.stderr, /\$ gh pr view/);
671
+ assert.match(quiet.log, /pr view/, "gh still ran despite the quieter stderr");
672
+ });
673
+
674
+ // #677. The other half of what `--quiet` does, and the half the flag exists for:
675
+ // `jobs` and `missing` leave the JSON payload with it and are present without
676
+ // it. Same fixture both ways, so the flag is the only difference. The field
677
+ // names are spelled out rather than derived from ci-state.mjs — deriving them
678
+ // from the assignment under test would make this pass vacuously if that
679
+ // assignment changed, which is the one thing it must not do. The deriving is
680
+ // `quiet-payload-prose.test.mjs`'s job, over the prose that has to agree.
681
+ test("--quiet drops `jobs` and `missing` from the payload; without it they are there", () => {
682
+ const opts = { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW } };
683
+ const loud = run([], opts);
684
+ const quiet = run(["--quiet"], opts);
685
+ assert.equal(loud.status, 0, loud.stdout + loud.stderr);
686
+ assert.equal(quiet.status, 0, quiet.stdout + quiet.stderr);
687
+ for (const field of ["jobs", "missing"]) {
688
+ assert.ok(field in loud.payload, `without --quiet the payload must carry \`${field}\`, and it reads ${JSON.stringify(loud.payload)}`);
689
+ assert.ok(!(field in quiet.payload), `--quiet must drop \`${field}\` from the payload, and it reads ${JSON.stringify(quiet.payload)}`);
690
+ }
691
+ });
692
+
693
+ test("trailing --pr (no value, the entry flag itself) still dies naming the flag", () => {
694
+ const r = spawnSync(process.execPath, [SCRIPT, "--pr"], { encoding: "utf8" });
695
+ assert.equal(r.status, 2);
696
+ assert.match(r.stderr, /--pr needs a value/);
697
+ });
698
+
699
+ // The other two branches of the same guard: a flag eating the NEXT FLAG as its
700
+ // value, and an explicit whitespace-only value. Deleting either clause from
701
+ // arg() left this suite 18/18 green before these two existed.
702
+ test("--base followed by another flag is rejected, not read as the string \"--workflow\"", () => {
703
+ const r = run(["--base", "--workflow", "CI"]);
704
+ assert.equal(r.status, 2);
705
+ assert.match(r.stderr, /--base needs a value/);
706
+ assert.doesNotMatch(r.log, /pr view/, "must die before ever asking gh anything");
707
+ });
708
+
709
+ // #463 fallout: `--workflow-file` is the one flag this file used to read below
710
+ // its guards, in discoverWorkflowFile()'s caller. With the read there, this
711
+ // invocation refused with `unexpected argument 'main'` — --base's innocent
712
+ // value — instead of naming the flag given wrong (measured). The read is a
713
+ // statement above sweep() for that reason; putting it back reds this.
714
+ test("trailing --workflow-file names --workflow-file, not the innocent value of the flag behind it", () => {
715
+ const r = run(["--workflow-file", "--base", "main"]);
716
+ assert.equal(r.status, 2);
717
+ assert.match(r.stderr, /--workflow-file needs a value/);
718
+ assert.doesNotMatch(r.log, /pr view/, "must die before ever asking gh anything");
719
+ });
720
+
721
+ test("--base given a whitespace-only value dies rather than comparing against the default base", () => {
722
+ const r = run(["--base", " "]);
723
+ assert.equal(r.status, 2);
724
+ assert.match(r.stderr, /--base needs a value/);
725
+ });
726
+
727
+ // --- #269: parsing a gh reply is not the same as it being the right shape --
728
+ // A reply that parses cleanly but is the wrong shape (an error object where
729
+ // an array is expected, a run view missing its jobs) previously flowed on
730
+ // unchecked until the first dereference threw — and an uncaught throw exits
731
+ // 1, this script's code for "not bound-green". Each case below pins the
732
+ // class: exit 2, naming the query and the field, before the crash site is
733
+ // ever reached. #232's caution is why the row-level cases exist too — a
734
+ // guard that checks the array but not its elements is itself a partial
735
+ // guard, and jobs/runs rows are read (`j.name`, `r.headSha`) unguarded.
736
+
737
+ // Every assertion in this section is about the REFUSAL LINE, not about stderr
738
+ // as a whole: the diagnostic stream echoes each gh command before running it,
739
+ // and that echo carries `pr view`, `run view` and every field name in the
740
+ // `--json` list — `$ gh pr view 42 --json headRefName,headRefOid,state,...`
741
+ // (measured). `assert.match(r.stderr, /headRefName/)` is therefore satisfied
742
+ // by a refusal that names nothing at all, which leaves the exit status as the
743
+ // only load-bearing half of such a case. Asserting on the line itself is what
744
+ // makes the field name — and, for #926, what the line says gh actually SENT —
745
+ // load-bearing.
746
+ const refusal = (r) => r.stderr.split("\n").find((l) => l.includes("not the expected shape")) ?? "";
747
+
748
+ // #926. Each of these guards covers three distinct faults — the key absent,
749
+ // the value an empty string, the value not a string — and "missing <field>"
750
+ // asserted absence for all of them: measured, `{"headRefName":""}`,
751
+ // `{"headRefName":42}` and the key omitted printed one identical line, so a
752
+ // reader hunted for a key gh had in fact returned as `""`, `42` or `null`.
753
+ // Each row pins its own fault's rendering AND that the line does not tell
754
+ // another fault's story: a present value is never reported as an absent key,
755
+ // and an absent key never quotes a value nothing sent.
756
+ //
757
+ // The clause-level reachability these rows also carry: an empty string
758
+ // satisfies the type check and a number satisfies the emptiness check, so
759
+ // those rows are what keep each clause from being deletable. The absent rows
760
+ // are refused by both clauses at once and so pin neither — they are here for
761
+ // what the line SAYS, which is this ticket. What a lost clause costs is the
762
+ // field flowing on: `branch` becomes the empty string or a number and
763
+ // `gh run list --branch` asks for the wrong branch, while `prHead` becomes a
764
+ // value no run's headSha can equal, which reads as the superseded-SHA case
765
+ // rather than as a reply that could not be trusted.
766
+ for (const [what, field, prFields, saw, notSaw] of [
767
+ ["an absent branch name", "headRefName", { headRefOid: PR_HEAD }, /the key is absent/, /got /],
768
+ ["an empty branch name", "headRefName", { headRefName: "", headRefOid: PR_HEAD }, /got ""/, /absent/],
769
+ ["a non-string branch name", "headRefName", { headRefName: 42, headRefOid: PR_HEAD }, /got 42/, /absent/],
770
+ ["a null branch name", "headRefName", { headRefName: null, headRefOid: PR_HEAD }, /got null/, /absent/],
771
+ ["an absent head sha", "headRefOid", { headRefName: BRANCH }, /the key is absent/, /got /],
772
+ ["an empty head sha", "headRefOid", { headRefName: BRANCH, headRefOid: "" }, /got ""/, /absent/],
773
+ ["a non-string head sha", "headRefOid", { headRefName: BRANCH, headRefOid: 42 }, /got 42/, /absent/],
774
+ ["a null head sha", "headRefOid", { headRefName: BRANCH, headRefOid: null }, /got null/, /absent/],
775
+ ]) {
776
+ test(`PR info carrying ${what}: exit 2 naming the field and what gh sent, never a verdict built on it`, () => {
777
+ const r = run([], {
778
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
779
+ prView: JSON.stringify({ state: "OPEN", mergeStateStatus: "CLEAN", ...prFields }),
780
+ });
781
+ assert.equal(r.status, 2, r.stdout + r.stderr);
782
+ assert.match(r.stderr, /pr view/);
783
+ assert.match(refusal(r), new RegExp(field));
784
+ assert.match(refusal(r), saw);
785
+ assert.doesNotMatch(refusal(r), notSaw);
786
+ assert.doesNotMatch(r.log, /run list/, "must die before ever asking gh for runs");
787
+ });
788
+ }
789
+
790
+ test("run list returns an error object, not an array: exit 2, never the crash from runs.filter", () => {
791
+ // The ticket's own reproduction: gh exits 0 printing an error body where
792
+ // --json databaseId,headSha,... normally produces an array.
793
+ const r = run([], {
794
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
795
+ runList: JSON.stringify({ error: "rate limited" }),
796
+ });
797
+ assert.equal(r.status, 2, r.stdout + r.stderr);
798
+ assert.match(r.stderr, /run list/);
799
+ assert.match(r.stderr, /expected an array of runs/);
800
+ });
801
+
802
+ test("run list row is null: exit 2, never the crash reading r.headSha off null", () => {
803
+ const r = run([], {
804
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
805
+ runList: JSON.stringify([null]),
806
+ });
807
+ assert.equal(r.status, 2, r.stdout + r.stderr);
808
+ assert.match(r.stderr, /run list row 0 is not an object/);
809
+ });
810
+
811
+ // The same #926 split at the run-view guard, whose faults are two rather than
812
+ // three: the `jobs` key absent, and a `jobs` present but not an array.
813
+ // "missing jobs array" asserted the first for both of them (measured), and the
814
+ // second is the shape an error body or a partial run view takes — the value is
815
+ // right there to be quoted. `absent` stays a row of its own because it is the
816
+ // shape this guard was added for: it is the only thing between a missing key
817
+ // and `view.jobs.map(...)`, and an uncaught throw there exits 1 — "could not
818
+ // be read" rendered as a CI verdict, the whole #269 class.
819
+ for (const [what, runFields, saw, notSaw] of [
820
+ ["absent", {}, /the key is absent/, /got /],
821
+ ["an error object", { jobs: { error: "rate limited" } }, /got \{"error":"rate limited"\}/, /absent/],
822
+ ["a string", { jobs: "none" }, /got "none"/, /absent/],
823
+ ["null", { jobs: null }, /got null/, /absent/],
824
+ ]) {
825
+ test(`run view whose jobs is ${what}: exit 2 naming the field and what gh sent, never read as zero jobs`, () => {
826
+ const r = run([], {
827
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
828
+ runView: JSON.stringify({ attempt: 1, status: "completed", conclusion: "success", headSha: PR_HEAD, ...runFields }),
829
+ });
830
+ assert.equal(r.status, 2, r.stdout + r.stderr);
831
+ assert.match(refusal(r), /run view/);
832
+ assert.match(refusal(r), /jobs/);
833
+ assert.match(refusal(r), saw);
834
+ assert.doesNotMatch(refusal(r), notSaw);
835
+ });
836
+ }
837
+
838
+ // #926's own new hazard: the value a refusal quotes is gh's, so its length is
839
+ // gh's too — a `jobs` that came back as an error body carries however much
840
+ // text that body had, onto a stderr the fleet's CI monitor polls. So it is
841
+ // cut short, and says that it was: a tail dropped with no marker reads as the
842
+ // whole value, the same class of lie "missing" was. Asserted against whether
843
+ // the value's own unbroken run survives the cut, not against the cap's
844
+ // number, so tuning the cap does not red this — a smaller cap only cuts the
845
+ // run shorter, it does not make it survive.
846
+ test("a refusal quoting an unbounded value is cut short and says that it was", () => {
847
+ const huge = "x".repeat(400);
848
+ const r = run([], {
849
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
850
+ runView: JSON.stringify({ jobs: { error: huge }, attempt: 1, status: "completed", conclusion: "success", headSha: PR_HEAD }),
851
+ });
852
+ assert.equal(r.status, 2, r.stdout + r.stderr);
853
+ assert.match(refusal(r), /jobs/);
854
+ assert.match(refusal(r), /\(truncated\)/);
855
+ assert.doesNotMatch(
856
+ refusal(r),
857
+ /x{400}/,
858
+ `the refusal must not carry the whole value, and it reads ${refusal(r)}`,
859
+ );
860
+ });
861
+
862
+ // The direction this guard gets wrong on its own: what it wrongly REFUSES.
863
+ // Every jobs fixture above is malformed by construction, so none of them can
864
+ // show that the legitimate empty reply still reaches a verdict — and an empty
865
+ // `jobs` is legitimate: the guard's whole question is array-ness, a run with
866
+ // no job rows answers it, and the job-presence check below is what has an
867
+ // opinion about how many. A guard tightened from "is an array" onto
868
+ // truthiness or length would refuse it, and refusing a working invocation
869
+ // costs more than any diagnostic above gains. The verdict it must reach is
870
+ // not-green, by that job-presence check rather than by the shape check —
871
+ // which is also where the word "absent" belongs: about a job expected and
872
+ // missing from the run, never about a key gh did send.
873
+ test("run view whose jobs is an empty array is accepted — a verdict, never a shape refusal", () => {
874
+ const r = run([], {
875
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
876
+ runView: JSON.stringify({ jobs: [], attempt: 1, status: "completed", conclusion: "success", headSha: PR_HEAD }),
877
+ });
878
+ assert.equal(r.status, 1, r.stdout + r.stderr);
879
+ assert.equal(r.payload.verdict, "not-green");
880
+ assert.doesNotMatch(r.stderr, /not the expected shape/);
881
+ assert.match(r.stderr, /expected jobs absent from the run: check/);
882
+ });
883
+
884
+ test("a job entry in the run view is null: exit 2, never the crash reading j.name off null", () => {
885
+ const r = run([], {
886
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
887
+ runView: JSON.stringify({ jobs: [null], attempt: 1, status: "completed", conclusion: "success", headSha: PR_HEAD }),
888
+ });
889
+ assert.equal(r.status, 2, r.stdout + r.stderr);
890
+ assert.match(r.stderr, /job entry 0 is not an object/);
891
+ });
892
+
893
+ // The refusal names a POSITION, and a fixture whose malformed element sits
894
+ // first is satisfied by a guard that only answers "is one of them bad". Each
895
+ // site carries a well-formed element ahead of the bad one so the reported
896
+ // index has to be derived rather than guessed. Nothing reads the index today;
897
+ // it is the diagnostic a human gets for a reply gh really sent, so being wrong
898
+ // about which element was malformed sends them to the wrong one.
899
+ test("a run list row after a well-formed one is malformed: the refusal names that row's position", () => {
900
+ const [current] = JSON.parse(RUN_LIST);
901
+ const r = run([], {
902
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
903
+ runList: JSON.stringify([current, null]),
904
+ });
905
+ assert.equal(r.status, 2, r.stdout + r.stderr);
906
+ assert.match(r.stderr, /run list row 1 is not an object/);
907
+ });
908
+
909
+ test("a job entry after a well-formed one is malformed: the refusal names that entry's position", () => {
910
+ const view = JSON.parse(RUN_VIEW);
911
+ const r = run([], {
912
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
913
+ runView: JSON.stringify({ ...view, jobs: [...view.jobs, null] }),
914
+ });
915
+ assert.equal(r.status, 2, r.stdout + r.stderr);
916
+ assert.match(r.stderr, /job entry 1 is not an object/);
917
+ });
918
+
919
+ // The direction these guards get wrong on their own: what they wrongly REFUSE.
920
+ // Every fixture above is malformed by construction, so none of them can show
921
+ // that a well-formed reply carrying more than one row still reaches a verdict
922
+ // — and more than one row is the shape gh returns for any branch with a run
923
+ // history, the normal case rather than an edge one. A guard tightened past it
924
+ // refuses a working invocation, which costs more than the diagnostic above.
925
+ test("a run list whose rows are all well-formed still reaches a verdict, superseded rows included", () => {
926
+ const [current] = JSON.parse(RUN_LIST);
927
+ const r = run([], {
928
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
929
+ runList: JSON.stringify([
930
+ { ...current, databaseId: 2, headSha: "0000000", createdAt: "2025-12-31T00:00:00Z" },
931
+ current,
932
+ ]),
933
+ });
934
+ assert.equal(r.status, 0, r.stdout + r.stderr);
935
+ assert.equal(r.payload.verdict, "green");
936
+ });
937
+
938
+ // isObject is the whole refusal at the row and job level, so each of its
939
+ // clauses is load-bearing alone — at both sites, which take the same two shapes
940
+ // here. Every other malformed row and job fixture in this file is `null`, which
941
+ // the null clause already refuses on its own; an array and a scalar are what
942
+ // separate the other two clauses from decoration. Both degrade quietly rather
943
+ // than crashing, which is why they need pinning: either one yields `undefined`
944
+ // for every field read off it, so the run reports runs and jobs it never saw
945
+ // instead of refusing the reply.
946
+ for (const [what, malformed] of [
947
+ ["an array", []],
948
+ ["a scalar", "check"],
949
+ ]) {
950
+ test(`a job entry that is ${what}: exit 2, never read as a job with no fields`, () => {
951
+ const r = run([], {
952
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
953
+ runView: JSON.stringify({ jobs: [malformed], attempt: 1, status: "completed", conclusion: "success", headSha: PR_HEAD }),
954
+ });
955
+ assert.equal(r.status, 2, r.stdout + r.stderr);
956
+ assert.match(r.stderr, /job entry 0 is not an object/);
957
+ });
958
+
959
+ test(`a run list row that is ${what}: exit 2, never read as a run with no fields`, () => {
960
+ const r = run([], {
961
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
962
+ runList: JSON.stringify([malformed]),
963
+ });
964
+ assert.equal(r.status, 2, r.stdout + r.stderr);
965
+ assert.match(r.stderr, /run list row 0 is not an object/);
966
+ });
967
+ }
968
+
969
+ // The false-positive class the guard must NOT create: an in-progress job's
970
+ // `conclusion` is legitimately `null`, not a missing/wrong-shaped field. If
971
+ // the shape check validated field types instead of just object-ness, this
972
+ // well-formed reply would itself start being refused.
973
+ test("in-progress job with conclusion:null is accepted — not refused as malformed shape", () => {
974
+ const r = run([], {
975
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
976
+ runView: JSON.stringify({
977
+ jobs: [{ name: "check", status: "in_progress", conclusion: null }],
978
+ attempt: 1,
979
+ status: "in_progress",
980
+ conclusion: null,
981
+ headSha: PR_HEAD,
982
+ }),
983
+ });
984
+ assert.equal(r.status, 1, r.stdout + r.stderr); // not-green (still running) — never exit 2
985
+ assert.equal(r.payload.verdict, "not-green");
986
+ assert.doesNotMatch(r.stderr, /not the expected shape/);
987
+ });
988
+
989
+ // #365's other half. The sweep refuses any `--` token not in this script's
990
+ // known set, so a name missing from that set refuses an invocation this script
991
+ // accepts — "worse than the bug" by the ticket's own words. Measured, dropping
992
+ // `base` or `workflow` reddens THIS test and nothing else; the other four names
993
+ // also redden tests above, which happen to pass them.
994
+ //
995
+ // So: every flag ci-state.mjs accepts, in ONE green run. --workflow-file is the
996
+ // one that would not otherwise be here, because its arg() call sits far below
997
+ // the sweep, next to discoverWorkflowFile — the sweep needs the NAME, and a set
998
+ // built by reading down to the first gh call would miss it.
999
+ //
1000
+ // Relative to cwd on purpose: run() builds its repo in a fresh tmpdir this
1001
+ // scope cannot name, and the script resolves an explicit --workflow-file
1002
+ // against cwd, which run() sets to that repo.
1003
+ test("every flag ci-state.mjs accepts survives the unknown-flag sweep in one invocation", () => {
1004
+ const r = run(["--base", "main", "--workflow", "CI", "--workflow-file", ".github/workflows/ci.yml", "--declare-no-ci", "--quiet"], {
1005
+ repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW },
1006
+ });
1007
+ assert.equal(r.status, 0, `a working invocation was refused: ${r.stderr}`);
1008
+ // Live, not subsumed by the status assertion above: the behind-count block
1009
+ // TOLERATES its children — tryRun() swallows the failure and returns null
1010
+ // while execFileSync has already forwarded the child's stderr — so a child
1011
+ // refusing a flag lands here at exit 0 with `behind` silently null. Matches
1012
+ // git's "unknown option" as well as the fleet's own "unknown flag", because
1013
+ // the tolerated children are git's: measured, a bogus flag on the `git
1014
+ // remote get-url` call is otherwise 35/35 green.
1015
+ assert.doesNotMatch(r.stderr, /unknown (flag|option)/);
1016
+ assert.equal(r.payload.verdict, "green");
1017
+ });
1018
+
1019
+ // --- #262: a quota refusal is a distinguishable cause, not a generic failure -
1020
+ // Every `gh` read failure landed on one arm that reported the exit code and
1021
+ // nothing a caller could act on — an exhausted REST quota, a repo that cannot
1022
+ // be resolved and a revoked token were one undifferentiated cause. The correct
1023
+ // responses differ: a quota refusal recovers on its own and is worth re-probing
1024
+ // shortly, the others need someone to look, so the cause is named in the
1025
+ // PAYLOAD. That is where the fleet's gates read this script — `merge-gate.mjs`
1026
+ // gates every merge on the payload's own fields, and an empty payload, which is
1027
+ // all this arm produced, is `ci-unreadable` there: a probe that could not look,
1028
+ // never a reading about the PR.
1029
+ //
1030
+ // No test reached this arm before: every other exit-2 case here dies in
1031
+ // workflow discovery or in a shape check, never in the subprocess failure path.
1032
+ // `$GH_FAIL_MSG` is what makes the two causes drivable, and the pair below is
1033
+ // the point — either test alone passes a script that ignores the cause entirely.
1034
+
1035
+ // The quota refusal as `gh` actually words it, wrapping the REST body.
1036
+ const RATE_LIMIT_STDERR =
1037
+ "couldn't fetch workflows for feigi/claude-config: HTTP 403: API rate limit exceeded for user ID 1234.";
1038
+ // A failure that is NOT a quota refusal and never recovers by waiting.
1039
+ const MISSING_REPO_STDERR = "could not resolve to a Repository with the name 'feigi/nope'";
1040
+
1041
+ const ghFailure = (ghFailMsg) =>
1042
+ run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW }, runList: null, ghFailMsg });
1043
+
1044
+ test("a rate-limited gh read names the quota as its cause in the payload, at the unchanged exit 2", () => {
1045
+ const r = ghFailure(RATE_LIMIT_STDERR);
1046
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1047
+ assert.ok(r.payload, "a quota refusal must emit a payload — the cause is unreadable to a gate that only sees stderr");
1048
+ assert.equal(r.payload.verdict, "rate-limited");
1049
+ assert.match(r.payload.reasons.join("; "), /rate limit/i);
1050
+ // `pr` is the payload's only identifying field, and the fleet polls this
1051
+ // script for several PRs at once — an outage attributed to the wrong one, or
1052
+ // carrying a string where every other payload here carries a number, is
1053
+ // indistinguishable from a correct report at the point a caller reads it.
1054
+ // assert/strict, so this pins the type as well as the value.
1055
+ assert.equal(r.payload.pr, 42);
1056
+ // The refused query, not merely that a quota was mentioned: `pr view` is
1057
+ // GraphQL and `run list`/`run view` are REST, so which one was refused is
1058
+ // what separates an exhausted REST quota from a token or repo problem. The
1059
+ // fixture refuses `run list` — keep this literal in step with it.
1060
+ assert.match(r.payload.reasons.join("; "), /gh run list/);
1061
+ });
1062
+
1063
+ // GitHub's older spelling of the same self-clearing secondary limit, still
1064
+ // emitted by a GHE Server predating the rename. Without this the alternation in
1065
+ // RATE_LIMITED is unpinned: dropping it leaves every test above green, because
1066
+ // they all drive the current wording.
1067
+ const LEGACY_ABUSE_STDERR =
1068
+ "HTTP 403: You have triggered an abuse detection mechanism. Please wait a few minutes before you try again.";
1069
+
1070
+ test("the pre-rename secondary-limit wording is read as a quota refusal too", () => {
1071
+ const r = ghFailure(LEGACY_ABUSE_STDERR);
1072
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1073
+ assert.ok(r.payload, "the abuse-detection spelling is the same self-clearing limit under its old name");
1074
+ assert.equal(r.payload.verdict, "rate-limited");
1075
+ });
1076
+
1077
+ // The bound on that alternation: `abuse` alone appears in refusals no wait
1078
+ // clears, so matching the short form would tell a caller to re-probe a
1079
+ // repository that has been disabled outright.
1080
+ const DISABLED_REPO_STDERR =
1081
+ "HTTP 403: Repository access blocked. This repository has been disabled for abuse of GitHub's terms of service.";
1082
+
1083
+ test("a repository disabled for abuse is NOT a quota refusal", () => {
1084
+ const r = ghFailure(DISABLED_REPO_STDERR);
1085
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1086
+ assert.equal(r.payload, null, "a permanent block must not be reported as an outage that clears on its own");
1087
+ });
1088
+
1089
+ test("a gh read failing for any other reason reports exactly as it did before: exit 2, no payload", () => {
1090
+ const r = ghFailure(MISSING_REPO_STDERR);
1091
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1092
+ assert.equal(r.payload, null, "only a quota refusal earns a payload; every other cause is unchanged");
1093
+ assert.match(r.stderr, /gh failed/);
1094
+ });
1095
+
1096
+ // The outage payload must not be mistaken for a reading. A quota refusal is a
1097
+ // probe that could not look, so it reports no CI state at all. Emitting these
1098
+ // as nulls or empty arrays would let unobserved state read as observed: an
1099
+ // empty `missing` says "nothing is missing", which is a reading, where an
1100
+ // absent one is what `merge-gate.mjs`, which gates every merge on this
1101
+ // payload's own fields, reads as a probe that could not look rather than as
1102
+ // observed state.
1103
+ test("the outage payload reports no CI state it could not observe", () => {
1104
+ const r = ghFailure(RATE_LIMIT_STDERR);
1105
+ for (const field of ["status", "conclusion", "jobs", "missing", "runId"]) {
1106
+ assert.ok(
1107
+ !(field in r.payload),
1108
+ `a probe that never read CI must not report \`${field}\`, and the payload reads ${JSON.stringify(r.payload)}`,
1109
+ );
1110
+ }
1111
+ });
1112
+
1113
+ // #927: `jobs`/`missing` used to ship as `[]` on the no-ci arm too — module
1114
+ // scope initialises `let jobs = []`/`let missing = []` and the no-ci branch
1115
+ // never reaches the run-binding code that reassigns them, so every no-ci
1116
+ // payload carried them empty. An empty `missing` is a READING — "nothing is
1117
+ // missing" — and no-ci never took a reading: there was no workflow file to
1118
+ // derive an expected-job set from, let alone a run to check it against.
1119
+ // `emitRateLimited()` above already answers the identical "nothing was read"
1120
+ // question by omitting `jobs`/`missing` rather than shipping them empty —
1121
+ // covered by "the outage payload reports no CI state it could not observe"
1122
+ // above, which this test does not duplicate — and this pins that the no-ci
1123
+ // arm now answers it the same way.
1124
+ test("a payload for a question never asked — no-ci — omits `jobs`/`missing` rather than shipping them empty", () => {
1125
+ const noCi = run([]);
1126
+ assert.equal(noCi.status, 1, noCi.stdout + noCi.stderr);
1127
+ assert.equal(noCi.payload.verdict, "no-ci");
1128
+
1129
+ for (const field of ["jobs", "missing"]) {
1130
+ assert.ok(
1131
+ !(field in noCi.payload),
1132
+ `no-ci never binds a run, so \`${field}\` must be absent, not an empty array — and the payload reads ${JSON.stringify(noCi.payload)}`,
1133
+ );
1134
+ }
1135
+ });
1136
+
1137
+ // The declared-away flip only moves the exit code (#111) — it must not start
1138
+ // shipping `jobs`/`missing` back in, since `--declare-no-ci` still never binds
1139
+ // a run for this script to read either field from.
1140
+ test("no CI + --declare-no-ci: `jobs`/`missing` stay absent — the flag changes the gate, not what was read", () => {
1141
+ const r = run(["--declare-no-ci"]);
1142
+ assert.equal(r.status, 0, r.stdout + r.stderr);
1143
+ for (const field of ["jobs", "missing"]) {
1144
+ assert.ok(!(field in r.payload), `\`${field}\` must stay absent under --declare-no-ci too — got ${JSON.stringify(r.payload)}`);
1145
+ }
1146
+ });
1147
+
1148
+ // #890: the same one-line/one-terminator contract the verdict payload is held to
1149
+ // below, at the other call site that writes a payload to stdout. writeAll() appends
1150
+ // no newline of its own, so each site supplies its own: supplying none runs this
1151
+ // payload together with whatever the caller polling a rate-limited PR prints
1152
+ // next, and supplying two ends the output early for a reader that treats a blank
1153
+ // line as the end of it. Both were green here before this assertion — the
1154
+ // quota-refusal tests above all read `payload`, and the harness parses that from
1155
+ // a TRIMMED stdout, so every one of them is blind to the terminator by
1156
+ // construction.
1157
+ //
1158
+ // Compared against a re-serialisation of the payload this very run emitted
1159
+ // rather than against a literal copy of it, which is what keeps the assertion
1160
+ // about the terminator alone: rewording a reason, or adding a field, changes
1161
+ // both sides together and stays green, while any change to the trailing bytes
1162
+ // reds. A literal would instead have to be re-typed every time the refusal text
1163
+ // moved, and would red for the wrong reason when it was.
1164
+ test("the rate-limited payload is emitted byte for byte too: one line, one trailing newline", () => {
1165
+ const r = ghFailure(RATE_LIMIT_STDERR);
1166
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1167
+ assert.equal(r.stdout, `${JSON.stringify(r.payload)}\n`);
1168
+ });
1169
+
1170
+ // --- #840: a non-numeric --pr must refuse, never ship an unnamed payload -----
1171
+ // `--pr` was validated for truthiness alone, so `--pr abc` reached both payload
1172
+ // sites. Each builds `pr: Number(pr)`, and `JSON.stringify(NaN)` is `null` — the
1173
+ // normal path shipped a payload with no identifying field at exit 0 under
1174
+ // `verdict: "green"`, the verdict the fleet gates on.
1175
+ //
1176
+ // The gh receipt below is the load-bearing assertion, not decoration. Exit 2, an
1177
+ // empty stdout and a matching stderr line are each reproducible by a LATER
1178
+ // guard: downgrade this one to a warning and the script runs on, gh fails, and
1179
+ // die() reproduces all three while the warning still sits in stderr. Only a
1180
+ // refusal reached BEFORE the first query can show gh was never asked, so the
1181
+ // receipt is what pins fatality and the other three merely describe the refusal.
1182
+ //
1183
+ // `prView: null` is what keeps that argument true, and is not tidiness. Under
1184
+ // the green fixture the downgraded guard reaches a gh that ANSWERS, so the run
1185
+ // gets further than the refusal it is being compared against and diverges on
1186
+ // its exit code first — the assertion that reds is the status one, and the
1187
+ // receipt is never what caught it. A gh that fails when reached is what makes
1188
+ // exit 2, an empty stdout and a matching stderr line reproducible by the later
1189
+ // guard too, leaving the receipt as the only assertion that separates them.
1190
+ //
1191
+ // The stub also keeps a regressed guard off this repo's live GitHub data —
1192
+ // arg.test.mjs's own stubGhBin() gives the same two jobs, for the same shape of
1193
+ // guard.
1194
+ test("a non-numeric --pr refuses before any query, rather than reporting `pr: null`", () => {
1195
+ const r = run([], { pr: "abc", prView: null });
1196
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1197
+ assert.match(r.stderr, /--pr needs a number/);
1198
+ assert.equal(r.stdout.trim(), "", `a refusal ships no payload, and stdout reads ${r.stdout}`);
1199
+ assert.equal(r.log, "", `the refusal must land before the first gh read, and gh was asked: ${r.log}`);
1200
+ });
1201
+
1202
+ // Both anchors, separately. A guard that loses `$` still matches "42x" on its
1203
+ // digit prefix, and one that loses `^` still matches "x42" on its digit suffix,
1204
+ // so each value refuses only while its own anchor is present and neither mutant
1205
+ // survives the pair. What a surviving mutant lets through is this block's whole
1206
+ // defect back: Number("42x") is NaN, the payload's only identifying field
1207
+ // serializes to null, and `gh pr view 42x` resolves the value as a BRANCH — the
1208
+ // ambiguity the digits-only shape is chosen to forfeit against. Every other
1209
+ // --pr this suite feeds the guard is all digits or none, and both mutants agree
1210
+ // with the real guard on those.
1211
+ for (const pr of ["42x", "x42"]) {
1212
+ test(`a --pr mixing digits with non-digits refuses as \`abc\` does: ${pr}`, () => {
1213
+ const r = run([], { pr, prView: null });
1214
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1215
+ assert.match(r.stderr, /--pr needs a number/);
1216
+ assert.equal(r.stdout.trim(), "", `a refusal ships no payload, and stdout reads ${r.stdout}`);
1217
+ assert.equal(r.log, "", `the refusal must land before the first gh read, and gh was asked: ${r.log}`);
1218
+ });
1219
+ }
1220
+
1221
+ // The direction a new guard gets wrong on its own: what it wrongly REFUSES. A
1222
+ // suite that only feeds it invalid input pins nothing about the callers it must
1223
+ // keep working. board.mjs's runCiState() sends `String(pr)` off a numeric board
1224
+ // record, which is exactly the digits this harness defaults to — so a guard
1225
+ // tightened past them refuses a working invocation, the outcome #365's own AC
1226
+ // calls worse than the bug being fixed.
1227
+ //
1228
+ // assert/strict pins the TYPE as well as the value: `pr` reading back as the
1229
+ // string "42" would satisfy a loose check while breaking every consumer that
1230
+ // keys on a number, and reading back as `null` is the defect itself. Nothing
1231
+ // else covers the normal-path payload's `pr` — the sibling assertion in the
1232
+ // quota section covers the outage payload's.
1233
+ test("the numeric shape board.mjs sends is accepted, and the payload names its PR", () => {
1234
+ const r = run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW } });
1235
+ assert.equal(r.status, 0, r.stdout + r.stderr);
1236
+ assert.equal(r.payload.verdict, "green");
1237
+ assert.equal(r.payload.pr, 42);
1238
+ });
1239
+
1240
+ // `--pr 0` is the row the `=== null` absence check exists for, and the one a
1241
+ // later "simplification" back to `!pr` silently breaks: numArg() returns a
1242
+ // NUMBER, so `!pr` is true for a zero the caller plainly GAVE, and this file's
1243
+ // own usage die above would then answer it with "--pr is required" instead of
1244
+ // letting gh answer as no such PR. Companion to arg.test.mjs's identical row
1245
+ // for diff-stats.mjs and pr-overlap.mjs's own for `--a`/`--b` — #878's own
1246
+ // comment names all three callers as sharing this contract, and only
1247
+ // diff-stats.mjs had this row before.
1248
+ //
1249
+ // `strictEqual`, same reason as the "42" test above: a payload reading `pr`
1250
+ // back as the string "0" would satisfy a loose check while breaking every
1251
+ // consumer that keys on a number.
1252
+ test("#878: `--pr 0` reaches gh rather than drawing the usage line for an absent flag", () => {
1253
+ const r = run([], { pr: "0", repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW } });
1254
+ assert.equal(r.status, 0, r.stdout + r.stderr);
1255
+ assert.doesNotMatch(r.stderr, /usage:/, `--pr 0 was answered as an absent flag: ${r.stderr}`);
1256
+ assert.equal(r.payload.verdict, "green");
1257
+ assert.strictEqual(r.payload.pr, 0, `a zero PR must survive to the payload as 0: ${JSON.stringify(r.payload)}`);
1258
+ });
1259
+
1260
+ // What the new guard's PLACEMENT could newly break. It sits below the usage die
1261
+ // on purpose: RegExp.test coerces a null argument to the string "null", so a
1262
+ // guard merged into that die — or hoisted above it — answers an omitted --pr
1263
+ // with a complaint about a number and never prints the usage line at all. Both
1264
+ // spellings exit 2, so the exit code cannot tell them apart.
1265
+ test("--pr omitted still answers with the usage line, not the numeric complaint", () => {
1266
+ const r = run([], { pr: null, prView: null });
1267
+ assert.equal(r.status, 2, r.stdout + r.stderr);
1268
+ assert.match(r.stderr, /usage: ci-state\.mjs --pr <number>/);
1269
+ assert.doesNotMatch(r.stderr, /needs a number/, "an omitted --pr is a different mistake from a malformed one");
1270
+ assert.equal(r.log, "", `a usage refusal must also precede any gh read, and gh was asked: ${r.log}`);
1271
+ });
1272
+
1273
+ // --- The verdict payload has to survive a pipe ------------------------------
1274
+ // `console.log` + `process.exit()` loses whatever is still queued: on a pipe the
1275
+ // stdout write is asynchronous, the kernel accepts one buffer's worth
1276
+ // synchronously, and process.exit() discards the remainder rather than draining
1277
+ // it. The payload is then cut mid-JSON while the exit code arrives intact, so a
1278
+ // caller that reads the code sees a normal verdict and a caller that parses
1279
+ // stdout gets nothing it can use. emitRateLimited() already writes its payload
1280
+ // with writeSync for this reason; these tests hold the verdict payload to the
1281
+ // same standard.
1282
+ //
1283
+ // The mode under test is a stream the parent drains as the child writes, which
1284
+ // a file is not: the same payload reaches a file fd whole and is cut on
1285
+ // spawnSync's default stdio (measured), which is why these can reuse run() — a
1286
+ // harness that captured stdout to a file would pass whether or not the script
1287
+ // was ever fixed. That default stdio is not a FIFO but a Unix-domain SOCKET, on
1288
+ // darwin and Linux alike (#1730, fstat: isSocket() on fds 1 and 2). It starts
1289
+ // out blocking, and Node puts it in O_NONBLOCK once it opens a stream on it
1290
+ // (Linux /proc/self/fdinfo): console.log does that to fd 1, and fd 2 has been
1291
+ // through it by the time the verdict line is written, quiet or verbose.
1292
+ //
1293
+ // How far past "one buffer" a fixture has to reach is what that socket takes
1294
+ // in ONE non-blocking write, and that is not 64 KiB everywhere. Measured for
1295
+ // #1730 on 2026-09-24 with #1722's harness — a spawnSync child opens the fd's
1296
+ // stream, then makes one writeSync of N bytes — 200 trials per N per fd, Linux
1297
+ // being node:26-slim under Docker:
1298
+ //
1299
+ // darwin 65,536 bytes, every time.
1300
+ // Linux N up to 146,176 went through whole every time, on both fds. Past
1301
+ // it the first write took exactly 146,176 at the minimum and the
1302
+ // median of every N tried, up to 2 MiB — yet it also took the WHOLE
1303
+ // N some of the time, at every N: fd 2 took all of 146,177 38/200,
1304
+ // all of 200,000 4/200, all of 1 MiB 1/200.
1305
+ //
1306
+ // So Linux has a floor and no ceiling. The parent drains the socket while the
1307
+ // write is still in the kernel, and a write that races a quick enough reader
1308
+ // goes through whole at any size. #1722's 584,704 was the largest first write
1309
+ // in its sample, not a bound.
1310
+ //
1311
+ // These tests used to size themselves past 65,536 alone, and on Linux that
1312
+ // proved nothing. Against the regressions two of them exist to catch — the
1313
+ // payload back on console.log + process.exit, the stderr line back on one bare
1314
+ // writeSync — the 131,323-byte payload and 131,165-byte line they built went
1315
+ // out whole 200/200 times, so on Linux both passed the very defect they are
1316
+ // named for while their `> 65536` guards held. The green payload, 317,606
1317
+ // bytes, caught it 198/200.
1318
+ //
1319
+ // What the guards compare against is that floor: a payload at or under it goes
1320
+ // out in one write on Linux however the script writes it, so the test cannot
1321
+ // fail there, and it covers darwin's 65,536 too. It is measured rather than
1322
+ // derived from the fixture sizes below, which is what lets it catch the
1323
+ // fixture itself: the pre-#1730 one fails it, on darwin as well. A guard
1324
+ // against the constant a fixture is built from can never fail, and
1325
+ // arg.test.mjs's was exactly that until #1722.
1326
+ const LINUX_FIRST_WRITE_BYTES = 146_176;
1327
+
1328
+ // The fixture size is the other half, chosen from how often each regression
1329
+ // still got through at each size on Linux — not from the floor, and not on
1330
+ // "bigger is safer", which the runs refuted. Interleaved, 200 runs per size
1331
+ // per regression: the bare writeSync got the stderr line through whole 15
1332
+ // times at 2 MiB, against 0–1 from 292,352 to 1 MiB, with short first writes
1333
+ // at 2 MiB as large as 2,046,464; console.log got the payload through twice at
1334
+ // 292,352 and never from 584,704 up. 1 MiB is where both were lowest. A single
1335
+ // write is still unbounded — the race above — so on Linux these tests catch a
1336
+ // regression with high probability, not certainty; darwin, whose first write
1337
+ // is always 65,536, catches it every time.
1338
+ const SHORT_WRITE_BYTES = 1024 * 1024;
1339
+
1340
+ const jobId = (i) => `generated-job-${String(i).padStart(6, "0")}-padding-padding`;
1341
+
1342
+ // Derived rather than written as a literal number of jobs: the property that
1343
+ // matters is "past SHORT_WRITE_BYTES", and a hardcoded count silently stops
1344
+ // clearing it the moment the id shape or the payload's other fields change. The
1345
+ // ids are shaped the way expectedJobs() derives them, and carry no job-level
1346
+ // `name:`, which that derivation refuses.
1347
+ function jobsClearingShortWrite() {
1348
+ const ids = [];
1349
+ for (let joined = 0; joined <= SHORT_WRITE_BYTES; ) {
1350
+ const id = jobId(ids.length);
1351
+ ids.push(id);
1352
+ joined += id.length + ", ".length; // how the absent-jobs reason joins them
1353
+ }
1354
+ return ids;
1355
+ }
1356
+
1357
+ const workflowWithJobs = (ids) =>
1358
+ `name: CI\non: [pull_request]\njobs:\n${ids.map((id) => ` ${id}:\n runs-on: ubuntu-latest\n steps:\n - run: echo hi\n`).join("")}`;
1359
+
1360
+ const succeededJob = (name) => ({ name, status: "completed", conclusion: "success" });
1361
+
1362
+ const runViewAllSucceeded = (ids) =>
1363
+ JSON.stringify({
1364
+ jobs: ids.map(succeededJob),
1365
+ attempt: 1,
1366
+ status: "completed",
1367
+ conclusion: "success",
1368
+ headSha: PR_HEAD,
1369
+ });
1370
+
1371
+ // The green fixture cannot follow the other two to SHORT_WRITE_BYTES. Its jobs
1372
+ // arrive through `gh run view`, which ci-state.mjs reads with execFileSync's
1373
+ // default 1 MiB maxBuffer — one job past it and the read dies ENOBUFS, and the
1374
+ // script exits 2 with no verdict at all (measured: 11,397 jobs). So it carries
1375
+ // as many jobs as one run-view reply holds, and since the payload echoes the
1376
+ // same jobs back, that lands it at 1 MiB as well, by a different road.
1377
+ const GH_READ_BYTES = 1024 * 1024;
1378
+ function jobsFillingOneGhRead() {
1379
+ const ids = [];
1380
+ // One comma counted per job, one more than the reply carries: errs under.
1381
+ for (let bytes = runViewAllSucceeded([]).length; ; ) {
1382
+ const id = jobId(ids.length);
1383
+ bytes += JSON.stringify(succeededJob(id)).length + ",".length;
1384
+ if (bytes > GH_READ_BYTES) return ids;
1385
+ ids.push(id);
1386
+ }
1387
+ }
1388
+
1389
+ // --quiet is the mode the controller's CI Monitor polls in, and it drops `jobs`
1390
+ // and `missing` — so this also pins that the payload still outgrows one write
1391
+ // on the hot path, through `reasons` alone, where the absent-job reason names
1392
+ // every job it could not find.
1393
+ test("a not-green verdict payload too large for one non-blocking write reaches the caller whole", () => {
1394
+ const ids = jobsClearingShortWrite();
1395
+ const r = run(["--quiet"], {
1396
+ repoFiles: { ".github/workflows/ci.yml": workflowWithJobs(ids) },
1397
+ tolerateUnparsedStdout: true,
1398
+ });
1399
+ let payload;
1400
+ try {
1401
+ payload = JSON.parse(r.stdout);
1402
+ } catch (e) {
1403
+ assert.fail(`verdict payload did not survive the pipe: ${r.stdout.length} bytes, ${e.message}`);
1404
+ }
1405
+ assert.ok(
1406
+ r.stdout.length > LINUX_FIRST_WRITE_BYTES,
1407
+ `fixture no longer outgrows one write on Linux (${r.stdout.length} bytes, floor ${LINUX_FIRST_WRITE_BYTES}), so on Linux this test would pass without proving anything`,
1408
+ );
1409
+ assert.equal(payload.verdict, "not-green");
1410
+ assert.equal(r.status, 1, r.stderr);
1411
+ });
1412
+
1413
+ // The other direction, and the one a fix for the above can newly break. writeSync
1414
+ // throws where console.log swallows — on a saturated non-blocking pipe it raises
1415
+ // EAGAIN — and an uncaught throw here would skip the exit call entirely, dropping
1416
+ // the process to exit 1: the code this script reserves for not-green. A green PR
1417
+ // would then be reported as failing CI, which is worse than the truncation being
1418
+ // fixed. Green is also the only verdict that can carry a large payload without
1419
+ // `reasons`, so this is what exercises the write with `jobs` doing the growing.
1420
+ //
1421
+ // That throw needs fd 1 non-blocking, and on run()'s default stdio it never
1422
+ // is. The script opens no stream on fd 1, so the payload write blocks until
1423
+ // the reader has taken all of it and cannot raise EAGAIN (measured: 1 MiB in
1424
+ // one writeSync, 0/100 EAGAIN on darwin and on Linux). A Node caller passing
1425
+ // its own non-blocking stdout through changes nothing: the child still took
1426
+ // the whole MiB in one write, 20/20 on both. So without nonBlockingStdout,
1427
+ // deleting writeAll()'s EAGAIN catch left this test green every time, 20/20 on
1428
+ // darwin and 50/50 on Linux, while the other two --quiet tests here, the
1429
+ // not-green payload above and the stderr line below, went red through the
1430
+ // verdict line on fd 2.
1431
+ //
1432
+ // nonBlockingStdout opens the stream, and then this payload write meets EAGAIN
1433
+ // on its own. With the catch deleted it throws there: red 20/20 on darwin,
1434
+ // where the sampled runs exited 1 with the payload cut at 65,536 bytes. On
1435
+ // Linux fd 1 is non-blocking at that write too (fdinfo, 30/30), but the 1 MiB
1436
+ // usually goes out whole anyway, the no-ceiling race above, so this test caught
1437
+ // the same mutant only 19/150 times there. On Linux the two fd 2 tests are what
1438
+ // catch it, 50/50 each.
1439
+ test("a green verdict payload too large for one non-blocking write still exits 0, gate not inverted", () => {
1440
+ const ids = jobsFillingOneGhRead();
1441
+ const r = run([], {
1442
+ repoFiles: { ".github/workflows/ci.yml": workflowWithJobs(ids) },
1443
+ runView: runViewAllSucceeded(ids),
1444
+ nonBlockingStdout: true,
1445
+ tolerateUnparsedStdout: true,
1446
+ });
1447
+ let payload;
1448
+ try {
1449
+ payload = JSON.parse(r.stdout);
1450
+ } catch (e) {
1451
+ assert.fail(`verdict payload did not survive the pipe: ${r.stdout.length} bytes, ${e.message}`);
1452
+ }
1453
+ assert.ok(
1454
+ r.stdout.length > LINUX_FIRST_WRITE_BYTES,
1455
+ `fixture no longer outgrows one write on Linux (${r.stdout.length} bytes, floor ${LINUX_FIRST_WRITE_BYTES}), so on Linux this test would pass without proving anything`,
1456
+ );
1457
+ assert.equal(payload.verdict, "green");
1458
+ assert.equal(r.status, 0, r.stderr);
1459
+ });
1460
+
1461
+ // What the write must NOT change on every payload that was never at risk. console.log
1462
+ // appends exactly one newline and writeSync appends none of its own, so the
1463
+ // replacement has to supply it — supplying none concatenates the payload with
1464
+ // whatever a caller prints next, and supplying two breaks a reader that treats a
1465
+ // blank line as end of output. Pinned as exact bytes rather than "parses", which
1466
+ // all three spellings would satisfy.
1467
+ test("a payload that never reaches the buffer is emitted byte for byte as before: one line, one trailing newline", () => {
1468
+ const r = run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW } });
1469
+ assert.equal(r.status, 0, r.stderr);
1470
+ assert.equal(r.stdout, `${JSON.stringify(r.payload)}\n`);
1471
+ });
1472
+
1473
+ // The guard writeAll() puts around its write is what arg.mjs calls not
1474
+ // optional, and until here nothing in this repo EXECUTED it from this script:
1475
+ // deleting the try/catch outright and running this file, and then the whole
1476
+ // fleet suite, left both green (measured). The two tests above prove a
1477
+ // SUCCESSFUL oversized write survives; neither makes the write fail, so the
1478
+ // mechanism was pinned by prose alone. arg.test.mjs pins the same guard from
1479
+ // die()'s side — and since #1549 it is literally the same code, which is why
1480
+ // this test stays: it is the only one that executes it through THIS script's
1481
+ // exit-code contract.
1482
+ //
1483
+ // The failure is forced deterministically rather than by racing a reader: the
1484
+ // child's stdout is /dev/null opened READ-only, so the first writeSync raises
1485
+ // EBADF. A different errno from the EAGAIN in the field, and the same and only
1486
+ // thing writeAll() promises about either — the message may be lost, the exit code
1487
+ // may not.
1488
+ //
1489
+ // Green is the discriminating verdict, and the only one that discriminates: with
1490
+ // the guard, the payload is lost and exit 0 still lands; without it the EBADF
1491
+ // propagates, skips the process.exit() the tail is about to make, and Node falls
1492
+ // through to its default exit 1 — a green PR reported to the fleet's merge gate
1493
+ // as failing CI. That is the #299/#328 inversion itself, reproduced without the
1494
+ // race, so this discriminates on a machine where EAGAIN never fires. Measured
1495
+ // both ways: guarded exit 0, guard removed exit 1.
1496
+ test("the verdict write keeps the green exit code when it throws — the guard executed, not lifted", () => {
1497
+ const r = run([], { repoFiles: { ".github/workflows/ci.yml": CI_WORKFLOW }, readOnlyStdout: true });
1498
+ assert.equal(r.status, 0, `exit ${r.status}: the verdict write threw and took the green verdict with it`);
1499
+ });
1500
+
1501
+ // The verdict SUMMARY goes to fd 2, and fd 2 already has a Node stream open on
1502
+ // it by then — vlog's console.error, or under --quiet the git stderr
1503
+ // execFileSync forwards — which is what puts it in O_NONBLOCK. A
1504
+ // non-blocking write to a full pipe SHORT-WRITES: it returns the count it
1505
+ // managed and throws nothing, so the catch above never fires and nothing is
1506
+ // logged. Measured against this same fixture before the write loop consumed that
1507
+ // value: the line arrived cut at one buffer with its trailing newline gone, in
1508
+ // this quiet mode and in the verbose one, while stdout and the exit code came
1509
+ // through untouched — the one channel the tests above cannot speak for.
1510
+ //
1511
+ // Completeness is asserted by CONTENT, before the size guard rather than after.
1512
+ // The absent-job reason ends with the last id it joined, so a cut line simply
1513
+ // does not end with it; a truncated line is also one first write long — 65,535
1514
+ // bytes on darwin, most often 146,175 on Linux (measured, #1730) — which would
1515
+ // fail the size guard and blame the fixture for a defect in the script. Ordered
1516
+ // this way each failure names its own cause.
1517
+ test("the verdict line on stderr, too large for one non-blocking write, survives with its reasons whole", () => {
1518
+ const ids = jobsClearingShortWrite();
1519
+ const r = run(["--quiet"], {
1520
+ repoFiles: { ".github/workflows/ci.yml": workflowWithJobs(ids) },
1521
+ tolerateUnparsedStdout: true,
1522
+ });
1523
+ const line = r.stderr.split("\n").find((l) => l.includes("verdict="));
1524
+ assert.ok(line, `no verdict line on stderr at all, in ${r.stderr.length} bytes`);
1525
+ assert.ok(
1526
+ line.endsWith(ids[ids.length - 1]),
1527
+ `verdict line cut mid-reason at ${Buffer.byteLength(line)} bytes: it does not reach the last job it names`,
1528
+ );
1529
+ assert.ok(
1530
+ Buffer.byteLength(line) > LINUX_FIRST_WRITE_BYTES,
1531
+ `fixture no longer outgrows one write on Linux on stderr (${Buffer.byteLength(line)} bytes, floor ${LINUX_FIRST_WRITE_BYTES}), so on Linux this test would pass without proving anything`,
1532
+ );
1533
+ assert.equal(r.status, 1, "the exit code must survive the write it follows");
1534
+ });
1535
+
1536
+ // #901: the verdict summary is the writeAll() call site on fd 2, and the
1537
+ // terminator contract already held at the payload sites on stdout was never
1538
+ // pinned here. writeAll() appends no newline of its own, so each call site
1539
+ // supplies its own: supplying none runs this line together with whatever the
1540
+ // caller prints next, and supplying an extra ends the output early for a
1541
+ // reader that treats a blank line as the end of it.
1542
+ //
1543
+ // The completeness assertion covering this same line cannot stand in for that.
1544
+ // It locates the line by splitting stderr on "\n", and splitting on the
1545
+ // terminator is what discards it — every segment that yields is the content
1546
+ // BETWEEN newlines, so no wording of an assertion over that segment can see
1547
+ // whether the line was terminated at all. Measured before this test existed:
1548
+ // dropping the trailing newline left this file green.
1549
+ //
1550
+ // fd 2 also carries the vlog trace stream and gh's own forwarded stderr, so it
1551
+ // has no single expected byte string and the whole-stream equality the stdout
1552
+ // pins use has no equivalent here. This isolates the line instead — it locates
1553
+ // the summary by the verdict and reasons THIS run reported, then reads the
1554
+ // bytes on either side of it. Deriving the expected text from the emitted
1555
+ // payload rather than from a literal copy is what keeps the assertions about
1556
+ // the newlines alone: rewording a reason or adding a payload field moves both
1557
+ // sides together and stays green, as does rewording any trace.
1558
+ //
1559
+ // The LEADING newline is insurance for forwarded child stderr still draining
1560
+ // through the async stream without having ended its line — arg.mjs's die()
1561
+ // documents the same shape for the same reason. That RACE is what does not
1562
+ // reproduce here: the text before the summary has already ended its own line,
1563
+ // in this fixture a vlog trace and under --quiet git's forwarded `error: No
1564
+ // such remote 'origin'`. The BYTE is another matter — against already-ended
1565
+ // text the leading newline leaves a blank line and dropping it leaves none —
1566
+ // so it is pinned below, doubled as well as missing. What that leaves
1567
+ // untested is the mid-line landing the newline exists to prevent, not the
1568
+ // newline itself.
1569
+ test("the verdict summary on stderr carries exactly one newline of its own on each side", () => {
1570
+ const r = run([]);
1571
+ assert.ok(
1572
+ r.payload.reasons.length,
1573
+ "fixture no longer produces a reason, so the summary derived below would carry an em dash the script omits when reasons is empty, and this test would fail on the lookup rather than on the terminator",
1574
+ );
1575
+ const summary = `ci-state: verdict=${r.payload.verdict} — ${r.payload.reasons.join("; ")}`;
1576
+ const at = r.stderr.indexOf(summary);
1577
+ assert.ok(at >= 0, `the verdict summary is not on stderr as emitted, in ${JSON.stringify(r.stderr)}`);
1578
+ const before = r.stderr.slice(0, at);
1579
+ assert.equal(
1580
+ before.match(/\n*$/)[0].length,
1581
+ 2,
1582
+ `the summary's own leading newline must leave exactly one blank line after the already-ended text before it, which runs ${JSON.stringify(before.slice(-40))}`,
1583
+ );
1584
+ const after = r.stderr.slice(at + summary.length);
1585
+ assert.ok(
1586
+ after.startsWith("\n"),
1587
+ `the verdict summary is unterminated: it runs straight into ${JSON.stringify(after.slice(0, 40))}`,
1588
+ );
1589
+ assert.ok(
1590
+ !after.startsWith("\n\n"),
1591
+ "the verdict summary's terminator is doubled, ending the stream early for a reader that stops at a blank line",
1592
+ );
1593
+ });
1594
+
1595
+ // The shape pin. The test above executes the guard, and this one pins that the
1596
+ // write still goes through the SHARED loop — the two are independent: a body
1597
+ // that catches faithfully and still calls writeSync once satisfies the
1598
+ // behavioural test and reintroduces the short write, because a short write
1599
+ // never throws.
1600
+ //
1601
+ // #1549: this file used to pin its own copy of that loop, with a regex
1602
+ // differing from candidates.test.mjs's and staleness.test.mjs's only in head
1603
+ // line, Buffer.from argument and fd. Three near-copies pinning three
1604
+ // hand-mirrored loops is exactly what that ticket removed — the loop's shape,
1605
+ // its EAGAIN cap and its short-write resume are now pinned AND executed once,
1606
+ // in arg.test.mjs, against arg.mjs's writeAll().
1607
+ //
1608
+ // What is left for this file to pin is the half arg.test.mjs cannot see: that
1609
+ // ci-state.mjs still ROUTES through it. emit() was this script's own copy and
1610
+ // the only one of the three that never grew #889's retry cap, so the copy
1611
+ // coming BACK is the specific regression here — and it is invisible to every
1612
+ // behavioural test in this file, because a freshly hand-rolled loop behaves
1613
+ // identically on the day it is written and drifts only afterwards.
1614
+ //
1615
+ // Derived through stripComments() rather than matched against raw source: a
1616
+ // /m regex over raw source is satisfied by the correct shape sitting in a
1617
+ // block comment, and `^(?!\s*//)` closes neither escape (both measured, and
1618
+ // strip-comments.mjs's own header records them).
1619
+ test("ci-state.mjs routes every outbound write through arg.mjs's writeAll(), with no re-inlined loop of its own", () => {
1620
+ const source = stripComments(readFileSync(SCRIPT, "utf8"));
1621
+ assert.match(
1622
+ source,
1623
+ /^import \{[^}]*\bwriteAll\b[^}]*\} from "\.\/arg\.mjs";/m,
1624
+ "ci-state.mjs must import writeAll from ./arg.mjs rather than hand-rolling its own write loop",
1625
+ );
1626
+ // Measured: re-inlining an emit()-shaped loop into this file reds exactly
1627
+ // this assertion and nothing else in the suite.
1628
+ assert.equal(
1629
+ source.match(/\bwriteSync\(/g),
1630
+ null,
1631
+ "ci-state.mjs calls writeSync directly again — every write here must go through writeAll(), whose loop and EAGAIN cap are pinned once in arg.test.mjs",
1632
+ );
1633
+ // ...and the write is actually THERE: without this, deleting the verdict
1634
+ // write outright would satisfy the assertion above.
1635
+ assert.match(
1636
+ source,
1637
+ /^writeAll\(1, `\$\{JSON\.stringify\(payload\)\}\\n`\);/m,
1638
+ "the verdict payload must go out through writeAll() on fd 1 — the write every pipe-buffer test above is about",
1639
+ );
1640
+ });