Vitest worker count is a library default that oversubscribes this team's machines

[cliffhall]

Found while landing #2323 (PR #2334), and it is the same class that issue is
about — a number nobody chose — one layer down. #2323 fixed the wall-clock
budgets; this is the concurrency that makes those budgets get spent.

The defect

No Vitest project in this repo sets maxWorkers — confirmed, nothing in any
vitest.shared.mts, client config or poolOptions names it — so all six inherit
Vitest's own default.

That default is Math.max(availableParallelism() - 1, 1) for a non-watch run
(getDefaultThreadsCount, node_modules/vitest/dist/chunks/cli-api.BK8pd4xc.js:2354,
Vitest 4.1.10). On the machine this team works on (Apple M3, 4 performance + 4
efficiency cores, 8 logical) that is 7, not 8.

⚠️ Vitest's own CLI help text says default: os.availableParallelism(), which is
stale — the code subtracts one. Do not re-derive this number from --help.

Seven workers on eight logical cores still means only four of them can get a
performance core. The rest run the same workload on E-cores that are several
times slower, which is how a test that takes a second blows a 15-second budget.
That default assumes homogeneous cores. Every Apple Silicon machine violates that
assumption, and the whole team is on them.

One stage is already exempt: the browser pool (Storybook) self-caps at
Math.min(12, numCpus - 1), so it is not governed by whatever is decided
here.

Measured

344-file web unit suite, runs sequential, same machine, nothing else of ours
running. npx vitest run --project=unit --maxWorkers=N:

maxWorkers	Wall	vs 8	CPU in tests	CPU in import
8 (explicit)	46s	—	138.7s	97.3s
6	56s	+22%	120.5s	80.2s
4	60s	+30%	99.0s	53.2s
3	70s	+52%	88.1s	44.9s
2	93s	+102%	82.6s	39.0s

⚠️ The baseline row is not the default. It was run as an explicit
--maxWorkers=8, one worker above the 7 this repo actually inherits. The shape of
the curve is very unlikely to change, but every percentage in the vs column is
measured against a configuration nothing runs. Re-measure with 7 as the
baseline before quoting any of these figures in a decision.

The CPU columns are the finding, not the wall column. Same 344 files and the
same assertions, but 8 workers burns 40% more CPU in tests and 2.5x more
in import than 2 workers. That is contention overhead — cache thrash plus work
landing on efficiency cores. The default is not buying eight cores of
parallelism; it is buying roughly four and paying for eight.

⚠️ maxWorkers: 4 is not "one per performance core." macOS exposes no CPU
affinity API, and Vitest's workers are given no distinguishing QoS class, so the
scheduler is free to place any of them on an E-core — and with the main process
and v8 coverage instrumentation also runnable, it will. Capping reduces
contention; it does not buy P-core residency. 4 is a chosen number, not a
derived one, and whatever value is committed has to be justified as a chosen one.

What the table actually argues

Worth stating plainly, because it shapes the decision: the default is the
fastest configuration measured. Every row below it is slower in wall clock. The
CPU columns only matter to the extent that something else wants those cycles —
and on this machine the only something else is another gate in another worktree.

So this is a politeness knob for the multi-session case, not a fix for a bad
single-session default. A developer running one gate alone pays the full wall-clock
cost for no benefit. That is a real trade to make deliberately; it is not a free
win, and the issue should not be closed as though it were one.

Why it matters beyond runtime

#2334's review took thirteen local:gate runs, of which roughly half went red —
every time on unrelated files with a bare Test timed out, a different set each
run, each passing in about a second in isolation. One showed 940 seconds of wall
clock against a 15-second budget, which is a starved worker rather than a slow
assertion. Non-causation was provable on the later ones: zero files under
clients/ had changed since the last fully green run.

Not memory (55% free, zero swap) and not Docker (<1% CPU). Sampling during a gate
showed the spikes coming from the gate itself.

⚠️ The flake reduction is a well-grounded hypothesis, not a measured result.
The mechanism fits exactly, but proving it needs many runs at each setting — hours
of machine time — and nobody should read the table above as having demonstrated
it. Measuring that is part of this issue, not a premise of it.

