stacklok / stacklok/mecatl

Persist, reattach, and reconcile session microVM lifecycles

Open
#532 0 comments 0 reactions 1 assignee View on GitHub

@JAORMX is already working on this.

Since Aug 14, 2026.

enhancement
Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

Parent: #526

Outcome

A session owns one durable microVM environment generation that can be detached and reattached across harness restarts, and can be deleted/reconciled without leaks or accidental empty-environment recreation.

Scope

  • Add an internal provisioning/lifecycle manager without widening tool.Environment into a service locator.
  • Define and persist the environment state machine from reservation through worktree preparation, artifact verification, VM readiness, session persistence, attachment, detachment, stop, deletion, and tombstone.
  • Persist owner UID/optional principal, session ID, EnvironmentRef, generation, path mapping, resolved profile, artifact digests, runtime process identity, endpoint identity, and cleanup state.
  • Make creation idempotent and rollback provisional resources if session persistence fails.
  • Resolve the exact persisted ref/generation at run entry; never recreate an empty VM or fall back to local.
  • Define detach versus suspend/stop versus permanent delete.
  • Add durable cleanup/reconciliation for host or daemon crashes, PID reuse, stale sockets, stale worktrees, child environments, and partial deletion.
  • Apply per-user/deployment quotas for booting/active VMs, CPU, RAM, disk/inodes, execs, forks, image pulls, and boot rate.

Acceptance

  • Restarting mecated or microvmd reattaches the exact valid environment generation or fails with an actionable precondition error.
  • Unknown, foreign, stale, destroyed, incompatible, or mismatched refs never create replacement state.
  • CloseSession detaches and leaves the session reattachable; explicit deletion eventually removes VM resources and session worktree according to preservation rules.
  • Crashes at every lifecycle transition converge without leaked VMs, sockets, worktrees, quotas, or deletion of another environment.
  • Two daemon processes racing the same ref cannot both own it.
  • Cleanup paths are canonical-base-confined and never derive recursive-delete authority from model/caller text.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.