Introduce "template" as a VM state

[sjmiller609]

Summary

Models "Template" as a state in the instance state machine. A Standby instance is auto-promoted to Template the first time it's forked from a snapshot. ForkCount is bumped on each subsequent fork and decremented when a fork is deleted. Templates cannot wake while ForkCount > 0; un-promote (Template -> Standby) and delete (Template -> Stopped) are both refused until forks drain. RestoreInstance on a Template with zero forks transparently un-promotes and then restores.

Three new fields live on StoredMetadata: IsTemplate, ForkCount, ForkOfTemplate. A fourth field HotPagesPath is reserved for the future UFFD prefetch path and is cleared on un-promote.

State derivation in query.go returns StateTemplate when there's a snapshot, no socket, and IsTemplate=true. Template is a derived state alongside Standby/Stopped — no extra files on disk, no separate index.

The running-fork flow (from_running=true) skips promotion: it restores the source back to Running afterward, and a template can't wake.

Fork delete decrements the parent's ForkCount under the parent's lock after the fork's data is gone. Worst case on partial failure is drift (parent count higher than reality), fixed by a future reconciliation pass.

Test plan

• go build ./... clean
• Existing instance tests pass (go test ./lib/instances/...)
• New unit tests in templates_test.go cover: deriveState returns Template, Restore refused on Template with forks, Restore demotes Template with zero forks, Delete refused on Template with forks, Delete-fork decrements parent ForkCount
• State-transition tests cover the new Standby<->Template and Template->Stopped edges
• End-to-end fork-from-Template flow (not exercised in unit tests; needs real snapshot/VMM)

---

Note

Medium Risk
Adds a new instance lifecycle state and new API endpoints that change fork/restore/delete behavior; mistakes could block restores/deletes or mis-handle template fork tracking.

Overview
Introduces a new Template instance state (derived from a standby snapshot) and extends the state machine to allow Standby -> Template and Template -> Standby/Stopped while disallowing waking templates directly.

Adds lifecycle operations to explicitly manage templates: new API endpoints POST /instances/{id}/promote-template and POST /instances/{id}/demote-template, plus instances.Manager methods PromoteToTemplate/DemoteTemplate with state/"live fork" guards.

Updates forking semantics to allow forks from templates (treating template/standby as snapshot-based), record parent linkage via ForkOfTemplate, and ensure forks do not inherit template-only metadata; deletion and demotion now refuse when a template has live forks, enforced via a new countTemplateForks scan and covered by new templates_test.go.

^{Reviewed by Cursor Bugbot for commit 0d0ab12. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

✱ Stainless preview builds for hypeman

This PR will update the hypeman SDKs with the following commit message.

feat: Model template as an instance state instead of a separate registry

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/98a12ef59b07e556650e6d9fabaaf7cac04acaea/dist.tar.gz

✅ hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@7e4dccadb0ce4cf062288caf68a3ecb8c5625520

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-13 19:45:15 UTC

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR modifies instance state machine logic in packages/api/lib/instances, not the API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal) specified in the filter.

To monitor this PR anyway, reply with @firetiger monitor this.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0d0ab12. Configure here.}