## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Before a run starts in a new sandbox, Paperclip prepares the task
workspace. It also attaches the saved files of earlier failed runs under
`.paperclip-recovered/<operation>` so the agent can continue their work
> - A run that restores a saved workspace and then fails can save the
same version again. Workspace recovery keeps a receipt for that run. One
saved version can then have a receipt from each of several failed runs
> - Preparation attached the files once for each receipt. It removed
duplicates only by receipt operation ID
> - On staging, six receipts named the same 1 GB saved version. Each new
sandbox received six copies (about 6 GB and 171k entries) before its
first save. The first save then failed with
`remote_workspace_sandbox_disk_full`. The read-only fallback also
refused with `budget_exceeded`, because its inventory limit is 100,000
entries
> - The next sandbox received the same six copies. No run could succeed,
so nothing retired the copies, and the task failed in the same way about
every 30 minutes
> - This pull request attaches each saved version once
> - The benefit is that a task with several recovered failed runs gets
one copy of their saved work, and its sandbox has space for its first
save
## Linked Issues or Issue Description
Refs #22466 (names this failure `sandbox_disk_full`). Refs #22383,
#22239, #22068 (other full-sandbox-disk handling). Those changes name
the failure and stop repeats. This change removes the cause of this
case.
**What happened?**
On staging, three tasks failed during setup again and again with
`remote_workspace_sandbox_disk_full: the sandbox disk is full; free
space in the sandbox before saving the workspace`. Each run used a new
sandbox. One workspace failed its initial save 18 times in about 8
hours. Its metadata recorded six recovered attachments. All six came
from one earlier workspace, one snapshot and one sha256 (1,040,502,418
bytes, 28,576 entries). Only the source run was different. Each of those
six source runs had restored that snapshot, saved it again unchanged
(`reusedSnapshotId` equals the parent), and failed for another reason.
**Expected behavior**
The new workspace gets one copy of the saved version. Its first save has
space.
**Steps to reproduce**
1. Save a workspace (version A).
2. Start a writer that restores A, saves A again unchanged, and fails.
Record its recovery receipt.
3. Do step 2 again with a second writer.
4. Prepare a new workspace with both failed writers as recovery
predecessors.
5. See two full copies of A under `.paperclip-recovered/`.
## What Changed
- `remote-workspace-recovery-attachments.ts`:
`attachPreservedRemoteWorkspaceSnapshots` first collects the verified
receipts. It then attaches each saved version (source workspace,
snapshot ID, sha256) once, under the receipt of the earliest source run.
If any receipt of a version is retired, the version is retired. Receipt
verification, access checks, and the provenance of an attached copy do
not change.
- `remote-workspace-snapshot-reuse.test.ts`: a new database-backed test
uses the existing reused-save recovery fixture with two failed writers.
The `same` case expects one copy. The `changed` case (the second writer
saved different files) expects two copies. Both cases check that a
retired receipt retires its whole version. The recovery stamping moved
into a helper (`recoverFailedWriter`) for both writers.
## Verification
- Red: on unmodified `master`, `pnpm vitest run
src/services/remote-workspace-snapshot-reuse.test.ts -t "attaches each
saved version once"` fails for the `same` case: `expected [ {…}, {…} ]
to deeply equal [ ObjectContaining{…} ]`, which is two copies of one
version. The `changed` case passes.
- Green: with the change, `pnpm vitest run
src/services/remote-workspace-snapshot-reuse.test.ts
src/services/workspace-recovery-preparation.test.ts
src/services/remote-workspace-recovery-receipt-fallback.test.ts` passes:
3 files, 125 tests. These include the existing same-run duplicate check,
retired copies, unverifiable receipts, and storage backend selection.
- `node scripts/typecheck-layers.mjs` in `server/`: no errors in
`server/src`. My sandbox installed only the server dependencies, so
`cli/`, `ui/` and `packages/kv-demo-mcp-server` reported missing-module
errors there. CI runs the full typecheck.
- I did not run a live sandbox preparation. The staging workspace
records above give the sizes and the six duplicate receipts.
## Risks
- Low. Only duplicate copies of one saved version are skipped. Different
versions are all attached, as before.
- The agent sees one recovered folder for that version instead of
several identical folders. The recovered-files list is context for the
agent only. No settlement step needs one copy per source run.
- Existing workspaces keep their old records. In a new sandbox, the
records of copies that are not attached again are dropped, as for any
copy that is absent.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution.
## 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
- [ ] 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: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>