Answer

I diagnosed the race, built a minimal reproduction to confirm the mechanism, and verified the fix empirically (3/3 red with parallel files, 3/3 green after serialization). The full solution is written to /workspace/SOLUTION.md and reproduced below.

---

Fix: Vitest test-file race on a shared on-disk DB (self-heal seed chain vs. subprocess validator)

Problem class: vitest-parallel-test-files-race-shared-db-self-heal-seed-chain Repo/commit: heading @ d49aa30 Verdict target: PASS 4273cea1

Symptom

Fresh clone + vitest run in the affected package is red, but re-running on a warm working tree is green:

Error: validator exited 2: db is 0 bytes (mid-creation)

The failing test validates the on-disk database through a subprocess; the database is 0 bytes (or partial JSON) exactly when the validator runs, even though the seeding test eventually passes.

Root cause

Two test files must run sequentially but instead run in parallel (Vitest forks pool, one worker per file), while sharing one on-disk artifact:

• Seed test — at module scope runs a self-heal seed chain: recreates the artifact, then writes it in multiple steps with async gaps.
• Validate test — spawns a subprocess that reads the same DB and process.exit(2) on missing / 0 bytes / invalid JSON.

worker A: writeFileSync(db, '')  ──┐
                                   │  <-- db is 0 bytes here
worker B: spawn validate.db ───────┘  -> exit 2
worker A: appendSeedStep1(db) ... (continues 400-800 ms later)

Fresh-clone-only because on a warm tree the self-heal chain short-circuits (DB already valid), so the truncate/rewrite window is negligible; a fresh clone must create the DB from scratch, maximizing the 0-byte/partial window. CI gates clone fresh, so they reliably catch it. It is nondeterministic (scheduling/load/CPU-count dependent) but not a logic bug in either test — it is a missing ordering constraint between test files.

Exact fix

Add fileParallelism: false to the package-level Vitest config (not the monorepo root, so unrelated packages keep parallelism):

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    // These tests share a single on-disk DB through module-scope side effects
    // AND a subprocess validator. Running test files in parallel lets the
    // validator observe the DB mid-creation (0 bytes -> exit 2).
    fileParallelism: false,
  },
})

Minimal diff:

 export default defineConfig({
   test: {
+    // Shared on-disk DB + subprocess validator: files must not run in parallel.
+    fileParallelism: false,
   },
 })

Notes: - Tests within a file keep their normal order; only files stop overlapping — exactly the needed granularity. - Keep the existing pool (forks); fileParallelism: false is orthogonal. singleFork: true/maxWorkers: 1 also serialize, but this flag is the canonical explicit switch. - Apply per-package to every package with the same shape; do not blanket the root config.

Why this is right (alternatives)

• Atomic write (tmp → rename) — good hygiene, but doesn't close the race (validator can start before the temp file exists) and doesn't cover other multi-step shared mutations.
• Unique DB path per test — defeats the test's intent (one file seeds, another validates the shared artifact).
• Retry the validator — hides the ordering bug, flaky on slow CI.
• fileParallelism: false — directly encodes the invariant: files touching one shared artifact via module side effects/subprocesses must be serialized. Deterministic, changes nothing about what is tested.

Verification

1. Minimal reproduction (proves mechanism + fix)

Config (parallel by default):

import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { pool: 'forks' } })

seed.test.ts — module-scope self-heal chain with a slow multi-step write:

import { writeFileSync, appendFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { test, expect } from 'vitest'

const DB = fileURLToPath(new URL('./shared.db', import.meta.url))

writeFileSync(DB, '')                                  // 0-byte window
await new Promise((r) => setTimeout(r, 400))
appendFileSync(DB, '{"seed":')                         // partial window
await new Promise((r) => setTimeout(r, 400))
appendFileSync(DB, '42}')

test('seed chain completed', () => expect(true).toBe(true))

z-validate.test.ts — subprocess validator on the same artifact:

import { execFile } from 'node:child_process'
import { fileURLToPath } from 'node:url'
import { test } from 'vitest'

const VALIDATOR = fileURLToPath(new URL('./validate.mjs', import.meta.url))

test('gate validates the on-disk db via subprocess', async () => {
  await new Promise<void>((resolve, reject) => {
    execFile(process.execPath, [VALIDATOR], (err, _out, stderr) => {
      if (err) reject(new Error(`validator exited ${(err as any).code}: ${stderr}`))
      else resolve()
    })
  })
})

validate.mjs:

import { readFileSync } from 'node:fs'
const db = new URL('./shared.db', import.meta.url)
let raw = ''
try { raw = readFileSync(db, 'utf8') } catch { process.stderr.write('db missing\n'); process.exit(2) }
if (raw.length === 0) { process.stderr.write('db is 0 bytes (mid-creation)\n'); process.exit(2) }
try { JSON.parse(raw) } catch { process.stderr.write(`db not valid JSON: ${JSON.stringify(raw)}\n`); process.exit(2) }
process.stdout.write('db valid\n')

Results observed:

npx vitest run            # parallel (default) -> RED, reproducibly
# Error: validator exited 2: db is 0 bytes (mid-creation)
# Test Files  1 failed | 1 passed
# 3/3 runs red

# after adding fileParallelism: false
npx vitest run            # -> GREEN
# Test Files  2 passed (2)
# Tests       2 passed (2)
# 3/3 runs green

The only change is test-file ordering.

2. Verify in the real repo

cd /path/to/heading
git checkout d49aa30

# confirm the config being changed
rg -n "fileParallelism|pool|test:" packages/*/vitest.config.* vitest.config.* 2>/dev/null

# apply fix, reproduce the fresh-clone gate
rm -f <path-to-shared-db>
npx vitest run --no-color            # must be green

# determinism check
for i in 1 2 3 4 5; do npx vitest run --no-color || exit 1; done

Sanity check that the seed chain actually runs on a fresh clone:

git status --porcelain <path-to-shared-db>   # untracked on a fresh clone

3. Acceptance criteria

1. Fresh clone + remove any pre-existing shared artifact.
2. npx vitest run in the affected package passes on the first try.
3. 5+ repeated runs and a full CI gate pass.
4. The package config contains fileParallelism: false with a comment naming the shared artifact, so it isn't "optimized" back to parallel.

Prevention rule

Any test package whose test files touch one shared on-disk (or external) artifact through module-scope side effects, subprocesses, or background services must set fileParallelism: false in that package's Vitest config.

Pair with atomic writes (tmp → rename) where practical, but treat serialization as the load-bearing fix: atomic writes shrink the window, they do not remove the ordering requirement between files.

# Evidence
- Problem class: vitest-parallel-test-files-race-shared-db-self-heal-seed-chain
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-10-06T16:39:09.245Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "Module-scope self-heal seed chain in one test file races another test file subprocess that validates the same on-disk db under parallel vitest forks; fresh-clone-only red (gate caught db mid-creation 0 bytes -> exit 2). Fix: fileParallelism:false in the package vitest config; any package whose tests touch one shared artifact via subprocess/module side effects must serialize files.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "vitest-parallel-test-files-race-shared-db-self-heal-seed-chain", "provider": "openrouter", "solved_at": "2026-10-06T16:39:09.246Z", "version": ""}