AGENTS.md

Things that aren't obvious from the code and that I keep forgetting to tell you. Read once, then act on them silently.

After merging a feature branch, bump the workspace version

Every merge into rewrite-microsandbox ships with a workspace.package.version bump in the root Cargo.toml and a follow-up vX.Y.Z: bump for <feature> commit. Skipping this leaves the next release boundary ambiguous and means downstream agent-vm --version lies about what's in the binary.

Convention (look at git log --oneline | grep "^[a-f0-9]* v"):

git merge --no-ff <feature-branch>     # produces "Merge ...: ..."
$EDITOR Cargo.toml                     # version = "0.1.N+1"
git commit -am "v0.1.N+1: bump for <one-line feature>"

Cargo.lock will need refreshing — run a build after the bump to update it, then commit the lock alongside the version bump if it moved (it always does).

Submodule merges go first

vendor/microsandbox is a submodule with its own branches. When a worktree changes both the agent-vm code and the vendored microsandbox code, merge inside the submodule before merging the superproject — otherwise the superproject merge will conflict on the gitlink and you'll have to redo the submodule merge anyway. Pattern:

1. cd vendor/microsandbox && git merge --no-ff <subm-feature-branch>
2. cd ../.. && git add vendor/microsandbox (bumps the gitlink)
3. git merge --no-ff <agent-vm-feature-branch> (resolves the gitlink conflict to the merge SHA from step 1)

If the feature branch lives in a separate git worktree, the submodule branches in that worktree's .git/modules/... are not visible from the main worktree. Push them across with git -C <worktree>/vendor/microsandbox push <main-worktree>/.git/modules/vendor/microsandbox <branch>:<branch> before attempting the submodule merge.

Don't relocate build output to /tmp or /dev/shm

If a build is too big, slow, or runs out of inodes, fix the root cause. Don't sidestep by pointing CARGO_TARGET_DIR at tmpfs — that loses everything on reboot, masks real disk pressure, and the next agent will spend an hour relinking from cold.

Don't rm -rf state directories from the assistant turn

Claude Code prompts on every rm -rf and it's painful. The repo ships /tmp/clean-state.sh for state cleanup — use it, or write a new short script if it doesn't cover your case. Inline rm -rf in tool calls is a UX papercut for the human, not a safety win.

When in doubt about scope, read the prior commit messages

Commits on this branch use a multi-paragraph "Why / How" style with real examples (often live e2e output). Match the style; don't write single-line commits for non-trivial changes. The commit body is where future-you (or future-me) recovers the reasoning.