Docs: building on a VM with a generic CPU model (kvm64/'Common KVM processor') hangs the agent-binary install

[rappdw]

Symptom

On a Proxmox (or any QEMU/KVM) VM using the default generic CPU model, sandy hangs at:

[sandy] Building sandbox image (may take a few minutes)...

with one process pegged at ~90% CPU: /home/claude/.claude/downloads/claude-2.1.220-linux-x64 install (or the grok binary equivalent). It never finishes.

Root cause

Claude Code 2.x (and grok) ship as native binaries with an embedded JS/JIT runtime; npm install -g runs the binary's install post-step during the image build. On a generic VM CPU model (kvm64 / qemu64 / lscpu "Model name: Common KVM processor"), the advertised feature set is x86-64-v1 baseline — no sse4_2, popcnt, avx, avx2. The JIT runtime hits a fallback/detection path that busy-loops in userspace (confirmed: R state, ~90% CPU, and strace shows zero syscalls → not network, not I/O; VLAN egress is a red herring). Same-arch (x86_64 both sides), so it's not cross-arch QEMU emulation. It works fine in CI / on real hardware because those expose full CPU features.

Fix (for the user)

Give the VM real CPU features:

• Proxmox → VM → Hardware → Processors → Type → host (or x86-64-v3 / x86-64-v2-AES if live-migration constrains you).
• Cold-boot the VM (Stop → Start; CPU type only changes on a fresh power cycle).
• Verify: lscpu | grep -o 'avx2\|sse4_2\|popcnt' should now show them.

The ask (docs)

Add a short Troubleshooting note (README and/or SPECIFICATION Appendix D / a TROUBLESHOOTING section):

• "Build hangs at Building sandbox image with a claude-*/grok process at ~100% CPU and no output" → generic VM CPU model; sandy runs native agent binaries that need an x86-64-v2+ feature floor; set the VM CPU type to host (or x86-64-v2+) and cold-boot.
• Note the diagnostic tell: lscpu shows Common KVM processor / sparse flags; strace shows no syscalls (pure userspace spin) which distinguishes it from a network/egress stall.

Optional (beyond docs)

Consider a launch-time preflight warning: if /proc/cpuinfo flags lack avx2 (or sse4_2), print a one-line heads-up before the build that agent-binary installs may spin and to use a host/x86-64-v2+ CPU type. Cheap, and turns a silent multi-minute hang into an actionable message. (Discuss whether to gate the build or just warn.)