feat: microVM isolation per role with a validated runbook (0.20.0)

CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to `codesema` (the npm package in `packages/cli`) are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org).
 
+## [0.20.0] - 2026-08-28
+
+### Added
+
+- **`isolation: "microvm"`: a task's turn runs in a disposable Microsandbox VM.** Beside `container` and `policy`, the runner can now boot a throwaway microVM (libkrun/KVM, `microsandbox` SDK 0.6.15 as an optional dependency) per turn: the worktree is copied in, the agent runs as a non-root user with the same tools as the cage, the result is copied back and the VM is destroyed. Never picked by `auto`; `codesema runner serve` refuses to create a `microvm` task when the workspace was not probed for it (`msb doctor` is the way out). The seam is `SandboxDriver` (`microsandbox-driver.ts`, with a `FakeSandboxDriver` for every test) and `runMicrovmTurn`.
+- **The runbook: how a repository is installed, started and tested, validated by actually doing it.** `codesema runbook scan` lets an agent propose `.codesema/runbook.json` (image, install, services, healthchecks, tests, egress allowlist, `depends_on_files`), then replays it in a microVM and only keeps a runbook whose tests pass. The runner daemon claims and runs one queued hub runbook scan per tick in `microvm` mode. `@codesema/contract` 0.11.0 carries `RunbookConfig`, `RunbookValidation`, `RunbookScan` and their sanitizers.
+- **Mechanical verification of a microvm task.** After a turn's commit and before the review, `verifyTask` replays the validated runbook's `tests` in a fresh VM restored from the project snapshot; a drift of `depends_on_files` since validation refuses the verification outright. The verdict (`TaskVerification`) is persisted, reported to the hub, folded into the reviewer's prompt as a mandatory chapter, and a refused or failed verification sends the task back exactly like red checks.
+- **Warm per-project snapshot.** `microvm-snapshot.ts` builds one snapshot per project (image + `install` + services), keyed by a fingerprint of lockfiles, compose file and canonical runbook; older ones are purged, and a runbook needing a flat root disk (dockerd) falls back to a cold boot.
+- **Checks, review and ship run in their own sandboxes for a microvm task.** `runChecks`, `runAdHocCheck` and `bootstrapWorktreeInstall` accept a `StepExecutor` (`microvmStepExecutor`); the reviewer runs in a read-only VM distinct from the dev VM (`runMicrovmReview`, network limited to the Anthropic hosts); the push and the merge request come from a dedicated `codesema-gitops-<taskId>` sandbox with the forge token carried as a placeholder secret only, never in argv or env. Orphaned `codesema-*` sandboxes are swept at boot.
+- **Hub contract for the runbook loop.** New `hub-client` calls: `listRunbookScans`, `claimRunbookScan`, `reportRunbookScanResult`, `failRunbookScan`, `currentRunbook`, `verification`; the `merged` transition carries `changed_files` so the hub can mark a runbook stale.
+
+### Changed
+
+- **`TaskIsolation` gains `microvm`** (`@codesema/contract`, CLI config, web UI badge and plan): a task record carries `runbook_sha`/`runbook_integrity` when it was verified against a runbook.
+- **The reviewer resolves the microvm snapshot, runbook and mechanical verification per task turn** (`resolveReviewContext`) instead of freezing them once per project, and finding repro checks of a VM-isolated task run through the injected microvm `StepExecutor` instead of always falling back to docker/podman.
+- **The web workspace shows a microVM badge, plan label and build-image hint** for `microvm` tasks instead of folding them into `policy`.
+- **Microsandbox SDK pinned to 0.6.16** (was 0.6.15), which requires an `msb` 0.6.16 runtime and a store created by it: the published 0.6.16 cannot open a store created by 0.6.15 (its migration `m20260818_sandbox_network_slot` is ordered before 0.6.15's last one), so an existing `~/.microsandbox` from 0.6.15 has to be moved aside and the project snapshots rebuilt.
+
+### Fixed
+
+- **Review findings folded in before release** (adversarial review of the microvm lots, 23 confirmed findings). Ship: an origin URL embedding credentials is stripped before it reaches the gitops sandbox, host-side `credential.helper`/`http.*.extraheader` are purged in the guest, and an unknown forge gets both `GH_TOKEN` and `GITLAB_TOKEN` declared instead of a guess; the forge token is picked from the project's actual remote, never from whichever env var happens to exist. Checks: `microvmStepExecutor` copies `/work` back after every step (an install step's result reached nobody before), mounts the linked worktree's git common dir and removes the synthetic `.git` pointer before the copy-back. Review: dual mode gave both lanes the same sandbox name; the review VM's destroy is guarded and its duration carries the same headroom as checks. Turn: `destroy()` is memoised and awaited after the worktree copy-back (a killed turn could lose its files), and the guest user name is validated before being interpolated in root scripts. Runbook scan: the claim is renewed every half-lease while the scan runs and no result is reported once the lease is lost; a scan whose `head_sha` does not match the local HEAD is skipped instead of validating the wrong commit. `merged` transitions now carry `changed_files` so the hub can mark a runbook stale. `sanitizeTaskVerification` refuses a record without `head_sha` and bounds its timestamps like the hub does; the real Microsandbox driver refuses a sandbox without a network policy, like the fake always did.
+- **Real microVM run findings folded in** (local end-to-end on Microsandbox 0.6.15, 2026-08-29). `user` and `workdir` on the sandbox spec made every `create()` fail (the guest user is created and used from the scripts instead); `copyFromHost`/`copyToHost` only moved single files (directories are tarred); the runbook proposal was parsed twice and always rejected; no VM ever had the agent CLI (it is now baked into the project snapshot at build time, `registry.npmjs.org` allowed for that build only, installed at boot on a cold VM); provider secrets never reached the proposal VM; `listSandboxes` asked the SDK for more than its 100 cap; the boot probe never probed Microsandbox so a `microvm` project silently degraded to `policy`; the validated runbook was read from the task worktree where it never exists (read from the project root, with `.codesema/runbook.validation.json` written by `codesema runbook scan` carrying the validated sha); `git push` from the gitops sandbox was refused as dubious ownership; a sandbox the SDK provisioned before `create()` failed is now removed. Two driver defects made every `create()` after the first `destroy()` of a long-lived server fail with `FOREIGN KEY constraint failed` or `disk I/O error` and leave a `[libkrun VM] <defunct>` zombie: `destroy()` stopped a handle re-fetched with `Sandbox.get` instead of the native instance `create()` returned (the only one that reaps the VM process), and a per-destroy purge rewrote `~/.microsandbox/db/msb.db` under the live SDK connection. `destroy()` now stops the original instance first, the purge is gone, and the secret values the runtime leaves in the store WAL are scrubbed (`wal_checkpoint(TRUNCATE)` + `VACUUM`) once per process before the SDK is loaded, skipped with a notice while another process holds the store open.
+- The package cache volume of the checks step is now mounted with `namedWith(name, 'ensure-exists')`: a `named()` mount is existing-only in the SDK and failed the first checks attempt of every task with `volume not found` even right after `ensureVolume()` had returned, so the volume is created or reused inside the same `create()` call.
+
+
 ## [0.19.0] - 2026-08-28
 
 ### Added

