rungate 0.8.7 → 0.8.8

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.
@@ -43,12 +43,22 @@
43
43
  *
44
44
  * ## Scope, stated rather than implied
45
45
  *
46
- * No YAML parser. This repo ships four runtime dependencies and a guard is not
47
- * a reason to add a fifth to a published package — the same decision
48
- * `test/claude-review-no-key.test.ts` records. Everything here is a cut and a
49
- * regex over the cut, and every cut refuses by name when it cannot find its
50
- * region, because a slice that missed its section is an empty string and an
51
- * empty string satisfies every claim of the form "X is not in here".
46
+ * No ADDED dependency. This repo ships four runtime dependencies and a guard
47
+ * is not a reason to add a fifth to a published package — the same decision
48
+ * `test/claude-review-no-key.test.ts` records.
49
+ *
50
+ * That rule is about the dependency list, not about parsing, and this
51
+ * paragraph used to say "no YAML parser" as though the two were the same
52
+ * thing. They are not: `triggerNames` parses the workflow with `Bun.YAML`,
53
+ * which is built into the runtime and adds nothing to `package.json`. Six
54
+ * revisions of hand-rolled trigger matching shipped two fail-open holes
55
+ * before that distinction was drawn (#1614), so it is drawn here explicitly
56
+ * — if a real parser is reachable without a dependency, use it.
57
+ *
58
+ * Everything else here is a cut and a regex over the cut, and every cut
59
+ * refuses by name when it cannot find its region, because a slice that
60
+ * missed its section is an empty string and an empty string satisfies every
61
+ * claim of the form "X is not in here".
52
62
  */
53
63
 
54
64
  import { structuralCut } from "./source-slice";
@@ -60,6 +70,9 @@ export type ReviewToolViolationKind =
60
70
  | "PROMPT_NAMES_A_DENIED_TOOL"
61
71
  | "PROMPT_NAMES_AN_UNGRANTED_TOOL"
62
72
  | "ALLOWED_TOOL_CANNOT_EXIST_ON_THIS_TRIGGER"
73
+ | "ENTITY_TRIGGER_WITHOUT_A_FORK_GUARD"
74
+ | "PULL_REQUEST_TARGET_TRIGGER"
75
+ | "TRIGGERS_UNMEASURED"
63
76
  | "NO_POSTING_TOOL_IS_ALLOWED"
64
77
  | "NO_SUBJECT_REACHES_THE_AGENT"
65
78
  | "MUTABLE_PLUGIN_MARKETPLACE"
@@ -100,6 +113,226 @@ export const AUTOMATION_ONLY_TRIGGERS = [
100
113
  "workflow_run",
101
114
  ] as const;
102
115
 
116
+ /**
117
+ * Triggers that fire on somebody else's pull request, so the job sees a diff
118
+ * written by a person who is not a collaborator (#631/#675).
119
+ *
120
+ * `pull_request_target` is here as a trigger to REFUSE, not one to guard. It
121
+ * runs the base branch's workflow definition with a full write token against
122
+ * the fork's code, which is this workflow's egress sink with the credential
123
+ * handed over on purpose. There is no condition that makes it safe for a job
124
+ * that runs an agent, so it gets its own violation rather than a guard.
125
+ */
126
+ export const ENTITY_TRIGGERS = ["pull_request", "pull_request_target"] as const;
127
+
128
+ /**
129
+ * The trigger names a workflow declares, parsed as YAML.
130
+ *
131
+ * **This was hand-rolled text matching and it should not have been.** Six
132
+ * revisions on #1614, each correct for the case it was shown and wrong for
133
+ * the next one, and the reviewer's round-cap assessment on round 13 named
134
+ * the class rather than the instance: *hand-rolled regex parsing of the
135
+ * `on:` block, patched edge case by edge case*. It was right, so the
136
+ * instrument changed instead of the pattern. What the six revisions cost:
137
+ *
138
+ * two-space-only every other spelling read as `[]`, which made the
139
+ * callers SILENT. `on: {pull_request_target: }` passed
140
+ * — a WRITE token on a fork's pull request
141
+ * any-indentation any indentation is any DEPTH, so every field of the
142
+ * `workflow_dispatch.inputs` schema read as a trigger
143
+ * outermost-depth correct for block and flow style, and still blind to
144
+ * a YAML merge key, a list form and a scalar form
145
+ *
146
+ * `Bun.YAML` is built in, so this costs no dependency, and it answers all
147
+ * three plus the forms nobody had thought to ask about:
148
+ *
149
+ * on: {pull_request_target: } flow
150
+ * on:\n pull_request_target: four-space
151
+ * on:\n <<: *anchor merge key, resolved
152
+ * on: [push, pull_request_target] list
153
+ * on: pull_request_target scalar
154
+ *
155
+ * The refusal stays and is still load-bearing: a source that will not parse,
156
+ * or declares no `on`, yields `[]` and the caller reports
157
+ * `TRIGGERS_UNMEASURED`. A reading that could not be taken is never a clean
158
+ * one — and that is now the ONLY way this returns empty, because the parser
159
+ * no longer has spellings it cannot see.
160
+ */
161
+ export function triggerNames(source: string): string[] {
162
+ let doc: unknown;
163
+ try {
164
+ doc = (Bun as unknown as { YAML: { parse(s: string): unknown } }).YAML.parse(source);
165
+ } catch {
166
+ // A workflow that is not YAML has no readable triggers. UNMEASURED, and
167
+ // never a silent pass — the caller turns `[]` into a reported refusal.
168
+ return [];
169
+ }
170
+ if (doc === null || typeof doc !== "object") return [];
171
+ // YAML 1.1 resolves a bare `on` to the boolean true, and parsers differ on
172
+ // whether the key survives as "on" or "true". Read both rather than
173
+ // depending on which one this runtime picked.
174
+ const rec = doc as Record<string, unknown>;
175
+ const on = rec.on ?? rec["true"];
176
+ if (typeof on === "string") return [on];
177
+ if (Array.isArray(on)) return on.filter((t): t is string => typeof t === "string");
178
+ if (on !== null && typeof on === "object") return Object.keys(on as object);
179
+ return [];
180
+ }
181
+
182
+ /**
183
+ * The two expressions a job-level condition needs to compare before it can be
184
+ * said to refuse a fork. Spelled out so the check names what is missing rather
185
+ * than reporting that an `if:` "looks wrong".
186
+ */
187
+ export const FORK_GUARD_TERMS = [
188
+ "github.event.pull_request.head.repo.full_name",
189
+ "github.repository",
190
+ ] as const;
191
+
192
+ /**
193
+ * The comparison itself, in either operand order, with `==` and not `!=`.
194
+ *
195
+ * An earlier revision of this check asked only whether both `FORK_GUARD_TERMS`
196
+ * appeared anywhere in the job header, and said so in a comment: "this cannot
197
+ * tell `==` from `!=`". **The reviewer this module exists to make work caught
198
+ * that on the pull request that promoted the trigger**, and it was right —
199
+ * `.claude/rules/checks-must-be-able-to-fail.md`, fifth shape. An inverted
200
+ * guard contains both terms, passes a presence check, and runs the job on
201
+ * forks ONLY, which is the precise opposite of the property the check is
202
+ * named after. A check satisfied by a dangerously backwards version of its
203
+ * own subject is worse than no check: it certifies the regression.
204
+ *
205
+ * It is also read from the `if:` block rather than the whole job header, for
206
+ * the same reason every other cut here is bounded — a `name:` or an `env:`
207
+ * value carrying both substrings would otherwise satisfy it.
208
+ */
209
+ export const FORK_GUARD_COMPARISON =
210
+ /^(?:github\.event\.pull_request\.head\.repo\.full_name\s*==\s*github\.repository|github\.repository\s*==\s*github\.event\.pull_request\.head\.repo\.full_name)$/;
211
+
212
+ /**
213
+ * The only other thing a disjunct of this condition is allowed to be: a guard
214
+ * naming the event, which is how the dispatch arm earns its place beside the
215
+ * fork comparison.
216
+ */
217
+ export const FORK_GUARD_COMPANION_EVENTS = ["workflow_dispatch", "schedule"] as const;
218
+
219
+ /**
220
+ * And the event it names must be one that CANNOT carry a fork's head.
221
+ *
222
+ * The first spelling of this was `'[a-z_]+'` — any event at all — and the
223
+ * reviewer caught it, the third real finding about this one guard:
224
+ *
225
+ * if: >-
226
+ * github.event_name == 'pull_request' ||
227
+ * github.event.pull_request.head.repo.full_name == github.repository
228
+ *
229
+ * On a fork's pull request the FIRST arm is true, so the job runs and the
230
+ * comparison beside it decides nothing. That is the bypass `forkGuardDefect`
231
+ * was written to close, reopened by the escape hatch added to let the live
232
+ * file's dispatch arm through.
233
+ *
234
+ * `FORK_GUARD_COMPANION_EVENTS` is the closed set, and the membership test is
235
+ * what the event has in common: no `github.event.pull_request` context at
236
+ * all, so the fork comparison cannot be the predicate for it and a separate
237
+ * arm is the only way to express the case. `pull_request` and
238
+ * `pull_request_target` are excluded by construction rather than by being
239
+ * listed as denied — an allowlist cannot be widened by forgetting a denial.
240
+ */
241
+ export const FORK_GUARD_COMPANION_ARM = new RegExp(
242
+ `^github\\.event_name\\s*==\\s*'(?:${FORK_GUARD_COMPANION_EVENTS.join("|")})'$`,
243
+ );
244
+
245
+ /**
246
+ * Why an ANCHORED per-disjunct test and not a substring search.
247
+ *
248
+ * The previous revision of this check asked whether `FORK_GUARD_COMPARISON`
249
+ * matched anywhere in the condition. **The reviewer caught that too** — the
250
+ * second time on the same pull request, and the same shape as the `!=`
251
+ * inversion it had already caught once. A substring search is satisfied by a
252
+ * condition that contains the correct comparison and then neutralises it:
253
+ *
254
+ * if: >-
255
+ * true ||
256
+ * github.event.pull_request.head.repo.full_name == github.repository
257
+ *
258
+ * if: >-
259
+ * !(github.event.pull_request.head.repo.full_name == github.repository)
260
+ *
261
+ * Both contain `A == B`. The first runs on every fork; the second runs on
262
+ * forks ONLY. So the fix is not a better regex for the comparison — it is
263
+ * asking a different question: **is that comparison the governing predicate?**
264
+ *
265
+ * The condition is split on `||` and every arm must be either the fork
266
+ * comparison itself or `FORK_GUARD_COMPANION_ARM`. `true`, `always()` and a
267
+ * parenthesised negation are all arms that match neither, so each is named
268
+ * rather than tolerated.
269
+ *
270
+ * **Both patterns are anchored, so each accepts exactly ONE spelling of its
271
+ * arm and refuses every equivalent rewrite.** Say what is tolerated rather
272
+ * than listing what is not, because the list of rewrites is open and the
273
+ * tolerance is closed. Measured, not inferred:
274
+ *
275
+ * clean github.event_name == 'workflow_dispatch' || <fork comparison>
276
+ * clean extra inner whitespace around either `==`
277
+ * clean the fork comparison with its operands reversed
278
+ * FLAGGED (github.event_name == 'workflow_dispatch') || (<fork comparison>)
279
+ * FLAGGED github.event_name == "workflow_dispatch" || <fork comparison>
280
+ * FLAGGED github.event_name == 'workflow_dispatch' && github.actor == 'x'
281
+ *
282
+ * Whitespace and operand order are the whole of the tolerance. A
283
+ * parenthesised arm, a double-quoted event name and a narrowing `&&` are all
284
+ * refused, and all three are SAFE conditions — the `&&` one runs on a strict
285
+ * subset of what the bare arm runs on. So these are false positives, never
286
+ * bypasses: the direction `.claude/rules/checks-must-be-able-to-fail.md`
287
+ * says to be wrong in. The cost is a confusing refusal for somebody writing
288
+ * a legitimate variant; the cost of the other direction is deciding whether
289
+ * an arbitrary rewrite narrows or widens, which means evaluating GitHub's
290
+ * expression language, and a guard that reasons about what it cannot
291
+ * evaluate is the substring search this function replaced.
292
+ *
293
+ * AC-26 in `test/claude-review-executable-prompt.test.ts` holds every row of
294
+ * that table. Two successive revisions of this comment got it wrong and
295
+ * nothing contradicted either: the first claimed a narrowing `&&` was
296
+ * tolerated (#1614, round 8), and the fix for that named `&&` alone while
297
+ * parens and double quotes behaved identically (#1614, round 9). The table
298
+ * is stated as a tolerance precisely so the next equivalent spelling nobody
299
+ * has thought of is already covered by it.
300
+ *
301
+ * This is deliberately a CLOSED set. Widening it is how the check dies: the
302
+ * next arm somebody wants is likelier to be the bypass than the exception,
303
+ * and an allowlist that grows on request is a substring search with extra
304
+ * steps.
305
+ */
306
+ export function forkGuardDefect(condition: string): string | null {
307
+ const flat = condition
308
+ .replace(/^\s*if:\s*(?:[>|][-+]?)?/, " ")
309
+ .replace(/\s+/g, " ")
310
+ .trim();
311
+ if (flat === "") return "the job has no `if:` condition at all";
312
+ const arms = flat.split("||").map(a => a.trim());
313
+ if (!arms.some(a => FORK_GUARD_COMPARISON.test(a))) {
314
+ return (
315
+ "the job's condition mentions both terms but no `||` arm of it IS the " +
316
+ "comparison — a comparison wrapped in a negation, or buried inside a " +
317
+ "larger expression, is not the predicate that decides whether the job runs"
318
+ );
319
+ }
320
+ const stray = arms.filter(
321
+ a => !FORK_GUARD_COMPARISON.test(a) && !FORK_GUARD_COMPANION_ARM.test(a),
322
+ );
323
+ if (stray.length > 0) {
324
+ return (
325
+ `the job's condition compares the two terms, but it is one arm of a ` +
326
+ `disjunction whose other arm is ${stray.map(a => `\`${a}\``).join(", ")} — ` +
327
+ `an arm that can be true on a fork makes the comparison beside it decide ` +
328
+ `nothing. The only arm that may sit beside it is ` +
329
+ `\`github.event_name == '<e>'\` for e in ${FORK_GUARD_COMPANION_EVENTS.join(", ")} — ` +
330
+ `events that carry no pull_request context, so the comparison cannot serve them`
331
+ );
332
+ }
333
+ return null;
334
+ }
335
+
103
336
  /**
104
337
  * Tools that can put a human-readable finding on a pull request. The property
105
338
  * AC-4 needs is "a comment naming the defect appears", so this is the set the
@@ -261,11 +494,18 @@ function quotedListAfter(claudeArgs: string, flag: string): string[] | null {
261
494
  */
