Add Cloudflare Sandbox provider

[coygeek]

Closes #368

Summary

• add a new cloudflare-sandbox delegated-run provider backed by the Cloudflare Sandbox bridge contract
• support bridge URL/workdir/timeout/forget-missing config, read-only doctor, warmup, run/sync, list/status/stop/cleanup, and provider registry/docs integration
• harden bridge lifecycle behavior with typed 404 handling, operation locks, /workspace workdir confinement, secret stripping, remote metadata validation, and redacted repository metadata

Verification

• go test ./internal/providers/cloudflaresandbox ./internal/providers/all ./internal/cli
• node scripts/check-provider-matrix.mjs
• go vet ./...
• scripts/check-docs.sh
• git diff --check
• go test ./...

Notes

• No live Cloudflare Sandbox writes were run; fake bridge tests are the deterministic proof surface for this plan set.
• Worker-side code did not change; public CI still runs the Worker gate before merge.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 23, 2026, 8:45 PM ET / 00:45 UTC.

Summary
The PR adds a new Cloudflare Sandbox delegated-run provider with config, bridge client, lifecycle/sync/run support, registration, tests, and provider documentation.

Reproducibility: yes. from source inspection: the PR client request structs and routes differ from the Cloudflare Sandbox SDK bridge source and worker README, so a real bridge would reject or misparse core operations.

Review metrics: 1 noteworthy metric.

• Provider surface added: 1 provider, 30 files, +3542/-27. This is a large first-party remote execution surface, so live contract mismatches and proof gaps are material before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #368
Summary: This PR is the implementation candidate for the open Cloudflare Sandbox provider issue.

Members:

• canonical: Add a Cloudflare Sandbox delegated-run provider backed by the official SDK bridge #368 - The PR body says it closes the open issue requesting this provider.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🧂 unranked krab
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Fix the bridge route and JSON contract against the official SDK bridge source.
• [P1] Add redacted live output for doctor, run, sync, keep/reuse, status, stop, and cleanup against a real bridge.

Proof guidance:

• [P1] Needs real behavior proof before merge: Only fake bridge tests are provided; the contributor should add redacted terminal/live output from a real bridge and update the PR body to trigger re-review.

Risk before merge

• [P1] Core Cloudflare Sandbox operations would fail against the official bridge until the route and JSON contract is corrected.
• [P1] The linked issue still needs maintainer product/security review because this adds a token-bearing remote execution provider and possibly requires a Crabbox-specific bridge extension for inventory/list behavior.
• [P1] The PR lacks real behavior proof from a live Cloudflare Sandbox bridge; fake bridge tests do not prove the provider works in a real setup.

Maintainer options:

1. Fix the bridge contract first (recommended)
   Update the client and tests to use the official exec, file, hydrate, running, and lifecycle routes before this provider lands.
2. Pause for bridge-extension direction
   If Crabbox needs inventory or metadata routes that the official bridge does not expose, pause until maintainers approve the extension contract and compatibility story.

Next step before merge

• [P1] Human handling is needed because the branch needs contributor live proof and maintainer product/security direction after the blocking bridge-contract defects are fixed.

Security
Cleared: No malicious or supply-chain issue was found, but the new token-bearing remote execution provider still needs maintainer security review and live proof before merge.

Review findings

• [P1] Match the bridge exec wire format — internal/providers/cloudflaresandbox/client.go:66-76
• [P1] Use the documented file upload route — internal/providers/cloudflaresandbox/client.go:341-343
• [P1] Remove unsupported inventory calls — internal/providers/cloudflaresandbox/client.go:142-166

Review details

Best possible solution:

Align the provider with the official Cloudflare Sandbox bridge or explicitly define a maintainer-approved Crabbox bridge extension, then require redacted live bridge proof before merge.

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

Yes from source inspection: the PR client request structs and routes differ from the Cloudflare Sandbox SDK bridge source and worker README, so a real bridge would reject or misparse core operations.

Is this the best way to solve the issue?

No; the separated delegated-run provider shape is plausible, but the implementation must first match the official bridge contract or intentionally document and test a maintainer-approved Crabbox bridge extension.

Full review comments:

• [P1] Match the bridge exec wire format — internal/providers/cloudflaresandbox/client.go:66-76
  The official Cloudflare Sandbox bridge accepts exec bodies as argv, timeout_ms, and cwd, and its SSE completion event uses exit_code. This client sends command, workingDir, env, and timeoutSecs and requires exitCode, so real bridge exec calls will either 400 before running or fail to parse completion even though the fake bridge tests pass.
  Confidence: 0.93
