feat(cua): add delegated-run provider

[coygeek]

Closes #381

Summary

• add the CUA delegated-run provider with trusted local configuration, provider metadata, registration, and documentation
• implement warmup, fresh run, retained reuse, list/status/stop/cleanup, delegated archive sync, timing JSON, and operation locking
• bind every retained sandbox claim to the exact CUA API scope, provider-returned resource name, and creation timestamp
• recheck the creation identity immediately before destructive operations and require list-confirmed absence before reporting deletion success
• isolate the SDK bridge home, pass credentials through explicit environment only, strip provider auth from sandbox commands, and cover the embedded Python bridge with a real subprocess contract test
• make automatic cleanup outlive deletion verification, create forwarded-env files as mode 0600 before writing values, and remove them idempotently

Verification

Exact candidate: 113ce8e36c533a39c6a83ffad7b3211e1da0b1c5

• go vet ./...
• go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
• scripts/check-go-coverage.sh 90.0 (90.1% core coverage)
• go test -race ./internal/providers/cua ./internal/providers/all ./cmd/crabbox -count=1
• go test -race ./internal/cli -run '^(TestApplyEnvRejectsNegativeCUAResources|TestCUARepoConfigCannotReplaceBridgeRuntime|TestCUAConfigRejectsNegativeYAMLValues)$' -count=1
• node scripts/check-provider-matrix.mjs (72 providers)
• scripts/check-docs.sh (52 command docs, 206 Markdown files, generated site)
• node --test scripts/live-cua-smoke.test.js
• current cua==0.1.6 / cua-sandbox==0.1.17 installed in disposable Python 3.13; the built CLI doctor proves Python and SDK readiness and classifies only missing auth
• embedded bridge subprocess proves private env-file creation, value forwarding, command execution, and zero-residue cleanup
• branch AutoReview clean with no actionable findings

The module-wide runner encountered two unrelated controller timing assertions in separate runs; each passed immediately in an isolated rerun. Hosted CI is running on the exact candidate above.

Live proof gate

The current CUA service routes new accounts to an early-access request instead of issuing dashboard access or an API key. The approved test-account request was submitted and confirmed, but no credential or paid resource exists yet. Keep this PR unmerged until access is enabled and CRABBOX_CUA_LIVE=1 scripts/live-cua-smoke.sh passes create, run, reuse, stop, and list-confirmed zero-residue cleanup on this exact head.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 3, 2026, 11:45 PM ET / 03:45 UTC.

Summary
Adds a built-in CUA delegated-run provider with config/env/flags, docs and metadata, a Python SDK bridge, lifecycle operations, archive sync, tests, and an opt-in live-smoke script.

Reproducibility: not applicable. this is a feature PR rather than a report of broken current-main behavior. The relevant verification is live CUA runtime proof on the proposed provider branch.

Review metrics: 2 noteworthy metrics.

• Provider surface: 29 files changed, +4632/-3. This is a full built-in provider addition across config, provider code, docs, tests, and live-smoke coverage.
• Live runtime proof: 0 successful live CUA runs posted. The PR body reports local tests and environment-blocked setup, but no real CUA resource lifecycle proof.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

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

Rank-up moves:

• [P1] Add redacted terminal output, logs, or a recording from a real CUA doctor/run/reuse/status/list/stop cleanup flow on the exact head.
• Redact private details such as API keys, IP addresses, non-public endpoints, and account identifiers before posting proof.
• After adding proof, update the PR body to trigger a fresh ClawSweeper review; if it does not rerun, ask a maintainer to comment @clawsweeper re-review.

Proof guidance:

• [P1] Needs real behavior proof before merge: After-fix real CUA behavior proof is missing; the PR body says account/API-key access is not available yet and asks to keep the PR unmerged until the live smoke passes. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] No successful live CUA create, run, reuse, status, list, stop, or cleanup proof is posted, so the real service lifecycle and zero-residue cleanup path remain unproven.
• [P1] The PR introduces a credentialed local Python bridge and destructive remote sandbox deletion, so sandbox ownership and secret handling need maintainer-visible live proof before merge.
• [P1] The linked provider issue remains open with maintainer-review/product-decision signals, so built-in provider acceptance is still a maintainer decision.

