@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,693 @@
1
+ // Regression gate for verify-sha.sh, the check that says whether a member's
2
+ // reported SHA is really on the branch it claims. Zero deps:
3
+ // `node --test plugin/scripts/verify-sha.test.mjs`.
4
+ //
5
+ // A shell script that reasons about git history can only be tested against real
6
+ // git history, so the cases below that reason about history build a throwaway
7
+ // origin+clone in a temp dir and run the script for real; a case that fails
8
+ // before the script reaches git does not.
9
+ //
10
+ // The load-bearing case is `a merge-base that fails rather than answers is exit
11
+ // 2, never reachable:false` (#266). Every non-zero status used to collapse into
12
+ // the definite verdict reachable:false at exit 1, so "the repository could not
13
+ // answer" and "the SHA is not on the branch" — the one distinction this script
14
+ // exists to make — were indistinguishable to the controller. Its two neighbours
15
+ // here, the reachable and the genuinely-not-reachable cases, are what keep the
16
+ // guard from over-firing: exit 1 has to survive as a real answer.
17
+
18
+ import { test } from "node:test";
19
+ import assert from "node:assert/strict";
20
+ import { execFileSync, spawnSync } from "node:child_process";
21
+ import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
22
+ import { tmpdir } from "node:os";
23
+ import { join } from "node:path";
24
+ import { fileURLToPath } from "node:url";
25
+
26
+ const SCRIPT = fileURLToPath(new URL("./verify-sha.sh", import.meta.url));
27
+
28
+ // Pin identity and cut the developer's ~/.gitconfig out of the fixture, so a
29
+ // local `pull.rebase` or hook cannot change what these repos look like. The
30
+ // GIT_* redirects would point the fixtures out of their own temp dirs.
31
+ const ENV = {
32
+ ...process.env,
33
+ GIT_DIR: undefined,
34
+ GIT_WORK_TREE: undefined,
35
+ GIT_TEMPLATE_DIR: undefined,
36
+ GIT_INDEX_FILE: undefined,
37
+ GIT_AUTHOR_NAME: "t",
38
+ GIT_AUTHOR_EMAIL: "t@example.com",
39
+ GIT_COMMITTER_NAME: "t",
40
+ GIT_COMMITTER_EMAIL: "t@example.com",
41
+ GIT_CONFIG_GLOBAL: "/dev/null",
42
+ GIT_CONFIG_SYSTEM: "/dev/null",
43
+ };
44
+
45
+ const git = (cwd, ...args) =>
46
+ execFileSync("git", args, { cwd, env: ENV, encoding: "utf8" }).trim();
47
+
48
+ // Absolute path to the real git, for any test that shadows `git` on PATH.
49
+ const REAL_GIT = execFileSync("sh", ["-c", "command -v git"], { encoding: "utf8" }).trim();
50
+
51
+ // Absolute path to the real sed, for the passthrough shim that controls the
52
+ // broken-escaper case. Resolved out here, where PATH is still the real one, and
53
+ // quoted at the exec, for the reasons the git shims below record at length.
54
+ const REAL_SED = execFileSync("sh", ["-c", "command -v sed"], { encoding: "utf8" }).trim();
55
+
56
+ /** Empty commit on the current branch; returns its sha. */
57
+ const commit = (w, msg) => {
58
+ git(w, "commit", "-q", "--allow-empty", "-m", msg);
59
+ return git(w, "rev-parse", "HEAD");
60
+ };
61
+
62
+ /** Bare origin + working clone with one commit on main. Returns the clone dir. */
63
+ function repo(t) {
64
+ const root = mkdtempSync(join(tmpdir(), "verify-sha-"));
65
+ t.after(() => rmSync(root, { recursive: true, force: true }));
66
+ const origin = join(root, "origin.git");
67
+ const w = join(root, "w");
68
+ execFileSync("git", ["-c", "init.defaultBranch=main", "init", "-q", "--bare", origin], { env: ENV });
69
+ execFileSync("git", ["clone", "-q", origin, w], { env: ENV });
70
+ commit(w, "root");
71
+ git(w, "branch", "-M", "main");
72
+ git(w, "push", "-q", "-u", "origin", "main");
73
+ return w;
74
+ }
75
+
76
+ function verify(cwd, branch, sha, env = ENV) {
77
+ const r = spawnSync("sh", [SCRIPT, branch, sha], { cwd, env, encoding: "utf8" });
78
+ return { code: r.status, json: r.stdout.trim() ? JSON.parse(r.stdout) : null, stderr: r.stderr };
79
+ }
80
+
81
+ test("a sha on the branch is reachable — exit 0", (t) => {
82
+ const w = repo(t);
83
+ const head = commit(w, "work that really landed");
84
+ git(w, "push", "-q", "origin", "main");
85
+
86
+ const { code, json } = verify(w, "main", head);
87
+ assert.equal(code, 0);
88
+ assert.equal(json.reachable, true);
89
+ assert.equal(json.sha, head);
90
+ assert.equal(json.tip, head);
91
+ });
92
+
93
+ test("a sha on a stray branch is not reachable — exit 1, the answer the script exists to give", (t) => {
94
+ const w = repo(t);
95
+ // The nested-worktree scenario from the script's header: a real commit in this
96
+ // repository that never made it onto the branch the member claims.
97
+ git(w, "checkout", "-q", "-b", "stray");
98
+ const stray = commit(w, "committed somewhere else");
99
+ git(w, "checkout", "-q", "main");
100
+ const tip = commit(w, "main moves on without it");
101
+ git(w, "push", "-q", "origin", "main");
102
+
103
+ const { code, json, stderr } = verify(w, "main", stray);
104
+ assert.equal(code, 1, "a real negative stays exit 1 — it is an answer, not a failure");
105
+ assert.equal(json.reachable, false);
106
+ assert.equal(json.tip, tip);
107
+ // Dropping `2>/dev/null` from the probe must not start leaking git noise onto
108
+ // the ordinary negative path: git says nothing at all when the answer is "no".
109
+ assert.doesNotMatch(stderr, /error:/, "a plain negative answer prints no git error");
110
+ });
111
+
112
+ test("a merge-base that fails rather than answers is exit 2, never reachable:false", (t) => {
113
+ // The #266 defect: `git merge-base --is-ancestor` exits 128 when it cannot walk
114
+ // the history — a corrupt or unreadable object — and every non-zero status used
115
+ // to collapse into the definite verdict reachable:false at exit 1. Shim only
116
+ // `merge-base`; everything else is real git, so the fetch and both preconditions
117
+ // pass exactly as they do in the field and none of the existing exit-2 guards
118
+ // fires. This is the same collapse #17 fixed in the sibling prove-merge.sh.
119
+ const w = repo(t);
120
+ const head = commit(w, "work that really landed");
121
+ git(w, "push", "-q", "origin", "main");
122
+
123
+ const bin = mkdtempSync(join(tmpdir(), "verify-sha-shim-"));
124
+ t.after(() => rmSync(bin, { recursive: true, force: true }));
125
+ // Ask the shell where git is, rather than deriving it from `--exec-path`: that
126
+ // answer is `<prefix>/libexec/git-core` on macOS but `/usr/lib/git-core` on
127
+ // Debian, where a `libexec` rewrite matches nothing and the shim execs a
128
+ // DIRECTORY — the fetch then fails first and this test measures the wrong
129
+ // failure. Resolved out here, where PATH is still the real one, and quoted at
130
+ // the exec: a git under a path with a space word-splits otherwise, and the
131
+ // fetch then dies first — which still satisfies the exit-2 and null-json
132
+ // assertions below, so only the stderr match would catch it.
133
+ writeFileSync(
134
+ join(bin, "git"),
135
+ `#!/bin/sh\n[ "$1" = merge-base ] && { echo "error: could not parse commit deadbeef" >&2; exit 128; }\nexec "${REAL_GIT}" "$@"\n`,
136
+ { mode: 0o755 },
137
+ );
138
+
139
+ const { code, json, stderr } = verify(w, "main", head, {
140
+ ...ENV,
141
+ PATH: `${bin}:${ENV.PATH ?? process.env.PATH}`,
142
+ });
143
+ assert.equal(json, null, "no verdict may be printed for a question that was never answered");
144
+ assert.equal(code, 2, "unanswerable is exit 2, not the exit 1 that means definitely-not-reachable");
145
+ assert.match(stderr, /cannot tell reachable from unanswerable/);
146
+ // The cause has to reach the operator, which is why the probe drops 2>/dev/null.
147
+ assert.match(stderr, /could not parse commit/, "git's own diagnosis must survive to stderr");
148
+ });
149
+
150
+ test("a sha that is not a commit in this repository is exit 2, not a negative verdict", (t) => {
151
+ // repo(t)'s root commit is enough: the 40-zero sha dies at the `cat-file -e`
152
+ // guard before merge-base runs, so where the tip sits is unobservable here.
153
+ const w = repo(t);
154
+ const { code, json, stderr } = verify(w, "main", "0".repeat(40));
155
+ assert.equal(code, 2);
156
+ assert.equal(json, null);
157
+ // Names the guard that fired, so this cannot pass on some other exit 2 — the
158
+ // fetch failing is also exit 2 with no stdout, which is why the code alone
159
+ // and an empty stdout are not enough to tell these two cases apart.
160
+ assert.match(stderr, /cannot resolve 0{40} to a commit in this repository/);
161
+ assert.match(stderr, /Not a valid object name/, "git's own diagnosis must survive to stderr");
162
+ });
163
+
164
+ test("a failed fetch carries git's own cause, and a bad URL no longer reads like a removed remote", (t) => {
165
+ // #559: these two produced byte-identical output, "cannot fetch origin/main —
166
+ // branch missing, or no network", naming neither failure. The sha is never
167
+ // reached in any of these — the fetch guard fires first — so 40 zeros will do.
168
+ const dead = "0".repeat(40);
169
+
170
+ const badUrl = repo(t);
171
+ git(badUrl, "remote", "set-url", "origin", "/nonexistent/path.git");
172
+ const a = verify(badUrl, "main", dead);
173
+
174
+ const noRemote = repo(t);
175
+ git(noRemote, "remote", "remove", "origin");
176
+ const b = verify(noRemote, "main", dead);
177
+
178
+ for (const r of [a, b]) {
179
+ assert.equal(r.code, 2);
180
+ assert.equal(r.json, null, "no verdict for a question that was never answered");
181
+ assert.match(r.stderr, /cannot fetch origin\/main/);
182
+ assert.doesNotMatch(r.stderr, /branch missing|no network/, "the guard no longer asserts a cause it cannot know");
183
+ assert.match(r.stderr, /does not appear to be a git repository/, "git's own diagnosis must survive to stderr");
184
+ }
185
+ // Only git's line tells the two apart, which is exactly what was discarded.
186
+ assert.match(a.stderr, /'\/nonexistent\/path\.git'/);
187
+ assert.doesNotMatch(b.stderr, /nonexistent/, "two distinct faults must not collapse into one message");
188
+
189
+ // The one cause the old list did name is still reported — now by git, and
190
+ // precisely, so dropping the list refuses nothing it used to explain.
191
+ const c = verify(repo(t), "nosuchbranch", dead);
192
+ assert.equal(c.code, 2);
193
+ assert.match(c.stderr, /cannot fetch origin\/nosuchbranch/);
194
+ assert.match(c.stderr, /couldn't find remote ref nosuchbranch/);
195
+ });
196
+
197
+ test("a failed fetch is fatal — the script stops rather than answering off a stale ref", (t) => {
198
+ // #574: the case above asserts exit 2, no JSON, and git's cause on stderr, and
199
+ // every one of those survives downgrading this guard's `die` to a warning. With
200
+ // the guard advisory the script runs ON: `origin/main` still resolves from the
201
+ // tracking ref the clone left behind, and the sha then dies at the `cat-file -e`
202
+ // guard — which independently gives exit 2, no stdout, and leaves the `cannot
203
+ // fetch` line and git's diagnosis sitting on stderr. Exit code, empty stdout and
204
+ // a stderr substring are each reproducible by a later guard, so no conjunction
205
+ // of them can see whether this one was fatal.
206
+ //
207
+ // What only fatality produces is the absence of progress: the `tip =` trace is
208
+ // echoed once the `rev-parse --verify` guard that follows this one has passed
209
+ // — and it does pass here, off the tracking ref — so the trace appears if and
210
+ // only if execution got past THIS guard. That line is pinned verbatim by "a
211
+ // healthy run stays quiet", so it cannot be reworded out from under this
212
+ // assertion unseen — and unlike a `doesNotMatch` on some later guard's
213
+ // message, it does not depend on which of them happens to fire, or on how it
214
+ // is worded.
215
+ const w = repo(t);
216
+ // One fixture: a bad URL and a removed remote both take this guard's `|| die`
217
+ // branch, differing only in git's own line — the distinction #565 pinned next
218
+ // door. This test is about the guard's fatality, not about telling causes apart.
219
+ git(w, "remote", "set-url", "origin", "/nonexistent/path.git");
220
+
221
+ const { code, json, stderr } = verify(w, "main", "0".repeat(40));
222
+ assert.equal(code, 2);
223
+ assert.equal(json, null);
224
+ assert.doesNotMatch(
225
+ stderr,
226
+ /origin\/main tip =/,
227
+ "a fetch that failed must stop the script, not warn and answer against an unupdated ref",
228
+ );
229
+ });
230
+
231
+ test("a fetch that succeeds but leaves origin/<branch> unresolvable is exit 2 at the rev-parse guard", (t) => {
232
+ const w = repo(t);
233
+ // Real git throughout, no shim: with no fetch refspec configured, `git fetch
234
+ // origin main` still succeeds — into FETCH_HEAD — without updating the
235
+ // remote-tracking ref, so deleting that ref leaves the second guard to fire
236
+ // while the first passes. A shim that killed the fetch would measure the
237
+ // wrong failure, since that is also exit 2 with no stdout.
238
+ git(w, "config", "--unset", "remote.origin.fetch");
239
+ git(w, "update-ref", "-d", "refs/remotes/origin/main");
240
+
241
+ const { code, json, stderr } = verify(w, "main", "0".repeat(40));
242
+ assert.equal(code, 2);
243
+ assert.equal(json, null);
244
+ assert.match(stderr, /origin\/main does not resolve after fetch/);
245
+ // #1146 added --verify to this capture, which changes git's own wording for
246
+ // this exact failure: `fatal: Needed a single revision`, not the `ambiguous
247
+ // argument` a bare `git rev-parse` prints for the same unresolvable ref.
248
+ assert.match(stderr, /fatal: Needed a single revision/, "git's own diagnosis must survive to stderr");
249
+ assert.doesNotMatch(stderr, /cannot fetch/, "the fetch passed — this is the guard after it");
250
+ });
251
+
252
+ test("a rev-parse that cannot resolve origin/<branch> is fatal — the script stops rather than answering off an empty tip", (t) => {
253
+ // #580, the defect #574 fixed one guard up. The case above asserts exit 2, no
254
+ // JSON, this guard's own message and git's cause — and every one of those
255
+ // survives downgrading this guard's `die` to a warning. With it advisory `tip`
256
+ // is empty, the script runs ON, and the `cat-file -e` guard below kills it:
257
+ // exit 2 again, no stdout again, and this guard's own line still sitting on
258
+ // stderr. Measured — the whole suite stayed green under that mutant, so no
259
+ // conjunction of those three can see whether this guard was fatal.
260
+ //
261
+ // What only fatality produces is the absence of progress. The `tip =` trace is
262
+ // echoed by the `echo` this guard falls through to, so it appears if and only
263
+ // if execution got past it, and it is pinned verbatim by "a healthy run stays
264
+ // quiet", so it cannot be reworded out from under this assertion unseen.
265
+ // git's own `Needed a single revision` (#1146 added --verify, which is what
266
+ // produces this exact wording rather than a bare rev-parse's `ambiguous
267
+ // argument`) is the other bracket: it proves rev-parse ran and failed HERE,
268
+ // rather than this test passing off an earlier guard that stopped the script
269
+ // before it. Neither bracket names a `die` string, so rewording any guard's
270
+ // message — this one included — leaves both standing.
271
+ const w = repo(t);
272
+ // The fixture of the case above: with no refspec configured the fetch still
273
+ // succeeds, into FETCH_HEAD, so deleting the tracking ref leaves this guard to
274
+ // fire while the one before it passes.
275
+ git(w, "config", "--unset", "remote.origin.fetch");
276
+ git(w, "update-ref", "-d", "refs/remotes/origin/main");
277
+
278
+ const { code, json, stderr } = verify(w, "main", "0".repeat(40));
279
+ assert.equal(code, 2);
280
+ assert.equal(json, null);
281
+ assert.match(stderr, /fatal: Needed a single revision/, "rev-parse ran and failed here, not some earlier guard");
282
+ assert.doesNotMatch(
283
+ stderr,
284
+ /origin\/main tip =/,
285
+ "a ref that does not resolve must stop the script, not warn and carry an empty tip onward",
286
+ );
287
+ });
288
+
289
+ // #1146: the tip capture (`tip=$(git rev-parse "origin/$branch")`) had no
290
+ // `--verify`. Without it, an unresolvable "origin/<branch>" falls back to
291
+ // treating the argument as a PATH: if a file or dir of that name sits in the
292
+ // cwd, rev-parse prints it and exits 0, and this guard's own `|| die` never
293
+ // fires. This differs from the case above only in that a colliding path
294
+ // exists — same missing tracking ref, same fetch, same everything else.
295
+ test("a rev-parse that would fall back to a colliding path is still fatal, and names the tip guard as the cause", (t) => {
296
+ const w = repo(t);
297
+ git(w, "config", "--unset", "remote.origin.fetch");
298
+ git(w, "update-ref", "-d", "refs/remotes/origin/main");
299
+ // The collision: a file at the exact path "origin/main" would print, at
300
+ // exit 0, wherever this guard let a bare `git rev-parse` fall back to it.
301
+ mkdirSync(join(w, "origin"), { recursive: true });
302
+ writeFileSync(join(w, "origin", "main"), "not a sha\n");
303
+
304
+ const { code, json, stderr } = verify(w, "main", "0".repeat(40));
305
+ assert.equal(code, 2);
306
+ assert.equal(json, null);
307
+ assert.match(stderr, /origin\/main does not resolve after fetch/, "this guard is what catches it");
308
+ assert.match(stderr, /fatal: Needed a single revision/, "git's own --verify diagnosis must survive to stderr");
309
+ // The discriminating pair: without --verify this guard does not catch this
310
+ // fixture at all. Measured 2026-09-03 against a single-point mutant (this
311
+ // capture with `--verify` removed, nothing else): the capture exits 0 with
312
+ // the colliding PATH as the tip, and the run dies at the `git cat-file -e`
313
+ // guard with `cannot resolve 0000… to a commit in this repository` — a
314
+ // refusal about the sha, not about the ref. It never reaches
315
+ // `git merge-base --is-ancestor`: an all-zero sha cannot clear `cat-file`.
316
+ // Reaching merge-base takes a real commit for a sha, which is the mutant
317
+ // test's fixture, not this one.
318
+ assert.doesNotMatch(stderr, /cannot resolve .* to a commit/,
319
+ "without --verify the colliding path is carried onward and the cat-file guard is what refuses — this guard must be the one that fires");
320
+ });
321
+
322
+ // The positive control criterion #1146 names explicitly: a real ref and a
323
+ // same-named path coexisting must still resolve the ref. Git's own
324
+ // precedence — try revision resolution before ever falling back to a path —
325
+ // makes this true for both the bare and the --verify forms; pinned here so a
326
+ // reader does not need to trust that reasoning, only this measurement.
327
+ test("a colliding path does not shadow a real remote-tracking ref", (t) => {
328
+ const w = repo(t);
329
+ const head = commit(w, "the ref, not the path, must win");
330
+ git(w, "push", "-q", "origin", "main");
331
+ mkdirSync(join(w, "origin"), { recursive: true });
332
+ writeFileSync(join(w, "origin", "main"), "not a sha\n");
333
+
334
+ const { code, json } = verify(w, "main", head);
335
+ assert.equal(code, 0);
336
+ assert.equal(json.reachable, true);
337
+ assert.equal(json.tip, head, "the real ref's sha, never the colliding path's name");
338
+ });
339
+
340
+ // The regression control: what a fixture whose sha is a REAL commit catches
341
+ // WITHOUT --verify. Not the fixture of the colliding-path test above, whose
342
+ // all-zero sha is refused earlier, by `git cat-file -e`; the sha is what
343
+ // routes a run to one guard or the other. And not the shape a reader might
344
+ // assume from the ticket's general description of this bug class (a
345
+ // malformed-but-parseable payload at exit 0). Measured 2026-09-03: the
346
+ // `git merge-base --is-ancestor` guard re-resolves the identical
347
+ // "origin/$branch" string, and merge-base has no path fallback, so it
348
+ // independently refuses (rc 128) whenever the ref genuinely does not exist.
349
+ // That guard's own `|| die` already fires — this script was fail-closed
350
+ // before this fix too, by whichever guard the sha routed it to. What the
351
+ // mutant actually costs is the DIAGNOSIS: it dies with "cannot tell reachable
352
+ // from unanswerable" — a guard that exists to catch a broken `merge-base`,
353
+ // not an unresolvable ref — never with the tip guard's own "does not resolve
354
+ // after fetch". An operator reading the refusal is told the wrong thing
355
+ // failed.
356
+ test("mutant: without --verify, the same fixture is still caught, but by the wrong guard", (t) => {
357
+ const w = repo(t);
358
+ // A real commit, so the mutant's bogus tip gets past `git cat-file -e` and
359
+ // reaches merge-base — the deepest point this bug can reach. Local existence
360
+ // is the whole requirement: what makes merge-base refuse is the deleted
361
+ // tracking ref, so this commit is deliberately NOT pushed.
362
+ const head = commit(w, "a real commit, so the mutant runs all the way to merge-base");
363
+ git(w, "config", "--unset", "remote.origin.fetch");
364
+ git(w, "update-ref", "-d", "refs/remotes/origin/main");
365
+ mkdirSync(join(w, "origin"), { recursive: true });
366
+ writeFileSync(join(w, "origin", "main"), "not a sha\n");
367
+
368
+ const scriptText = readFileSync(SCRIPT, "utf8");
369
+ const FIXED_LINE = 'tip=$(git rev-parse --verify "origin/$branch")';
370
+ assert.ok(scriptText.includes(FIXED_LINE), "the capture line moved — update this mutant to match");
371
+ const scratch = mkdtempSync(join(tmpdir(), "verify-sha-mutant-"));
372
+ t.after(() => rmSync(scratch, { recursive: true, force: true }));
373
+ const mutant = join(scratch, "verify-sha.sh");
374
+ writeFileSync(mutant, scriptText.replace(FIXED_LINE, 'tip=$(git rev-parse "origin/$branch")'), { mode: 0o755 });
375
+ // The mutant sources json.sh/net.sh next to itself ("$(dirname "$0")"), so
376
+ // both siblings have to travel with it or the run dies at the library guard
377
+ // instead of measuring anything about this mutant.
378
+ copyFileSync(fileURLToPath(new URL("./json.sh", import.meta.url)), join(scratch, "json.sh"));
379
+ copyFileSync(fileURLToPath(new URL("./net.sh", import.meta.url)), join(scratch, "net.sh"));
380
+
381
+ const r = spawnSync("sh", [mutant, "main", head], { cwd: w, env: ENV, encoding: "utf8" });
382
+ assert.equal(r.status, 2, "still fails closed — merge-base's own guard catches it either way");
383
+ assert.equal(r.stdout, "", "no payload either way — this bug never reaches the printf");
384
+ assert.match(r.stderr, /cannot tell reachable from unanswerable/, "caught by the WRONG guard");
385
+ assert.doesNotMatch(r.stderr, /origin\/main does not resolve after fetch/,
386
+ "and never names the real cause — restoring that name is what this fix buys");
387
+ });
388
+
389
+ test("an object that is present but is not a commit is not reported as absent", (t) => {
390
+ const w = repo(t);
391
+ const tree = git(w, "rev-parse", "HEAD^{tree}");
392
+ const { code, json, stderr } = verify(w, "main", tree);
393
+ assert.equal(code, 2);
394
+ assert.equal(json, null);
395
+ assert.match(stderr, /cannot resolve .+ to a commit in this repository/);
396
+ // The old wording asserted this object "is not a commit object in this
397
+ // repository". It is in this repository — git reads it and reports its real
398
+ // type, which is the half the guard was throwing away.
399
+ assert.match(stderr, /dereferences to tree type/, "git's own diagnosis must survive to stderr");
400
+ });
401
+
402
+ test("a sha the cat-file guard rejects is fatal — the script stops rather than asking merge-base about it", (t) => {
403
+ // #580's second site, and the one where the #574 remedy does not transcribe.
404
+ // The guards around this one each emit a progress marker once they pass — the
405
+ // `tip =` trace after the rev-parse guard, the `IS reachable` / `is NOT
406
+ // reachable` echoes inside the merge-base branch; this one emits none. The
407
+ // script emits nothing between it and the merge-base status guard, and on
408
+ // both fixtures its two sibling cases use — 40
409
+ // zeros, and a tree object — merge-base cannot resolve the object either, so
410
+ // it exits 128 and that status guard kills the run. Measured: exit 2, empty
411
+ // stdout and this guard's own line on stderr, all reproduced, and the suite
412
+ // stayed green under the mutant. Neither `reachable` echo is ever reached, so
413
+ // there is no marker here whose absence could be asserted.
414
+ //
415
+ // This fixture therefore removes the mask rather than looking for a marker
416
+ // that is not there. `git cat-file` is shimmed to fail — standing in for the
417
+ // unreadable object store this guard's own comment names as one of the things
418
+ // it fires on — and every other git call is real. `$sha` is a genuinely
419
+ // reachable commit, so with the guard downgraded merge-base answers normally
420
+ // and the script runs to completion, printing `reachable:true` at exit 0. The
421
+ // downgrade does not take a different route to exit 2; it returns the WRONG
422
+ // ANSWER, which is why the exit code and the payload are pinned here too.
423
+ const w = repo(t);
424
+ const head = commit(w, "work that really landed");
425
+ git(w, "push", "-q", "origin", "main");
426
+
427
+ const bin = mkdtempSync(join(tmpdir(), "verify-sha-catfile-shim-"));
428
+ t.after(() => rmSync(bin, { recursive: true, force: true }));
429
+ // Resolved out here, where PATH is still the real one, and quoted at the exec,
430
+ // for the reasons the merge-base shim above records at length.
431
+ writeFileSync(
432
+ join(bin, "git"),
433
+ `#!/bin/sh\n[ "$1" = cat-file ] && { echo "error: unable to read object" >&2; exit 1; }\nexec "${REAL_GIT}" "$@"\n`,
434
+ { mode: 0o755 },
435
+ );
436
+
437
+ const { code, json, stderr } = verify(w, "main", head, {
438
+ ...ENV,
439
+ PATH: `${bin}:${ENV.PATH ?? process.env.PATH}`,
440
+ });
441
+ assert.equal(code, 2);
442
+ assert.equal(json, null);
443
+ // The positive control, and this test needs one: shimming `git` wholesale
444
+ // could break the fetch instead, and a run that died two guards earlier gives
445
+ // exit 2 with an empty stdout just the same — this test would pass while
446
+ // measuring nothing. The `tip =` trace sits between the two, so it proves
447
+ // execution reached THIS guard, and the shim's own line proves cat-file is
448
+ // what failed. Both are pinned elsewhere: the trace verbatim by "a healthy run
449
+ // stays quiet", the shim's line by the shim right here.
450
+ assert.match(stderr, /origin\/main tip =/, "the fetch and the rev-parse guard both passed — this is the guard after them");
451
+ assert.match(stderr, /unable to read object/, "cat-file ran and failed, which is the failure under test");
452
+ assert.doesNotMatch(
453
+ stderr,
454
+ /IS reachable on origin\/main/,
455
+ "a sha this guard could not resolve must stop the script, not warn and then report it as reachable",
456
+ );
457
+ });
458
+
459
+ test("a healthy run stays quiet — the unmuted guards add nothing to stderr", (t) => {
460
+ const w = repo(t);
461
+ // Push from a second clone so `w`'s fetch has real objects to transfer: an
462
+ // already-up-to-date fetch would not exercise the path that could go noisy.
463
+ const other = join(w, "..", "other");
464
+ execFileSync("git", ["clone", "-q", join(w, "..", "origin.git"), other], { env: ENV });
465
+ const head = commit(other, "work that really landed");
466
+ git(other, "push", "-q", "origin", "main");
467
+
468
+ const { code, json, stderr } = verify(w, "main", head);
469
+ assert.equal(code, 0);
470
+ assert.equal(json.reachable, true);
471
+ // Exact, not a /fatal:/ sniff. Dropping `2>/dev/null` from three guards is
472
+ // only safe while all three stay silent when they succeed, and this script's
473
+ // stderr is read by the fleet controller. Anything git starts printing on an
474
+ // ordinary run shows up here as a fourth line.
475
+ assert.deepEqual(stderr.split("\n").filter(Boolean), [
476
+ "$ git fetch --quiet origin main",
477
+ ` origin/main tip = ${head}`,
478
+ ` ${head} IS reachable on origin/main`,
479
+ ]);
480
+ });
481
+
482
+ // No git fixture: the argc guard fires before the script runs any git at all,
483
+ // so the cwd never has to be a repository.
484
+ test("a wrong argument count is exit 2", () => {
485
+ const r = spawnSync("sh", [SCRIPT, "main"], { cwd: tmpdir(), env: ENV, encoding: "utf8" });
486
+ assert.equal(r.status, 2);
487
+ assert.match(r.stderr, /usage: verify-sha\.sh/);
488
+ });
489
+
490
+ // --- #119: the payload's own string fields.
491
+ //
492
+ // `git check-ref-format --branch 'evil"branch'` exits 0 — git accepts a double
493
+ // quote in a ref — so pushing a branch is all the access this needs. Spliced
494
+ // raw, the script emitted `{"branch":"evil"branch",…}` at **exit 0**: an
495
+ // unparseable payload with no signal at all that anything went wrong, while the
496
+ // contract row in `docs/specs/2026-07-23-fleet-plugin-design.md` documents the
497
+ // exit-0/1 payload as `{branch, sha, reachable, tip}`.
498
+ //
499
+ // Two of the three are reachable, not one. `$tip` is `git rev-parse`, which
500
+ // emits 40 hex characters and nothing else, and is wrapped for uniformity. But
501
+ // `$sha` is not: it is argv, and `git cat-file -e "${sha}^{commit}"` resolves
502
+ // any rev expression rather than only a hex object name — a REF name included —
503
+ // so a tag or branch holding a quote passes that gate and reaches the payload.
504
+ // The second test below is that vector, and it fails without the wrapping.
505
+ test("a branch name holding a double quote still emits parseable JSON", (t) => {
506
+ const w = repo(t);
507
+ const head = commit(w, "work on a hostile branch name");
508
+ git(w, "branch", 'evil"branch');
509
+ git(w, "push", "-q", "origin", 'evil"branch');
510
+
511
+ const r = spawnSync("sh", [SCRIPT, 'evil"branch', head], { cwd: w, env: ENV, encoding: "utf8" });
512
+
513
+ assert.equal(r.status, 0, "the sha IS on that branch — the quote must not change the verdict");
514
+ const json = JSON.parse(r.stdout);
515
+ assert.equal(json.branch, 'evil"branch', "and the field round-trips to the name that went in");
516
+ assert.equal(json.reachable, true);
517
+ assert.equal(json.tip, head);
518
+ });
519
+
520
+ // The `$sha` half of the same vector. `git cat-file -e 'evil"tag^{commit}'`
521
+ // resolves the TAG, so argv reaches the payload carrying a quote and the field
522
+ // is emitted as `"sha":"evil"tag"` — unparseable, at exit 0 — with the wrapping
523
+ // removed. Pinned separately from `$branch` because the two are independent
524
+ // operands of the same `&&` chain and either could be dropped alone.
525
+ test("a sha argument naming a quote-bearing ref still emits parseable JSON", (t) => {
526
+ const w = repo(t);
527
+ const head = commit(w, "work reachable by a hostile tag name");
528
+ git(w, "tag", 'evil"tag', head);
529
+ git(w, "push", "-q", "origin", "main");
530
+
531
+ const r = spawnSync("sh", [SCRIPT, "main", 'evil"tag'], { cwd: w, env: ENV, encoding: "utf8" });
532
+
533
+ assert.equal(r.status, 0, "the tag IS reachable on origin/main — the quote must not change the verdict");
534
+ const json = JSON.parse(r.stdout);
535
+ assert.equal(json.sha, 'evil"tag', "and the field round-trips to the argument that went in");
536
+ assert.equal(json.reachable, true);
537
+ });
538
+
539
+ // No backslash case here, deliberately: measured, `git branch 'back\slash'`
540
+ // and `git check-ref-format --branch 'back\slash'` both exit 128 — git refuses
541
+ // a backslash in a ref outright. A branch name is this script's ONLY string
542
+ // input, so `\` is unreachable and a test for it would pin fiction. The
543
+ // backslash vector is real on the scripts whose input is a worktree PATH.
544
+
545
+ test("an ordinary branch name is untouched — the escaping accepts what it should", (t) => {
546
+ // The false-positive half. A guard that mangles or refuses the names this
547
+ // script sees on every healthy run is a different bug from the one above.
548
+ const w = repo(t);
549
+ const head = commit(w, "ordinary");
550
+ git(w, "branch", "fix/119-json-sh-extract");
551
+ git(w, "push", "-q", "origin", "fix/119-json-sh-extract");
552
+
553
+ const r = spawnSync("sh", [SCRIPT, "fix/119-json-sh-extract", head], { cwd: w, env: ENV, encoding: "utf8" });
554
+
555
+ assert.equal(r.status, 0);
556
+ assert.equal(r.stdout, `{"branch":"fix/119-json-sh-extract","sha":"${head}","reachable":true,"tip":"${head}"}\n`,
557
+ "byte-identical to what this script has always emitted for a name with nothing to escape");
558
+ });
559
+
560
+ // #884: the escaping guard's FATALITY, which every case above is blind to. They
561
+ // each assert what a WORKING escaper produces, so none of them reaches the
562
+ // `|| die` that covers the escaper failing — measured, downgrading it to a
563
+ // message-preserving warning left this whole suite green.
564
+ //
565
+ // The downgrade does not emit a malformed payload. `branch_j`, `sha_j` and
566
+ // `tip_j` are assigned by one `&&` chain, so the first `jstr` that fails
567
+ // short-circuits the rest and leaves those names unset; with the guard advisory
568
+ // the `printf` references one and `set -u` aborts the shell. Measured on this
569
+ // fixture, whose sha IS reachable, stdout empty in every run: unmutated,
570
+ // /bin/sh (macOS bash 3.2.57) and /bin/dash alike exit 2 with the guard's own
571
+ // line. Downgraded, /bin/sh aborts at exit 1 saying `sha_j: unbound variable`,
572
+ // and /bin/dash aborts at exit 2 saying `sha_j: parameter not set`.
573
+ //
574
+ // Exit 1 is what this script's contract reads as "the sha is NOT reachable", so
575
+ // under a bash-family `sh` the downgrade is a confident wrong verdict. An
576
+ // unparseable payload would at least fail the caller's parse; a bare exit 1
577
+ // instead has `run-team/SKILL.md` flag the member, withhold the enqueue and
578
+ // hold the ticket until a maintainer rules — spent on a SHA that was on the
579
+ // branch the whole time.
580
+ //
581
+ // Which abort it is, though, is the shell's to choose and not this script's,
582
+ // and dash's lands on 2 — the very status a firing guard returns. `verify`
583
+ // spawns a bare `sh`, and `.github/workflows/ci.yml`'s `check` job runs on
584
+ // `ubuntu-latest`, where that name resolves to dash: an exit-code assertion
585
+ // therefore pins this guard on a developer's Mac and lets the mutant through
586
+ // on the runner that gates the merge. `sha_j` is what discriminates instead.
587
+ // It reaches stderr only from that nounset abort — measured under /bin/sh and
588
+ // /bin/dash, no healthy run, no genuine `not reachable`, no ordinary `die` and
589
+ // no firing of this guard puts it there — while a shell aborting on it names
590
+ // it first and words the rest however it likes. Matching a wording pins the
591
+ // shell that uses that wording and no other.
592
+ //
593
+ // `jstr` escapes through a `sed`/`tr` pipeline, so shadowing `sed` breaks the
594
+ // escaper without touching git. The git shims elsewhere in this file cannot
595
+ // reach this guard: every failure they inject kills the run before the payload
596
+ // is built.
597
+ //
598
+ // Two brackets stand in for a progress marker this guard does not have — the
599
+ // script prints nothing between the escaping and the `printf` it protects. The
600
+ // `IS reachable` trace is echoed only once merge-base has answered, so it
601
+ // proves the run cleared every earlier guard, and the shim's own line proves
602
+ // the escaper is what failed. Between them, no other guard can produce this
603
+ // signature. The trace is pinned verbatim by "a healthy run stays quiet", so it
604
+ // cannot be reworded out from under this assertion unseen, and no assertion
605
+ // here names a `die` message — rewording any of them, this guard's own
606
+ // included, leaves the pin standing.
607
+
608
+ /** A dir holding a `sed` shim with the given body, prepended to PATH. */
609
+ function sedShim(t, body) {
610
+ const bin = mkdtempSync(join(tmpdir(), "verify-sha-sed-shim-"));
611
+ t.after(() => rmSync(bin, { recursive: true, force: true }));
612
+ writeFileSync(join(bin, "sed"), `#!/bin/sh\n${body}\n`, { mode: 0o755 });
613
+ return `${bin}:${ENV.PATH ?? process.env.PATH}`;
614
+ }
615
+
616
+ test("an escaper that cannot run is exit 2, never the exit 1 that means `not reachable`", (t) => {
617
+ const w = repo(t);
618
+ const head = commit(w, "work that really landed");
619
+ git(w, "push", "-q", "origin", "main");
620
+
621
+ const { code, json, stderr } = verify(w, "main", head, {
622
+ ...ENV,
623
+ PATH: sedShim(t, 'echo "sed: outage" >&2\nexit 1'),
624
+ });
625
+
626
+ // Whether this fixture measured the guard at all is settled before its
627
+ // verdict is read: an assertion that fails masks every one after it, and
628
+ // "the shim broke something else" and "the guard is not fatal" are not
629
+ // interchangeable diagnoses.
630
+ assert.match(stderr, /sed: outage/, "the escaper ran and failed, which is the failure under test");
631
+ assert.match(
632
+ stderr,
633
+ /IS reachable on origin\/main/,
634
+ "merge-base answered — this is the guard after it, not an earlier one the shim happened to break",
635
+ );
636
+
637
+ assert.equal(
638
+ code,
639
+ 2,
640
+ "a payload that could not be escaped is `the question could not be answered`. Exit 1 would report a sha that IS on the branch as missing from it, and the controller would flag the member and hold its ticket for a maintainer's ruling.",
641
+ );
642
+ assert.equal(json, null, "no verdict may be printed for a payload that was never escaped");
643
+ assert.doesNotMatch(
644
+ stderr,
645
+ /sha_j/,
646
+ "the guard must stop the script, not warn and leave the payload `printf` reading names the `&&` chain never assigned. The NAME, never the wording: bash says `sha_j: unbound variable` at exit 1 and dash `sha_j: parameter not set` at exit 2, so a wording match and the exit-2 assertion each pass on the mutant under the shell CI actually runs.",
647
+ );
648
+ });
649
+
650
+ test("a shadowed `sed` that works is answered normally — the guard refuses only a real outage", (t) => {
651
+ // The false-positive half, and the control the case above needs: shadowing
652
+ // `sed` on PATH is not by itself fatal to this script. Same fixture and the
653
+ // same shadowed name, a passthrough body — so the exit 2 up there is the
654
+ // escaper failing, not the shim's mere presence. Without this, that case
655
+ // could be measuring a PATH it broke wholesale and still read green.
656
+ const w = repo(t);
657
+ const head = commit(w, "ordinary");
658
+ git(w, "push", "-q", "origin", "main");
659
+
660
+ const r = spawnSync("sh", [SCRIPT, "main", head], {
661
+ cwd: w,
662
+ env: { ...ENV, PATH: sedShim(t, `exec "${REAL_SED}" "$@"`) },
663
+ encoding: "utf8",
664
+ });
665
+
666
+ assert.equal(r.status, 0, "the sha IS reachable — a working escaper must not change the verdict");
667
+ assert.equal(
668
+ r.stdout,
669
+ `{"branch":"main","sha":"${head}","reachable":true,"tip":"${head}"}\n`,
670
+ "byte-identical to the payload this script emits with no shim in the way",
671
+ );
672
+ });
673
+
674
+ // `.` is a POSIX special builtin, so failing to open its operand aborts a
675
+ // non-interactive shell before any `||` on the line can run — measured, /bin/sh
676
+ // (macOS bash 3.2), bash 3.2 and `bash --posix` all exit 1 with the guard
677
+ // unfired. Exit 1 out of THIS script means `the sha is not reachable`, the one
678
+ // distinction it exists to make. A missing file must never be able to say that.
679
+ test("a missing json.sh is exit 2, never the exit 1 that means `not reachable`", (t) => {
680
+ const w = repo(t);
681
+ const head = commit(w, "work");
682
+ git(w, "push", "-q", "origin", "main");
683
+ const lone = mkdtempSync(join(tmpdir(), "verify-sha-nolib-"));
684
+ t.after(() => rmSync(lone, { recursive: true, force: true }));
685
+ copyFileSync(SCRIPT, join(lone, "verify-sha.sh"));
686
+
687
+ const r = spawnSync("sh", [join(lone, "verify-sha.sh"), "main", head], { cwd: w, env: ENV, encoding: "utf8" });
688
+
689
+ assert.equal(r.status, 2,
690
+ "a missing library is `the question could not be answered`. Exit 1 would report a sha that IS on the branch as missing from it, and the controller would reject a PR that is exactly where it claims to be.");
691
+ assert.match(r.stderr, /json\.sh/, "and it names the file rather than blaming the fetch or the ref");
692
+ assert.equal(r.stdout, "", "no payload: nothing was answered");
693
+ });