rungate 0.7.0 → 0.8.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 (63) hide show
  1. package/hooks/ActionVerificationGate.hook.ts +96 -0
  2. package/hooks/AgentBriefGuard.hook.ts +38 -0
  3. package/hooks/AgentVerdictCapture.hook.ts +87 -0
  4. package/hooks/AutoVerifyGate.hook.ts +79 -0
  5. package/hooks/BashToolGuard.hook.ts +65 -0
  6. package/hooks/BashWriteGuard.hook.ts +60 -0
  7. package/hooks/CommitEnforcement.hook.ts +130 -0
  8. package/hooks/DocHygiene.hook.ts +148 -0
  9. package/hooks/GateEnforcement.hook.ts +58 -0
  10. package/hooks/GateResultProtection.hook.ts +69 -0
  11. package/hooks/HarnessAFKGate.hook.ts +85 -0
  12. package/hooks/HookCurrency.hook.ts +99 -0
  13. package/hooks/IssueCloseGuard.hook.ts +149 -0
  14. package/hooks/MergeGuard.hook.ts +58 -0
  15. package/hooks/PostCompact.hook.ts +60 -0
  16. package/hooks/ProjectStateSync.hook.ts +103 -0
  17. package/hooks/SkillGuard.hook.ts +69 -0
  18. package/hooks/SpecConformityTrigger.hook.ts +43 -0
  19. package/hooks/SpecSCGuard.hook.ts +123 -0
  20. package/hooks/StaleTTLCleanup.hook.ts +141 -0
  21. package/hooks/TaskCompleted.hook.ts +51 -0
  22. package/hooks/TeamInit.hook.ts +85 -0
  23. package/hooks/TestSuiteGuard.hook.ts +70 -0
  24. package/hooks/TestSuiteRelease.hook.ts +85 -0
  25. package/hooks/TopLevelCdGuard.hook.ts +108 -0
  26. package/hooks/VerifyPhaseLock.hook.ts +84 -0
  27. package/hooks/WorkflowStateGuard.hook.ts +40 -0
  28. package/hooks/lib/agent-config.json +9 -0
  29. package/hooks/lib/agentDetection.ts +201 -0
  30. package/hooks/lib/comment-template.ts +86 -0
  31. package/hooks/lib/findWorkflow.ts +101 -0
  32. package/hooks/lib/parseStdin.ts +37 -0
  33. package/hooks/lib/paths.ts +111 -0
  34. package/hooks/lib/utils.ts +338 -0
  35. package/lib/affected-tests.ts +29 -0
  36. package/lib/bash-write-guard.ts +373 -0
  37. package/lib/branch-cleanup.ts +279 -7
  38. package/lib/config-trackable.ts +9 -0
  39. package/lib/distribution-currency.ts +55 -5
  40. package/lib/failure-intake.ts +7 -1
  41. package/lib/gate-enforcement.ts +222 -28
  42. package/lib/gate-names.ts +72 -0
  43. package/lib/gate-result-protection.ts +427 -0
  44. package/lib/intake-sources.ts +380 -0
  45. package/lib/late-env-spawn.ts +331 -0
  46. package/lib/launch-base.ts +128 -5
  47. package/lib/paths.ts +96 -3
  48. package/lib/phase2-decomposition.ts +1 -1
  49. package/lib/published-artifact.ts +162 -18
  50. package/lib/sc-id-cross-tree.ts +84 -8
  51. package/lib/scaffold/ai-review-findings.ts +7 -1
  52. package/lib/scaffold/ai-review-step.ts +861 -116
  53. package/lib/scaffold/defaults.ts +82 -1
  54. package/lib/scaffold/steps.ts +436 -44
  55. package/lib/security-verdict.ts +1 -1
  56. package/lib/shell-path-interpolation.ts +594 -0
  57. package/lib/text-dependents.ts +875 -0
  58. package/lib/workflow-security.ts +29 -0
  59. package/lib/workflow-taint.ts +732 -0
  60. package/lib/worktree-cleanup.ts +65 -38
  61. package/lib/worktree-repo.ts +32 -2
  62. package/package.json +3 -1
  63. package/scripts/check-installed-hook-currency.ts +825 -0
@@ -209,10 +209,9 @@ export const AI_REVIEW_JOB = "ai-review";
209
209
  /**
210
210
  * Whether anything in the generated job READS the findings payload (#675).
211
211
  *
212
- * `false` today, and the one position that says so. The reader exists, is
213
- * tested, and is reachable as `rungate ai-review-findings` since #675's first
214
- * half — but no step in the emitted workflow runs it, so a `critical` finding
215
- * is a green check.
212
+ * `true` since #1013, and the one position that says so. The verdict step's
213
+ * success branch runs `AI_REVIEW_FINDINGS_COMMAND` over the payload and exits
214
+ * on what it returns, so a blocking finding fails the check.
216
215
  *
217
216
  * It is a constant rather than two sentences because two places describe this
218
217
  * state: `buildReviewRunScript`'s warning, which tells an operator mid-run,
@@ -222,16 +221,102 @@ export const AI_REVIEW_JOB = "ai-review";
222
221
  * enforcement over a job that has none. `test/ai-review-outcomes-header.test.ts`
223
222
  * holds them to this.
224
223
  *
225
- * Flip it when the adjudication step lands, and the caveat leaves the header
226
- * in the same commit.
224
+ * It does NOT claim the adjudicator ran on any particular runner. That is a
225
+ * per-run reading, and the step takes it per run — see
226
+ * `AI_REVIEW_OUTCOME_LINE`.
227
227
  */
228
- export const AI_REVIEW_FINDINGS_ADJUDICATED = false;
228
+ export const AI_REVIEW_FINDINGS_ADJUDICATED = true;
229
+
230
+ /**
231
+ * The npm package the generated job fetches the adjudicator from (#1013).
232
+ *
233
+ * The job runs `bunx <package>@<generating version> <command> <payload>` and
234
+ * nothing else. Three routes to running the reader were measured on #1013 and
235
+ * this is the only one that is not a security regression:
236
+ *
237
+ * - `bun install` from the checkout executes the pull request's own dependency
238
+ * graph in a job holding `id-token: write`. `ai-review-restore-untrusted`
239
+ * restores nine paths from the base and `package.json`/`bun.lock` are not
240
+ * among them, and `--ignore-scripts` does not help when the next line runs
241
+ * `node_modules/.bin/rungate`, which that manifest names.
242
+ * - `bun bin/rungate.ts` from the checkout runs the branch's own code in the
243
+ * one job whose design is that the reviewer READS the branch.
244
+ * - `bunx <package>@<version>` reads no consumer manifest, writes no
245
+ * `node_modules` into the workspace, and names its version in the generated
246
+ * file, so it cannot drift without the file changing.
247
+ *
248
+ * The version is the GENERATING version, passed in rather than read here —
249
+ * this module has no relative imports (see `AiReviewActionRefs`). A tree whose
250
+ * version is not yet on the registry emits a command that cannot resolve, and
251
+ * that is the same correct-but-not-yet-resolvable output `harnessDevDepRange`
252
+ * in `lib/scaffold/steps.ts` has emitted since #364. It is not silent: a
253
+ * command that could not run produces no `AI_REVIEW_OUTCOME_LINE`, and the
254
+ * step reports UNMEASURED rather than reading the exit code as a verdict.
255
+ */
256
+ export const AI_REVIEW_ADJUDICATOR_PACKAGE = "rungate";
257
+
258
+ /** The subcommand inside it. Registered in `lib/cli-commands.ts`. */
259
+ export const AI_REVIEW_FINDINGS_COMMAND = "ai-review-findings";
260
+
261
+ /**
262
+ * The line the adjudicator prints BEFORE it decides anything — the proof that
263
+ * it ran at all (#1013).
264
+ *
265
+ * The exit code cannot carry that proof. `AI_REVIEW_REQUIRED_EXIT` is `1`, and
266
+ * so is a `bunx` that could not resolve the package, a `bun` that is not on the
267
+ * runner, and a dispatcher that threw. Reading `1` as "the review refused"
268
+ * makes an UNINSTALLABLE adjudicator indistinguishable from a blocking finding,
269
+ * and the obvious repair for a check that fails on every pull request is to
270
+ * delete it. So the step requires this line in the output before it treats the
271
+ * exit code as a verdict, and reports UNMEASURED when it is absent.
272
+ *
273
+ * Declared here and imported by `./ai-review-findings`, which prints it, so the
274
+ * printer and the bash that greps for it are one string. Two spellings that
275
+ * agree today is #295: the reader asked for a key no writer produced, every run
276
+ * came back empty, and empty read as clean.
277
+ */
278
+ export const AI_REVIEW_OUTCOME_LINE = "ai-review findings outcome:";
229
279
 
230
280
  export const AI_REVIEW_AUTH_STEP_NAME = "Detect AI review credentials";
231
281
 
232
282
  /** The annotation title, shared by the warning and the refusal. */
233
283
  export const AI_REVIEW_UNMEASURED_TITLE = "AI review UNMEASURED";
234
284
 
285
+ /**
286
+ * The title that says a review was READ, carried by the one branch that can
287
+ * only be reached by reading one (#1087).
288
+ *
289
+ * Everything else this step emits is an absence. A green `ai-review` meant
290
+ * "no `AI_REVIEW_UNMEASURED_TITLE` warning came back", and absence is the
291
+ * weakest evidence this file accepts anywhere else — it is the Silent Default
292
+ * Substitution the module header is about, applied to the gate's own result.
293
+ * Three conditions emit that title (the report step, #989's restored-base
294
+ * reading, and whatever is split off next), #1110 showed a state that emits
295
+ * NO annotation at all, and a skipped action emits none either. So the
296
+ * absence has at least four causes and cannot be read backwards into "a
297
+ * review happened".
298
+ *
299
+ * Measured over the 22 `ai-review` runs that completed between #1076 merging
300
+ * at 01:54:48Z and 03:09:36Z on 2026-10-22: **22 green, 9 adjudicated, 8
301
+ * skipped by the action's workflow validation, 5 green with neither** — and
302
+ * telling those apart took a full log download per run plus a regex on the
303
+ * timestamped line, because `gh run view --log` echoes the whole `run:`
304
+ * script and an unfiltered grep finds every branch that did NOT execute. The
305
+ * fleet query in #1087 counted that echo twice before this was noticed.
306
+ *
307
+ * A `::notice` is the cheapest thing that is readable from outside the job:
308
+ * it lands in `check-runs/<id>/annotations` beside the conclusion, which is
309
+ * what a required check's consumers already read. With it, green-plus-this
310
+ * is an adjudicated CLEAN, green-without is a review that did not happen,
311
+ * red-plus-this is a verdict, and red-without is a job that broke before the
312
+ * verdict — four states, no log parsing.
313
+ *
314
+ * Distinct from `AI_REVIEW_UNMEASURED_TITLE` and not a substring of it in
315
+ * either direction, for the reason #1105 gave: a reader that greps titles
316
+ * conflates a title that contains another.
317
+ */
318
+ export const AI_REVIEW_ADJUDICATED_TITLE = "AI review adjudicated";
319
+
235
320
  /** The reporting step's `id:`. Separate from the auth step, so each has one job. */
236
321
  export const AI_REVIEW_RUN_STEP_ID = "ai-review-run";
237
322
 
@@ -730,6 +815,30 @@ export interface AiReviewActionRefs {
730
815
  auth: string;
731
816
  /** `actionRef("anthropics/claude-code-action")`, declared by `lib/claude-code-action.ts`. */
732
817
  review: string;
818
+ /**
819
+ * `actionRef("oven-sh/setup-bun")` from `lib/workflow-actions.ts` (#1013).
820
+ *
821
+ * The adjudicator is `bunx`, and a GitHub-hosted runner has no bun. The
822
+ * step that installs it is the only thing standing between a consumer's
823
+ * first scaffold and an adjudication that silently cannot start.
824
+ */
825
+ setupBun: string;
826
+ /**
827
+ * That step's `with:` body, from `setupBunWith(declaredBunVersion(root))`.
828
+ *
829
+ * Rendered by the caller rather than here, and NOT optional. #622: the bun
830
+ * version had four positions and three spellings, and `lib/bun-version.ts`
831
+ * is now the single declaration every generated `setup-bun` resolves from —
832
+ * `test/bun-version-agreement.test.ts` AC-3 and
833
+ * `test/bun-version-moving-tag.test.ts` count the steps under
834
+ * `.github/workflows` and refuse one that names a version of its own, or
835
+ * none at all. A step emitted here without it is that defect reinstated in
836
+ * the one job that cannot afford a runtime surprise.
837
+ *
838
+ * Indented for the step body as the builder writes it — the whole block is
839
+ * re-indented by `indent` on the way out, like every script above.
840
+ */
841
+ setupBunWith: string;
733
842
  }
734
843
 
735
844
  /**
@@ -940,10 +1049,30 @@ export const AI_REVIEW_FINDINGS_PATH_VAR = "AI_REVIEW_FINDINGS_PATH";
940
1049
  */
941
1050
  export const AI_REVIEW_EXECUTION_FILE_VAR = "AI_REVIEW_EXECUTION_FILE";
942
1051
 
1052
+ /**
1053
+ * The execution file's denial counter, as the report step matches it (#1087).
1054
+ *
1055
+ * One spelling, because the route block greps it three times — for the key's
1056
+ * presence, for a zero, and implicitly for everything else — and three
1057
+ * literals would be three things to get subtly out of step with each other.
1058
+ *
1059
+ * It is the pinned action's own field name, written by the SDK into the file
1060
+ * `setExecutionFileOutputIfPresent` names. Matched as TEXT rather than parsed,
1061
+ * for the reason the turn-budget branch beside it states: a runner is not
1062
+ * guaranteed `jq`, and the cost of a false match here is a different
1063
+ * explanatory sentence, never a different exit code.
1064
+ */
1065
+ export const AI_REVIEW_DENIALS_KEY = "permission_denials_count";
1066
+
943
1067
  export const AI_REVIEW_PREPARE_STEP_ID = "ai-review-prepare";
944
1068
 
945
1069
  export const AI_REVIEW_PREPARE_STEP_NAME = "Choose a findings path outside the checkout";
946
1070
 
1071
+ /** The step that puts `bunx` on the runner, so the verdict can adjudicate (#1013). */
1072
+ export const AI_REVIEW_SETUP_BUN_STEP_ID = "ai-review-setup-bun";
1073
+
1074
+ export const AI_REVIEW_SETUP_BUN_STEP_NAME = "Install bun for the findings adjudicator";
1075
+
947
1076
  /** The basename, nonce aside. One spelling, so the glob and the write agree. */
948
1077
  export const AI_REVIEW_FINDINGS_BASENAME = "ai-review-findings";
949
1078
 
@@ -1719,6 +1848,58 @@ export const AI_REVIEW_RUNTIME_CONFIG_UNMEASURED =
1719
1848
  `This run is UNMEASURED at these paths, which is not the same as a run ` +
1720
1849
  `in which the reviewer did not write to them. Paths`;
1721
1850
 
1851
+ /**
1852
+ * The annotation title the reading above carries, and why it is NOT
1853
+ * `AI_REVIEW_UNMEASURED_TITLE` (#1087).
1854
+ *
1855
+ * ## The measurement that went wrong
1856
+ *
1857
+ * Two steps emitted one title. The report step says `AI review UNMEASURED`
1858
+ * when it cannot say a review happened at all; the drift step said the same
1859
+ * words about a run in which the review DID happen, was adjudicated, and one
1860
+ * named sub-reading — the runtime's own config under `$HOME` — could not be
1861
+ * taken. Those are not the same claim and only one of them is about whether
1862
+ * the pull request was reviewed.
1863
+ *
1864
+ * The consequence was a fleet query, run over this repository's own history:
1865
+ *
1866
+ * ```
1867
+ * gh api repos/<o>/<r>/check-runs/$JID/annotations \
1868
+ * --jq '[.[]|select(.title=="AI review UNMEASURED")]|length'
1869
+ * → of 30 most recent GREEN ai-review runs: real=0 unmeasured=30
1870
+ * ```
1871
+ *
1872
+ * read as "0 of 30 green runs produced a review". Classifying the same runs
1873
+ * by MESSAGE instead of title: 29 of 40 were this reading, and 17 of them had
1874
+ * written a real findings payload. The three newest carried `ai-review
1875
+ * findings outcome: CLEAN` beside the annotation that was being counted as
1876
+ * its absence. The gate was working and the count said it had never run.
1877
+ *
1878
+ * ## Why a title and not a level
1879
+ *
1880
+ * Both readings are `::warning`, both exit 0, and neither should change: the
1881
+ * runtime-config blind spot is real and naming it is #871's whole point.
1882
+ * Nothing here is quieter than it was — the message is unchanged, the
1883
+ * annotation still appears on every run that earns it. What changes is that a
1884
+ * reader counting one title is no longer counting the other.
1885
+ *
1886
+ * ## The boundary, stated, because the next reading has to pick a side
1887
+ *
1888
+ * This title is for "the review happened and a NAMED sub-reading could not be
1889
+ * taken". `AI_REVIEW_UNMEASURED_TITLE` stays on everything that means "this
1890
+ * job cannot say a review happened" — including the drift step's own
1891
+ * no-usable-`$HOME` branch, which is unmeasured about the reviewer rather
1892
+ * than about a path list, and keeps the original title for exactly that
1893
+ * reason.
1894
+ *
1895
+ * It does not contain `AI_REVIEW_UNMEASURED_TITLE` as a substring, so a
1896
+ * reader who greps rather than compares is separated too. That is deliberate
1897
+ * and `test/ai-review-outside-reading.test.ts` asserts it, because a title
1898
+ * that merely extends the other would read as fixed while leaving every
1899
+ * `grep -c` in the same state.
1900
+ */
1901
+ export const AI_REVIEW_RUNTIME_CONFIG_TITLE = "AI review runtime config UNMEASURED";
1902
+
1722
1903
  /**
1723
1904
  * The reviewer's turn budget. One declaring position; see `aiReviewClaudeArgs`.
1724
1905
  *
@@ -2069,7 +2250,7 @@ export function buildOutcomesHeader(
2069
2250
  const unenforced = adjudicated
2070
2251
  ? ""
2071
2252
  : `#\n# NOT YET: the first outcome is not enforced. The findings reader exists\n` +
2072
- `# and is reachable as \`rungate ${"ai-review-findings"}\`, and no step in this job runs\n` +
2253
+ `# and is reachable as \`rungate ${AI_REVIEW_FINDINGS_COMMAND}\`, and no step in this job runs\n` +
2073
2254
  `# it (#675) — so a blocking finding is reported in the comments and the\n` +
2074
2255
  `# check is green. The job says so on every run rather than exiting 0 in\n` +
2075
2256
  `# silence; "reviewed, and nobody read the result" is its own state.\n`;
@@ -2124,6 +2305,14 @@ export function aiReviewScaffoldAction(vertex: VertexCiDecision): string {
2124
2305
  * safe because every variable is read through `${X:-}` — an unset GitHub
2125
2306
  * secret interpolates to the empty string, so absent and empty have to be the
2126
2307
  * same case anyway.
2308
+ *
2309
+ * "No `set -e`" describes what this generator WRITES, not the shell the step
2310
+ * RUNS IN (#1110). GitHub's default for a `run:` step is `/usr/bin/bash -e
2311
+ * {0}`, so `-e` is on in every generated step whether or not the text says
2312
+ * so. A condition is unaffected — `-e` does not fire inside `if`, `&&`, `||`
2313
+ * or `!` — but a standalone statement that may exit non-zero is a shell that
2314
+ * dies there. `buildReviewRunScript`'s adjudication is the one such statement
2315
+ * in this file and it carries the full account.
2127
2316
  */
