feat(cloud-agent): cache prepared workspaces#3974
Open
eshurakov wants to merge 2 commits into
Open
Conversation
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Contributor
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Executive SummaryBoth previously flagged issues have been resolved: Resolved Issues
Files Reviewed (20 files)
Reviewed by claude-4.6-sonnet-20260217 · 265,339 tokens Review guidance: REVIEW.md from base branch |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why
Fresh Cloud Agent sessions repeatedly clone repositories and rebuild the same setup-produced workspace state. Reusing a prepared repository directory can shorten cold starts, but the cache must not become authoritative for Git state, credentials, or session-specific runtime data.
What was done
High-level architecture
sequenceDiagram participant Session as Cloud Agent session participant Adapter as Sandbox adapter participant R2 as R2 backup index participant Sandbox as Cloudflare Sandbox participant Wrapper as Session wrapper Session->>Adapter: Ensure prepared wrapper Adapter->>R2: Load owner-scoped backup record alt Valid cache hit Adapter->>Sandbox: Restore repository directory Adapter->>Wrapper: Ensure session ready from warm base Wrapper->>Wrapper: Reconcile Git and rerun setup alt Reconciliation fails Wrapper-->>Adapter: WORKSPACE_RECONCILIATION_FAILED Adapter->>Sandbox: Remove restored workspace Adapter->>Wrapper: Retry normal cold bootstrap Adapter->>Sandbox: Create directory backup Adapter->>R2: Publish validated backup record end else Miss or ineligible Adapter->>Wrapper: Run normal cold bootstrap opt Eligible miss Adapter->>Sandbox: Create directory backup Adapter->>R2: Publish validated backup record end end Adapter-->>Session: Session readyArchitecture decision
Decision: Use Cloudflare Sandbox directory backups as owner-scoped warm repository bases, while preserving authoritative Git reconciliation and setup execution for every restored session.
Context: Full runtime snapshots would capture session-specific credentials, process state, and home-directory data, while skipping reconciliation or setup would trust cached state beyond its safe lifetime.
Rationale: Repository-only backups reuse setup-produced filesystem state without changing the existing wrapper's ownership of Git reconciliation, session materialization, and setup semantics. Credential-free cache identity and current-token restoration keep authentication outside the persisted contract.
Alternatives considered:
Consequences: Cache hits still pay Git reconciliation and setup costs, and setup-generated untracked files may survive into the warm base. In return, cache failure can remain isolated from session correctness and most misses degrade to the existing cold path.
Verification
Visual Changes
N/A
Reviewer Notes