doctor's prescriptions don't always match what fixes headless sandboxes (order matters; a failing install-dawn isn't fatal)

Summary

Two related findings from running real coding agents against vgpu@0.2.0 through our agent-evals dogfooding harness (apps/agent-evals, merged in #253). Both are in the same subsystem — the ladder of remedies vgpu doctor gives an agent to go from unhealthy to healthy on a headless host.

Finding 1: doctor's primary prescription isn't the rung that actually works, on Debian/arm64

On ghcr.io/vercel/eve:latest (Debian, arm64) — one of the sandbox images our harness runs agents in — a fresh install is unhealthy out of the box:

[FAIL] linux-vulkan-loader: libvulkan.so.1 not found
[FAIL] linux-vulkan-icd: No Vulkan ICD manifest was found in /usr/share/vulkan/icd.d, VK_ICD_FILENAMES, or VK_DRIVER_FILES.
[FAIL] render: VGPU-NODE-NO-ADAPTER

doctor's prescription for this (lavapipePrescription() in packages/vgpu/lib/doctor/run.js) is one block of prose, primary rung first, alternative second:

run: npx vgpu install-software-renderer
Alternative (system packages): apt-get update && apt-get install -y libvulkan1 libdrm2 zlib1g libzstd1 libudev1 mesa-vulkan-drivers
export VK_ICD_FILENAMES=...

Running the primary rung alone (npx vgpu install-software-renderer) does not bring this image to healthy. What does is the rung listed second, the "Alternative (system packages)" apt install. Our harness's sandbox bootstrap (apps/agent-evals/agent/sandbox/sandbox.ts) walks doctor's own remedies in the order doctor recommends them and logs which one actually flips the verdict — on this image it's the second rung, never the first.

An agent reading the prescription top-to-bottom (the natural, literal reading) reaches for the thing that doesn't fix it before the thing that does.

Finding 2: a failing install-dawn looks fatal but isn't

Separately, on linux/x64 (verified in a real Vercel Sandbox, Amazon Linux 2023), npx vgpu install-dawn fails outright:

$ npx vgpu install-dawn
VGPU-NODE-PREBUILD-MISSING: unsupported platform linux/x64

(exit code 1)

This is expected in the sense that vgpu's own docs say the portable Dawn prebuild only targets Linux arm64: "Linux musl, other Linux CPUs, and other operating systems continue to try stock webgpu" (@vgpu/adapter-node/create-node-adapter docs). On linux/x64 that "stock webgpu" step is exactly what covers it — vgpu doctor's own resolution-order probe says as much: "Normal chain will try vgpu cache under <dir>, then stock webgpu at <path>, then the downloadable prebuild."

In practice: install-dawn fails, nothing else is done, and npx vgpu doctor right after reports healthy anyway — the webgpu npm package fallback already worked, install-dawn was never load-bearing on this platform. An agent that treats "a doctor-recommended command exited non-zero" as fatal and stops has no reason to; the only way to know the fallback covers it is to re-run doctor.

AX note (context, not a request)

prescription fields on doctor findings are multi-line prose ("run: ...\nAlternative (system packages): ...\nexport ..."), not structured/executable data. Our harness had to hardcode its own remedy ladder (see the REMEDIES array and the comment above it in sandbox.ts) instead of executing prescription directly, because shipping that string to a shell literally runs the word run: as a command. Mentioning it because it's the same shape as both findings above: whatever consumes doctor's prescriptions — agent or tooling — ends up having to second-guess the order/format doctor itself hands it.

Discussion (not proposing a specific fix — that's the doctor design's call)

A couple of directions that seem worth considering, no strong opinion on which:

• Platform/image-aware prescriptions (know that install-software-renderer alone doesn't cover this Debian/arm64 shape; put the system-package rung first there, or run both), or otherwise reorder so the rung that actually works comes first.
• For install-dawn-style failures that turn out non-fatal, say so in the message and name npx vgpu doctor as the arbiter, instead of leaving an agent to guess whether to stop.

How we found this

Both from running real coding-agent sessions (not synthetic) against vgpu@0.2.0 through our agent-evals harness (apps/agent-evals, merged in #253) — actual docker run / sandbox sessions with an agent driving the CLI, plus a manual spike reproducing the same steps by hand.

Reproduce

Finding 1 (Debian/arm64):

docker run --rm -it --platform linux/arm64 ghcr.io/vercel/eve:latest bash
npm i vgpu@0.2.0 && npx vgpu doctor        # unhealthy: libvulkan.so.1 not found, no ICD manifest, VGPU-NODE-NO-ADAPTER
npx vgpu install-software-renderer && npx vgpu doctor   # still unhealthy
apt-get update && apt-get install -y libvulkan1 libdrm2 zlib1g libzstd1 libudev1 mesa-vulkan-drivers
npx vgpu doctor                             # healthy

Finding 2 (linux/x64):

npm i vgpu@0.2.0
npx vgpu doctor          # unhealthy (no adapter yet)
npx vgpu install-dawn    # exit 1: VGPU-NODE-PREBUILD-MISSING: unsupported platform linux/x64
npx vgpu doctor          # healthy — via the stock `webgpu` fallback, install-dawn's failure was never blocking

Evidence

• packages/vgpu/lib/doctor/run.js — lavapipePrescription() / prescriptionsFor() (source of the two-rung prescription quoted above), and the resolution-order probe text ("Normal chain will try vgpu cache ... then stock webgpu ... then the downloadable prebuild").
• apps/agent-evals/agent/sandbox/sandbox.ts — the REMEDIES ladder, the comment explaining why prescriptions are hardcoded rather than executed, and the log line reporting which remedy actually worked.
• @vgpu/adapter-node/create-node-adapter docs (via npx vgpu docs cat create-node-adapter.md) — confirms the portable Dawn prebuild is arm64-only and that other platforms fall back to stock webgpu.

Happy to share full session transcripts if useful.