docs(design): plan — warm and resumable Daytona sessions (F-020)

[mmabrouk]

The symptom

Every conversational turn on a Daytona agent pays a full sandbox creation, measured live at about 20 seconds per turn (QA finding F-020). A user's second message in the same chat waits through provision, mount, and harness startup that the first turn already paid for. PR #5197's durable continuity makes the resumed turn answer correctly, but no sandbox instance is ever reused.

What this PR contains

A design-only plan-feature workspace at docs/design/agent-workflows/projects/warm-daytona-sessions/ (README, context, research, plan, open-questions, status). No code changes. No live Daytona runs.

The load-bearing finding

The working tree already carries the warm plumbing (PR #5197 plus the untested lifecycle commit 60990d396e: keepWarm park at turn end, stored-id reconnect, native ACP session/load, ephemeral: false with autoStop/autoArchive/autoDelete timers). But the vendored Daytona provider (sandbox-agent@0.4.2) implements no pause and no reconnect. So pauseSandbox() falls back to delete, reconnect can never revive a stopped instance, and every turn still recreates. F-020's behavior stands at HEAD; only its mechanism description was out of date.

The two tiers

• Tier 1, cheap resume (park to stopped). Stop the sandbox at clean turn end, restart it by stored id next turn, session/load the harness. Parked cost is storage only; Daytona's own stop/archive/delete timers are the sweeper and crash backstop. Mostly prototyped already; the remaining work is two provider hooks, two failure-cleanup seam fixes in the vendored lifecycle, a compatibility fingerprint, and fenced pointer writes.
• Tier 2, true warm pool (park to running). Extend the keep-alive pool to Daytona with a short TTL and a running-sandbox cap. Near-instant second turns; parked cost is live compute, so the TTL and cap are billing knobs.

Recommendation

Land Tier 1 behind a default-off flag, close the P0 lifecycle gaps, and enable it after one credit-controlled live test on E3. Defer Tier 2 until its eviction can enforce the running cap safely, a billing owner sets the knobs, and F-018 (the Daytona tool-call hang) lands so tool turns benefit too. Durable replay stays the always-correct floor.

Review round

An ask-codex (xhigh) design review ran on the draft plan; its P0 findings (broken failed-pause fallback, double-sandbox reconnect leak, unfenced pointer writes, no reuse compatibility check, unmeasured latency claim) are folded into plan.md and noted in status.md.

https://claude.ai/code/session_018MaXPNpvzN22kngHno3VMj

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 10, 2026 11:17pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e9927a66-1a86-44c3-b871-5009f2d1ea70

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/warm-daytona-sessions-plan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Feedback needed on three decisions before implementation starts: (1) the crash-orphan compute budget and the DAYTONA_AUTOSTOP value (5 min can stop a sandbox under a live long tool call; the old default was 15) — needs the billing owner; (2) where the sandbox-pointer fence lives (session_states generation column vs the existing turn counter vs the Redis owner claim) — see open-questions.md #3; (3) whether Tier 2 should ship at all before Tier 1's real second-turn latency is measured on E3. Everything else in plan.md is ready to implement once these are settled.