• [P1] Use the documented file upload route — internal/providers/cloudflaresandbox/client.go:341-343
  The bridge exposes raw file writes as PUT /v1/sandbox/:id/file/* and hydrate as POST /v1/sandbox/:id/hydrate; there is no documented POST /files/write?path=...&encoding=raw endpoint. Archive sync therefore cannot upload to the official bridge and crabbox run will fail before executing commands.
  Confidence: 0.91
• [P1] Remove unsupported inventory calls — internal/providers/cloudflaresandbox/client.go:142-166
  The current bridge only creates, deletes, runs, checks /running, and operates on a specific sandbox ID; it does not document GET /v1/sandbox, GET /v1/sandbox/:id, or GET /v1/sandbox/running inventory endpoints. Using those routes for list/status/cleanup makes those commands fail against the official bridge unless the PR also defines a Crabbox-specific bridge extension.
  Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 1468e704228e.

Label changes

Label changes:

• add P2: This is a normal-priority provider improvement with blocking correctness issues but no current-user regression.
• add merge-risk: 🚨 other: Merging would add a documented provider whose core live bridge operations fail against the current official bridge contract.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Only fake bridge tests are provided; the contributor should add redacted terminal/live output from a real bridge and update the PR body to trigger re-review.

Label justifications:

• P2: This is a normal-priority provider improvement with blocking correctness issues but no current-user regression.
• merge-risk: 🚨 other: Merging would add a documented provider whose core live bridge operations fail against the current official bridge contract.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Only fake bridge tests are provided; the contributor should add redacted terminal/live output from a real bridge and update the PR body to trigger re-review.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its provider-neutral boundary and secret-handling guidance are relevant to this provider review. (AGENTS.md:11, 1468e704228e)
• Current main lacks this provider: The current provider registry imports Cloudflare Containers and Cloudflare Dynamic Workers, but not a cloudflaresandbox provider package, so the PR is still meaningful work rather than obsolete cleanup. (internal/providers/all/all.go:14, 1468e704228e)
• Product direction is conditional: Current provider-selection docs say Cloudflare Sandbox SDK should stay separate until the runtime contract maps cleanly to Crabbox, which makes the bridge contract a merge gate. (docs/features/provider-selection.md:110, 1468e704228e)
• Official bridge exec shape differs: The Cloudflare Sandbox bridge types define exec requests as argv, timeout_ms, and cwd, while this PR sends command, workingDir, env, and timeoutSecs. (internal/providers/cloudflaresandbox/client.go:66, 8964edc610d0)
• Official bridge routes differ: Cloudflare's bridge README/source document POST /v1/sandbox/:id/exec, PUT /v1/sandbox/:id/file/*, GET /v1/sandbox/:id/running, DELETE /v1/sandbox/:id, and OpenAPI routes, but not the list/get/files-write routes used by the PR client. (internal/providers/cloudflaresandbox/client.go:142, 8964edc610d0)
• Real proof is absent: The PR body says no live Cloudflare Sandbox writes were run and that fake bridge tests are the deterministic proof surface. (8964edc610d0)

Likely related people:

• coygeek: Authored merged Vercel Sandbox and Cloudflare Dynamic Workers provider work, which is the closest current-main pattern for this PR's delegated bridge shape. (role: adjacent SDK-bridge provider author; confidence: high; commits: 159da078de76, fedb3ce4e841, c495ddec7e2e; files: internal/providers/vercelsandbox/backend.go, internal/providers/vercelsandbox/client.go, internal/providers/cloudflaredynamicworkers/backend.go)
• steipete: Merged and hardened adjacent Vercel Sandbox, Cloudflare Dynamic Workers, and Cloudflare Containers provider surfaces after initial implementation. (role: recent provider hardening and merger; confidence: high; commits: 307ccd6e1259, 001f90306c4a, dde7fb7fba27; files: internal/providers/vercelsandbox/backend.go, internal/providers/cloudflaredynamicworkers/backend.go, internal/providers/cloudflare/backend.go)
• altaywtf: Authored the merged Cloudflare Containers provider history, including the earlier naming transition away from Cloudflare sandbox wording. (role: introduced adjacent Cloudflare provider; confidence: high; commits: f672eb4901ee, d1ae655ca582, e93300082d5e; files: internal/providers/cloudflare/provider.go, internal/providers/cloudflare/backend.go, internal/providers/cloudflare/client.go)
• zozo123: Authored the merged Cloudflare run-session support update, which is adjacent lifecycle/session behavior for delegated Cloudflare providers. (role: recent adjacent Cloudflare contributor; confidence: medium; commits: 55779d4b6c5d, e2147da1fad4, 309cc434d3d8; files: internal/providers/cloudflare/provider.go, internal/providers/cloudflare/backend.go, docs/providers/cloudflare.md)
• vincentkoc: Recent current-main blame/log on provider session and conformance areas points to provider metadata/timing work that overlaps the registry and generated matrix touched by this PR. (role: recent provider-surface contributor; confidence: medium; commits: d8c40f7b596b; files: internal/providers/vercelsandbox/provider.go, internal/providers/cloudflare/provider.go, internal/providers/all/all_test.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.