mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 07:42:38 +01:00
## 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>