Files
PaperClipAI/packages
1dba97303e fix(runner): wait for run.attach before restoring a Codex session on a fresh Runner (#22267)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Runnerd runs a coding harness such as Codex or Claude (through ACPX)
for one agent session, and keeps durable state so a later run can
continue the conversation
> - Core can rotate a session to a new run before it starts the Runner.
It archives the old Runner state and starts a Runner under the new run's
identity, over the same saved provider session
> - ACPX waits for `run.attach` in this case. Codex does not: if the
saved session was still open, Codex restores the app server on the first
poll or command, with the old run's settings
> - This pull request makes Codex follow the ACPX rule
> - The benefit is one app-server start with the new run's settings, and
no old-session events in the new run before attachment

## Linked Issues or Issue Description

**What existing behavior does this improve?**

A Runner that starts with fresh durable state over a saved, open Codex
session.

**Subsystem affected**

Runnerd: the durable runner and the Codex provider executor.

**Current behavior**

The Codex executor restores the app server on the first poll or command.
It uses the saved run's tools and settings. Restore events go out under
the new run before `run.attach`. If `run.attach` changes the tool set,
the app server restarts, so it starts twice.

**Proposed behavior**

The Codex executor waits for `run.attach` before it restores. Until then
it refuses commands that start work; snapshots and shutdown commands
still work. The wait is saved with the Codex state, so a restart before
attachment keeps it. `run.attach` treats the saved open session like a
stopped session, so the app server starts once with the new run's
settings. A Runner that recovers its own durable state restores as
before.

**Reason and benefit**

All providers then use one rule for a Runner that starts as a new run.
Today this case occurs only after a rotation from a lost Runner or from
a session left open. A later change can use the same rotation for every
follow-up that starts a new Runner process.

## What Changed

- Before it creates fresh durable state, the durable runner tells the
executor (`observe_fresh_durable_state`).
- The native executor then marks a saved Codex session as waiting for
`run.attach`. The Codex executor reads the mark when it loads the
session.
- The Codex executor does not restore the provider until attachment, and
refuses commands that start work. Snapshot, close, drain, suspend,
shutdown, interrupt, cancel and stop still pass.
- The mark (`awaitingRunAttach`) is saved before the Runner's durable
state exists, so a Runner lost or restarted before `run.attach` keeps
waiting. `run.attach` clears it. `run.attach` accepts a saved
`session_open` or `provider_exited` session without a live provider, the
same as a stopped (`prepared`) session.
- `DURABLE_TRANSPORT.md` describes the rule.
- Four tests: a fresh Runner waits for `run.attach` and starts Codex
once; a restart before attachment still waits; a Runner lost right after
a fresh start still waits; a recovered Runner still restores its own
session.

## Verification

- `cargo test -p paperclip-runner-core --test codex_provider --test
native_provider_backend --test durable_recovery`: 131, 47 and 4 passed.
- `npx vitest run src/live/runnerd-codex-transport.test.ts` in
`packages/paperclip-runner`, with a rebuilt runnerd: 335 passed,
including the removed-context rotation.
- `cargo test -p paperclip-runner-core --lib durable::`: 133 passed.
- Red-green: with the fence turned off,
`a_fresh_runner_waits_for_run_attach_before_restoring_a_saved_session`
fails on the first poll. Without the saved wait,
`a_fresh_runner_restarted_before_run_attach_still_waits_for_it` fails.
- `cargo fmt --all -- --check` passes.

## Risks

- Low risk. The fence applies only when the durable state is fresh and a
saved Codex session exists. New sessions have no saved session.
Recovered Runners do not get the fence.
- While the fence is set, the Runner refuses commands that start work.
Core sends `run.attach` first after a rotation, so no current flow is
blocked. Teardown commands still pass, so a session whose `run.attach`
fails can still close.
- The new state field is omitted when false, and older Runners ignore
it.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use
(code search, editing, local test runs).

## 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: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 19:23:02 -08:00
..