linux-vm-test

name	linux-vm-test
description	Run ad-hoc Nub tests and debugging probes on real local Linux guests. Use for Linux-specific sandbox, kernel, distro, architecture, package, or runtime behavior that Docker cannot reproduce faithfully. Selects persistent Lima for source-mounted iteration or ephemeral Tart for clean-image reproduction.
metadata	{"internal":true}

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:

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:

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:

limactl shell landlock-vm -- bash -lc \
  'cd /Users/colinmcd94/.cache/nub/worktrees/<worktree> && <probe>'

Trace a guest command without modifying the host checkout:

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:

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:

limactl start landlock-vm
limactl stop landlock-vm

Clean Tart reproduction

Let the checked-in helper own lifecycle:

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.