Files
PaperClipAI/packages
Nicky Leach 3a41e54c51 perf(runner): start ACPX once on parked checkpoint relaunch (#22064)
## 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
2026-11-17 13:32:28 -08:00
..