sandbox-v2-lifecycle

name	sandbox-v2-lifecycle
description	Vercel Sandbox v2 lifecycle expertise for vercel-openclaw: named persistent OpenClaw sandbox create/resume/stop/delete, persistent auto-save truth, manual snapshot diagnostics, short-lived worker sandboxes, hot spares, and SDK v2 semantics.

Sandbox v2 Lifecycle

Use this skill for vercel-openclaw sandbox lifecycle, restore, stop, reset, hot-spare, worker sandbox, and debug timing work.

Source Of Truth

Official Vercel Sandbox v2 docs are authoritative. Repo docs or agent guidance that assumes v1/manual snapshot restore is stale unless already updated.

Load references only as needed:

• references/vercel-sandbox-v2-persistent.md — persistent sandbox auto-save/resume/name/session model.
• references/vercel-sandbox-v2-sdk.md — SDK calls, resume flags, delete, command behavior, and network policy notes.
• references/vercel-sandbox-v2-snapshots.md — manual Snapshot API semantics.
• references/vercel-openclaw-lifecycle-map.md — repo-specific invariants and owner files.

Core Model

• Main OpenClaw runtime is one named persistent sandbox.
• Persistent stop() auto-saves filesystem state; no manual snapshot() is needed for normal stop.
• Normal wake resumes by name with Sandbox.get({ name, resume: true }) through the repo controller.
• resume defaults false; use resume:false for observation/status reconciliation.
• Commands may auto-resume stopped persistent sandboxes; stop() and update() do not.
• Manual snapshot() is explicit/debug/checkpoint only. It shuts the sandbox down; do not call stop() afterward.
• delete() permanently removes the persistent sandbox and its sessions/snapshots.
• Worker/debug sandboxes are short-lived; pass persistent:false.

Repo Invariants

• Preserve one persistent OpenClaw sandbox, Redis metadata, channel wake/restore, and short-lived workers.
• Keep SDK access behind src/server/sandbox/controller.ts except documented raw SDK debug routes.
• Distinguish host metadata status, SDK status/session, gateway readiness, persistent auto-saved state, and manual Snapshot APIs.
• Do not use manual snapshotId as the normal restore gate.
• Preserve resume:false during snapshotting/stopped observation.
• Keep lifecycle locks and fail-closed firewall behavior.

Workflow

1. Read lat.md/sandbox-lifecycle.md, docs/lifecycle-and-restore.md, and relevant references from this skill.
2. Inspect src/server/sandbox/lifecycle.ts, controller.ts, restore-attestation.ts, hot-spare.ts, and worker sandbox code.
3. Classify whether the change affects persistent resume, manual snapshots, reset/delete, workers, or debug diagnostics.
4. Patch the smallest surface that fixes the v2 truth model.
5. Add or adjust targeted tests before broad verification.

Verification

Run the narrowest covering test first, then broader gates for lifecycle changes:

node --import tsx --test src/server/sandbox/restore-attestation.test.ts
pnpm run test:lifecycle
pnpm run typecheck
pnpm run lint
lat check

When touching launch verification or preflight, also run pnpm run verify:observability-pass.