feat(sessions,minimald,minvmd): session persistence contracts + provider index - #715

Stacked on #705. Now that session worktrees and the package cache survive a VM restart on the /dev/vdb volume, several things that were harmless when all state died with the per-boot tmpfs become persistent traps. This PR closes them.

Failure modes fixed

1. A corrupt session index bricks every session — silently, after READY.
The session store hard-failed to construct if sessions/index.json didn't parse. On a tmpfs that was nearly impossible (the file was rewritten every boot); on the persistent volume a torn write survives, and an unclean stop is exactly how you get one. The daemon then reached READY but every session RPC failed against the un-constructable store — a VM that looks healthy and can touch none of its sessions, with no path back short of hand-deleting the file.
Now: a parse failure is treated as recoverable (the index is derived state, not the source of truth). The store falls back to an empty index, rebuilds it from the per-session record.json files via the self-heal pass that already existed, and writes a valid index back. A read I/O error still fails — only corruption self-heals.

2. Stale provider identity persists across reboots.
providers/ holds boot-ephemeral identity — the host SSH key, known_hosts, socket paths. On the tmpfs it was regenerated every boot. On the persistent volume it would carry a previous boot's host key forward, so a client that learned the new key mid-session, or any host-key rotation, would silently mismatch.
Now: the guest resets providers/ after mounting the volume and before regenerating its instance dir, while sessions/ and cache/ are preserved. The reset only ever touches entries inside providers/ — never a glob over the state root — so persistent user data is untouchable by construction.

3. A dirty worktree silently swallows every push.
When a session's checked-out worktree had uncommitted changes, the git post-receive hook printed a note to stderr and continued — the push exited 0, the refs updated, but the working tree was never checked out. The client believes it deployed new code; the guest keeps running the old code. On a tmpfs the dirty state cleared on the next boot; on the persistent worktree it sticks, so every subsequent push to that session is silently ignored until someone manually cleans the tree.
Now: a pre-receive hook rejects the push loudly — ! [remote rejected] (pre-receive hook declined) and a non-zero git push exit — unless the client passes git push -o force-checkout, which discards the uncommitted changes and checks out. receive-pack advertises push options and sets receive.denyCurrentBranch=ignore (the hook pair, not git's default guard, owns worktree consistency). Recovery from a mid-checkout failure is a re-push.

4. The host can't locate a session that outlives its VM.
Sessions now persist on the volume image after the VM process exits, but nothing on the host recorded which image holds which session — the mapping lived only inside the ext4 image, invisible until a VM booted it. Any future routing of attach/activate to the owning VM (#311) had nothing to route against.
Now: a host-side ProviderIndex at <state>/session_index.json maps each session id to { image_path, vm_id }, written atomically. It's derived state — a corrupt or missing file loads empty and is rebuilt — so it never becomes its own failure mode.

Transport note (why not the guest→host RPC the design sketched)

Maintaining the index was originally sketched as the guest pushing session-lifecycle events to the host. That's unimplementable safely: libkrun's vsock wedges when a guest→host connection overlaps host→guest traffic (#588 — the failure that red-lit autospawn-e2e on #672), and lifecycle events fire precisely while the client's own host→guest SSH connection is open, so even one-shot emits can't be serialized clear of it. Instead the run supervisor polls ListSessions over the existing host→guest bridge (the proven direction) and reconciles the index — MINVMD_SESSION_POLL_SECS, default 15 s, 0 disables. Entries persist across VM stop (a stopped VM's sessions stay routable); the cost is bounded staleness, fine for a consumer that's future work. Only the run supervisor maintains the index — bare minvmd boot leaves nothing behind to poll. architecture.md is updated to record this.

Verification

Gated e2e (MINVMD_E2E=1, verified on macOS/HVF): a created session appears in session_index.json with the right image path and vm id, a destroyed one is removed, and a session live at minvmd stop persists in the index. Unit coverage: corrupt-index recovery (three shapes — bad bytes, wrong-shape JSON, corrupt-with-no-records), providers reset preserving sessions/cache, the git-push hook matrix (clean push, clean re-push, dirty rejection, forced override) driven against real git, and ProviderIndex round-trip / atomic-flush / corrupt-load.

Refs: #583. Full multi-VM routing on top of the index is #311.

🤖 Generated with Claude Code