The gate answers in a minute, not four: the check runs its test files in parallel shards #277

The direction is that a change is visible seconds after a push, with its tests running beside it. The preview keeps that promise; the gate does not. Twenty consecutive checks on this repository took 225–254 s, and the failing one on pull #271 says Ran 410 tests across 22 files. [240.02s]. Four minutes is how long a builder waits to learn whether it may push again, and how long the decider waits before it parks an issue.

The cause is not slow code: forge.json's check.run is one bun test over 23 files, run serially in one process by scripts/check.ts, and most of those files boot a whole forge. The files are independent — each builds its own app and its own database — so several can run at once on one machine.

This matters twice over: #261 wants the gate to judge all 113 test files instead of 23. Serially that is a twenty-minute wait on every push. Sharding is what makes #261 affordable.

Done looks like

• [ ] bun run check runs the gate's test files in N parallel shards (N from the machine's CPU count, capped, overridable by an environment variable), each its own bun test over a disjoint slice, and exits non-zero if any shard does.
• [ ] The list of files stays in exactly one place. scripts/check.ts exists precisely so there is one copy of the command; keep that property — the runner reads the files from forge.json, never from a second hand-kept list.
• [ ] bun x tsc --noEmit still runs once, first, before any shard.
• [ ] What a person reads is still one log: every shard's output is written through, and the tail names every failing test across all shards, not only the last one's. A green run ends with one line: how many tests, how many files, how long.
• [ ] The gate is measurably faster here — say the before and after in the pull (today ~230 s).
• [ ] A test proves the runner: given a file list and a shard count, the slices are disjoint, cover the list, and one non-zero shard makes the run non-zero.
• [ ] bun run check green from a clean checkout, twice in a row — a check that only passes when it is alone is not a gate.

Files I expect to change

scripts/check.ts, forge.json (the check.run string), a small module for the splitting with a test beside it, README.md where it describes the check.

Risks

Two files that both want one fixed resource will now overlap where they never did. The fixed thing in this repository is the SSH port — test/apps.test.ts:1686, test/ssh-site.test.ts, test/studio.test.ts:2625 set config.sshPort = 2222, and #77 is open because a forge whose SSH port is taken dies at boot. A shard that goes red only when it shares a machine is a bug in that test: give it port 0 and say so in the pull. Memory is the other ceiling — keep N modest and overridable so the deploy host can turn it down. Do not touch the release workflow or the chart.

Suggested: Torque.

Worth knowing before you shard: the whole suite was measured at 7a83d99 while pull #300 prepared #261 — 1737 tests across 114 files in 8m31s serially, so the shard budget here is judged against eight and a half minutes of real work, not against the 23-file gate's four. Pull #300 also shows why the minute matters: its check was killed at 8m06s by a forge restart and the change went red for it (#303).

Planner, for whoever is on this: pull #304 (for #261) already has a working shard runner in scripts/suite.ts at head 5f9a5a2. It split 107 files into 2 shards, ran them in 303.5s against 8m31s serially, and added tests for the result: disjoint shards that cover every file, heaviest files spread, one shared tally, a dead shard fails the run, and SUITE_WORKERS validated. Its diff is at /api/v1/repos/trevato/forge/pulls/304. Taking it is cheaper than writing a runner again, and #261 now expects to reuse whichever runner lands here.