feat: add microVM execution environments

.claude/plans/microvm-execution-environments/README.md

@@ -0,0 +1,8 @@
+# MicroVM execution environments orchestration
+
+Acceptance plan: `docs/acceptance/microvm-execution-environments.md`
+Accumulator: `acc/microvm-execution-environments`
+Epic: stacklok/mecatl#526
+
+Task files are orchestrator-managed. Git ancestry on the accumulator is authoritative.
+Every implementation worker uses an isolated worktree and task branch.

.claude/plans/microvm-execution-environments/tasks/01-module-contract.md

@@ -0,0 +1,26 @@
+---
+id: 01-module-contract
+title: Nested module boundary and architecture contract
+blocked_by: []
+status: done
+branch: "plan-microvm-execution-environments/01-module-contract"
+worktree: ".scratch/task-microvm-01"
+issue: "527"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Establish the nested `environment/microvm` module boundary, keep go-microvm/libkrun out of engine/root default builds, and pin the byte-compatible disabled path. Reconcile the proposed ADR and living architecture/resource inventories where this task owns their structural contract. Do not implement runtime behavior owned by later tasks.
+
+## Acceptance criteria
+
+- AC1.5: With microVM support disabled or no microVM profile selected, existing
+  default/no-fs session snapshots, catalogs, prompts, and behavior remain byte-compatible.
+  - verify: `TestInvariant_microvm_disabled_is_byte_compatible`
+- AC1.6: The normal engine module and root default build have no go-microvm/libkrun
+  import or link dependency; only the nested `environment/microvm` module owns the
+  heavy runtime.
+  - verify: `TestADR_0108_MicroVMDependenciesStayOutOfEngineAndRoot`

.claude/plans/microvm-execution-environments/tasks/02-profile-paths.md

@@ -0,0 +1,37 @@
+---
+id: 02-profile-paths
+title: Environment profiles and source/worktree/guest path roles
+blocked_by: [01-module-contract]
+status: done
+branch: "plan-microvm-execution-environments/02-profile-paths"
+worktree: ".scratch/task-microvm-02"
+issue: "533"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Add the operator-only environment-profile surface and the explicit source checkout, prepared host worktree, guest root, and EnvironmentRef projections. Wire host-side discovery to the correct tier without enabling VM provisioning yet. Project configuration must not control privileged environment policy.
+
+## Acceptance criteria
+
+- AC1.1: Selecting an enabled operator microVM profile creates a session whose source
+  checkout, prepared host worktree, guest `/workspace`, and EnvironmentRef are four
+  explicit values with non-overlapping meanings; the response/UI displays the first
+  three accurately without exposing driver credentials or control endpoints.
+  - verify: `TestMicroVMEnvironments_Scenario1_PathRolesAreExplicit`
+- AC1.2: `environment_profile` selects execution placement independently from the
+  existing `profile`; default and `no-fs` retain their existing tool-surface meaning.
+  - verify: `TestADR_0108_EnvironmentProfileIsIndependentOfToolProfile`
+- AC1.3: Project-tier configuration and model input cannot set or weaken the driver
+  endpoint, image, mounts, resources, egress, seccomp, lifecycle, quotas, signer, or
+  attestation policy; an unknown, disabled, or unavailable alias fails loudly without
+  local fallback.
+  - verify: `TestMicroVMEnvironments_Scenario1_OperatorProfilesAreAuthoritative`
+- AC1.4: Project AGENTS/CLAUDE instructions, rules, commands, skills, and agent
+  definitions are resolved from the prepared session worktree, while user-global
+  settings, soul, memory, skills/agents, MCP configuration, identity, and provider
+  credentials remain host-side.
+  - verify: `TestMicroVMEnvironments_Scenario1_DiscoveryUsesCorrectPathTier`

.claude/plans/microvm-execution-environments/tasks/03-artifact-verification.md

@@ -0,0 +1,30 @@
+---
+id: 03-artifact-verification
+title: Runtime, firmware, and execution-image verification
+blocked_by: [01-module-contract]
+status: done
+branch: "plan-microvm-execution-environments/03-artifact-verification"
+worktree: ".scratch/task-microvm-03"
+issue: "528"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Consume go-microvm's existing runtime/firmware artifacts, add immutable digest resolution, operator trust policy, signature/attestation verification, and atomic cache admission in the nested module. Keep verification offline-testable with fakes; do not require live registries in ordinary tests.
+
+## Acceptance criteria
+
+- AC2.1: A correctly signed and attested runtime, firmware, and execution image resolve
+  to immutable digests, enter the verified cache atomically, and boot a VM whose durable
+  metadata records those digests and the verification-policy revision.
+  - verify: `TestMicroVMEnvironments_Scenario2_VerifiedArtifactsBoot`
+- AC2.2: A mutable/tag-only input, wrong digest, unsigned artifact, wrong signer,
+  missing/wrong attestation, revoked identity, corrupted cache entry, or stale policy
+  fails before VM execution.
+  - verify: `TestMicroVMEnvironments_Scenario2_UnverifiedArtifactsFailClosed`
+- AC2.3: Concurrent sessions requesting the same cold artifact observe one complete
+  verified cache result; none can execute a partial or pre-verification file.
+  - verify: `TestMicroVMEnvironments_Scenario2_ConcurrentCacheAdmissionIsAtomic`

