rungate 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -21,20 +21,40 @@
21
21
  * This module is the counting and the comparison; `gates/gate-executor.ts`
22
22
  * holds the refusal and decides when to bank a new reading.
23
23
  *
24
- * ## What this guard does NOT do, stated rather than implied
24
+ * ## The erasure this used to permit, and what closed it (#494)
25
25
  *
26
26
  * The banked census lives in the run's `workflow-state.json`, which is a
27
- * file the heal agent can write. A heal agent that deleted a test AND the
28
- * census would see `first-reading` on the next round and pass. This guard
29
- * raises the cost of an accidental deletion, which is the failure mode that
30
- * actually happened on `wf_5cdce852-1e2`; it is not tamper-evident against a
31
- * deliberate one, and `writeWorkflowState`'s Zod validation does not make it
32
- * so, because an absent optional key is valid.
33
- *
34
- * Closing that properly means putting the reading somewhere the guarded
35
- * party does not write — the witness, or an HMAC over it — and is filed
36
- * separately rather than half-done here. A guard whose limit is written down
37
- * is a guard somebody can finish; one whose limit is implied is one everybody
27
+ * file the heal agent can write — `workflows/ship.js` hands it the file by
28
+ * name, with a working `writeWorkflowState` recipe. A heal agent that
29
+ * deleted a test AND the census saw `first-reading` on the next round and
30
+ * passed, because `first-reading` increments neither `fails` nor `warns`.
31
+ * `writeWorkflowState`'s Zod validation did not help: an absent optional
32
+ * key is valid.
33
+ *
34
+ * Since #494 the gate SIGNS the banked census — `signCensus` in
35
+ * `gates/witness.ts`, HMAC over the sorted reading and the run's slug —
36
+ * and stores the signature beside it. The signature alone cannot close the
37
+ * hole, because an agent erasing the census erases the signature with it
38
+ * and the two absences are identical. The second half is a fact the state
39
+ * file does not hold: `~/.rungate/<slug>/witnesses/`, written by
40
+ * `writeWitness` on every gate run and named by no prompt. An unsigned or
41
+ * mismatched census where a witness already exists is UNMEASURED, which is
42
+ * a WARN in this gate, and no longer a first reading.
43
+ *
44
+ * ## What it still does NOT do, stated rather than implied
45
+ *
46
+ * Tamper-EVIDENT, not tamper-proof, and that is the intended goal. The gate
47
+ * salt is readable by anything running as this user, so an agent that knows
48
+ * where it lives can re-sign a census it rewrote. It can also delete the
49
+ * witness directory, which puts the run back to looking like a first round.
50
+ * Both are a different and louder act than deleting a key out of a file the
51
+ * prompt told it to edit, and neither is what the accidental deletion on
52
+ * `wf_5cdce852-1e2` looked like.
53
+ *
54
+ * Closing THAT means a store the run cannot write at all — an append-only
55
+ * log off the machine, or a signing key the gate process does not hold.
56
+ * Filed rather than half-done here. A guard whose limit is written down is
57
+ * a guard somebody can finish; one whose limit is implied is one everybody
38
58
  * assumes is complete.
39
59
  *
40
60
  * ## Why a declaration count and not a run
@@ -52,6 +72,7 @@
52
72
  */
53
73
  import { existsSync, readdirSync, readFileSync, statSync } from "fs";
54
74
  import { join } from "path";
75
+ import { testDeclarations } from "./test-case-bodies";
55
76
 
56
77
  /**
57
78
  * Directories a census never walks into.
@@ -101,30 +122,77 @@ const TEST_FILE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/;
101
122
  export const MAX_CENSUS_FILE_BYTES = 2_000_000;
102
123
 
103
124
  /**
104
- * Declaration forms bun recognises. `test` and `it`, bare or with a modifier.
105
- *
106
- * Anchored on a word boundary so `subtest(` and `omit(` do not count, and
107
- * requiring the open paren so a bare mention in prose does not. The modifier
108
- * list is explicit rather than `\w+` because `test.each(...)(...)` and a
109
- * hypothetical `test.anything` should not silently start counting — an
110
- * unrecognised form is better as a miss we can see than as a count nobody
111
- * can explain.
125
+ * Which reader took a census, stamped beside it (#883).
126
+ *
127
+ * A census is BANKED per run and compared round to round, so the first round
128
+ * after this module's reader changes compares an old number against a new
129
+ * one and every file whose count moved reads as a regression. A reading
130
+ * taken with a different instrument is not comparable with one taken by
131
+ * this one, and the honest answer to an incomparable pair is UNMEASURED
132
+ * rather than either verdict.
133
+ *
134
+ * `"1"` is the pre-#883 reader and is never written — a banked census with
135
+ * no stamp IS version 1, which is how the migration is detected at all.
136
+ *
137
+ * **Bump this whenever `testDeclarations` changes what it counts.** Not when
138
+ * it changes how it is spelled: the stamp is about comparability of numbers,
139
+ * and a refactor that moves no count costs every in-flight run a round of
140
+ * UNMEASURED for nothing.
141
+ *
142
+ * **It IS covered by the signature, and the first draft of #883 said the
143
+ * opposite.** That draft's docblock read *"It is NOT a security control…
144
+ * the stamp is not covered by `signCensus`, so an agent that can edit the
145
+ * state file can edit it — but that agent can already delete the census
146
+ * outright."* Both halves are wrong, and writing the sentence is what
147
+ * stopped the question being asked:
148
+ *
149
+ * - Flipping this one byte is CHEAPER than deleting the census and much
150
+ * quieter. The census still verifies, so the round reports a WARN whose
151
+ * text explains an ordinary migration and refuses nothing.
152
+ * - `nextCensus` banks the current reading on a reader change, by design —
153
+ * so the lowered count becomes the baseline and the NEXT round is clean.
154
+ * The erasure #494 exists to catch is laundered into the record.
155
+ *
156
+ * `signStampedCensus` in `gates/witness.ts` signs the census and this stamp
157
+ * together. A forged or deleted stamp reads `unverified`; an absent one is
158
+ * checked against the v1 payload, which is what a real pre-#883 file has.
159
+ * Still tamper-evident rather than tamper-proof: the boundary is the salt.
112
160
  */
113
- const DECLARATION =
114
- /(?<![.\w$])(?:test|it)(?:\.(?:skip|todo|only|failing|each|skipIf|todoIf|only))?\s*[(`]/g;
161
+ export const TEST_CENSUS_READER = "2";
115
162
 
116
163
  /**
117
164
  * How many tests a source file declares.
118
165
  *
119
- * Comments are NOT stripped. A commented-out test is a removed test, and
120
- * stripping would make "comment the block out" a way past the guard. The
121
- * cost is that prose saying `test(` counts, which inflates a file's number
122
- * — and inflation is harmless here, because only a DECREASE is refused.
123
- * The one direction this may be wrong in is toward not refusing, which is
124
- * the direction a guard over somebody else's edits has to be wrong in.
166
+ * A projection of `testDeclarations`, which is the one binding deciding what
167
+ * a declaration is (#883). Before that it had its own expression, and the
168
+ * two disagreed on 174 of this tree's 483 test files: `gates/gate-executor.ts`
169
+ * refused a round on THIS count while the deletion reading named cases from
170
+ * the other, so an operator handed *"30 test(s) before, 27 after"* beside a
171
+ * list of 8 case names could not reconcile them.
172
+ *
173
+ * ## Comments ARE excluded now, and the old rationale was backwards
174
+ *
175
+ * This docblock used to read:
176
+ *
177
+ * > Comments are NOT stripped. A commented-out test is a removed test, and
178
+ * > stripping would make "comment the block out" a way past the guard.
179
+ *
180
+ * The second sentence is inverted, and it is worth leaving the correction
181
+ * here rather than quietly deleting it. Only a DECREASE is refused. With
182
+ * comments counted, commenting a test out leaves the number unchanged, so
183
+ * the guard does not fire — the hole the sentence describes was the one the
184
+ * policy created. Measured on the pre-#883 reader:
185
+ *
186
+ * countTestDeclarations('test("a", () => {})') → 1
187
+ * countTestDeclarations('// test("a", () => {})') → 1
188
+ *
189
+ * Excluding comments makes the count drop, which is exactly the refusal the
190
+ * guard exists for. The same scan also excludes a `test(` sequence inside a
191
+ * string, a template or a regex, which is where ~225 of the old reader's 443
192
+ * extra matches on this tree came from — prose, counted as coverage.
125
193
  */
126
194
  export function countTestDeclarations(source: string): number {
127
- return [...source.matchAll(DECLARATION)].length;
195
+ return testDeclarations(source).length;
128
196
  }
129
197
 
130
198
  /**
@@ -0,0 +1,274 @@
1
+ /**
2
+ * Every position in a tree that NAMES the project's test command, and the
3
+ * comparison between them (#621, #626 category 1, relocated here by #637).
4
+ *
5
+ * ## Why this is a library module and not a section of a script
6
+ *
7
+ * It was written inside `test/test-command-agreement.test.ts` (#621), moved
8
+ * into `scripts/contract-parity.ts` when the parity check came to need it
9
+ * (#626), and moved HERE by #637 — because a script cannot be imported by a
10
+ * script, and the moment a second consumer appears the only two options are an
11
+ * importable module or a second copy. A second copy of the three extractors is
12
+ * a producer and a consumer that must agree with nothing comparing them, which
13
+ * is the exact defect this whole family of checks exists to find.
14
+ *
15
+ * `lib/` is the position that makes the question answerable in one place:
16
+ * `test/test-command-agreement.test.ts`, `test/ci-global-tools.test.ts`,
17
+ * `test/contract-parity.test.ts` and `scripts/contract-parity.ts` all import
18
+ * these bindings from here, and there is one site to mutate.
19
+ *
20
+ * ## The decider this is NOT a second copy of
21
+ *
22
+ * `lib/test-command.ts`'s `testCommandDecision` answers "what command should
23
+ * this project RUN", with a config rung, a `package.json` rung and a default.
24
+ * This module answers "what command does each position in the tree SAY", which
25
+ * is a different question with a different failure mode: the decision has to
26
+ * produce an answer for every project, and this has to refuse when a position
27
+ * says nothing.
28
+ *
29
+ * They are not two deciders that agree, and the input that proves it is a tree
30
+ * with `test.command` set, no `dev.testCmd`, and a `package.json` `scripts.test`
31
+ * naming something else: `testCommandsNamedByConfig` reports `test.command` and
32
+ * `testCommandDecision` reports the package script. `commandParity` reads both
33
+ * on purpose, and a disagreement between them is a finding rather than noise.
34
+ *
35
+ * ## Where `suiteJobName` lives, and why it is not here
36
+ *
37
+ * #735 made `lib/ci-checkout.ts`'s `suiteJobName` the one binding for "which
38
+ * job in a generated `ci.yml` runs the suite" — `test` normally, `test-shard`
39
+ * under a matrix, where `test` becomes an aggregate that runs nothing. It was
40
+ * exported precisely so `scripts/contract-parity.ts` could ask rather than
41
+ * carry a copy.
42
+ *
43
+ * The CI extractor moved here, so the IMPORT moved with it and
44
+ * `scripts/contract-parity.ts` no longer names `suiteJobName` at all — its
45
+ * only use there was inside the function below. That is the same arrangement
46
+ * #735 asked for, one position further out: one declaration in
47
+ * `lib/ci-checkout.ts`, one consumer here, nothing to disagree. Leaving the
48
+ * import behind in the script would have been an unused specifier, not a
49
+ * second reader, but it would also have been the first thing to tempt someone
50
+ * into re-adding a local copy.
51
+ *
52
+ * ## Finding nothing in every file is perfect agreement
53
+ *
54
+ * Zero strings are trivially all equal, so every extractor here REFUSES when it
55
+ * finds no command rather than returning `[]`, and the refusal is let out of
56
+ * `testCommandAgreement` rather than folded into an empty violation list. A
57
+ * template edit that moves a table row or renames a CI step must turn this red,
58
+ * not quiet (`.claude/rules/checks-must-be-able-to-fail.md`, third shape).
59
+ */
60
+ import { existsSync, readFileSync } from "fs";
61
+ import { join } from "path";
62
+ import { suiteJobName } from "./ci-checkout";
63
+ import { RUNGATE_CONFIG_RELATIVE_PATH, resolveConfig } from "./config-loader";
64
+
65
+ /**
66
+ * The three positions compared, as repo-relative paths.
67
+ *
68
+ * `CONFIG_JSON` is a LABEL, not a path: the config's location is asked of
69
+ * `lib/config-loader.ts` (`rungateConfigPath` below), because this repository
70
+ * supports two layouts indefinitely and a reader that knows only the directory
71
+ * form silently gets nothing from a consumer on the monolith
72
+ * (`.claude/rules/config-access.md`, and CONFIG-1 enforces it).
73
+ */
74
+ export const AGENTS_MD = "AGENTS.md";
75
+ export const CONFIG_JSON = RUNGATE_CONFIG_RELATIVE_PATH;
76
+ export const CI_YML = join(".github", "workflows", "ci.yml");
77
+ export const AGREEMENT_FILES = [AGENTS_MD, CONFIG_JSON, CI_YML] as const;
78
+
79
+ /**
80
+ * Where this project's rungate config actually is, or null when it has none.
81
+ *
82
+ * Through `resolveConfig`, so both layouts are honoured and a corrupt config
83
+ * THROWS rather than arriving as an absent one — the distinction #70 lost for
84
+ * a month, and the one #626 AC-4 keeps as two separate UNMEASURED kinds.
85
+ */
86
+ export function rungateConfigPath(root: string): string | null {
87
+ const resolution = resolveConfig(root);
88
+ if (resolution.status === "absent") return null;
89
+ return resolution.source === "directory" ? join(resolution.path, "config.json") : resolution.path;
90
+ }
91
+
92
+ /** One test command, and the position in the tree that names it. */
93
+ export interface NamedTestCommand {
94
+ /** Repo-relative path. */
95
+ file: string;
96
+ /** Where inside the file — the row, the field, the step. */
97
+ where: string;
98
+ command: string;
99
+ }
100
+
101
+ /** Thrown when a file this check reads names no test command at all. */
102
+ export class NoTestCommandError extends Error {}
103
+
104
+ function refuse(file: string, why: string): never {
105
+ throw new NoTestCommandError(
106
+ `${file} names no test command: ${why}. ` +
107
+ `Three files naming nothing are not three files that agree — ` +
108
+ `see .claude/rules/checks-must-be-able-to-fail.md.`,
109
+ );
110
+ }
111
+
112
+ /**
113
+ * The `| Test | \`…\` |` row of AGENTS.md's Commands table.
114
+ *
115
+ * The cell must be exactly `Test`: `Test as CI sees it` is a different command
116
+ * on purpose, and matching it here would make the check compare a row against
117
+ * itself. The section is sliced out first — asserting against the whole
118
+ * document is how a claim about one section gets satisfied by a match
119
+ * somewhere else (#297, #484, #60).
120
+ */
121
+ export function testCommandsNamedByAgentsMd(text: string): NamedTestCommand[] {
122
+ const start = text.indexOf("\n## Commands");
123
+ if (start === -1) refuse(AGENTS_MD, "it has no `## Commands` section");
124
+ const rest = text.slice(start + 1);
125
+ const end = rest.indexOf("\n## ", 1);
126
+ const section = end === -1 ? rest : rest.slice(0, end);
127
+ if (section.trim() === "") refuse(AGENTS_MD, "its `## Commands` section is empty");
128
+
129
+ const row = /^\|\s*Test\s*\|\s*`([^`]+)`\s*\|/m.exec(section);
130
+ if (!row) refuse(AGENTS_MD, "its Commands table has no `| Test | \\`…\\` |` row");
131
+ return [{ file: AGENTS_MD, where: "the Commands table's Test row", command: row![1].trim() }];
132
+ }
133
+
134
+ /**
135
+ * The `**Test:** \`…\`` line of AGENTS.md's Workflow section.
136
+ *
137
+ * A second position in the same generated file, and the reason the slice above
138
+ * matters: the two have always agreed here, so the live tree cannot witness a
139
+ * reader that confuses them.
140
+ */
141
+ export function testCommandNamedByAgentsWorkflow(text: string): NamedTestCommand[] {
142
+ const line = /^\s*-?\s*\*\*Test:\*\*\s*`([^`]+)`/m.exec(text);
143
+ return line ? [{ file: AGENTS_MD, where: "the Workflow section's Test line", command: line[1].trim() }] : [];
144
+ }
145
+
146
+ /**
147
+ * Every test command the rungate config declares.
148
+ *
149
+ * Both fields, because both are read: `test.command` is what the ship run
150
+ * measures with (`workflows/ship.js`, which cannot import — #69) and
151
+ * `dev.testCmd` is the top rung of `lib/test-command.ts`, which is what the
152
+ * scaffold writes into AGENTS.md and CI.
153
+ */
154
+ export function testCommandsNamedByConfig(text: string): NamedTestCommand[] {
155
+ // Deliberately not caught: a corrupt config is never a missing config
156
+ // (.claude/rules/config-access.md).
157
+ const config = JSON.parse(text) as { test?: { command?: unknown }; dev?: { testCmd?: unknown } };
158
+ const found: NamedTestCommand[] = [];
159
+ const declared = (where: string, value: unknown) => {
160
+ if (typeof value === "string" && value.trim() !== "") {
161
+ found.push({ file: CONFIG_JSON, where, command: value.trim() });
162
+ }
163
+ };
164
+ declared("test.command", config?.test?.command);
165
+ declared("dev.testCmd", config?.dev?.testCmd);
166
+ if (found.length === 0) refuse(CONFIG_JSON, "neither `test.command` nor `dev.testCmd` is set");
167
+ return found;
168
+ }
169
+
170
+ /**
171
+ * Steps that are part of running CI but are not the project's test command.
172
+ * Named rather than positional: "the second run step" is a proxy, and a proxy
173
+ * is a thing a template edit can satisfy while the property breaks.
174
+ */
175
+ const NOT_THE_TEST_STEP = new Set(["bun install", "bun run typecheck"]);
176
+
177
+ /**
178
+ * The shard selector is a CI PARTITION, not a different test command (#735).
179
+ *
180
+ * `bun test --shard=2/4` runs a quarter of the files of `bun test`; it does
181
+ * not run them differently. The property #621 protects is that one command
182
+ * is named everywhere, and appending a partition selector in CI does not
183
+ * break it — but comparing the raw strings says it does, and the cheap fix
184
+ * for that red is to add the sharded spelling to AGENTS.md, which would put
185
+ * a CI-only flag in the row a human copies to run the suite locally.
186
+ *
187
+ * Stripped only at the END and only with a `N/M` argument, so a command that
188
+ * genuinely differs before the flag still disagrees.
189
+ *
190
+ * `\S+` will not do for the numerator: the generated value is the GitHub
191
+ * expression `${{ matrix.shard }}`, which contains spaces.
192
+ */
193
+ const SHARD_SELECTOR = /\s+--shard=.+?\/\d+\s*$/;
194
+
195
+ /** The test step of the generated suite job in ci.yml. */
196
+ export function testCommandsNamedByCiWorkflow(text: string): NamedTestCommand[] {
197
+ // `suiteJobName` is the one binding for "which job runs the suite" — it is
198
+ // `test` normally and `test-shard` under a matrix, where `test` becomes the
199
+ // aggregate and runs no tests at all. A second copy of that rule here would
200
+ // survive any mutation of the first and both would read as covered.
201
+ const anchor = `\n ${suiteJobName(text)}:`;
202
+ const start = text.indexOf(anchor);
203
+ if (start === -1) refuse(CI_YML, "it has no `test:` job");
204
+ const rest = text.slice(start + 1);
205
+ // The next job at the same indent ends this one. Jobs a consumer added are
206
+ // theirs (#216) and must not be read as this project's test command.
207
+ const head = anchor.slice(1);
208
+ const end = /\n {2}[A-Za-z_][\w-]*:/.exec(rest.slice(head.length));
209
+ const job = end === null ? rest : rest.slice(0, head.length + end.index);
210
+ if (job.trim() === "") refuse(CI_YML, "its `test:` job is empty");
211
+
212
+ const runs = job
213
+ .split("\n")
214
+ .map(line => /^\s+- run:\s*(\S.*)$/.exec(line))
215
+ .filter((m): m is RegExpExecArray => m !== null)
216
+ .map(m => m[1].trim())
217
+ // `run: |` opens a block scalar; the body is not a command on this line.
218
+ .filter(cmd => cmd !== "|" && !cmd.startsWith("|"))
219
+ .filter(cmd => !NOT_THE_TEST_STEP.has(cmd))
220
+ .map(cmd => cmd.replace(SHARD_SELECTOR, ""));
221
+
222
+ if (runs.length === 0) {
223
+ refuse(CI_YML, "its `test:` job runs nothing but setup and the type check");
224
+ }
225
+ return [{ file: CI_YML, where: "the test job's run step", command: runs[0] }];
226
+ }
227
+
228
+ const EXTRACTORS: Record<string, (text: string) => NamedTestCommand[]> = {
229
+ [AGENTS_MD]: testCommandsNamedByAgentsMd,
230
+ [CONFIG_JSON]: testCommandsNamedByConfig,
231
+ [CI_YML]: testCommandsNamedByCiWorkflow,
232
+ };
233
+
234
+ export interface TestCommandAgreement {
235
+ commands: NamedTestCommand[];
236
+ /** Empty when every position names the same string. */
237
+ violations: string[];
238
+ }
239
+
240
+ /**
241
+ * The violation text, shared by the three-file binding and the category.
242
+ *
243
+ * Exported because `commandParity` compares SIX positions and this one
244
+ * compares three — a second copy of the sentence would be a second decider
245
+ * that agrees with this one on every input either has ever seen.
246
+ */
247
+ export function commandDisagreement(commands: NamedTestCommand[]): string[] {
248
+ const distinct = [...new Set(commands.map(c => c.command))];
249
+ if (distinct.length <= 1) return [];
250
+ return [
251
+ `the test command is spelled ${distinct.length} different ways: ` +
252
+ commands.map(c => `${c.file} (${c.where}) says \`${c.command}\``).join("; "),
253
+ ];
254
+ }
255
+
256
+ /**
257
+ * The three-file binding #621 shipped. Reads all three files, extracts what
258
+ * each names, and reports a violation when the set of distinct strings is
259
+ * larger than one.
260
+ *
261
+ * A missing file and a file that names nothing both THROW. Neither is a clean
262
+ * reading, and both would otherwise arrive here as "no disagreement".
263
+ */
264
+ export function testCommandAgreement(root: string): TestCommandAgreement {
265
+ const commands: NamedTestCommand[] = [];
266
+ for (const file of AGREEMENT_FILES) {
267
+ const path = file === CONFIG_JSON ? rungateConfigPath(root) : join(root, file);
268
+ if (path === null || !existsSync(path)) {
269
+ throw new NoTestCommandError(`${file} does not exist under ${root}, so it names no test command`);
270
+ }
271
+ commands.push(...EXTRACTORS[file](readFileSync(path, "utf-8")));
272
+ }
273
+ return { commands, violations: commandDisagreement(commands) };
274
+ }
@@ -37,6 +37,7 @@ import { execFileSync } from "child_process";
37
37
  import { createHash } from "crypto";
38
38
  import { tmpdir } from "os";
39
39
  import { join } from "path";
40
+ import { readProcessTable, type ProcessRow } from "./process-table";
40
41
 
41
42
  /**
42
43
  * Suites allowed to run AT ONCE. Measured, not chosen: one full suite peaks at
@@ -538,27 +539,169 @@ function segmentIsFullSuite(segment: string, depth = 0): boolean {
538
539
  */
539
540
  const LIVENESS_GRACE_SECONDS = 25;
540
541
 
542
+ /** The spelling of a suite that the command line itself carries. */
543
+ const SPELLED_BUN = /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/;
544
+
545
+ /** `test` or `run test` as the first arguments after argv[0]. */
546
+ const SUITE_ARGUMENTS = /^\s+(run\s+)?test(\s|$)/;
547
+
548
+ /** What one `ps` command line is. `unknown` is a reading, not a default. */
549
+ export type PsLineReading = "suite" | "not-suite" | "unknown";
550
+
551
+ /** How argv[0] is resolved to the file it actually names. Injected for tests. */
552
+ export type ExecutableResolver = (path: string) => string;
553
+
554
+ /**
555
+ * The one place a `ps` line is judged to be a running suite (#707).
556
+ *
557
+ * Exported so there is exactly one binding to mutate and one thing for a
558
+ * case to drive over a table of real command lines. `suiteLiveness` reads
559
+ * the process table; this decides what a line means, and the two questions
560
+ * are separable only because they are separate functions. **The orphan
561
+ * reaper in `lib/orphan-reaper.ts` asks this same binding**, so the thing
562
+ * that decides what keeps a slot and the thing that decides what may be
563
+ * killed cannot drift apart — which is the whole of the #690/#707 pairing.
564
+ *
565
+ * ## Widening the leading boundary buys nothing, and that is still true
566
+ *
567
+ * `/tmp/brun test` is the documented workaround for #690, and `brun` is
568
+ * b-r-u-n: it **does not contain `bun` at all**, so no loosening of a
569
+ * pattern written over the string `bun` can ever match it. Measured:
570
+ * `"brun".includes("bun")` is `false`. #727 established this and reverted
571
+ * the widening, and nothing below re-litigates it — `SPELLED_BUN` is
572
+ * unchanged.
573
+ *
574
+ * ## What is new: ask the filesystem what the executable IS
575
+ *
576
+ * The workaround is a SYMLINK — measured on this machine, 2026-10-21:
577
+ * `/tmp/brun -> /opt/homebrew/bin/bun`, which `realpath`s to
578
+ * `/opt/homebrew/Cellar/bun/<version>/bin/bun`. So the name is an evasion
579
+ * and the identity is not. When a line's ARGUMENTS are a suite invocation
580
+ * (`<exe> test …` or `<exe> run test …`) but argv[0] is not spelled `bun`,
581
+ * this resolves argv[0] on disk and reads the basename of what it points
582
+ * at. A renamed or symlinked launcher is a `suite`; a resolution that
583
+ * cannot be taken is `unknown`.
584
+ *
585
+ * This is the liveness signal "that is not the process name at all" which
586
+ * the previous revision of this comment asked for, arriving as the
587
+ * executable's identity rather than as a heartbeat. A heartbeat was the
588
+ * other candidate and it is not available at this layer: the slot is taken
589
+ * by a PreToolUse hook that exits immediately, and a session running a
590
+ * foreground suite makes no tool calls while it waits, so nothing exists
591
+ * that could refresh the file.
592
+ *
593
+ * ## The two directions, and why they are not symmetric
594
+ *
595
+ * A resolution that fails, or an argv[0] that is not an absolute path, is
596
+ * `unknown` — and so is a binary whose resolved basename is something else,
597
+ * because a *copy* of bun under another name resolves to itself and no
598
+ * cheap reading can tell it from an unrelated program called with a `test`
599
+ * argument. The two consumers read that third state in OPPOSITE directions,
600
+ * deliberately:
601
+ *
602
+ * - **Keeping a slot** needs "not positively idle", so `unknown` keeps it.
603
+ * Over-detection costs at most one wedged slot for a TTL. Missing a suite
604
+ * that IS there reclaims a live slot and lets two real suites run against
605
+ * a cap of one, which is the OOM condition this whole mechanism prevents.
606
+ * - **Killing a process** needs "positively a suite", so `unknown` is never
607
+ * reaped. Over-detection there costs somebody else's work.
608
+ *
609
+ * The cost of the conservative reading is bounded and worth naming: one
610
+ * long-lived unrelated `/usr/bin/foo test` process makes the machine read
611
+ * `unknown`, which switches the early liveness reclaim off and leaves the
612
+ * 420-second TTL as the only staleness rule. That is the pre-#74 behaviour,
613
+ * not a new failure mode.
614
+ */
615
+ export function classifyPsLine(
616
+ line: string,
617
+ options: { resolveExecutable?: ExecutableResolver } = {},
618
+ ): PsLineReading {
619
+ if (SPELLED_BUN.test(line)) return "suite";
620
+
621
+ const space = line.indexOf(" ");
622
+ if (space <= 0) return "not-suite";
623
+ const argv0 = line.slice(0, space);
624
+ if (!SUITE_ARGUMENTS.test(line.slice(space))) return "not-suite";
625
+
626
+ // The arguments say "suite" and the name does not. Everything from here is
627
+ // a question about the file on disk, which is the thing a rename cannot
628
+ // change.
629
+ if (!argv0.startsWith("/")) return "unknown";
630
+ let resolved: string;
631
+ try {
632
+ resolved = (options.resolveExecutable ?? realpathSync)(argv0);
633
+ } catch {
634
+ return "unknown";
635
+ }
636
+ return resolved.slice(resolved.lastIndexOf("/") + 1) === "bun" ? "suite" : "unknown";
637
+ }
638
+
639
+ /**
640
+ * `psLineIsSuite` as it has always behaved: a projection of the reading
641
+ * above, kept because callers and cases already name it.
642
+ *
643
+ * It is a PROJECTION and not a second decider — there is one `classifyPsLine`
644
+ * and this restates its answer — so a mutation of the classifier moves this
645
+ * too, which is the property that makes the battery able to see either.
646
+ */
647
+ export function psLineIsSuite(
648
+ line: string,
649
+ options: { resolveExecutable?: ExecutableResolver } = {},
650
+ ): boolean {
651
+ return classifyPsLine(line, options) === "suite";
652
+ }
653
+
654
+ /** What the machine as a whole is doing. `unknown` is a reading. */
655
+ export type SuiteLiveness = "running" | "idle" | "unknown";
656
+
657
+ export interface LivenessOptions {
658
+ rows?: ProcessRow[];
659
+ readRows?: () => ProcessRow[];
660
+ resolveExecutable?: ExecutableResolver;
661
+ }
662
+
541
663
  /**
542
- * True when at least one full suite is running anywhere on this machine.
664
+ * Whether any full suite is running anywhere on this machine.
543
665
  *
544
- * ONLY THE ZERO CASE IS USED, deliberately. #67 established that attributing
545
- * bun processes to sessions is unreliable — the agentgrit suite leaks ~31
546
- * dangling bun processes per run, which is why slots are files rather than a
547
- * process count. This does not attribute anything: a slot means a running
548
- * suite, so if NO suite is running at all, every slot is provably false.
666
+ * ONLY THE `idle` CASE IS ACTED ON, deliberately. #67 established that
667
+ * attributing bun processes to sessions is unreliable — the agentgrit suite
668
+ * leaks ~31 dangling bun processes per run, which is why slots are files
669
+ * rather than a process count. This does not attribute anything: a slot
670
+ * means a running suite, so if NO suite is running at all, every slot is
671
+ * provably false.
549
672
  *
550
- * Matches on the command line rather than the executable name. `pgrep -f bun`
551
- * is useless here — it matches powerd's bundle paths, mdbulkimport and any
552
- * other command containing "bun" as a substring.
673
+ * `idle` is therefore a POSITIVE claim and it is made only when the whole
674
+ * table was read and every row was classified. One unclassifiable row makes
675
+ * the reading `unknown`, because `idle` is the only reading that lets a live
676
+ * slot be taken away from somebody.
677
+ */
678
+ export function suiteLiveness(options: LivenessOptions = {}): SuiteLiveness {
679
+ let rows: ProcessRow[];
680
+ try {
681
+ rows = options.rows ?? (options.readRows ?? readProcessTable)();
682
+ } catch {
683
+ return "unknown";
684
+ }
685
+ let sawUnknown = false;
686
+ for (const row of rows) {
687
+ const reading = classifyPsLine(row.command, options);
688
+ if (reading === "suite") return "running";
689
+ if (reading === "unknown") sawUnknown = true;
690
+ }
691
+ return sawUnknown ? "unknown" : "idle";
692
+ }
693
+
694
+ /**
695
+ * True when the machine is NOT positively idle.
553
696
  *
554
- * Throws rather than guessing when the process table cannot be read; the
555
- * caller treats that as "cannot determine" and keeps the slot.
697
+ * The collapse is one-sided on purpose: `unknown` reads as `true` here, so a
698
+ * caller that only wants "may I take this slot away" gets the safe answer
699
+ * without having to remember which way round the third state goes. A caller
700
+ * that needs to tell `unknown` from `running` asks `suiteLiveness` — and the
701
+ * reaper does, because the opposite collapse would kill on a guess.
556
702
  */
557
- export function anySuiteRunning(): boolean {
558
- const out = execFileSync("ps", ["-axo", "command"], { encoding: "utf-8" });
559
- return out
560
- .split("\n")
561
- .some(line => /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/.test(line));
703
+ export function anySuiteRunning(options: LivenessOptions = {}): boolean {
704
+ return suiteLiveness(options) !== "idle";
562
705
  }
563
706
 
564
707
  /**