2128
2317
  export function buildAuthDetectScript(vertex: VertexCiDecision): string {
2129
2318
  // Vertex is a GENERATED LITERAL, not a runtime reading. The provider is
@@ -2517,7 +2706,47 @@ export const AI_REVIEW_APP_INSTALL_CAUSE =
2517
2706
  `${AI_REVIEW_APP_INSTALL_URL} and re-run. This job cannot read that log, ` +
2518
2707
  `so it is naming a likely cause and not reporting a measured one.`;
2519
2708
 
2520
- export function buildReviewRunScript(): string {
2709
+ /**
2710
+ * The step that says which of the states above this run is in.
2711
+ *
2712
+ * ## Reading the log these messages send you to, without being lied to (#1087)
2713
+ *
2714
+ * Several routes here end in "search the step's log for X". Whoever follows
2715
+ * that instruction will reach for:
2716
+ *
2717
+ * ```
2718
+ * gh run view <id> -R <owner>/<repo> --log
2719
+ * ```
2720
+ *
2721
+ * and that output contains **every branch of every `if` in this file**,
2722
+ * whether or not it ran. The runner echoes each step's whole script back
2723
+ * before executing it, one line at a time, each prefixed with a literal
2724
+ * `^[[36;1m` (ESC `[36;1m`, cyan). So an unfiltered `grep` over it reports
2725
+ * code as though it were output: grepping for `mode=none` returns a hit on
2726
+ * every run, because the line is in the script that prints `mode=vertex`.
2727
+ *
2728
+ * Filter the echo before reading anything:
2729
+ *
2730
+ * ```
2731
+ * gh run view <id> -R <o>/<r> --log | perl -ne 'print unless /\Q^[[36;1m\E/'
2732
+ * ```
2733
+ *
2734
+ * Note the `^[` there is two literal characters in the downloaded bytes, not
2735
+ * an escape — `grep -F $'\e[36;1m'` matches nothing against it, which is the
2736
+ * failure that looks like "the filter is not needed".
2737
+ *
2738
+ * This cost two readers of #1087 a wrong conclusion each: one relayed
2739
+ * `mode=none` as a missing credential off an echoed line, and one spent a
2740
+ * pass reading the generated script as though it were the run. It is written
2741
+ * here rather than in a rules file because the people who hit it are the
2742
+ * people these annotations have just sent to the log.
2743
+ */
2744
+ export function buildReviewRunScript(version: string): string {
2745
+ // The exact command the success branch runs. Built here so the comments
2746
+ // below and the bash are one string, and so a test can name it.
2747
+ const adjudicator =
2748
+ `bunx ${AI_REVIEW_ADJUDICATOR_PACKAGE}@${version} ${AI_REVIEW_FINDINGS_COMMAND}`;
2749
+
2521
2750
  // The DECLINED route, and the only one of the five below on which the
2522
2751
  // app-install cause can be true: no execution file means the action never
2523
2752
  // got far enough to write one (#826).
@@ -2541,15 +2770,23 @@ export function buildReviewRunScript(): string {
2541
2770
  // asserted the opposite without stat'ing the path — this branch is reached
2542
2771
  // before the success branch's `-s` test, so nothing had ever looked. The
2543
2772
  // verdict does not soften: an action that did not complete has not produced
2544
- // a review whose payload can be trusted, and nothing reads it anyway (#675).
2773
+ // a review whose payload can be trusted.
2774
+ //
2775
+ // The adjudicator is NOT run here, and that is deliberate (#1013). It
2776
+ // adjudicates a COMPLETED review; a payload left behind by an action that
2777
+ // died is a partial document, and reading it would turn "the review was cut
2778
+ // short" into "the review found nothing" — a half-written findings array is
2779
+ // indistinguishable from a clean one.
2545
2780
  const pendingPayload =
2546
2781
  `The review action (#631) did not complete, and yet a findings payload ` +
2547
2782
  `IS present at the path this job gave the reviewer. So the reviewer ran ` +
2548
2783
  `and wrote a result, and the action failed around it. The payload is NOT ` +
2549
- `adjudicated — nothing in this job reads one (#675) — and a run whose ` +
2550
- `action did not complete is not a run whose review can be trusted to be ` +
2551
- `whole. Read the execution file and the action's own log before treating ` +
2552
- `that file as a verdict. This check is UNMEASURED, not a passing review.`;
2784
+ `adjudicated — the adjudicator reads a review that COMPLETED, and a ` +
2785
+ `partially written findings list is indistinguishable from a clean one — ` +
2786
+ `and a run whose action did not complete is not a run whose review can ` +
2787
+ `be trusted to be whole. Read the execution file and the action's own log ` +
2788
+ `before treating that file as a verdict. This check is UNMEASURED, not a ` +
2789
+ `passing review.`;
2553
2790
 
2554
2791
  // The measured overshoot. `base-action/src/run-claude-sdk.ts` at the pinned
2555
2792
  // SHA writes the execution file at `:222` and only then throws at `:249`
@@ -2602,26 +2839,78 @@ export function buildReviewRunScript(): string {
2602
2839
  `happened.`;
2603
2840
 
2604
2841
  // The third state, and the one most easily mistaken for a pass: the
2605
- // reviewer ran, wrote a payload, and NOTHING IN THIS JOB READS IT. The
2606
- // reader exists and is tested (`lib/scaffold/ai-review-findings.ts`), but
2607
- // wiring it into the job needs a way for a scaffolded consumer — which has
2608
- // no copy of rungate's sources — to execute it, and that is #675.
2842
+ // reviewer ran, wrote a payload, and the ADJUDICATOR could not run over it
2843
+ // (#1013). Not "nobody wired it" — the command is right there in the step —
2844
+ // but "the command this step named produced no reading".
2845
+ //
2846
+ // It is a distinct state from every other UNMEASURED here, and the
2847
+ // discriminator is `${AI_REVIEW_OUTCOME_LINE}` rather than the exit code:
2848
+ // `${AI_REVIEW_REQUIRED_EXIT}` is 1 and so is a `bunx` that could not
2849
+ // resolve the package, so the code alone cannot tell a refusal from a
2850
+ // command that never started.
2609
2851
  //
2610
- // Until then a run carrying a `critical` finding is a green check, so the
2611
- // job says so by name rather than exiting 0 in silence. "Reviewed, found
2612
- // nothing" and "reviewed, and nobody read the result" are different facts
2613
- // and only one of them is a pass.
2852
+ // **IT FAILS, and it does not consult ${AI_REVIEW_REQUIRE_VAR}.** The first
2853
+ // cut of #1013 ran this through that flag like every other unmeasured state
2854
+ // in the file, and that was wrong in a way worth writing down, because the
2855
+ // flag reads as if it covers this.
2856
+ //
2857
+ // What the flag is for is a tree that has NEVER CONFIGURED A CREDENTIAL:
2858
+ // nothing was attempted, nobody promised a review, and
2859
+ // `.claude/rules/config-access.md` argues — correctly — that a first
2860
+ // scaffold should say so rather than go red. That reasoning does not reach
2861
+ // here. Reaching this line means the action completed AND a findings
2862
+ // payload is on disk: a review WAS attempted, the reviewer DID write a
2863
+ // result, and the only thing missing is this job's own reading of it. A
2864
+ // payload nobody adjudicated and a payload adjudicated clean are then
2865
+ // indistinguishable from outside the job — which is a green required check
2866
+ // over an unread `critical`, the exact state #1013 exists to end.
2867
+ //
2868
+ // The cost of failing closed is named rather than waved at: a registry
2869
+ // outage reds every pull request in the repository until it clears. That is
2870
+ // the right direction for a REQUIRED check — "I could not measure" is a
2871
+ // failure, not a pass — and the annotation names the cause precisely so an
2872
+ // operator can tell an outage from their own code. The argument for warning
2873
+ // instead was that a check which is red on every pull request gets deleted;
2874
+ // that argument proves too much, because it is an argument against ever
2875
+ // failing closed.
2614
2876
  const unadjudicated =
2615
- `The AI review completed and wrote a findings payload, but no step in ` +
2616
- `this job reads it yet (#675), so a blocking finding would not fail this ` +
2617
- `check. The review is UNMEASURED as a GATE — the comments are real, the ` +
2618
- `verdict is not enforced.`;
2619
-
2620
- const unadjudicatedRefusal =
2621
- `${AI_REVIEW_REQUIRE_VAR} is '${AI_REVIEW_REQUIRE_VALUE}' and nothing in ` +
2622
- `this job adjudicates the findings payload (#675), so a blocking finding ` +
2623
- `would report green. Failing rather than reporting a passing gate for a ` +
2624
- `verdict nobody read.`;
2877
+ `The AI review completed and wrote a findings payload, and the step that ` +
2878
+ `adjudicates it produced no reading: '${adjudicator}' printed no ` +
2879
+ `'${AI_REVIEW_OUTCOME_LINE}' line, so it did not run. The payload is ` +
2880
+ `therefore UNMEASURED — not clean. Failing rather than reporting a green ` +
2881
+ `check for a review whose findings nobody read; a blocking finding and an ` +
2882
+ `adjudication that never happened look identical from outside this job. ` +
2883
+ `This is NOT the ${AI_REVIEW_REQUIRE_VAR} case: that flag is for a tree ` +
2884
+ `with no credential, where no review was attempted. One was attempted ` +
2885
+ `here and its result is sitting at the findings path unread. The usual ` +
2886
+ `causes are that ${AI_REVIEW_ADJUDICATOR_PACKAGE}@${version} is not on ` +
2887
+ `the registry, that bun is not on this runner, or that the registry was ` +
2888
+ `unreachable — the command's own output is printed above this line.`;
2889
+
2890
+ // #1087. The sentence that travels with the positive reading. It names what
2891
+ // the ABSENCE of this annotation means, because that is the half a reader
2892
+ // gets wrong: on a green run it was being read as "the review was clean".
2893
+ //
2894
+ // Two words this sentence may not spell, both for reasons older than it:
2895
+ //
2896
+ // - the other title's, because `test/ai-review-workflow.test.ts` AC-9a
2897
+ // asserts a clean adjudication's output contains no "UNMEASURED"
2898
+ // anywhere, and prose here that used the term would make an operator's
2899
+ // `grep` on a green run report a state that did not occur;
2900
+ // - the action's skip sentence unhyphenated, because
2901
+ // `test/ai-review-payload-reading.test.ts` AC-6 refuses that phrase
2902
+ // anywhere in this script — the reading must never depend on upstream
2903
+ // log prose, and the check cannot tell a grep from a mention. `skipped`
2904
+ // above hyphenates for the same reason.
2905
+ const adjudicatedEvidence =
2906
+ `read from the findings payload by '${adjudicator}', whose exit code is ` +
2907
+ `this step's. This annotation is the only one this job emits that an ` +
2908
+ `unread payload cannot produce — the branch is entered on the outcome ` +
2909
+ `line and nothing else — so a run carrying this title had a review AND a ` +
2910
+ `verdict on it. Its ABSENCE on a green run is not a clean review: it ` +
2911
+ `means no payload was written, or the action skipped itself on its own ` +
2912
+ `workflow-validation guard, or the step died before the reading — none ` +
2913
+ `of which measured anything.`;
2625
2914
 
2626
2915
  // The FOURTH state, and the reason the third one had to be split (#816):
2627
2916
  // the action exited ZERO having not reviewed anything.
@@ -2684,15 +2973,52 @@ export function buildReviewRunScript(): string {
2684
2973
  // what keeps it from being the second decider the comment above declines to
2685
2974
  // build, and it is asserted in `test/ai-review-route-reading.test.ts`
2686
2975
  // (AC-B5) rather than left as an intention.
2687
- const executed =
2976
+ // #1087. The three sentences below replace ONE that guessed. It read
2977
+ // "a reviewer that ran and wrote nothing is usually one that could not
2978
+ // write to the findings path", and the execution files say otherwise:
2979
+ // every cause-B run sampled on this repository reported
2980
+ // `permission_denials_count: 0` — runs 39707821002 (22 turns), 39708155573
2981
+ // (40), 39707657746 (43), 39707621271 (47) and 39708162846 (51). The guess
2982
+ // cost two readers a dead end before anyone stat'ed the number it was
2983
+ // guessing about, which is this file's own standing complaint about a
2984
+ // default substituted for a reading, made about its own prose.
2985
+ //
2986
+ // So the denial count is READ, by the same text match the turn-budget
2987
+ // branch above uses and for the same reason: a runner is not guaranteed
2988
+ // `jq`, and a false match here costs a different explanatory sentence
2989
+ // rather than a different verdict. Three states and not two — a file that
2990
+ // does not carry the key at all is not a file reporting zero, and calling
2991
+ // it zero would be the substitution this branch exists to stop making.
2992
+ const executedNoDenials =
2688
2993
  `The review action exited successfully WITHOUT writing a findings ` +
2689
2994
  `payload, so no AI review ran on this pull request — and the reviewer ` +
2690
2995
  `DID execute: the action wrote an execution file, so this is NOT the ` +
2691
2996
  `case where it declined before running, and nothing about the workflow ` +
2692
- `file is worth checking. Read that execution file for the turn count ` +
2693
- `and the permission denials; a reviewer that ran and wrote nothing is ` +
2694
- `usually one that could not write to the findings path, which is outside ` +
2695
- `the checkout. This check is UNMEASURED, not a passing review.`;
2997
+ `file is worth checking. Its execution file reports ` +
2998
+ `permission_denials_count 0, so the reviewer was never refused a call: ` +
2999
+ `access to the findings path is NOT the cause and reading it as one is a ` +
3000
+ `dead end (#1087). Read the execution file for the turn count and what ` +
3001
+ `the reviewer spent its turns on instead. This check is UNMEASURED, not ` +
3002
+ `a passing review.`;
3003
+
3004
+ const executedDenied =
3005
+ `The review action exited successfully WITHOUT writing a findings ` +
3006
+ `payload, so no AI review ran on this pull request — and the reviewer ` +
3007
+ `DID execute: the action wrote an execution file, and that file reports ` +
3008
+ `a NON-ZERO permission_denials_count, so the reviewer was refused at ` +
3009
+ `least one call. Read the denials in the execution file: a reviewer ` +
3010
+ `refused its own output file is the one case where the findings path, ` +
3011
+ `which is outside the checkout, is worth checking. This check is ` +
3012
+ `UNMEASURED, not a passing review.`;
3013
+
3014
+ const executedDenialsUnknown =
3015
+ `The review action exited successfully WITHOUT writing a findings ` +
3016
+ `payload, so no AI review ran on this pull request — and the reviewer ` +
3017
+ `DID execute: the action wrote an execution file. That file carries no ` +
3018
+ `permission_denials_count, so whether the reviewer was refused anything ` +
3019
+ `is UNMEASURED too and this job will not guess at it (#1087). Read the ` +
3020
+ `execution file and the action's own log. This check is UNMEASURED, not ` +
3021
+ `a passing review.`;
2696
3022
 
2697
3023
  const exhausted =
2698
3024
  `The review action exited successfully WITHOUT writing a findings ` +
@@ -2848,12 +3174,123 @@ if [ "\${AI_REVIEW_ACTION_OUTCOME:-}" = success ]; then
2848
3174
  # is the honest direction: the prepare step did not run, so nobody can say a
2849
3175
  # review happened.
2850
3176
  if [ -s "\${${AI_REVIEW_FINDINGS_PATH_VAR}:-}" ]; then
2851
- echo "::warning title=${AI_REVIEW_UNMEASURED_TITLE}::${unadjudicated}"
2852
- if [ "\${${AI_REVIEW_REQUIRE_VAR}:-}" = "${AI_REVIEW_REQUIRE_VALUE}" ]; then
2853
- echo "::error title=${AI_REVIEW_UNMEASURED_TITLE}::${unadjudicatedRefusal}" >&2
2854
- exit ${AI_REVIEW_REQUIRED_EXIT}
2855
- fi
2856
- exit 0
3177
+ # #1013. The adjudication, and the ONLY branch in this file whose exit
3178
+ # code comes from something other than this script.
3179
+ #
3180
+ # Resolved inside \`run:\`, never in an \`if:\`. A step skipped by \`if:\`
3181
+ # reports *skipped*, and a skipped required check can be treated as
3182
+ # satisfied — the module header's standing rule, and it applies hardest
3183
+ # here, where the thing being skipped is the verdict.
3184
+ #
3185
+ # Both streams are captured: the reader writes its \`::error\` annotation
3186
+ # to stderr and the outcome line to stdout, and this branch needs to read
3187
+ # the second while still SHOWING the first. The output is re-printed
3188
+ # verbatim rather than through \`escape_annotation\` — the reader escapes
3189
+ # its own annotation payloads (one escaper, in \`ai-review-findings.ts\`),
3190
+ # and escaping it twice turns \`%\` into \`%2525\` and the annotation into
3191
+ # noise.
3192
+ #
3193
+ # RUN FROM THE PAYLOAD'S OWN DIRECTORY, not from the checkout. \`bunx\`
3194
+ # resolves \`bunfig.toml\`, \`.npmrc\`, \`package.json\` and \`node_modules\`
3195
+ # by walking UP from the working directory, and a step's working directory
3196
+ # is \${GITHUB_WORKSPACE} — the tree under review. A branch that adds a
3197
+ # \`bunfig.toml\` naming its own registry, or a \`node_modules/.bin\`
3198
+ # entry, would choose what this credentialed job executes. On THIS
3199
+ # repository the trigger is \`pull_request\`, so a fork gets no secrets and
3200
+ # the attacker would need push access; this file is a GENERATOR, and the
3201
+ # job it writes lands in consumer repositories whose trigger and trust
3202
+ # settings nobody here can see. The consumer is the threat model.
3203
+ #
3204
+ # The payload's directory is the right cwd and needs no new wiring: the
3205
+ # prepare step puts it under \${RUNNER_TEMP} and REFUSES the run if that
3206
+ # is unset, so it is outside the checkout by construction rather than by
3207
+ # convention. A \`cd\` that fails takes the subshell non-zero with no
3208
+ # outcome line, which the reading below fails closed on.
3209
+ #
3210
+ # \`|| adjudicated=\$?\` AND NOT A PLAIN ASSIGNMENT (#1110). The module
3211
+ # header says "No \`set -e\`", and that is true of what this generator
3212
+ # WRITES and false of what the runner SUPPLIES: GitHub's default shell for
3213
+ # a \`run:\` step is \`/usr/bin/bash -e {0}\`, which every job log echoes.
3214
+ # Under \`-e\` an assignment whose value is a command substitution takes
3215
+ # the substitution's status, and a non-zero status aborts the shell ON
3216
+ # THIS LINE — so \`adjudicated=\$?\`, the \`printf\`, the \`case\` and the
3217
+ # UNMEASURED annotation below were all unreachable for every non-zero
3218
+ # adjudication, which is EVERY blocking finding and EVERY failure to
3219
+ # start. Measured on run 39711570020: 1.8s, no stdout at all, exit 1.
3220
+ # An uninstallable adjudicator was worse still — the shell died carrying
3221
+ # the adjudicator's own 127 out of the job, past the mapped exit
3222
+ # ${AI_REVIEW_REQUIRED_EXIT} entirely.
3223
+ #
3224
+ # \`||\` puts the substitution where \`-e\` does not fire, so the exit code
3225
+ # becomes DATA for the reading below instead of control flow. Everything
3226
+ # downstream was already correct; it had simply never run.
3227
+ #
3228
+ # \`adjudicated\` is seeded first: on the success path the \`||\` branch
3229
+ # does not execute, and an unset variable there would make a clean
3230
+ # adjudication read as an empty string rather than as 0.
3231
+ adjudicated=0
3232
+ adjudication=\$(cd "\$(dirname "\${${AI_REVIEW_FINDINGS_PATH_VAR}}")" && ${adjudicator} "\${${AI_REVIEW_FINDINGS_PATH_VAR}}" 2>&1) || adjudicated=\$?
3233
+ printf '%s\\n' "\${adjudication}"
3234
+
3235
+ # DID IT RUN, asked before WHAT IT SAID. Without this line a registry that
3236
+ # is down, a runner without bun and a review carrying a \`critical\` all
3237
+ # exit 1 and all read as a blocked pull request.
3238
+ #
3239
+ # The code is MAPPED rather than passed through, so every non-zero exit in
3240
+ # this script is still the one exported constant — \`test/ai-review-
3241
+ # scaffold.test.ts\` AC-6b refuses a literal here, and a bare
3242
+ # \`exit \${adjudicated}\` would be a refusal the mutation that zeroes
3243
+ # \${AI_REVIEW_REQUIRED_EXIT} could not reach. It re-states the same value
3244
+ # rather than adding one: the reader's own refusals already route through
3245
+ # that constant (\`test/ai-review-exit-binding.test.ts\`), so the only
3246
+ # thing this widens is a reader that ran and died some other way, which is
3247
+ # a refusal too.
3248
+ case "\${adjudication}" in
3249
+ *"${AI_REVIEW_OUTCOME_LINE}"*)
3250
+ # THE POSITIVE READING (#1087), emitted inside the arm and above both
3251
+ # exits, so it is carried by a blocking verdict as well as a clean
3252
+ # one. What it distinguishes is not CLEAN from BLOCKED — the exit code
3253
+ # already does that — but "a verdict" from "no verdict", which nothing
3254
+ # outside this job could tell apart while every terminal state was
3255
+ # either a shared-title warning or silence.
3256
+ #
3257
+ # The outcome line is lifted out of the captured output rather than
3258
+ # re-derived: \`\${adjudication}\` is what the reader actually printed,
3259
+ # and a second spelling of the verdict computed here could disagree
3260
+ # with the exit code this step is about to use (#295).
3261
+ #
3262
+ # Lifted by PARAMETER EXPANSION and not by \`grep | head\`, for two
3263
+ # independent reasons. \`test/ai-review-security-repairs.test.ts\`
3264
+ # AC-14a refuses any \`\$(\` in an annotation that is not
3265
+ # \`escape_annotation\` — the encoder is the one command an annotation
3266
+ # may run, and a pipeline inside its argument is a second one. And an
3267
+ # expansion has no exit status to abort on: a \`grep\` that matched
3268
+ # nothing exits 1, which under the runner's \`bash -e\` would kill the
3269
+ # step between the adjudication and the verdict, which is #1110
3270
+ # exactly. The two-step form takes everything after the marker, then
3271
+ # everything before the first newline, then puts the marker back.
3272
+ #
3273
+ # \`escape_annotation\` IS applied here, where the comment above
3274
+ # declines it for the reader's own \`::error\` payload. The difference
3275
+ # is whose string it is: that one arrives pre-escaped and escaping it
3276
+ # twice turns \`%\` into \`%2525\`, while this one is assembled by this
3277
+ # step out of a line the reader never escaped.
3278
+ verdict="\${adjudication#*${AI_REVIEW_OUTCOME_LINE}}"
3279
+ verdict="${AI_REVIEW_OUTCOME_LINE}\${verdict%%\$'\\n'*}"
3280
+ echo "::notice title=${AI_REVIEW_ADJUDICATED_TITLE}::$(escape_annotation "\${verdict}") — ${adjudicatedEvidence}"
3281
+ if [ "\${adjudicated}" = 0 ]; then
3282
+ exit 0
3283
+ fi
3284
+ exit ${AI_REVIEW_REQUIRED_EXIT}
3285
+ ;;
3286
+ esac
3287
+
3288
+ # NO ${AI_REVIEW_REQUIRE_VAR} CHECK HERE, deliberately — see the sentence
3289
+ # this prints. A payload exists, so a review was attempted; "nobody read
3290
+ # it" is a failure on every tree, not an opt-in. The flag still governs
3291
+ # every branch above and below, where nothing was attempted at all.
3292
+ echo "::error title=${AI_REVIEW_UNMEASURED_TITLE}::${unadjudicated}" >&2
3293
+ exit ${AI_REVIEW_REQUIRED_EXIT}
2857
3294
  fi
2858
3295
 
2859
3296
  # Which route, and nothing else. \`route\` is a string this block prints; no
@@ -2867,8 +3304,28 @@ if [ "\${AI_REVIEW_ACTION_OUTCOME:-}" = success ]; then
2867
3304
  # different explanatory sentence rather than a different verdict.
2868
3305
  if grep -qE '"subtype"[[:space:]]*:[[:space:]]*"error_max_turns"' "\${${AI_REVIEW_EXECUTION_FILE_VAR}}"; then
2869
3306
  route="${exhausted}"
3307
+ elif ! grep -qE '"${AI_REVIEW_DENIALS_KEY}"[[:space:]]*:' "\${${AI_REVIEW_EXECUTION_FILE_VAR}}"; then
3308
+ # Asked FIRST, because the two readings below are both about a number
3309
+ # that may not be there, and "absent" answered last is "absent" reported
3310
+ # as whichever branch fell through to it.
3311
+ route="${executedDenialsUnknown}"
3312
+ elif grep -qE '"${AI_REVIEW_DENIALS_KEY}"[[:space:]]*:[[:space:]]*0[[:space:]]*(,|\}|$)' "\${${AI_REVIEW_EXECUTION_FILE_VAR}}"; then
3313
+ # The end-anchor is \`(,|}|$)\` and the \`$\` is the whole of it. grep is
3314
+ # LINE-based: it strips the newline before matching, so in the
3315
+ # pretty-printed file the action actually writes — where this field is
3316
+ # the last member of the result object — the character after \`0\` is the
3317
+ # end of the line and nothing else. A \`[,}]\` class alone therefore
3318
+ # fails to match a genuine zero, which is the failing direction: the
3319
+ # zero route would be unreachable and every executed run would report
3320
+ # denials it did not have.
3321
+ #
3322
+ # That is not a hypothetical. The first draft of this branch was
3323
+ # \`[,}]\`, and \`test/ai-review-route-reading.test.ts\` AC-C4 caught it by
3324
+ # pairing the three routes and finding two of them printing one
3325
+ # sentence. The trailing \`,\` and \`}\` are kept for a compact file.
3326
+ route="${executedNoDenials}"
2870
3327
  else
2871
- route="${executed}"
3328
+ route="${executedDenied}"
2872
3329
  fi
2873
3330
  elif [ -n "\${${AI_REVIEW_EXECUTION_FILE_VAR}:-}" ]; then
2874
3331
  # Named but unreadable. Reporting that as the declined route would be a
@@ -3216,6 +3673,27 @@ export const AI_REVIEW_UNTRUSTED_PATHS: readonly string[] = [
3216
3673
  // one. Both are needed and neither covers the other.
3217
3674
  ".gitignore",
3218
3675
  ".gitattributes",
3676
+ // #1013 review. Not an instruction and not an input to the measurement —
3677
+ // this one selects the INTERPRETER. The job's `setup-bun` step reads this
3678
+ // file out of the checkout to decide which bun to install, and that bun
3679
+ // then runs the findings adjudicator inside a credentialed job. A branch
3680
+ // that edits it is choosing the runtime its own reviewer executes.
3681
+ //
3682
+ // Spelled as a literal because this module has no relative imports (see
3683
+ // `AiReviewActionRefs`), so it cannot read `BUN_VERSION_FILE` from
3684
+ // `lib/bun-version.ts`. That makes it a second position for one name, and
3685
+ // the repair is a test rather than a comment: `test/ai-review-untrusted-
3686
+ // restore.test.ts` compares this entry to that constant, so the two cannot
3687
+ // drift apart silently.
3688
+ //
3689
+ // The sibling bun/npm resolution files — `bunfig.toml`, `.npmrc`,
3690
+ // `package.json`, `bun.lock`, `node_modules` — are deliberately NOT here.
3691
+ // The adjudicator runs with its working directory under `RUNNER_TEMP`, and
3692
+ // bun resolves those by walking up from the working directory, so none of
3693
+ // them is on its path at all. Restoring `package.json` would additionally
3694
+ // change WHAT THE REVIEWER READS, which #1013's body flags as a separate
3695
+ // decision and not one to make in passing.
3696
+ ".bun-version",
3219
3697
  ];
3220
3698
 
3221
3699
  export const AI_REVIEW_RESTORE_STEP_ID = "ai-review-restore-untrusted";
@@ -3367,7 +3845,19 @@ base_remote="refs/remotes/origin/\${base_ref}"
3367
3845
 
3368
3846
  # Through the environment, never \`-c\`: a value passed with \`-c\` is in the
3369
3847
  # command line of the git process and readable by anything that can run \`ps\`.
3370
- ${AI_REVIEW_GIT_AUTH_VAR}="AUTHORIZATION: basic $(printf 'x-access-token:%s' "\${GITHUB_TOKEN:-}" | base64 | tr -d '\\n')"
3848
+ #
3849
+ # Wrapped in \`if !\` rather than left a bare assignment, which is the idiom the
3850
+ # fetch below already uses and for the same reason (#1116). GitHub runs this
3851
+ # step as \`bash -e\`, and with \`pipefail\` set an assignment from a pipeline
3852
+ # takes the pipeline's status, so any failure here would abort the step on
3853
+ # this line: no annotation, no exit code of ours, nothing on stdout. That is
3854
+ # the shape of #1110. These three commands are local and a failure is remote,
3855
+ # but "this cannot fail" is exactly what was believed about the adjudication
3856
+ # until an npm 503 falsified it.
3857
+ if ! ${AI_REVIEW_GIT_AUTH_VAR}="AUTHORIZATION: basic $(printf 'x-access-token:%s' "\${GITHUB_TOKEN:-}" | base64 | tr -d '\\n')"; then
3858
+ echo "::error title=AI review modified the tree::could not build the credential header used to fetch the pull request base, so the untrusted paths were NOT restored and this run is UNMEASURED." >&2
3859
+ exit ${AI_REVIEW_REQUIRED_EXIT}
3860
+ fi
3371
3861
  export ${AI_REVIEW_GIT_AUTH_VAR}
3372
3862
 
3373
3863
  # Checked on its own line, never captured into an assignment, for the reason
@@ -3804,55 +4294,136 @@ export const AI_REVIEW_IGNORED_READING = "--ignored=matching";
3804
4294
  * - **It names a SHA-pinned dependency's documented scratch**, not a class of
3805
4295
  * paths and not anything in this repository.
3806
4296
  *
3807
- * ## UNMEASURED, and asserted so it cannot outlive its subject
4297
+ * ## What the exemption used to cost, and no longer does (#1071)
3808
4298
  *
3809
- * A write INSIDE `.claude-pr/` is not seen. That is true of every
3810
- * collapsed-ignored directory under `matching` and is not special to this one;
3811
- * it is the price of the entry count above. The case that asserts the
3812
- * blindness is in `test/ai-review-ignored-reading.test.ts`, so the day the
3813
- * reading starts seeing it, the note is refuted rather than left standing.
4299
+ * `continue` on this entry did not drop a line — it dropped the ONLY line.
4300
+ * `matching` collapses the whole ignored subtree to `!! .claude-pr/`, so
4301
+ * exempting that entry left the reading EMPTY and the drift step with nothing
4302
+ * to compare: `.claude-pr/EVIL.md` was invisible at any depth. The exemption
4303
+ * stays, because the action still creates and ignores this directory
4304
+ * mid-review and nothing separates it from a plant. What changed is that the
4305
+ * reader now descends one level instead of returning — see
4306
+ * `AI_REVIEW_SCRATCH_SCAN_LIMIT`.
3814
4307
  */
3815
4308
  export const AI_REVIEW_ACTION_SCRATCH = ".claude-pr/";
3816
4309
 
3817
4310
  /**
3818
- * What a collapsed ignored DIRECTORY hashes to (#1061).
4311
+ * How many entries of the exempted scratch the reader will report (#1071).
4312
+ *
4313
+ * ## The hole this bounds, and why descending one level closes it
4314
+ *
4315
+ * The exemption above is unavoidable and the entry it exempts is the whole
4316
+ * reading, so everything under `.claude-pr/` was invisible. Closing that
4317
+ * cannot mean "report the scratch's contents": the action fills it mid-review
4318
+ * and the baseline was taken before, so every file in it is an addition and
4319
+ * every pull request goes red. That is PR #1002's outage with extra steps,
4320
+ * and it is why #1071 was filed rather than patched.
4321
+ *
4322
+ * The discriminator is read from the dependency's own source rather than
4323
+ * guessed. `restoreConfigFromBase()` in `src/github/operations/restore-config.ts`
4324
+ * at the pinned SHA is the only writer, and it writes exactly:
4325
+ *
4326
+ * ```ts
4327
+ * rmSync(".claude-pr", { recursive: true, force: true });
4328
+ * for (const p of SENSITIVE_PATHS) {
4329
+ * if (lstatSync(p, { throwIfNoEntry: false })) {
4330
+ * snapshotSensitivePath(p, `.claude-pr/${p}`, workTreeRealPath, tracked);
4331
+ * }
4332
+ * }
4333
+ * ```
4334
+ *
4335
+ * Every `p` is a single path component, so **the action creates nothing at the
4336
+ * TOP of its scratch except a name from that list** — including the
4337
+ * `recordPlaceholder` files, which land under the same `p`. A top-level entry
4338
+ * with any other name had no second author, and that is a property of the
4339
+ * writer, not a shape of the message.
4340
+ *
4341
+ * So the reader enumerates `.claude-pr/` at depth ONE, drops the mirrored
4342
+ * names, and classifies the rest exactly as it classifies any other path. On
4343
+ * a normal pull request that yields zero lines, by construction — which is
4344
+ * what makes this green rather than hopeful.
4345
+ *
4346
+ * ## The names come from `AI_REVIEW_UNTRUSTED_PATHS`, and that is a widening
4347
+ *
4348
+ * That constant is required to be a SUPERSET of the action's list, and it
4349
+ * currently holds two names the action does not snapshot — `.gitignore` and
4350
+ * `.gitattributes`, added by #856 because they are inputs to the measurement.
4351
+ * So `.claude-pr/.gitignore` stays unreported. Stated rather than hidden, and
4352
+ * asserted, but not repaired with a second list: a list that is a SUBSET of
4353
+ * the action's reds every pull request the first time the action's list
4354
+ * grows, and a superset costs two blind names. One declaring position, and
4355
+ * the error that remains is the survivable one.
4356
+ *
4357
+ * ## Volume, which is the bound the issue asked for
4358
+ *
4359
+ * `-maxdepth 1`, so the cost is the number of top-level entries — ten, not
4360
+ * the size of a copy of the pull request's `.claude/` tree. No `hash-object`
4361
+ * runs for a mirrored name. The limit below bounds what a REVIEWER can make
4362
+ * the reader print; truncating it cannot flip the verdict, because one line
4363
+ * is already a refusal.
4364
+ *
4365
+ * ## WHAT THIS DOES NOT FIX
4366
+ *
4367
+ * A write under a mirrored name — `.claude-pr/.claude/EVIL.md` — is still
4368
+ * invisible. That is `--ignored=matching`'s collapse, the same bound
4369
+ * `AI_REVIEW_PRESENT_UNHASHABLE` already states, and it is asserted in
4370
+ * `test/ai-review-ignored-reading.test.ts` so it cannot outlive its subject.
4371
+ */
4372
+ export const AI_REVIEW_SCRATCH_SCAN_LIMIT = 50;
4373
+
4374
+ /**
4375
+ * What a path that is PRESENT but not a regular file hashes to (#1061,
4376
+ * #1070).
3819
4377
  *
3820
4378
  * ## `absent` was true of every input the reader could be handed, until #969
3821
4379
  *
3822
- * `--untracked-files=all` alone never yields a directory entry — that is
3823
- * what `all` means — so `[ -f "${p}" ]` was a total question and its `else`
3824
- * branch was always right. `AI_REVIEW_IGNORED_READING` introduces the one
3825
- * input it is wrong about: a wholly-ignored directory, reported collapsed
3826
- * with a trailing slash, present on disk, and stamped `absent`.
4380
+ * `--untracked-files=all` alone yields nothing but file paths, so
4381
+ * `[ -f "${p}" ]` was a total question and its `else` branch was always
4382
+ * right: not a regular file meant gone. `AI_REVIEW_IGNORED_READING` broke
4383
+ * that, and the reader then had two states sharing one token —
4384
+ * *the path was removed* and *the path is here and is not a file*.
3827
4385
  *
3828
- * ## Why that is not a cosmetic lie
4386
+ * ## Why conflating them is not a cosmetic lie
3829
4387
  *
3830
4388
  * `absent` is a VALUE the drift step branches on. #989's twice-restored
3831
4389
  * classifier reads it as *the action deleted a restored path*, asks the base
3832
4390
  * whether it carries the file, and on `no` files the line under `restored` —
3833
4391
  * acquitted, and reported as the action's work rather than the reviewer's.
3834
- * A directory can reach that branch, and the question it is then asked is a
3835
- * question about a file.
4392
+ * So a path that exists reaches a branch that assumes it does not, and the
4393
+ * run says the opposite of what happened.
3836
4394
  *
3837
- * Measured against `origin/main` at `d8f76417`, git 2.50.1, driving the real
3838
- * `buildBaselineScript()` and `buildDriftScript()`. The reviewer does exactly
3839
- * two things between the two readings — appends `/.claude/evil/` to
3840
- * `.git/info/exclude`, and writes `.claude/evil/payload.md`:
3841
- *
3842
- * | reader | `git status` | drift |
3843
- * |---|---|---|
3844
- * | before this change | `!! .claude/evil/` | **exit 0**, warning: *"NOT counted as a reviewer write (#989). Paths: `absent .claude/evil/`"* |
3845
- * | with this token | `!! .claude/evil/` | **exit 1**: *"The reviewer modified the tree it was reviewing: `ignored-dir .claude/evil/`"* |
4395
+ * ## Both shapes, measured end to end
3846
4396
  *
3847
- * The refusal is not a new rule. The line simply stops entering the `absent`
3848
- * branch, falls through to the blob comparison, resolves nothing on the base,
3849
- * and stays in `added` — which is the tight direction that comparison already
3850
- * documents.
4397
+ * Real `buildBaselineScript()` and `buildDriftScript()`, git 2.50.1. In each
4398
+ * row the reviewer acts once between the two readings, under an untrusted
4399
+ * path so the line reaches #989's classifier:
3851
4400
  *
3852
- * `.claude/evil/` is deliberately NOT `AI_REVIEW_ACTION_SCRATCH`: that
3853
- * exemption is exact and correctly does not match, and this change does not
3854
- * touch it. PR #1002's outage stays closed, which `AC-7/green` is the control
3855
- * for.
4401
+ * | the reviewer writes | token | drift |
4402
+ * |---|---|---|
4403
+ * | `/.claude/evil/` into `.git/info/exclude`, then `.claude/evil/payload.md` | was `absent` | **exit 0**, credited to the action (`d8f76417`) |
4404
+ * | a dangling symlink `.claude/evil-link` | was `absent` | **exit 0**, credited to the action (`c514b585`) |
4405
+ * | either, with this token | `not-a-regular-file` | **exit 1**, named as a reviewer write |
4406
+ *
4407
+ * **Row two is why this constant is not called `ignored-dir`.** #1061 shipped
4408
+ * a trailing-slash case arm keyed on git's own slash, which is the shape of the first
4409
+ * row and not the property either row has. `[ -f ]` is false for a dangling
4410
+ * symlink, a fifo and a socket too, and none of those carries a slash. The
4411
+ * arm is gone: `[ -e ]` is true of a collapsed directory, so keeping both
4412
+ * would be two deciders for one question and a mutation of either would
4413
+ * leave the other holding the case up.
4414
+ *
4415
+ * `[ -e ]` FOLLOWS symlinks, so it is false for a dangling one. `[ -L ]` is
4416
+ * the half that catches it, and omitting it is exactly how #1061 came up
4417
+ * short.
4418
+ *
4419
+ * The refusal is not a new rule. The line stops entering the `absent` branch,
4420
+ * falls through to the blob comparison, resolves nothing on the base, and
4421
+ * stays in `added` — the tight direction that comparison already documents.
4422
+ *
4423
+ * `absent` keeps its meaning and its branch: a tracked file the reviewer
4424
+ * DELETES still reads `absent` and is still classified exactly as before.
4425
+ * `AC-11/deletion` is the control that says this is a repair and not a
4426
+ * widening that retires a working branch.
3856
4427
  *
3857
4428
  * ## Not folded into the UNMEASURED warning, deliberately
3858
4429
  *
@@ -3862,13 +4433,14 @@ export const AI_REVIEW_ACTION_SCRATCH = ".claude-pr/";
3862
4433
  *
3863
4434
  * ## WHAT THIS DOES NOT FIX
3864
4435
  *
3865
- * The collapsed entry carries no content hash, so a write INSIDE a directory
3866
- * that was already ignored at baseline is still invisible and a modification
3867
- * inside one still produces a byte-identical line. Unchanged, UNMEASURED,
3868
- * and already asserted by `AC-8/inside`. `--ignored=traditional` is the only
3869
- * setting that sees it, at 1508 lines on this checkout.
4436
+ * The line carries no content, so a write INSIDE a directory already ignored
4437
+ * at baseline is still invisible and a modification inside one still produces
4438
+ * a byte-identical line. Unchanged, UNMEASURED, asserted by `AC-8/inside`.
4439
+ * `--ignored=traditional` is the only setting that sees it, at 1508 lines on
4440
+ * this checkout. The blindness under `AI_REVIEW_ACTION_SCRATCH` specifically
4441
+ * is #1071.
3870
4442
  */
3871
- export const AI_REVIEW_IGNORED_DIR_HASH = "ignored-dir";
4443
+ export const AI_REVIEW_PRESENT_UNHASHABLE = "not-a-regular-file";
3872
4444
 
3873
4445
  /**
3874
4446
  * The one reading of the tree, shared by the baseline step and the drift step
@@ -3938,8 +4510,162 @@ export const AI_REVIEW_IGNORED_DIR_HASH = "ignored-dir";
3938
4510
  * content.
3939
4511
  */
3940
4512
 
3941
- export const AI_REVIEW_TREE_READER = `read_tree() {
3942
- local raw line xy p h
4513
+ export const AI_REVIEW_TREE_READER = `classify_path() {
4514
+ local p h esc
4515
+ p="\${1}"
4516
+ # ONE quoting decision, for every source that reaches this function.
4517
+ #
4518
+ # The leading-quote test is git's shape: porcelain v1 C-quotes a path
4519
+ # carrying a newline, a quote or a backslash, so a git-derived path arrives
4520
+ # already wrapped and matches here. \`read_scratch\` (#1071) does NOT get its
4521
+ # paths from git — it globs the filesystem — so an attacker-chosen name
4522
+ # reaches this function raw, and the line below PRINTS it. A name carrying a
4523
+ # newline therefore printed as TWO lines, and the second was indistinguishable
4524
+ # from a record this function produced: a reviewer naming a file
4525
+ # \`p<newline>absent .ripgreprc\` wrote \`absent .ripgreprc\` into the reading,
4526
+ # which is the token #989's classifier acquits on and reports as the review
4527
+ # action's own restore. Measured on \`origin/main\` at \`77dd0f7f\`: exit 1 from
4528
+ # the reviewer's own genuine line, and the forged path named in the
4529
+ # twice-restored warning as the ACTION's work.
4530
+ #
4531
+ # Asked HERE and not in the walk, deliberately. "Is this path safe to print"
4532
+ # has one answer, and two guards answering it are one decider with a spare —
4533
+ # a mutation of either leaves the other holding the case up
4534
+ # (\`.claude/rules/checks-must-be-able-to-fail.md\`, fourth shape). The next
4535
+ # path source inherits this instead of needing a third.
4536
+ #
4537
+ # THE NEWLINE IS THE ONE THAT MATTERS, and a quote-anywhere test is the
4538
+ # cheapest wrong fix: a quote or a backslash in the MIDDLE of a name
4539
+ # corrupts a field, while only a newline forges a RECORD. A case built
4540
+ # around a quoted filename goes green on the newline and witnesses nothing.
4541
+ #
4542
+ # TWO ARMS, ONE TOKEN (#1104). Both are \`unquotable\` and both raise
4543
+ # UNMEASURED; they differ only in whether the name is already safe to print.
4544
+ #
4545
+ # git C-quotes a porcelain path carrying a space, a quote, a backslash or a
4546
+ # control character — measured, git 2.50.1: \`"ordinary name with spaces.md"\`
4547
+ # comes back WRAPPED. So a git-derived path is already single-line and
4548
+ # already injective, and re-escaping it would change the record for every
4549
+ # spaced filename in every consumer repository to buy nothing.
4550
+ #
4551
+ # A path from \`read_scratch\` was never seen by git and is wrapped by
4552
+ # nothing. That is the one that needs escaping below, and \`esc\` is how the
4553
+ # renderer knows which it is WITHOUT asking the question a second time.
4554
+ case "\${p}" in
4555
+ '"'*) h=unquotable; esc= ;;
4556
+ *$'\\n'*) h=unquotable; esc=1 ;;
4557
+ *)
4558
+ esc=
4559
+ if [ -f "\${p}" ]; then
4560
+ # --no-filters, or the repository's own text/eol conversion is
4561
+ # applied before hashing and two DIFFERENT working-tree blobs
4562
+ # collapse to one hash (#856 F3). Measured under \`* text eol=lf\`:
4563
+ # "x\\r\\n" and "x\\n" both hash 587be6b4…, and with --no-filters
4564
+ # they are db127bf6… and 587be6b4…. The reading is only a reading
4565
+ # of content if the hash is of the bytes on disk.
4566
+ # Isolated for the same reason as the status below (#960). It is
4567
+ # the \`-c\` half that matters here: \`--no-filters\` already
4568
+ # defeats a text/eol conversion, but a hash taken under the
4569
+ # reviewer's config is still a reading the reviewer chose.
4570
+ h=$(${AI_REVIEW_GIT_ISOLATED} hash-object --no-filters -- "\${p}" 2>/dev/null) || h=unreadable
4571
+ # PRESENT but not a regular file, which is not a deletion. \`-e\`
4572
+ # FOLLOWS symlinks, so it is false for a dangling one — \`-L\` is the
4573
+ # half that catches it, and leaving it out is how #1061 came up
4574
+ # short. See AI_REVIEW_PRESENT_UNHASHABLE.
4575
+ elif [ -e "\${p}" ] || [ -L "\${p}" ]; then
4576
+ h=${AI_REVIEW_PRESENT_UNHASHABLE}
4577
+ else
4578
+ h=absent
4579
+ fi
4580
+ ;;
4581
+ esac
4582
+ # ESCAPED, not truncated (#1104). The record must be one line, and it must
4583
+ # name the entry it is about.
4584
+ #
4585
+ # The first repair truncated at the first newline. That made the record
4586
+ # single-line and made the printed path NOT the path on disk, so a reviewer
4587
+ # who writes both \`x\` and \`x<newline>y\` produced two records naming one
4588
+ # path with two different tokens — fail-safe, both refuse, and a reading a
4589
+ # human cannot act on. Full redaction is worse: two distinct plants collapse
4590
+ # to byte-identical lines and the refusal names neither.
4591
+ #
4592
+ # \`%q\` is injective and single-line, so the name survives in full and two
4593
+ # entries can never collide. It is also the convention this reader already
4594
+ # has for this condition — the docblock above describes a path git had to
4595
+ # quote, and this is the same answer for a path git never saw.
4596
+ #
4597
+ # KEYED OFF \`\${esc}\`, NOT OFF \`\${p}\`. The \`case\` has already decided
4598
+ # whether this path can be printed as itself; asking again here would be the
4599
+ # second decider #1071 spent its whole battery avoiding, and the two could
4600
+ # then be changed apart. This reads that answer.
4601
+ #
4602
+ # NOT UNCONDITIONAL, and this is the coupling to protect: \`%q\` escapes a
4603
+ # SPACE, and the drift step does \`p="\${line#* }"\` and hands the result to
4604
+ # \`git cat-file -e <base>:<path>\` (#989). An escaped ordinary path would
4605
+ # stop resolving on the base, so every path with a space in it would stop
4606
+ # being acquitted. \`%q\` is the identity for a path with no special
4607
+ # characters, which is exactly why an unconditional version looks green and
4608
+ # is not.
4609
+ if [ -n "\${esc}" ]; then
4610
+ printf '%s %q\\n' "\${h}" "\${p}"
4611
+ else
4612
+ printf '%s %s\\n' "\${h}" "\${p}"
4613
+ fi
4614
+ }
4615
+
4616
+ # The interior of the one exempted entry, one level deep (#1071). Split out of
4617
+ # the loop below so there is exactly ONE classifier: every path this finds goes
4618
+ # through \`classify_path\` rather than through a copy of it, so whoever next
4619
+ # changes how a path is turned into a token changes it here too without
4620
+ # knowing this function exists.
4621
+ #
4622
+ # \`\${1}\` is the scratch entry git just reported, carrying git's own trailing
4623
+ # slash, so the globs below expand against its contents. Three of them,
4624
+ # because a single \`*\` does not match a leading dot and the two dot forms
4625
+ # skip \`.\` and \`..\`. Globbing rather than \`find\`: a filename may contain a
4626
+ # newline, and \`find | while read\` would split one entry into two and report
4627
+ # neither.
4628
+ #
4629
+ # NOTHING here asks what kind of thing an entry is. #1070 made
4630
+ # \`classify_path\` ask the property — present-and-hashable against
4631
+ # present-and-not against gone — so a directory, a fifo and a dangling link
4632
+ # planted here are all answered by the one classifier. An earlier draft of
4633
+ # this walk tested \`[ -d \]\` to hand a directory on in git's collapsed shape;
4634
+ # that was a second decider for a question #1070 already answers, and it is
4635
+ # gone rather than left beside it.
4636
+ read_scratch() {
4637
+ local root e name u mirrored n
4638
+ root="\${1}"
4639
+ n=0
4640
+ for e in "\${root}"* "\${root}".[!.]* "\${root}"..?*; do
4641
+ # An unmatched glob comes back as the pattern itself. \`-L\` as well as
4642
+ # \`-e\`, because \`-e\` follows symlinks and is false for a dangling one —
4643
+ # which is a thing the reviewer can create and the reader must still
4644
+ # report (#1070).
4645
+ { [ -e "\${e}" ] || [ -L "\${e}" ]; } || continue
4646
+ name="\${e##*/}"
4647
+ # The action snapshots each of these paths into the scratch under its own
4648
+ # name, and every one of them is a single component, so a top-level entry
4649
+ # with any other name is not the action's. See
4650
+ # AI_REVIEW_SCRATCH_SCAN_LIMIT.
4651
+ mirrored=
4652
+ for u in ${AI_REVIEW_UNTRUSTED_PATHS.map(p => "'" + p + "'").join(" ")}; do
4653
+ if [ "\${name}" = "\${u}" ]; then
4654
+ mirrored=1
4655
+ break
4656
+ fi
4657
+ done
4658
+ [ -z "\${mirrored}" ] || continue
4659
+ n=$((n + 1))
4660
+ if [ "\${n}" -gt ${AI_REVIEW_SCRATCH_SCAN_LIMIT} ]; then
4661
+ break
4662
+ fi
4663
+ classify_path "\${e}"
4664
+ done
4665
+ }
4666
+
4667
+ read_tree() {
4668
+ local raw line xy p
3943
4669
  # Checked on its own line, never captured into an assignment: \`x=$(...)\`
3944
4670
  # DISCARDS the exit code, so a git that failed produces the same empty
3945
4671
  # string a clean tree produces, and "unreadable" would pass as "clean".
@@ -3969,35 +4695,16 @@ export const AI_REVIEW_TREE_READER = `read_tree() {
3969
4695
  # a path merely starting with the name, or carrying anything after the
3970
4696
  # slash, is still reported. See AI_REVIEW_ACTION_SCRATCH for why an
3971
4697
  # exemption is unavoidable at all.
4698
+ #
4699
+ # DESCEND rather than \`continue\` (#1071). This entry is not one line of
4700
+ # the reading, it IS the reading — \`matching\` collapses the whole subtree
4701
+ # into it — so skipping it left the comparison empty and everything the
4702
+ # reviewer wrote under that path invisible at any depth.
3972
4703
  if [ "\${p}" = "${AI_REVIEW_ACTION_SCRATCH}" ]; then
4704
+ read_scratch "\${p}"
3973
4705
  continue
3974
4706
  fi
3975
- case "\${p}" in
3976
- '"'*) h=unquotable ;;
3977
- # A wholly-ignored directory, reported COLLAPSED with git's own
3978
- # trailing slash. It is PRESENT, so \`absent\` would be false — and
3979
- # \`absent\` is a value the drift step branches on, so the lie does not
3980
- # stay cosmetic. See AI_REVIEW_IGNORED_DIR_HASH.
3981
- */) h=${AI_REVIEW_IGNORED_DIR_HASH} ;;
3982
- *)
3983
- if [ -f "\${p}" ]; then
3984
- # --no-filters, or the repository's own text/eol conversion is
3985
- # applied before hashing and two DIFFERENT working-tree blobs
3986
- # collapse to one hash (#856 F3). Measured under \`* text eol=lf\`:
3987
- # "x\\r\\n" and "x\\n" both hash 587be6b4…, and with --no-filters
3988
- # they are db127bf6… and 587be6b4…. The reading is only a reading
3989
- # of content if the hash is of the bytes on disk.
3990
- # Isolated for the same reason as the status above (#960). It is
3991
- # the \`-c\` half that matters here: \`--no-filters\` already
3992
- # defeats a text/eol conversion, but a hash taken under the
3993
- # reviewer's config is still a reading the reviewer chose.
3994
- h=$(${AI_REVIEW_GIT_ISOLATED} hash-object --no-filters -- "\${p}" 2>/dev/null) || h=unreadable
3995
- else
3996
- h=absent
3997
- fi
3998
- ;;
3999
- esac
4000
- printf '%s %s\\n' "\${h}" "\${p}"
4707
+ classify_path "\${p}"
4001
4708
  done
4002
4709
  }`;
4003
4710
 
@@ -4373,7 +5080,7 @@ ${AI_REVIEW_RUNTIME_CONFIG_PATHS.map((p, i) => {
4373
5080
  \\) \\
4374
5081
  2>/dev/null | head -50 || true)
4375
5082
  if [ -n "\${runtime_config}" ]; then
4376
- echo "::warning title=${AI_REVIEW_UNMEASURED_TITLE}::${runtimeConfig}: $(escape_annotation "\${runtime_config}")"
5083
+ echo "::warning title=${AI_REVIEW_RUNTIME_CONFIG_TITLE}::${runtimeConfig}: $(escape_annotation "\${runtime_config}")"
4377
5084
  fi
4378
5085
 
4379
5086
  if [ -n "\${outside}" ]; then
@@ -4562,9 +5269,14 @@ function indented(lines: string[], indent: string): string {
4562
5269
  /**
4563
5270
  * The review steps, as YAML, ready to be indented under a job's `steps:`.
4564
5271
  *
4565
- * Six steps, in the order they have to run: check out the branch, choose a
4566
- * payload path outside it, authenticate to Vertex, run the reviewer, say
4567
- * whether it ran, and refuse one that edited the tree it was reviewing.
5272
+ * In the order they have to run: check out the branch, choose a payload path
5273
+ * outside it, install bun for the adjudicator, authenticate to Vertex, run the
5274
+ * reviewer, adjudicate its payload, and refuse one that edited the tree it was
5275
+ * reviewing.
5276
+ *
5277
+ * `version` is the generating harness version, and it reaches the `bunx`
5278
+ * invocation in the verdict step. It is a parameter rather than a read because
5279
+ * this module has no relative imports — see `AiReviewActionRefs`.
4568
5280
  *
4569
5281
  * Every credential is gated on the mode the
4570
5282
  * auth step resolved rather than on the secret itself — the auth step is the
@@ -4578,6 +5290,7 @@ function indented(lines: string[], indent: string): string {
4578
5290
  export function buildReviewRunStep(
4579
5291
  vertex: VertexCiDecision,
4580
5292
  refs: AiReviewActionRefs,
5293
+ version: string,
4581
5294
  indent = " ",
4582
5295
  ): string {
4583
5296
  const modeIs = (mode: string) =>
@@ -4602,6 +5315,27 @@ export function buildReviewRunStep(
4602
5315
  ...buildPrepareScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
4603
5316
  ];
4604
5317
 
5318
+ // #1013. BEFORE the baseline, for #836's reason rather than for
5319
+ // convenience: anything a step writes into GITHUB_WORKSPACE after the
5320
+ // baseline is taken lands in the REVIEWER's column in the drift reading.
5321
+ // This action writes to the runner's tool cache and to `~/.bun`, not to the
5322
+ // checkout — but "it does not write there today" is the kind of belief the
5323
+ // drift step exists to stop relying on, and taking it early makes whatever
5324
+ // it does write cancel.
5325
+ //
5326
+ // `continue-on-error: true`, like every other step here: nothing in this
5327
+ // job may have an `if:`, and a setup action that fails hard turns a runner
5328
+ // with no bun into a RED check rather than an UNMEASURED one. The verdict
5329
+ // step reads the adjudicator's own output and says which it was.
5330
+ const setupBun = [
5331
+ `- name: ${AI_REVIEW_SETUP_BUN_STEP_NAME}`,
5332
+ ` id: ${AI_REVIEW_SETUP_BUN_STEP_ID}`,
5333
+ ` continue-on-error: true`,
5334
+ ` uses: ${refs.setupBun}`,
5335
+ ` with:`,
5336
+ ...refs.setupBunWith.trimEnd().split("\n"),
5337
+ ];
5338
+
4605
5339
  // Workload Identity Federation, and NO service-account key (#677 AC-15).
4606
5340
  //
4607
5341
  // Emitted only when `ci.vertex` resolved. A step that authenticates with
@@ -4760,7 +5494,7 @@ export function buildReviewRunStep(
4760
5494
  // turning every unmeasured pull request green.
4761
5495
  ` ${AI_REVIEW_EVENT_VAR}: \${{ github.event_name }}`,
4762
5496
  ` run: |`,
4763
- ...buildReviewRunScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
5497
+ ...buildReviewRunScript(version).trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
4764
5498
  ];
4765
5499
 
4766
5500
  return (
@@ -4769,6 +5503,17 @@ export function buildReviewRunStep(
4769
5503
  (vertexAuth.length === 0 ? "" : indented(vertexAuth, indent)) +
4770
5504
  (credsRelocate.length === 0 ? "" : indented(credsRelocate, indent)) +
4771
5505
  indented(restore, indent) +
5506
+ // AFTER the restore and BEFORE the baseline, and both halves are load
5507
+ // bearing. The action reads the bun-version declaration out of the
5508
+ // CHECKOUT to decide which runtime to install, so running it before the
5509
+ // restore lets the branch choose the interpreter this job then executes
5510
+ // the adjudicator with. That declaration is in
5511
+ // `AI_REVIEW_UNTRUSTED_PATHS` for exactly that reason, and restoring it
5512
+ // buys nothing if the step that reads it has already run. Before the
5513
+ // baseline is #836's ordering: anything a step writes into the workspace
5514
+ // after the baseline is taken lands in the REVIEWER's column in the
5515
+ // drift reading.
5516
+ indented(setupBun, indent) +
4772
5517
  indented(baseline, indent) +
4773
5518
  indented(review, indent) +
4774
5519
  indented(report, indent) +