Files
PaperClipAI/doc
DottaandClaude Opus 5.5 2a16be36ab docs(plans): per-turn follow-ups without re-uploading the repository (#20100)
## Thinking Path

- Per-turn remote sandboxes stay the default while warm reuse (#20048)
is on hold.
- On the paperclip clone, a per-turn follow-up spends about 13 s in
`workspace_sync.transfer`, though its changes pack in 0.5 s: every fresh
sandbox receives the whole 70 MB (gzip) seed again, at about 5 MB/s from
the controller.
- The coordinator asked for a design that uploads only changed files
into a fresh sandbox, with a full-upload fallback, measured against the
spans. It also asked to build it only if the implementation is bounded
and safe.

## Linked Issues or Issue Description

Refs #20048

**What happened?**
Per-turn follow-ups on large repositories wait about 13 s re-uploading
the full workspace seed even when almost nothing changed (pack 0.54 s,
transfer 13.3 s, time to first token about 31 s).

**Steps to reproduce**
1. Run `tests/restart-chaos/ttft-baseline.ts --env daytona
--workspace-repo <paperclip clone>` with per-turn sandboxes.
2. Compare `workspace_sync.pack` and `workspace_sync.transfer` on the
follow-up turn.

**Expected behavior**
A follow-up uploads only its overlay into a sandbox that already holds
the seed, falling back to the full upload when unsure.

## What Changed

- `doc/plans/2026-11-08-incremental-per-turn-workspace-upload.md`. It
contains:
- the measured span table and the size analysis (220 MB archive, 70 MB
gzip, about 5 MB/s);
- the expected saving: about 12–13 s per follow-up, time to first token
about 31 s → about 18 s;
- a design keyed by seed generation with a content-hashed manifest,
using a Daytona snapshot (preferred) or a Daytona volume to hold the
seed;
  - the overlay-only turn flow, with a verified fallback;
  - one bounded experiment to choose the seed location before building.
- Not built yet: both seed locations need provider capabilities
(snapshot build time, volume read speed) that must be measured first, so
the implementation isn't bounded until the experiment picks one.

## Verification

Docs only.

## Risks

None at runtime.

## Model Used

Claude Opus 5.5 (`claude-opus-5-5`, Anthropic), 1M context window, tool
use and code execution, via Claude Code.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 14:21:24 -06:00
..
…
…
…
…
…
…