The design question, which is why this is not a one-liner

Capping workers is a pure loss on CI. GitHub runners are not oversubscribed
and no evidence from #2323 or #2334 implicates them — CI went 8 for 8 green across
that PR's entire review. A committed maxWorkers: 4 would slow every CI run to
fix a problem CI does not have.

So the options, in rough order of preference:

1. Set it in local:gate, as an env var read by vitest.shared.mts. CI never
   runs local:gate — .github/workflows/main.yml invokes npm run validate
   (line 55) and npm run coverage (line 175) directly — so the cap lives in the
   one entry point that is local-only by construction. No CI cost, no CI
   sniffing, no knob anyone has to discover, and it propagates to every child
   script through the environment. verify:test-timeouts can assert both the
   plumbing and the value, which is exactly its existing charter.
   The gap to name: a bare npm run validate in the fast inner loop would not
   get the cap, since that script is shared with CI. Probably acceptable — the
   long contended runs are gate runs — but say so rather than leaving it implicit.
2. Local-only via a bare env override. A TEST_MAX_WORKERS read in
   vitest.shared.mts next to TIMEOUTS, defaulting to unset (library behavior)
   and set by developers who want it. Honest, but a knob everyone has to discover
   is a knob nobody sets — the same objection Test-gate timeouts are still library defaults — the unit, tui and launcher projects and all 788 Testing Library waits fail correct tests under concurrent-worktree load #2323 raises against its own
   deferred INSPECTOR_TEST_TIMEOUT_SCALE. Option 1 is this option with the
   discovery problem solved.
3. Key it off CI detection. process.env.CI ? undefined : 4. Gets the benefit
   by default locally at no CI cost, but makes the local gate and CI run
   measurably different configurations.
   ⚠️ The original filing cited the pinned-CLI reasoning in AGENTS.md
   against this. That citation was a poor fit — the pinned-CLI argument is about a
   different schema, one that can disagree about pass/fail on semantics, and
   maxWorkers changes nothing about what runs. The objection survives for a
   different reason: the budgets this knob interacts with are wall-clock, so a
   purely-scheduling difference can still flip an outcome. That is the whole
   premise of this issue, and it is the reason to write down, not the other one.
4. Commit maxWorkers: 4 everywhere and accept the CI cost as the price of one
   number that means the same thing in both places.

⚠️ None of these compose across worktrees. Four sessions at maxWorkers: 4 is
still 16 workers on 8 cores — worse than one session at the inherited 7. This
narrows the self-inflicted share only — which the sampling suggests is the
larger one — and the cross-worktree lease #2323 raises and defers is the actual
fix for the multi-session case. Do not close that door by declaring this issue the
solution.

Work

1. Re-measure the baseline at 7, the value actually inherited, and recompute
   the vs column against it. The existing table's reference point does not exist
   in practice.
2. Re-run the sweep under v8 coverage (test:coverage), which is the heavier
   and more flake-prone stage, and on the tui project. The unit-suite shape
   should transfer but has not been checked.
3. Measure the flake rate, not just runtime: N full runs at the default and at
   the candidate, counting Test timed out failures. That is the number this issue
   actually turns on.
   ⚠️ Decide up front whether this is affordable and whether it can be run
   cleanly. It is hours of machine time on a box whose contention is the thing
   under test, and a concurrent session in another worktree invalidates the sample
   — the control-arm problem from the gate-queue work: control-green /
   treatment-red is not a verdict if ambient load moved between the arms. If it
   cannot be run cleanly, say so and fall back to deciding on the CPU-burn
   evidence alone, with the flake claim recorded as a standing hypothesis.
4. Pick an option above and say why in the code, the way TIMEOUTS does.
5. If a value is committed, extend verify:test-timeouts to assert it — it already
   owns "the concurrency and budget numbers are stated, not inherited".

Acceptance

• maxWorkers is either a stated value with its reasoning, or explicitly recorded
  here as "keep the default" with the measurement that justifies it.
• The reasoning states the value as chosen, not as derived from the P-core
  count, since it cannot be.
