linux-vm-test

# Linux VM testing Use a real VM only when the behavior depends on a Linux kernel or guest OS. Prefer Docker for userspace-only clean-cache/config experiments and `ci-adhoc-test` for unavailable architectures, distributions, or release-platform proof. Two local backends serve different purposes: - Lima `landlock-vm`: persistent Ubuntu arm64 debugger with the host home mounted read-only. - Tart: disposable Ubuntu arm64 guest for clean-machine or alternate-image reproduction. ## Preflight Inspect both backends before changing VM state: ```sh limactl list tart list limactl shell landlock-vm -- bash -lc \ 'uname -srm; . /etc/os-release; echo "$PRETTY_NAME"; df -h "$HOME" /tmp' ``` Confirm the source mount before treating it as writable: ```sh limactl shell landlock-vm -- bash -lc \ 'findmnt -T /Users/colinmcd94/Documents/projects/nub' ``` The known Lima mount is read-only. Never build in `/Users/colinmcd94/**`. If the guest disk is full, report it and ask before reclaiming space. Never stop, delete, or clean an existing VM merely to make room. ## Persistent Lima debugging Run a short probe synchronously against the exact host source state: ```sh limactl shell landlock-vm -- bash -lc \ 'cd /Users/colinmcd94/.cache/nub/worktrees/<worktree> && <probe>' ``` Trace a guest command without modifying the host checkout: ```sh limactl shell landlock-vm -- bash -lc \ 'strace -f -o /tmp/nub.strace -- <command>' limactl shell landlock-vm -- bash -lc \ 'bpftrace -l "tracepoint:syscalls:sys_enter_*" | head' ``` For a Linux Rust build, copy the exact source state into guest-local storage and use a guest-only target directory: ```sh limactl shell landlock-vm -- bash -lc ' mkdir -p "$HOME/src" "$HOME/.cache/nub/linux-vm-target" src=/Users/colinmcd94/.cache/nub/worktrees/<worktree> dest="$HOME/src/nub-<slug>" rsync -a --delete \ --exclude .git --exclude target --exclude node_modules \ "$src/" "$dest/" cd "$dest" export CARGO_TARGET_DIR="$HOME/.cache/nub/linux-vm-target/<slug>" cargo build -p nub-cli --profile fast cargo test -p nub-cli --test <test_stem> ' ``` Repeat the copy after host edits. Use the exact host worktree under test, a distinct guest target for each branch or probe, and direct Cargo commands because the copied tree intentionally omits Git metadata. Remove only probe-owned files after capturing evidence; do not sweep guest caches or unrelated targets. Start or stop the persistent VM only when required: ```sh limactl start landlock-vm limactl stop landlock-vm ``` ## Clean Tart reproduction Let the checked-in helper own lifecycle: ```sh tests/vm/tart-vm.sh up <name> <image> tests/vm/tart-vm.sh exec <name> -- bash -lc '<probe>' tests/vm/tart-vm.sh run <name> ./probe.sh tests/vm/tart-vm.sh down <name> tests/vm/tart-vm.sh rm <name> ``` Use a unique VM name. The `run` operation copies one script when `sshpass` is installed and otherwise streams its body; it does not copy a fixture tree or checkout. Fetch or copy multi-file fixtures deliberately. Finish a throwaway run with `rm`; `down` intentionally preserves the disk. ## Evidence Record: - Host commit plus dirty-state summary. - Guest distro, kernel, and architecture. - Exact command and environment overrides. - Exit status, stdout, and stderr. - Relevant trace or log path. Copy concise results to the host before deleting a Tart guest. Do not claim x86_64 coverage from these Apple-Silicon arm64 VMs. Use `ci-adhoc-test` when the claim requires x86_64-native behavior or another unavailable platform.