mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-12 06:10:44 +01:00
DottaandClaude Opus 5.5
15b987d9b8
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Restarts must be invisible to a task: an agent that was working
keeps working after the control plane comes back
> - Restart chaos t05 (Daytona warm wave, codex, K4 hold) ended a task
as blocked even though its document save succeeded
> - #20069 refuses a finish or block that the agent decided before it
saw results that had already returned. Here the results had not returned
yet when the block was checked: after the reattach, the held calls and
the later block are handled at the same time
> - This pull request makes a finish or block wait, for a bounded time,
for earlier calls of its turn that have not returned, and then apply the
same check
> - The benefit is that a controller outage during a Paperclip tool call
no longer turns into a false "blocked" task
## Linked Issues or Issue Description
Refs #19831 (durable ownership plan). Restart chaos wave
`w-20261108T192459-s9501`, task t05 (Daytona warm, codex, C1, K4 hold of
182 s, master c5a172a183, which includes #20069).
**Problem**
1. 19:37:01: the follow-up comment arrives. The agent reads the brief
and calls `write_document`.
2. 19:37:44 to 19:40:51: K4 hold. Codex keeps the call pending and
re-samples the model: "The save request is still pending", then
`read_document` (also pending), then `paperclip_block`.
3. 19:42:02, after the reattach: the controller recovers the held write
and read (`recoverPendingSemanticInputs`) while the Runner delivers the
block. The block reaches the check at seq ~331–334. The write's result,
with the FOLLOWUP line saved, is committed at seq 337. The check saw no
returned call, so the block was recorded and the issue rested `blocked`
with no Retry.
So held calls are answered after ready (the save succeeded, the brief
has the marker). The defect was the order in which the terminal call was
judged.
## What Changed
- `packages/paperclip-runner/src/live/terminal-call-freshness.ts`:
- `pendingEarlierToolCalls`: calls made before the terminal call that
have neither returned nor reached the agent;
- `settleEarlierToolCalls`: waits, bounded at 30 s
(`TERMINAL_CALL_SETTLE_TIMEOUT_MS`), until none is pending, then reports
which returned unseen and which are still pending;
- `staleTerminalCallResult` also names still-pending calls: "has not
returned yet. Wait for its result (do not repeat a write until it
returns)…", still `terminal_call_before_results`, retryable.
- `runnerd-codex-transport.ts`: before dispatching `paperclip_finish` or
`paperclip_block`, waits for those calls and re-checks session identity.
It refuses the terminal call if any earlier call returned unseen or is
still pending.
- Scope: `DurablePrpCodexTransport` serves Codex and ACPX on local, warm
Daytona and per-turn Daytona, so every path that reattaches to a
surviving Runner is covered. The wait applies only to terminal calls
with earlier unreturned calls, so it adds nothing before `turn.start`.
- Not covered: the external-driver path
(`drivers/external/runnerd-external-driver.ts`) has its own semantic
handler without either check. It is recorded as a campaign follow-up.
## Verification
Red/green:
- `runnerd-codex-transport.test.ts` "refuses a terminal call that
arrives before a held call's result (restart chaos t05)": the write is
started without a result, the block arrives, and the write's
`semantic_tool.result` lands 100 ms later.
- On master's transport and guard: fails, the block is dispatched
(`handler` called once).
- With this PR: the block is refused with
`terminal_call_before_results`, naming the returned write.
- `terminal-call-freshness.test.ts`: pending versus returned, a result
that lands during the wait, a call still pending after the bound, no
wait when everything was seen, and a session that goes away.
- Both files: 300 passed. `tsc --noEmit -p packages/paperclip-runner` is
clean.
Live: the crash point `runner.semantic_tool.after_input_before_dispatch`
(from #20069) holds K4 during a Paperclip tool call. A Daytona run
against this branch is requested from the slot owner after merge.
## Risks
- A finish or block made in the same model step as a write (parallel
tool calls) now waits for the write and is refused once, because the
agent had not seen the write's result. The agent calls it again after
reading the result: one extra model step in that case. #20069 already
behaved this way whenever the write returned first.
- A Paperclip call that never returns delays a terminal call by 30 s,
and the terminal call is refused. Recovery answers held calls after
ready or disconnects the Runner, so the refusal cannot repeat
indefinitely in practice.
- No schema or persisted run-state change.
## Model Used
Anthropic Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code, with
tool use (shell, file editing).
## 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 (#20069)
- [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 (code
comments; no user docs affected)
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green (pending)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(pending)
- [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>