Add waitForState endpoint for blocking state transitions

[hiroTamada]

Summary

Adds GET /instances/{id}/wait?state=Running&timeout=30s endpoint that blocks until an instance reaches the target state, avoiding client-side polling.

Behavior:

• Reuses existing GetInstance state derivation logic, polling internally every 1s
• Default timeout 60s, max 5m, configurable via timeout query parameter
• Returns immediately if already in target state
• Returns early on terminal states (Stopped when not the target) or error states (Unknown)
• Handles client disconnects via context cancellation
• Instance deletion during wait returns 404

Response shape:

{
  "state": "Running",
  "state_error": null,
  "timed_out": false
}

Changes:

• openapi.yaml — new WaitForStateResponse schema + /instances/{id}/wait endpoint
• lib/oapi/oapi.go — regenerated from spec
• cmd/api/api/instances.go — handler implementation

Test plan

• Verify endpoint returns immediately when instance is already in target state
• Verify timeout behavior (returns timed_out: true with current state)
• Verify early return on terminal state (Stopped) and error state (Unknown)
• Verify 404 when instance is deleted during wait
• Verify client disconnect is handled gracefully
• Verify invalid state/timeout params return 400
• Integration test with a real instance lifecycle (create → wait for Running)

---

Note

Medium Risk
Adds a new blocking API endpoint and introduces state-change subscriptions into the instances.Manager interface, which affects all manager implementations and state transition paths. Risk is mainly around missed notifications, channel lifecycle on delete, and potential regressions in lifecycle methods now emitting events.

Overview
Adds a new GET /instances/{id}/wait endpoint that blocks until an instance reaches a requested state (with validated target states, configurable timeout capped at 5m, and timed_out/state_error in the response).

Implements instances.WaitForState, backed by a new per-instance subscription mechanism (Manager.Subscribe, subscribe.go) with a 5s polling fallback, and wires lifecycle operations (StartInstance, StopInstance, StandbyInstance, Restore*) to broadcast state changes and close subscribers on delete.

Updates OpenAPI/client codegen (openapi.yaml, lib/oapi/oapi.go), scopes mapping, Stainless config, and adds unit/integration tests covering immediate return, invalid params, deletion during wait, context cancellation, and subscription behavior.

^{Written by Cursor Bugbot for commit b0d3836. This will update automatically on new commits. Configure here.}

[github-actions]

✱ Stainless preview builds

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

feat: Add waitForState endpoint for blocking state transitions

✅ hypeman-openapi studio · code

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

✅ 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@d6cea176033845f13c0dcbe79c0a8150c5a87d94

⚠️ hypeman-typescript studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

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

---

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-03-27 17:35:08 UTC

[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.}