Ignacy Łątka 2be58a5cf1 fix(boot-device): five correctness fixes from post-merge Linux review (#296) ...

## Summary

Five issues found in the post-merge code review of #249 (Linux support).
All confirmed present on main; none fixed by #194.

### H1 — `awaitFirstRealFrame` timeout leaves emulator running

`awaitFirstRealFrame` is called after the cold-boot `try/catch` closes.
On a SurfaceFlinger timeout the emulator process stayed alive:
`inFlightBoots.finally` cleared the map entry, so the next `boot-device`
call found the stale serial via the `alreadyRunning` fast path, had to
run `assertScreencapAlive`, killed it there, and then fell through to
another full cold boot — doubling latency and surfacing a confusing
"wedged framebuffer" error instead of the original timeout.

**Fix:** wrap the `awaitFirstRealFrame` call in a try/catch that calls
`killEmulatorQuietly` before re-throwing.

### H2 — `awaitFirstRealFrame` budget not clamped against
`overallDeadline`

Every `attemptBoot` stage clamps via `Math.min(params.attemptDeadline,
…)`. `awaitFirstRealFrame` received the fixed
`STAGE_BUDGET.firstRealFrame` (90 s) with no knowledge of
`overallDeadline`, allowing total wall time to silently exceed
`bootTimeoutMs` by up to 90 s — violating the documented contract and
the Zod schema's `max(900_000)`.

**Fix:** pass `Math.min(STAGE_BUDGET.firstRealFrame, Math.max(0,
overallDeadline - Date.now()))`.

### H3 — `ARGENT_SIMULATOR_SERVER_DIR` semantic changed without
migration hint

The env var previously pointed directly at the directory containing
`simulator-server`; it now points at the root of the per-platform tree.
A user with the old flat layout gets a bare "binary not found" with no
explanation of what changed.

**Fix:** detect the old flat layout and include a migration hint in the
error message; update the env var's doc comment.

### M4 — `ARGENT_EMULATOR_NO_WINDOW=false` silently enables headless
mode

`selectExtraEmulatorArgs` used a deny-list (`!== "0"`) so `"false"` and
`"no"` — natural shell idioms for "disabled" — both mapped to
`-no-window`. Test suite covered `""`, `" "`, `"0"` but not `"false"`.

**Fix:** switch to an allowlist `["1", "true", "yes"]`; add `"false"`
and `"no"` to the parameterized off-test.

### M5 — `bootstrapDylibPathTcp` / `nativeDevtoolsDylibPathTcp` missing
`requireDarwin`

All six non-TCP dylib/binary exports gained explicit `requireDarwin()`
guards in #249. The two TCP dylib exports did not. A Linux caller gets
"dylib not found" instead of "requires macOS host".

**Fix:** add `requireDarwin()` as the first statement in both TCP dylib
functions; add a test.

### S7 (bonus) — `selectGpuMode` validation fires mid-function after
slow I/O

`selectGpuMode()` and `selectExtraEmulatorArgs()` were called inside
deep nested code after several seconds of I/O. A typo in
`ARGENT_EMULATOR_GPU_MODE` surfaced late with a spurious "emulator has
been terminated" suffix appended.

**Fix:** call both once at the top of `bootAndroidImpl`, just after
`ensureDep`, and reuse the captured values — eliminates the late error
and the redundant double-call.

## Test plan

- `npm run test -w @argent/tool-server` — **847 passed** (was 845; +2
for `false`/`no` NO_WINDOW cases)
- `npm run test -w @argent/native-devtools-ios` — **10 passed** (was 8;
+2 for TCP dylib darwin gate and migration hint)

2026-06-03 17:32:28 +02:00

..

index.test.ts

fix(boot-device): five correctness fixes from post-merge Linux review (#296)

2026-06-03 17:32:28 +02:00