• The flake-rate measurement is recorded — or its infeasibility is, with the
  decision resting explicitly on the runtime and CPU evidence instead.
• CI runtime impact is stated explicitly, whichever option is taken.

What #2339 means for this issue's ordering (from PR #2344)

The maxWorkers cap here and the #2339 lease are alternatives for the load half, and at two sessions the load half measured ~1.3x with no timeouts. With gates serialized, the oversubscription this issue exists to mitigate comes only from non-gate work (a bare npm run coverage in another session, Spotlight after an install). Measure this against a leased baseline before deciding it.

[cliffhall]

Amended the body. What changed, so the edit is auditable:

Corrections

1. The inherited default is 7, not 8. Vitest 4.1.10 resolves a non-watch run to Math.max(availableParallelism() - 1, 1) — getDefaultThreadsCount, node_modules/vitest/dist/chunks/cli-api.BK8pd4xc.js:2354. The availableParallelism() figure in the original filing came from Vitest's CLI help text, which is stale relative to its own code. Consequence: the table's baseline row was an explicit --maxWorkers=8, one worker above anything this repo actually runs, so every percentage in the vs default column is measured against a configuration that does not exist. Column relabelled vs 8, and a re-measurement at 7 added as work item 1.

2. maxWorkers: 4 does not pin workers to performance cores. macOS exposes no CPU affinity API and Vitest's workers carry no distinguishing QoS class, so the scheduler places them freely — and with the main process and v8 coverage instrumentation also runnable, some will land on E-cores regardless. Capping reduces contention; it buys no P-core residency. The "one per performance core" framing made 4 look derived when it is chosen, so the acceptance criteria now require it to be justified as chosen.

3. The AGENTS.md pinned-CLI citation against the CI-detection option was a poor fit. That argument is about a different schema — a check that can disagree about pass/fail on semantics — and maxWorkers changes nothing about what runs. The objection does survive, but for a different reason: the budgets this knob interacts with are wall-clock, so a purely-scheduling difference can still flip an outcome. Replaced the citation with that reasoning.

Additions

4. A new option 1 — set the cap in local:gate via an env var read by vitest.shared.mts. CI never runs local:gate (main.yml calls npm run validate and npm run coverage directly), so this is local-only by construction: no CI cost, no CI sniffing, and no knob to discover. Its gap is named too — a bare npm run validate would not get the cap, since that script is shared with CI. The old option 1 is now option 2, and is this option minus the discovery fix.

5. A "What the table actually argues" section. The default is the fastest configuration measured; the CPU columns only matter because something else wants the cycles, and the only something else here is another worktree. So this is a politeness knob for the multi-session case rather than a fix for a bad single-session default — worth stating so it is not read as a free win.

6. A feasibility warning on the flake measurement. It is hours of machine time on a box whose contention is the thing under test, and a concurrent session invalidates the sample — control-green / treatment-red is not a verdict if ambient load moved between the arms. Acceptance now allows recording its infeasibility and deciding on the runtime and CPU evidence, rather than blocking on a number that may not be obtainable cleanly.

7. Noted that the browser (Storybook) pool already self-caps at Math.min(12, numCpus - 1) and so is out of scope for this decision, and confirmed that nothing in the repo sets maxWorkers, maxThreads or poolOptions anywhere.

No measurements were re-run — items 1 and 2 in Work are still open.

[cliffhall]

Measured against the leased baseline: keep the default

Decision: maxWorkers stays unset, as a chosen value, with the measurement
below recorded in the repo (PR #2345: a comment beside TIMEOUTS in
vitest.shared.mts and a rule bullet in AGENTS.md). No code changes.