262
495
  export function reviewWorkflowRegions(source: string): {
263
496
  triggerBlock: string;
497
+ jobHeader: string;
264
498
  reviewStep: string;
265
499
  prompt: string;
266
500
  claudeArgs: string;
267
501
  } {
268
502
  const triggerBlock = structuralCut(source, "\non:", { endAnchor: "\npermissions:" });
503
+ // Everything the job declares ABOUT itself — `runs-on`, `timeout-minutes`,
504
+ // `if:` — and none of what it runs. Cut separately from the steps because a
505
+ // job-level condition is the only place the fork decision for an entity
506
+ // trigger can live, and searching the whole document for it would be
507
+ // satisfied by this file's own header discussing it.
508
+ const jobHeader = structuralCut(source, "\njobs:", { endAnchor: "\n steps:" });
269
509
  const reviewStep = blockUnder(source, "- name: Review");
270
510
 
271
511
  // The prompt is a YAML block scalar: `prompt: |` and everything indented
@@ -279,7 +519,7 @@ export function reviewWorkflowRegions(source: string): {
279
519
 
280
520
  const claudeArgs = blockUnder(reviewStep, "claude_args:");
281
521
 
282
- return { triggerBlock, reviewStep, prompt, claudeArgs };
522
+ return { triggerBlock, jobHeader, reviewStep, prompt, claudeArgs };
283
523
  }
284
524
 
285
525
  /**
@@ -289,7 +529,8 @@ export function reviewWorkflowRegions(source: string): {
289
529
  * cannot accidentally ask the question of the wrong slice.
290
530
  */
291
531
  export function reviewToolAgreement(source: string): ReviewToolViolation[] {
292
- const { triggerBlock, reviewStep, prompt, claudeArgs } = reviewWorkflowRegions(source);
532
+ const { triggerBlock, jobHeader, reviewStep, prompt, claudeArgs } =
533
+ reviewWorkflowRegions(source);
293
534
 
294
535
  const allowed = quotedListAfter(claudeArgs, "allowedTools") ?? [];
295
536
  const denied = quotedListAfter(claudeArgs, "disallowedTools") ?? [];
@@ -335,11 +576,58 @@ export function reviewToolAgreement(source: string): ReviewToolViolation[] {
335
576
 
336
577
  // 3. The door nothing in the prompt can show: a grant whose server the
337
578
  // pinned action never starts under this workflow's triggers.
338
- const triggers = [...triggerBlock.matchAll(/^\s{2}([a-z_]+):/gm)].map(m => m[1]);
339
- const everyTriggerIsAutomation =
340
- triggers.length > 0 &&
341
- triggers.every(t => (AUTOMATION_ONLY_TRIGGERS as readonly string[]).includes(t));
342
- if (everyTriggerIsAutomation) {
579
+ //
580
+ // PER-TRIGGER, not over the intersection. The first revision asked
581
+ // whether EVERY trigger was automation-only, which was the same question
582
+ // while this file had exactly one trigger — and silently became a weaker
583
+ // one when #631/#675 added `pull_request` beside `workflow_dispatch`.
584
+ // **The reviewer caught that too, on the pull request that made the
585
+ // change**: with a mixed trigger set the check went silent, even though
586
+ // a `workflow_dispatch` run of the same job still gets the automation
587
+ // classification and still has no entity-only server. A grant that works
588
+ // on one of two triggers is #732 reintroduced for the other one, and the
589
+ // property degraded from "never exists" to "does not exist on the
590
+ // intersection of all triggers" without the name or the comment moving.
591
+ // HOW THE TRIGGER NAMES ARE READ, and why an empty reading REFUSES
592
+ // (#1614, round 10). The first spelling of this was
593
+ // `/^\s{2}([a-z_]+):/gm` — exactly two leading spaces, block style only.
594
+ // Every other valid YAML spelling of the same trigger set returned `[]`,
595
+ // and `[]` made BOTH checks below silent rather than loud. Measured on
596
+ // the live file with only the `on:` block swapped:
597
+ //
598
+ // on:\n pull_request_target: → ["pull_request_target"], caught
599
+ // on: {pull_request_target: } → [], SILENT
600
+ // on:\n pull_request_target: → [], SILENT
601
+ //
602
+ // A workflow granting a write token on a fork's pull request therefore
603
+ // passed, which is the fail-open shape
604
+ // `.claude/rules/checks-must-be-able-to-fail.md` calls *a detector
605
+ // narrower than what it detects*.
606
+ //
607
+ // Two changes, and the second is the load-bearing one. Widening the
608
+ // pattern closes the spellings we thought of; refusing an EMPTY reading
609
+ // closes the ones we did not. The set of valid YAML spellings is open
610
+ // and the set of things this function can parse is closed, so the only
611
+ // safe thing to do with a block it cannot read is say so — an absent
612
+ // reading is UNMEASURED, never a clean one.
613
+ const triggers = triggerNames(source);
614
+ if (triggers.length === 0) {
615
+ v.push({
616
+ kind: "TRIGGERS_UNMEASURED",
617
+ detail:
618
+ "the `on:` block was found but no trigger name could be read out of it, so the " +
619
+ "pull_request_target and fork-guard checks below have nothing to decide on. That is " +
620
+ "UNMEASURED, not clean: a workflow with no readable triggers is one this check cannot " +
621
+ "speak about. Either the block uses a YAML spelling `triggerNames` does not cover — " +
622
+ "teach it that spelling and add a row to AC-27 — or the workflow genuinely " +
623
+ "declares no triggers, in which case it never runs",
624
+ });
625
+ }
626
+ const automationTriggers = triggers.filter(t =>
627
+ (AUTOMATION_ONLY_TRIGGERS as readonly string[]).includes(t),
628
+ );
629
+ if (automationTriggers.length > 0) {
630
+ const everyTriggerIsAutomation = automationTriggers.length === triggers.length;
343
631
  for (const tool of allowed) {
344
632
  const server = mcpServerOf(tool);
345
633
  const why = server ? ENTITY_ONLY_MCP_SERVERS[server] : undefined;
@@ -348,13 +636,74 @@ export function reviewToolAgreement(source: string): ReviewToolViolation[] {
348
636
  kind: "ALLOWED_TOOL_CANNOT_EXIST_ON_THIS_TRIGGER",
349
637
  detail:
350
638
  `--allowedTools grants ${tool}, whose MCP server is installed only under an entity ` +
351
- `event (${why}). This workflow's triggers are ${triggers.join(", ")}, all of which ` +
352
- `the action classifies as automation events, so the tool never exists`,
639
+ `event (${why}). ` +
640
+ (everyTriggerIsAutomation
641
+ ? `This workflow's triggers are ${triggers.join(", ")}, all of which the action ` +
642
+ `classifies as automation events, so the tool never exists`
643
+ : `This workflow also triggers on ${automationTriggers.join(", ")}, which the ` +
644
+ `action classifies as an automation event, so a run started that way has no ` +
645
+ `such server and the tool does not exist in it. The grant works on ` +
646
+ `${triggers.filter(t => !automationTriggers.includes(t)).join(", ")} and ` +
647
+ `silently does nothing on the rest`),
353
648
  });
354
649
  }
355
650
  }
356
651
  }
357
652
 
653
+ // 3b. The trigger promotion's own door (#631/#675). An entity trigger means
654
+ // the job fires on pull requests opened by people who are not
655
+ // collaborators, and on a public repository that is most of them. The
656
+ // fork decision then has to exist somewhere a reader can point at.
657
+ //
658
+ // Read from the JOB HEADER, never the document: every revision of
659
+ // `claude-review.yml` discusses forks in its header at length, and a
660
+ // whole-file search would be satisfied by the prose explaining why the
661
+ // guard matters — `.claude/rules/checks-must-be-able-to-fail.md`,
662
+ // "search the slice, not the document", which is the defect the
663
+ // reviewer found in this very module on #746.
664
+ //
665
+ // Silent on an automation-only workflow, which is why the pre-#732
666
+ // fixture does not report it: a dispatch cannot be opened by a
667
+ // stranger, and a guard against a case that cannot arise is one more
668
+ // thing to keep true for nothing.
669
+ const entityTriggers = triggers.filter(t => (ENTITY_TRIGGERS as readonly string[]).includes(t));
670
+ if (triggers.includes("pull_request_target")) {
671
+ v.push({
672
+ kind: "PULL_REQUEST_TARGET_TRIGGER",
673
+ detail:
674
+ "the workflow triggers on pull_request_target, which runs this job with a WRITE token " +
675
+ "against a fork's code. For a job that hands a diff to an agent that is the egress sink " +
676
+ "this file's header describes, with the credential handed over deliberately — use " +
677
+ "pull_request, whose fork runs are read-only",
678
+ });
679
+ }
680
+ if (entityTriggers.length > 0) {
681
+ // The `if:` block, not the job header. A `name:` or an `env:` value
682
+ // carrying both terms would satisfy a header-wide search, and an absent
683
+ // `if:` is reported as the missing guard it is rather than throwing.
684
+ let condition = "";
685
+ try {
686
+ condition = withoutComments(blockUnder(jobHeader, "if:"));
687
+ } catch {
688
+ condition = "";
689
+ }
690
+ const missing = FORK_GUARD_TERMS.filter(term => !condition.includes(term));
691
+ const why =
692
+ missing.length > 0
693
+ ? `the job's condition names neither ${missing.join(" nor ")}`
694
+ : forkGuardDefect(condition);
695
+ if (why !== null) {
696
+ v.push({
697
+ kind: "ENTITY_TRIGGER_WITHOUT_A_FORK_GUARD",
698
+ detail:
699
+ `the workflow triggers on ${entityTriggers.join(", ")}, so it runs on pull requests ` +
700
+ `from forks, and ${why}. A fork run holds a read-only token and no id-token: write, ` +
701
+ `so every step after auth fails — and a job that fails on every fork pull request is ` +
702
+ `a red check nobody can act on`,
703
+ });
704
+ }
705
+ }
706
+
358
707
  // 4. Nothing on the allowlist can write a finding anywhere a human will see.
359
708
  if (!allowed.some(a => (POSTING_TOOLS as readonly string[]).includes(a))) {
360
709
  v.push({
@@ -130,6 +130,7 @@ import {
130
130
  AI_REVIEW_REQUIRED_EXIT,
131
131
  AI_REVIEW_SEVERITIES,
132
132
  AI_REVIEW_SEVERITY_KEY,
133
+ AI_REVIEW_THREAD_KEY_MARKER,
133
134
  AI_REVIEW_VERDICT_KEY,
134
135
  SEVERITY_RANK,
135
136
  type Severity,
@@ -889,6 +890,7 @@ export interface AiReviewThreadRequest {
889
890
  */
890
891
  export function reviewThreadRequests(
891
892
  reading: AiReviewFindingsReading,
893
+ keyFor?: (finding: Record<string, unknown>) => string | null,
892
894
  ): AiReviewThreadRequest[] {
893
895
  const f = AI_REVIEW_FINDING_FIELDS;
894
896
  if (reading.reported === null) return [];
@@ -917,7 +919,7 @@ export function reviewThreadRequests(
917
919
  ? Number(suffixed[2])
918
920
  : null;
919
921
 
920
- requests.push({ path, line, body: threadBody(finding) });
922
+ requests.push({ path, line, body: threadBody(finding, keyFor?.(finding)) });
921
923
  }
922
924
  return requests;
923
925
  }
@@ -930,7 +932,24 @@ export function reviewThreadRequests(
930
932
  * path has never had room for it, which is part of why the annotations were
931
933
  * worth so little.
932
934
  */
933
- function threadBody(finding: Record<string, unknown>): string {
935
+ /**
936
+ * The thread a finding becomes, with the identity it was raised under
937
+ * appended when the caller could form one.
938
+ *
939
+ * `key` is a parameter and not something read here, for the reason
940
+ * `suppressRepeats` states about its own prior set: only the caller can
941
+ * reach the checkout to read the text at the cited line, and a function that
942
+ * fetches its own evidence cannot be given a negative control. It is also
943
+ * why `carryKey` is not imported — this module is copied ALONE into a
944
+ * scratch directory by several mutation batteries, and a relative import
945
+ * added to it resolves to nothing, so the mutant fails to LOAD and reads as
946
+ * a behavioural difference on every row.
947
+ *
948
+ * `null`, `undefined` and `""` all emit NO marker, and that is deliberate.
949
+ * A caller that could not key the finding has not recorded an empty key; it
950
+ * has recorded nothing, and the two must not be the same bytes.
951
+ */
952
+ export function threadBody(finding: Record<string, unknown>, key?: string | null): string {
934
953
  const f = AI_REVIEW_FINDING_FIELDS;
935
954
  const severity = finding[f.severity] !== undefined ? String(finding[f.severity]) : null;
936
955
  const summary =
@@ -939,7 +958,49 @@ function threadBody(finding: Record<string, unknown>): string {
939
958
  finding[f.failureScenario] !== undefined ? String(finding[f.failureScenario]) : null;
940
959
 
941
960
  const head = severity === null ? summary : `**${severity}** — ${summary}`;
942
- return scenario === null ? head : `${head}\n\n${scenario}`;
961
+ const prose = scenario === null ? head : `${head}\n\n${scenario}`;
962
+ if (typeof key !== "string" || key === "") return prose;
963
+ const payload = Buffer.from(key, "utf-8").toString("base64");
964
+ return `${prose}\n\n<!-- ${AI_REVIEW_THREAD_KEY_MARKER} ${payload} -->`;
965
+ }
966
+
967
+ /**
968
+ * Recover the key a thread was posted under, or `null`.
969
+ *
970
+ * `null` means THIS THREAD CANNOT BE SHOWN TO BE A REPEAT, and every way of
971
+ * failing collapses to it: no marker, a marker this version does not know, a
972
+ * payload that is not base64, a payload that does not decode to the bytes it
973
+ * encoded. That collapse is safe in exactly one direction — a thread read as
974
+ * unkeyed is re-posted, which is loud and self-correcting, whereas a thread
975
+ * read under the WRONG key suppresses a live finding silently and
976
+ * permanently.
977
+ *
978
+ * The round-trip check is why a corrupt payload cannot become a key by
979
+ * accident: `Buffer.from` is lenient and will decode almost any string to
980
+ * SOME bytes, so re-encoding and comparing is the only reading that
981
+ * distinguishes a payload this writer produced from one it did not.
982
+ */
983
+ export function threadKeyFrom(body: unknown): string | null {
984
+ if (typeof body !== "string") return null;
985
+ const at = body.lastIndexOf(`<!-- ${AI_REVIEW_THREAD_KEY_MARKER} `);
986
+ if (at === -1) return null;
987
+ const rest = body.slice(at + `<!-- ${AI_REVIEW_THREAD_KEY_MARKER} `.length);
988
+ const end = rest.indexOf("-->");
989
+ if (end === -1) return null;
990
+ const payload = rest.slice(0, end).trim();
991
+ if (payload === "") return null;
992
+ let decoded: string;
993
+ try {
994
+ decoded = Buffer.from(payload, "base64").toString("utf-8");
995
+ } catch {
996
+ return null;
997
+ }
998
+ if (decoded === "") return null;
999
+ // THE CONTROL ON THE DECODE. Without it `@@@not base64@@@` decodes to
1000
+ // mojibake and is returned as a key, so every corrupt thread becomes a
1001
+ // repeat of every other corrupt thread.
1002
+ if (Buffer.from(decoded, "utf-8").toString("base64") !== payload) return null;
1003
+ return decoded;
943
1004
  }
944
1005
 
945
1006
  /**