Sandbox Lifecycle Debug

Sandbox Lifecycle Debug

Use this skill when the sandbox state machine is the primary suspect.

For Sandbox v2 truth-model work, also load sandbox-v2-lifecycle. Official Vercel Sandbox v2 docs override older repo guidance that treats manual snapshots as the normal restore source.

Start Here

Read lat.md/sandbox-lifecycle.md sections Status State Machine, Triggers -- What Causes State Transitions, and the specific trigger involved. Run lat locate "Sandbox Lifecycle" or lat search "sandbox lifecycle <symptom>" when unsure.

Collect before edits:

• GET /api/status and any UI state that triggered the action.
• GET /api/admin/sandbox-diag.
• GET /api/admin/logs filtered for sandbox., gateway., watchdog., proxy..
• Local git rev-parse HEAD, remote git ls-remote origin main, and live deployment proof.

Split The State

Report these separately:

• metadata status in SingleMeta.status
• Vercel Sandbox SDK status
• gateway readiness on port 3000
• persistent auto-saved state availability
• manual snapshot/checkpoint availability when relevant
• lifecycle lock and start lock state when visible
• UI polling status

Do not use running as shorthand for gateway-ready or user-ready.

Common Paths

• Admin ensure: /api/admin/ensure -> ensureSandboxRunning() / ensureSandboxReady().
• Gateway request: auth -> ensureSandboxRunning() -> token refresh -> touchRunningSandbox() -> proxy.
• Stop/auto-save: stopSandbox() -> cleanup -> cron persistence -> sandbox.stop({ blocking: false }) -> snapshotting host metadata while v2 persists state.
• Status polling: GET /api/status -> stale running or snapshotting reconciliation.
• Reset: resetSandbox() destroys active sandbox and snapshots, clears cron and token metadata.

Sandbox v2 Rules

• Main OpenClaw sandbox is one named persistent sandbox.
• Normal resume uses the persistent name and auto-saved state, not manual snapshotId.
• Observation of stopped/snapshotting state must use resume:false.
• Manual snapshot() is explicit/debug/checkpoint only and shuts the sandbox down.
• Worker/debug sandboxes are short-lived and must use persistent:false.

Fix Boundaries

• Primary: src/server/sandbox/lifecycle.ts, src/server/sandbox/controller.ts.
• Routes: src/app/api/admin/{ensure,stop,snapshot,reset,status}/** and src/app/api/status/route.ts.
• Tests: lifecycle and harness tests under src/server/sandbox/**.test.ts and src/test-utils/harness.
• Docs: lat.md/sandbox-lifecycle.md, docs/lifecycle-and-restore.md.

Verification

Use the narrowest command that covers the path, then run the repo verifier when the change has broad lifecycle impact:

node scripts/verify.mjs --steps=test,typecheck
lat check

For live lifecycle incidents, include before/after /api/status, /api/admin/sandbox-diag, and relevant log events.