feat: add runtime adapter lifecycle

[steipete-oai]

Summary

• add a generic runtime-adapter lifecycle for creating, reconciling, attaching to, and deleting managed workspaces
• persist replay, reconciliation, terminal-finalization, cleanup, and credential-policy state in D1
• expose capability-aware terminal and transient desktop connections without durably storing bearer URLs
• preserve migrated live Sandbox sessions whose durable lease predates agent-token storage

Validation

• npx --yes pnpm@10.23.0 run check
• npx --yes pnpm@10.23.0 run test (130 tests)
• go test ./...
• go vet ./...
• gofmt clean for cmd/
• fresh replay of all 24 SQLite migrations; PRAGMA integrity_check returned ok
• focused autoreview of the remediation: no accepted/actionable findings
• complete branch autoreview against origin/main: no accepted/actionable findings

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 13, 2026, 1:29 AM ET / 05:29 UTC.

Summary
The PR adds a versioned runtime adapter lifecycle for managed workspaces, D1-backed replay/reconciliation/cleanup state, and capability-aware terminal and desktop connection handling.

Reproducibility: not applicable. this is a feature PR rather than a bug report with a current-main reproduction path. I did not run tests or a local runtime because the review is read-only and must not generate artifacts.

Review metrics: 2 noteworthy metrics.

• Diff size: 50 files changed, 13,186 added, 1,416 removed. The PR spans worker runtime logic, persistence, CLI, UI, docs, and tests, so broad maintainer review is needed.
• Persistence migrations: 4 added. New D1 migrations affect upgrade behavior for existing interactive sessions and sandbox credentials.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
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, screenshots, or a recording showing the real adapter lifecycle after the fix; redact private IPs, API keys, phone numbers, private endpoints, and other sensitive details.
• Include upgrade evidence for the new D1 migrations and existing interactive sessions; updating the PR body should trigger a fresh review, or a maintainer can comment @clawsweeper re-review if it does not.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists automated validation only; external PRs need redacted real behavior proof from the changed runtime path before merge. 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 after-fix real behavior proof is attached; the PR body lists tests and checks, but not a live adapter create, attach, desktop, stop, or reconcile run.
• [P1] Four migrations add and backfill lifecycle, credential-policy, and standalone sandbox state, so existing interactive sessions need upgrade proof before merge.
• [P1] The PR changes runtime defaults, CLI behavior, and strict OAuth redirect handling, so deployments using implicit crabbox CLI defaults or loosely configured GITHUB_REDIRECT_URI may need operator action.

Maintainer options:

1. Require runtime proof first (recommended)
   Ask for redacted after-fix proof from a real setup covering adapter create, terminal or desktop access, stop/reconcile, and migration replay before merge.
2. Accept staged rollout risk
   Maintainers may merge after explicitly accepting the runtime default, OAuth, and migration risks and planning a staged deployment check.
3. Pause for API direction
   If the runtime adapter API or default-runtime direction is not settled, pause or close this PR until the contract is approved.

Next step before merge

• [P1] Missing external real behavior proof and compatibility-sensitive runtime, D1, and OAuth changes need human maintainer review rather than an automated repair PR.

Security
Cleared: No concrete security or supply-chain regression was found in the reviewed diff; adapter calls and transient desktop URLs are handled defensively.

Review details

Best possible solution:

Land this after maintainers accept the new runtime adapter contract/defaults and the PR includes redacted real runtime plus upgrade proof.

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

Not applicable; this is a feature PR rather than a bug report with a current-main reproduction path. I did not run tests or a local runtime because the review is read-only and must not generate artifacts.

Is this the best way to solve the issue?

Unclear until maintainer review accepts the runtime adapter API and upgrade behavior. The implementation is not duplicated on main and no discrete code defect was confirmed, but proof and compatibility review are still required.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: This is a substantial feature PR with bounded but important runtime and persistence impact.
• add merge-risk: 🚨 compatibility: The PR changes runtime defaults, CLI behavior, OAuth redirect validation, and deployment configuration expectations.
• add merge-risk: 🚨 session-state: The PR adds and backfills D1 lifecycle and credential cleanup state for persisted interactive sessions.
• add merge-risk: 🚨 auth-provider: The PR changes GitHub OAuth callback validation and GitHub credential handling paths that existing deployments rely on.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists automated validation only; external PRs need redacted real behavior proof from the changed runtime path before merge. 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.
• remove rating: 🌊 off-meta tidepool: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

• P2: This is a substantial feature PR with bounded but important runtime and persistence impact.
• merge-risk: 🚨 compatibility: The PR changes runtime defaults, CLI behavior, OAuth redirect validation, and deployment configuration expectations.
• merge-risk: 🚨 session-state: The PR adds and backfills D1 lifecycle and credential cleanup state for persisted interactive sessions.
• merge-risk: 🚨 auth-provider: The PR changes GitHub OAuth callback validation and GitHub credential handling paths that existing deployments rely on.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists automated validation only; external PRs need redacted real behavior proof from the changed runtime path before merge. 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: AGENTS.md was read in full; the relevant applied rule is that OpenClaw CHANGELOG.md is release-owned, so the PR's changelog edit is not treated as a contributor action requirement. (../AGENTS.md:26)
• current main boundary: Current main exposes the legacy CRABBOX_RUNTIME_PROVISION_URL path but has no CRABBOX_RUNTIME_ADAPTER_URL or runtimeAdapterName lifecycle surface, so the PR is not obsolete on main. (worker-configuration.d.ts:15, 8845c26f367c)
• PR implementation surface: The PR adds lifecycle reconciliation, create/provision logic, runtime adapter stop handling, and session serialization in src/index.ts. (src/index.ts:3104, 658bcbe9cf7a)
• persistent state changes: The PR adds four migrations for runtime adapter lifecycle, credential-policy cleanup, and standalone sandbox expiry state. (migrations/0020_runtime_adapter_lifecycle.sql:1, 658bcbe9cf7a)
• proof evidence: The PR body lists automated tests/checks and migration replay, but no screenshot, terminal output, logs, recording, or linked artifact proving the changed runtime behavior in a real setup. (658bcbe9cf7a)
• security-sensitive adapter handling: The runtime adapter fetch path requires a configured token, validates HTTPS or literal loopback HTTP, disables redirects, and uses a 10 second abort timeout. (src/index.ts:11401, 658bcbe9cf7a)

Likely related people:

• Peter Steinberger: Introduced the interactive session creation path, default sandbox behavior, and later session supervision work that this PR extends. (role: feature owner; confidence: high; commits: 64a6c1d49ef4, 13fdae9b07ca, 6994827254cf; files: src/index.ts, cmd/crabfleet/main.go, src/fleet-state.ts)

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.