README.md

@@ -58,7 +58,9 @@ From the page you can also:
 
 **Checks run in a sandbox.** Alongside the review, typecheck, tests and lint run in an ephemeral `docker` or `podman` container mounted on the task's worktree, with `--network none` and cpu/memory caps. The plan comes from your `checks` key, otherwise from what the repository already declares (lefthook hooks, CI workflow jobs, filtered through a command allowlist), otherwise from the lockfile and the `typecheck`/`test`/`lint` scripts of `package.json`. Checks never block a task: they are a second opinion next to the review.
 
-**Tasks can be caged.** With a container runtime available, a task runs inside a container built from your `.devcontainer` (or `node:26`): the worktree is the only writable host mount, the git directory is mounted read-only, and the only network exit is a proxy restricted to the agent's own API domains (`isolationAllowedDomains`). Commits stay on the host, so your git credentials never enter the container. `isolation` picks the mode: `auto` (default, falls back to host hardening and says why), `container` (mandatory) or `policy` (always on the host). `claude` and `opencode` are cageable today.
+**Tasks can be caged.** With a container runtime available, a task runs inside a container built from your `.devcontainer` (or `node:26`): the worktree is the only writable host mount, the git directory is mounted read-only, and the only network exit is a proxy restricted to the agent's own API domains (`isolationAllowedDomains`). Commits stay on the host, so your git credentials never enter the container. `isolation` picks the mode: `auto` (default, falls back to host hardening and says why), `container` (mandatory), `policy` (always on the host) or `microvm` (mandatory, a disposable Microsandbox VM instead of a container). `claude` and `opencode` are cageable today.
+
+**Or run in a disposable microVM.** Set `isolation: "microvm"` and a task's whole turn runs inside a fresh [Microsandbox](https://microsandbox.dev) VM instead of a container — stronger isolation than a container's namespaces, at the cost of a heavier, beta dependency. Requires Linux with `/dev/kvm` readable and writable by your user (`msb doctor` checks this) and a filesystem with reflink support (btrfs, xfs) — without it every VM copies its whole root disk on boot instead of a near-instant clone. The agent runs as a non-root guest user with no view of the host beyond a copy of the task's worktree (copied in before the turn, copied back after — there is no live mount), and the same domain allowlist as the container cage, substituted by the VM's own network proxy: the agent's provider credentials reach the guest only as `$MSB_<name>` placeholders, never as a value it could read or leak. Unlike `container`, `auto` never picks `microvm` on its own — it is beta software with a heavier host requirement, so it only ever runs when you set it explicitly.
 
 **Statuses.** A task moves through `queued`, `running`, `waiting_for_you` (the agent ended its turn on a question), `reviewing`, then `review_ok` or `review_ko`, then `shipped` once the branch is pushed and the merge request opened via `gh`/`glab`. `interrupted` covers a turn cut short by Ctrl-C, a crash or the Stop button: the worktree and the agent session are kept, and a Resume button restarts that exact turn. Nothing restarts by itself at the next boot.
 
