Checkpoint a Managed Agents computer on park and roll it back on restart

[gane5hvarma]

Summary

• On used-turn teardown, qm calls POST /v2/agents/sessions/{id}/checkpoints (CreateCheckpoint) before the portable home tar and pause. The call is throttled by DO_AGENTS_SNAPSHOT_INTERVAL_SEC (default five minutes). There is no timer; a turn that never opens the computer does not capture.
• A successful capture stores the checkpoint id and deletes the previous one, so only the newest remains. A failed delete is remembered and retried on a later teardown. Checkpoint throttling is independent of the home tar, so a failed tar retries without taking another checkpoint.
• A capture failure is recorded on recovery.error and the session still pauses. The portable tar remains the recovery path when the session itself is gone, because a checkpoint is bound to its session.
• sandbox action=restart calls POST /v2/agents/sessions/{id}/checkpoints/{checkpoint_id}/rollback with the stored checkpoint. The session id stays, the response's sandbox id replaces the stored one, and any open port-forward is closed. Restart does not take a new checkpoint first. A paused session is rolled back directly. Restart with no stored checkpoint fails and leaves the session as it is.

Stacked on #2128.

Test plan

• node --experimental-test-module-mocks --test test/managed-agents-sandbox.test.ts test/managed-agents-client.test.ts (58 passed)
• Live smoke (scripts/managed-agents-sandbox-smoke.ts) against a real Managed Agents token, confirming teardown returns a READY checkpoint before pause and doctl harness-runtime rollback rewinds that session onto a new sandbox

[Copilot]

🟡 Changes recommended

Checkpoint throttling breaks after snapshot failures, and failed checkpoint deletions cannot be retried.

2 open findings

• Persist failed checkpoint deletions for later retries · New
• Avoid recapturing checkpoints after snapshot upload failure · New

What changed in this PR

Adds Managed Agents checkpoints during teardown while retaining portable home snapshots as the cross-session recovery path.

Changes:

• Adds checkpoint creation, validation, deletion, and durable status metadata.
• Captures checkpoints before home snapshots and pause.
• Expands fake services, tests, and preservation documentation.

File	Description
src/​sandbox/​managed-agents-client.ts	Adds checkpoint REST operations.
src/​sandbox/​managed-agents-sandbox.ts	Integrates checkpoint lifecycle into teardown and status.
test/​managed-agents-client.test.ts	Tests checkpoint API behavior.
test/​managed-agents-sandbox.test.ts	Tests teardown capture, failure, throttling, and replacement.
test/​support/​fake-managed-agents.ts	Adds checkpoint support to the sandbox fake.
test/​support/​fake-managed-agents-service.ts	Implements fake checkpoint HTTP routes.
docs/​sandbox-preservation.md	Documents checkpoint-based preservation.
adrs/​managed-agents-sandbox-backend.md	Updates the backend architecture flow.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.