Add instance restart policy

[sjmiller609]

Summary

• add restart_policy and restart_status API fields with generated bindings
• add a restart-policy controller for whole-instance restarts with backoff, max attempts, stable reset, and manual-stop suppression
• stack on the healthcheck branch and restart unhealthy running instances through restart policy when policy is on_failure or always
• document the healthcheck/restart-policy interaction

Testing

• go test ./lib/restart-policy ./lib/healthcheck ./lib/providers
• go test -tags containers_image_openpgp ./lib/instances -run 'Test(ValidateCreateRequestHealthCheck|ValidateUpdateInstanceRequestAllowsRestartPolicyOnly|NormalizeRestartPolicyWrapsInvalidRequest|RestartStatusAfterPolicyUpdatePreservesManualStop|RestartStatusAfterPolicyUpdateClearsRetryState)$'
• go test -tags containers_image_openpgp ./cmd/api/api -run 'Test(CreateInstance_MapsHealthCheckPolicy|CreateInstance_MapsRestartPolicy|UpdateInstance_MapsHealthCheckPatch|UpdateInstance_MapsRestartPolicyPatch|UpdateInstance_RejectsInvalidRestartPolicy)$'
• go test -tags containers_image_openpgp ./cmd/api -run 'Test(StartImageRetentionControllerSkipsNilController|StartImageRetentionControllerStartsRunner|ConfigureOCICacheGCSkipsDisabled|ConfigureOCICacheGCRejectsInvalidInterval)$'

Not run: full ./cmd/api/api package; it enters broader lifecycle coverage outside this focused change.

---

Note

Medium Risk
Adds new whole-instance restart supervision that can stop/start instances automatically based on exit/health signals, touching lifecycle state transitions and background controllers; misconfiguration or logic bugs could cause unexpected restart loops or suppressed restarts.

Overview
Adds instance restart supervision via new restart_policy (config) and restart_status (runtime) fields across the OpenAPI spec/generated oapi types and the instances API (CreateInstance, UpdateInstance, GetInstance mapping/validation).

Implements a new lib/restart-policy package plus an instances restart-policy controller that persists retry state, applies backoff/max-attempt/stable-window rules, suppresses restarts after manual StopInstance, and can treat health_check=unhealthy as a restart trigger for on_failure/always.

Wires the controller into cmd/api/main.go, extends health check controller to optionally call HandleHealthCheckUnhealthy, resets restart status on forks/snapshot restores, and adds unit + integration coverage for request mapping, validation, controller behavior, and metrics labels.

^{Reviewed by Cursor Bugbot for commit bb9b4f0. 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: Add instance restart policy

✅ hypeman-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ hypeman-typescript studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ✅

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

✅ hypeman-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@cfdcca8b51e20d5b0be4e99abc96a99b10adfd24

---

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-18 15:18:16 UTC

[firetiger-agent]

Monitoring Plan: Restart Policy

This PR introduces a new restart_policy feature on Hypeman instances along with a background RestartPolicyController goroutine that reconciles instance state every 5 seconds and handles health-check-driven stop/start cycles. The API gains new restart_policy / restart_status fields on Create and Update, and StopInstance has a behavior change: it now writes manual_stop to restart status even for already-stopped instances (previously a no-op).

The primary risks to watch are: stop/start loops if the reconciler misidentifies instances, a regression in StopInstance due to the new metadata write on the already-stopped path, and controller-level panics since this is a new background goroutine with no production history. Blast radius is limited — only instances with an explicit restart_policy set will be automatically restarted; browser sessions and other standard instances are unaffected. The plan checks against the 24h baseline of 0.069–0.096% 5xx error rate and monitors for restart-policy-specific WARN/ERROR logs. Status updates will be posted automatically on this PR as monitoring progresses.

View agent

[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 bb9b4f0. Configure here.}

[cursor]

Restart ignores manual stop set between status write and start

Medium Severity

RestartInstance acquires the instance lock and calls startInstance without checking if manual_stop was set on the restart status. In startInstanceForRestartPolicy, setRestartStatusIfStopped acquires the lock, verifies no manual_stop, writes the attempt status, and releases the lock. Then RestartInstance separately acquires the lock to start. If a user calls StopInstance in the gap between these two lock acquisitions, markRestartManualStopLocked writes manual_stop to metadata, but RestartInstance never checks it—startInstance only validates instance state is Stopped, not the restart status. This TOCTOU race allows one unwanted automatic restart after an explicit manual stop.

Additional Locations (1)

• lib/instances/restart_policy.go#L309-L326

 

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