rungate 0.2.0 → 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.
- package/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +400 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +220 -0
- package/lib/compliance-report.ts +504 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/conformity.ts +1818 -131
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +272 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +506 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +489 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +35 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +186 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +114 -4
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/steps.ts +2680 -0
- package/lib/scanner.ts +701 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +177 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +358 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +250 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/package.json +36 -3
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
- package/.claude/agents/aditi.md +0 -47
- package/.claude/agents/marcus.md +0 -50
- package/.claude/agents/quinn.md +0 -58
- package/.claude/agents/rook.md +0 -47
- package/.claude/agents/serena.md +0 -46
- package/.claude/rungate.json +0 -11
- package/.fallowrc.json +0 -28
- package/.github/copilot-instructions.md +0 -20
- package/.rungate/conformity-findings.json +0 -648
- package/AGENTS.md +0 -106
- package/CODE-MAP.md +0 -50
- package/HARNESS.md +0 -88
- package/bun.lock +0 -26
- package/bunfig.toml +0 -2
- package/config/brief-policies.json +0 -28
- package/config/ceremony-profiles.json +0 -212
- package/config/consumer-cascade-map.json +0 -24
- package/config/doc-cascade-map.json +0 -24
- package/config/eval.json +0 -84
- package/config/profiles/account-plan.yaml +0 -36
- package/config/profiles/campaign.yaml +0 -94
- package/config/prove-evidence.schema.json +0 -65
- package/config/spec-policies.json +0 -36
- package/config/workflow-schema.json +0 -281
- package/gates/SCHEMA-GUIDE.md +0 -121
- package/gates/ac-quality.test.ts +0 -106
- package/gates/adversarial.test.ts +0 -274
- package/gates/brief-assembler.test.ts +0 -429
- package/gates/brief-assembler.ts +0 -334
- package/gates/bunfig.toml +0 -2
- package/gates/chain.test.ts +0 -91
- package/gates/e2e-smoke.test.ts +0 -234
- package/gates/error-classifier.test.ts +0 -249
- package/gates/error-classifier.ts +0 -89
- package/gates/orchestrator.test.ts +0 -950
- package/gates/orchestrator.ts +0 -569
- package/gates/preload.ts +0 -77
- package/gates/prompts/ac-adversary.md +0 -20
- package/gates/prompts/evidence-validator.md +0 -22
- package/gates/prompts/prove-reproducer.md +0 -53
- package/gates/prove.test.ts +0 -164
- package/gates/run-gate.ts +0 -936
- package/gates/schema-parity.test.ts +0 -197
- package/gates/schema.ts +0 -362
- package/gates/self-heal.test.ts +0 -511
- package/gates/self-heal.ts +0 -121
- package/gates/ship-orchestrator.test.ts +0 -379
- package/gates/ship-orchestrator.ts +0 -363
- package/gates/test-fixtures/broken-no-environments.json +0 -60
- package/gates/test-fixtures/valid-standard.json +0 -54
- package/gates/test-utils.ts +0 -43
- package/gates/witness.ts +0 -220
- package/gates/workflow.test.ts +0 -1053
- package/hooks/AgentBriefGuard.hook.ts +0 -586
- package/hooks/AgentVerdictCapture.hook.ts +0 -134
- package/hooks/AutoVerifyGate.hook.ts +0 -76
- package/hooks/GateEnforcement.hook.ts +0 -273
- package/hooks/IssueCloseGuard.hook.ts +0 -116
- package/hooks/MergeGuard.hook.ts +0 -55
- package/hooks/StaleTTLCleanup.hook.ts +0 -133
- package/hooks/VerifyPhaseLock.hook.ts +0 -81
- package/hooks/WorkflowStateGuard.hook.ts +0 -37
- package/hooks/lib/agentDetection.ts +0 -70
- package/hooks/lib/findWorkflow.ts +0 -101
- package/hooks/lib/parseStdin.ts +0 -37
- package/hooks/lib/paths.ts +0 -111
- package/hooks/lib/utils.ts +0 -81
- package/reference/migration-manifest.json +0 -554
- package/reference/prompts/agent-aditi.md +0 -38
- package/reference/prompts/agent-marcus.md +0 -38
- package/reference/prompts/agent-quinn.md +0 -38
- package/reference/prompts/agent-rook.md +0 -37
- package/reference/prompts/agent-serena.md +0 -37
- package/reference/prompts/council-skill.md +0 -170
- package/reference/prompts/goal-skill.md +0 -235
- package/reference/prompts/prove-skill.md +0 -283
- package/reference/prompts/quinn-standard.md +0 -246
- package/reference/prompts/ship-convergence.md +0 -65
- package/reference/prompts/ship-escalation.md +0 -43
- package/reference/prompts/ship-iteration.md +0 -382
- package/reference/prompts/ship-pending-patches.md +0 -246
- package/reference/prompts/ship-reference.md +0 -250
- package/reference/prompts/ship-skill.md +0 -347
- package/reference/prompts/ship-templates.md +0 -215
- package/reference/scripts/batch-status.sh +0 -68
- package/reference/scripts/chain-compat-check.sh +0 -67
- package/reference/scripts/context-audit.sh +0 -314
- package/reference/scripts/dead-export-check.sh +0 -61
- package/reference/scripts/generate-qc-tables.sh +0 -92
- package/reference/scripts/harness-init.sh +0 -111
- package/reference/scripts/pai-054-baseline-check.sh +0 -40
- package/reference/scripts/prove-smoke-test.sh +0 -112
- package/reference/scripts/setup-keychain-salt.sh +0 -12
- package/reference/scripts/skill-optimizer-friday.sh +0 -88
- package/reference/scripts/skill-qc-test.sh +0 -351
- package/reference/scripts/skill-synthesize-tonight.sh +0 -66
- package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
- package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
- package/reference/specs/harness-v3-migration-plan.md +0 -188
- package/scripts/decision-reconcile.sh +0 -74
- package/scripts/decision-reconcile.ts +0 -152
- package/scripts/git-hooks/pre-commit +0 -76
- package/scripts/git-hooks/pre-push +0 -271
- package/scripts/harness-skill-check.sh +0 -52
- package/scripts/lib/gap-emit.sh +0 -65
- package/scripts/lib/jq-update.sh +0 -30
- package/scripts/lib/resolve-slug.sh +0 -30
- package/scripts/lib/verify-spec-compliance.sh +0 -102
- package/scripts/prove-backfill.sh +0 -87
- package/scripts/scaffold-rungate-config.ts +0 -91
- package/scripts/self-containment-check.sh +0 -109
- package/scripts/skill-qc-validator.sh +0 -402
- package/scripts/slug-resolver.sh +0 -14
- package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
- package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
- package/specs/HARNESS-GATES.md +0 -256
- package/specs/HARNESS-SKILL-CHAIN.md +0 -286
- package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
- package/specs/HARNESS-STANDARD.md +0 -488
- package/specs/SPEC-TEMPLATE.md +0 -53
- package/specs/bootstrap-data-flow.png +0 -0
- package/specs/harness-automation-matrix.md +0 -314
- package/specs/harness-automation-matrix.rules.json +0 -64
- package/test/anti.test.ts +0 -80
- package/test/contract-negative.test.ts +0 -86
- package/test/contract.test.ts +0 -158
- package/test/external-deps.test.ts +0 -48
- package/test/fixtures/golden-project/.env.example +0 -3
- package/test/fixtures/golden-project/Makefile +0 -7
- package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
- package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
- package/test/fixtures/golden-project/package.json +0 -10
- package/test/fixtures/golden-project/specs/api-spec.md +0 -20
- package/test/fixtures/golden-project/src/auth.ts +0 -8
- package/test/fixtures/golden-project/src/db.ts +0 -11
- package/test/fixtures/golden-project/src/index.ts +0 -19
- package/test/fixtures/golden-project/src/utils/format.ts +0 -3
- package/test/fixtures/golden-project/test/auth.test.ts +0 -15
- package/test/fixtures/golden-project/tsconfig.json +0 -12
- package/test/meta-sc-coverage.test.ts +0 -159
- package/test/phase-0.test.ts +0 -846
- package/test/phase-1.test.ts +0 -617
- package/test/phase-2.test.ts +0 -620
- package/test/phase-3.test.ts +0 -99
- package/test/scaffold-conformity.test.ts +0 -8
- package/test/schema-canary.test.ts +0 -51
- package/test/spec-compliance-auto.test.ts +0 -64
- package/test/spec-compliance.test.ts +0 -295
- package/test/spec-discovery.test.ts +0 -68
- package/test/spec-drift.test.ts +0 -5
- package/test/structure.test.ts +0 -165
- package/test/unit/agent-brief-guard-ship.test.ts +0 -293
- package/test/unit/extract-constraints.test.ts +0 -145
- package/test/unit/issue-close-guard.test.ts +0 -204
- package/test/unit/scaffold-project.test.ts +0 -417
- package/test/unit/skill-cooccurrence.test.ts +0 -177
- package/test/unit/skill-sequence-logger.test.ts +0 -244
- package/test/unit/workflow-state-guard.test.ts +0 -95
- package/workflows/batch-ship.js +0 -295
- package/workflows/council.js +0 -481
- package/workflows/prove.js +0 -560
- package/workflows/ship.js +0 -789
- package/workflows/verify.js +0 -236
|
@@ -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
|
+
}
|