@@ -122,31 +124,31 @@ Settings live in two files, and CLI flags win over both:
 
 Some keys are global only: they govern the machine (its load, its disk) or give a consent (merging, spending turns), so a cloned repository cannot set them on your behalf. A repository file that does is ignored, and says so at startup.
 
-| Key                                                        | Default                             | Scope           |
-| ---------------------------------------------------------- | ----------------------------------- | --------------- |
-| `agent`, `agentId`, `model`, `effort`                      | from the wizard                     | both            |
-| `language`                                                 | asked once (`en`, `fr`)             | both            |
-| `target`                                                   | auto-detected                       | both            |
-| `port`                                                     | `4400`                              | both            |
-| `timeout`                                                  | `900` seconds                       | both            |
-| `reviewMode`                                               | `simple` (or `dual`)                | both            |
-| `maxAutoFixRounds`                                         | `2`                                 | both            |
-| `isolation`                                                | `auto` (`container`, `policy`)      | both            |
-| `isolationAllowedDomains`                                  | the agent's own API domains         | both            |
-| `forgeCycleLabels`                                         | `false`                             | both            |
-| `checks`                                                   | inferred from the repository        | repository file |
-| `watchdogInactivitySeconds`                                | `1800`                              | both            |
-| `watchdogToolBudgetSeconds`                                | `7200`                              | both            |
-| `watchdogHeartbeatSeconds`                                 | `30`                                | both            |
-| `maxConcurrentAgents`                                      | `4`                                 | global only     |
-| `taskRetentionCount`                                       | `20` finished tasks per project     | global only     |
-| `maxTaskTurns`                                             | `30`                                | global only     |
-| `mergePolicy`                                              | `human` (or `auto`)                 | global only     |
-| `mergeStrategy`                                            | unset (`merge`, `squash`, `rebase`) | global only     |
-| `deleteBranchAfterMerge`                                   | `false`                             | global only     |
-| `allowMergeWithoutChecks`                                  | `false`                             | global only     |
-| `runnerAutoMerge`                                          | `true`                              | global only     |
-| `syncUrl`, `syncWorkspaceId`, `syncSecret`, `syncAutoPush` | unset                               | global only     |
+| Key                                                        | Default                                   | Scope           |
+| ---------------------------------------------------------- | ----------------------------------------- | --------------- |
+| `agent`, `agentId`, `model`, `effort`                      | from the wizard                           | both            |
+| `language`                                                 | asked once (`en`, `fr`)                   | both            |
+| `target`                                                   | auto-detected                             | both            |
+| `port`                                                     | `4400`                                    | both            |
+| `timeout`                                                  | `900` seconds                             | both            |
+| `reviewMode`                                               | `simple` (or `dual`)                      | both            |
+| `maxAutoFixRounds`                                         | `2`                                       | both            |
+| `isolation`                                                | `auto` (`container`, `policy`, `microvm`) | both            |
+| `isolationAllowedDomains`                                  | the agent's own API domains               | both            |
+| `forgeCycleLabels`                                         | `false`                                   | both            |
+| `checks`                                                   | inferred from the repository              | repository file |
+| `watchdogInactivitySeconds`                                | `1800`                                    | both            |
+| `watchdogToolBudgetSeconds`                                | `7200`                                    | both            |
+| `watchdogHeartbeatSeconds`                                 | `30`                                      | both            |
+| `maxConcurrentAgents`                                      | `4`                                       | global only     |
+| `taskRetentionCount`                                       | `20` finished tasks per project           | global only     |
+| `maxTaskTurns`                                             | `30`                                      | global only     |
+| `mergePolicy`                                              | `human` (or `auto`)                       | global only     |
+| `mergeStrategy`                                            | unset (`merge`, `squash`, `rebase`)       | global only     |
+| `deleteBranchAfterMerge`                                   | `false`                                   | global only     |
+| `allowMergeWithoutChecks`                                  | `false`                                   | global only     |
+| `runnerAutoMerge`                                          | `true`                                    | global only     |
+| `syncUrl`, `syncWorkspaceId`, `syncSecret`, `syncAutoPush` | unset                                     | global only     |
 
 `maxParallelTasks` is the former name of `maxConcurrentAgents`. It is still honoured, with a warning at startup.