Files
PaperClipAI/packages
Nicky LeachandClaude Opus 5.5 45523d21d0 fix(runner): re-bind any settled ACPX checkpoint across a Runner upgrade (#21220)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Runner runs Claude Code through the ACPX backend and saves
a durable checkpoint so a later run can continue the same conversation
> - Each Runner release changes the ACPX launch profile digest that the
checkpoint stores
> - Restore re-binds a saved checkpoint to the new digest only when it
is `suspended`, or when the same run resumes an interrupted turn
> - A retired or parked Claude Runner leaves an idle `session_open`
checkpoint, so a follow-up from the next run fails with
`provider_state_incompatible` before its first turn
> - `run.attach` already accepts that checkpoint. The restore gate is
stricter than the attach it serves
> - This pull request defines a settled checkpoint once and uses the
same rule for attach and for the upgrade re-bind
> - The benefit is that a completed Claude conversation continues after
a Runner upgrade, and a refused re-bind names its reason

## Linked Issues or Issue Description

Fixes #21212

Refs #20112 (the same-run interrupted-turn case, which this change keeps
as is)

## What Changed

- Added `settled_checkpoint_blockers`. A settled checkpoint is not
closed, has a provider identity, has no active turn, has no unconfirmed
provider exit, and has no undelivered event except a `session.resumed`
notice. `run.attach` now admits with this function. The warm-attach
readiness probe also uses it, and still waits for a pending
`session.resumed` notice.
- Restore re-binds any settled checkpoint to the current launch profile
digest, whichever run saved it and whatever its lifecycle
(`session_open`, `prepared` or `suspended`). Candidate admission, a
changed launch shape and pending runtime requests still block the
re-bind.
- `rebinds_interrupted_turn` keeps only its distinct case: the same
run's `turn_starting` or `turn_active` turn, under the lost-turn
recovery preconditions from #20112. The settled rule now covers its
`session_open` case.
- A digest mismatch that is not re-bound now names each reason, for
example `(not re-bound: durable_active_turn)` or `(not re-bound:
launch_shape_changed)`. The classification stays
`provider_state_incompatible`.
- Updated "Settled ACPX sessions across a Runner upgrade" in
`packages/paperclip-runner/docs/durable-recovery.md`.

## Verification

From `packages/paperclip-runner/runner`:

- `cargo test -p paperclip-runner-core --lib acpx_provider_backend`: 48
passed
- `cargo test -p paperclip-runner-core --test acpx_warm_attachment`: 6
passed
- `cargo test --locked -p paperclip-runner-core --no-fail-fast`: 1108
passed, 0 failed, 6 ignored
- `cargo fmt --all -- --check` and `cargo check --locked --workspace`:
clean

New and changed tests:

-
`settled_checkpoints_of_a_retired_runner_rebind_for_the_next_run_after_an_upgrade`
covers `session_open` with a semantic result, `prepared` with an
identity, and a pending `session.resumed` notice. Each checkpoint is
saved by run 1 and restored by run 2 under a new digest. Restore does
not write the checkpoint, `run.attach` succeeds, and the saved digest
becomes the current one. This test fails before the fix.
-
`continues_a_settled_conversation_in_the_next_run_after_a_runner_upgrade`
runs end to end with the fake sidecar. The replacement Runner attaches,
resumes the same provider session, and emits exactly one `turn.started`.
This test fails before the fix with the production error.
-
`unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class`
no longer lists `session_open` as strict. Each remaining strict case
asserts the reason in its error.

I did not run clippy because CI does not run it. I did not run `pnpm
verify` because only Rust and docs changed.

## Risks

- The re-bind now admits more checkpoints. It admits only the states
that `run.attach` already admits on the same build, so no in-flight
provider work moves to a new build. An active turn, a pending runtime
request, an unconfirmed provider exit, or an undelivered non-resume
event still blocks the re-bind.
- A same-run `session_open` checkpoint that has a semantic result or an
active goal now re-binds. The same build already re-opens this state.
The result and goal checks gate lost-turn recovery only, and that
recovery path is unchanged.
- Session start still verifies every launch artifact, the command digest
and the restored provider identity after the re-bind.
- No migration and no API change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, sub-agents) and extended thinking. One sub-agent
wrote the change. A second session reviewed it before this pull request.

## 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
- [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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 17:44:58 -08:00
..