rungate 0.8.1 → 0.8.2

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.
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- e73bae87c60821d450f281197562ebe7338b1adc4ab2b320e4d0eeb0ae901e95
1
+ 4bf447cd9f1aa5df2cbb1c260d54255a2d976fb28149b342a2b0360d7c4adbe4
@@ -10,6 +10,25 @@
10
10
  * `.gate-salt`, `witnesses/` — and to hook sources, plus `chmod`/`chflags`
11
11
  * on a hook file and `security` access to the gate-salt Keychain entry.
12
12
  *
13
+ * Since #1175 a protected NAME under an OS scratch root is a fixture and is
14
+ * allowed; everything else, including a destination this module cannot place
15
+ * in a tree, keeps the refusal. The scratch roots are FIXED — `TMPDIR` can
16
+ * select among them and cannot name a new one, because the writer sets it —
17
+ * and a command that creates a symlink voids the exemption outright. The run
18
+ * store and the directories hook registrations actually resolve to are
19
+ * SUBTRACTED from the exemption wherever they are, including under `/tmp`:
20
+ * a checkout is the live hook exactly when a variable says it is, which
21
+ * `lib/hook-target-tree.ts` measured happening. The scoping is to the scratch tree and not to
22
+ * the project root because a live `workflow-state.json` is not in the project
23
+ * root — see `lib/bash-write-guard.ts` for the measurement.
24
+ *
25
+ * #1240: a heredoc or herestring handed to an INTERPRETER is a program and
26
+ * is decided as one. Before that the body was stripped before every arm and
27
+ * only a `-c`/`-e` body was read back, so `bash <<'EOF'` and `python3 <<'PY'`
28
+ * reached a live gate artifact with the guard deciding on the single word
29
+ * `bash`. A body fed to anything else — `cat > doc.md <<'EOF'`,
30
+ * `gh --body-file - <<'EOF'` — is still a DOCUMENT and still stripped.
31
+ *
13
32
  * THE DECISION LIVES IN `lib/bash-write-guard.ts` (#1120), which is where
14
33
  * the reasoning and the measurements are. It was extracted for the same
15
34
  * reason #1137 extracted `lib/gate-result-protection.ts`: a decision that
@@ -5,21 +5,33 @@
5
5
  * SC-370 (HOOK-ARCHITECTURE-SPEC): Hook SC traceability
6
6
  * SC-371 (HOOK-ARCHITECTURE-SPEC): No hook exceeds 150 lines
7
7
  *
8
- * Blocks `gh issue create` during VERIFY phase.
9
- * Use verifyBlockers[] instead. Allows `gh issue create` carrying one of the
10
- * override labels in lib/issue-create-override.ts.
8
+ * TWO independent gates on one chokepoint — `gh issue create` reaching Bash.
9
+ * Both decisions live in lib/ and not here (#365, HOOK-ARCHITECTURE-SPEC:
10
+ * hooks are thin triggers).
11
11
  *
12
- * The decision lives in lib/ and not here (#365, HOOK-ARCHITECTURE-SPEC:
13
- * hooks are thin triggers). It used to be a substring test on the whole
14
- * command, which a `follow-up` in an issue TITLE satisfied.
12
+ * 1. **The VERIFY-phase lock** (#443, #365). Workflow discipline: during
13
+ * VERIFY, use verifyBlockers[] instead. Waived by the override labels in
14
+ * lib/issue-create-override.ts. It used to be a substring test on the
15
+ * whole command, which a `follow-up` in an issue TITLE satisfied.
15
16
  *
16
- * Issue: #443
17
+ * 2. **The finding adjudication** (#1261), on every phase. Asks whether the
18
+ * finding earned a filing — duplicate, or a dropped category — through
19
+ * lib/finding-arbiter.ts's own bindings. Before this, the only question
20
+ * asked at this chokepoint was gate 1's, and gate 1 tests whether an agent
21
+ * typed a label. lib/issue-filing-gate.ts has the measurement and the
22
+ * reason the two gates do not share an override label.
23
+ *
24
+ * Asked in that order because gate 1 is a cheap local read and gate 2 may pay
25
+ * for a `gh issue list`.
26
+ *
27
+ * Issue: #443, #1261
17
28
  */
18
29
 
19
30
  import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
20
31
  import { join } from 'path';
21
32
  import { parseHookInput } from './lib/parseStdin';
22
33
  import { verifyPhaseRefusal } from '../lib/issue-create-override';
34
+ import { filingGate, ledgerPath, recordAdjudication } from '../lib/issue-filing-gate';
23
35
 
24
36
  const WORK_DIR = process.env.RUNGATE_WORK_DIR || process.env.PAI_WORK_DIR || join(process.env.HOME!, '.rungate');
25
37
 
@@ -69,15 +81,43 @@ async function main() {
69
81
 
70
82
  const cmd = payload.tool_input?.command || '';
71
83
 
84
+ // ── 1. the VERIFY-phase lock ──
85
+ //
72
86
  // Ask the owner BEFORE reading the workflow state. Cheap, and it keeps the
73
87
  // whole decision in one place rather than half here and half in lib/.
74
88
  const refusal = verifyPhaseRefusal(cmd);
75
- if (refusal === null) process.exit(0);
89
+ if (refusal !== null) {
90
+ const wf = findActiveWorkflow();
91
+ if (wf && wf.data.phase === 'VERIFY') {
92
+ console.log(JSON.stringify({ decision: "block", reason: refusal }));
93
+ process.exit(0);
94
+ }
95
+ }
76
96
 
77
- const wf = findActiveWorkflow();
78
- if (!wf || wf.data.phase !== 'VERIFY') process.exit(0);
97
+ // ── 2. the finding adjudication (#1261) ──
98
+ //
99
+ // Every phase, and not only VERIFY: #1261's measurement is that filing is
100
+ // unadjudicated generally — open issues sat flat at 32 across three
101
+ // readings while 8 closed and 8 were filed — so a gate that only runs
102
+ // inside one phase would leave the intake rate untouched.
103
+ const gate = await filingGate(cmd, { projectRoot: process.cwd() });
104
+ const unrecorded = gate.rows.filter(row => !recordAdjudication(row)).length;
79
105
 
80
- console.log(JSON.stringify({ decision: "block", reason: refusal }));
106
+ if (gate.refusal !== null) {
107
+ console.log(JSON.stringify({ decision: "block", reason: gate.refusal }));
108
+ process.exit(0);
109
+ }
110
+ // systemMessage and not stderr: stderr from a hook that exits 0 is not
111
+ // shown. An UNMEASURED nobody sees is a silent pass, which is the one thing
112
+ // lib/issue-filing-gate.ts's header says this must not become.
113
+ const notes = [
114
+ gate.note,
115
+ unrecorded > 0
116
+ ? `[FindingArbiter] ${unrecorded} adjudication(s) could not be written to ${ledgerPath()}, ` +
117
+ `so this filing is not in the population that prices the gate.`
118
+ : null,
119
+ ].filter((n): n is string => n !== null);
120
+ if (notes.length > 0) console.log(JSON.stringify({ systemMessage: notes.join("\n\n") }));
81
121
  process.exit(0);
82
122
  }
83
123
 
@@ -0,0 +1,462 @@
1
+ /**
2
+ * Bounding review rounds on an open pull request (#1168).
3
+ *
4
+ * `lib/security-verdict.ts` already decides all of this for rook inside a
5
+ * ship run: `reReviewDecision` caps rounds and fails closed on an unreadable
6
+ * budget, `reReviewScope` works out that a stale FAIL and a stale PASS need
7
+ * different re-review scopes, and `reviewIsCurrent` clears a finding when a
8
+ * later commit replaced the code it was about. None of it is reachable from
9
+ * CI, because it governs a ship run and the swarm bypasses ship.js.
10
+ *
11
+ * **This module does not reimplement any of it.** Every decision below
12
+ * delegates to that file. What is added here is the part that file has no
13
+ * opinion about: where a round NUMBER comes from on a pull request, and what
14
+ * the reviewer should be told once the budget is spent.
15
+ *
16
+ * ## The measurement this was built from
17
+ *
18
+ * Anthropic report that `git blame` over what their reviewer kept flagging on
19
+ * later rounds showed ~59% of it was code already present at the first pass —
20
+ * the reviewer was finding a few more OLD bugs each round, not new ones.
21
+ *
22
+ * Measured here on 2026-10-22 over all 524 `AI Review` runs this repository
23
+ * has ever had: the findings adjudicator has only existed since #1013, so the
24
+ * whole population of blocking findings is 8, across 6 branches, and exactly
25
+ * **2** of them are round-2-or-later. Both cite a line that was present at
26
+ * round 1:
27
+ *
28
+ * * `rg/1175`, round 2 flagged `lib/bash-write-guard.ts:375`
29
+ * (`LINK_CREATION`). The byte-identical line was at `:318` at round 1.
30
+ * * `fix/1129`, round 2 flagged `lib/launch-base.ts:184`
31
+ * (`canonical === given`). `git diff` between the two reviewed commits
32
+ * reports the file UNCHANGED.
33
+ *
34
+ * 2 of 2 is 100% on a denominator of 2. It is consistent with their 59% and
35
+ * it is not a replication of it, and this module does not claim one.
36
+ *
37
+ * ## What that measurement changed in the design
38
+ *
39
+ * **A finding fingerprint may not be keyed on a line number.** The first case
40
+ * above moved 318 → 375 between rounds while staying byte-identical, so a
41
+ * `file:line` key would have failed to suppress the one repeat we can
42
+ * actually observe. `findingKey` therefore keys on the file, the normalised
43
+ * TEXT of the cited line, and the normalised summary.
44
+ *
45
+ * **`git blame` is the wrong instrument for this question.** It attributed
46
+ * the first case to a commit that is not an ancestor of the round-1 head (the
47
+ * branch was rebased between rounds) and the second to the round-2 commit
48
+ * itself (the round-2 commit is an amend of the round-1 one). Blame would
49
+ * have scored BOTH of our stale findings as fresh. Content presence is the
50
+ * reading; authorship is not.
51
+ *
52
+ * ## Why diff-scoping a later round is not safe on its own
53
+ *
54
+ * Anthropic ship diff-only re-review after the first few passes. Applied
55
+ * directly here that is `46034035` — the `fail-open-security-gate` this
56
+ * repository found and reverted — because a diff against the flagged commit
57
+ * does not contain the flagged code, so a later round that reads only the
58
+ * diff says nothing about a finding raised earlier. Theirs is safe because
59
+ * their findings are inline comments that PERSIST on the pull request and
60
+ * block merge until they are answered; ours is a check-run annotation that
61
+ * the next run replaces wholesale, so a finding not re-raised simply
62
+ * disappears and the check goes green.
63
+ *
64
+ * So `reviewScopeForRound` delegates to `reReviewScope`, which refuses to
65
+ * diff-scope anything but a held PASS, and `carryForward` is what makes a
66
+ * diff-scoped round honest: the unresolved earlier findings are re-emitted by
67
+ * the ADJUDICATOR rather than re-discovered by the reviewer.
68
+ */
69
+
70
+ import {
71
+ RE_REVIEW,
72
+ REVIEW_CURRENT,
73
+ REVIEW_SCOPE_DIFF,
74
+ REVIEW_SCOPE_FULL,
75
+ SECURITY_REREVIEW_EXHAUSTED,
76
+ reReviewDecision,
77
+ reReviewScope,
78
+ type ReviewScope,
79
+ } from "./security-verdict.ts";
80
+
81
+ export { REVIEW_SCOPE_DIFF, REVIEW_SCOPE_FULL, type ReviewScope };
82
+
83
+ /**
84
+ * How many review rounds a pull request gets before the reviewer is told to
85
+ * stop listing defects and assess the approach instead.
86
+ *
87
+ * Three, which is the number Anthropic shipped. Re-derived against this
88
+ * repository rather than adopted: over 294 merged pull requests that had an
89
+ * `AI Review` run, 22 (7.5%) went past three rounds, 13 (4.4%) reached five
90
+ * or more, and the mean was 1.738. So a cap of three leaves 92.5% of pull
91
+ * requests untouched and still reaches every run that has actually gone long.
92
+ */
93
+ export const AI_REVIEW_ROUND_CAP = 3;
94
+
95
+ /**
96
+ * The round from which a re-review may be scoped to the diff.
97
+ *
98
+ * Anthropic's "after the first few passes". Here it is the round AFTER the
99
+ * first, and it is a floor rather than the decision: `reviewScopeForRound`
100
+ * still refuses to diff-scope a round whose held verdict is not a PASS, which
101
+ * is `reReviewScope`'s rule and the whole of #244.
102
+ */
103
+ export const AI_REVIEW_DIFF_SCOPE_FROM_ROUND = 3;
104
+
105
+ /**
106
+ * The round budget could not be read, so this job does not know which round
107
+ * it is on.
108
+ *
109
+ * DECLARED ONCE, as an exported constant, for the reason
110
+ * `SECURITY_REREVIEW_EXHAUSTED` is: a second spelling is a second refusal
111
+ * path, reachable by code the first one's tests never visit.
112
+ *
113
+ * This is a REFUSAL and not a warning, and the reasoning is
114
+ * `reReviewDecision`'s own — a budget nobody can read is not a budget with
115
+ * room left in it. The specific fail-open it closes: an unreadable counter
116
+ * makes round 12 indistinguishable from round 1, and reading it as round 1
117
+ * resets the bound on every run, which is a cap that can never be reached.
118
+ */
119
+ export const AI_REVIEW_ROUNDS_UNMEASURED = "AI_REVIEW_ROUNDS_UNMEASURED";
120
+
121
+ /** The review is within budget and reviews normally. */
122
+ export const AI_REVIEW_ROUND_OPEN = "AI_REVIEW_ROUND_OPEN";
123
+ /**
124
+ * The budget is spent. The reviewer still speaks — see `atCapInstruction` —
125
+ * it just stops enumerating defects and says something about the approach.
126
+ */
127
+ export const AI_REVIEW_ROUND_AT_CAP = "AI_REVIEW_ROUND_AT_CAP";
128
+
129
+ export type RoundDecision =
130
+ | typeof AI_REVIEW_ROUND_OPEN
131
+ | typeof AI_REVIEW_ROUND_AT_CAP
132
+ | typeof AI_REVIEW_ROUNDS_UNMEASURED;
133
+
134
+ export interface RoundOutcome {
135
+ /** Exactly one of the three verdicts above. */
136
+ decision: RoundDecision;
137
+ /** The round this run is, or null when it could not be read. */
138
+ round: number | null;
139
+ /** Why the run is not in the ordinary state. Null — and only null — when it is. */
140
+ reason: string | null;
141
+ }
142
+
143
+ /**
144
+ * A round number as it arrives from the workflow: a decimal string on stdout,
145
+ * or nothing.
146
+ *
147
+ * FAILS CLOSED. Anything that is not a positive decimal integer is null, and
148
+ * null is the refusal above. `Number()` is not used: it reads `""` as 0,
149
+ * `" 2 "` as 2 and `0x3` as 3, and a counter that accepts three spellings of
150
+ * a number accepts inputs nobody has decided about.
151
+ *
152
+ * Zero is refused along with the rest. A run that is happening is at least
153
+ * round 1, so a counter reporting 0 has not counted this run — which is a
154
+ * different defect from an unreadable one and not one to paper over by
155
+ * adding one to it.
156
+ */
157
+ export function readRoundNumber(v: unknown): number | null {
158
+ if (typeof v === "number") {
159
+ return Number.isInteger(v) && v >= 1 ? v : null;
160
+ }
161
+ if (typeof v !== "string") return null;
162
+ const trimmed = v.trim();
163
+ if (!/^[0-9]+$/.test(trimmed)) return null;
164
+ const n = Number.parseInt(trimmed, 10);
165
+ return Number.isSafeInteger(n) && n >= 1 ? n : null;
166
+ }
167
+
168
+ /**
169
+ * Which state is this round in?
170
+ *
171
+ * The cap arithmetic is NOT done here. It is handed to `reReviewDecision`,
172
+ * which already answers "is there a round left in this budget" and already
173
+ * fails closed on an unreadable one — so the two cannot be changed apart, and
174
+ * a mutation of its `spent < cap` is observable through this function. The
175
+ * currency argument is the stale shape on purpose: a run that is reviewing is
176
+ * by definition reviewing something a previous round did not clear, so the
177
+ * only question left for that function is the budget one.
178
+ *
179
+ * `roundsSpent` is `round - 1` — the rounds that are already over. At round
180
+ * 4 with a cap of 3 that is 3 of 3 and the budget is gone, which is what
181
+ * makes round 4 the first capped round and rounds 1-3 the three the author
182
+ * gets.
183
+ */
184
+ export function roundOutcome(raw: unknown, cap: unknown = AI_REVIEW_ROUND_CAP): RoundOutcome {
185
+ const round = readRoundNumber(raw);
186
+ if (round === null) {
187
+ return {
188
+ decision: AI_REVIEW_ROUNDS_UNMEASURED,
189
+ round: null,
190
+ reason:
191
+ `the review-round counter read ${describe(raw)}, which is not a round number — ` +
192
+ `this job cannot tell a first review from a twelfth, so the round budget is ` +
193
+ `unreadable and refusing is the only reading that is not a guess`,
194
+ };
195
+ }
196
+
197
+ const stale = {
198
+ current: false,
199
+ reason: `this is review round ${round} on this pull request`,
200
+ };
201
+ const outcome = reReviewDecision(stale, round - 1, cap);
202
+
203
+ if (outcome.decision === RE_REVIEW) {
204
+ return { decision: AI_REVIEW_ROUND_OPEN, round, reason: null };
205
+ }
206
+ // REVIEW_CURRENT cannot be reached: the currency handed in is always stale.
207
+ // Checked anyway rather than folded into the exhaustion branch, because the
208
+ // two mean opposite things and a later change to the currency above would
209
+ // otherwise report "nothing to review" as "out of rounds".
210
+ if (outcome.decision === REVIEW_CURRENT) {
211
+ return { decision: AI_REVIEW_ROUND_OPEN, round, reason: null };
212
+ }
213
+ return {
214
+ decision: AI_REVIEW_ROUND_AT_CAP,
215
+ round,
216
+ reason: outcome.reason,
217
+ };
218
+ }
219
+
220
+ /**
221
+ * The scope the reviewer should read on this round.
222
+ *
223
+ * Two gates, and BOTH must open. The round floor is Anthropic's "after the
224
+ * first few passes"; `reReviewScope` is #244's refusal to diff-scope anything
225
+ * but a held PASS. The second is the one that matters, and it is delegated
226
+ * rather than restated: a diff against the flagged commit does not contain
227
+ * the flagged code.
228
+ *
229
+ * FAILS CLOSED TOWARD READING MORE, in both halves. An unreadable round is a
230
+ * full review, not a skipped one.
231
+ */
232
+ export function reviewScopeForRound(rawRound: unknown, heldVerdict: unknown): ReviewScope {
233
+ const round = readRoundNumber(rawRound);
234
+ if (round === null || round < AI_REVIEW_DIFF_SCOPE_FROM_ROUND) return REVIEW_SCOPE_FULL;
235
+ return reReviewScope(heldVerdict);
236
+ }
237
+
238
+ /** A finding as the payload contract spells it (`AI_REVIEW_FINDING_FIELDS`). */
239
+ export interface ReviewFinding {
240
+ severity?: unknown;
241
+ file?: unknown;
242
+ line?: unknown;
243
+ summary?: unknown;
244
+ failure_scenario?: unknown;
245
+ [k: string]: unknown;
246
+ }
247
+
248
+ /**
249
+ * Collapse the incidental differences between two spellings of one sentence.
250
+ *
251
+ * Case and whitespace only. Not punctuation, and not stemming: two findings
252
+ * that differ in a word are two findings, and a key that erases the
253
+ * difference suppresses a real one.
254
+ */
255
+ function normalise(v: unknown): string {
256
+ return typeof v === "string" ? v.trim().toLowerCase().replace(/\s+/g, " ") : "";
257
+ }
258
+
259
+ /**
260
+ * The identity of a finding, for deciding whether it has already been raised.
261
+ *
262
+ * `file` + the TEXT of the cited line + `summary`. **Not the line number**,
263
+ * and that is the measured part rather than a preference: the one repeat this
264
+ * repository can actually show moved from `:318` to `:375` between rounds
265
+ * while staying byte-identical, so a `file:line` key would have let it
266
+ * through. See this module's header.
267
+ *
268
+ * `lineText` is the content at the cited line, supplied by the caller because
269
+ * only the caller has the checkout. Absent or empty, the key falls back to
270
+ * the line NUMBER — which is weaker, and is the honest answer when the line
271
+ * cannot be read: a key that pretends to content it never saw would suppress
272
+ * on a collision of empty strings, and that suppresses everything.
273
+ *
274
+ * Returns null for a finding with no `file` and no `summary`. There is
275
+ * nothing to compare such a finding against, and giving it a key would make
276
+ * every one of them a repeat of the first.
277
+ */
278
+ export function findingKey(finding: unknown, lineText?: unknown): string | null {
279
+ if (typeof finding !== "object" || finding === null || Array.isArray(finding)) return null;
280
+ const f = finding as ReviewFinding;
281
+ const file = normalise(f.file);
282
+ const summary = normalise(f.summary);
283
+ if (!file && !summary) return null;
284
+ const text = normalise(lineText);
285
+ const anchor = text !== ""
286
+ ? `t:${text}`
287
+ : `n:${typeof f.line === "number" && Number.isInteger(f.line) ? f.line : ""}`;
288
+ return `${file}\u0000${anchor}\u0000${summary}`;
289
+ }
290
+
291
+ export interface SuppressionReading {
292
+ /** Findings this round may report. */
293
+ kept: ReviewFinding[];
294
+ /** Findings dropped because an earlier round already raised them. */
295
+ suppressed: ReviewFinding[];
296
+ /** One line per suppressed finding, for the annotation. */
297
+ reasons: string[];
298
+ }
299
+
300
+ /**
301
+ * Drop findings an earlier round already raised.
302
+ *
303
+ * Keyed by `findingKey`, so a finding whose line number moved is still a
304
+ * repeat and a finding whose summary changed is not.
305
+ *
306
+ * **Within this round too.** A reviewer that lists the same defect twice in
307
+ * one payload is the same waste as one that lists it on two rounds, and the
308
+ * first occurrence is kept. An unkeyable finding (no file, no summary) is
309
+ * always kept: it cannot be shown to be a repeat, and the direction this is
310
+ * allowed to be wrong in is toward reporting.
311
+ *
312
+ * `priorKeys` is what earlier rounds raised. It is a parameter rather than
313
+ * something read here, because only the caller can reach the pull request's
314
+ * history, and a function that fetches its own evidence cannot be given a
315
+ * negative control.
316
+ */
317
+ export function suppressRepeats(
318
+ fresh: unknown,
319
+ priorKeys: Iterable<string>,
320
+ lineTextFor?: (f: ReviewFinding) => string | undefined,
321
+ ): SuppressionReading {
322
+ const seen = new Set<string>(priorKeys);
323
+ const kept: ReviewFinding[] = [];
324
+ const suppressed: ReviewFinding[] = [];
325
+ const reasons: string[] = [];
326
+ const list = Array.isArray(fresh) ? fresh : [];
327
+
328
+ for (const raw of list) {
329
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
330
+ kept.push(raw as ReviewFinding);
331
+ continue;
332
+ }
333
+ const f = raw as ReviewFinding;
334
+ const key = findingKey(f, lineTextFor?.(f));
335
+ if (key === null || !seen.has(key)) {
336
+ if (key !== null) seen.add(key);
337
+ kept.push(f);
338
+ continue;
339
+ }
340
+ suppressed.push(f);
341
+ reasons.push(
342
+ `${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
343
+ `raised on an earlier round of this pull request, so it is not raised again`,
344
+ );
345
+ }
346
+
347
+ return { kept, suppressed, reasons };
348
+ }
349
+
350
+ /**
351
+ * Which of an earlier round's findings are still unresolved at this commit?
352
+ *
353
+ * This is what makes a diff-scoped round honest. A diff-scoped reviewer never
354
+ * reads the code an earlier finding was about, so if the adjudicator does not
355
+ * re-emit the unresolved ones the finding vanishes and the check goes green —
356
+ * `46034035` arriving by a different door.
357
+ *
358
+ * A finding is RESOLVED when the line it names is no longer the line it named:
359
+ * `currentLineText` differs from the text recorded with the finding. It is
360
+ * UNRESOLVED when the text is unchanged. When the text cannot be read at all
361
+ * it is UNRESOLVED, because a finding nobody could check is not a finding
362
+ * anybody cleared — the direction `reviewIsCurrent` also fails in.
363
+ *
364
+ * **It is a CONTENT comparison and not `reviewIsCurrent`, deliberately.**
365
+ * That function compares two commit SHAs, which is the right reading for "is
366
+ * this whole review still about this branch" and the wrong one for "is this
367
+ * one finding still true". Measured on this repository's own two multi-round
368
+ * cases: on `rg/1175` the branch was rebased between rounds, so the commit
369
+ * that introduced the flagged line is not an ancestor of the round-1 head
370
+ * even though the line is byte-identical in it; on `fix/1129` the round-2
371
+ * commit is an amend of the round-1 one, so blame attributes a line to it
372
+ * that it did not touch. Both findings were stale and a SHA or ancestry
373
+ * reading calls both of them fresh. Content is the only reading that was
374
+ * right on both.
375
+ */
376
+ export interface CarriedFinding {
377
+ finding: ReviewFinding;
378
+ /** The text at the cited line when the finding was raised. */
379
+ recordedText?: string;
380
+ }
381
+
382
+ export function carryForward(
383
+ prior: readonly CarriedFinding[],
384
+ currentLineText: (f: ReviewFinding) => string | undefined,
385
+ ): ReviewFinding[] {
386
+ const out: ReviewFinding[] = [];
387
+ for (const entry of prior) {
388
+ const now = currentLineText(entry.finding);
389
+ if (typeof now !== "string") {
390
+ out.push(entry.finding);
391
+ continue;
392
+ }
393
+ if (normalise(now) !== normalise(entry.recordedText)) continue;
394
+ out.push(entry.finding);
395
+ }
396
+ return out;
397
+ }
398
+
399
+ /**
400
+ * What the reviewer is told once the budget is spent.
401
+ *
402
+ * **A cap is not a silencer.** A reviewer that goes quiet at round 4 has
403
+ * handed the author a green check on a pull request three reviews have failed
404
+ * to settle, which is the outcome the cap exists to prevent, not the one it
405
+ * is for. So the reviewer still runs and still writes a payload; what changes
406
+ * is the question it is answering.
407
+ *
408
+ * Emitted at a NON-blocking severity by contract — the text says so — because
409
+ * "this approach is not converging" is not a defect at a line and the payload
410
+ * contract refuses a blocking finding that cannot name one. The round that
411
+ * blocks is the one that found the bug; this one is advice.
412
+ */
413
+ export function atCapInstruction(round: number, cap: number = AI_REVIEW_ROUND_CAP): string {
414
+ return (
415
+ `THIS IS REVIEW ROUND ${round}. This pull request has already had ${cap} rounds of ` +
416
+ `review and has not settled, so do not spend this round listing more defects.\n` +
417
+ `\n` +
418
+ `Step back and say something about the APPROACH instead. Three rounds that each ` +
419
+ `found something is evidence about the change, not about the reviewer: the usual ` +
420
+ `causes are a change that is doing more than one thing, a defect class being fixed ` +
421
+ `one line at a time, or a design that makes the defect easy to reintroduce. Say ` +
422
+ `which of those you think this is and what you would do instead.\n` +
423
+ `\n` +
424
+ `Write ONE finding, at a non-blocking severity, whose summary is that assessment. ` +
425
+ `Do not raise it to a blocking severity: the budget being spent is not itself a ` +
426
+ `defect at a line, and a blocking finding that cannot name one makes the whole ` +
427
+ `review unreadable. Stay silent and the author gets a green check on a pull ` +
428
+ `request three reviews could not settle, which is worse than either.`
429
+ );
430
+ }
431
+
432
+ /**
433
+ * The block appended to the prompt listing what has already been said.
434
+ *
435
+ * Handed to the reviewer as well as enforced by the adjudicator, and both on
436
+ * purpose: the instruction saves the round, and the adjudicator makes the
437
+ * saving checkable. An instruction nobody enforces is a request.
438
+ */
439
+ export function noRepeatsInstruction(priorSummaries: readonly string[]): string {
440
+ if (priorSummaries.length === 0) return "";
441
+ const list = priorSummaries.map(s => ` - ${s}`).join("\n");
442
+ return (
443
+ `ALREADY RAISED ON AN EARLIER ROUND OF THIS PULL REQUEST. Do not report any of ` +
444
+ `these again, at any severity, however you would word it:\n` +
445
+ `${list}\n` +
446
+ `\n` +
447
+ `A later step drops a finding that matches one of these on the file, the text of ` +
448
+ `the cited line and the summary — it does NOT match on the line number, so moving ` +
449
+ `the same defect to a new line does not make it a new finding. Report what is new ` +
450
+ `on this round, or report nothing.`
451
+ );
452
+ }
453
+
454
+ function describe(v: unknown): string {
455
+ if (v === undefined) return "nothing";
456
+ if (v === null) return "null";
457
+ if (Array.isArray(v)) return `an array of ${v.length}`;
458
+ if (typeof v === "object") return "an object";
459
+ return JSON.stringify(v);
460
+ }
461
+
462
+ export { SECURITY_REREVIEW_EXHAUSTED };
@@ -19,6 +19,8 @@
19
19
  */
20
20
 
21
21
  /** Commands that read files when given an operand. */
22
+ import { isInterpreterWord } from './interpreters';
23
+
22
24
  const FILE_READERS = new Set(['cat', 'head', 'tail']);
23
25
 
24
26
  /** Flags that consume the following token as their value (`head -n 20 f`). */
@@ -131,8 +133,20 @@ function splitSegments(command: string): string[] {
131
133
  return segments;
132
134
  }
133
135
 
134
- /** Shell interpreters that execute a heredoc body as commands. */
135
- const INTERPRETERS = /(^|[\s;&|])(ba|z|k|da)?sh\s*$/;
136
+ /**
137
+ * Does the text before a `<<` end in an interpreter, which will EXECUTE the
138
+ * body rather than read it as a document?
139
+ *
140
+ * #1240: this used to be a local regex matching shells only, so a
141
+ * `python3 <<'PY'` body read as a document here while the write guard could
142
+ * not see it at all. The name list now comes from `lib/interpreters.ts`,
143
+ * which is the one binding both modules read — the write guard's list was
144
+ * the wider and more correct of the two.
145
+ */
146
+ function feedsInterpreter(prefix: string): boolean {
147
+ const last = prefix.trim().split(/[\s;&|]+/).pop() ?? '';
148
+ return isInterpreterWord(last);
149
+ }
136
150
 
137
151
  /**
138
152
  * Remove heredoc bodies before scanning.
@@ -159,7 +173,7 @@ function stripHeredocBodies(command: string): string {
159
173
  }
160
174
 
161
175
  const m = line.match(/<<(-?)\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\2/);
162
- if (m && !INTERPRETERS.test(line.slice(0, m.index))) {
176
+ if (m && !feedsInterpreter(line.slice(0, m.index))) {
163
177
  allowIndent = m[1] === '-';
164
178
  delim = m[3];
165
179
  out.push(line.slice(0, m.index) + line.slice(m.index! + m[0].length));