rungate 0.8.12 → 0.8.13

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/bin/rungate.ts CHANGED
@@ -14,9 +14,23 @@ import { existsSync } from "fs";
14
14
  import { dirname, join, resolve } from "path";
15
15
  import { fileURLToPath } from "url";
16
16
  import { CLI_COMMANDS, helpText, runCommandScript } from "../lib/cli-commands";
17
+ import { harnessVersionLine } from "../lib/harness-identity";
17
18
 
18
19
  const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
19
20
 
21
+ // Say which version is running, before anything else can fail.
22
+ //
23
+ // On STDERR, and that is the whole design. `ai-review.yml` captures the
24
+ // adjudicator with `2>&1`, so this reaches the CI log either way and nothing
25
+ // is lost by keeping it off stdout — while stdout stays what a caller can
26
+ // parse. `--version` in particular exists to be read by a machine and must
27
+ // remain exactly one line.
28
+ //
29
+ // Emitted for every invocation including `--help` and an unknown command: the
30
+ // runs worth attributing are the ones that went wrong, and a banner that
31
+ // skips the failure paths is absent exactly when it is wanted.
32
+ console.error(harnessVersionLine(PACKAGE_ROOT));
33
+
20
34
  const [name, ...rest] = process.argv.slice(2);
21
35
 
