mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 07:23:08 +02:00
Dotta
8478ddbcee
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Rust ACPX session can now suspend only at a safe idle boundary and its events have a durable projection > - A later runner process cannot safely resume from an unbound or partially written identity record > - The recovery anchor must bind the exact provider identity, run, normalized session, catalog revision, and catalog digest > - The record must be bounded, private, strict about schema drift, and atomically replaceable > - Recovery must re-admit the entire prospective session configuration before releasing the stored identity > - This pull request adds only that package-local checkpoint store without selecting ACPX in runnerd ## Linked Issues or Issue Description Refs #12424 Refs #12422 ## What Changed - Add a versioned ACPX safe-suspension checkpoint contract with unknown fields rejected at every persisted level. - Bind each checkpoint to the run, normalized session, catalog revision, catalog digest, and exact provider identity. - Persist a checkpoint-specific strict identity that requires the pinned permission mode without narrowing the additive live sidecar identity wire shape. - Construct checkpoints only from a session configuration whose model, permission policy, tool catalog, and expected identity validate. - Admit recovery only when reconstructing the checkpoint from the prospective configuration produces an exact match. - Reject run, session, catalog revision, catalog digest, model, permission, expected-identity, profile, and workspace drift fail closed. - Require persisted run/session IDs to satisfy the same stable-ID boundary as fresh session admission. - Store the checkpoint under a dedicated private runner-state subdirectory. - Bound checkpoint files to 1 MiB before reading or decoding. - Refuse symlinked state directories and non-private or non-regular checkpoint files. - Replace checkpoints atomically through a private temporary file and directory sync. - Make repeated saves of the same checkpoint idempotent. - Add integration coverage for private round trips, complete recovery admission, malformed/oversized files, nested schema drift, missing permission binding, invalid stable IDs, and symlink denial. - Document the package-local suspension recovery boundary. - Do not change dependencies, lockfiles, workflows, runnerd selection, server behavior, UI, or migrations. ## Verification - Replay base: `1ee738cf487defe88043b241c4e2dc34a1a8a7bc` (`master` after #12424 merged). - Exact replay head: `89cfea5495428be890810d2b8a27673943234ca3`. - Stable patch ID: `dbaeb0bbe773f1ca5ef1f9bdc0fa61f4a08ca451`. - The exact delta is 4 files and 591 additions, all in `packages/paperclip-runner`; it contains no lockfile, workflow, server, UI, dependency, or migration change. - `git diff --check` and the Cargo formatting check pass on the replayed delta. - Exact-head GitHub Actions run `33374006661` (attempt 2): **PASSED** with 23/23 jobs passed. - Greptile reviewed exact head `89cfea5495428be890810d2b8a27673943234ca3`: **5/5**, with zero unresolved review threads. - Superagent, contributor trust, Socket, and Snyk security checks: **PASSED**. - No local test result is claimed. GitHub Actions is the authoritative verification environment for this replayed revision. ## Risks - A checkpoint is valid only after the sidecar has confirmed safe suspension. The constructor therefore accepts the exact identity returned by that operation and revalidates it against local authority. - Loading proves only that the file is structurally valid; `admit_recovery` is the boundary that proves the file belongs to the prospective run, catalog, model, permission policy, and expected provider identity. - The checkpoint intentionally contains no credentials, bootstrap ticket, provider output, or pending request payload. - Strict checkpoint schema and identity validation rejects incompatible or tampered recovery records rather than attempting partial migration. This strictness is checkpoint-local and does not narrow existing PRP or sidecar wire compatibility. - Atomic replacement uses the platform `rename` primitive; Unix additionally syncs the private parent directory before reporting success. - No production path loads this checkpoint in this pull request. Runnerd execution and durable recovery wiring remain a later slice. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex with GPT-5.6, agentic reasoning, 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 linked the preceding public PRs or described the issue in-PR - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id - [ ] 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge