rungate 0.8.20 → 0.8.22

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
- b387c07fdac25bd795e3bf46bc2a7dbe1b8f1f394d3d14380e9ef253451767f6
1
+ 7ed090dd68860ba3c71316283fe5935c3fc35fb98b04f2d15f1905c9dd39cac5
@@ -2,6 +2,10 @@
2
2
  /**
3
3
  * AgentBriefGuard — PreToolUse on Agent (SC-367, SC-370)
4
4
  * Validates briefs use templates + bypassPermissions. Delegates to lib/agent-brief-validation.ts
5
+ *
6
+ * USER scope since #1585: WORK_DIR/BASE_DIR are ~/.rungate and ~/.claude (machine state),
7
+ * and a project registration never loads in the worktree sessions where agents spawn agents.
8
+ * Registered live in ~/.claude/settings.json (measured 2026-11-15, #2225).
5
9
  */
6
10
  import { BASE_DIR, WORK_DIR } from './lib/paths';
7
11
  import { parseHookInput } from './lib/parseStdin';
@@ -41,6 +41,22 @@
41
41
  * and records both answers. Change either hook and update that table and
42
42
  * `specs/HOOK-ARCHITECTURE-SPEC.md` § "The workflow-state.json write contract"
43
43
  * in the same commit.
44
+ *
45
+ * ## User scope since #1585
46
+ *
47
+ * This was `project` scope and registered in `.claude/settings.json`. Agent
48
+ * sessions run in worktrees and do not load project settings, so it never
49
+ * fired, while `GateResultProtection` fired on the same tool calls from user
50
+ * settings. What it guards is machine-wide — the matcher below has no project
51
+ * scoping, and `lib/bash-write-guard.ts` records that a live
52
+ * `workflow-state.json` is almost never inside the project root — so SC-518
53
+ * puts it in user settings. The repo no longer registers it (dual registration
54
+ * fires twice) and reports it UNMEASURED. Registered live in ~/.claude/settings.json
55
+ * (measured 2026-11-15, #2225); the session-start reading reports it if that stops (#2229).
56
+ *
57
+ * A scaffolded consumer is unaffected: `deployHooksToConsumers` filters on
58
+ * `deployToConsumers`, not on scope, so the paragraph above about consumer
59
+ * trees still holds.
44
60
  */
45
61
 
46
62
  import { parseHookInput } from './lib/utils';
@@ -24,7 +24,7 @@
24
24
  * two that only a live fork or a line outside a hunk would otherwise produce.
25
25
  */
26
26
  import type { ThreadReading } from "./ai-review-rounds";
27
- import { reviewThreadRequests, threadKeyFrom } from "./scaffold/ai-review-findings";
27
+ import { escapeAnnotation, reviewThreadRequests, threadKeyFrom } from "./scaffold/ai-review-findings";
28
28
  import type { AiReviewFindingsReading, AiReviewThreadRequest } from "./scaffold/ai-review-findings";
29
29
 
30
30
  /**
@@ -254,6 +254,7 @@ export async function postReviewThreads(
254
254
  reading: AiReviewFindingsReading,
255
255
  post: AiReviewThreadPoster,
256
256
  keyFor?: (finding: Record<string, unknown>) => string | null,
257
+ fork?: boolean | null,
257
258
  ): Promise<AiReviewThreadsResult> {
258
259
  const detail: string[] = [];
259
260
 
@@ -306,10 +307,24 @@ export async function postReviewThreads(
306
307
  continue;
307
308
  }
308
309
  if (answer.status === FORBIDDEN) {
310
+ // #1992: the fork excuse holds only for a fork. A same-repository run
311
+ // whose token lost write is a broken producer, and degrading it would
312
+ // hide that behind a reason that does not apply.
313
+ if (fork === false) {
314
+ failed += 1;
315
+ detail.push(
316
+ `${where}: 403 — this token cannot write pull-request comments, and this run is not a fork ` +
317
+ `(${AI_REVIEW_PR_IS_FORK_VAR}=false), so the read-only-token excuse does not apply.`,
318
+ );
319
+ continue;
320
+ }
309
321
  forbidden += 1;
310
322
  detail.push(
311
323
  `${where}: 403 — this token cannot write pull-request comments. A pull_request run from a ` +
312
- `fork is handed a read-only token whatever the workflow declares.`,
324
+ `fork is handed a read-only token whatever the workflow declares.` +
325
+ (fork === true
326
+ ? ""
327
+ : ` Whether this run is a fork was not read (${AI_REVIEW_PR_IS_FORK_VAR} unset), so it is treated as one.`),
313
328
  );
314
329
  continue;
315
330
  }
@@ -358,6 +373,35 @@ export function threadsLandedPhrase(result: AiReviewThreadsResult): string {
358
373
  : `Only ${result.posted} of ${result.attempted} review threads were created`;
359
374
  }
360
375
 
376
+ /**
377
+ * The environment variable the workflow sets to say whether this run is a
378
+ * fork (#1992; the generator half is #2203). An environment variable and not
379
+ * a flag on purpose: a published CLI that does not know a flag refuses it,
380
+ * while an unknown variable is ignored, so the workflow can set it before or
381
+ * after this reader ships without reddening anything.
382
+ */
383
+ export const AI_REVIEW_PR_IS_FORK_VAR = "RUNGATE_PR_IS_FORK";
384
+
385
+ /**
386
+ * Read exactly: `"true"` and `"false"` are readings, anything else is unread
387
+ * (`null`). The same rule `.claude/rules/config-access.md` applies to a switch
388
+ * that turns a refusal on — a loose reading turns it on by accident.
389
+ */
390
+ export function prIsForkReading(raw: string | undefined): boolean | null {
391
+ return raw === "true" ? true : raw === "false" ? false : null;
392
+ }
393
+
394
+ /**
395
+ * Every line this command prints from a result's detail, escaped (#1992).
396
+ * Detail carries text the producer does not control — an API error message,
397
+ * a path a finding named — and a CR or LF printed raw starts a new line that
398
+ * the Actions runner reads as a workflow command. `escapeAnnotation` is the
399
+ * one escaper, so this does not grow a second.
400
+ */
401
+ export function threadsDetailLines(result: AiReviewThreadsResult, command: string): string[] {
402
+ return result.detail.map(line => `${command}: ${escapeAnnotation(line)}`);
403
+ }
404
+
361
405
  /** The exit code a round's outcome earns. Only `FAILED` refuses. */
362
406
  export function aiReviewThreadsExitCode(result: AiReviewThreadsResult): number {
363
407
  return result.outcome === "FAILED" ? AI_REVIEW_THREADS_REFUSAL : 0;
@@ -47,6 +47,7 @@ export type MoveRefusal =
47
47
  | "COLUMN_UNSEARCHABLE"
48
48
  | "API_FAILED"
49
49
  | "NULL_NODE"
50
+ | "WRONG_TYPE"
50
51
  | "FIELDS_TRUNCATED"
51
52
  | "NOT_RESOLVED"
52
53
  | "VALUES_TRUNCATED"
@@ -142,6 +143,8 @@ interface ReadSite {
142
143
  /** What the id names, and the input it came from, so the refusal blames the right one. */
143
144
  names: "the project" | "the item";
144
145
  input: "PROJECT_ID" | "ITEM_ID";
146
+ /** The type the query's inline fragment selects; any other type resolves with no connection. */
147
+ type: "ProjectV2" | "ProjectV2Item";
145
148
  wrote: boolean;
146
149
  }
147
150
 
@@ -153,6 +156,15 @@ interface ReadSite {
153
156
  */
154
157
  function requireNode<T>(data: unknown, key: "fields" | "fieldValues" | "items", site: ReadSite): Page<T> {
155
158
  const node = (data as { node?: Record<string, unknown> | null } | null | undefined)?.node;
159
+ // A node that RESOLVED but carries no connection is a different object
160
+ // type: the inline fragment did not apply. Said apart from a null node,
161
+ // which is an id that did not resolve (#2183, from PR #2194 round 6).
162
+ if (node !== null && node !== undefined && node[key] === undefined) {
163
+ throw new Refused(
164
+ "WRONG_TYPE",
165
+ `${site.what} is UNMEASURED and ${site.wrote ? "a write WAS sent before this read, so the board may already hold the new value" : "nothing was written"}: node(id: ${site.id}) resolved, but not to a ${site.type}, so ${site.input} names a different kind of object (an item id passed as the project, for example). This is NOT a stale id and NOT an empty board.`,
166
+ );
167
+ }
156
168
  const page = node?.[key] as Page<T> | null | undefined;
157
169
  if (!page) {
158
170
  throw new Refused(
@@ -191,7 +203,7 @@ export async function moveToColumn(input: MoveInput, deps: MoveDeps): Promise<Mo
191
203
  const fields = requireNode<{ id?: string; name?: string; options?: Array<{ id: string; name: string }> }>(
192
204
  await call(deps, FIELDS_QUERY, { project: projectId }),
193
205
  "fields",
194
- { what: "the project's field list", id: projectId, names: "the project", input: "PROJECT_ID", wrote: false },
206
+ { what: "the project's field list", id: projectId, names: "the project", input: "PROJECT_ID", type: "ProjectV2", wrote: false },
195
207
  );
196
208
  const status = present(fields).find(f => f.name === "Status");
197
209
  const fieldId = status?.id ?? "";
@@ -205,7 +217,7 @@ export async function moveToColumn(input: MoveInput, deps: MoveDeps): Promise<Mo
205
217
  if (!fieldId || !optionId) {
206
218
  throw new Refused(
207
219
  "NOT_RESOLVED",
208
- `Could not resolve the Status field or its '${column}' option on this project. ${fieldId ? "The Status field was found and its options are returned in full, so this is not a truncated page" : "The whole field list was read, so this is not a truncated page"}. The item WAS added; only the transition failed. Someone renamed the field or the column — update COLUMN in this workflow to match the board.`,
220
+ `Could not resolve the Status field or its '${column}' option on this project. ${fieldId ? `The Status field was found and its options were read in full${truncated(fields) ? " (the field list has more than one page, which does not affect its options)" : ""}, so this is not a truncated read` : "The whole field list was read, so this is not a truncated page"}. The item WAS added; only the transition failed. Someone renamed the field or the column — update COLUMN in this workflow to match the board.`,
209
221
  );
210
222
  }
211
223
 
@@ -218,7 +230,7 @@ export async function moveToColumn(input: MoveInput, deps: MoveDeps): Promise<Mo
218
230
  const values = requireNode<{ name?: string; field?: { name?: string } }>(
219
231
  await call(deps, VALUES_QUERY, { item: itemId }),
220
232
  "fieldValues",
221
- { what: "the item's field values, read back after the write", id: itemId, names: "the item", input: "ITEM_ID", wrote: true },
233
+ { what: "the item's field values, read back after the write", id: itemId, names: "the item", input: "ITEM_ID", type: "ProjectV2Item", wrote: true },
222
234
  );
223
235
  current = present(values).find(v => v.field?.name === "Status")?.name ?? "";
224
236
  if (!current && truncated(values)) {
@@ -233,7 +245,7 @@ export async function moveToColumn(input: MoveInput, deps: MoveDeps): Promise<Mo
233
245
  const index = requireNode<{ id?: string }>(
234
246
  await call(deps, INDEX_QUERY, { project: projectId, q: `status:"${column}"` }),
235
247
  "items",
236
- { what: `the search index for the '${column}' column`, id: projectId, names: "the project", input: "PROJECT_ID", wrote: true },
248
+ { what: `the search index for the '${column}' column`, id: projectId, names: "the project", input: "PROJECT_ID", type: "ProjectV2", wrote: true },
237
249
  );
238
250
  const indexed = present(index).some(n => n.id === itemId);
239
251
  if (!indexed && truncated(index)) {
@@ -211,6 +211,25 @@ interface FileReading {
211
211
 
212
212
  const READABLE: FileReading = { failure: null, unmeasured: null };
213
213
 
214
+ /**
215
+ * The directories a strike scan may read: every visible one, and no hidden one
216
+ * (#1987, SC-2771).
217
+ *
218
+ * A hidden directory under the run store is where runs are set aside, not run.
219
+ * `~/.rungate/.archive` is the one that exists. On 2026-11-15 it held 67
220
+ * workflow-state files within the two levels the scan below walks, and every
221
+ * one was counted as a live attempt. So a project whose failed runs had been
222
+ * archived stayed blocked by the strike rule, and the only workaround was to
223
+ * move the archive out of `~/.rungate` (DBD #1513).
224
+ *
225
+ * The rule is the hidden-directory convention, not the word: a directory named
226
+ * `archive` without the dot is a live run and is still read. One function and
227
+ * both scan levels call it, so there is one site to mutate.
228
+ */
229
+ export function excludeArchivedRuns<T extends { readonly name: string }>(dirs: readonly T[]): T[] {
230
+ return dirs.filter(d => !d.name.startsWith('.'));
231
+ }
232
+
214
233
  /**
215
234
  * Scan workflow-state.json files under workDir for active gate failures.
216
235
  * Returns the first failure found (scope > verify > ship priority).
@@ -239,8 +258,9 @@ export function findWorkflowGateFailure(workDir: string): WorkflowScan {
239
258
  };
240
259
 
241
260
  try {
242
- const dirs = readdirSync(workDir, { withFileTypes: true })
243
- .filter(d => d.isDirectory());
261
+ const dirs = excludeArchivedRuns(
262
+ readdirSync(workDir, { withFileTypes: true }).filter(d => d.isDirectory()),
263
+ );
244
264
 
245
265
  for (const d of dirs) {
246
266
  // Level 1: direct children
@@ -248,8 +268,9 @@ export function findWorkflowGateFailure(workDir: string): WorkflowScan {
248
268
 
249
269
  // Level 2: nested subdirectories
250
270
  try {
251
- const subDirs = readdirSync(`${workDir}/${d.name}`, { withFileTypes: true })
252
- .filter(sd => sd.isDirectory());
271
+ const subDirs = excludeArchivedRuns(
272
+ readdirSync(`${workDir}/${d.name}`, { withFileTypes: true }).filter(sd => sd.isDirectory()),
273
+ );
253
274
  for (const sd of subDirs) {
254
275
  take(checkWorkflowFile(
255
276
  `${workDir}/${d.name}/${sd.name}/workflow-state.json`,
@@ -386,6 +386,14 @@ export function unplacedHooks(input: {
386
386
  */
387
387
  export const NOT_LIVE_CLAIM = /\bnot live\b/i;
388
388
 
389
+ /**
390
+ * The reverse claim: a registry description saying its hook is registered in
391
+ * user settings (#2229). Checked against `user-settings` specifically, because
392
+ * that is the file the sentence names; a registration somewhere else does not
393
+ * make the sentence true.
394
+ */
395
+ export const LIVE_CLAIM = /\bregistered live in ~\/\.claude\/settings\.json/i;
396
+
389
397
  /**
390
398
  * Registry entries whose NOT LIVE claim the machine's registration contradicts,
391
399
  * as lines a person reads at session start (#1986).
@@ -396,8 +404,9 @@ export const NOT_LIVE_CLAIM = /\bnot live\b/i;
396
404
  * NOT LIVE claim disagree with itself. With that scope empty, `registered`
397
405
  * means a settings file a session loads names the hook — a disagreement;
398
406
  * `unmeasured` means a machine scope could not be read — said as UNMEASURED,
399
- * which is every CI runner; `unregistered` agrees with the claim, and is
400
- * silent.
407
+ * which is a machine with no user settings file (most CI runners);
408
+ * `unregistered` agrees with the claim, and is silent. Entries claiming the
409
+ * opposite, "registered live", are read by `liveRegistrationLine` (#2229).
401
410
  */
402
411
  export function liveClaimLines(
403
412
  entries: readonly { name?: unknown; description?: unknown }[],
@@ -410,7 +419,10 @@ export function liveClaimLines(
410
419
  const lines: string[] = [];
411
420
  for (const e of entries) {
412
421
  if (typeof e.name !== "string" || typeof e.description !== "string") continue;
413
- if (!NOT_LIVE_CLAIM.test(e.description)) continue;
422
+ if (!NOT_LIVE_CLAIM.test(e.description)) {
423
+ if (LIVE_CLAIM.test(e.description)) lines.push(...liveRegistrationLine(e.name, loaded));
424
+ continue;
425
+ }
414
426
  const r = hookRegistration(e.name, loaded);
415
427
  if (r.verdict === "registered") {
416
428
  lines.push(
@@ -427,6 +439,46 @@ export function liveClaimLines(
427
439
  return lines;
428
440
  }
429
441
 
442
+ /**
443
+ * #2229: an entry that claims user settings registers it. Silent when the
444
+ * `user-settings` scope names the hook. UNMEASURED when that scope could not
445
+ * be read, which is a machine with no `~/.claude/settings.json` (most CI
446
+ * runners). Otherwise a disagreement, naming where the hook IS registered, if
447
+ * anywhere.
448
+ *
449
+ * The claim is about the machine the registration was measured on, and the
450
+ * registry is shared. So on a machine whose user settings exist but never
451
+ * registered the hook (another contributor's laptop, a review sandbox), the
452
+ * reading is DISAGREES, and it is true FOR THAT MACHINE: the hook does not run
453
+ * there. The message says "on this machine" so it reads as that, and not as a
454
+ * claim that the entry is wrong everywhere (review of #2232).
455
+ */
456
+ function liveRegistrationLine(hook: string, loaded: ScopeReading[]): string[] {
457
+ const user = loaded.find(r => r.scope === "user-settings");
458
+ if (user === undefined || user.commands === null) {
459
+ return [
460
+ `Hook registry UNMEASURED: ${hook} is described as registered live in ~/.claude/settings.json, and ` +
461
+ `user-settings could not be read to check that claim (#2229)`,
462
+ ];
463
+ }
464
+ if (user.commands.some(c => commandNamesHook(c, hook))) return [];
465
+ const elsewhere = loaded.filter(r => (r.commands ?? []).some(c => commandNamesHook(c, hook))).map(r => r.scope);
466
+ // Registered in another scope a session loads (user-local-settings, say):
467
+ // the hook runs, and only the file the entry names is wrong. Saying "does
468
+ // not run here" then would be false (review of #2232, round 2).
469
+ if (elsewhere.length > 0) {
470
+ return [
471
+ `Hook registry DISAGREES: ${hook} is described as registered live in ~/.claude/settings.json, but ` +
472
+ `this machine registers it in ${elsewhere.join(", ")} instead — the entry names the wrong file (#2229)`,
473
+ ];
474
+ }
475
+ return [
476
+ `Hook registry DISAGREES: ${hook} is described as registered live in ~/.claude/settings.json, but ` +
477
+ `this machine's user settings do not register it, so it does not run here — ` +
478
+ `register it on this machine, or correct the entry if it is no longer meant to run (#2229)`,
479
+ ];
480
+ }
481
+
430
482
  /**
431
483
  * `liveClaimLines` over a fresh reading, as its own reading (#1986).
432
484
  *
@@ -196,8 +196,14 @@ ${opts.setupBunEnv}
196
196
  # reads it as GITHUB_TOKEN, board-ready as BOARD_PROJECT_TOKEN. An absent
197
197
  # secret is the empty string with no error, so each command's own
198
198
  # UNMEASURED refusal is what reports it.
199
+ #
200
+ # \`!cancelled()\` (#2239): an \`if:\` with no status function means
201
+ # \`success() && …\`, so a refusal in any step above skipped both of these
202
+ # for every issue the merge had just created. Each reads the whole board
203
+ # and writes only what is missing, so it never depends on an earlier step
204
+ # succeeding. The run is still red when one of those failed.
199
205
  - name: Criteria column on the board
200
- if: steps.accepted.outputs.any == 'true'
206
+ if: \${{ !cancelled() && steps.accepted.outputs.any == 'true' }}
201
207
  env:
202
208
  GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
203
209
  PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
@@ -209,7 +215,7 @@ ${opts.setupBunEnv}
209
215
  ${cli} board-mirror --project "$PROJECT_ID" --write
210
216
 
211
217
  - name: Top up Ready from the new issues
212
- if: steps.accepted.outputs.any == 'true'
218
+ if: \${{ !cancelled() && steps.accepted.outputs.any == 'true' }}
213
219
  env:
214
220
  BOARD_PROJECT_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
215
221
  PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
@@ -135,6 +135,7 @@ import {
135
135
  AI_REVIEW_VERDICT_KEY,
136
136
  SEVERITY_RANK,
137
137
  type Severity,
138
+ AI_REVIEW_UNTRUSTED_PATHS,
138
139
  } from "./ai-review-step";
139
140
 
140
141
  export {
@@ -1156,7 +1157,15 @@ export function reviewThreadRequests(
1156
1157
  // posting less.
1157
1158
  const scope = reading.scope;
1158
1159
  let touched: ReadonlySet<string> | null = null;
1160
+ // The diff's own spelling of each changed file, keyed by the comparison
1161
+ // form. When a finding matches one, THAT spelling is sent: it is byte for
1162
+ // byte what the API resolves against (#1992).
1163
+ const diffSpelling = new Map<string, string>();
1159
1164
  if (scope?.status === "MEASURED") {
1165
+ for (const entry of scope.files) {
1166
+ const spelt = repoPathSpelling(entry);
1167
+ if (spelt !== null) diffSpelling.set(spelt.toLowerCase(), spelt);
1168
+ }
1160
1169
  // The same conversion `readPayload` makes, through the same function, so
1161
1170
  // the skip here and the demotion there cannot disagree about one finding.
1162
1171
  const { readable } = partitionChangedFiles(scope.files);
@@ -1176,13 +1185,17 @@ export function reviewThreadRequests(
1176
1185
  if (findingPathScope(finding, touched) === "PRE_EXISTING") continue;
1177
1186
 
1178
1187
  const raw = finding[f.file];
1179
- // Readability is asked of the normalised spelling; the answer is carried
1180
- // by the raw one. A `:line` suffix is the one edit applied to it, because
1181
- // `src/a.ts:88` is not a path the API can match and the number in it is
1182
- // the only line the finding gave.
1183
- if (normaliseRepoPath(raw) === null) continue;
1188
+ // The scope check above matched the NORMALISED spelling; the raw one —
1189
+ // `./lib/a.ts`, `lib//a.ts` — asks the API for a path it cannot resolve,
1190
+ // the file-level retry is refused the same way, and the round ends
1191
+ // FAILED over a finding that was correctly in the diff (#1992). So the
1192
+ // diff's own spelling is sent when the finding matched one, and the
1193
+ // finding's case-kept spelling otherwise. Both drop a `:line` suffix;
1194
+ // the number in it is still read below, as the only line given.
1195
+ const spelt = repoPathSpelling(raw);
1196
+ if (spelt === null) continue;
1197
+ const path = diffSpelling.get(spelt.toLowerCase()) ?? spelt;
1184
1198
  const suffixed = String(raw).trim().replace(/\\/g, "/").match(/^(.*?):(\d+)(?::\d+)?$/);
1185
- const path = suffixed ? suffixed[1]! : String(raw).trim().replace(/\\/g, "/");
1186
1199
 
1187
1200
  const declared = finding[f.line];
1188
1201
  const line =
@@ -2016,8 +2029,22 @@ function readPayload(
2016
2029
  * deliberately `null` rather than unescaped here: decoding octal escapes to
2017
2030
  * compare a path is a second parser, and the right repair is to produce the
2018
2031
  * list with `-z` or `core.quotePath=false` in the first place.
2032
+ *
2033
+ * It is `repoPathSpelling` lowercased: the two share every rule but case,
2034
+ * because this one COMPARES and that one is SENT (#1992).
2019
2035
  */
2020
2036
  export function normaliseRepoPath(value: unknown): string | null {
2037
+ return repoPathSpelling(value)?.toLowerCase() ?? null;
2038
+ }
2039
+
2040
+ /**
2041
+ * A path in the spelling the REST API can match: dot segments collapsed,
2042
+ * leading slashes, backslashes and a `:line` suffix removed, CASE KEPT. The
2043
+ * API matches the diff byte for byte, so the lowercased comparison form is
2044
+ * the predicate and never the value (#1992). `null` exactly where
2045
+ * `normaliseRepoPath` is `null`, because that one is this one lowercased.
2046
+ */
2047
+ export function repoPathSpelling(value: unknown): string | null {
2021
2048
  if (typeof value !== "string") return null;
2022
2049
  let p = value.trim().replace(/\\/g, "/");
2023
2050
  // git's C-quoted spelling. Not comparable without a second unescaper.
@@ -2053,7 +2080,7 @@ export function normaliseRepoPath(value: unknown): string | null {
2053
2080
  p = out.join("/");
2054
2081
  if (p === "") return null;
2055
2082
 
2056
- return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p.toLowerCase() : null;
2083
+ return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p : null;
2057
2084
  }
2058
2085
 
2059
2086
  /** What a changed-file list reduced to, split by whether it could be read. */
@@ -2326,6 +2353,71 @@ export function aiReviewScopeLine(reading: AiReviewFindingsReading): string {
2326
2353
  );
2327
2354
  }
2328
2355
 
2356
+ /** The prefix of the line naming the changed files the reviewer read from base (#1887). */
2357
+ export const AI_REVIEW_RESTORED_LINE = "ai-review restored from base, not reviewed:";
2358
+
2359
+ /**
2360
+ * The changed files the review step restored from the base branch before the
2361
+ * reviewer ran, so the verdict was reached over the BASE copy (#1887).
2362
+ *
2363
+ * The restore is correct and stays: it is what stops a pull request editing
2364
+ * the instructions that judge it. What was wrong is that the verdict said
2365
+ * nothing, so a review that never read three of four changed files (#1882)
2366
+ * looked like a review that read all four.
2367
+ *
2368
+ * `restored` defaults to `AI_REVIEW_UNTRUSTED_PATHS`, the list the generated
2369
+ * restore step is built from, so there is no second copy to drift. A path
2370
+ * counts when it IS a restored entry or sits under one as a directory, which
2371
+ * is how `git checkout <base> -- <path>` reaches it. The match is byte for
2372
+ * byte on git's spelling: the runner's filesystem is case-sensitive, so
2373
+ * `claude.md` is not `CLAUDE.md` and was not restored.
2374
+ */
2375
+ export function restoredFromBase(
2376
+ files: readonly string[],
2377
+ restored: readonly string[] = AI_REVIEW_UNTRUSTED_PATHS,
2378
+ ): string[] {
2379
+ return files.filter(raw => {
2380
+ const f = repoPathSpelling(raw);
2381
+ return f !== null && restored.some(r => f === r || f.startsWith(`${r}/`));
2382
+ });
2383
+ }
2384
+
2385
+ /**
2386
+ * The line `main` prints after the scope line: how many changed files were
2387
+ * reviewed against the base copy, and which. Printed on every run, an empty
2388
+ * overlap included as an explicit `0 of N` — "nothing was hidden" and "nobody
2389
+ * looked" must not be the same bytes. With no readable changed-file list the
2390
+ * overlap is UNMEASURED, never zero.
2391
+ *
2392
+ * A report only, as #1887 scopes it. Whether an unreviewed fraction should
2393
+ * ever block is a separate decision, and nothing here refuses.
2394
+ */
2395
+ export function restoredFromBaseLine(scope: AiReviewScopeReading): string {
2396
+ if (scope.status !== "MEASURED") {
2397
+ return (
2398
+ `${AI_REVIEW_RESTORED_LINE} UNMEASURED — the changed-file list is ${scope.status}, so which ` +
2399
+ `changed files were reviewed against the base copy cannot be said`
2400
+ );
2401
+ }
2402
+ const hit = restoredFromBase(scope.files);
2403
+ const of = `${hit.length} of ${scope.files.length} changed files`;
2404
+ // An entry with no comparable spelling (git's C-quoted form for a non-ASCII
2405
+ // name, or a path escaping the root) cannot be classified either way. It is
2406
+ // NAMED rather than folded into "not restored": a restored `.claude/réglages.md`
2407
+ // arrives C-quoted, and counting it clean is the silence #1887 is about.
2408
+ const unread = scope.files.filter(f => repoPathSpelling(f) === null);
2409
+ const unreadNote =
2410
+ unread.length === 0
2411
+ ? ""
2412
+ : `; ${unread.length} could not be read as a repository path and may also have been ` +
2413
+ `restored: ${unread.map(p => JSON.stringify(p)).join(", ")}`;
2414
+ if (hit.length === 0) return `${AI_REVIEW_RESTORED_LINE} ${of}${unreadNote}`;
2415
+ return (
2416
+ `${AI_REVIEW_RESTORED_LINE} ${of} — the reviewer read the base branch's copy of ` +
2417
+ `${hit.map(p => JSON.stringify(p)).join(", ")}, not this pull request's${unreadNote}`
2418
+ );
2419
+ }
2420
+
2329
2421
  // `parseFindingsArgv` and `AiReviewFindingsArgv` lived here and are gone.
2330
2422
  // The parser refused a SECOND POSITIONAL argument by design, which is
2331
2423
  // exactly the invocation CRC-B7 deploys, so the flag CLI and the
@@ -2521,6 +2613,9 @@ export function main(
2521
2613
  // on the command line reaches a stream GitHub parses workflow commands out
2522
2614
  // of, and this module escapes exactly once, at the point of emission.
2523
2615
  console.log(escapeAnnotation(aiReviewScopeLine(reading)));
2616
+ // #1887: which changed files the reviewer saw only as the base copy. Same
2617
+ // escaping, for the same reason: these are paths off the command line.
2618
+ console.log(escapeAnnotation(restoredFromBaseLine(reading.scope)));
2524
2619
 
2525
2620
  // The ONE place a value reaches a workflow command. Everything upstream of
2526
2621
  // here — `renderFinding`, every `detail` sentence, `aiReviewRefusal` — builds
@@ -3199,6 +3199,13 @@ export const AI_REVIEW_THREADS_PR_VAR = "AI_REVIEW_THREADS_PR";
3199
3199
  export const AI_REVIEW_THREADS_REPO_VAR = "AI_REVIEW_THREADS_REPO";
3200
3200
  export const AI_REVIEW_THREADS_SHA_VAR = "AI_REVIEW_THREADS_SHA";
3201
3201
  export const AI_REVIEW_THREADS_TOKEN_VAR = "AI_REVIEW_THREADS_TOKEN";
3202
+ /**
3203
+ * Whether this run is a fork, for the threads CLI's 403 decision (#1992,
3204
+ * #2203). Spelt here rather than imported from `lib/ai-review-threads.ts`,
3205
+ * which would pull that module's import tree into this deliberately
3206
+ * import-light generator; `test/ai-review-threads.test.ts` binds the two.
3207
+ */
3208
+ export const AI_REVIEW_FORK_VAR = "RUNGATE_PR_IS_FORK";
3202
3209
 
3203
3210
  /**
3204
3211
  * The script the threads step runs.
@@ -3244,11 +3251,15 @@ export const AI_REVIEW_THREADS_TOKEN_VAR = "AI_REVIEW_THREADS_TOKEN";
3244
3251
  export function buildThreadsScript(version: string): string {
3245
3252
  const poster =
3246
3253
  `bunx ${AI_REVIEW_ADJUDICATOR_PACKAGE}@${version} ${AI_REVIEW_THREADS_COMMAND}`;
3247
- // Matched with `grep -qF` inside SINGLE quotes, where a double quote is
3248
- // literal and needs no escaping. The quotes are part of the signal:
3249
- // `bin/rungate.ts` prints the name quoted, and an unquoted match would
3250
- // also hit a findings summary that happened to mention the command.
3251
- const skew = `unknown command "${AI_REVIEW_THREADS_COMMAND}"`;
3254
+ // The WHOLE line `bin/rungate.ts` prints for an unknown command, matched
3255
+ // with `grep -qxF` (#2203). A substring match let the command's own
3256
+ // output satisfy it: a finding quoting the phrase turned a refusal into an
3257
+ // UNMEASURED exit 0. Since 0.8.21 (#1992) every line the command prints
3258
+ // from a finding is escaped and prefixed `ai-review-threads: `, so no
3259
+ // finding text can BE this line. The exit code cannot separate the cases:
3260
+ // the unknown-command path exits 1 like every refusal. Inside SINGLE
3261
+ // quotes below, where the double quotes are literal.
3262
+ const skew = `rungate: unknown command "${AI_REVIEW_THREADS_COMMAND}"`;
3252
3263
  return [
3253
3264
  `set -uo pipefail`,
3254
3265
  ``,
@@ -3274,7 +3285,7 @@ export function buildThreadsScript(version: string): string {
3274
3285
  ` --changed-files "\${${AI_REVIEW_CHANGED_FILES_PATH_VAR}}" 2>&1)" || threads_code=$?`,
3275
3286
  `printf '%s\\n' "$threads_out"`,
3276
3287
  ``,
3277
- `if [ "$threads_code" -ne 0 ] && printf '%s' "$threads_out" | grep -qF '${skew}'; then`,
3288
+ `if [ "$threads_code" -ne 0 ] && printf '%s\\n' "$threads_out" | grep -qxF '${skew}'; then`,
3278
3289
  ` echo "::warning title=AI review threads::UNMEASURED - rungate@${version} does not carry the ${AI_REVIEW_THREADS_COMMAND} command yet, so no review threads were posted. This workflow is ahead of the published package; it resolves itself on the next release."`,
3279
3290
  ` exit 0`,
3280
3291
  `fi`,
@@ -11695,6 +11706,11 @@ export function buildReviewRunStep(
11695
11706
  ` ${AI_REVIEW_THREADS_SHA_VAR}: \${{ github.event.pull_request.head.sha }}`,
11696
11707
  ` ${AI_REVIEW_THREADS_REPO_VAR}: \${{ github.repository }}`,
11697
11708
  ` ${AI_REVIEW_THREADS_TOKEN_VAR}: \${{ secrets.GITHUB_TOKEN }}`,
11709
+ // #1992/#2203: a 403 degrades only on a fork. GitHub evaluates this to
11710
+ // the string "true" or "false", which is exactly what the CLI reads. On
11711
+ // a merge_group run it reads "true", harmlessly: the script exits before
11712
+ // posting when there is no pull request.
11713
+ ` ${AI_REVIEW_FORK_VAR}: \${{ github.event.pull_request.head.repo.full_name != github.repository }}`,
11698
11714
  // AC-3. This step POSTS the threads, so it is the one that can create a
11699
11715
  // duplicate, and until now it was the only reader handed no suppression
11700
11716
  // gate — the adjudicator dropped a repeat from its annotation while this