diff --git a/vmbox/NEXT_SESSION_PROMPT.md b/vmbox/NEXT_SESSION_PROMPT.md new file mode 100644 index 0000000..085edc3 --- /dev/null +++ b/vmbox/NEXT_SESSION_PROMPT.md @@ -0,0 +1,121 @@ +# Next session: make vmbox the default place scripts get tested + +Paste everything below into a fresh Claude session. + +--- + +`~/utils/vmbox` is a working disposable-Arch-VM sandbox (built and verified +2026-08-22, pushed to `github.com/kuhyx/utils`). Read `~/utils/vmbox/README.md` +first — it documents the design and the traps. + +Two jobs this session, in order. + +## Job 1: harden it by using it for real + +vmbox has only ever been driven by one session, against a handful of scripts. +`testsAndMisc/linux_configuration` is ~1090 files, ~170 of which need root. +**Expect it to break.** That is the point of this job: find the breakages by +running real work through it, and fix them. + +Work through this list, fixing vmbox whenever it gets in the way: + +1. The 8 Arch-only tests the repo's CI already names in + `.github/workflows/shell-tests.yml` (`arch-tests` job) — `test_hosts_*`, + `test_makepkg_*`, `test_pacman_wrapper_security.sh`, + `test_security_hardening.sh`, `test_shutdown_timer_monitor.sh`. These are + the ones its comments say "cannot run on an Ubuntu runner". Run them in a + sandbox and report which pass. +2. `test_security_hardening.sh` specifically: on a bare guest it reports its + host checks as *skipped*. Install the real system first + (`install_core_system.sh`), then re-run it, so those checks become real. +3. `setup_night_lockdown.sh` — writes `/etc/systemd/system` units and an + i2c module config. The i2c RGB part is hardware and will not work; confirm + everything else does. +4. `boot_recovery/install.sh` — pacman hooks + mkinitcpio. Highest blast + radius of anything in the repo, and the best argument for the sandbox. +5. The hosts guard (`periodic_background/hosts/install.sh`) — rewrites + `/etc/hosts` and makes it immutable with `chattr +i`. Verify the immutable + flag really lands in the guest, then that `vm reset` clears it. + +For each: `vm share` what it needs, clone into the guest, run it, report what +happened. When vmbox itself is the thing that broke, fix vmbox and commit. + +### Known-good invocation shape + +```bash +vm share ~/testsAndMisc # bind mount, NOT a symlink (9p won't follow one) +vm share ~/utils # guard-lib lives here; several scripts need guardctl +vm new t1 --rtc 2026-08-22T20:55:00 # pin the clock: shutdown scripts gate on 21:00-05:00 +vm run t1 'git clone --no-hardlinks -q /mnt/hostrepo/testsAndMisc ~/tam' +vm run t1 'echo y | sudo bash ~/tam/path/to/script.sh enable' # many prompt; stdin is closed +vm reset t1 # ~2s back to pristine +``` + +### Traps already paid for — do not rediscover these + +- **A guest that boots but refuses ssh is almost never a network problem.** + Run `systemctl list-jobs` on the guest via `vm ssh` or the serial console. A + unit that is enabled, has satisfied dependencies, and neither starts nor + fails is QUEUED behind something. That cost most of a session. +- **Never grep a `bash -x` trace for the failure** — you find where your + pattern matched, not where execution stopped. Read the tail. +- **`pkill -f `** kills the Bash-tool shell when the pattern appears + in the command running it (exit 144). Use `pgrep -f | xargs -r kill`. +- Full list: `~/.claude/projects/-home-kuhy/memory/reference-vmbox-guest-image-traps.md` + and `reference-qemu-shutdown-verification.md`. + +### Rebuilding the image + +`vm build --force` takes ~10 min. It ends with a smoke test that boots a real +sandbox and refuses to ship an unreachable image. **Do not debug the image by +rebuilding per hypothesis** — boot an overlay off the current base, fix it live +over the serial console (root autologin is on ttyS0 and ttyS1), confirm the +fix, and only then bake it into `guest/provision.sh` and rebuild once. + +## Job 2: make it the default, once Job 1 says it is trustworthy + +kuhy's ask: *"claude should ALWAYS defer to using this sandbox when testing +stuff, ESPECIALLY when testing scripts."* + +**Do Job 2 only after Job 1.** A rule that routes work into a tool that +breaks is worse than no rule. If Job 1 leaves vmbox flaky, say so and stop. + +The rule belongs in `~/.claude/CLAUDE.md`. Points to settle with kuhy before +writing it — these are real forks, not rhetorical: + +- **What triggers it.** "Any script" is too broad: it would send a one-line + `python_pkg` unit test through a VM boot. A sharper line is anything that + needs root, writes outside `$HOME`, touches systemd/pacman/`/etc`, or could + power the machine off. +- **What it replaces.** Today's `CLAUDE.md` development workflow says "run the + actual script to verify it does what it is supposed to do". Does the sandbox + become the *first* run, or an extra step before the host run? Note the + standing `feedback-verify-real-deployment-path` memory: testing somewhere + that is not the real deploy target has burned kuhy before, so a sandbox pass + must NOT be presented as proof the host is fine. +- **The escape hatch.** Anything hardware-bound (adb/phone, GPU, i2c, the + Huion tablet) cannot run in a VM. The rule needs a stated exception, or it + will be violated on the first phone task and quietly stop being followed. +- **Where it lives.** `CLAUDE.md` is always-on context, so keep it to a few + lines and link out. Per `token-spend.instructions.md`, a long rule there is + a permanent per-turn tax. + +Draft it, get kuhy's sign-off on those four points, then write it. + +## Definition of done + +- The 5 items in Job 1 have been run in a sandbox, with results reported per + item (pass / fail / not-applicable-in-a-VM, with reasons). +- Every vmbox bug found is fixed, committed, and pushed. +- `bats ~/utils/vmbox/tests/test_vmbox.bats`, shellcheck and ruff all clean. +- Either the CLAUDE.md rule is written and agreed, or there is a clear + statement of what still makes vmbox untrustworthy. + +## State as of handoff + +Verified working: the shutdown verdict (5 outcomes, all measured against real +guests), destructive demo 7/7, reset ~2s, VM-to-VM ping (0% loss), screenshots, +pinned clock, repo share + clone, base-corruption guard, build smoke gate. + +Unverified / not attempted: everything in Job 1 above; anything hardware-bound; +concurrent sandboxes beyond two.