22
36
  if (!name || name === "--help" || name === "-h" || name === "help") {
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 0c470ba3039b3a05fb26683dbd8a3320accfa01e18c78aa33e014017a86366bf
1
+ 747398b3ddaddadd72ae597e21f050587654bc584d2f72286d66b4c2a921e001
@@ -0,0 +1,237 @@
1
+ /**
2
+ * When a blocking issue closes, which of the issues it was blocking should
3
+ * move to Ready — and which should be left exactly where they are.
4
+ *
5
+ * #1744. Moves Claim 7, whose third falsification reads *"a board state
6
+ * reachable only by someone running a command by hand"*. Ready is that today:
7
+ * `board-mirror --ready --write` is the only thing that writes it, and a
8
+ * person has to remember.
9
+ *
10
+ * ## Why an Action at all
11
+ *
12
+ * Researched against docs.github.com on 2026-11-03. GitHub has no built-in
13
+ * workflow keyed on dependencies; `actions/add-to-project` takes only
14
+ * `project-url`, `github-token`, `labeled` and `label-operator` and **cannot
15
+ * set a field**. GitHub's own documented answer for this is a self-written
16
+ * Action driving `updateProjectV2ItemFieldValue`.
17
+ *
18
+ * There is also **no "became unblocked" event**. `issue_dependencies` exists
19
+ * as a webhook but is not a valid Actions `on:` trigger, and
20
+ * `blocked_by_removed` fires when somebody unlinks a dependency, not when the
21
+ * blocker closes. So the trigger is `issues: [closed]` and the fan-out walks
22
+ * that issue's `blocking` list. No cron — a schedule is the thing this exists
23
+ * to remove.
24
+ *
25
+ * GitHub roadmap **#1336 "Granular issue status"** is in public preview and
26
+ * would make this module dead code. That is a reason to keep it small, not a
27
+ * reason to wait.
28
+ *
29
+ * ## What this file deliberately does NOT do
30
+ *
31
+ * **It does not decide readiness.** `isReady` does, and it carries the
32
+ * phase-frontier rule that stopped the Ready lane holding 36 of 46 open
33
+ * issues. A second decider here would agree with it on every input anybody
34
+ * thought to test, so no behavioural case could tell which was live and a
35
+ * mutation of either would leave the other holding the case up. `BR-7`
36
+ * asserts the agreement across a 48-row grid rather than trusting the import.
37
+ *
38
+ * **It does not add anything to the board.** Membership is `board-mirror`'s.
39
+ * An Action that added items would make the board's contents depend on which
40
+ * issues happened to close.
41
+ */
42
+ import { isReady } from "./board-mirror";
43
+
44
+ /** One issue that the closed blocker was blocking. */
45
+ export interface Dependent {
46
+ readonly number: number;
47
+ /** `OPEN` or `CLOSED`, as GraphQL spells it. */
48
+ readonly state: string;
49
+ readonly phase: number | null;
50
+ /**
51
+ * OPEN blockers only — the lifetime count never goes back down.
52
+ *
53
+ * **`null` means the dependency summary could not be read**, which is not
54
+ * the same as zero. `issueDependenciesSummary` is absent on a response the
55
+ * token was not scoped for, and `?? 0` turned that into "nothing is
56
+ * blocking it" — a fail-open that moves a genuinely blocked issue to
57
+ * Ready. Caught in review of #1747.
58
+ */
59
+ readonly blockedByOpen: number | null;
60
+ /**
61
+ * **`null` means the assignee count could not be read**, exactly as above.
62
+ * `?? 0` here says "nobody has claimed it", and that is the direction that
63
+ * MOVES — an issue somebody is already working on lands in Ready. The
64
+ * sibling field was fixed for this and this one was left; caught in review
65
+ * of #1747, round 7.
66
+ */
67
+ readonly assignees: number | null;
68
+ /** Is this issue on the board at all? Membership is `board-mirror`'s. */
69
+ readonly onBoard: boolean;
70
+ /**
71
+ * The board column, or `null` when the item has no Status VALUE.
72
+ *
73
+ * Not the same question as `onBoard`, and the two were one field until
74
+ * review of #1747 round 6. GraphQL returns a
75
+ * `ProjectV2ItemFieldSingleSelectValue` node only for a field that already
76
+ * has a value, so an item added to the project and never given a Status
77
+ * returns no node — producing the same `null` as an issue that is not on
78
+ * the board. One of those means "board-mirror owns this, leave it"; the
79
+ * other means "it is here and I cannot see where".
80
+ */
81
+ readonly boardStatus: string | null;
82
+ }
83
+
84
+ export type FanoutDecision =
85
+ | { readonly number: number; readonly move: true }
86
+ | { readonly number: number; readonly move: false; readonly why: string };
87
+
88
+ /**
89
+ * Why `isReady` said no, for the log.
90
+ *
91
+ * **This explains a verdict; it never produces one.** It is only ever called
92
+ * after `isReady` has already returned false, so a wrong or incomplete reason
93
+ * costs a confusing log line and cannot move an issue. Keeping that ordering
94
+ * is what stops it becoming the second decider described above.
95
+ */
96
+ function whyNotReady(d: Dependent, frontier: number | null): string {
97
+ if (d.state !== "OPEN") return `the issue is ${d.state}`;
98
+ if (d.blockedByOpen === null) return "UNMEASURED — the dependency summary could not be read";
99
+ if (d.blockedByOpen > 0) {
100
+ return `${d.blockedByOpen} open blocker${d.blockedByOpen === 1 ? "" : "s"} remain`;
101
+ }
102
+ if (d.assignees === null) return "UNMEASURED — the assignee count could not be read";
103
+ if (d.assignees > 0) return "somebody has claimed it";
104
+ if (frontier === null) return "no phase has open work, so nothing is next";
105
+ if (d.phase === null) return "no phase milestone — it serves no criterion (ADR-003)";
106
+ if (d.phase !== frontier) return `phase ${d.phase} is behind the frontier at phase ${frontier}`;
107
+ return "isReady said no and this reason list did not anticipate it";
108
+ }
109
+
110
+ /**
111
+ * One decision per dependent. Writes nothing; the caller performs the moves.
112
+ */
113
+ export function fanoutDecisions(
114
+ dependents: readonly Dependent[],
115
+ frontier: number | null,
116
+ readyColumn: string,
117
+ ): FanoutDecision[] {
118
+ return dependents.map((d): FanoutDecision => {
119
+ if (!d.onBoard) {
120
+ return { number: d.number, move: false, why: "not on the board — board-mirror owns membership" };
121
+ }
122
+ // On the board, and no Status value. Distinct from the line above on
123
+ // purpose: the caller resolves the Status FIELD ID from the item's own
124
+ // value node, so an item that has never had a Status has nothing to
125
+ // write through. Saying "not on the board" sent the reader to
126
+ // board-mirror to add an item that was already there.
127
+ if (d.boardStatus === null) {
128
+ return {
129
+ number: d.number,
130
+ move: false,
131
+ why:
132
+ "UNMEASURED — it is on the board with no Status value, so there is no Status field id " +
133
+ "to write through. This is NOT absent from the board.",
134
+ };
135
+ }
136
+ if (d.boardStatus === readyColumn) {
137
+ return { number: d.number, move: false, why: `already ${readyColumn}` };
138
+ }
139
+ // An unreadable blocker count is UNMEASURED, and UNMEASURED never moves.
140
+ // It cannot be handed to `isReady`, whose parameter is a number and whose
141
+ // honest answer here does not exist — the question is unanswerable, not
142
+ // answered false. Refusing before the decider is what keeps `isReady` the
143
+ // only thing that says yes.
144
+ if (d.blockedByOpen === null || d.assignees === null) {
145
+ return { number: d.number, move: false, why: whyNotReady(d, frontier) };
146
+ }
147
+ const measured = { ...d, blockedByOpen: d.blockedByOpen, assignees: d.assignees };
148
+ if (!isReady(measured, frontier)) {
149
+ return { number: d.number, move: false, why: whyNotReady(d, frontier) };
150
+ }
151
+ return { number: d.number, move: true };
152
+ });
153
+ }
154
+
155
+ /** A GraphQL connection, as far as truncation is concerned. */
156
+ interface MaybeTruncated {
157
+ readonly pageInfo?: { readonly hasNextPage?: boolean } | null;
158
+ readonly nodes?: readonly unknown[] | null;
159
+ }
160
+
161
+ /**
162
+ * Which dependents had their board membership read only in part.
163
+ *
164
+ * `projectItems` and `fieldValues` are sub-selections inside a paginated
165
+ * list, so cursoring them costs a round trip per node and both are bounded
166
+ * in practice. **"Bounded in practice" is the reasoning that has been wrong
167
+ * four times on this day's work**, so it is not trusted: each is asked for
168
+ * with a `pageInfo`, and a truncated page is UNMEASURED.
169
+ *
170
+ * It matters because a Status field on page two and no Status field at all
171
+ * produce the same `undefined`, and one of those means "leave it alone"
172
+ * while the other means "I could not look".
173
+ */
174
+ export function truncatedReadings(
175
+ dependents: readonly { readonly number: number; readonly projectItems?: MaybeTruncated | null }[],
176
+ ): number[] {
177
+ return dependents
178
+ .filter(d => {
179
+ const items = d.projectItems;
180
+ if (items?.pageInfo?.hasNextPage === true) return true;
181
+ return (items?.nodes ?? []).some(
182
+ (n: any) => n?.fieldValues?.pageInfo?.hasNextPage === true,
183
+ );
184
+ })
185
+ .map(d => d.number);
186
+ }
187
+
188
+ /**
189
+ * May the identity that triggered this run cause a board write?
190
+ *
191
+ * The first version of this gate was an Actions `if:` reading
192
+ * `github.event.issue.author_association`, and review was right that it
193
+ * checks the wrong person: that field describes whoever OPENED the issue,
194
+ * never whoever closed it. The two differ in both directions and the
195
+ * ordinary direction is the damaging one — a maintainer closing an outside
196
+ * contributor's issue would have been refused, so the feature would have
197
+ * quietly not worked for exactly the issues most likely to come from
198
+ * outside.
199
+ *
200
+ * `repos/{repo}/collaborators/{actor}/permission` answers about the ACTOR.
201
+ * Its `permission` field is one of `admin`, `write`, `read`, `none`, and an
202
+ * unreadable response is `null` — which is UNMEASURED and refuses, because
203
+ * a permission we could not read is not a permission we were granted.
204
+ */
205
+ export const WRITING_PERMISSIONS: readonly string[] = ["admin", "write", "maintain"];
206
+
207
+ export function actorMayWrite(permission: string | null): boolean {
208
+ if (permission === null) return false;
209
+ return WRITING_PERMISSIONS.includes(permission);
210
+ }
211
+
212
+ /** The credential, or the reason there is no reading to report. */
213
+ export type CredentialReading =
214
+ | { readonly kind: "present"; readonly token: string }
215
+ | { readonly kind: "UNMEASURED"; readonly why: string };
216
+
217
+ /**
218
+ * `GITHUB_TOKEN` cannot write ProjectsV2, so this needs a PAT or a GitHub
219
+ * App. A run without one has not found nothing to move — it has not looked,
220
+ * and those are different states (`.claude/rules/config-access.md`).
221
+ *
222
+ * Whitespace is absence. A secret that was declared and left empty produces
223
+ * `""`, and treating that as a token turns the refusal into a 401 three calls
224
+ * later, where it reads as GitHub's problem.
225
+ */
226
+ export function readBoardCredential(env: Record<string, string | undefined>): CredentialReading {
227
+ const raw = (env.BOARD_PROJECT_TOKEN ?? "").trim();
228
+ if (raw === "") {
229
+ return {
230
+ kind: "UNMEASURED",
231
+ why:
232
+ "BOARD_PROJECT_TOKEN is not set. GITHUB_TOKEN cannot write ProjectsV2, " +
233
+ "so this run could not read or move anything — it is UNMEASURED, not clean.",
234
+ };
235
+ }
236
+ return { kind: "present", token: raw };
237
+ }
package/lib/github.ts CHANGED
@@ -20,6 +20,7 @@
20
20
 
21
21
  import { Octokit } from "@octokit/rest";
22
22
 
23
+
23
24
  // ── Types ──────────────────────────────────────────────────────────────────
24
25
 
25
26
  export interface GitHubClient {
@@ -193,31 +194,142 @@ export function createGitHubClient(): GitHubClient {
193
194
  * name hidden in the userinfo (`https://127.0.0.1@evil.com`) are both
194
195
  * refused. GitHub Enterprise needs a host outside this list and stays a
195
196
  * separate, deliberate decision rather than a side effect of a test seam.
197
+ *
198
+ * **A second caller is coming, and is not here yet** — a paginating reader
199
+ * following `Link: rel="next"`, which is a **response** header, so the host it
200
+ * names is chosen by whoever answered rather than by us. Same question,
201
+ * second input. That reader is `restAll()` in `scripts/work-status.ts` and it
202
+ * lands with #1740; this tree does not contain it.
203
+ *
204
+ * The check is therefore `tokenRefusalReason` below, exported so one decider
205
+ * can answer both: two copies of an allowlist are one guard with a dead twin,
206
+ * and no behavioural case can tell which half it exercised. Written in the
207
+ * future tense on purpose — the earlier wording said "appeared" and "both" of
208
+ * a tree holding one caller, and a reader going to check found nothing and
209
+ * could not tell a split from a sentence nobody updated.
210
+ *
211
+ * It stays in THIS file rather than moving to a leaf module, and the three
212
+ * red checks that settled it are worth recording: SC-528 binds the literals
213
+ * `loopback` and `url.hostname` to `lib/github.ts`, and #827's fixed-point
214
+ * battery copies this file into an `mkdtemp` alone, where a new relative
215
+ * import dies on module resolution — a mutant that fails to load reads as a
216
+ * refusal (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
196
217
  */
218
+ export function resolveApiBaseUrl(): string | undefined {
219
+ const raw = process.env.GITHUB_API_URL?.trim();
220
+ if (!raw) return undefined;
221
+ const reason = tokenRefusalReason(raw);
222
+ if (reason !== null) throw new Error(`GITHUB_API_URL ${reason}`);
223
+ return raw;
224
+ }
225
+
226
+ /**
227
+ * GitHub itself, or a port on this machine. Nothing else.
228
+ *
229
+ * Hostname is compared **exactly**, and the userinfo fields are checked
230
+ * separately — `https://127.0.0.1@evil.com` has hostname `evil.com`, and
231
+ * `https://evil.com@api.github.com` has an allowed hostname while still
232
+ * sending credentials nobody wrote. Neither may pass.
233
+ */
234
+ // BRACKETED ONLY. These are compared against `url.hostname`, and WHATWG
235
+ // always brackets an IPv6 host — `http://[::1]/x` and the longhand
236
+ // `http://[0:0:0:0:0:0:0:1]/x` both yield `"[::1]"`, and `http://::1/x` is
237
+ // not a parseable URL at all. An unbracketed `"::1"` was here and matched
238
+ // nothing; its removal changes no outcome, which is why the row that holds
239
+ // this is a source assertion rather than a behavioural case.
240
+ const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
241
+
197
242
  const ALLOWED_API_HOSTS = new Set([
198
243
  "api.github.com",
199
244
  "github.com",
200
- "localhost",
201
- "127.0.0.1",
202
- "[::1]",
203
- "::1",
245
+ ...LOOPBACK_HOSTS,
204
246
  ]);
205
247
 
206
- export function resolveApiBaseUrl(): string | undefined {
207
- const raw = process.env.GITHUB_API_URL?.trim();
208
- if (!raw) return undefined;
248
+ /**
249
+ * Why this URL may not carry our bearer token, or `null` when it may.
250
+ *
251
+ * One decider, and these are its callers as this tree actually stands:
252
+ *
253
+ * | caller | where | passes `base` |
254
+ * |---|---|---|
255
+ * | `resolveApiBaseUrl` | ABOVE, over `GITHUB_API_URL` | no |
256
+ * | `assertTokenMayReach` | BELOW, the throwing wrapper | yes, passes through |
257
+ * | `test/token-host-allowlist.test.ts` | the suite | yes, directly |
258
+ *
259
+ * `assertTokenMayReach` has **no in-tree production caller**. It is the entry
260
+ * point `restAll()` in `scripts/work-status.ts` will use, and that lands with
261
+ * #1740 — so today only the suite reaches it, and only the suite exercises
262
+ * `base`, which resolves a relative `Link: rel="next"` against the page it
263
+ * arrived on.
264
+ *
265
+ * Spelled out as a table because prose got it wrong twice: once naming
266
+ * `scripts/work-status.ts` as a current input when this tree lacks the file,
267
+ * and once naming `assertTokenMayReach` as the `GITHUB_API_URL` caller — the
268
+ * wrong function, in the wrong direction, and the one with no caller at all.
269
+ */
270
+ export function tokenRefusalReason(raw: string, base?: string): string | null {
209
271
  let url: URL;
210
272
  try {
211
- url = new URL(raw);
273
+ url = new URL(raw, base);
212
274
  } catch {
213
- throw new Error(`GITHUB_API_URL is not a valid URL: ${raw}`);
275
+ return `is not a valid URL: ${raw}`;
214
276
  }
277
+ // **The host check is first, and the order is asserted.** Every refusal
278
+ // here is a refusal whatever the order, so this is about the REASON, and a
279
+ // reason is the only part of a refusal anybody reads. `http://evil.com` and
280
+ // `https://127.0.0.1@evil.com` are host problems that also happen to be a
281
+ // scheme problem and a userinfo problem; reporting the incidental one sends
282
+ // the reader to fix the wrong thing. The existing cases in
283
+ // `test/github-client.test.ts` match on `/loopback/` and caught exactly
284
+ // this when the scheme check was added above them.
215
285
  if (!ALLOWED_API_HOSTS.has(url.hostname)) {
216
- throw new Error(
217
- `GITHUB_API_URL may only point at GitHub or loopback — refusing to send a token to ${url.hostname}`,
218
- );
286
+ return `may only point at GitHub or loopback — refusing to send a token to ${url.hostname}`;
219
287
  }
220
- return raw;
288
+ // `https://evil.com@api.github.com` has an ALLOWED hostname and still sends
289
+ // credentials nobody wrote, so this cannot be folded into the check above.
290
+ if (url.username || url.password) {
291
+ return `refuses to send a token to a URL carrying userinfo: ${url.host}`;
292
+ }
293
+ // THE SCHEME IS CHECKED WITHOUT REFERENCE TO THE HOST, and the single
294
+ // condition below used to do both at once:
295
+ //
296
+ // url.protocol !== "https:" && !LOOPBACK_HOSTS.has(url.hostname)
297
+ //
298
+ // which is a conjunction, so a loopback host short-circuited the scheme
299
+ // test away entirely. `ftp://127.0.0.1/x`, `ws://localhost/x` and
300
+ // `gopher://[::1]/x` all returned null. The documented contract is "https
301
+ // everywhere, plain http only for loopback"; what was implemented was "any
302
+ // scheme at all for loopback".
303
+ //
304
+ // It survived six rounds of review on #1740 because the two cases around
305
+ // it each vary one axis and the gap sits on the pair neither visits: one
306
+ // tries a bad scheme on a REAL host, the other tries `http:` on LOOPBACK.
307
+ // Nothing tried a bad scheme on loopback until round 12 read the
308
+ // conjunction itself (`.claude/rules/checks-must-be-able-to-fail.md`, the
309
+ // seventh shape).
310
+ if (url.protocol !== "https:" && url.protocol !== "http:") {
311
+ return `refuses to send a token over ${url.protocol}// to ${url.hostname}`;
312
+ }
313
+ // An allowed hostname over cleartext still puts the token on the wire.
314
+ // `http://api.github.com/x` passes every check above. Loopback keeps
315
+ // `http:` on purpose — a local test server has no certificate and the
316
+ // token never leaves the machine.
317
+ if (url.protocol !== "https:" && !LOOPBACK_HOSTS.has(url.hostname)) {
318
+ return `refuses to send a token over ${url.protocol}// to ${url.hostname}`;
319
+ }
320
+ return null;
321
+ }
322
+
323
+ /**
324
+ * Throw unless this URL may carry the token. `context` names where the URL
325
+ * came from, because "refused" is only actionable when the reader knows which
326
+ * input produced it — an environment variable and a response header are
327
+ * repaired differently.
328
+ */
329
+ export function assertTokenMayReach(raw: string, context: string, base?: string): URL {
330
+ const reason = tokenRefusalReason(raw, base);
331
+ if (reason !== null) throw new Error(`${context} ${reason}`);
332
+ return new URL(raw, base);
221
333
  }
222
334
 
223
335
  /**
@@ -240,9 +352,18 @@ export function resolveApiBaseUrl(): string | undefined {
240
352
  * exported-but-unset variable must produce the clear error here rather than
241
353
  * an unauthenticated client that 401s somewhere less obvious.
242
354
  */
243
- export function resolveGitHubToken(): string | undefined {
355
+ export function resolveGitHubToken(
356
+ // Injectable so a second implementation can be asserted to AGREE with this
357
+ // one on the same inputs. `scripts/check-state-record-closes.ts` must stay
358
+ // import-free — `test/state-record-closes-mutation.test.ts` asserts it,
359
+ // because its mutants run from a temp directory and a relative import
360
+ // makes every one of them die on module resolution, which reads as a
361
+ // refusal on the merits. So that file cannot call this; the next best
362
+ // thing is that the two cannot silently disagree.
363
+ env: Record<string, string | undefined> = process.env,
364
+ ): string | undefined {
244
365
  for (const name of ["GITHUB_TOKEN", "GH_TOKEN"]) {
245
- const v = process.env[name];
366
+ const v = env[name];
246
367
  // Trimmed, not just tested: `GH_TOKEN=$(cat token)` carries a trailing
247
368
  // newline, and Octokit sends it in the Authorization header, where it
248
369
  // 401s with nothing pointing at the whitespace as the cause.
@@ -43,6 +43,62 @@ import { join } from "path";
43
43
  /** The harness's own package name. The one fact this module knows. */
44
44
  export const HARNESS_PACKAGE = "rungate";
45
45
 
46
+ /**
47
+ * What the CLI says about itself before it does anything (#1598 follow-up).
48
+ *
49
+ * ## The reading this exists to make possible
50
+ *
51
+ * CI invokes the adjudicator as `bunx rungate@<version>`, and the version in
52
+ * that command is **authored text**. It is written into
53
+ * `.github/workflows/ai-review.yml` by the scaffold at generation time, and
54
+ * it is written again into the `::notice` annotation that quotes the command
55
+ * back to the reader. So a log can carry the string `rungate@0.8.4` three
56
+ * times and still not contain a single resolved reading of which version ran.
57
+ *
58
+ * That is not hypothetical. On 2026-10-24 three consecutive attempts to
59
+ * establish a version from a run log were wrong in the same direction, each
60
+ * correction finding the next layer:
61
+ *
62
+ * | the reading | why it cannot attribute a version |
63
+ * |---|---|
64
+ * | grep the log for `rungate@0.8.x` | matches the PR body, echoed by the round-counting step |
65
+ * | the same grep with colour codes excluded | still matches the annotation, which is authored |
66
+ * | bun's resolve block above the adjudication | prints `Resolved, downloaded and extracted [76]` — a count, no name, no version |
67
+ *
68
+ * The version had to be recovered from outside the log entirely, by reading
69
+ * the pin out of `ai-review.yml` at main's commit as of the run's
70
+ * `createdAt`. That works and it is three readings, two of which are easy to
71
+ * take against the wrong tree — `refs/pull/<N>/merge` is recomputed when main
72
+ * moves, so it describes a tree the run never saw.
73
+ *
74
+ * One line printed by the running process collapses all three into one.
75
+ *
76
+ * ## Why the spelling is deliberately not the pin's
77
+ *
78
+ * `rungate-version:` rather than `rungate@<v>`. If the announcement used the
79
+ * pin's spelling, a grep for a resolved value would match authored text again
80
+ * and this would have bought nothing — the defect reproduced inside its own
81
+ * fix. The marker is the discriminator; the version is the payload.
82
+ *
83
+ * ## UNMEASURED rather than a plausible default
84
+ *
85
+ * An unreadable or version-less `package.json` returns `UNMEASURED`, not a
86
+ * guess and not an empty string. A version that could not be read must not be
87
+ * spelled the same as one that could — `.claude/rules/config-access.md`,
88
+ * *Silent Default Substitution*. It does not throw: a CLI that dies because
89
+ * it could not introduce itself is worse than one that cannot.
90
+ */
91
+ export function harnessVersionLine(root: string): string {
92
+ let version: unknown;
93
+ try {
94
+ version = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))?.version;
95
+ } catch {
96
+ version = undefined;
97
+ }
98
+ const resolved = typeof version === "string" && version.length > 0 ? version : "UNMEASURED";
99
+ return `rungate-version: ${resolved} (resolved at runtime, not the pin)`;
100
+ }
101
+
46
102
  export function isHarnessItself(root: string): boolean {
47
103
  try {
48
104
  return JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))?.name === HARNESS_PACKAGE;
@@ -1016,6 +1016,25 @@ export interface AiReviewThreadRequest {
1016
1016
  * a hunk, which is a separate 422 the caller has to be able to fall back
1017
1017
  * from. Dropping here would silently lose findings whose only defect is that
1018
1018
  * the reviewer wrote no line number.
1019
+ *
1020
+ * **A finding whose file is not in the diff is not requested, blocking or
1021
+ * not.** `unlocatableReported` is populated by `readPayload`'s DEMOTION
1022
+ * branch, and that branch only runs for a finding that BLOCKS — so the
1023
+ * subtraction above cannot see a non-blocking finding carried forward onto a
1024
+ * path this branch has since stopped touching. It was sent, and GitHub
1025
+ * answered `422 pull_request_review_thread.path "could not be resolved"` at
1026
+ * the line AND again at file level, because the caller's demotion answers
1027
+ * "the line moved" and has no answer for "the file left". That lands in
1028
+ * `failed`, the one refusing outcome. Observed on #1740 head
1029
+ * `1d95e1da457cf5fc91298bd017a94087b8244d46`, run `41950364518`: two carried
1030
+ * findings on `lib/github.ts`, `0 of 2 posted`, exit 1, and a required check
1031
+ * permanently red over a branch with nothing wrong in it.
1032
+ *
1033
+ * The two skips are NOT the fourth shape in
1034
+ * `.claude/rules/checks-must-be-able-to-fail.md`, because each has an input
1035
+ * the other cannot answer: a MEASURED scope with `unlocatableReported` null
1036
+ * is reachable only by the scope check, and a reading carrying no scope with
1037
+ * `unlocatableReported` set is reachable only by the subtraction.
1019
1038
  */
1020
1039
  export function reviewThreadRequests(
1021
1040
  reading: AiReviewFindingsReading,
@@ -1025,11 +1044,31 @@ export function reviewThreadRequests(
1025
1044
  if (reading.reported === null) return [];
1026
1045
  const unlocatable = new Set(reading.unlocatableReported ?? []);
1027
1046
 
1047
+ // Only a scope that was TAKEN can retire anything. `NOT_SUPPLIED` and
1048
+ // `UNMEASURED` leave `touched` null, which `findingPathScope` answers
1049
+ // `NOT_CHECKED` for every finding — a reading nobody took is not a pull
1050
+ // request that touched nothing, and must never become a blanket excuse for
1051
+ // posting less.
1052
+ const scope = reading.scope;
1053
+ let touched: ReadonlySet<string> | null = null;
1054
+ if (scope?.status === "MEASURED") {
1055
+ // The same conversion `readPayload` makes, through the same function, so
1056
+ // the skip here and the demotion there cannot disagree about one finding.
1057
+ const { readable } = partitionChangedFiles(scope.files);
1058
+ // Nothing readable left is the input `readPayload` refuses the whole
1059
+ // reading over, for the reason stated there: comparing against it would
1060
+ // retire every finding. Here the equivalent is to decide nothing.
1061
+ if (readable.length > 0) touched = new Set(readable);
1062
+ }
1063
+
1028
1064
  const requests: AiReviewThreadRequest[] = [];
1029
1065
  for (const item of reading.reported) {
1030
1066
  if (unlocatable.has(item)) continue;
1031
1067
  if (typeof item !== "object" || item === null) continue;
1032
1068
  const finding = item as Record<string, unknown>;
1069
+ // `PRE_EXISTING` only. `UNDECIDABLE` is a path this reader could not
1070
+ // compare, and it keeps the behaviour the line below already gives it.
1071
+ if (findingPathScope(finding, touched) === "PRE_EXISTING") continue;
1033
1072
 
1034
1073
  const raw = finding[f.file];
1035
1074
  // Readability is asked of the normalised spelling; the answer is carried
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.12",
3
+ "version": "0.8.13",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {