rungate 0.2.1 → 0.3.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 (119) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +24 -2
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,1136 @@
1
+ /**
2
+ * Cross-session concurrency guard for full `bun test` runs (issue #67).
3
+ *
4
+ * CLAUDE.md mandates a full suite before implementation work and
5
+ * hooks/TestSuiteGuard.hook.ts caps that per session. Nothing capped it across
6
+ * sessions, so N open sessions meant N simultaneous suites. On 2026-10-05 that
7
+ * exhausted the VM compressor and rebooted the machine.
8
+ *
9
+ * Capacity is measured, not guessed. One rungate full suite peaks at 5,360 MB
10
+ * across 33 processes on this hardware; one is comfortably safe, two is fine,
11
+ * four-plus is the cliff once an editor and containers are also resident.
12
+ *
13
+ * Slots are explicit files rather than a process count, for two reasons found
14
+ * on this machine: the agentgrit suite leaks ~31 dangling bun processes per run
15
+ * so a count cannot distinguish live work from residue, and BSD `pgrep` has no
16
+ * `-c` flag, so the obvious `pgrep -c bun` exits 2 and silently counts nothing.
17
+ *
18
+ * The guard fails OPEN: if the lock directory is unusable, work proceeds. A
19
+ * broken guard must never be able to block the suite. It does not, however,
20
+ * fail SILENT — a refusal is always reported to the caller.
21
+ */
22
+
23
+ import {
24
+ closeSync,
25
+ existsSync,
26
+ mkdirSync,
27
+ openSync,
28
+ readFileSync,
29
+ renameSync,
30
+ statSync,
31
+ unlinkSync,
32
+ writeFileSync,
33
+ writeSync,
34
+ } from "fs";
35
+ import { execFileSync } from "child_process";
36
+ import { createHash } from "crypto";
37
+ import { tmpdir } from "os";
38
+ import { join } from "path";
39
+
40
+ /**
41
+ * Suites allowed to run AT ONCE. Measured, not chosen: one full suite peaks at
42
+ * 5,360 MB and 33 processes on this machine, and three at once rebooted it on
43
+ * 2026-10-05. Exported so the rate tests can assert it did not move when the
44
+ * rate did — the two are routinely confused, and the 2026-10-13 raise was
45
+ * approved on exactly that distinction.
46
+ */
47
+ export const DEFAULT_CAPACITY = 2;
48
+ const DEFAULT_TTL_SECONDS = 420;
49
+
50
+ /**
51
+ * How far back the DIR-L29 budget looks. Issue #73: this used to be "forever",
52
+ * which turned a rate limit into a one-way lockout — and because subagents
53
+ * carry the parent session's id, the whole pipeline shared one lifetime budget
54
+ * and ran out partway through.
55
+ *
56
+ * 30 minutes is a little longer than two full suites back to back (~190s each
57
+ * plus the agent work between them), so it still stops thrashing while letting
58
+ * a long session come back for a legitimate later run.
59
+ */
60
+ const DEFAULT_BUDGET_WINDOW_MS = 30 * 60_000;
61
+
62
+ /**
63
+ * Full suites one worker may spend inside the window.
64
+ *
65
+ * Raised from 2 to 4 on 2026-10-10. Two was measured against a session that
66
+ * ran the suite as a gate and then got on with it; what actually happens in a
67
+ * long autonomous run is gate, fix, re-measure, fix again — four readings of a
68
+ * tree that is still moving. At 2 the third refusal landed mid-run and the
69
+ * work either stalled or proceeded on an unmeasured tree, which is the
70
+ * failure this budget exists to prevent, arrived at from the other side.
71
+ *
72
+ * This is a RATE, not a concurrency limit. `DEFAULT_CAPACITY` still holds the
73
+ * machine to 2 suites at once, and that is the number the 2026-10-05 reboot
74
+ * was about — 5,360 MB and 33 processes per suite. Raising the rate lets one
75
+ * worker come back sooner; it does not let two more start together.
76
+ *
77
+ * Must stay <= MAX_TRACKED_RUNS, which bounds what the counter file retains.
78
+ * A budget larger than what is remembered is a budget that silently resets.
79
+ *
80
+ * Raised again from 4 to 8 on 2026-10-13, at Jason's direction, on the
81
+ * argument the paragraph above already makes: the rate and the concurrency
82
+ * cap are different things, and in a single-session run with nothing
83
+ * overlapping, `DEFAULT_CAPACITY` is the one doing the protecting. Four was
84
+ * reached three times in one afternoon of backlog work — once mid-
85
+ * reconciliation, which is the stall this budget exists to prevent arriving
86
+ * from the other side, exactly as the 2026-10-10 note describes.
87
+ *
88
+ * 8 is the ceiling, not a step toward a larger one. Going higher means raising
89
+ * retention first and saying why — a budget above what the counter file
90
+ * remembers resets silently.
91
+ *
92
+ * Raising the rate to 8 forced `MAX_TRACKED_RUNS` up to 12 in the same change,
93
+ * and NOT for capacity. At 8 the rate would have equalled retention, and then
94
+ * `Math.min(parsed, DEFAULT_MAX_RUNS_PER_WORKER)` below and
95
+ * `Math.min(option, MAX_TRACKED_RUNS)` above become the same function: no input
96
+ * distinguishes them, so the one-way environment clamp — the whole finding of
97
+ * the d6cc5acf security review — stops being observable by any test. The
98
+ * property would still have been coded and would no longer have been checkable.
99
+ * Retention is a slice length bounded by `MAX_COUNTER_BYTES`; headroom there
100
+ * costs nothing and keeps the clamp measurable.
101
+ *
102
+ * What did NOT change, and must not: `DEFAULT_CAPACITY` stays at 2. The
103
+ * 2026-10-05 reboot was 5,360 MB and 33 processes per suite running at once,
104
+ * and nothing here touches that.
105
+ */
106
+ export const DEFAULT_MAX_RUNS_PER_WORKER = 8;
107
+
108
+ /**
109
+ * Full suites ONE SHIP RUN may spend in total, across every agent in it.
110
+ *
111
+ * A second bound rather than a different one (#194). The per-worker rate above
112
+ * is correct and must stay: #239 keyed it on the worker because three disjoint
113
+ * sub-agents sharing a session id serialised on the window, one of them
114
+ * sleeping in 580-second increments for twenty minutes while its siblings were
115
+ * already done. Reverting that recreates #239 exactly.
116
+ *
117
+ * But per-worker is the wrong unit for "how much did shipping this issue
118
+ * cost". A run is Marcus, plus heal iterations, plus Quinn, each with its own
119
+ * worker identity — so "at most four" became "at most four, several times
120
+ * over". Measured across four runs: 7, 11, 13 and 12+ full suites for one
121
+ * issue each, against a cap that was never once reached by any single worker.
122
+ *
123
+ * Eight covers what a run legitimately needs — the entry gate, a re-measure
124
+ * after fixes, the verify pass, a final reconciliation, with slack — and bites
125
+ * well before thirteen. It must stay <= MAX_TRACKED_RUNS, which bounds what
126
+ * the counter file retains; a budget larger than what is remembered is a
127
+ * budget that silently resets.
128
+ */
129
+ export const DEFAULT_MAX_RUNS_PER_PIPELINE = 8;
130
+
131
+ /**
132
+ * How long an abandoned run counter is kept.
133
+ *
134
+ * NOT a rate window — the run ceiling deliberately has none, because a
135
+ * 30-minute window cannot constrain a 41-minute run and all four measured runs
136
+ * were longer than the window meant to bound them. This is garbage collection:
137
+ * a run id is unique and its counter would otherwise sit in the lock directory
138
+ * forever, and a corrupt one would wedge that id permanently. Twelve hours is
139
+ * far longer than any run observed (30 to 41 minutes).
140
+ */
141
+ const RUN_COUNTER_MAX_AGE_MS = 12 * 3_600_000;
142
+
143
+ /**
144
+ * The ship run a working directory belongs to, or null outside one.
145
+ *
146
+ * Derived from the path because that is what a hook can see. Hooks inherit the
147
+ * Claude Code process environment, not the workflow's, so a run id exported by
148
+ * `workflows/ship.js` never reaches the guard — the same reason
149
+ * `RUNGATE_MAX_FULL_SUITE_RUNS` is documented as hard to reach from one
150
+ * direction and trusted from none.
151
+ *
152
+ * Agent worktrees are `.claude/worktrees/<runId>-<n>`, so the trailing index
153
+ * comes off and everything from one run agrees. Null for the repo root: the DA
154
+ * is not part of a fan-out, and inventing an id for it would put every session
155
+ * that never ships anything into one shared ceiling.
156
+ */
157
+ export function deriveRunId(cwd?: string): string | null {
158
+ if (!cwd) return null;
159
+ const m = /[\\/]\.claude[\\/]worktrees[\\/]([^\\/]+)/.exec(cwd);
160
+ if (!m) return null;
161
+ const name = m[1].replace(/-\d+$/, "");
162
+ return name.length > 0 ? filenameSegment(name) : null;
163
+ }
164
+
165
+ /**
166
+ * Lowers the rate for a session that wants to be stricter. It cannot raise it.
167
+ *
168
+ * The first version of this let the environment set any value up to
169
+ * MAX_TRACKED_RUNS, and security review of d6cc5acf called that correctly: a
170
+ * guard that exists to stop a machine-killing suite must not read its own
171
+ * limit from a place the guarded work can influence. Reaching the hook's
172
+ * environment is not trivial — hooks inherit the Claude Code process's env, so
173
+ * an inline `VAR=8 bun test` sets it for the suite and not for the guard — but
174
+ * "hard to reach from one direction" is not the property a control needs, and
175
+ * a shell profile, a launch script or an exported parent all reach it.
176
+ *
177
+ * One-way is the whole fix: tightening is always safe and never needs
178
+ * permission, so there is no reason for the loosening direction to exist.
179
+ */
180
+ const MAX_RUNS_ENV = "RUNGATE_MAX_FULL_SUITE_RUNS";
181
+
182
+ /**
183
+ * The rate in force, in precedence order: explicit option, environment, default.
184
+ *
185
+ * An unreadable or out-of-range environment value falls back to the default
186
+ * rather than to "no limit" — this reads a world-writable environment to
187
+ * decide whether a guard applies, so every path that is not a clearly valid
188
+ * number has to land somewhere bounded.
189
+ */
190
+ export function resolveMaxRuns(
191
+ option?: number,
192
+ env: string | undefined = process.env[MAX_RUNS_ENV],
193
+ ): number {
194
+ // An explicit option is a caller in this repo passing a number, not the
195
+ // graded run talking, so it is trusted to raise as well as lower — bounded
196
+ // only by what the counter file can remember.
197
+ if (typeof option === "number" && Number.isInteger(option) && option >= 0) {
198
+ return Math.min(option, MAX_TRACKED_RUNS);
199
+ }
200
+ if (typeof env === "string" && /^\d+$/.test(env.trim())) {
201
+ const parsed = parseInt(env.trim(), 10);
202
+ if (Number.isInteger(parsed) && parsed >= 0) {
203
+ // Clamped DOWN to the policy, never up to MAX_TRACKED_RUNS.
204
+ return Math.min(parsed, DEFAULT_MAX_RUNS_PER_WORKER);
205
+ }
206
+ }
207
+ return DEFAULT_MAX_RUNS_PER_WORKER;
208
+ }
209
+
210
+ export interface SlotHolder {
211
+ sessionId: string;
212
+ /** The worker that took the slot (#239). Absent on slots written before it. */
213
+ workerId?: string;
214
+ startedAt: number;
215
+ ageSeconds: number;
216
+ }
217
+
218
+ export interface AcquireResult {
219
+ ok: boolean;
220
+ /** Present when refused — who is holding the slots and for how long. */
221
+ holders?: SlotHolder[];
222
+ /** True when the guard could not function and allowed the run anyway. */
223
+ degraded?: boolean;
224
+ }
225
+
226
+ export interface LockOptions {
227
+ lockDir?: string;
228
+ capacity?: number;
229
+ ttlSeconds?: number;
230
+ now?: number;
231
+ /**
232
+ * Whether any full suite is running on this machine. Injected so tests do
233
+ * not depend on the real process table. Defaults to `anySuiteRunning`.
234
+ */
235
+ suitesRunning?: () => boolean;
236
+ /**
237
+ * The unit of work asking for the suite (#239). Sibling sub-agents carry
238
+ * their PARENT's session id, so the session cannot distinguish them; the
239
+ * worker can. Defaults to the session id, which is exactly the pre-#239
240
+ * behaviour for every caller that does not know about workers.
241
+ *
242
+ * Derive it with `deriveWorkerId` — this is reduced to one filename-safe
243
+ * segment before it is used, because the budget counter is a file.
244
+ */
245
+ workerId?: string;
246
+ }
247
+
248
+ interface SlotEntry {
249
+ sessionId: string;
250
+ /** Optional: slots written before #239 carry only a session id. */
251
+ workerId?: string;
252
+ startedAt: number;
253
+ }
254
+
255
+ /**
256
+ * Where slot files live. TMPDIR is shared across sessions on this machine,
257
+ * which is exactly what makes the cap work between them.
258
+ *
259
+ * RUNGATE_LOCK_DIR overrides it. Tests that drive the hook as a subprocess
260
+ * cannot pass `options`, so without an override they compete for the real
261
+ * slots — including the slot held by the very suite running them — and leak a
262
+ * live slot per case, wedging the next run for a full TTL.
263
+ */
264
+ function defaultLockDir(): string {
265
+ return process.env.RUNGATE_LOCK_DIR || process.env.TMPDIR || tmpdir() || "/tmp";
266
+ }
267
+
268
+ function slotPath(lockDir: string, index: number): string {
269
+ return join(lockDir, `full-suite.slot-${index}.lock`);
270
+ }
271
+
272
+ // ── worker identity (#239) ───────────────────────────────────
273
+ //
274
+ // A SLOT has meant one running suite since #67-B, because sub-agent Bash calls
275
+ // reach PreToolUse carrying the PARENT session's id. The RATE budget never got
276
+ // the same treatment: it stayed keyed on the session, so a ship run that fans
277
+ // out to three implementers handed three agents two runs per 30 minutes
278
+ // between them. Run wf_18abb197-f03 spent both on sub-agents 235001 and
279
+ // 235003, and 235002 slept ~22 minutes waiting for a window to age out while
280
+ // its siblings had been finished for twenty.
281
+ //
282
+ // The budget itself is not the problem — concurrent full suites jetsam-killed
283
+ // this machine on 2026-10-05, and raising maxRuns would re-open that. The key
284
+ // is the problem.
285
+
286
+ /**
287
+ * How long a derived key may be. Comfortably inside every filesystem's
288
+ * component limit once the `rungate-test-suite-count-` prefix is added.
289
+ */
290
+ const WORKER_KEY_MAX = 72;
291
+
292
+ /** Exactly what may appear in a key: one path component, no dots, no escape. */
293
+ const SAFE_SEGMENT = new RegExp(`^[A-Za-z0-9_-]{1,${WORKER_KEY_MAX}}$`);
294
+
295
+ /**
296
+ * Reduce anything to ONE filename-safe segment.
297
+ *
298
+ * The identity is derived from a working directory and then concatenated into
299
+ * `join(lockDir, ...)`. A key carrying `/` or `..` would steer the counter
300
+ * file out of the lock directory — writing wherever the traversal points and,
301
+ * worse, letting two workers pick the same escaped path and share a budget
302
+ * again. Sanitising alone is not enough either: collapsing separators makes
303
+ * `/a/b` and `-a-b` the same key, so the digest is what keeps distinct
304
+ * directories distinct after the collapse.
305
+ *
306
+ * Already-safe input is returned unchanged, which makes this idempotent — the
307
+ * hook derives a key and the lock derives it again, and both must agree.
308
+ */
309
+ export function filenameSegment(raw: string): string {
310
+ if (SAFE_SEGMENT.test(raw)) return raw;
311
+ const digest = createHash("sha256").update(raw).digest("hex").slice(0, 12);
312
+ const readable = raw
313
+ .replace(/[^A-Za-z0-9_-]+/g, "-")
314
+ .replace(/^-+|-+$/g, "")
315
+ .slice(-(WORKER_KEY_MAX - digest.length - 1));
316
+ return readable ? `${readable}-${digest}` : digest;
317
+ }
318
+
319
+ /**
320
+ * The identity of one unit of work asking for the full suite.
321
+ *
322
+ * `workDir` is the distinguishing fact: sibling sub-agents share a session id
323
+ * but each runs in its own worktree. When it is absent — a plain session, or a
324
+ * hook input without a cwd — this degrades to the session id, which is exactly
325
+ * the pre-#239 key, so existing counter files keep counting.
326
+ */
327
+ export function deriveWorkerId(sessionId: string, workDir?: string): string {
328
+ return filenameSegment(workDir ? `${sessionId}@${workDir}` : sessionId);
329
+ }
330
+
331
+ /**
332
+ * THE key the rate budget is filed under — the single site #239 changes.
333
+ *
334
+ * Reverting this to `return sessionId` restores the defect exactly, which is
335
+ * what test/test-suite-lock-key-mutation.test.ts mutates to prove the sibling
336
+ * case can fail. Keep it one line, one site: a second place that computes the
337
+ * budget key would survive the mutation and the proof would be decorative.
338
+ */
339
+ export function counterKey(sessionId: string, options: LockOptions = {}): string {
340
+ return filenameSegment(options.workerId ?? sessionId);
341
+ }
342
+
343
+ /**
344
+ * Who owns a slot, for the purposes of releasing it.
345
+ *
346
+ * Acquire and release must agree or a slot leaks for a full TTL. Defaulting to
347
+ * the session id keeps every pre-#239 caller — and every slot file already on
348
+ * disk, which has no workerId — behaving as it did.
349
+ */
350
+ function slotOwner(sessionId: string, options: LockOptions): string {
351
+ return options.workerId ?? sessionId;
352
+ }
353
+
354
+ function ownerOf(entry: SlotEntry): string {
355
+ return entry.workerId ?? entry.sessionId;
356
+ }
357
+
358
+ function readSlot(path: string): SlotEntry | null {
359
+ try {
360
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
361
+ if (
362
+ parsed &&
363
+ typeof parsed.sessionId === "string" &&
364
+ typeof parsed.startedAt === "number"
365
+ ) {
366
+ // Rebuilt field by field rather than cast: a slot file is world-writable
367
+ // and `workerId` decides who may release the slot, so a non-string one
368
+ // must read as absent rather than as an object that compares oddly.
369
+ return {
370
+ sessionId: parsed.sessionId,
371
+ startedAt: parsed.startedAt,
372
+ ...(typeof parsed.workerId === "string" ? { workerId: parsed.workerId } : {}),
373
+ };
374
+ }
375
+ return null;
376
+ } catch {
377
+ // Missing or corrupt — either way there is no live holder here.
378
+ return null;
379
+ }
380
+ }
381
+
382
+ /** Leading `FOO=bar` assignments, which precede the real command word. */
383
+ const ENV_PREFIX = /^[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+/;
384
+
385
+ /** Wrappers that delegate to the command word after them. */
386
+ const WRAPPER_PREFIX = /^(?:time|nice|exec|command|env|npx|stdbuf|nohup|sudo|xargs)\s+/;
387
+
388
+ /** Wrappers that take one argument of their own before the real command. */
389
+ const WRAPPER_WITH_ARG = /^(?:timeout|nice\s+-n)\s+\S+\s+/;
390
+
391
+ /** `bash -c "<inner>"` and friends — the suite hides inside the quotes. */
392
+ const SHELL_DASH_C = /^(?:ba|z|k|)sh\s+-[a-z]*c\s+(['"])([\s\S]*)\1\s*$/;
393
+
394
+ /**
395
+ * Every spelling that runs the whole suite. `package.json` defines
396
+ * `test` = `bun test`, so `bun run test` and `npm test` are the same 5.4 GB run
397
+ * under different names — omitting them left the most obvious spelling unguarded.
398
+ *
399
+ * The negative lookahead is what keeps `bun test:structure` out: that script is
400
+ * `bun test test/structure.test.ts`, a targeted run that must not be blocked.
401
+ */
402
+ const SUITE_INVOCATION =
403
+ /^(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?test(?![:\w-])/;
404
+
405
+ /** A redirection operator, attached target or not: `>`, `2>`, `&>>`, `2>&1`, `2>/dev/null`. */
406
+ const REDIRECT = /^(?:\d*|&)>>?(?:&\d+)?(.*)$/;
407
+
408
+ /**
409
+ * Split on command separators that are NOT inside quotes.
410
+ *
411
+ * Quote-blindness cut both ways: `git commit -m "lint && bun test"` was blocked
412
+ * because the `&&` inside the message split the command, and
413
+ * `bash -c "bun test; echo done"` went unguarded because the `;` inside the body
414
+ * split it before the shell-wrapper pattern could match a balanced quoted string.
415
+ */
416
+ function splitTopLevel(command: string): string[] {
417
+ const out: string[] = [];
418
+ let cur = "";
419
+ let quote: string | null = null;
420
+
421
+ for (let i = 0; i < command.length; i++) {
422
+ const c = command[i];
423
+
424
+ if (quote) {
425
+ cur += c;
426
+ if (c === quote && command[i - 1] !== "\\") quote = null;
427
+ continue;
428
+ }
429
+ if (c === '"' || c === "'") {
430
+ quote = c;
431
+ cur += c;
432
+ continue;
433
+ }
434
+ // Backslash-newline is a line continuation, not a separator (#82). Splitting
435
+ // on it stranded the paths of `bun test \` on the next segment, leaving a
436
+ // zero-argument `bun test` that fails closed — so routine multi-line Bash
437
+ // charged targeted runs to the full-suite budget. Collapse to a space rather
438
+ // than nothing, or the tokens either side would glue into one.
439
+ if (c === "\\" && command[i + 1] === "\n") {
440
+ cur += " ";
441
+ i++;
442
+ continue;
443
+ }
444
+ if (c === "\n" || c === ";" || c === "&" || c === "|") {
445
+ if ((c === "&" && command[i + 1] === "&") || (c === "|" && command[i + 1] === "|")) i++;
446
+ out.push(cur);
447
+ cur = "";
448
+ continue;
449
+ }
450
+ cur += c;
451
+ }
452
+ out.push(cur);
453
+ return out;
454
+ }
455
+
456
+ /**
457
+ * True for a full-suite invocation, false for targeted paths.
458
+ *
459
+ * Fails CLOSED. A missed full suite is unlimited concurrency — the condition that
460
+ * rebooted this machine — whereas a false positive is a loud, recoverable block.
461
+ * So anything that reaches `bun test` at a command position is guarded unless a
462
+ * surviving argument is demonstrably a path.
463
+ *
464
+ * Targeted runs are cheap (415 MB / 7 processes for test/unit) and must never be
465
+ * guarded, which is the only reason this does argument analysis at all.
466
+ */
467
+ export function isFullSuiteCommand(command: string): boolean {
468
+ // Newlines matter: multi-line Bash bodies are routine, and omitting them hid
469
+ // `bun test` on any line but the first.
470
+ for (const segment of splitTopLevel(command)) {
471
+ if (segmentIsFullSuite(segment)) return true;
472
+ }
473
+ return false;
474
+ }
475
+
476
+ function segmentIsFullSuite(segment: string, depth = 0): boolean {
477
+ if (depth > 3) return false;
478
+
479
+ let s = segment.trim();
480
+
481
+ // Peel env assignments and pass-through wrappers off the front.
482
+ for (let i = 0; i < 8; i++) {
483
+ const next = s
484
+ .replace(ENV_PREFIX, "")
485
+ .replace(WRAPPER_WITH_ARG, "")
486
+ .replace(WRAPPER_PREFIX, "");
487
+ if (next === s) break;
488
+ s = next.trim();
489
+ }
490
+
491
+ // `bash -c "bun test; echo done"` — recurse into the quoted body.
492
+ const shellC = s.match(SHELL_DASH_C);
493
+ if (shellC) {
494
+ return splitTopLevel(shellC[2]).some((inner) =>
495
+ segmentIsFullSuite(inner, depth + 1),
496
+ );
497
+ }
498
+
499
+ const invocation = s.match(SUITE_INVOCATION);
500
+ if (!invocation) return false;
501
+
502
+ const rest = s.slice(invocation[0].length).trim();
503
+ // `npm test -- test/foo.ts` passes args through the runner.
504
+ const tokens = rest.replace(/^--\s+/, "").split(/\s+/).filter(Boolean);
505
+
506
+ const args: string[] = [];
507
+ for (let i = 0; i < tokens.length; i++) {
508
+ const t = tokens[i];
509
+
510
+ // Flags never make a run targeted.
511
+ if (t.startsWith("-")) continue;
512
+
513
+ const redirect = t.match(REDIRECT);
514
+ if (redirect) {
515
+ // `2>/dev/null` carries its target; a bare `>` consumes the next token.
516
+ // Either way the target is a sink, not a test path.
517
+ if (!redirect[1]) i++;
518
+ continue;
519
+ }
520
+
521
+ args.push(t);
522
+ }
523
+
524
+ const hasPath = args.some(
525
+ (a) => a.includes("/") || /\.(test\.)?(ts|tsx|js|jsx)$/.test(a),
526
+ );
527
+ return !hasPath;
528
+ }
529
+
530
+ /**
531
+ * Seconds a slot is protected from liveness-based reclamation.
532
+ *
533
+ * The slot is taken at PreToolUse, before the suite is spawned, so there is a
534
+ * window where the slot is legitimately held and no `bun test` is in the
535
+ * process table yet. Reclaiming inside that window would break the exact case
536
+ * the lock exists for.
537
+ */
538
+ const LIVENESS_GRACE_SECONDS = 25;
539
+
540
+ /**
541
+ * True when at least one full suite is running anywhere on this machine.
542
+ *
543
+ * ONLY THE ZERO CASE IS USED, deliberately. #67 established that attributing
544
+ * bun processes to sessions is unreliable — the agentgrit suite leaks ~31
545
+ * dangling bun processes per run, which is why slots are files rather than a
546
+ * process count. This does not attribute anything: a slot means a running
547
+ * suite, so if NO suite is running at all, every slot is provably false.
548
+ *
549
+ * Matches on the command line rather than the executable name. `pgrep -f bun`
550
+ * is useless here — it matches powerd's bundle paths, mdbulkimport and any
551
+ * other command containing "bun" as a substring.
552
+ *
553
+ * Throws rather than guessing when the process table cannot be read; the
554
+ * caller treats that as "cannot determine" and keeps the slot.
555
+ */
556
+ export function anySuiteRunning(): boolean {
557
+ const out = execFileSync("ps", ["-axo", "command"], { encoding: "utf-8" });
558
+ return out
559
+ .split("\n")
560
+ .some(line => /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/.test(line));
561
+ }
562
+
563
+ /**
564
+ * True when no full suite is running anywhere, so every slot is provably false.
565
+ *
566
+ * A detector that throws means "cannot determine", which must read as "keep the
567
+ * slots": reclaiming on an unreadable process table would let two real suites
568
+ * run against a cap of one.
569
+ */
570
+ function noSuiteRunningNow(options: LockOptions): boolean {
571
+ try {
572
+ return (options.suitesRunning ?? anySuiteRunning)() === false;
573
+ } catch {
574
+ return false;
575
+ }
576
+ }
577
+
578
+ /**
579
+ * The one staleness rule, so the acquirer and the read-only predicate cannot
580
+ * drift apart. A prediction that disagrees with the gate is worse than no
581
+ * prediction — it reports a deadlock the gate does not actually have.
582
+ */
583
+ function slotIsStale(
584
+ ageSeconds: number,
585
+ ttlSeconds: number,
586
+ noSuiteRunning: boolean,
587
+ ): boolean {
588
+ return (
589
+ ageSeconds >= ttlSeconds ||
590
+ (noSuiteRunning && ageSeconds >= LIVENESS_GRACE_SECONDS)
591
+ );
592
+ }
593
+
594
+ /** Non-stale slot holders, newest timestamp wins. */
595
+ export function heldSlots(
596
+ lockDir: string,
597
+ now: number = Date.now(),
598
+ capacity: number = DEFAULT_CAPACITY,
599
+ ttlSeconds: number = DEFAULT_TTL_SECONDS,
600
+ ): SlotHolder[] {
601
+ const holders: SlotHolder[] = [];
602
+ for (let i = 0; i < capacity; i++) {
603
+ const entry = readSlot(slotPath(lockDir, i));
604
+ if (!entry) continue;
605
+ const ageSeconds = Math.floor((now - entry.startedAt) / 1000);
606
+ if (ageSeconds >= ttlSeconds) continue;
607
+ holders.push({ ...entry, ageSeconds });
608
+ }
609
+ return holders;
610
+ }
611
+
612
+ /**
613
+ * Take one of the concurrency slots, or report who is holding them.
614
+ *
615
+ * Slots are created with O_EXCL so two sessions racing for the last slot cannot
616
+ * both win — the loser falls through and is refused rather than silently
617
+ * doubling the concurrency.
618
+ */
619
+ export function acquireFullSuiteSlot(
620
+ sessionId: string,
621
+ options: LockOptions = {},
622
+ ): AcquireResult {
623
+ const lockDir = options.lockDir ?? defaultLockDir();
624
+ const capacity = options.capacity ?? DEFAULT_CAPACITY;
625
+ const ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
626
+ const now = options.now ?? Date.now();
627
+
628
+ try {
629
+ mkdirSync(lockDir, { recursive: true });
630
+
631
+ // ONE SLOT IS ONE RUNNING SUITE, NOT ONE SESSION. A single session can
632
+ // legitimately have two suites in flight: a backgrounded run plus a
633
+ // foreground one, or two pipeline agents, which share their parent's
634
+ // session id. Each takes its own slot, so the cap keeps counting suites.
635
+ //
636
+ // Both earlier attempts had the unit wrong. The original re-entrant branch
637
+ // returned ok WITHOUT taking a slot, so A's two suites occupied one slot
638
+ // while B took the other — three suites against a cap of two, the OOM
639
+ // condition this exists to prevent. Replacing it with a flat refusal then
640
+ // over-corrected: Marcus holds the slot, Quinn is refused, and the pipeline
641
+ // reports a test failure that is really a lock collision.
642
+ // #74: a slot leaks for a full TTL when a LATER PreToolUse hook blocks the
643
+ // command — the tool never runs, so PostToolUse never releases. Nothing
644
+ // tells the acquiring hook it was denied, so reconcile here instead.
645
+ //
646
+ // Only the zero case is used, and only after a grace period. If no suite
647
+ // is running anywhere, every slot is provably false; within the grace
648
+ // period the slot may simply be waiting for its own `bun` to appear. If
649
+ // liveness cannot be determined the slots are KEPT: reclaiming on an
650
+ // unreadable process table would let two real suites run against a cap of
651
+ // one, which is the OOM condition this whole mechanism prevents.
652
+ const noSuiteRunning = noSuiteRunningNow(options);
653
+
654
+ for (let i = 0; i < capacity; i++) {
655
+ const path = slotPath(lockDir, i);
656
+ const entry = readSlot(path);
657
+ const ageSeconds = entry ? Math.floor((now - entry.startedAt) / 1000) : Infinity;
658
+ const stale = !entry || slotIsStale(ageSeconds, ttlSeconds, noSuiteRunning);
659
+
660
+ // The worker is recorded alongside the session so the release can free
661
+ // the suite that actually finished rather than a sibling's (#239).
662
+ const owner = slotOwner(sessionId, options);
663
+ const claim = JSON.stringify({ sessionId, workerId: owner, startedAt: now });
664
+
665
+ // A corrupt file reads as `entry === null` but still occupies the name, so
666
+ // O_EXCL would fail. Decide on the file's existence, not on parseability.
667
+ if (stale && existsSync(path)) {
668
+ // Reclaiming a stale slot via unlink-then-create was racy: two sessions
669
+ // could each unlink the other's fresh claim and both believe they held
670
+ // slot i. rename(2) is atomic, so exactly one writer survives, and the
671
+ // read-back below tells the loser to move on.
672
+ const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}`;
673
+ try {
674
+ writeFileSync(tmp, claim);
675
+ renameSync(tmp, path);
676
+ // Compared on the OWNER, not the session: two sibling workers
677
+ // racing for the same stale slot share a session id, so a session
678
+ // comparison would tell both of them they had won it (#239).
679
+ const after = readSlot(path);
680
+ if (after && ownerOf(after) === owner) return { ok: true };
681
+ continue;
682
+ } catch {
683
+ try {
684
+ unlinkSync(tmp);
685
+ } catch {
686
+ // Temp file already gone.
687
+ }
688
+ continue;
689
+ }
690
+ }
691
+
692
+ try {
693
+ const fd = openSync(path, "wx");
694
+ writeSync(fd, claim);
695
+ closeSync(fd);
696
+ return { ok: true };
697
+ } catch {
698
+ // Slot taken between the staleness check and the create — try the next.
699
+ }
700
+ }
701
+
702
+ return { ok: false, holders: heldSlots(lockDir, now, capacity, ttlSeconds) };
703
+ } catch {
704
+ // The guard itself is broken. Allow the run rather than wedge the repo.
705
+ return { ok: true, degraded: true };
706
+ }
707
+ }
708
+
709
+ export interface GateDecision {
710
+ allow: boolean;
711
+ /** Present when refused — shown verbatim to the caller. Never silent. */
712
+ reason?: string;
713
+ /**
714
+ * Present when the run was allowed only because the guard could not function.
715
+ * Fail-open is deliberate; fail-open-and-quiet is not — an unreadable lock
716
+ * directory would otherwise restore unlimited concurrency invisibly.
717
+ */
718
+ warning?: string;
719
+ }
720
+
721
+ /**
722
+ * `key` is always a `counterKey` result — one filename-safe segment (#239).
723
+ * Taking the key rather than the session id is what keeps the sanitising on
724
+ * one path: a caller that passed a raw cwd here would escape the lock dir.
725
+ */
726
+ function counterPath(lockDir: string, key: string): string {
727
+ return join(lockDir, `rungate-test-suite-count-${key}`);
728
+ }
729
+
730
+ /**
731
+ * Where one ship run's total is kept. A separate file from the per-worker
732
+ * counter because they answer different questions and have different
733
+ * lifetimes — merging them would make the run ceiling age out on the worker's
734
+ * window, which is the defect.
735
+ *
736
+ * `filenameSegment` again rather than trusting the caller: `deriveRunId`
737
+ * already sanitises, and a second caller passing a raw path here would escape
738
+ * the lock directory.
739
+ */
740
+ export function runCounterPath(lockDir: string, runId: string): string {
741
+ return join(lockDir, `rungate-test-suite-runcount-${filenameSegment(runId)}`);
742
+ }
743
+
744
+ /**
745
+ * Timestamps of the runs this session has spent, newest last.
746
+ *
747
+ * Three file shapes have to be read, and the difference between them matters:
748
+ *
749
+ * missing -> no runs. Genuinely nothing spent.
750
+ * `{"runs":[...]}` -> the current format.
751
+ * `2` -> written before #73. Dated from the file's mtime, which
752
+ * is when that run actually happened, so an existing
753
+ * lockout ages out instead of being reset to a free
754
+ * budget the moment this ships.
755
+ *
756
+ * Anything else is corrupt, and corrupt returns a FULL budget rather than an
757
+ * empty one. An unreadable counter that parses as "zero runs spent" is the
758
+ * check-that-reports-success-without-checking shape (#65, #71): a one-character
759
+ * edit would silently disable the cap while every message still looked normal.
760
+ *
761
+ * Every bound below exists because the counter lives in a world-writable
762
+ * TMPDIR and TestSuiteGuard ends in `catch { process.exit(0) }`. That catch is
763
+ * a deliberate fail-open so a broken guard can never wedge the repo — which
764
+ * means ANY throw in here silently removes the cap, with nothing printed.
765
+ * Crashing is therefore the most dangerous thing this function can do, worse
766
+ * than reading a wrong number, so it allocates nothing it has not bounded.
767
+ * Found by the security review of b95438cf.
768
+ */
769
+
770
+ /** Generous for the real format (~20 bytes/run); far below a memory problem. */
771
+ const MAX_COUNTER_BYTES = 64 * 1024;
772
+
773
+ /**
774
+ * Entries kept per session. Only `maxRuns` can ever be spent; the rest is slack.
775
+ *
776
+ * Exported so tests derive the retention invariant rather than re-pinning the
777
+ * number beside it — two literals that must agree are one of them going stale.
778
+ *
779
+ * Raised 8 → 12 on 2026-10-13 alongside the rate. The slack is now load-bearing
780
+ * and not merely generous: at zero slack the environment clamp in
781
+ * `resolveMaxRuns` becomes indistinguishable from the option clamp, and a
782
+ * security property no input can observe is not a property. See
783
+ * `DEFAULT_MAX_RUNS_PER_WORKER`.
784
+ */
785
+ export const MAX_TRACKED_RUNS = 12;
786
+
787
+ function readRuns(path: string, maxRuns: number): number[] {
788
+ const budget = Math.max(0, Math.min(maxRuns, MAX_TRACKED_RUNS));
789
+ let raw: string;
790
+ let mtimeMs: number;
791
+ try {
792
+ const stat = statSync(path);
793
+ // Checked before the read, not after: the point is to not load it.
794
+ if (stat.size > MAX_COUNTER_BYTES) {
795
+ return Array.from({ length: budget }, () => stat.mtimeMs);
796
+ }
797
+ mtimeMs = stat.mtimeMs;
798
+ raw = readFileSync(path, "utf-8").trim();
799
+ } catch {
800
+ return [];
801
+ }
802
+ if (!raw) return [];
803
+
804
+ // Legacy: a bare integer, with no record of when those runs happened.
805
+ // Clamped — `99999999999` is a RangeError at the allocation, not a big array.
806
+ if (/^\d+$/.test(raw)) {
807
+ const count = Math.min(parseInt(raw, 10) || 0, budget);
808
+ return Array.from({ length: count }, () => mtimeMs);
809
+ }
810
+
811
+ try {
812
+ const parsed = JSON.parse(raw) as { runs?: unknown };
813
+ const runs = parsed?.runs;
814
+ if (
815
+ Array.isArray(runs) &&
816
+ runs.length <= MAX_COUNTER_BYTES &&
817
+ runs.every((t) => typeof t === "number" && Number.isFinite(t))
818
+ ) {
819
+ // Newest first, then trimmed: the oldest entries are the ones about to
820
+ // expire anyway, and this keeps every later read cheap.
821
+ return (runs as number[]).slice().sort((a, b) => a - b).slice(-MAX_TRACKED_RUNS);
822
+ }
823
+ } catch {
824
+ // fall through to the fail-closed path
825
+ }
826
+
827
+ // Fail closed: spend the whole budget so a corrupt file blocks rather than
828
+ // waves everything through. Dated from mtime, so it clears after one window
829
+ // instead of wedging the session permanently.
830
+ return Array.from({ length: budget }, () => mtimeMs);
831
+ }
832
+
833
+ /** `Math.min(...xs)` throws on a large array — every element is an argument. */
834
+ function earliest(values: number[]): number | null {
835
+ let min: number | null = null;
836
+ for (const v of values) if (min === null || v < min) min = v;
837
+ return min;
838
+ }
839
+
840
+ /** Plain-English wait, for a refusal that would otherwise offer no way out. */
841
+ function describeWait(ms: number): string {
842
+ const minutes = Math.max(1, Math.ceil(ms / 60_000));
843
+ return minutes === 1 ? "1 minute" : `${minutes} minutes`;
844
+ }
845
+
846
+ export interface GateOptions extends LockOptions {
847
+ /** Overrides the rate. Omitted, `resolveMaxRuns` decides (env, then default). */
848
+ maxRunsPerSession?: number;
849
+ /** Rolling window the budget is measured over (#73). */
850
+ budgetWindowMs?: number;
851
+ /** Injected clock, so the window is testable without sleeping. */
852
+ now?: number;
853
+ /**
854
+ * The ship run this request belongs to (#194). Absent outside a run
855
+ * worktree, and then only the per-worker rate applies — which is exactly
856
+ * the pre-#194 behaviour for every caller that does not know about runs.
857
+ *
858
+ * Derive it with `deriveRunId`.
859
+ */
860
+ runId?: string;
861
+ /** Overrides the per-run ceiling. Tests only; there is no environment path. */
862
+ maxRunsPerPipeline?: number;
863
+ }
864
+
865
+ interface BudgetView {
866
+ /** In-window runs, oldest first — what a new run is appended to. */
867
+ recent: number[];
868
+ /** The DIR-L29 refusal, present only when the budget is spent. */
869
+ refusal?: GateDecision;
870
+ }
871
+
872
+ /**
873
+ * What this session has spent inside the rolling window, and whether that is
874
+ * already too much.
875
+ *
876
+ * The window arithmetic lives here and nowhere else. Two copies of it — one
877
+ * that decides and one that reports — is how a predicate starts telling people
878
+ * something the gate does not do.
879
+ */
880
+ function budgetView(sessionId: string, options: GateOptions): BudgetView {
881
+ const lockDir = options.lockDir ?? defaultLockDir();
882
+ const maxRuns = resolveMaxRuns(options.maxRunsPerSession);
883
+ const windowMs = options.budgetWindowMs ?? DEFAULT_BUDGET_WINDOW_MS;
884
+ const now = options.now ?? Date.now();
885
+
886
+ // Runs older than the window are forgotten, which is the whole of #73: the
887
+ // budget is a rate limit again rather than a lifetime total.
888
+ const recent = readRuns(
889
+ counterPath(lockDir, counterKey(sessionId, options)),
890
+ maxRuns,
891
+ ).filter((t) => t > now - windowMs);
892
+ if (recent.length < maxRuns) return { recent };
893
+
894
+ const oldest = earliest(recent);
895
+ // `recent` is empty only when maxRuns is 0 — a configured stop, with no run
896
+ // to wait for. Saying "frees up in Infinity minutes" taught people to stop
897
+ // reading the refusal.
898
+ const when =
899
+ oldest === null
900
+ ? "Full suite runs are disabled for this session (budget 0)."
901
+ : `One run frees up in ${describeWait(oldest + windowMs - now)}.`;
902
+ return {
903
+ recent,
904
+ refusal: {
905
+ allow: false,
906
+ reason:
907
+ `DIR-L29: Full test suite limit reached (${recent.length}/${maxRuns}) in the last ` +
908
+ `${describeWait(windowMs)}. ${when}\n` +
909
+ `Use targeted tests until then:\n bun test test/specific-file.test.ts\n` +
910
+ `Full suite runs cost ~190s and ~5.4 GB each.`,
911
+ },
912
+ };
913
+ }
914
+
915
+ /**
916
+ * What this SHIP RUN has spent in total, and whether that is already too much.
917
+ *
918
+ * No window on purpose (#194). All four measured runs outlasted the 30-minute
919
+ * per-worker window — 30, 32, 34 and 41 minutes — so that window reset
920
+ * mid-run every time and could not bound a run by construction. The run id
921
+ * bounds this one instead: a new run is a new id and a fresh ceiling.
922
+ *
923
+ * `RUN_COUNTER_MAX_AGE_MS` is garbage collection, not a rate window. Without
924
+ * it an abandoned id's counter would sit in the lock directory forever, and a
925
+ * corrupt one would wedge that id permanently rather than for one day.
926
+ */
927
+ function pipelineBudgetView(options: GateOptions): BudgetView {
928
+ const runId = options.runId;
929
+ if (!runId) return { recent: [] };
930
+
931
+ const lockDir = options.lockDir ?? defaultLockDir();
932
+ const maxRuns = Math.max(
933
+ 0,
934
+ Math.min(options.maxRunsPerPipeline ?? DEFAULT_MAX_RUNS_PER_PIPELINE, MAX_TRACKED_RUNS),
935
+ );
936
+ const now = options.now ?? Date.now();
937
+
938
+ const recent = readRuns(runCounterPath(lockDir, runId), maxRuns)
939
+ .filter((t) => t > now - RUN_COUNTER_MAX_AGE_MS);
940
+ if (recent.length < maxRuns) return { recent };
941
+
942
+ return {
943
+ recent,
944
+ refusal: {
945
+ allow: false,
946
+ reason:
947
+ `DIR-L29: ship run ${runId} has spent its full-suite budget ` +
948
+ `(${recent.length}/${maxRuns} for the whole run, across every agent in it).\n` +
949
+ `This is a per-RUN ceiling with no window — it does not age out, because ` +
950
+ `the per-worker window is shorter than a run and could not bound one (#194).\n` +
951
+ `Use targeted tests:\n bun test test/specific-file.test.ts\n` +
952
+ `If the run genuinely needs another full reading of the tree, say so to the ` +
953
+ `caller rather than waiting — nothing will free up.`,
954
+ },
955
+ };
956
+ }
957
+
958
+ /** The "no slot for you" refusal, worded for whoever is holding them. */
959
+ function concurrencyRefusal(
960
+ sessionId: string,
961
+ holders: SlotHolder[],
962
+ ): GateDecision {
963
+ const self = holders.find((h) => h.sessionId === sessionId);
964
+ if (self) {
965
+ return {
966
+ allow: false,
967
+ reason:
968
+ `Every full-suite slot is in use and one of them is yours ` +
969
+ `(started ${self.ageSeconds}s ago).\n` +
970
+ `A slot is one running suite, not one session — a backgrounded suite keeps its ` +
971
+ `slot until it finishes or the ${DEFAULT_TTL_SECONDS}s TTL expires.\n` +
972
+ `Wait for it, or run targeted tests now:\n bun test test/specific-file.test.ts`,
973
+ };
974
+ }
975
+ const who = holders.map((h) => `${h.sessionId} (${h.ageSeconds}s)`).join(", ");
976
+ return {
977
+ allow: false,
978
+ reason:
979
+ `Another full test suite is already running: ${who}.\n` +
980
+ `Concurrent full suites exhausted the VM compressor and rebooted this machine on 2026-10-05 ` +
981
+ `(one suite peaks at ~5.4 GB across 33 processes).\n` +
982
+ `Wait for it to finish, or run targeted tests now:\n bun test test/specific-file.test.ts`,
983
+ };
984
+ }
985
+
986
+ /**
987
+ * Would this command be allowed right now? Answers without changing the answer.
988
+ *
989
+ * `evaluateFullSuiteRequest` reads as a predicate and behaves as a transaction:
990
+ * it takes one of two machine-wide slots and spends a unit of the DIR-L29
991
+ * budget. On 2026-10-05 a three-call diagnostic that only wanted the verdict
992
+ * took both slots, and every other session was refused by a message naming two
993
+ * holders that were running nothing (#103).
994
+ *
995
+ * This reads the same slot files and the same counter — it must, or it would be
996
+ * answering about a different world — but it writes nothing and creates
997
+ * nothing. Both verdicts come from the same `budgetView`, `slotIsStale` and
998
+ * refusal builders the gate uses, so the prediction cannot drift from the act.
999
+ *
1000
+ * It is a prediction, not a reservation: between asking and running, another
1001
+ * session may take the last slot. Callers that intend to RUN must still call
1002
+ * `evaluateFullSuiteRequest`, which re-checks atomically.
1003
+ */
1004
+ export function wouldAllowFullSuite(
1005
+ sessionId: string,
1006
+ command: string,
1007
+ options: GateOptions = {},
1008
+ ): GateDecision {
1009
+ if (!isFullSuiteCommand(command)) return { allow: true };
1010
+
1011
+ const budget = budgetView(sessionId, options);
1012
+ if (budget.refusal) return budget.refusal;
1013
+
1014
+ // After the per-worker rate, so that check's behaviour is unchanged and a
1015
+ // run refused by it does not also spend the run ceiling (#194).
1016
+ const pipeline = pipelineBudgetView(options);
1017
+ if (pipeline.refusal) return pipeline.refusal;
1018
+
1019
+ const lockDir = options.lockDir ?? defaultLockDir();
1020
+ const capacity = options.capacity ?? DEFAULT_CAPACITY;
1021
+ const ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
1022
+ const now = options.now ?? Date.now();
1023
+
1024
+ // The slots the acquirer would refuse to overwrite: present, parseable, and
1025
+ // neither past the TTL nor provably dead.
1026
+ const noSuiteRunning = noSuiteRunningNow(options);
1027
+ const holders = heldSlots(lockDir, now, capacity, ttlSeconds).filter(
1028
+ (h) => !slotIsStale(h.ageSeconds, ttlSeconds, noSuiteRunning),
1029
+ );
1030
+ if (holders.length >= capacity) return concurrencyRefusal(sessionId, holders);
1031
+
1032
+ return { allow: true };
1033
+ }
1034
+
1035
+ /**
1036
+ * The whole gate: per-session budget (DIR-L29) then cross-session concurrency.
1037
+ *
1038
+ * Order is deliberate. The per-session cap is checked first so its behaviour is
1039
+ * unchanged, and a run refused by either check does not consume the other's
1040
+ * budget. Both checks are `wouldAllowFullSuite`; what this adds is the
1041
+ * side effects — claiming a slot and spending a unit of budget.
1042
+ */
1043
+ export function evaluateFullSuiteRequest(
1044
+ sessionId: string,
1045
+ command: string,
1046
+ options: GateOptions = {},
1047
+ ): GateDecision {
1048
+ const predicted = wouldAllowFullSuite(sessionId, command, options);
1049
+ if (!predicted.allow) return predicted;
1050
+ // Targeted runs are neither capped nor counted, so there is nothing to spend.
1051
+ if (!isFullSuiteCommand(command)) return { allow: true };
1052
+
1053
+ const lockDir = options.lockDir ?? defaultLockDir();
1054
+ const now = options.now ?? Date.now();
1055
+
1056
+ // The prediction above is advisory; this is the atomic claim. Another session
1057
+ // can take the last slot in between, and then the acquirer's answer wins.
1058
+ const slot = acquireFullSuiteSlot(sessionId, options);
1059
+ if (!slot.ok) return concurrencyRefusal(sessionId, slot.holders ?? []);
1060
+
1061
+ try {
1062
+ // Only the in-window runs are carried forward, and never more than the
1063
+ // tracked maximum, so neither a long session nor a poisoned file can leave
1064
+ // an expensive read behind.
1065
+ const runs = [...budgetView(sessionId, options).recent, now].slice(
1066
+ -MAX_TRACKED_RUNS,
1067
+ );
1068
+ writeFileSync(
1069
+ counterPath(lockDir, counterKey(sessionId, options)),
1070
+ JSON.stringify({ runs }),
1071
+ );
1072
+ if (options.runId) {
1073
+ const runRuns = [...pipelineBudgetView(options).recent, now].slice(-MAX_TRACKED_RUNS);
1074
+ writeFileSync(runCounterPath(lockDir, options.runId), JSON.stringify({ runs: runRuns }));
1075
+ }
1076
+ } catch {
1077
+ // Budget tracking is best-effort; the concurrency slot is the real guard.
1078
+ }
1079
+
1080
+ if (slot.degraded) {
1081
+ return {
1082
+ allow: true,
1083
+ warning:
1084
+ `Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
1085
+ `was allowed without taking a slot. The cap is not being enforced right now. ` +
1086
+ `Check with other sessions before starting a full suite.`,
1087
+ };
1088
+ }
1089
+ return { allow: true };
1090
+ }
1091
+
1092
+ /**
1093
+ * Give up ONE slot for a finished suite. Releasing one you do not hold is a no-op.
1094
+ *
1095
+ * Exactly one, not all of them: a session may hold several slots, one per
1096
+ * running suite, and only the suite that just finished is done. Freeing every
1097
+ * slot the session owns would hand back capacity that is still in use — which
1098
+ * is the same over-count that caused the original three-concurrent-suite bug.
1099
+ *
1100
+ * The newest slot is the one released, since the run that just finished is the
1101
+ * most recent acquisition. When that guess is wrong the identity of the freed
1102
+ * slot differs but the count does not, and the count is what the cap enforces.
1103
+ */
1104
+ export function releaseFullSuiteSlot(
1105
+ sessionId: string,
1106
+ options: LockOptions = {},
1107
+ ): void {
1108
+ const lockDir = options.lockDir ?? defaultLockDir();
1109
+ const capacity = options.capacity ?? DEFAULT_CAPACITY;
1110
+
1111
+ // Ownership is the WORKER's when one is given (#239): two sibling agents
1112
+ // share a session id, so a session match would let the first to finish free
1113
+ // the slot its sibling's suite is still using. Falls back to the session id
1114
+ // for callers and slot files that predate workers.
1115
+ const owner = slotOwner(sessionId, options);
1116
+
1117
+ let newestPath: string | null = null;
1118
+ let newestStartedAt = -Infinity;
1119
+
1120
+ for (let i = 0; i < capacity; i++) {
1121
+ const path = slotPath(lockDir, i);
1122
+ const entry = readSlot(path);
1123
+ if (!entry || ownerOf(entry) !== owner) continue;
1124
+ if (entry.startedAt > newestStartedAt) {
1125
+ newestStartedAt = entry.startedAt;
1126
+ newestPath = path;
1127
+ }
1128
+ }
1129
+
1130
+ if (!newestPath) return;
1131
+ try {
1132
+ unlinkSync(newestPath);
1133
+ } catch {
1134
+ // Already gone, or reclaimed by the TTL — either way nothing is held.
1135
+ }
1136
+ }