Everything below is on v2/main @ f16a51d4 (after the #2339 lease), Vitest
4.1.11 — which still resolves a non-watch run to availableParallelism() - 1
= 7 on this M3 — one worktree (mcp-inspector-wt-2336), no other gate, no
lease held, Spotlight's post-install indexing waited out before the first arm.
Arms were interleaved (default / --maxWorkers=4 / default per round, three
rounds) so ambient drift lands on every arm equally; the "reverted" arm is the
third slot of each round. CPU is user+sys from /usr/bin/time -l, which counts
the forked workers.

Work item 1 — the baseline re-measured at 7 (web unit, 345 files)

arm	n	wall (mean, min–max)	CPU	failures
default (7)	6	54.9s (45.0–64.5)	378s	0
maxWorkers: 4	3	62.4s (58.7–67.3)	294s	0

+14% wall, −22% CPU. In every round the capped run was the slowest of the
three. Vitest's own breakdown confirms the issue's CPU finding at smaller
magnitude than 8-vs-2: import 75–113s at 7 vs 51–59s at 4; tests 120–180s
vs 94–107s.

Work item 2 — under v8 coverage (web test:coverage, unit + integration, 422 files)

arm	n	wall (mean, min–max)	CPU	failures
default (7)	6	88.0s (87.3–89.0)	461s	0
maxWorkers: 4	3	122.5s (121.6–123.8)	376s	0

+39% wall, −18% CPU, with spreads under 2s — every capped run slower than
every default run. On the gate's heaviest stage a cap is ~35s on every solo
coverage:web, roughly a tenth of the whole six-minute gate.

Work item 3 — the flake rate

Solo, leased baseline: 0 failures in 18 runs, either arm. There was no flake
to cure at the baseline every other #2338 number is tuned to.

The question the lease leaves open is non-gate work in a sibling session, so I
also ran each arm against a concurrent bare vitest run --project=unit started
8s earlier in the same worktree (the sibling's outcome recorded too):

ours	sibling	pairings	ours wall	sibling wall	failures (ours / sibling)
7	7	5	98.7s	91.6s	0 / 2
4	7	3	107.1s	79.0s	0 / 0
4	4	3	101.7s	97.1s	0 / 0

• With the sibling at the default, capping ourselves costs +8% and hands the
  sibling 14% back — a politeness trade.
• With both capped (what a committed value would produce), both sides run
  at ~100s: the same total throughput as both at the default (99s + 92s). Eight
  cores are saturated either way; the CPU a cap saves does not come back as
  wall clock.
• The only failures in the whole campaign — 2 of the 10 runs at 7-vs-7, 0 of
  the 12 with a cap on either side — were the same test both times:
  AppRenderer.test.tsx › pushes a live theme flip …, whose 5s inner
  waitFor expired ("Number of calls: 0", 5017ms) under 14 workers. That is
  one site's inner budget starving at two sessions' worth of workers —
  aspect 3 of Make the test gate trustworthy on a machine running several agents at once #2338, fixable at that site (its inner budget is already the
  documented 5s-inside-15s shape) — not a case for taxing every solo run.

Feasibility note, as the issue asked: the sibling-session measurement was
affordable (~25 min) and clean (no other session was running a gate or Vitest;
verified by ps and the lease dir before starting). n is small — 5/3/3
pairings — so the 2-vs-0 is a consistent signal, not a rate.

The option chosen, and why not the others

Keep the default (no cap anywhere). Options 1–3 (a local-only cap, however
plumbed) all make the local gate and CI run different concurrency; the budgets
this knob interacts with are wall-clock, so a purely scheduling difference can
flip an outcome, and the gate's whole promise is that passing it locally means
CI passes. Option 4 (cap everywhere) pays the +39% on CI too. None of them buys
a measured failure reduction at the leased baseline. The default is also the
fastest single-session configuration, as the issue's own table said.

• The value is chosen, not derived. 7 is what the expression yields here;
  it is kept because it measured fastest, not because of any core count.
  macOS exposes no affinity API, so no cap is "one per P-core" — recorded in
  the comment for whoever reopens this.
• CI runtime impact: none. CI's runners resolve the same expression against
  their own core count; nothing changes for them.
• What would reopen it: the lease going away, or Test timed out recurring
  on a run whose only contention is a sibling session. The 4-vs-4 numbers above
  are the starting point.

Not done here: the tui project sweep from work item 2. The web unit and
coverage stages are the largest surfaces and the curve is the same shape on
both; I did not spend the machine time on the 24s TUI stage.