Maintainer options:

1. Require Live CUA Lifecycle Proof (recommended)
   Ask for redacted output from CRABBOX_CUA_LIVE=1 scripts/live-cua-smoke.sh or equivalent doctor/run/reuse/status/list/stop cleanup proof on a real CUA credential before merge.
2. Maintainer-Sponsored Provider Landing
   A maintainer can intentionally accept the remaining live-provider uncertainty after reviewing the guardrails and owning follow-up validation.
3. Pause On Provider Direction
   Keep this PR open if the built-in CUA provider contract should stay tied to the linked product-direction issue before landing.

Next step before merge

• [P1] Needs contributor-provided live CUA proof plus maintainer product/security-boundary acceptance; automation cannot prove the contributor's credentialed CUA environment.

Security
Cleared: No concrete secret leak or supply-chain defect was found in the diff, but the credentialed CUA bridge and deletion path still need live proof before merge.

Review details

Best possible solution:

Merge only after maintainers accept CUA as a built-in delegated-run provider and the PR body includes redacted live CUA lifecycle proof on the exact head.

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

Not applicable; this is a feature PR rather than a report of broken current-main behavior. The relevant verification is live CUA runtime proof on the proposed provider branch.

Is this the best way to solve the issue?

Yes for the implementation direction: the provider-local delegated-run adapter matches the linked issue and repository architecture. It is not merge-ready until live CUA proof and maintainer product acceptance are in place.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: A new delegated-run provider is normal-priority feature work with meaningful but bounded provider impact.
• merge-risk: 🚨 security-boundary: The PR introduces credentialed bridge execution and remote sandbox deletion, so sandbox ownership and secret handling need proof beyond unit tests.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: After-fix real CUA behavior proof is missing; the PR body says account/API-key access is not available yet and asks to keep the PR unmerged until the live smoke passes. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its provider-neutral architecture and credential-handling guidance apply to this provider PR. (AGENTS.md:1, b8abdbc5b874)
• Current main lacks CUA: A current-main source/docs/scripts search for CUA provider terms returned no matches, so the PR is not obsolete on main. (b8abdbc5b874)
• Canonical linked issue: The PR body closes the open request for a first-class CUA delegated-run provider, while the earlier same-title PR is closed as a duplicate of this one. (113ce8e36c53)
• Provider registration shape: The branch registers provider=cua as delegated-run, Linux-only, archive-sync plus cleanup, with no coordinator and no aliases. (internal/providers/cua/provider.go:21, 113ce8e36c53)
• Config trust boundary: Repository YAML can set non-secret CUA fields but cannot set APIURL, and trusted-only bridge runtime fields are guarded by the config loader. (internal/cli/config.go:3842, 113ce8e36c53)
• Bridge secret handling: The bridge builds a narrow subprocess environment, maps only CUA API credentials to the SDK env, isolates HOME/USERPROFILE, and tests that unrelated ambient secrets are not inherited. (internal/providers/cua/bridge.go:343, 113ce8e36c53)

Likely related people:

• coygeek: Prior merged delegated-provider work for OpenSandbox, Superserve, Vercel Sandbox, CodeSandbox, and Agent Sandbox makes this a strong routing candidate beyond only authoring this PR. (role: recent delegated-provider contributor; confidence: high; commits: 684210fdc858, b400623c4dfd, 159da078de76; files: internal/providers/opensandbox, internal/providers/superserve, internal/providers/vercelsandbox)
• steipete: Recent adjacent provider hardening history and the latest CUA identity/cleanup hardening commits make this a likely follow-up owner for lifecycle safety review. (role: provider framework and hardening contributor; confidence: medium; commits: cb83fcf, 1ee493e, e7d3cb217a44; files: internal/cli/delegated_archive_sync.go, internal/providers/codesandbox, internal/providers/opencomputer)

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.