mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 23:08:26 +01:00
## Thinking Path > - Paperclip manages work for AI agents. > - Runner uses ACPX to resume provider sessions from durable checkpoints. > - A parked Runner can be gone after a reboot or retention eviction. The host can then verify the saved park checkpoint and start a replacement process. > - The relaunch currently opens a sidecar for source-run readiness and opens another for the incoming run. > - The replacement Runner keeps the source-run command fence until authenticated attachment. > - Runner can open the sidecar once with the incoming run's bindings and verify dormancy before it accepts the attachment. ## Linked Issues or Issue Description Refs #19912 for ACPX run and tool authority design. **What existing behavior does this improve?** ACPX follow-up when the parked Runner process is gone and the host starts a replacement from its verified park checkpoint. **Subsystem affected** Native Runner hosting and the ACPX provider executor. **Current behavior** The readiness probe and the idle event poll both enter generic recovery. Recovery opens the source-run sidecar. Attachment then closes it and opens a new sidecar for the incoming run. **Proposed behavior** A host can signal this path through private Runner control after verifying an earlier ACPX park checkpoint and confirming that the old execution has stopped. The replacement Runner checks provider eligibility and checkpoint settlement, serves readiness from saved state, and fences commands until authenticated `run.attach` starts the provider with the incoming run’s bindings. A live frozen Runner follows the existing thaw and claim flow. **Reason and benefit** This removes a sidecar startup and shutdown from the time to the next ACPX turn while preserving the conversation and applying the incoming run’s tool, instruction, and workspace bindings. **Breaking changes** The launch argument is optional and requires private host control in listener mode. The feature reads checkpoints from the previous release. No checkpoint or controller message format changes. ## What Changed - Keep a relaunched park within the existing host claim command fence. - Load a settled provider checkpoint that qualifies for host parking without opening the provider during readiness or polling. - Open the provider with the incoming run's settings. Verify the session identity and that it has no active work before publishing the new provider checkpoint. - Verify one sidecar start, preservation of the saved checkpoint on failed admission, and rejection of early turn execution. ## Verification - `cargo fmt --manifest-path packages/paperclip-runner/runner/Cargo.toml --all --check` - `cargo test --offline --locked -p paperclip-runner-core --lib --bins` passed locally (673 passed, 4 ignored). - The confined sidecar regression uses previous-release checkpoints for two ACPX providers. It verifies a single start on attachment for both and preserves the saved checkpoint when the live provider reports an active goal. - The authenticated loopback test restarts with a saved incoming provider checkpoint and a prepared authority receipt. It verifies receipt replay, rejection of the prior authority after activation, and command execution under the incoming run. - `cargo test --offline --locked -p paperclip-runner-core --test acpx_warm_attachment --test acpx_park_readiness --test durable_recovery` passed locally (19 passed). - Hosted CI passed. Greptile scored the current commit 5/5 with no unresolved review threads. ## Risks - An incorrect checkpoint could cross a run boundary. The private host signal requires settled Runner and ACPX provider checkpoints. Runner verifies live session identity and dormancy before transferring authority. - The existing transition receipt handles reconnects after attachment. The optional launch signal has no effect on older Runner binaries. ## Model Used - OpenAI GPT-6 (Codex), with source analysis and local Rust process and protocol tests. ## 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 documented the private launch contract and compatibility above - [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