mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 07:42:38 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A volume-free server keeps no local volume. It must find every file it needs in durable storage. > - Before a volume-free server starts, a data gate refuses to start if records still point at files on a local disk. > - Old native runs can keep runtime skill bundles that a release before #19729 wrote only to its own disk. The gate reports these as `runtime_skill_assets_require_migration`. > - On a volume-free server those files are not on the disk, and no volume can be attached again. So the refusal repeats on every restart, and nothing can clear it. A staging stack crash-looped like this and stayed down. > - This pull request makes the server copy every retained bundle that is still on its disk into durable storage, and start over the bundles that are gone, the same way #20990 handles harness backups. > - The benefit is that a volume-free stack can always start again. No one has to repair it by hand. ## Linked Issues or Issue Description Refs #19675, #19729, #20990 **What happened?** A volume-free staging stack ran for twelve days on a release that kept runtime skill bundles only on its container disk. When that container stopped, every newer release crash-looped at boot with `Volume-free server data is not eligible: runtime_skill_assets_require_migration`. The old container was gone, so the bundles were gone. The deploy could not roll back, and a retry could not help. **Expected behavior** A volume-free server starts. It saves each retained bundle that is still on its disk to durable storage. It starts over a bundle that is not on its disk when the volume-free owner marker proves that no volume is mounted, and restart recovery owns those runs. **Steps to reproduce** 1. Retain a native run with an admitted runtime skill bundle that has no version ID and no durable preservation receipt. 2. Remove the bundle from the instance root. 3. Start the server with `PAPERCLIP_EPHEMERAL_SERVER=true` and the volume-free owner marker present. 4. Startup fails with `runtime_skill_assets_require_migration`, on every restart. ## What Changed - `runtime-skill-preservation.ts`: - The obligation scan is one generator. `hasLocalRuntimeSkillObligations` uses it. - New `preserveLocalRuntimeSkillObligations` copies each obligated run's bundles with `preserveRuntimeSkillAssets` and returns `{ bundles, unsaved }`. - A missing source is decided at its reader: `readLocalManifest`/`readSource` throw `RuntimeSkillSourceAbsent` (other instance root, or a missing directory, manifest or listed file). Only that error marks a run unsaved. Any other failure, including an `ENOENT` from storage or cache work, propagates. - `preserveRuntimeSkillAssets` no longer aborts on an invalid or non-durable existing receipt. It copies the local bytes again and replaces the receipt. - One durability helper (`preservedAssetRowDurable` for metadata, `preservedAssetDurable` with a metadata or object read) replaces the copies in the scan, staging, locking, preservation and rehydration. - `runtime-skill-preservation-reference.ts`: the scan matches only null pins, which is exactly what preservation copies. A non-null pin is a version pin and cannot become an obligation that nothing can settle. - `file-manifest-cache.ts`: new `inspectFileManifest` returns `verified`, `missing` or `changed` from the same walk. `verifyFileManifest` wraps it. - `ephemeral-server-contract.ts`: the gate saves the bundles still on the disk. If none stay unsaved, the blocker clears. Unsaved runs are waived only when the volume-free owner marker is present, with a warning. A save failure still refuses. The decision uses the copy pass result, not another scan. One exported blocker constant. - `ephemeral-migration-data.ts`: offline enrollment accepts the blocker and copies the bundles from the attached volume, in a phase after the package phases. Any unsaved run still fails the enrollment. - `index.ts`: comment update only. - Tests: `ephemeral-server-runtime-skill-startup.test.ts` (real scan, real copy, embedded Postgres) and an S3-gated case in `ephemeral-migration.test.ts`. ## Verification - `cd server && npx vitest run src/__tests__/ephemeral-server-runtime-skill-startup.test.ts` - Red on `origin/master`: 2 of 3 fail with the production error `Volume-free server data is not eligible: runtime_skill_assets_require_migration`. - Green with this change: all cases pass (lost bundle, saved bundle, no marker, mixed present and lost, one missing listed file, non-version pin, mixed pins, non-durable receipt recapture, storage failure, storage ENOENT, unsaved set). - `cd server && npx vitest run src/__tests__/ephemeral-server-startup-run-state.test.ts src/__tests__/runtime-skill-preservation.test.ts` pass (existing gate and preservation behavior unchanged). - `cd server && npx tsc --noEmit -p .` passes. - `ephemeral-migration.test.ts` needs `PAPERCLIP_TEST_S3_ENDPOINT`. It typechecks, but it was not run here. ## Risks - A run whose bundle is lost now starts under restart recovery instead of blocking the whole server. Recovery of that one run can fail. Before, the whole server stayed down, and the bundle was lost anyway. - Startup does more work only when unsaved legacy bundles exist. A current release saves bundles before admission (#19729), so new runs never add this work. - No schema change. No API change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use (shell, file edits, test runs). ## 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>