.claude/plans/microvm-execution-environments/tasks/04-control-protocol.md

@@ -0,0 +1,27 @@
+---
+id: 04-control-protocol
+title: Local control socket and guest protocol handshake
+blocked_by: [01-module-contract]
+status: done
+branch: "plan-microvm-execution-environments/04-control-protocol"
+worktree: ".scratch/task-microvm-04"
+issue: "530"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Define the local microvmd control service, Linux/macOS peer authentication, environment owner/ref/generation binding, and guest protocol handshake over go-microvm's vsock-to-UDS primitive. This task establishes framing/capabilities and test fakes, not full Workspace or exec methods.
+
+## Acceptance criteria
+
+- AC2.4: The local control socket authenticates the configured Unix account using the
+  platform peer-credential mechanism; possession or guessing of an environment ID,
+  socket path, or session ID alone authorizes no operation.
+  - verify: `TestMicroVMEnvironments_Scenario2_LocalPeerCredentialsBindOwner`
+- AC2.5: Protocol negotiation rejects a missing required filesystem, streaming,
+  cancellation, generation-binding, or message-bound capability; it never degrades to
+  SSH or host-local tool execution.
+  - verify: `TestMicroVMEnvironments_Scenario2_CapabilityNegotiationFailsClosed`

.claude/plans/microvm-execution-environments/tasks/05-worktree-git.md

@@ -0,0 +1,27 @@
+---
+id: 05-worktree-git
+title: Exact session worktree capture and guest Git reconstruction
+blocked_by: [01-module-contract]
+status: done
+branch: "plan-microvm-execution-environments/05-worktree-git"
+worktree: ".scratch/task-microvm-05"
+issue: "529"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Prepare one hardened session branch/worktree and exact source-state capture. Reuse or extract Brood Box's linked-worktree validation and guest-local Git metadata reconstruction, including the common object-store alternates design. This task prepares/mount-describes paths but leaves generic Workspace RPC to task 07.
+
+## Acceptance criteria
+
+- AC3.1: The prepared worktree contains the source's committed files and the full
+  declared staged/unstaged/untracked content fidelity; a race or unsupported state
+  that prevents exact capture aborts creation instead of silently starting clean.
+  - verify: `TestMicroVMEnvironments_Scenario3_SourceStateCaptureIsExactOrFails`
+- AC3.3: Guest Git operates with reconstructed local metadata and the common object
+  store mounted host-enforced read-only; malicious `.git`/`commondir`, symlink, or
+  escape inputs cannot expose another host path.
+  - verify: `TestMicroVMEnvironments_Scenario3_WorktreeGitMetadataIsConfined`

.claude/plans/microvm-execution-environments/tasks/06-virtiofs-assets.md

@@ -0,0 +1,27 @@
+---
+id: 06-virtiofs-assets
+title: RW worktree and read-only asset virtio-fs mounts
+blocked_by: [03-artifact-verification, 05-worktree-git]
+status: done
+branch: "plan-microvm-execution-environments/06-virtiofs-assets"
+worktree: ".scratch/task-microvm-06"
+issue: "529"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Wire the prepared worktree RW at guest `/workspace`, adopt libkrun's host-enforced read-only virtio-fs API through go-microvm for Git objects and materialized skill assets, and prove bidirectional host/guest visibility. Keep mount inputs explicit and confined.
+
+## Acceptance criteria
+
+- AC3.2: A guest Write/Edit or Bash mutation under `/workspace` is immediately visible
+  in the prepared host worktree, and a host edit to that worktree is visible to the
+  guest.
+  - verify: `TestMicroVMEnvironments_Scenario3_WorktreeIsBidirectionallyVisible`
+- AC3.6: An out-of-repository skill asset reaches the guest only through explicit
+  materialization or a host-enforced read-only mount; Bash cannot discover an arbitrary
+  user home/config directory through that capability.
+  - verify: `TestMicroVMEnvironments_Scenario3_SkillAssetsAreExplicitAndReadOnly`

.claude/plans/microvm-execution-environments/tasks/07-workspace-rpc.md

