mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-13 15:55:46 +01:00
DottaandClaude
1fa7e92fa8
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A native run talks to a Runner process. When the control plane loses
that Runner, the run resumes itself with a limited number of same-run
attempts.
> - A server freeze while the controller suspends a finished turn can
stop the Runner inside `runner.suspend`. The controller journal then
keeps that suspend as pending.
> - The next attempt starts a new Runner. It settles the old suspend
from the welcome, records `suspended`, and exits with code 0 before it
accepts any command of the new attempt. The server reported "runnerd
exited unexpectedly with code 0", so one freeze spent one same-run
attempt. If a second fault then occurs, no attempt is left in reserve.
> - #20714 made both sides agree on that suspend's acknowledgement. This
pull request handles the clean exit that follows it.
> - During startup, the server restarts that Runner in place once,
through the existing `#recoverRunnerProcess` path, and only when the
durable Runner journal proves the exit.
> - The benefit is that one freeze during a suspend costs zero same-run
attempts.
## Linked Issues or Issue Description
Refs #20714.
**What happened?**
A restart-chaos task (local Runner, Claude, a freeze of the server
during a live turn) needed a manual Retry. #20714 fixed the identity
mismatch. The second same-run attempt still ended with
`runner_local_connect_failed: runnerd exited unexpectedly with code 0`,
because that Runner only settled the suspend left by the first attempt
and then exited as suspended.
**Expected behavior**
The attempt continues. The server restarts the Runner once. The new
Runner starts from a clean `suspended` state and serves the attempt's
commands. No provider work is repeated.
**Steps to reproduce**
1. Start a native run. Let the controller send `runner.suspend` when it
closes the session.
2. Stop the Runner after it journaled the suspend and before the
controller records the result (a server freeze does this).
3. Resume the same run. The new Runner settles the old suspend and exits
with code 0, and startup fails.
The new live test reproduces this with the real runnerd and the fake
Codex provider.
**Paperclip version or commit**
`master` at e719d42557 (after #20714).
## What Changed
- `runnerd-codex-transport.ts`: when the transport opens its controller,
it records the number of commands already in the journal. These commands
come from earlier attempts.
- When a Runner exits with code 0 during startup, the transport reads
the local Runner state once. It restarts the Runner in place, once per
attempt, with a bounded 30 s grace through the existing
`#recoverRunnerProcess`, only when all of these are true:
- the Runner's last command is a `runner.suspend` from an earlier
attempt, with the same command id, type and controller sequence in both
journals;
- the controller has settled that suspend;
- the Runner is `suspended`, with no terminal fence, no provider cleanup
fence and no warm transition;
- no command of this attempt has a result, so no turn started and no
provider work ran.
- While that one restart runs, the startup waits for the replacement.
The startup does not fail on the old process.
- An exit that does not have that proof keeps its earlier failure. So do
remote, external-state and adopted Runners.
- The proof is a pure function, `carriedSuspendSettlementProven`,
exported through `runnerdRecoveryInternals`.
- `docs/durable-recovery.md`: it describes the restart.
## Verification
- Red, then green. New live test
`runnerd-codex-transport-carried-suspend.test.ts` (real runnerd binary,
fake Codex):
- `journaled`: the journals are rewritten to the freeze moment. Before
the change: `runner_local_connect_failed: runnerd exited unexpectedly
with code 0`. After the change: `thread/read` succeeds in the same
attempt, the old suspend is `failed / execution_indeterminate`, and the
provider has no `turn/start`.
- `fenced`: a released build left a terminal fence. The next Runner
keeps a provider cleanup fence, so it is not restarted. The test checks
that the earlier failure stays.
- Unit negatives for the proof: a suspend that this attempt queued, an
unsettled suspend, a last command that is not a suspend, a Runner that
went on to a later command, a command of this attempt with a result, a
Runner that is not suspended or has a fence, a receipt mismatch, and
another run identity.
- The live test passes with the Runner binary from before #20714 and
with the current `master` Runner.
- `npx tsc --noEmit -p packages/paperclip-runner`: clean.
- `runnerd-codex-transport.test.ts`, `-cut-attach`, `-settlement`,
`-suspension`, `-cold-restore`: 335 of 336 passed in one parallel run.
The one failure was a 20 s settlement case under load, and it passed
when run alone (19/19).
## Risks
- A clean exit that is not this case keeps its earlier failure. The
proof needs exact durable evidence. The restart happens at most once per
attempt and is bounded to 30 s.
- No command runs again. The old suspend is never executed again. The
replacement Runner starts from `suspended` and receives this attempt's
commands for the first time.
- Old Runners and old saved state: the proof only reads the Runner state
fields that released Runners already write. A state with a fence or a
provider cleanup fence is not restarted.
- The normal path has no added waits or file reads. The Runner file is
read only after a code-0 exit during startup.
- This changes no Runner (Rust) code. No new Runner image is needed.
> 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
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with
tool use (shell, file edits, test runs). Extended reasoning.
## 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 <noreply@anthropic.com>