@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,414 @@
1
+ #!/usr/bin/env node
2
+ // Is a shortlisted ticket's defect still there? (#238)
3
+ //
4
+ // A backlog ticket is a claim about a tree that has since moved. Nothing
5
+ // reconciles the two, so a ticket fixed as a side effect of an unrelated
6
+ // commit stays open and `ready-for-agent` — the worked case is #199, closed
7
+ // by `b243b4e` while that commit was solving something else, and nobody
8
+ // noticed. Phase 0 then counts it as supply and an implementer can claim it,
9
+ // take the label, build a worktree and burn a slot before finding there is
10
+ // nothing to do.
11
+ //
12
+ // This does the MECHANICAL half of the check and nothing else. Deciding WHICH
13
+ // string settles a ticket needs the ticket read, which phase 0 step 4 already
14
+ // does; this takes that string and answers what the tree says about it, with
15
+ // the evidence a close would have to cite.
16
+ //
17
+ // Exit-code contract — the whole interface for a caller that reads no stderr:
18
+ //
19
+ // 0 live the defect still reproduces → offer the ticket
20
+ // 1 fixed provably fixed, evidence in the → do not offer; close citing
21
+ // payload the named commit
22
+ // 2 unknown the question could not be → offer the ticket, SAYING
23
+ // answered the probe could not check
24
+ //
25
+ // THREE values, deliberately. Two is the defect this file exists to avoid: a
26
+ // probe that could not look answers exactly like a probe that looked and found
27
+ // nothing (measured across four fleet tools in one run), so collapsing
28
+ // `unknown` into either neighbour either drops live supply on a guess or
29
+ // reports a defect as live on a spelling the tree stopped using. Same shape as
30
+ // `inflight.sh`, and the same code for it.
31
+ //
32
+ // Exit 2 is also `arg.mjs`'s `die()` code, which is why every guard below can
33
+ // simply die: a malformed invocation, a git call that failed, a path that
34
+ // cannot be read all land on the verdict that keeps the ticket in the queue.
35
+ // The one code that must never be reached by accident is 1 — see the catch at
36
+ // the foot of this file.
37
+ //
38
+ // What it deliberately does NOT do: run a reproduction. #230's check needed a
39
+ // purpose-built fixture plus a positive and a negative control, and a
40
+ // reproduction run without both misattributes causes rather than merely
41
+ // missing defects. That is the general backlog oracle #238 rules out; this
42
+ // probe informs supply, and a human or a triage pass closes.
43
+
44
+ import { execFileSync } from "node:child_process";
45
+ import { gitEnv } from "./git-env.mjs";
46
+ import { relative, resolve } from "node:path";
47
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
48
+
49
+ const NAME = "staleness";
50
+
51
+ const die = makeDie(NAME);
52
+ const { arg, sweep, stray } = defineFlags(die, {
53
+ flags: { path: "value", gone: "value", present: "value" },
54
+ });
55
+
56
+ // #818: a needle QUOTED OUT OF A TICKET can legitimately start with `--`
57
+ // (#240's is `--label ready-for-agent`), and arg()'s value guard refuses
58
+ // that spelling outright (#61/#169 — see arg.mjs's isFlagLike for why the
59
+ // refusal itself stays). An end-of-options separator opts `--gone`/
60
+ // `--present` into the literal reading: `--gone -- '--value'` is the POSIX
61
+ // convention, explicit at the call site, no second input channel.
62
+ //
63
+ // Given bare, with no `--` immediately after the flag, a flag defers to arg()
64
+ // unchanged — a `--`-prefixed value still dies "needs a value" exactly as
65
+ // before #818; that refusal is what keeps a flag from swallowing the next
66
+ // flag as its own value, and it is not weakened here. The three tokens
67
+ // (flag, separator, value) are spliced out of process.argv once read, so
68
+ // sweep()/stray() below never see the swallowed `--` or a needle shaped like
69
+ // a flag — either would otherwise die on it as unrecognized.
70
+ //
71
+ // ONE left-to-right pass over argv, both names in it together and every
72
+ // separator triple consumed before arg() reads anything. Position decides
73
+ // which flag owns a token, never the order the reads are written in —
74
+ // because the values #818 exists to carry are FLAG-SHAPED, so a
75
+ // separator-quoted needle can spell this script's own flag names, and a
76
+ // scan for one name over the whole argv matches the sibling's already-quoted
77
+ // data. Measured against a `needleArg("gone")`-then-`needleArg("present")`
78
+ // version, with `--path` read ahead of both: `--present -- --gone` died
79
+ // `--gone needs a value` and `--present -- --gone extra` died `--gone and
80
+ // --present are opposite questions`, each naming a flag the caller never
81
+ // typed; `--gone -- --path --path src.mjs` died `--path needs a value`.
82
+ // Every one of those is a needle that IS a flag spelling — the class this
83
+ // feature exists for — and all three answer now.
84
+ function separatedNeedles() {
85
+ const found = {};
86
+ for (let i = 2; i < process.argv.length; ) {
87
+ const name = /^--(gone|present)$/.exec(process.argv[i])?.[1];
88
+ // A repeated `--gone -- x` is left where it sits rather than silently
89
+ // overwriting the first: its stranded `--` is then a token no name
90
+ // owns, and sweep() below refuses it as `unknown flag --` (measured).
91
+ if (!name || found[name] !== undefined || process.argv[i + 1] !== "--") {
92
+ i++;
93
+ continue;
94
+ }
95
+ const value = process.argv[i + 2];
96
+ if (value === undefined || value.trim() === "") die(`--${name} needs a value`);
97
+ found[name] = value;
98
+ process.argv.splice(i, 3);
99
+ }
100
+ return found;
101
+ }
102
+
103
+ const separated = separatedNeedles();
104
+ const path = arg("path");
105
+ const gone = separated.gone ?? arg("gone");
106
+ const present = separated.present ?? arg("present");
107
+ // `--gone`/`--present` are the two shapes a ticket's asked-for change takes,
108
+ // and the caller has to say which — the direction is not inferable from the
109
+ // string. `--gone` is a defect the fix must REMOVE (the wording a ticket
110
+ // quotes as wrong); `--present` is something the fix must ADD (the assertion a
111
+ // pin ticket asks for). Refusing both-or-neither rather than defaulting: a
112
+ // default here would pick a direction on the caller's behalf and then report
113
+ // the opposite verdict with full confidence.
114
+ //
115
+ // Checked against the resolved values, not a raw `--gone`/`--present` token
116
+ // scan: separatedNeedles() above splices a separator-form flag's own token
117
+ // out of process.argv once consumed, so a presence scan would read it as
118
+ // absent — measured, with `--gone -- a --present -- b` answering under
119
+ // `--gone` alone at exit 0 while the caller asked two opposite questions.
120
+ if (gone && present) die("--gone and --present are opposite questions; give one");
121
+ if (!gone && !present) die("give --gone <string> (the fix removes it) or --present <string> (the fix adds it)");
122
+ if (!path) die("--path <path> is required");
123
+
124
+ // Below the value guards, the way candidates.mjs places its parseArgs: where
125
+ // both would refuse, the more specific wording wins, and nothing above here
126
+ // has run a git call.
127
+ //
128
+ // One consequence the caller has to be told about, so run-team/SKILL.md says
129
+ // it too: a needle that starts with `--`, given BARE, never reaches this
130
+ // script's question — `arg()` refuses it as a missing value, at exit 2, which
131
+ // is the verdict that keeps the ticket in the queue. `--gone -- '<value>'`
132
+ // (separatedNeedles() above) is the opt-in past that, one flag at a time.
133
+ sweep();
134
+
135
+ // #463: the sweep above only ever refuses a `--`-prefixed token, so a bare
136
+ // or single-dash stray rode through in silence here too — measured, `--path
137
+ // README.md --present needle JUNKTOKEN` returned a payload byte-identical to
138
+ // the same invocation without it. This script takes no positional of its
139
+ // own, so any leftover token is a stray.
140
+ //
141
+ // The shape that makes it worse here than elsewhere is an unquoted needle:
142
+ // `--present two words` takes `two` and discards `words` (measured), then
143
+ // answers with full confidence about a needle the caller never asked about.
144
+ // This verdict feeds ticket selection, where a wrong `fixed`/`live` retires
145
+ // live supply or claims dead work.
146
+ stray();
147
+
148
+ const mode = gone ? "gone" : "present";
149
+ const needle = gone ?? present;
150
+
151
+ // stdio: git's own stderr is forwarded (execFileSync does that precisely
152
+ // because `stdio` is absent here), so the diagnostics below name the cause and
153
+ // never re-print git's text — the duplication candidates.mjs measured at
154
+ // 7,700 B → 15,454 B applies identically.
155
+ //
156
+ // maxBuffer is set because the default is 1 MB and execFileSync THROWS
157
+ // (ENOBUFS) rather than truncating: a tracked file over that size would land
158
+ // in a catch below and be reported under whatever cause that catch names,
159
+ // with no errno anywhere, since the failure is Node's and git prints nothing.
160
+ // The largest tracked file here is under 200 KB today, so this is headroom
161
+ // rather than a fix for a live case — but the growing one is a metrics TSV
162
+ // that only ever gets appended to.
163
+ //
164
+ // GIT_DIR/GIT_WORK_TREE scrubbed (#1599, gitEnv()): the ONE spawn primitive
165
+ // every git call in this file routes through, so scrubbing it here protects
166
+ // all four call sites at once. Measured: an ambient GIT_WORK_TREE alone makes
167
+ // the `rev-parse --show-toplevel` call below answer with the AMBIENT path
168
+ // outright, silently, at exit 0 — root becomes a directory that is not this
169
+ // repository, and every pathspec resolved against it names the wrong file. An
170
+ // ambient GIT_DIR alone makes every `-C root ...` call below (still `-C` —
171
+ // GIT_DIR outranks it) answer from a DIFFERENT repository's object database:
172
+ // `ls-tree origin/main` on a path this repo genuinely tracks comes back
173
+ // empty, exit 0 — the SAME shape this file's own comment above already
174
+ // measures for a generated, genuinely-untracked file (`.agent-test.sh`), so a
175
+ // tracked ticket-fix file would misreport as untracked and the probe would
176
+ // answer `unknown` for a fix that is really sitting right there. Worse for
177
+ // `log -S`: pointed at a coincidentally-real `origin/main` in the ambient
178
+ // repository, it can name a REAL commit from a repository that has nothing to
179
+ // do with this ticket — a `fixed` verdict citing the wrong commit, silently.
180
+ function git(args) {
181
+ return execFileSync("git", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, env: gitEnv() });
182
+ }
183
+
184
+ function verdict(v, extra) {
185
+ // writeSync, not console.log, for the reason arg.mjs gives for die(): a
186
+ // failed write to stdout is invisible through console.log, so a reader that
187
+ // dies mid-pipe leaves `fixed` still exiting 1 — "close citing the payload's
188
+ // commit and subject" — with no payload anywhere and nothing on stderr.
189
+ // Measured: piped into a process that exits immediately, this exits 2 and
190
+ // says so, where console.log exited 1 silently. A verdict nobody received is
191
+ // a verdict nobody can act on, so a failed write is a could-not-check.
192
+ //
193
+ // NOT PINNED, and deliberately so: the shape that reaches this catch is a
194
+ // reader that closed the pipe before the write, and a test for it has to win
195
+ // a race against the child's own exit — such a pin reports on timing rather
196
+ // than on whether the downgrade works, and a flaky pin on a safety path is
197
+ // worse than none. The measurement above is what stands behind it. Closing
198
+ // it properly needs a seam that makes fd 1 fail on demand, which is the same
199
+ // testability seam #822 turns on.
200
+ //
201
+ // The short-write/EAGAIN loop itself is arg.mjs's writeAll() (#1549). A
202
+ // single writeSync can short-write — return the count it managed and throw
203
+ // nothing at all — and this function used to hand-roll the resume, one of
204
+ // three copies of the same loop held in step by a comment saying so.
205
+ // writeAll answers false once the bytes are lost, to a non-EAGAIN errno or
206
+ // to its own capped EAGAIN retry, so a reader that never drains still
207
+ // reaches the could-not-check downgrade below instead of hanging forever.
208
+ //
209
+ // The try still covers the PAYLOAD's construction and not merely the write:
210
+ // JSON.stringify throws on a circular `extra` or a throwing toJSON, and a
211
+ // verdict that could not be serialised is as much a verdict nobody received
212
+ // as one that could not be written. Both reach the same downgrade, which is
213
+ // why the result is read after the catch rather than die() being spelled
214
+ // out at two sites.
215
+ let ok = false;
216
+ try {
217
+ ok = writeAll(1, `${JSON.stringify({ verdict: v, path, mode, needle, ...extra })}\n`);
218
+ } catch {
219
+ // Serialising the payload threw; ok stays false and the downgrade follows.
220
+ }
221
+ if (!ok) die("the verdict could not be written to stdout — could not check");
222
+ process.exitCode = { live: 0, fixed: 1, unknown: 2 }[v];
223
+ }
224
+
225
+ // "Could not check" is a first-class ANSWER, not a failure: it carries the
226
+ // same four identifying fields as the other two verdicts, and a `why`, so a
227
+ // caller reading only stdout can say "offered, could not check" instead of
228
+ // dropping the row. What varies across all three is the EVIDENCE, and it
229
+ // varies with how far the probe got — measured over every branch below:
230
+ // `bytes` once the file was read, `found` once the search over it ran (an
231
+ // empty file is read and never searched), `commit`/`subject` only on `fixed`,
232
+ // and `error` only where the blob read is the call that failed.
233
+ const unknown = (why, extra = {}) => verdict("unknown", { why, ...extra });
234
+
235
+ function probe() {
236
+ // `--path` is read against the REPO ROOT, never the caller's cwd. git
237
+ // resolves a pathspec relative to wherever the process happens to be, so an
238
+ // unanchored probe run from a subdirectory reports a tracked file as
239
+ // UNTRACKED — a positive claim about the tree, made by the script whose
240
+ // whole job is answering questions about the tree, and false. Same anchoring
241
+ // ci-state.mjs does before it answers anything, and the reason ledger.mjs
242
+ // and release-ticket.sh reach for `git -C`.
243
+ let root;
244
+ try {
245
+ root = git(["rev-parse", "--show-toplevel"]).trim();
246
+ } catch {
247
+ return unknown("`git rev-parse --show-toplevel` failed — with no repository root to read this path against, nothing about it is settled");
248
+ }
249
+ // ls-tree prints root-relative paths, so the equality check below needs the
250
+ // argument in that same spelling: an absolute path, a `./` prefix and a
251
+ // trailing slash all name the same file and must not read as a different
252
+ // one. Without this the probe refuses a single literal file path while
253
+ // telling the caller to give a single literal file path. `|| "."` is the
254
+ // path that names the root itself — an empty pathspec is fatal to git, while
255
+ // "." reaches the one-answer guard below, which is the refusal that case has
256
+ // earned.
257
+ const target = relative(root, resolve(root, path)) || ".";
258
+
259
+ // The tracked/untracked discriminator, and it is the first thing asked about
260
+ // the path, because both failures it separates are silent in the other
261
+ // direction. `git show
262
+ // origin/main:<path>` is FATAL, not empty, on a path this repo does not
263
+ // track — while the file may sit right there in the working checkout — so
264
+ // reading that failure as "the file is gone, the fix landed" closes a live
265
+ // ticket. And a GENERATED artifact is untracked by construction:
266
+ // `.agent-test.sh` was claim-ticket.sh's heredoc output, materialized beside
267
+ // the tracked `agent-test` bootstrap on every run of it until ADR 0015, so
268
+ // what is on disk is whatever the last run produced. Measured 2026-08-22 on
269
+ // `agent-test` itself, which was the generated one before #55 tracked it:
270
+ // `git ls-tree origin/main -- <path>` prints nothing at exit 0 and `git show
271
+ // origin/main:<path>` exits 128, while the file sits right there in the
272
+ // checkout. A probe that resolved it by name would
273
+ // measure an arbitrarily old build and report the answer with full
274
+ // confidence, so this file NEVER reads the working tree and never executes
275
+ // what it finds — `origin/main` or `unknown`, nothing else.
276
+ let listing;
277
+ try {
278
+ listing = git(["-C", root, "ls-tree", "origin/main", "--", target]);
279
+ } catch {
280
+ return unknown("`git ls-tree origin/main` failed — the tree could not be read, so nothing about this path is settled");
281
+ }
282
+ if (listing.trim() === "") {
283
+ return unknown(
284
+ "untracked in origin/main — either generated (claim-time heredoc output, whose on-disk copy is a snapshot, not the current form) or absent. Not tracked is not the same fact as does not exist",
285
+ { tracked: false },
286
+ );
287
+ }
288
+ // One entry, and the entry git printed is the path that was asked for. A
289
+ // pathspec matching several entries, or matching something other than what
290
+ // was typed, is a question with more than one answer — which is not an
291
+ // answer. Without this a `--path 'skills/**/*.mjs'` would be read against
292
+ // whatever git listed first.
293
+ const lines = listing.split("\n").filter((l) => l !== "");
294
+ const entry = lines.length === 1 && /^\d+ \w+ ([0-9a-f]+)\t(.*)$/.exec(lines[0]);
295
+ if (!entry || entry[2] !== target) {
296
+ return unknown("the pathspec did not resolve to exactly this one path in origin/main — give a single literal file path");
297
+ }
298
+
299
+ // The object ls-tree named, read as a file. A directory or a submodule at
300
+ // this path lands here and refuses, which is the answer: a tree read as a
301
+ // file would put a list of FILENAMES in front of the search, and a needle
302
+ // absent from a list of filenames reads as clean. No separate type branch
303
+ // above — it would refuse the same inputs with the same verdict, and a guard
304
+ // whose removal no verdict can detect is a guard nothing pins.
305
+ let content;
306
+ try {
307
+ content = git(["-C", root, "cat-file", "blob", entry[1]]);
308
+ } catch (e) {
309
+ // The cause is NOT asserted here, because this catch cannot tell the
310
+ // causes apart: a directory and a submodule land here, and so does a read
311
+ // this process could not complete — a missing or corrupt object in a
312
+ // partial clone, or a blob past the buffer above. Naming one of them would
313
+ // hand a reader who then checks and finds an ordinary file a dead end, so
314
+ // the error itself is carried instead.
315
+ return unknown("what origin/main holds at this path could not be read as a file — a directory, a submodule, and a read that failed all reach here", { error: e.code ?? e.message });
316
+ }
317
+ // The probe's own positive control for the state check: a search over no
318
+ // bytes finds nothing, and "found nothing" is the answer BOTH verdicts below
319
+ // are read off. An empty tracked file is a probe that could not look.
320
+ if (content === "") return unknown("the file is empty in origin/main — a search over no bytes settles nothing", { bytes: 0 });
321
+
322
+ const found = content.includes(needle);
323
+ const bytes = Buffer.byteLength(content);
324
+
325
+ // The two directions, and which one of them is a verdict on its own.
326
+ //
327
+ // `--present` + found, and `--gone` + not found, both mean the asked-for
328
+ // change is in the tree — but only ONE of them is safe to report off the
329
+ // state alone, and neither is reported off the state alone here, because a
330
+ // wrong `fixed` silently removes real supply from the queue. Both go through
331
+ // the history check below for the commit a close has to cite.
332
+ //
333
+ // The other two are `live`, and `live` is the safe direction: the ticket
334
+ // stays offered. It still carries its bound in `why` — a fix that landed as
335
+ // an EQUIVALENT REWORDING satisfies the ticket while failing a literal
336
+ // string test, measured on #206, whose defect `0dc39ef` had already fixed in
337
+ // wording that appears nowhere in the ticket. So `live` means "this literal
338
+ // string still says the defect is here", never "no fix landed".
339
+ if (mode === "present" && !found) {
340
+ return verdict("live", {
341
+ found: false,
342
+ bytes,
343
+ why: "the asked-for string is absent from the current file — the change has not landed under this spelling. An equivalent rewording would read the same way, so this is a reason to offer the ticket, not a proof nothing landed",
344
+ });
345
+ }
346
+ if (mode === "gone" && found) {
347
+ return verdict("live", {
348
+ found: true,
349
+ bytes,
350
+ why: "the string the ticket quotes as the defect is still in the current file",
351
+ });
352
+ }
353
+
354
+ // The evidence bar, and the positive control in one call. `-S` names the
355
+ // commit that last CHANGED this string's count at this path — the one that
356
+ // removed it in `--gone`, the one that introduced it in `--present`.
357
+ //
358
+ // Empty output here is never `fixed`. In `--gone` it is the whole positive
359
+ // control: the string absent from the current file AND never present at this
360
+ // path in this history means the probe was pointed at the wrong spelling or
361
+ // the wrong file, and reading that as "the fix landed" is how a probe with no
362
+ // control closes a live ticket. In `--present` it is a history that cannot
363
+ // account for a string that is right there — a shallow clone, a graft — and
364
+ // an answer nobody should cite.
365
+ //
366
+ // `origin/main` is the walk's starting point, so the commit it names is
367
+ // reachable from `origin/main` BY CONSTRUCTION and needs no
368
+ // `merge-base --is-ancestor` after the fact. That check belongs to the other
369
+ // shape — a sha quoted in a ticket, which can be a pre-rebase orphan that
370
+ // `git show` resolves happily. Measured on #199, against a path this repo
371
+ // no longer tracks: `git log -S 'decodeArgs' origin/main -- <path>` named
372
+ // `b243b4e`, and `git merge-base --is-ancestor b243b4e origin/main` is true,
373
+ // as it is for every commit this walk can reach.
374
+ //
375
+ // Newest-first with `-n 1`, never `--reverse`: the oldest count-changing
376
+ // commit is the file's last rename whenever the string predates one, and a
377
+ // refactor clears an ancestry gate exactly as well as the real fix.
378
+ // (Measured on #206's old wording, `--reverse` names a move commit and
379
+ // newest-first names the commit that actually did it.)
380
+ let record;
381
+ try {
382
+ record = git(["-C", root, "log", "-S", needle, "-n", "1", "--format=%H%x00%s", "origin/main", "--", target]);
383
+ } catch {
384
+ return unknown("`git log -S` failed — the commit that changed this string could not be located, and a close needs it");
385
+ }
386
+ const [commit, subject] = record.trim().split("\0");
387
+ if (!commit) {
388
+ return unknown(
389
+ mode === "gone"
390
+ ? "the string is absent from the current file AND never changed count at this path on origin/main — the probe could not see anything, which is not the same as the defect being gone"
391
+ : "the string is in the current file but no commit on origin/main accounts for it — this history cannot be cited",
392
+ { found, bytes },
393
+ );
394
+ }
395
+ return verdict("fixed", {
396
+ found,
397
+ bytes,
398
+ commit,
399
+ subject,
400
+ why: "read the subject before citing it — `-S` names the commit that changed this string's count, which is the fix only if that commit's subject is about this",
401
+ });
402
+ }
403
+
404
+ // The one code this file must never reach by accident is 1. Node exits 1 on an
405
+ // uncaught throw, and 1 here means "provably fixed" — so a bug in the probe
406
+ // would silently retire a live ticket, the exact harm #238's evidence
407
+ // criterion exists to prevent. `arg.mjs` records the same inversion from the
408
+ // other side (#299/#328). Nothing above is allowed to escape: every failure is
409
+ // an `unknown`, this one included.
410
+ try {
411
+ probe();
412
+ } catch (e) {
413
+ die(`probe failed: ${e.code ?? e.message} — could not check`);
414
+ }