@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,97 @@
1
+ // #836. `docs/agents/triage-labels.md`'s Meaning column is a TRANSCRIPT of the
2
+ // tracker's own label descriptions — three of the five cells were byte-identical
3
+ // to `gh api repos/feigi/claude-config/labels/<name> --jq .description` when this
4
+ // was written. A transcript has no owner, so it drifts against whichever side
5
+ // moves. ADR 0001 repriced the filing bar to "is the defect confirmed"; the
6
+ // `ready-for-agent` cell kept saying "Fully specified", which a remedy-open
7
+ // ticket is by construction not.
8
+ //
9
+ // The fix was to strip the criterion rather than restate it, so what needs
10
+ // guarding is a RE-ADDITION, and its vector is named and still live: the
11
+ // `ready-for-agent` description on the tracker still carries the old wording,
12
+ // and anyone re-syncing this column from it puts the contradiction back.
13
+ //
14
+ // #836 raises the `ready-for-agent` cell alone. The `ready-for-human` pin below
15
+ // is an ADDITION, made under the ticket's own acceptance criterion that "the
16
+ // other four rows are checked for the same drift while the file is open". That
17
+ // check found the same narrowing in `ready-for-human` and nothing to correct in
18
+ // the other three. Its vector is not the re-sync above — the tracker's own
19
+ // `ready-for-human` description does not narrow to implementation — so what is
20
+ // pinned there is the narrowing itself.
21
+ //
22
+ // CEILING: each test pins one row slice, on three things — the role-to-label-
23
+ // string mapping, that the gloss still turns on whether an AFK agent can take
24
+ // the work, and the absence of the restated criterion. The middle one is what
25
+ // stops the negative passing on an emptied cell; the label-string companion
26
+ // alone does not, because it pins columns the gloss is not in. None of this
27
+ // proves the column carries no OTHER restated criterion — no assertion can. The
28
+ // bound is the file's own stated job at `:3`, which "maps those roles to the
29
+ // actual label strings": a mapping, not a criteria source.
30
+ //
31
+ // Measured as of this commit, on a copy of the tree with `cp` restore after
32
+ // each: seven mutations — the old description re-synced verbatim, the criterion
33
+ // re-added with two words wedged into the adjacency, `ready-for-human` narrowed
34
+ // back to implementation, that same narrowing with the noun gone, the
35
+ // label-string mapping broken, and each gloss cell emptied out entirely — each
36
+ // reddened its own pin and no other. Controls: a benign reword of either pinned
37
+ // cell, an unpinned row's cell rewritten, and the table re-padded to a wider
38
+ // column all stayed green.
39
+ import { test } from "node:test";
40
+ import assert from "node:assert/strict";
41
+ import { readFileSync } from "node:fs";
42
+ import { join } from "node:path";
43
+ import { between, phrase } from "./prose-pin.mjs";
44
+
45
+ const REPO = join(import.meta.dirname, "..", "..");
46
+ const TABLE = readFileSync(join(REPO, "docs", "agents", "triage-labels.md"), "utf8");
47
+
48
+ // One table row per slice. The claim is a single cell, so anything wider lets
49
+ // a neighbouring row satisfy the assertion with the cell rewritten.
50
+ const row = (label) => between(TABLE, `| \`${label}\``, "\n|", `the ${label} row`);
51
+
52
+ test("the ready-for-agent row maps the role and states no filing criterion", () => {
53
+ const r = row("ready-for-agent");
54
+ assert.match(
55
+ r,
56
+ phrase("| `ready-for-agent` | `ready-for-agent` |"),
57
+ "the ready-for-agent row no longer maps the role to its label string — that mapping is what scripts read",
58
+ );
59
+ // The gloss itself, which the mapping companion above does not cover: it pins
60
+ // columns 1 and 2, so emptying column 3 leaves it green and the negative
61
+ // below then passes on nothing at all.
62
+ assert.match(
63
+ r,
64
+ /AFK agent/,
65
+ "the ready-for-agent gloss no longer says who the label routes work to, so the negative below is passing on an empty cell",
66
+ );
67
+ // The stem, not the phrase. A negative pinned to the adjacency is trivially
68
+ // evaded — measured: `/[Ff]ully\s+\w*\s*specified/` stayed green against
69
+ // "Ready for a fully and precisely specified AFK agent", because a one-word
70
+ // gap does not span two. A one-row gloss cell has no innocent use of the stem.
71
+ assert.doesNotMatch(
72
+ r,
73
+ /specifi/i,
74
+ "the ready-for-agent gloss is back to promising a fully specified ticket, which the filing bar in `commands/review-and-fix.md` step 5 contradicts — a confirmed defect files here with its remedy still open",
75
+ );
76
+ });
77
+
78
+ test("the ready-for-human row does not narrow the role to implementation", () => {
79
+ const r = row("ready-for-human");
80
+ assert.match(
81
+ r,
82
+ phrase("| `ready-for-human` | `ready-for-human` |"),
83
+ "the ready-for-human row no longer maps the role to its label string — that mapping is what scripts read",
84
+ );
85
+ assert.match(
86
+ r,
87
+ /AFK agent/,
88
+ "the ready-for-human gloss no longer says who the label routes work to, so the negative below is passing on an empty cell",
89
+ );
90
+ // Stem again: "Requires a human to implement" carries the same narrowing
91
+ // with the noun gone.
92
+ assert.doesNotMatch(
93
+ r,
94
+ /implement/i,
95
+ "the ready-for-human gloss is back to requiring human implementation — `skills/run-team/SKILL.md` also routes work needing a human BEFORE implementation here",
96
+ );
97
+ });
@@ -0,0 +1,142 @@
1
+ // Regression gate for #347, and the ticket's own recorded enumeration.
2
+ //
3
+ // #92 named the hazard for one call: an unattended `git` network call with no
4
+ // prompt suppression and no bound can sit on a credential or host-key prompt
5
+ // nobody will answer, or on a transport that connects and then goes quiet, and
6
+ // either way it holds a fleet slot until something outside kills it. #346 built
7
+ // the mechanism that closes it. #347 is the observation that inflight.sh's
8
+ // probe 2 was the only call routed through it.
9
+ //
10
+ // The enumeration this file records, so the next reader does not re-derive it —
11
+ // every raw `git` network call in the fleet's shell scripts at the time, from
12
+ // the Brief's own command, `git ls-files '*.sh' | xargs grep -nE 'git
13
+ // (ls-remote|push|fetch|clone)|gh (issue|pr|api)'`:
14
+ //
15
+ // inflight.sh ls-remote --heads origin already bounded (#346)
16
+ // release-ticket.sh ls-remote --heads origin refs/heads/… routed here
17
+ // prove-merge.sh fetch --quiet origin routed here
18
+ // reap.sh fetch --prune --quiet origin routed here
19
+ // verify-sha.sh fetch --quiet origin <branch> routed here
20
+ //
21
+ // DELIBERATELY LEFT, both with their reason:
22
+ //
23
+ // - Every `gh` call (claim-ticket.sh, drop-merged-label.sh, inflight.sh,
24
+ // release-ticket.sh, .github/scripts/apply-ruleset.sh). `gh` bounds
25
+ // itself: measured during the PR #332 review, `gh issue view` against a
26
+ // silent listener failed on its own at 10.0s with `net/http: TLS handshake
27
+ // timeout`. Wrapping it would buy a second bound over the first.
28
+ // - `.github/workflows/ci.yml`'s `git fetch`. Not a `*.sh` and not a fleet
29
+ // member: it runs under `actions/checkout`'s credentials on a runner that
30
+ // is torn down, so there is no fleet slot to hold and no prompt to answer.
31
+ //
32
+ // The sweep below is the durable half. The list above rots; a scan does not,
33
+ // and it is what catches the sibling nobody thought of — the failure mode #347
34
+ // exists to report, where a fix landed on the one call a ticket named and every
35
+ // call beside it stayed broken.
36
+ //
37
+ // Zero deps: `node --test plugin/scripts/unattended-git-sweep.test.mjs`.
38
+
39
+ import { test } from "node:test";
40
+ import assert from "node:assert/strict";
41
+ import { readFileSync } from "node:fs";
42
+ import { join } from "node:path";
43
+ import { fileURLToPath } from "node:url";
44
+ import { repoRoot, skipWithoutRepo, trackedShellScripts } from "./repo-root.mjs";
45
+
46
+ // This file needs an ambient git WORKING TREE, not just the sources: it asks git
47
+ // what ships rather than walking the directory, so both calls below want a
48
+ // `.git` at or above them. A checkout and a worktree both have one; a `git
49
+ // archive` extraction does not, and this file's tests DECLINE there with a
50
+ // reason instead of running — the tree they would police is not reachable from
51
+ // an extraction. That is the extraction missing a repo, not a defect in the tree
52
+ // under it, and a review or CI step that unpacks an archive should run this one
53
+ // against a checkout. Until #1149 the same condition threw at module load and
54
+ // node could only report it as one synthetic failing test at line 1.
55
+ const ROOT = repoRoot(fileURLToPath(new URL(".", import.meta.url)));
56
+ const SKIP_WITHOUT_REPO = skipWithoutRepo(ROOT, "this sweep over what ships");
57
+
58
+ // Tracked `*.sh` only, and from git rather than a directory walk: an untracked
59
+ // scratch script is not what ships, and a fleet script that moves out of this
60
+ // directory must not fall out of the sweep with it.
61
+ //
62
+ // Empty ONLY because the root lookup could not answer, in which case both tests
63
+ // are skipped. A root that answers and lists nothing is a different condition —
64
+ // the wrong repository, or a broken glob — and it must reach the non-vacuity
65
+ // test below and fail there.
66
+ const SHELL_SCRIPTS = ROOT === null ? [] : trackedShellScripts(ROOT);
67
+
68
+ // Whole-line `#` comments only, blanked rather than deleted so line numbers
69
+ // survive for the diagnostic. A trailing `code # note` keeps its comment, and
70
+ // a `#` inside a string is left alone — blanking either would delete real code,
71
+ // and neither can hide a command from this scan, which is what it is for.
72
+ const stripHashComments = (source) =>
73
+ source.split("\n").map((l) => (/^\s*#/.test(l) ? "" : l)).join("\n");
74
+
75
+ // The verbs that reach the network. `pull` and `clone` appear in no fleet
76
+ // script today and are swept anyway: the point of a sweep is the call that has
77
+ // not been written yet.
78
+ const RAW_NETWORK_GIT = /\bgit\s+(?:-[^\s]+\s+|-c\s+\S+\s+|-C\s+\S+\s+)*(ls-remote|fetch|push|clone|pull)\b/g;
79
+
80
+ // A `git fetch` inside a QUOTED STRING is not a call, and both of the fleet's
81
+ // conventions put one there: the trace line every script prints before it acts
82
+ // (`echo "\$ git fetch …" >&2`), and the refusal every script prints when the
83
+ // call fails (`die "git fetch did not finish within …"`). Measured — without
84
+ // this, the sweep reports seven offenders across four scripts on a tree where
85
+ // every one of those calls is routed, which is worse than a useless assertion:
86
+ // the obvious way to quiet it is to delete it.
87
+ //
88
+ // Odd quote count before the match means it opened a string and did not close
89
+ // it. Backslash escapes are dropped first so `\"` inside one does not read as a
90
+ // closing quote. Known ceiling: a heredoc body, and a string that opens on one
91
+ // line and closes on another, are judged per line — no fleet script writes a
92
+ // git call in either, and the failure direction is a false OFFENDER, which is
93
+ // read and dismissed, never a call let through.
94
+ const insideString = (prefix) => {
95
+ const bare = prefix.replace(/\\./g, "");
96
+ return (bare.split('"').length - 1) % 2 === 1 || (bare.split("'").length - 1) % 2 === 1;
97
+ };
98
+
99
+ // A guard on the guard, and the half the skip above leans on: a bad glob, a
100
+ // moved directory or a `git ls-files` that answers nothing turns every
101
+ // assertion below into a vacuous pass over an empty list — green, and blind.
102
+ // The skip is allowed to make that list empty for ONE reason (no working tree);
103
+ // every other reason has to land here as a failure. Named scripts, because
104
+ // those are the ones this file exists to police.
105
+ test("the sweep sees the scripts it is supposed to police", { skip: SKIP_WITHOUT_REPO }, () => {
106
+ for (const s of ["inflight.sh", "release-ticket.sh", "prove-merge.sh", "reap.sh", "verify-sha.sh"]) {
107
+ assert.ok(
108
+ SHELL_SCRIPTS.some((f) => f.endsWith(`/${s}`)),
109
+ `${s} is not in the tracked-script list — the glob or the root above is broken, not the script`,
110
+ );
111
+ }
112
+ });
113
+
114
+ test("no fleet shell script makes a raw git network call — they all route through net.sh (#347)", { skip: SKIP_WITHOUT_REPO }, () => {
115
+ const offenders = [];
116
+ for (const f of SHELL_SCRIPTS) {
117
+ const code = stripHashComments(readFileSync(join(ROOT, f), "utf8"));
118
+ for (const line of code.split("\n")) {
119
+ for (const m of line.matchAll(RAW_NETWORK_GIT)) {
120
+ if (insideString(line.slice(0, m.index))) continue;
121
+ offenders.push(`${f}: ${m[0].trim()} in ${line.trim()}`);
122
+ }
123
+ }
124
+ }
125
+
126
+ assert.deepEqual(offenders, [],
127
+ "an unattended `git` network call is running raw. It can prompt for a credential or a host key with nobody there to answer, or stall on a transport that connects and goes quiet, and either holds a fleet slot indefinitely (#92). Route it through net.sh's `net_git` — which takes the subcommand as arguments, so its own dispatch carries no verb and this sweep does not see it — rather than copying transport flags to the call site, which does not bound the connect phase in any case since git exposes no knob for it (#346, #347).");
128
+ });
129
+
130
+ // The other direction. The sweep above is an absence, and an absence is also
131
+ // what a tree with the calls DELETED would show — so on its own it cannot tell
132
+ // "routed" from "gone". These are the five call sites the enumeration names;
133
+ // each must still source the lib and still reach it.
134
+ test("every script that made one of those calls still sources net.sh and reaches net_git (#347)", { skip: SKIP_WITHOUT_REPO }, () => {
135
+ for (const f of ["inflight.sh", "release-ticket.sh", "prove-merge.sh", "reap.sh", "verify-sha.sh"]) {
136
+ const code = stripHashComments(readFileSync(join(ROOT, "plugin", "scripts", f), "utf8"));
137
+ assert.match(code, /\.\s+"\$net_lib"/,
138
+ `${f} no longer sources net.sh, so whatever network call it makes is unbounded again`);
139
+ assert.match(code, /\bnet_git\s+"/,
140
+ `${f} sources net.sh but calls nothing in it — the sweep above would stay green on a call that was deleted rather than routed`);
141
+ }
142
+ });
@@ -0,0 +1,269 @@
1
+ // #558. The "Verify every reported SHA" guard is the ONLY consuming-side rule
2
+ // for `verify-sha.sh`, and it named exactly one outcome — "Not reachable →
3
+ // flag" — so a controller following it literally had no instruction for exit 2,
4
+ // "the question could not be answered". In `sh`, both `cmd || handle` and
5
+ // `if cmd; then` treat 1 and 2 alike, so the natural reading files an
6
+ // unanswerable probe under "not reachable" by accident rather than by rule.
7
+ //
8
+ // That accident is fail-safe TODAY only because exit 2 emits no JSON at all: a
9
+ // controller cannot read `reachable:true` off it. It is not fail-safe in the
10
+ // other direction — an unanswerable probe recorded as a real "not reachable"
11
+ // verdict flags a member for a stray commit that was never demonstrated, and
12
+ // holds its ticket out of the pool "until the maintainer rules" over a failure
13
+ // that a re-run would have cleared.
14
+ //
15
+ // The pins below are the rules the corrected guard has to carry, each checked
16
+ // against `verify-sha.sh` itself before being written down:
17
+ //
18
+ // 1. the three exit codes are named where the command is named, the inline
19
+ // convention `next-ticket/SKILL.md` already uses for `inflight.sh`;
20
+ // 2. exit 1 KEEPS its verdict — the flag, the withheld enqueue and the
21
+ // maintainer's ruling still hang off "not reachable", and exit 2 is not
22
+ // allowed to drift into that gap. This is the pin against the fix
23
+ // overshooting: a guard that teaches "non-zero is unanswerable" destroys
24
+ // the one distinction the script exists to make;
25
+ // 3. exit 2 gets its own remedy — read stderr, re-run, escalate on repeat —
26
+ // and exit 1's remedy is not allowed to drift into THAT gap;
27
+ // 4. the exit-2 branch is stated as a PROPERTY of the exit code, not as a
28
+ // list of causes. Every `die()` in the script produces the identical
29
+ // caller-visible shape (no stdout, cause on stderr), so a cause list adds
30
+ // nothing a controller can act on differently — and it rots on the next
31
+ // commit that adds or removes one. Test 4 forbids the tally outright.
32
+ //
33
+ // Rule 4 is why this file pins no number. `verify-sha.sh`'s exit-2 paths have
34
+ // already grown twice — the `merge-base --is-ancestor` guard, then #119's three
35
+ // JSON-escaping guards — and the issue that asked for this fix was filed
36
+ // before the last of those landed: its count was accurate when written, and
37
+ // stale by the time this fix was. A number written here would age the same way.
38
+ //
39
+ // THE CEILING, same as inflight-exit2-prose.test.mjs: these are PRESENCE pins
40
+ // over a bounded slice, plus two adjacency pins. Text spliced INSIDE a pinned
41
+ // phrase reddens them; a whole new sentence appended after one, carving out an
42
+ // exception, does not. A reflow (line wraps, `**bold**` moved) stays green.
43
+ import { test } from "node:test";
44
+ import assert from "node:assert/strict";
45
+ import { readFileSync } from "node:fs";
46
+ import { join } from "node:path";
47
+ import { between, phrase } from "./prose-pin.mjs";
48
+
49
+ const REPO = join(import.meta.dirname, "..");
50
+ const read = (...p) => readFileSync(join(REPO, ...p), "utf8");
51
+ const RUN_TEAM = read("skills", "run-team", "SKILL.md");
52
+ const SCRIPT = read("scripts", "verify-sha.sh");
53
+
54
+ // Bounded at both ends and small: the guard, not the `## Guards` section. A
55
+ // slice wide enough to reach its neighbours is satisfied by their vocabulary.
56
+ const guard = () =>
57
+ between(RUN_TEAM, "**Verify every reported SHA.**", "**Never `--delete-branch`", "run-team/SKILL.md");
58
+
59
+ // Bold moves, and these pins must not care. `**` is allowed at ANY word
60
+ // boundary inside a pinned phrase: markdown emphasis slides around a sentence
61
+ // without changing what the sentence says, so a pin that reds on a moved `**`
62
+ // pins the formatting rather than the rule. One `\*{0,2}` per pin — the first
63
+ // spelling — closed only the seam its own instance happened to use, and every
64
+ // other seam still reddened. Measured: `Exit 2 is **not a verdict**` and `Not
65
+ // reachable **(exit 1)**` are both what an editor emphasising this guard
66
+ // writes, and both were false reds. The tolerance goes INSIDE the gap
67
+ // lookaheads too, or `**Exit** 2` drifts straight through the exclusion the
68
+ // gap exists to enforce — measured green before this was widened.
69
+ const B = String.raw`\*{0,2}`; // an optional bold marker at one seam
70
+ const S = String.raw`\*{0,2}\s+\*{0,2}`; // a word gap that tolerates one
71
+ const EXIT2_VERDICT = String.raw`[Ee]xit${S}2${S}is${S}not${S}a${S}verdict`;
72
+
73
+ // The guard's required annotation, in the form the guard writes it. Shared, so
74
+ // the pin below and the assertion that the annotation survives that pin are
75
+ // provably about the same string rather than two copies that can drift apart.
76
+ const ANNOTATION = "`# 0 reachable, 1 not reachable, 2 unanswerable`";
77
+
78
+ // The tally is the rot. A written count is false the moment a `die()` is added
79
+ // or removed, and this script's set has already changed twice.
80
+ //
81
+ // Scoped to the COUNTED NOUN, not to a bare number near "exit 2": the annotation
82
+ // this same guard carries is `2 unanswerable`, which is the exit code's meaning
83
+ // and must stay. Measured — the first spelling of this pin reddened on the
84
+ // guard's own correct text, and `reachable`/`unanswerable` are what the exit
85
+ // codes MEAN, so neither can ever go in this list.
86
+ //
87
+ // What separates a tally from prose is the NUMBER, not the noun: in a tally the
88
+ // number counts something, and in this guard's correct sentences the number is
89
+ // an exit code with `exit` in front of it. The lookbehind refuses a number the
90
+ // exit token directly precedes, and that is what carries the noun list —
91
+ // measured, the spelling this replaces reddened on `Escalate exit 2 on all
92
+ // paths by pinging the maintainer`, and `ways?` could not be admitted at all
93
+ // because it reddened on `Treat exit 2 the same way in all cases`. Both are
94
+ // prose. Both are green here, and every counted-noun spelling below stays red.
95
+ //
96
+ // The separator inside the lookbehind takes a hyphen as well as a space, or
97
+ // `exit-2` — how this repo writes the branch — reads as a count and reds. It
98
+ // takes `**` on either seam for the reason `S` does: a lookaround cannot see a
99
+ // bold-split token, so `**Exit** 2` would walk straight through it. The
100
+ // optional `code`/`codes` token is in for the reason the hyphen is: `exit code
101
+ // 2` names the same exit code, and measured, without that token `Treat exit
102
+ // code 2 the same way in all cases.` reddened while `Treat exit 2 …` did not.
103
+ // The seam tolerance repeats around it, or `**exit code** 2` walks through the
104
+ // same way `**Exit** 2` would. Case comes from the `i` flag, and `[Ee]` keeps
105
+ // the exclusion working if that flag is ever narrowed — an exclusion that stops
106
+ // firing is a green over the rot itself.
107
+ //
108
+ // The nouns this change adds are here because each was measured missing, not
109
+ // guessed: every one of them let `three unanswerable <noun> here` through green
110
+ // against the spelling this replaces. The nouns already in that spelling stay
111
+ // as they are; the loop that pins every noun carries the per-noun history.
112
+ //
113
+ // THE CEILING: this is still a list, so a counted noun nobody has thought of
114
+ // still passes. The filler window between the number and the noun also stays
115
+ // narrow — `three distinct kinds of ways` overruns it and is green, on this
116
+ // spelling and on the one it replaces. Widening that window is what let a noun
117
+ // reach an exit code in the first place, so it stays as it is.
118
+ //
119
+ // The exclusion is ADJACENCY, so correct prose that puts anything between the
120
+ // exit token and its number still reds: measured, `Treat exit codes 1 and 2 the
121
+ // same way in all cases.` reds here and was green against the spelling this
122
+ // replaces, because `and` sits where the exit token would have to be. No
123
+ // lookbehind reaches that one — it is a false red that admitting `ways?`
124
+ // opened, and this spelling does not close it.
125
+ const TALLY = new RegExp(
126
+ String.raw`(?<![Ee]xit(?:\*{0,2}[-\s]+\*{0,2}codes?)?\*{0,2}[-\s]+\*{0,2})` +
127
+ String.raw`\b(?:two|three|four|five|six|seven|eight|nine|ten|\d+)\s+(?:\w+[-\s]+){0,2}` +
128
+ String.raw`(?:paths?|causes?|cases?|reasons?|branches|conditions?|outcomes?|scenarios?|situations?|types?|ways?|(?:failure\s+)?modes?)\b`,
129
+ "i",
130
+ );
131
+
132
+ test("the guard names the script's exit codes where it names the command", () => {
133
+ assert.match(guard(), phrase(ANNOTATION));
134
+ });
135
+
136
+ test("exit 1 keeps the verdict — the flag, the held enqueue and the maintainer's ruling", () => {
137
+ // ADJACENCY, not three presence pins: each clause on its own survives the
138
+ // subject being swapped to exit 2, which is the overshoot this guards.
139
+ // `[Ee]xit 2` excluded from the gap so the two branches cannot merge into
140
+ // one. The character class is load-bearing, not decoration: a drifting
141
+ // sentence that opens on the code capitalises it, which a bare `exit` misses.
142
+ assert.match(
143
+ guard(),
144
+ new RegExp(
145
+ String.raw`[Nn]ot${S}reachable${B}\s*${B}\(exit${S}1\)${B}\s*${B}→\s*${B}flag` +
146
+ String.raw`(?:(?!${B}[Ee]xit${S}2)[\s\S]){0,200}?until${S}the${S}maintainer${S}rules`,
147
+ ),
148
+ "the not-reachable branch no longer binds exit 1 to flag/hold/maintainer-rules, or exit 2 has drifted into that gap — an unanswerable probe must never spend a maintainer's ruling",
149
+ );
150
+ });
151
+
152
+ test("exit 2 is not a verdict and carries its own remedy", () => {
153
+ assert.match(guard(), new RegExp(EXIT2_VERDICT));
154
+ // Same adjacency shape, mirrored: exit 1's remedy must not drift into the
155
+ // exit-2 gap either. Re-running a genuine "not reachable" hides a stray
156
+ // commit behind a probe that answers the same way every time.
157
+ assert.match(
158
+ guard(),
159
+ new RegExp(EXIT2_VERDICT + String.raw`(?:(?!${B}[Ee]xit${S}1)[\s\S]){0,400}?re-run`),
160
+ "the exit-2 branch no longer tells the controller to re-run, or exit 1 has drifted into its gap",
161
+ );
162
+ assert.match(guard(), phrase("never record it as a stray commit"));
163
+ });
164
+
165
+ test("the exit-2 branch is stated as a property of the code, never as a tally of causes", () => {
166
+ // The property that makes one rule cover every cause: the caller cannot tell
167
+ // them apart, so it must key on the code.
168
+ assert.match(guard(), phrase("no JSON on stdout"));
169
+ assert.match(guard(), phrase("the cause on stderr"));
170
+
171
+ // Whether the PIN works is settled before the guard is judged by it, because
172
+ // an assertion that fails masks every one after it and the messages are not
173
+ // interchangeable. Measured: with the pin's noun list widened to reach the
174
+ // annotation, the guard's own verdict fired first and reported that a count
175
+ // had been written into the guard — false, about text that is correct and
176
+ // required to be there. The honest message existed and never ran.
177
+ //
178
+ // What the pin CATCHES, asserted rather than inferred: every assertion over
179
+ // the guard here is a `doesNotMatch`, and those are green against a regex
180
+ // that matches nothing. Measured — a pin emptied to `/$^/` left this whole
181
+ // file green before these landed, guard verdict included.
182
+ //
183
+ // The spellings are the counted nouns that would express a tally in this
184
+ // guard, each measured to have passed green before it was covered.
185
+ for (const noun of [
186
+ "paths",
187
+ "causes",
188
+ "cases",
189
+ "reasons",
190
+ "branches",
191
+ "failure modes",
192
+ "modes",
193
+ "conditions",
194
+ "outcomes",
195
+ "scenarios",
196
+ "situations",
197
+ "types",
198
+ "ways",
199
+ ]) {
200
+ assert.match(
201
+ `There are three unanswerable ${noun} here.`,
202
+ TALLY,
203
+ `the tally pin stopped reading a count spelled with "${noun}" — that is the rot rule 4 forbids, wearing a word the pin no longer sees`,
204
+ );
205
+ }
206
+ // And what it must REFUSE to catch. Every widening of this pin risks
207
+ // reddening correct text, and correct text here is number-adjacent by
208
+ // construction — the guard names exit codes for a living. In each of these
209
+ // the number is an exit code, not a count, which is the property the pin
210
+ // keys on; the hyphen spelling is in because this repo writes the branch
211
+ // that way and a whitespace-only exclusion reds on it, and the `exit code`
212
+ // spellings are in because the exclusion has to carry across that token and
213
+ // its bold seam — both measured red before it did.
214
+ for (const correct of [
215
+ "Treat exit 2 the same way in all cases.",
216
+ "Escalate exit 2 on all paths by pinging the maintainer.",
217
+ "Escalate exit-2 on all paths by pinging the maintainer.",
218
+ "Treat **Exit** 2 the same way in all cases.",
219
+ "Treat exit code 2 the same way in all cases.",
220
+ "Treat **exit code** 2 the same way in all cases.",
221
+ ]) {
222
+ assert.doesNotMatch(
223
+ correct,
224
+ TALLY,
225
+ `the tally pin reddens on correct prose: "${correct}" states no count — the number in it is an exit code, and a pin that cannot tell those apart fires on edits that are right`,
226
+ );
227
+ }
228
+ // The annotation keeps its own message rather than joining the sentences
229
+ // above: what goes wrong here is a noun list reaching a REQUIRED string, and
230
+ // naming the two words that can never join that list is what sends the reader
231
+ // to the fix instead of to the guard.
232
+ assert.doesNotMatch(
233
+ ANNOTATION,
234
+ TALLY,
235
+ "the tally pin's noun list now reaches the guard's own required annotation — `reachable` and `unanswerable` are what the exit codes MEAN, not a count of causes",
236
+ );
237
+
238
+ // Only now the guard itself, judged by a pin already shown to discriminate.
239
+ assert.doesNotMatch(
240
+ guard(),
241
+ TALLY,
242
+ "a count of exit-2 paths has been written into the guard — state the property instead; the next `die()` added to verify-sha.sh falsifies the number",
243
+ );
244
+ });
245
+
246
+ test("verify-sha.sh still declares the exit codes the guard quotes", () => {
247
+ // Cross-file coupling, otherwise invisible: the guard's annotation is a copy
248
+ // of the script's contract. If the script's codes change, the doc lies and
249
+ // nothing else says so.
250
+ assert.match(SCRIPT, phrase("Exit 0 reachable, 1 not reachable, 2 the question could not be answered"));
251
+ // Every exit-2 path is the same `die`, which is what lets one rule cover all
252
+ // of them. A second exit-2 spelling would need the guard revisited.
253
+ assert.match(SCRIPT, /^die\(\)\s*\{[^}]*exit 2;?\s*\}/m);
254
+ // Comment lines stripped first: this script is two-thirds prose about its own
255
+ // exit codes, and counting the raw substring reds on a comment that merely
256
+ // MENTIONS exit 2 — with a message sending the reader after a code path that
257
+ // does not exist (measured). `\b` also stops `exit 22` from counting. Whole
258
+ // comment lines only, never a trailing `#`: cutting at one would let a `#`
259
+ // inside a quoted string hide a genuine second exit, and a missed exit
260
+ // defeats the assertion, where a comment it still trips is merely loud.
261
+ //
262
+ // No null guard: the `die()` pin above carries this same `exit 2` literal on a
263
+ // line that is not a comment, so reaching here means a match already exists.
264
+ assert.equal(
265
+ SCRIPT.replace(/^\s*#.*$/gm, "").match(/\bexit 2\b/g).length,
266
+ 1,
267
+ "verify-sha.sh grew a second way to exit 2 — the guard's single rule covers every cause only because `die()` is the sole one",
268
+ );
269
+ });
@@ -0,0 +1,117 @@
1
+ #!/bin/sh
2
+ # Is <sha> reachable on origin/<branch>?
3
+ #
4
+ # A member can create a nested worktree and commit there, leaving the SHA it
5
+ # reports on a stray branch while its report reads entirely normally. Enqueueing
6
+ # that PR for review wastes a reviewer on work that is not where it claims.
7
+ #
8
+ # Exit 0 reachable, 1 not reachable, 2 the question could not be answered.
9
+ set -eu
10
+
11
+ NAME=verify-sha
12
+ die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
13
+
14
+ # The escaping helpers (#119). json.sh's header holds the sourcing contract and
15
+ # the measurements behind it. Exit 1 out of THIS script means "the sha is not
16
+ # reachable", the one distinction it exists to make, so a missing library would
17
+ # report a member's PR as sitting somewhere it does not — which is why `[ -r ]`
18
+ # has to fire before the `.` can kill the shell.
19
+ json_lib="$(dirname "$0")/json.sh"
20
+ [ -r "$json_lib" ] || die "cannot read $json_lib — refusing to answer without the JSON escaping helpers"
21
+ # shellcheck source-path=SCRIPTDIR
22
+ # shellcheck source=json.sh
23
+ . "$json_lib" || die "$json_lib failed to load"
24
+
25
+ # The bounded, prompt-suppressed git transport (#92, #346, #347). The fetch
26
+ # below is unattended: with no bound it can prompt for a credential or a host
27
+ # key, or stall on a transport that connects and then goes quiet, and either
28
+ # holds a fleet slot until something outside kills it. net.sh's header holds the
29
+ # reasoning and the measurements. Sourced below json.sh so a lone copy of this
30
+ # script still blames json.sh, the name its missing-library test pins.
31
+ net_lib="$(dirname "$0")/net.sh"
32
+ [ -r "$net_lib" ] || die "cannot read $net_lib — refusing to answer without the bounded git transport"
33
+ # shellcheck source-path=SCRIPTDIR
34
+ # shellcheck source=net.sh
35
+ . "$net_lib" || die "$net_lib failed to load"
36
+
37
+ [ $# -eq 2 ] || die "usage: verify-sha.sh <branch> <sha>"
38
+ branch=$1
39
+ sha=$2
40
+
41
+ # Nothing below silences git. Each of these is silent on its healthy path, so
42
+ # the only stderr it can add is the diagnosis of a failure, and swallowing that
43
+ # leaves the die message asserting a cause the script cannot know. A bad remote
44
+ # URL and a removed remote are both "cannot fetch"; only git can say which.
45
+ #
46
+ # `printf`, not `echo`, on THIS line alone (#484): `$branch` is still raw argv
47
+ # here — `[ $# -eq 2 ]` is the only guard it has passed — so a `\c` in it
48
+ # truncated the trace AND swallowed its newline, welding git's own `fatal:`
49
+ # onto the tail of a line that had already lied about the command being run.
50
+ # The three `$branch` echoes below are a different case and stay: each runs
51
+ # only after git ACCEPTED the ref, and `git check-ref-format --branch` refuses
52
+ # a backslash, so no value reaching them can carry one. Acceptance is what
53
+ # makes a refname safe, never the proposal.
54
+ printf '$ git fetch --quiet origin %s\n' "$branch" >&2
55
+ fetch_budget=$(net_fetch_budget)
56
+ fetch_rc=0
57
+ net_git "" "$fetch_budget" fetch --quiet origin "$branch" || fetch_rc=$?
58
+ if [ "$fetch_rc" -ne 0 ]; then
59
+ # A killed fetch and a refused one are different facts and get different
60
+ # words. Without the split, a transport that stalled reads as "cannot fetch",
61
+ # which names a cause this script never observed.
62
+ if net_stalled "$fetch_rc"; then
63
+ die "git fetch origin/$branch did not finish within ${fetch_budget}s and was killed"
64
+ fi
65
+ die "cannot fetch origin/$branch"
66
+ fi
67
+
68
+ # --verify (#1146): without it, an unresolvable "origin/$branch" falls back to
69
+ # treating the argument as a PATH — if a file or dir of that name sits in the
70
+ # cwd, rev-parse prints it and exits 0, and this guard's `|| die` never fires.
71
+ # Measured: a real ref still wins over a same-named path either way, so
72
+ # --verify costs the healthy case nothing; it only closes the fallback.
73
+ tip=$(git rev-parse --verify "origin/$branch") \
74
+ || die "origin/$branch does not resolve after fetch"
75
+ echo " origin/$branch tip = $tip" >&2
76
+
77
+ # Fail closed on an unknown object: "not reachable" and "never heard of it" are
78
+ # different answers, and only one of them is a finding about the branch. The
79
+ # message stops at what the guard observed: cat-file -e also fails on an object
80
+ # that is present but is not a commit, and on an object store it cannot read.
81
+ git cat-file -e "${sha}^{commit}" \
82
+ || die "cannot resolve $sha to a commit in this repository"
83
+
84
+ # Exit 1 is the answer "no"; anything else is git failing to answer, and the one
85
+ # distinction this script exists to make must never be read off a failure. Keep
86
+ # the status read first in the branch — anything above it overwrites $?. git is
87
+ # silent on a plain "no", so the rule above costs this branch nothing: a real
88
+ # negative still reaches the controller with no git noise attached.
89
+ if git merge-base --is-ancestor "$sha" "origin/$branch"; then
90
+ reachable=true
91
+ rc=0
92
+ echo " $sha IS reachable on origin/$branch" >&2
93
+ else
94
+ [ $? -eq 1 ] || die "git merge-base --is-ancestor failed — cannot tell reachable from unanswerable"
95
+ reachable=false
96
+ rc=1
97
+ echo " $sha is NOT reachable on origin/$branch" >&2
98
+ fi
99
+
100
+ # Two of the three string fields are reachable. git accepts a `"` in a ref
101
+ # (`git check-ref-format --branch 'evil"branch'` exits 0), so pushing a branch
102
+ # is one vector, and raw it emitted an unparseable payload at exit 0 — the worst
103
+ # shape, since the caller gets no signal at all. `$sha` is the other, and not by
104
+ # a later edit: `git cat-file -e "${sha}^{commit}"` resolves any rev expression,
105
+ # a REF NAME included, so `verify-sha.sh main 'evil"tag'` reaches here with a
106
+ # quote in it. Measured — unwrapped it emits `"sha":"evil"tag"`, which
107
+ # JSON.parse rejects, at exit 0. `$tip` is `git rev-parse`, 40 hex characters
108
+ # and nothing else, and is wrapped anyway: it costs nothing and survives a later
109
+ # edit moving where it comes from.
110
+ # Assigned before the printf, never inline in its argument list — a `$()`
111
+ # there sits outside this `|| die`, contributes an empty argument on failure,
112
+ # and printf still exits 0 with a malformed payload.
113
+ branch_j=$(jstr "$branch") && sha_j=$(jstr "$sha") && tip_j=$(jstr "$tip") \
114
+ || die "could not escape the payload fields for origin/$branch"
115
+ printf '{"branch":"%s","sha":"%s","reachable":%s,"tip":"%s"}\n' \
116
+ "$branch_j" "$sha_j" "$reachable" "$tip_j"
117
+ exit "$rc"