@@ -0,0 +1,26 @@
+---
+id: 07-workspace-rpc
+title: Guest Workspace RPC and version-aware conformance
+blocked_by: [04-control-protocol, 06-virtiofs-assets]
+status: done
+branch: "plan-microvm-execution-environments/07-workspace-rpc"
+worktree: ".scratch/task-microvm-07"
+issue: "530"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Implement the guest/host Workspace methods and adapter over the authenticated protocol. Preserve all current FileVersion, read-ledger, create-only, conditional-replace, path confinement, Glob/Grep, and bounded-result semantics. Extend the shared filesystem/environment conformance suites rather than inventing parallel rules.
+
+## Acceptance criteria
+
+- AC3.4: Read/Edit/Write/Grep/Glob and Bash observe the same bytes and cwd. A Workspace
+  read followed by Bash mutation is visible to a later Workspace read, and vice versa.
+  - verify: `TestInvariant_environment_workspace_runner_affinity`
+- AC3.5: Workspace ReadVersion/CreateFile/ReplaceFile preserve opaque versions,
+  create-only behavior, and backend-atomic conditional replacement; a concurrent host
+  or guest change yields a model-visible conflict instead of overwriting newer bytes.
+  - verify: `TestMicroVMEnvironments_Scenario3_RemoteWorkspaceConformance`

.claude/plans/microvm-execution-environments/tasks/08-exec-rpc.md

@@ -0,0 +1,30 @@
+---
+id: 08-exec-rpc
+title: Structured guest exec streaming and cancellation
+blocked_by: [04-control-protocol, 06-virtiofs-assets]
+status: done
+branch: "plan-microvm-execution-environments/08-exec-rpc"
+worktree: ".scratch/task-microvm-08"
+issue: "530"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Implement bound CommandRunner/CommandStreamer behavior over the authenticated guest protocol: ordered stdout/stderr, explicit exits, bounds/backpressure, cancellation, and process-group termination. SSH remains bootstrap/debug only and no stale path can run on the host.
+
+## Acceptance criteria
+
+- AC4.1: Exec streams ordered stdout and stderr plus an explicit exit status; a nonzero
+  guest exit is a completed command result, not a transport failure.
+  - verify: `TestMicroVMEnvironments_Scenario4_ExecStreamingPreservesChannelsAndExit`
+- AC4.2: Cancellation or deadline terminates the entire guest process group within a
+  bound, returns partial output already produced, and is distinguishable from a
+  transport fault.
+  - verify: `TestMicroVMEnvironments_Scenario4_CancelKillsGuestProcessGroup`
+- AC4.3: Wrong owner/session/ref/generation, replayed endpoint credentials,
+  malformed/oversized frames, output overflow, and excessive concurrent execs fail
+  closed without reaching another environment or the daemon control plane.
+  - verify: `TestMicroVMEnvironments_Scenario4_GuestProtocolBoundaryIsBounded`

.claude/plans/microvm-execution-environments/tasks/09-network-egress.md

@@ -0,0 +1,29 @@
+---
+id: 09-network-egress
+title: Explicit guest networking and egress enforcement
+blocked_by: [03-artifact-verification, 04-control-protocol]
+status: done
+branch: "plan-microvm-execution-environments/09-network-egress"
+worktree: ".scratch/task-microvm-09"
+issue: "531"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Always configure go-microvm's selected network provider and implement the guest-only deny/allow policy with IPv6 parity or explicit disablement. Surface honest separate guest and host egress status. Ordinary tests use deterministic network fakes; live bypass coverage lands in task 16.
+
+## Acceptance criteria
+
+- AC4.4: VM creation always configures the selected network provider. Failure to start
+  or enforce it aborts creation and never selects implicit or allow-all networking.
+  - verify: `TestADR_0108_ExplicitNetworkProviderNeverDegrades`
+- AC4.5: Deny-all and configured hostname/port/protocol allowlists work from a real
+  guest; IPv6 is either equivalently filtered or disabled and demonstrably unavailable.
+  - verify: `TestMicroVMEnvironments_Scenario4_GuestEgressIsFailClosed`
+- AC4.6: Session/UI status and documentation separately report guest-process egress and
+  host-service egress; guest deny-all never claims to constrain LLM providers,
+  WebFetch, WebSearch, MCP, hooks, OCI pulls, or telemetry.
+  - verify: `TestMicroVMEnvironments_Scenario4_EgressScopeIsHonest`

.claude/plans/microvm-execution-environments/tasks/10-lifecycle-create.md

