@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,777 @@
1
+ import { test } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { readFileSync, readdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import { execFileSync } from "node:child_process";
6
+ import { join } from "node:path";
7
+ import { stripComments } from "./strip-comments.mjs";
8
+ import { between, phrase } from "./prose-pin.mjs";
9
+ import { snapshotMissing as snapshotMissingRaw } from "./review-core.mjs";
10
+
11
+ // `snap.path` used to reach every specialist prompt and every verifier prompt
12
+ // unchecked: a well-formed string the schema required, but never confirmed to
13
+ // name a real directory. A silently-failed 'git archive | tar -x' (bad auth,
14
+ // a dead HEAD) leaves 'mkdir -p's directory standing, empty — so every
15
+ // specialist got `No such file or directory` on every read and reasoned from
16
+ // source instead of measuring, on all six dimensions at once (#140).
17
+ //
18
+ // `snapshotMissing` is the fix: a `pathVerified` boolean in the snapshot
19
+ // schema's own `required` array, so the agent cannot silently omit it — read by
20
+ // the CALLER rather than trusted from the agent's narration of the
21
+ // byte-identity 'Verify it' step in the snapshot prompt.
22
+ const REPO = join(import.meta.dirname, "..");
23
+ const SOURCE = readFileSync(join(REPO, "scripts", "review-core.mjs"), "utf8");
24
+
25
+ // Pins run against CODE, not SOURCE: review-core-reads.test.mjs and
26
+ // review-core-testcmd.test.mjs each measured a source-text pin pass vacuously
27
+ // against a field dead under a comment — same stripper, same policy here.
28
+ const CODE = stripComments(SOURCE);
29
+
30
+ // #1129 gave the guard a second parameter: the `${scratch}/pr${pr}/run-` prefix
31
+ // the SCRIPT owns, which is what the reported `runRoot` is checked against. The
32
+ // per-run segment itself is minted by the snapshot agent's shell (`mktemp -d`),
33
+ // never by the caller, because two reviews sharing one scratch root must never
34
+ // mint the same one (#1129) — a JS-side `Date.now()`/`Math.random()` in the
35
+ // controller could not provision a directory on the specialist's own
36
+ // filesystem anyway, so the shell was always the only place this could live.
37
+
38
+ const PREFIX = "/scr/pr7/run-";
39
+ const ROOT = `${PREFIX}ab12cd34`;
40
+ const SNAP = `${ROOT}/snapshot-abc123`;
41
+
42
+ // Every fixture in the tests that PREDATE the run-root check must satisfy that
43
+ // check, or the check silently becomes the thing deciding them and the branch
44
+ // each was written for stops being exercised. So the wrapper supplies a valid
45
+ // `runRoot` and the prefix, and each fixture's `path` sits under it: the field
46
+ // the test is about stays the only thing wrong with the report.
47
+ const snapshotMissing = (snap) => snapshotMissingRaw(snap && { runRoot: ROOT, ...snap }, PREFIX);
48
+
49
+ // The accept case: this is the ONLY shape the review/verify stages may
50
+ // proceed on. A guard's false-positive class (wrongly refusing a healthy
51
+ // snapshot) is not its false-negative class, and nothing above this line
52
+ // exercises the ACCEPT path — every other test in this file feeds it input
53
+ // it must reject.
54
+ test("a fully verified snapshot is not missing", () => {
55
+ const reason = snapshotMissing({ path: SNAP, head: "abc123", pathVerified: true });
56
+ assert.equal(reason, null, "a snapshot with path, head and pathVerified:true must not be refused");
57
+ });
58
+
59
+ // Pre-existing behaviour (#140 must not regress it): no snapshot object at
60
+ // all, or one missing path/head, was already refused before this ticket.
61
+ // #539 splits the single "no tree" message this used to share across all six
62
+ // inputs into three, so the three groups below are asserted separately —
63
+ // otherwise a branch that can't actually tell path-missing from head-missing
64
+ // would still pass a loop that only checks "some string came back".
65
+ //
66
+ // A falsy `snap` is the agent contract failing — it died, or the harness
67
+ // exhausted structured-output retries and `agent()` returned null — not a
68
+ // claim about the tree on disk, which may be perfectly good. The citation is
69
+ // the `required:` comment inside `FINDINGS_SCHEMA` in review-core.mjs, which
70
+ // records that a schema REJECTION is retried and every observed one recovered:
71
+ // exhaustion is the only one of the two that returns null, so naming rejection
72
+ // as the cause would point an operator at a signature successful runs carry.
73
+ test("a falsy snapshot (agent died, or it exhausted its structured-output retries) names the agent contract, not a missing tree", () => {
74
+ for (const dead of [null, undefined, false]) {
75
+ const reason = snapshotMissing(dead);
76
+ assert.equal(typeof reason, "string", `${JSON.stringify(dead)} must yield a reason`);
77
+ assert.match(reason, /died/, "the reason no longer names a dead agent as a cause");
78
+ assert.match(reason, /exhausted/, "the reason no longer names exhausted retries — the only structured-output state that yields a falsy snap");
79
+ assert.doesNotMatch(reason, /rejected/, "the reason names a rejection, which is retried and recovers rather than returning null");
80
+ }
81
+ });
82
+
83
+ // `{}` and `{ head: "abc123" }` are both missing `path`; the original
84
+ // `!snap || !snap.path || !snap.head` chain checks `path` before `head`, so
85
+ // both land on the same branch under the split too — the split preserves that
86
+ // order rather than re-deciding it.
87
+ test("a report missing path is refused, naming path and not head", () => {
88
+ for (const report of [{}, { head: "abc123" }]) {
89
+ const reason = snapshotMissing(report);
90
+ assert.equal(typeof reason, "string", `${JSON.stringify(report)} must yield a reason`);
91
+ assert.match(reason, /`path`/, "the reason no longer names path as the missing field");
92
+ assert.doesNotMatch(reason, /`head`/, "a missing-path report must not mention `head` at all — the pin is what catches this branch returning the head branch's message");
93
+ }
94
+ });
95
+
96
+ // `{ path: SNAP }` is the one input of the six with `path` present —
97
+ // the only one that can reach the `head`-missing branch at all. It is also the
98
+ // one branch of the three that must NOT borrow the "no tree to review" ending:
99
+ // `path` is present and may name a perfectly good directory, so the absent sha
100
+ // is the whole of what is wrong. #539 exists because one message misattributed
101
+ // a handshake failure as a missing tree; this branch is where that would come
102
+ // straight back.
103
+ test("a report missing head (path present) is refused, naming head and not path", () => {
104
+ const reason = snapshotMissing({ path: SNAP });
105
+ assert.equal(typeof reason, "string", "a present path with no head must yield a reason");
106
+ assert.match(reason, /`head`/, "the reason no longer names head as the missing field");
107
+ assert.doesNotMatch(reason, /no tree/, "the head branch claims there is no tree, on the one branch whose path is present and whose tree may be fine");
108
+ assert.doesNotMatch(reason, /`path`/, "a missing-head report must not mention `path` at all — the pin is what catches this branch returning the path branch's message");
109
+ });
110
+
111
+ // #140's actual case: path and head are both present, well-formed strings —
112
+ // exactly what let a garbage path through before this ticket — but the
113
+ // mechanical existence check came back false. The interpolation defect this
114
+ // closes is only reachable through THIS branch, not the no-tree one above.
115
+ test("a present path that failed its existence check is refused, naming the path", () => {
116
+ const reason = snapshotMissing({ path: `${ROOT}/snapshot-empty`, head: "abc123", pathVerified: false });
117
+ assert.equal(typeof reason, "string", "pathVerified:false must yield a reason");
118
+ assert.match(reason, /snapshot-empty/, "the reason must name the unverified path");
119
+ assert.match(reason, /not verified to exist/, "the reason no longer says the path was not verified");
120
+ });
121
+
122
+ // A specialist that skipped the required field entirely is the same fact as
123
+ // one that ran the check and got false — the schema's `required` is what is
124
+ // supposed to prevent this at the tool-call layer, but the pure function must
125
+ // not read silence as success if that layer is ever bypassed.
126
+ test("a snapshot that omitted pathVerified is refused, not assumed true", () => {
127
+ const reason = snapshotMissing({ path: SNAP, head: "abc123" });
128
+ assert.equal(typeof reason, "string", "an absent pathVerified must yield a reason, not pass through as verified");
129
+ });
130
+
131
+ // #1056 Finding 2: a string is not a boolean. `pathVerified` used to be
132
+ // checked with `!snap.pathVerified` — a falsy check — so the STRING "false"
133
+ // (truthy in JS) passed it silently, defeating the exact defect class this
134
+ // field exists to guard against just as surely as an omitted field would.
135
+ // `repoVerified`'s sibling check is `=== true` (snapshot-repo.test.mjs pins
136
+ // it); this mirrors that guard onto `pathVerified`.
137
+ test("a non-boolean truthy pathVerified is refused, not accepted as verified", () => {
138
+ const falseString = snapshotMissing({ path: SNAP, head: "abc123", pathVerified: "false" });
139
+ assert.equal(typeof falseString, "string", 'a `pathVerified` of the STRING "false" must still yield a reason — it is truthy, not the boolean the check requires');
140
+ const trueString = snapshotMissing({ path: SNAP, head: "abc123", pathVerified: "true" });
141
+ assert.equal(typeof trueString, "string", 'a `pathVerified` of the STRING "true" must still yield a reason — a schema bypass or a hand-built fixture can carry the word rather than the value');
142
+ });
143
+
144
+ // #532: the head compare already existed — in `usableDiff`, where a
145
+ // mismatching head cost the review its DIFF and nothing else. The review
146
+ // then ran to completion against a tree that was not the PR, on the fallback
147
+ // read rules, and reported findings about code the PR does not contain. That is
148
+ // the measured case: a carried-over worktree re-created with
149
+ // `git worktree add <path> <branch>`, which checks out a leftover LOCAL branch
150
+ // and never consults the remote, so the tree sat at a pre-rebase commit whose
151
+ // subject line was byte-identical to the PR head's. Neither commit was an
152
+ // ancestor of the other. The refusal is what the comparison was missing.
153
+ test("a tree whose head is not the branch ref's is refused, naming both commits", () => {
154
+ const reason = snapshotMissing({ path: SNAP, head: "cff7330", pathVerified: true, refHead: "9e8ee3d" });
155
+ assert.equal(typeof reason, "string", "a present, mismatching refHead must yield a reason");
156
+ assert.match(reason, /cff7330/, "the reason must name the commit the tree is actually at");
157
+ assert.match(reason, /9e8ee3d/, "the reason must name the branch head it was measured against");
158
+ });
159
+
160
+ // #1513, and the expensive half of the mechanism #1168 fixed for worktree
161
+ // dispatch. This refusal runs BEFORE `usableDiff`, so the operand it reads
162
+ // decides whether the review happens AT ALL: against `prHead` — the PR object's
163
+ // `headRefOid`, which sits on the pre-rebase sha for minutes after a rebase has
164
+ // landed (~2 min in one merge-bot run and ~84s in the next, measured in
165
+ // `run-merge-bot.md`'s step 1) — a snapshot cut from the CORRECT tree inside
166
+ // that window cancelled the whole review, which is strictly worse than the
167
+ // dropped diff the same operand cost `usableDiff`.
168
+ test("a lagging PR object does not cancel the review of a tree that matches the ref", () => {
169
+ const rebased = "62ba798" + "0".repeat(33);
170
+ const stale = "c774756" + "0".repeat(33);
171
+ assert.equal(
172
+ snapshotMissing({ path: SNAP, pathVerified: true, head: rebased, refHead: rebased, prHead: stale }),
173
+ null,
174
+ "the review of a correct tree is refused because GitHub's PR object had not caught up",
175
+ );
176
+ // The other direction, which is #1168's own measured case: a worktree cut
177
+ // from a stale remote-tracking ref leaves the tree AND the PR object on the
178
+ // superseded sha, so a `prHead` compare reads EQUAL and admits it.
179
+ assert.equal(
180
+ typeof snapshotMissing({ path: SNAP, pathVerified: true, head: stale, refHead: rebased, prHead: stale }),
181
+ "string",
182
+ "a tree matching only the lagging PR object is admitted — the false pass #1168 removed",
183
+ );
184
+ });
185
+
186
+ // The ACCEPT half, and the one this guard is most likely to get wrong. An
187
+ // ABSENT `refHead` is not a mismatch: the ref read can still come back empty on
188
+ // its own — an unreachable `origin`, or a read that failed — so turning missing
189
+ // input into a refusal would let a network blip cancel a runnable review. That
190
+ // is the inversion `usableDiff`'s own comment records for the diff, now with a
191
+ // whole review behind it instead of a diff, and the rule `run-team/SKILL.md`'s
192
+ // phase-1 compare states as "an empty read is neither equal nor a mismatch".
193
+ // Absent and mismatching are different cases and stay different.
194
+ //
195
+ // A fork PR is NOT one of the absent cases any more (#1616), and it used to be
196
+ // the whole class this refusal could never fire on: a fork's branch resolves
197
+ // nowhere on `origin`, so the operand was permanently absent and a fork
198
+ // snapshotted at the wrong commit was admitted in silence. The snapshot block
199
+ // falls back to `refs/pull/<number>/head`, which the base repository carries
200
+ // for fork-sourced and same-repo PRs alike, so a fork now reaches this compare
201
+ // carrying its real head. What the fixture below pins is unchanged by that: a
202
+ // snapshot with no ref head AT ALL still proceeds.
203
+ //
204
+ // The EMPTY read reaches the same verdict here whatever the guard does — `""`
205
+ // is a prefix of every sha — so it is pinned where it is actually decidable:
206
+ // the run-log test below, where a falsy `refHead` has to still NAME the skip.
207
+ test("a snapshot with no refHead at all still proceeds", () => {
208
+ assert.equal(
209
+ snapshotMissing({ path: SNAP, head: "abc123", pathVerified: true }),
210
+ null,
211
+ "a missing refHead must not refuse an otherwise good snapshot",
212
+ );
213
+ });
214
+
215
+ // #1129's whole value rests on one invariant: every consumer reads a tree
216
+ // rooted under THIS run's own root. Before these three branches that invariant
217
+ // was carried entirely by prompt prose asking the snapshot agent to copy
218
+ // SNAPSHOT_DEST verbatim and not reconstruct it — and a refuter reverted that
219
+ // paragraph and ran all 18 test files that read review-core.mjs, 276 tests, with
220
+ // nothing turning red. Prose an agent is asked to obey is not an invariant.
221
+ // These are, because the run root prefix is the caller's own string: a
222
+ // reconstructed, stale, or mistranscribed path now costs the run instead of
223
+ // sending six specialists into a tree that belongs to some other review.
224
+ test("a report whose run root is not this run's is refused, naming both roots", () => {
225
+ const reason = snapshotMissingRaw(
226
+ { runRoot: "/scr/pr7/run-OTHER", path: "/scr/pr7/run-OTHER/snapshot-abc123", head: "abc123", pathVerified: true },
227
+ "/scr/pr9/run-",
228
+ );
229
+ assert.equal(typeof reason, "string", "a run root outside the caller's prefix must yield a reason");
230
+ assert.match(reason, /run-OTHER/, "the reason must name the root that was reported");
231
+ assert.match(reason, /\/scr\/pr9\/run-/, "the reason must name the prefix it was measured against");
232
+ });
233
+
234
+ // The mistranscription this is really for: a path that is plausible, present,
235
+ // and under a REAL run root — just not this run's. `pathVerified` cannot catch
236
+ // it, because the tree it names genuinely exists.
237
+ test("a snapshot path outside the reported run root is refused, naming both", () => {
238
+ const reason = snapshotMissing({ path: `${PREFIX}99999999/snapshot-abc123`, head: "abc123", pathVerified: true });
239
+ assert.equal(typeof reason, "string", "a path under a different run's root must yield a reason");
240
+ assert.match(reason, /run-99999999/, "the reason must name the path that was reported");
241
+ assert.match(reason, /ab12cd34/, "the reason must name this run's own root");
242
+ });
243
+
244
+ // A prefix test alone does not settle "under": a `..` segment carries the
245
+ // prefix and resolves outside it. Asserted here rather than left to the prefix
246
+ // check, which passes on every one of these.
247
+ test("a snapshot path that climbs out of the run root with `..` is refused", () => {
248
+ for (const path of [`${ROOT}/snapshot-abc/../../../etc`, `${ROOT}/snapshot-abc/..`]) {
249
+ const reason = snapshotMissing({ path, head: "abc123", pathVerified: true });
250
+ assert.equal(typeof reason, "string", `${path} carries the run root prefix and resolves outside it — it must yield a reason`);
251
+ }
252
+ });
253
+
254
+ // The field cannot be silently omitted at the tool-call layer — the schema's
255
+ // `required` covers that — but the pure function must not read silence as
256
+ // "this run's tree" if that layer is ever bypassed, which is the same rule
257
+ // `pathVerified` above follows.
258
+ test("a report that omitted runRoot is refused, not assumed to be this run's", () => {
259
+ const reason = snapshotMissingRaw({ path: SNAP, head: "abc123", pathVerified: true }, PREFIX);
260
+ assert.equal(typeof reason, "string", "an absent runRoot must yield a reason");
261
+ assert.match(reason, /`runRoot`/, "the reason no longer names runRoot as the missing field");
262
+ });
263
+
264
+ // The normal path, plus the abbreviation tolerance that keeps it normal.
265
+ // `refHead` is 40 chars from `git ls-remote`; `head` is whatever the snapshot
266
+ // for "the HEAD sha", and an agent may abbreviate it. Under a raw `!==` those
267
+ // two matching shas compare unequal — which used to cost a diff and would now
268
+ // cost the entire review, so the prefix tolerance is load-bearing in both
269
+ // directions here in a way it was not before.
270
+ test("a matching head proceeds, abbreviated on either side", () => {
271
+ const full = "a".repeat(40);
272
+ const ok = (snap) => snapshotMissing({ path: SNAP, pathVerified: true, ...snap });
273
+ assert.equal(ok({ head: "abc123", refHead: "abc123" }), null, "an exact match must not be refused");
274
+ assert.equal(ok({ head: full.slice(0, 7), refHead: full }), null, "an abbreviated head is the same commit");
275
+ assert.equal(ok({ head: full, refHead: full.slice(0, 7) }), null, "and the same the other way round");
276
+ // The tolerance must not swallow the case it sits beside: a genuinely
277
+ // different sha still refuses, at short compare length too.
278
+ assert.equal(
279
+ typeof ok({ head: "abc1234", refHead: "abd" + "9".repeat(37) }),
280
+ "string",
281
+ "a different sha stays disqualifying however short the compare",
282
+ );
283
+ });
284
+
285
+ // The refusal above raised the price of an unnormalized `head` from one diff to
286
+ // the whole review: `refHead` is 40 lowercase hex from `git ls-remote`, `head`
287
+ // is whatever an agent relayed for `git rev-parse HEAD`, and that command
288
+ // prints a trailing newline. Measured before the fix: `"9e8ee3d\n"` against a
289
+ // 40-char compare operand beginning `9e8ee3d` refused, naming two shas that
290
+ // look identical.
291
+ //
292
+ // The normalization is a top-level statement rather than a function, so it is
293
+ // lifted as TEXT and RUN. A presence pin would stay green on a normalization
294
+ // that had stopped normalizing, which is the failure this test exists to catch.
295
+ test("a relayed head is normalized before the refusal ever sees it", () => {
296
+ // Anchored on the ASSIGNMENT, not on `.trim()`: anchoring on the operation
297
+ // means a normalization that stops normalizing reads as one that was deleted,
298
+ // and the assertions below never run to say what actually broke.
299
+ const block = CODE.match(/if \(snap\) \{[^}]*snap\.head = [^}]*\}/);
300
+ assert.ok(
301
+ block,
302
+ "no `if (snap) { … snap.head = … }` normalization ahead of snapshotMissing — it was deleted, or reshaped past what this pins",
303
+ );
304
+ assert.ok(
305
+ CODE.indexOf(block[0]) < CODE.indexOf("const missingReason = snapshotMissing(snap, runRootPrefix);"),
306
+ "the normalization runs AFTER the refusal — it can no longer keep a relay artifact from cancelling the review",
307
+ );
308
+ const normalize = new Function("snap", block[0]);
309
+ const full = "deadbee" + "0".repeat(33);
310
+ const after = (head, refHead) => {
311
+ const snap = { path: SNAP, pathVerified: true, head, refHead };
312
+ normalize(snap);
313
+ return snapshotMissing(snap);
314
+ };
315
+ assert.equal(after("deadbee\n", full), null, "a rev-parse newline is a relay artifact, not a different commit");
316
+ assert.equal(after(" deadbee ", full), null, "and neither is surrounding whitespace");
317
+ assert.equal(after("DEADBEE", full), null, "and neither is case");
318
+ // The tolerance must not swallow the case it sits beside, here either.
319
+ assert.equal(typeof after("cff7330", full), "string", "a genuinely different sha still refuses after normalizing");
320
+ // The OPERAND side, which the four rows above cannot reach: `refHead` arrives
321
+ // through the same agent relay as `head`, and the rows above hand it a clean
322
+ // 40-char sha, so every one of them stays green with `refHead`'s own pass
323
+ // deleted. A leading space is what actually costs the review — the prefix
324
+ // tolerance absorbs a TRAILING one on the longer side, so a trailing-newline
325
+ // row would be green either way and pin nothing.
326
+ assert.equal(
327
+ after("deadbee", ` ${full}`),
328
+ null,
329
+ "a leading space on the ls-remote read cancels the review of a matching tree — `refHead` is not being normalized",
330
+ );
331
+ assert.equal(after("deadbee", full.toUpperCase()), null, "and neither is case, on the operand side either");
332
+ const absent = { path: SNAP, pathVerified: true, head: "deadbee" };
333
+ normalize(absent);
334
+ assert.equal(snapshotMissing(absent), null, "normalizing must not invent a refHead the snapshot agent never sent");
335
+ // `prHead` stopped being an operand in #1513, so no refusal can observe its
336
+ // normalization any more — and the run log below is the only remaining reader
337
+ // of the field, where a relayed newline splits one record into two. Asserting
338
+ // the block's own output is the only place that pass is observable at all; a
339
+ // `prHead` dropped from it leaves this green only by being deleted here too.
340
+ const relayed = { path: SNAP, pathVerified: true, head: "deadbee", prHead: " CAFE123\n" };
341
+ normalize(relayed);
342
+ assert.equal(
343
+ relayed.prHead,
344
+ "cafe123",
345
+ "the PR-object head reaches the run log with the relay's whitespace and case still on it",
346
+ );
347
+ // A dead snapshot agent returns falsy, and `snapshotMissing`'s first guard is
348
+ // what names that. Normalizing must not beat it to the dereference.
349
+ assert.doesNotThrow(() => normalize(null), "a falsy snap must reach snapshotMissing's own guard, not a TypeError here");
350
+ });
351
+
352
+ // `snapshotMissing`'s head compare is guarded on `snap.refHead &&`, so a failed
353
+ // `ls-remote` skips the refusal — deliberately, per the test above — and the
354
+ // run log used to be BYTE-IDENTICAL to a run where the two heads were compared
355
+ // and matched. That is the #532 case with the evidence removed: a wrong-commit
356
+ // review and a verified one read the same afterwards. Measured by running the
357
+ // log statement itself, not by matching its source, so a line that stops
358
+ // distinguishing the two reds here.
359
+ test("the snapshot log line says when the head check was skipped", () => {
360
+ const line = CODE.split("\n").find((l) => l.trim().startsWith("log(`snapshot "));
361
+ assert.ok(line, "the snapshot run-log line is gone — the whole diff decision below it is unobservable without it");
362
+ const say = (snap) => {
363
+ let out;
364
+ new Function("snap", "log", line)(snap, (m) => (out = m));
365
+ return out;
366
+ };
367
+ const skipped = say({ path: SNAP, head: "deadbee" });
368
+ const checked = say({ path: SNAP, head: "deadbee", refHead: "deadbee" + "0".repeat(33) });
369
+ assert.notEqual(skipped, checked, "a skipped head check and a passed one log the same line — the two runs cannot be told apart");
370
+ assert.match(skipped, /SKIPPED/, "the skip must be NAMED, not left to be inferred from a field the line does not print");
371
+ // The EMPTY read, which is where this line's fallback and the compare's own
372
+ // guard have to agree. `ls-remote` exits 0 and prints nothing when no ref
373
+ // matches, and the compare tests TRUTHINESS — so a `??` fallback here printed
374
+ // a blank where the skip belongs, and the run read as one where both heads
375
+ // were compared and matched. The prompt asks the agent to omit the field
376
+ // instead of reporting `""`, but prose is not the enforcement.
377
+ assert.match(
378
+ say({ path: SNAP, head: "deadbee", refHead: "" }),
379
+ /SKIPPED/,
380
+ "an empty ref read prints as a blank rather than naming the skip — the compare skipped and the log says it ran",
381
+ );
382
+ // #1513 left `prHead` reported but no longer compared. This line records it
383
+ // first; the no-diff diagnostic below repeats it when the diff is rejected,
384
+ // but nothing downstream compares it against the ref to detect the desync
385
+ // itself — the PR-object desync `run-merge-bot.md`'s step 1 hands to a
386
+ // controller. Dropping it from this line loses the fact silently, with the
387
+ // refusal and the skip both still behaving exactly as they do here.
388
+ const desynced = say({
389
+ path: SNAP,
390
+ head: "deadbee",
391
+ refHead: "deadbee" + "0".repeat(33),
392
+ prHead: "c774756" + "0".repeat(33),
393
+ });
394
+ assert.match(
395
+ desynced,
396
+ /c774756/,
397
+ "the PR object's head is not printed — a run where it lagged the ref is indistinguishable from one where it agreed",
398
+ );
399
+ });
400
+
401
+ // Bound at both ends via prose-pin.mjs's between() — an unbounded end lets the
402
+ // specialist and refuter prompts further down satisfy the assertions instead,
403
+ // the defect `review-pr-testcmd.test.mjs`'s "the specialist prompt hands the
404
+ // command over verbatim and rules 'tests 0' a failure" test records having
405
+ // shipped. Same two anchors `review-pr-reads.test.mjs`'s `slice()` and
406
+ // `review-pr-testcmd.test.mjs` already use.
407
+ function snapshotBlock() {
408
+ return between(CODE, "const snap = await agent(", "if (snap) {", "the snapshot agent dispatch");
409
+ }
410
+
411
+ // Every test above runs against the lifted `snapshotMissing`, which decides what
412
+ // to do with `pathVerified` but never produces it. The thing that produces it is
413
+ // two lines of review-core.mjs — a shell probe and the sentence binding the field
414
+ // to that probe's output — and neither was pinned. Delete either and
415
+ // `required: [..., "pathVerified"]` still passes, all four tests above still
416
+ // pass, and the agent has lost the only instruction saying what value to report:
417
+ // `pathVerified` degrades to a boolean it invents, silently reopening #140 under
418
+ // a green suite. That is the exact shape `review-pr-reads.test.mjs`'s "the
419
+ // snapshot agent asks for the diff facts AND declares them in its schema"
420
+ // measured on the diff facts — "deleting this paragraph outright left this file
421
+ // at 12 pass, 0 fail".
422
+ test("the snapshot prompt runs the emptiness probe AND binds pathVerified to its output", () => {
423
+ const snapshot = snapshotBlock();
424
+ assert.match(
425
+ snapshot,
426
+ /\[ -n "\$\(ls -A "\$SNAP"\)" \] && echo SNAPSHOT_NONEMPTY \|\| echo SNAPSHOT_EMPTY/,
427
+ "the emptiness probe is gone — nothing mechanical stands behind pathVerified",
428
+ );
429
+ // These names live inside a template literal, so each backtick is a
430
+ // BACKSLASH-backtick in the source text — `\\?` matches it either way, the
431
+ // idiom review-pr-reads.test.mjs and review-pr-testcmd.test.mjs already use.
432
+ // `\s+` spans the line wraps so a reflow of the same sentence stays green.
433
+ const B = "\\\\?`";
434
+ assert.match(
435
+ snapshot,
436
+ new RegExp(`Report\\s+${B}pathVerified${B}\\s+=\\s+true\\s+ONLY\\s+if\\s+the\\s+'ls -A'\\s+line\\s+printed\\s+SNAPSHOT_NONEMPTY`),
437
+ "pathVerified is no longer bound to the probe's output — the agent may report whatever it likes",
438
+ );
439
+ });
440
+
441
+ // The instruction that makes the round trip work at all, and the one thing in
442
+ // #1129 that nothing held down: `snapshotMissing` REFUSES a reconstructed path,
443
+ // but only this paragraph makes the agent report a correct one in the first
444
+ // place. Delete it and every review still refuses — loudly, and having spent a
445
+ // snapshot agent to get there. Measured on the pre-check version of this
446
+ // paragraph: a refuter reverted it to the pre-#1129 wording and ran all 18 test
447
+ // files that read review-core.mjs, and nothing turned red.
448
+ //
449
+ // So this pins the instruction, and the check pins the outcome. Neither
450
+ // substitutes for the other: prose an agent is asked to obey is not an
451
+ // invariant, and a refusal is not a working review.
452
+ test("the snapshot prompt tells the agent to copy both printed values verbatim, never to reconstruct them", () => {
453
+ const snapshot = snapshotBlock();
454
+ const B = "\\\\?`";
455
+ for (const [re, gone] of [
456
+ [
457
+ new RegExp(`Report\\s+${B}runRoot${B}\\s+=\\s+the\\s+SNAPSHOT_RUN_ROOT\\s+value`),
458
+ "the agent is no longer told to report `runRoot` off the printed SNAPSHOT_RUN_ROOT — the caller's containment check now refuses every run instead of catching a wrong one",
459
+ ],
460
+ [
461
+ new RegExp(`${B}path${B}\\s+=\\s+the\\s+SNAPSHOT_DEST\\s+value`),
462
+ "the agent is no longer told to report `path` off the printed SNAPSHOT_DEST",
463
+ ],
464
+ [
465
+ // phrase(), not a literal: the sentence wraps in the source, so a plain
466
+ // space between "the" and "block" matches nothing and the pin reds on
467
+ // prose that is present and correct.
468
+ phrase("do not reconstruct it, and do not report a path the block did not print"),
469
+ "the prohibition on reconstructing the destination is gone — both values end in components the shell substituted, so an agent invited to guess produces a path that reads plausible and belongs to no run",
470
+ ],
471
+ ]) {
472
+ assert.match(snapshot, re, gone);
473
+ }
474
+ });
475
+
476
+ // The ORDER is the guard, not the probe, and two different reorderings each
477
+ // defeat it. Measured, both:
478
+ // probe AFTER the symlink -> `ls -A` counts the symlink, so a `git archive`
479
+ // that extracted NOTHING still prints SNAPSHOT_NONEMPTY, in every repo that
480
+ // has node_modules (which is every repo the symlink exists for).
481
+ // probe AFTER the `git init` -> the same thing one directory entry later, and
482
+ // in EVERY repo rather than only the ones with node_modules: `.git` alone
483
+ // makes `ls -A` non-empty (#1056).
484
+ // guard MISSING -> the `find` deletes, so an empty `scratch` sends it at
485
+ // '/pr<N>' — the directory this block's own `mkdir -p "${runRootParent}"`
486
+ // creates — so what the guard buys is a NAMED refusal, not containment.
487
+ // prune MISSING -> nothing ever removes a run root and the scratch tree grows
488
+ // without bound (#1083). No probe here can see it: the growth is in SIBLING
489
+ // roots and this run's own snapshot is perfectly good, which is why
490
+ // `snapshot-repo.test.mjs` executes the prune against fixtures instead.
491
+ // prune ABOVE the `mkdir -p` -> on a PR's first review the parent does not
492
+ // exist yet, so `find` fails and a healthy run prints SNAPSHOT_PRUNE_FAILED,
493
+ // training a reader to ignore the marker. That is POSITION, not presence, so
494
+ // this pin is the one that catches it and the executed one cannot.
495
+ // The two probe reorderings end the same way: the agent honestly reports
496
+ // `pathVerified: true`, because that is what it was told to report. Hence a
497
+ // sequence pin, not a presence pin — every one of these lines is in the right
498
+ // place or the guard is decorative. The destination itself needs no wipe to
499
+ // pin any more; #1129 measured what one cost (reviewing prB, the snapshot held
500
+ // prA's file, across two PRs sharing one scratch) and retired it by making the
501
+ // destination per-run instead of re-bounding it.
502
+ //
503
+ // #1129 moved the destination off `${scratch}/snapshot` and onto a per-run root
504
+ // the SHELL mints, so the needles below address `$RUN` and `$SNAP`. The order is
505
+ // the guard: an assignment that moved below its readers would leave them
506
+ // addressing an unset (empty) variable, and one command still spelling the old
507
+ // bare path would be a second destination this pin says nothing about.
508
+ //
509
+ // The needles are REGEXES, and every one that spans a shell word tolerates an
510
+ // optional quote around it. A literal-substring needle pinned one arbitrary
511
+ // quote placement: adding quotes to the `SNAP=` assignment — a no-op on the
512
+ // right-hand side of a bash assignment, and what a shellcheck pass suggests —
513
+ // red this test with a message claiming a #1129 collision regression that had
514
+ // not happened. A pin that reds on correct changes gets weakened by the next
515
+ // reader, so these match the shape that decides behaviour and nothing else.
516
+ test("the snapshot block mints a per-run destination, then extracts, probes, and symlinks — in that order", () => {
517
+ const snapshot = snapshotBlock();
518
+ let prev = -1;
519
+ for (const [needle, gone] of [
520
+ [
521
+ /unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_TEMPLATE_DIR/,
522
+ "the ambient git vars are no longer cleared before this block runs — an inherited GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE/GIT_TEMPLATE_DIR can retarget the SHA capture, the archive, the tree-hash compare, or the init's template silently, and nothing downstream in the block catches it (#1056)",
523
+ ],
524
+ [
525
+ /\[ -n "\$\{scratch\}" \] \|\| \{ echo SNAPSHOT_SCRATCH_UNSET/,
526
+ "the empty-scratch guard is gone — an empty interpolation now creates this run's artefacts at `/` instead of refusing by name",
527
+ ],
528
+ [
529
+ /mkdir -p "?\$\{runRootParent\}"?/,
530
+ "the run root's parent is no longer created — `mktemp -d` has nowhere to mint into and every run dies at the same line",
531
+ ],
532
+ [
533
+ /RUN=\$\(mktemp -d "?\$\{runRootPrefix\}X{3,}"?\)/,
534
+ "the run root is no longer minted by `mktemp -d` under the prefix the caller owns — two reviews sharing one scratch can collide again (#1129)",
535
+ ],
536
+ [
537
+ /echo SNAPSHOT_RUN_ROOT="?\$RUN"?/,
538
+ "the run root is never printed — the agent cannot report a `runRoot` it can no longer read off this prompt, and the caller's containment check has nothing to check",
539
+ ],
540
+ [
541
+ /find "?\$\{runRootParent\}"?[^\n]*-exec rm -rf \{\} \+ \|\| echo SNAPSHOT_PRUNE_FAILED/,
542
+ "the stale-run-root prune is gone or no longer refuses by name — every review leaves a tree nothing removes (#1083), and `snapshot-repo.test.mjs`'s executed prune test is where its behaviour is measured",
543
+ ],
544
+ [
545
+ /SHA=\$\(git -C \$\{worktree\} rev-parse --short HEAD\)/,
546
+ "the archived commit is no longer captured into its own variable — a rev-parse failure goes back to shortening the destination silently",
547
+ ],
548
+ [
549
+ /SNAP="?\$RUN\/snapshot-\$SHA"?/,
550
+ "the destination is no longer this run's root plus the archived commit — it addresses something the run does not own",
551
+ ],
552
+ [
553
+ /echo SNAPSHOT_DEST="?\$SNAP"?/,
554
+ "the destination is never printed — the agent cannot report a path it can no longer read off this prompt",
555
+ ],
556
+ [/mkdir -p "?\$SNAP"?/, "the mkdir is gone — `tar -x` has nowhere to extract to"],
557
+ [/git -C \$\{worktree\} archive HEAD/, "the archive is gone — there is no snapshot to review"],
558
+ [/\[ -n "\$\(ls -A "\$SNAP"\)" \]/, "the emptiness probe is gone — nothing mechanical stands behind pathVerified"],
559
+ [
560
+ /\( cd "\$SNAP" && git init -q/,
561
+ "the snapshot is no longer made a git repository — a bare extraction leaves it unmeasurable, and repo-needing tests silently skip or fail there (#1056)",
562
+ ],
563
+ [
564
+ /git init -q && git add -A -f/,
565
+ "the init no longer force-adds — a file a repo's own .gitignore covers is tracked at HEAD and present in the extraction, so plain `git add` leaves it out and the tree hash cannot match",
566
+ ],
567
+ [
568
+ /commit -q --no-verify/,
569
+ "the snapshot commit is gone — an index alone gives no HEAD, so nothing can compare the snapshot's tree against the reviewed commit's",
570
+ ],
571
+ [
572
+ /SNAPTREE=\$\(git -C "?\$SNAP"? rev-parse 'HEAD\^\{tree\}'/,
573
+ "the snapshot's own tree hash is never read — `repoVerified` has nothing mechanical behind it",
574
+ ],
575
+ [
576
+ /echo SNAPSHOT_TREE_MATCH \|\| echo SNAPSHOT_TREE_MISMATCH/,
577
+ "the tree compare no longer names its two outcomes — a failed init or a snapshot that is not the reviewed tree goes back to being reported as a verified environment",
578
+ ],
579
+ [/ln -s \$\{worktree\}\/node_modules/, "the node_modules symlink is gone — a derived `npm test --` cannot run"],
580
+ ]) {
581
+ const at = snapshot.search(needle);
582
+ assert.notEqual(at, -1, gone);
583
+ assert.ok(
584
+ at > prev,
585
+ `${needle} is out of sequence — the block must mint the run root, derive the destination, then extract, then probe, then symlink`,
586
+ );
587
+ prev = at;
588
+ }
589
+ });
590
+
591
+ // Both failure clauses, pinned where they are decided. Neither 'mktemp' nor
592
+ // 'rev-parse' failing stops the block on its own: each contributes a path
593
+ // component, so an unread failure does not abort, it SHORTENS "$SNAP" to a path
594
+ // another run could also produce — the collision this ticket closes, arriving by
595
+ // a different route. The `|| { echo …; exit 1; }` is what makes each a named
596
+ // refusal instead of an empty string.
597
+ test("the run root and the sha each refuse by name rather than shortening the destination", () => {
598
+ const snapshot = snapshotBlock();
599
+ for (const [needle, gone] of [
600
+ [/mktemp -d [^\n]*\|\| \{ echo SNAPSHOT_RUNROOT_FAILED; exit 1; \}/, "a failed `mktemp -d` no longer refuses by name — `$RUN` goes empty and every path below collapses to its suffix"],
601
+ [/rev-parse --short HEAD\) \|\| \{ echo SNAPSHOT_REVPARSE_FAILED; exit 1; \}/, "a failed `rev-parse` no longer refuses by name — the sha goes empty and the destination stops naming the commit it holds"],
602
+ ]) {
603
+ assert.match(snapshot, needle, gone);
604
+ }
605
+ });
606
+
607
+ // #1129. The destination used to be `scratch` plus a fixed literal, so two runs
608
+ // handed one scratch root resolved to ONE absolute path — and the block wiped
609
+ // its destination before extracting, so the second review deleted the tree the
610
+ // first review's fix-applier was still citing. Nothing failed: the path still
611
+ // existed, still held a plausible checkout of this repo, and answered a read
612
+ // with another PR's code. Observed live, worked around by hand-feeding each
613
+ // review a different scratch root.
614
+ //
615
+ // The per-run segment is minted by the SHELL, so the AC-1 property — two runs
616
+ // never share a root — is a property of `mktemp -d`, not of any expression in
617
+ // review-core.mjs. It is asserted by RUNNING the two lines that mint it, for the
618
+ // reason the executed derivation it replaces gives: a presence pin over
619
+ // `mktemp` would stay green on a block that had stopped varying. Only the lines
620
+ // up to SNAPSHOT_RUN_ROOT are lifted — `mkdir`, `mktemp` and the echo, and the
621
+ // block prints the root ahead of the sha precisely so those three stand alone.
622
+ // So this needs no git at all, which is worth keeping even now that the review
623
+ // snapshot is one: a test that shells out to git in the snapshot depends on the
624
+ // very mechanism under review here (#1056), so a regression in the init would
625
+ // surface as this pin failing on its environment instead of on the block it
626
+ // pins. `snapshot-repo.test.mjs` is where git IS exercised, against fixture
627
+ // repositories it builds itself. What the rest of the block does is pinned by
628
+ // the sequence test.
629
+ function mintScript(scratch) {
630
+ const snapshot = snapshotBlock();
631
+ const from = snapshot.search(/^ *mkdir -p "?\$\{runRootParent\}"?/m);
632
+ const runRootLine = snapshot.search(/^ *echo SNAPSHOT_RUN_ROOT=/m);
633
+ assert.ok(from !== -1, "the snapshot block no longer creates the run root's parent — this test lifts lines that are gone");
634
+ assert.ok(runRootLine > from, "the snapshot block no longer prints SNAPSHOT_RUN_ROOT below the mint — this test lifts lines that are gone");
635
+ const lines = snapshot.slice(from, snapshot.indexOf("\n", runRootLine));
636
+ // Rendered, not string-replaced: the lines carry `${runRootParent}` and
637
+ // `${runRootPrefix}` exactly as review-core.mjs interpolates them, and the two
638
+ // are derived here by the same expressions the script uses — lifted below —
639
+ // so a change to either derivation reaches this test instead of being
640
+ // re-spelled in it.
641
+ const derive = deriveRunRoot();
642
+ const { runRootParent, runRootPrefix } = derive(scratch, 1129);
643
+ return new Function("runRootParent", "runRootPrefix", "return `" + lines + "`")(runRootParent, runRootPrefix);
644
+ }
645
+
646
+ // The prefix is the half the SCRIPT still owns — it is what `snapshotMissing`
647
+ // checks the reported root against — so it is lifted as TEXT and RUN, the idiom
648
+ // the `snap.head` normalization above already uses. The `.match()` is guarded
649
+ // and lives INSIDE the helper, never at module scope, so a reformat that
650
+ // defeats the anchor reds named tests instead of taking the whole file down
651
+ // before any of them registers.
652
+ function deriveRunRoot() {
653
+ const block = CODE.match(/^\s*const runRootParent = .+\n\s*const runRootPrefix = .+$/m);
654
+ assert.ok(
655
+ block,
656
+ "review-core.mjs no longer derives `runRootParent` and `runRootPrefix` as adjacent top-level statements — the run root the caller owns was deleted, or reshaped past what this lifts",
657
+ );
658
+ assert.ok(
659
+ CODE.indexOf(block[0]) < CODE.indexOf("const snap = await agent("),
660
+ "the run root prefix is derived BELOW the snapshot dispatch that interpolates it",
661
+ );
662
+ return new Function("scratch", "pr", `${block[0]}\nreturn { runRootParent, runRootPrefix };`);
663
+ }
664
+
665
+ // AC-1, executed rather than read: two runs differing in nothing at all, both
666
+ // minting into one scratch root. This is the half a per-PR path does NOT fix and
667
+ // the one measured under #140 — one PR reviewed twice used to be one path twice,
668
+ // so a re-review landed on the tree a live consumer of the first review was
669
+ // citing.
670
+ test("two review runs sharing one scratch root never mint the same artefact root", () => {
671
+ const scratch = mkdtempSync(join(tmpdir(), "review-pr-mint-"));
672
+ try {
673
+ const run = () => {
674
+ const out = execFileSync("sh", ["-c", mintScript(scratch)], { encoding: "utf8" });
675
+ const m = out.match(/^SNAPSHOT_RUN_ROOT=(.+)$/m);
676
+ assert.ok(m, `the mint printed no SNAPSHOT_RUN_ROOT line: ${JSON.stringify(out)}`);
677
+ return m[1];
678
+ };
679
+ const roots = Array.from({ length: 8 }, run);
680
+ assert.equal(
681
+ new Set(roots).size,
682
+ roots.length,
683
+ `re-reviewing ONE PR minted a repeated artefact root — ${roots[0]} came back more than once, so a second review of the same PR still overwrites the first's tree`,
684
+ );
685
+ for (const root of roots) {
686
+ assert.ok(statSync(root).isDirectory(), `${root} was reported but never created — a name alone cannot stop two runs meeting, only a directory that exists can`);
687
+ // AC-2's PR half: a path that does not say which PR it holds is one a
688
+ // consumer cannot tell a stale reference from a current one by reading.
689
+ assert.match(root, /\/pr1129\/run-/, "the artefact root no longer names the PR — the roots are distinct but anonymous");
690
+ }
691
+ } finally {
692
+ rmSync(scratch, { recursive: true, force: true });
693
+ }
694
+ });
695
+
696
+ // The ACCEPT case, and the class this change could wrongly BREAK. Everything
697
+ // downstream — the diff redirect, the specialists' own directories, the
698
+ // controller that provisioned the root and expects to find the run's artefacts
699
+ // beneath it — assumes what a run writes lands under the scratch argument it was
700
+ // given. A mint that "fixed" collisions by putting artefacts somewhere unique
701
+ // but OUTSIDE that root would satisfy the assertion above and break every one of
702
+ // those consumers, so the containment is asserted in its own right.
703
+ test("a run's artefact root stays under the scratch root the caller provisioned", () => {
704
+ const derive = deriveRunRoot();
705
+ for (const scratch of ["/scr", "/run/scratch", "/tmp/claude-501/session/scratchpad"]) {
706
+ const { runRootPrefix } = derive(scratch, 1129);
707
+ assert.ok(
708
+ runRootPrefix.startsWith(`${scratch}/`),
709
+ `a run under ${scratch} writes to ${runRootPrefix}, outside the root the caller provisioned — a caller that cleans up or inspects its own scratch root now finds nothing there`,
710
+ );
711
+ // A prefix alone does not settle "under": `/scr/../elsewhere` carries it and
712
+ // resolves outside. Same escape review-pr-refuter-scratch.test.mjs asserts
713
+ // separately of the refuter paths built on this root.
714
+ assert.doesNotMatch(runRootPrefix, /\/\.\.(\/|$)/, `${runRootPrefix} climbs out of the provisioned root with a \`..\` segment`);
715
+ }
716
+ });
717
+
718
+ // AC-6, and the pin that reds on a revert of ANY of the four artefact sites
719
+ // rather than only the snapshot's. `${scratch}` reaching a path directly is the
720
+ // whole defect: the snapshot, the captured diff behind `diffPath`, each
721
+ // specialist's directory and each refuter's were all spelled that way, and
722
+ // fixing one leaves the others colliding. Stated as a property over the source
723
+ // rather than as a list of four expected paths, so an artefact added later is
724
+ // covered without this test being remembered.
725
+ //
726
+ // The derivation itself is the one legitimate occurrence — it is where the
727
+ // caller's root is consumed — so it is excluded by identity, not by counting.
728
+ test("no artefact path is spelled off the bare scratch argument — every one hangs off the per-run root", () => {
729
+ const offending = CODE.split("\n").filter((l) => l.includes("${scratch}/") && !l.includes("const runRootParent ="));
730
+ assert.deepEqual(
731
+ offending,
732
+ [],
733
+ `these lines still build a path from the caller's scratch argument directly, so two reviews in one session share it:\n ${offending.join("\n ")}`,
734
+ );
735
+ // The other direction: an empty list must not be satisfied by the derivation
736
+ // having been deleted along with everything it fed. Bound to the derivation
737
+ // CONSUMING the caller's root, not to its shape — pinning the literal here
738
+ // would red this test on every reshaping the tests above already judge on
739
+ // their own terms, which makes a failure say nothing about which property
740
+ // broke.
741
+ assert.ok(
742
+ CODE.split("\n").some((l) => l.includes("const runRootParent =") && l.includes("${scratch}/")),
743
+ "the run root no longer derives from the caller's scratch argument at all — the empty list above is vacuous",
744
+ );
745
+ });
746
+
747
+ // The function is worthless if nothing calls it, and every test above tests a
748
+ // COPY lifted from the source text: it stays green while the feature
749
+ // disconnects. `review-core-testcmd.test.mjs`'s "runReview actually calls
750
+ // resolveTestCmd once the snapshot is validated" records this exact defect for
751
+ // resolveTestCmd, and `select-dimensions.test.mjs`'s "actually calls
752
+ // resolveDimensions" pin does for the fan-out.
753
+ // Delete the `snapshotMissing(snap)` call and its `throw` in review-core.mjs and
754
+ // #140's refusal is dead code with this whole file green.
755
+ test("runReview actually calls snapshotMissing and throws on its result", () => {
756
+ assert.match(
757
+ CODE,
758
+ /^\s*const missingReason = snapshotMissing\(snap, runRootPrefix\);$/m,
759
+ "the snapshotMissing call site changed — the #140 guard may be disconnected",
760
+ );
761
+ assert.match(
762
+ CODE,
763
+ /^\s*if \(missingReason\) throw new Error\(/m,
764
+ "snapshotMissing's result is computed but never thrown on — the guard decides nothing",
765
+ );
766
+ // Ordering, same guardAt/callAt shape as review-core-testcmd.test.mjs's
767
+ // "runReview actually calls resolveTestCmd once the snapshot is validated":
768
+ // after the schema that produces `pathVerified`, and before the first thing
769
+ // that reads `snap` — `resolveTestCmd`, which would otherwise derive a command
770
+ // for a tree that was never confirmed to exist.
771
+ const schemaAt = CODE.indexOf('required: ["runRoot", "path", "head", "pathVerified", "repoVerified"]');
772
+ const callAt = CODE.indexOf("const missingReason = snapshotMissing(snap, runRootPrefix);");
773
+ const testCmdAt = CODE.indexOf("const testCmd = resolveTestCmd(");
774
+ assert.ok(schemaAt !== -1 && testCmdAt !== -1, "the schema or the resolveTestCmd call moved — update this test");
775
+ assert.ok(schemaAt < callAt, "the guard runs above the schema that produces pathVerified");
776
+ assert.ok(callAt < testCmdAt, "resolveTestCmd reads snap before the guard has cleared it");
777
+ });