feat(cloud-agent-next): add durable control-plane diagnostics

[eshurakov]

Summary

• Add verbose, sanitized Worker/DO and wrapper diagnostics for heartbeats, event forwarding, task phases, deadlines, provider operations, and durable message transitions so stalled sessions can be investigated beyond the final failure reason.
• Archive bounded structured wrapper batches in the existing R2 bucket using allocation-scoped upload-only grants. Add internal authenticated list/download routes that remain usable after the sandbox disappears, and document the operator workflow.
• Keep diagnostics best-effort: exclude credentials and message/tool content, bound buffering and shutdown flushing, stop uploads after authentication rejection, and limit optional signing-secret lookup to one second. Preserve existing session lifecycle and allocation fencing.

Verification

No manual/live-provider end-to-end validation was performed. The local stack was not configured in this worktree, and no deployment was made. Live-provider verification remains outstanding; automated coverage is listed below.

Visual Changes

N/A

Reviewer Notes

Automated checks passed on the final changes:

• Repository formatting check and git diff --check.
• Cloud Agent lint, Worker/wrapper typecheck, and production wrapper build.
• Service regressions: pnpm exec vitest run src/sandbox-control src/sandbox-session src/server.test.ts test/unit/sandbox-control.test.ts — 983 passed.
• Wrapper control regressions: bun test src/control — 231 passed.
• Focused Workers-runtime checks — 6 control-socket tests and 30 terminal-bridge tests passed in separate runs.

The complete Workers control suite timed out during review after printing test passes; this is not a full integration-suite pass. The teardown issue remains unverified and no workaround was added.

Verbose metadata logging is enabled by default. Upload grants expire after four hours without renewal. R2 retention remains governed by the existing external bucket policy; this PR does not change retention or add historical-data processing.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (25 files)

• services/cloud-agent-next/DEBUG.md
• services/cloud-agent-next/src/persistence/SandboxControl.ts
• services/cloud-agent-next/src/sandbox-control/cloudflare-provider.ts
• services/cloud-agent-next/src/sandbox-control/diagnostics.ts
• services/cloud-agent-next/src/sandbox-control/lifecycle.test.ts
• services/cloud-agent-next/src/sandbox-control/log-routes.test.ts
• services/cloud-agent-next/src/sandbox-control/log-routes.ts
• services/cloud-agent-next/src/sandbox-control/log-upload-grant.test.ts
• services/cloud-agent-next/src/sandbox-control/log-upload-grant.ts
• services/cloud-agent-next/src/sandbox-control/socket.ts
• services/cloud-agent-next/src/sandbox-control/vercel-provider.ts
• services/cloud-agent-next/src/sandbox-control/wrapper-launch-env.test.ts
• services/cloud-agent-next/src/sandbox-control/wrapper-launch-env.ts
• services/cloud-agent-next/src/sandbox-session/SandboxSession.ts
• services/cloud-agent-next/src/server.test.ts
• services/cloud-agent-next/src/server.ts
• services/cloud-agent-next/src/shared/control-diagnostics.ts
• services/cloud-agent-next/src/shared/runtime-environment.ts
• services/cloud-agent-next/wrapper/src/control/diagnostics.test.ts
• services/cloud-agent-next/wrapper/src/control/diagnostics.ts
• services/cloud-agent-next/wrapper/src/control/main.ts
• services/cloud-agent-next/wrapper/src/control/sandbox-control-client.ts
• services/cloud-agent-next/wrapper/src/control/sandbox-control-handlers.ts
• services/cloud-agent-next/wrapper/src/control/sandbox-control-runtime.ts
• services/cloud-agent-next/wrapper/src/control/worktree-runtime.ts

---

_{Reviewed by grok-4.6 · Input: 288.7K · Output: 27.2K · Cached: 3.2M}

_{Review guidance: REVIEW.md from base branch main}