@@ -0,0 +1,27 @@
+---
+id: 10-lifecycle-create
+title: Transactional environment provisioning and fail-closed resolution
+blocked_by: [02-profile-paths, 03-artifact-verification, 04-control-protocol, 05-worktree-git]
+status: done
+branch: "plan-microvm-execution-environments/10-lifecycle-create"
+worktree: ".scratch/task-microvm-10"
+issue: "532"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Add the internal provisioning/lifecycle seam and creation transaction across worktree, artifact, VM, protocol, environment ref/generation, and session persistence. Extend the existing resolver without widening tool.Environment into lifecycle management. Fail closed for every invalid ref.
+
+## Acceptance criteria
+
+- AC5.1: After a successful creation response, the persisted session, driver registry,
+  prepared worktree, VM, guest endpoint, owner, profile, generation, and artifact
+  identities agree; a failure before persistence rolls back or durably queues every
+  provisional resource for cleanup.
+  - verify: `TestMicroVMEnvironments_Scenario5_CreateTransactionIsAllOrReconciled`
+- AC5.4: A nil resolver, unknown, foreign, stale, destroyed, incompatible, or
+  generation-mismatched ref fails before tool execution with no local fallback.
+  - verify: `TestInvariant_remote_environment_resolution_fails_closed`

.claude/plans/microvm-execution-environments/tasks/11-lifecycle-reconcile.md

@@ -0,0 +1,35 @@
+---
+id: 11-lifecycle-reconcile
+title: Restart reattachment, deletion, and crash reconciliation
+blocked_by: [07-workspace-rpc, 08-exec-rpc, 09-network-egress, 10-lifecycle-create]
+status: done
+branch: "plan-microvm-execution-environments/11-lifecycle-reconcile"
+worktree: ".scratch/task-microvm-11"
+issue: "532"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Complete the session-lifetime environment lifecycle: harness and daemon restart, exact generation reattachment, detach versus delete, retention destruction, durable cleanup/tombstones, and crash/race reconciliation. Update ADR 0027 resource and rehydration inventories for the real resources introduced.
+
+## Acceptance criteria
+
+- AC5.2: Restarting mecated reattaches the exact environment generation and preserves
+  its worktree state without rebuilding the per-session engine unless the independent
+  engine-rehydration rules require it.
+  - verify: `TestMicroVMEnvironments_Scenario5_HarnessRestartReattachesExactGeneration`
+- AC5.3: Restarting microvmd reconstructs or reconciles its durable registry and either
+  reattaches the exact live environment or returns an actionable failed precondition;
+  it never mints an empty replacement for the same ref.
+  - verify: `TestMicroVMEnvironments_Scenario5_DaemonRestartNeverRecreatesEmptyEnvironment`
+- AC5.5: CloseSession detaches process-local handles and leaves the environment
+  reattachable; explicit deletion prevents new runs, destroys the VM/endpoints/children,
+  and removes or preserves the worktree according to the dirty-state policy.
+  - verify: `TestMicroVMEnvironments_Scenario5_DetachAndDeleteAreDistinct`
+- AC5.6: Crashes at every lifecycle transition, PID reuse, stale sockets, disk-full,
+  and two daemons racing one ref converge without deleting another environment or
+  leaking quota indefinitely.
+  - verify: `TestMicroVMEnvironments_Scenario5_ReconcilerConvergesAcrossCrashPoints`

.claude/plans/microvm-execution-environments/tasks/12-multi-session.md

@@ -0,0 +1,34 @@
+---
+id: 12-multi-session
+title: Same-repository concurrency and resource admission
+blocked_by: [11-lifecycle-reconcile]
+status: done
+branch: "plan-microvm-execution-environments/12-multi-session"
+worktree: ".scratch/task-microvm-12"
+issue: "533"
+retries: 0
+last_error: ""
+accumulator: acc/microvm-execution-environments
+---
+
+# Task brief
+
+Prove and harden concurrent local sessions from one repository. Each session gets independent worktree, Git metadata, VM, endpoint, generation, and quotas while sharing only verified immutable caches/object data. Add mecatui projections for each resolved session.
+
+## Acceptance criteria
+
+- AC6.1: Two concurrent session creates from one repository succeed with distinct
+  worktree roots, branches, indexes, environments, endpoints, and writable files; each
+  UI displays its own resolved paths.
+  - verify: `TestMicroVMEnvironments_Scenario6_SameRepoSessionsUseDistinctWorktreesAndVMs`
+- AC6.2: File and Git mutations in session A do not alter session B's working files,
+  index, refs, config, hooks, or guest-local metadata; both can read the shared
+  host-enforced read-only object store.
+  - verify: `TestMicroVMEnvironments_Scenario6_SiblingSessionsCannotMutateEachOther`
+- AC6.3: VM/worktree/image-pull admission observes per-user and deployment limits for
+  booting/active VMs, CPU, RAM, disk/inodes, execs, forks, pulls, and boot rate; a
+  rejection is stable and actionable.
+  - verify: `TestMicroVMEnvironments_Scenario6_ResourceAdmissionIsBounded`
+- AC6.4: Concurrent cache, worktree, endpoint, and cleanup operations do not collide
+  when session IDs or repository names share prefixes or hostile characters.
+  - verify: `TestMicroVMEnvironments_Scenario6_ConcurrentResourceNamesAreOpaqueAndConfined`