SDK suite flake: ENOENT '.relayflow/backlog-picker-entry.json' under vitest parallelism

[kjgbot]

Now that #153 makes CI run all 26 SDK test files rather than four, this will surface in CI periodically.

Symptom

Error: ENOENT: no such file or directory, open '.relayflow/backlog-picker-entry.json'

Observed once in roughly five full vitest run invocations. Re-runs of the same tree are clean, so it is order/timing dependent rather than a real failure:

run 1:  Test Files  1 failed | 23 passed | 1 skipped (25)
run 2:  Test Files  26 passed | 1 skipped (27)   ← same tree
run 3:  Test Files  26 passed | 1 skipped (27)   ← same tree

Likely cause

The path is relative, so it resolves against the process working directory rather than a per-test temp dir. Under vitest's default parallelism, sibling test files share that directory, so one test can create, consume or remove .relayflow/ while another is midway through using it.

The fix shape is probably to give the test its own temp directory and an absolute path, the way the kernel's fixtures already do, rather than to serialise the suite.

Why file it separately

It is unrelated to the v2 lane PRs; it was simply invisible while CI ran four named files. Noting it so an intermittent red on an unrelated PR is not misdiagnosed as that PR's fault.

Found while verifying #139 and #134 rebases.

[kjgbot]

Broader than this one test: the SDK suite has at least three Linux-only flakes

Now that #153/#154/#159 make CI actually run all 26 SDK files, several independent tests fail intermittently only on the runner. Each passes locally, repeatedly. Collecting them here because individually they look like "that PR broke something" and collectively they are the reason green is a coin flip.

test	symptom	local	seen on
backlog-picker (this issue)	ENOENT '.relayflow/backlog-picker-entry.json'	passes	#158, #134, #139
cli-hn-monitor > terminates (exit 1) when the worker emits an error asynchronously	expected +0 to be 1	16/16 over 3 runs	#134 (then passed on re-run), #139
live-kernel > follows a live worker dispatch through flows run	parked without a classifiable completion, and separately WARNING [unprovable_effects] Step "greet" command "printf" resolves, but its effects cannot be proven before execution	27/27	#139

Plus the kernel-side hang tracked separately as #160.

Why this matters for reading CI

Every one of these has already been mistaken for a PR's own defect at least once tonight, including by me:

• I attributed the agent::rung_c_sigkill_... hangs on Linux runners ~half the time, costing 30min and cancelling the job #160 hang to feat(sdk): settle data and code gate contract #139's gate work, then to fix(kernel): a dead leased attempt serves no retry delay #158's retry change. Both wrong — same commit hung and passed.
• feat(surface): add unpublished authored contract foundation #134's cli-hn-monitor failure looked like feat(surface): add unpublished authored contract foundation #134's bug until a re-run passed.
• feat(sdk): settle data and code gate contract #139's two failures above both pass locally and both passed on other PRs' runs.

The practical rule until these are fixed: a single red on one of these tests is not evidence. Re-run first, and only treat it as real if it reproduces or fails locally.

Shared shape worth checking

Two of the three look like ordering/timing against a shared resource rather than logic:

• the ENOENT is a relative path (.relayflow/…), so it resolves against the process working directory and is shared across parallel test files;
• expected +0 to be 1 is an exit code read before an async error has propagated.

Both are the kind of thing a slower, more contended runner exposes and a fast local machine hides. Worth checking whether these tests need per-test temp dirs and awaited teardown rather than individual fixes.

[kjgbot]

#190 has landed, but it does not close this — and the distinction matters.

The stated cause does not hold

A relative path racing under vitest parallelism was a good hypothesis, but every caller of the flow's steps already runs in its own mkdtempSync directory with an explicit cwd: backlog-picker.test.ts, backlog-picker-flow.test.ts, work-package-consumer.test.ts. There is no shared working directory to race over.

What the ENOENT text actually is

Expected output. Several tests here assert a step fails, and execFileSync echoes a failing child's stderr into the parent's — so a completely green run prints that stack trace. Six consecutive full suites on main before any change: 662 passed, 3 skipped every time, ENOENT text present every time.

#190 captures that stderr instead of echoing it, so the noise is gone (ENOENT lines: 0 across three runs; 2 when reverted). That removes the thing that gets misread, which is worth doing on its own.

Why this stays open

Your first run showed Test Files 1 failed | 23 passed | 1 skipped (25). Something genuinely failed then, and I have not explained it — I could not reproduce a failure in six full runs on current main.

Two honest possibilities, and I cannot distinguish them from here:

1. it was fixed incidentally — the suite has changed a lot since (ci: run the kernel and full SDK suites #153 widened it from four files to all of them, and fix(cli): a running run is not a protocol error (#179) #180, test(sdk): restore the four authored-flow cases dropped in #140 (#166) #184, fix(sdk): report the missing done(), not the step the author awaited (#183) #187 all landed in this area);
2. it is rarer than 1 in 6 and still present.

Closing this on "I could not reproduce it" would convert an unexplained failure into a silent one. If it recurs, it will now be legible: any ENOENT in the output is a real failure rather than expected noise, which was not true before #190.