Add fixed idempotent lease-ID support to the Agent Sandbox provider

[jimmybrancaccio]

Summary

Add fixed idempotent lease-ID support to the agent-sandbox provider so it can satisfy OpenClaw’s cloud-worker lifecycle contract.

Problem

OpenClaw cloud workers provision Crabbox leases using a caller-supplied fixed cbx_... lease ID. Crabbox 0.48.0’s Agent Sandbox provider rejects this before allocation:

provider=agent-sandbox does not support fixed idempotent lease IDs

The same Agent Sandbox configuration otherwise works. A direct disposable crabbox run successfully created a SandboxClaim, ran Node.js on ARM64, and deleted the claim.

This prevents Agent Sandbox from being used as an OpenClaw cloud-worker backend.

Environment

• Crabbox: 0.48.0
• Agent Sandbox controller: v1.0.0
• Kubernetes: K3s v1.36.3+k3s1
• Nodes: Linux/ARM64
• Provider kind: delegated-run
• Provider capabilities: archive-sync, cleanup, run-session, managed-sandbox

Current Crabbox main at d3d244899f79d5fcecbb5073fa482c9f1e7230df also lacks an Agent Sandbox implementation of the fixed-ID backend contract.

Reproduction

1. Configure a working Agent Sandbox context, namespace, and SandboxWarmPool.
2. Confirm an ordinary run succeeds:

crabbox run \
  --provider agent-sandbox \
  --agent-sandbox-context default \
  --agent-sandbox-namespace openclaw-sandboxes-pilot \
  --agent-sandbox-warm-pool openclaw-arm64-cold \
  --no-sync \
  -- node --version

3. Request a caller-supplied lease ID through OpenClaw cloud-worker dispatch, or directly through the corresponding Crabbox fixed-ID path.
4. Observe exit code 2:

provider=agent-sandbox does not support fixed idempotent lease IDs

No SandboxClaim, Sandbox, or pod is created.

Requested behavior

Implement Crabbox’s fixed idempotent lease-ID contract for agent-sandbox, including:

• Deterministic, replay-safe acquisition for a caller-supplied cbx_... ID
• Durable create intent before Kubernetes mutation
• Exact binding to context, namespace, warm pool, claim UID, and ownership metadata
• Safe replay after an ambiguous create result
• Idempotent stop with confirmed deletion or authoritative absence
• A terminal receipt or tombstone sufficient for repeated cleanup
• Provider capability metadata that allows callers to detect fixed-ID support without attempting allocation
• Tests covering duplicate acquisition, restart recovery, ambiguous create, ownership mismatch, deletion, and already-absent cleanup

The implementation should continue to fail closed when Kubernetes identity or ownership cannot be established.

Related work

• Add Kubernetes Agent Sandbox provider #321 introduced the Agent Sandbox provider.
• feat: add agent-sandbox provider #322 implemented its initial delegated-run lifecycle.
• feat(providers): expose agent-sandbox sessions #627 exposed Agent Sandbox sessions.
• refactor(providers): share lease operation locking #1416 consolidated provider operation locking but did not add fixed-ID acquisition.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 2, 2026, 2:35 PM ET / 18:35 UTC.

Summary
Current main still rejects fixed lease IDs before Agent Sandbox provisioning, and the provider only allocates generated lease IDs. This is a real, aligned provider-capability request rather than a regression, but its durable lifecycle contract needs maintainer sponsorship before implementation.

Reproducibility: yes. from source: a valid caller-supplied lease ID reaches the CLI capability guard, while Agent Sandbox has no such capability and its creation path generates a new ID.

Maintainer decision needed

Question	Recommendation
Should Crabbox expand the optional fixed lease-ID contract to the Agent Sandbox delegated-run provider for external orchestrator use?	Sponsor adapter support: Implement fixed-ID acquisition with durable intent, exact Kubernetes identity checks, replay recovery, terminal cleanup, and focused tests.

Why: The documented contract makes fixed IDs optional, and this request would establish durable cross-retry lifecycle semantics rather than a small CLI change.

Next step
The source-proven gap is real, but accepting an optional durable provider contract requires maintainer product direction before implementation.

Review details

Best possible solution:

Implement the capability as an adapter-owned transaction that durably records the requested identity before Kubernetes mutation and validates exact replay and cleanup behavior through the existing ownership chain.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: a valid caller-supplied lease ID reaches the CLI capability guard, while Agent Sandbox has no such capability and its creation path generates a new ID.

Is this the best way to solve the issue?

Unclear: the direction fits the provider lifecycle vision, but fixed IDs are optional and the adapter-specific durable transaction needs maintainer approval.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Merely advertising capability would allow a caller ID through while the delegated warmup path does not yet carry it, risking a generated claim rather than replay-safe acquisition.
• Fixed-ID support must preserve the existing scope, Kubernetes UID, recovery-nonce, and deletion invariants across retries and terminal cleanup.

Codex review notes: model internal, reasoning high; reviewed against 9ab5b3ba7e05.

Label changes

Label changes:

• add P2: This is a bounded provider capability gap affecting a specific orchestration workflow rather than general runtime availability.
• add impact:other: The issue blocks an idempotent remote-execution integration outside the more specific owned impact categories.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded provider capability gap affecting a specific orchestration workflow rather than general runtime availability.
• impact:other: The issue blocks an idempotent remote-execution integration outside the more specific owned impact categories.

Evidence reviewed

What I checked:

• Current fixed-ID rejection: The CLI requires a backend to implement the fixed-ID capability and otherwise returns the reported rejection before provisioning. (internal/cli/run.go:86, 9ab5b3ba7e05)
• Agent Sandbox generates its own ID: Agent Sandbox claim creation unconditionally calls newLeaseID, then derives the claim name and ownership labels from that generated value. (internal/providers/agentsandbox/backend.go:670, 9ab5b3ba7e05)
• Existing contract is optional: The provider-backend contract documents requested fixed IDs as optional and identifies only selected adapters as implementing them; Agent Sandbox does not declare the capability in its provider surface. (docs/provider-backends.md:183, 9ab5b3ba7e05)
• Release check: The v0.48.0 release source likewise has no Agent Sandbox fixed-ID capability and creates a fresh lease ID, so the reported v0.48.0 behavior remains current-main behavior. (internal/providers/agentsandbox/provider.go:22, 26b735abbaf6)
• Feature history: The original provider landed in the merged Agent Sandbox provider change; later history includes session and lifecycle maintenance but no fixed-ID addition. (internal/providers/agentsandbox/backend.go:658, 4003a3000972)

Likely related people:

• coygeek: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.