Files
PaperClipAI/packages/paperclip-runner/runner
DottaandClaude Opus 5.5 3452639a81 fix(runner): reject only the overflow call when parallel tool calls exceed the result reserve (#21913)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Native agent runs call Paperclip tools through the runner's provider
tool bridge
> - The bridge reserves 768 KiB for each pending call against an 8 MiB
budget per turn
> - When an agent sends many tool calls in parallel, the reserve for the
pending calls can go over the budget, although the bytes the turn really
holds are small
> - The bridge then reports the durable receipt limit, and the backend
stops the whole turn. The run ends as cancelled with `needs_review`, and
the task stays blocked with a Retry button
> - This pull request rejects only the overflow call as retryable, and
keeps the turn stop for real held bytes. It also adds a server backstop:
a turn stopped at the receipt limit continues by itself in a fresh
session
> - The benefit is that a parallel burst of tool calls no longer leaves
a task waiting for a person

## Linked Issues or Issue Description

**What happened?**
In a restart-chaos wave, an opencode agent sent 10 parallel `get_task`
calls. The turn already held about 0.7 MB of results. 10 × 768 KiB plus
0.7 MB is more than 8 MiB, so `begin_call` returned
`active_turn_receipt_limit()` for the 10th call. This branch does not
set `durable_run_receipt_limit_reached`, so it is a temporary reserve
overflow. `handle_tool_call` sends every receipt-limit error to
`stop_turn_at_tool_receipt_limit`, which interrupts the turn. The run
ended as cancelled with `needs_review` and a human review request. The
release then blocked the task
(`native_continuation_requires_reconciliation`) and showed Retry. No
continuation was scheduled. The task moved again only because a person
posted a comment ten minutes later.

**Expected behavior**
The overflow call gets a normal, retryable rejection, and the turn
continues. The agent can send the call again after a pending result
arrives. If a turn does stop at the receipt limit, Paperclip continues
the task in a fresh session, as it does for `agent_tool_call_loop`
(#21734). The task does not show Retry.

**Steps to reproduce**
1. Start a native turn that holds about 600 KiB of settled tool results.
2. Send 10 tool calls in parallel.
3. On master, the 10th call stops the turn, and the task becomes blocked
with Retry.

**Paperclip version or commit**
`master` at c5218f5ec4 (wave), rebased on 991f773d7f.

## What Changed

- `provider_bridge.rs`: the two `begin_call` branches that fail only
because of the per-call result reserve now return a new retryable error
(`tool_calls_in_flight`). The provider sees "Too many tool calls are in
flight. This call was not executed. Wait for the pending tool results,
then retry it." The branches that set
`durable_run_receipt_limit_reached` (real held bytes, exact identity
capacity, saturated replay history) still stop the turn.
- `provider_backend.rs`: the invalid tool call result sets `retryable`
from the error, so this rejection is `retryable: true`. Other rejections
stay `false`.
- `native-tool-receipt-limit.ts` (new): reads the persisted,
source-bound `harness.diagnostic` event with code
`semantic_tool_turn_receipt_limit` for the run, and holds the lane
constants and the hint for the next session.
- `status-arbiter.ts`: a run that did not succeed and whose runner
stopped it at the receipt limit preserves the task status and schedules
a retry with cause `semantic_tool_turn_receipt_limit` (and releases run
resources when it was cancelled). This applies only when the task owner
holds the decision, with no review, governance gate, open blocker, pause
hold or prior `blocked` status, and at most 2 times per chain. Other
cases keep their current path.
- `native-provider-capacity-retry.ts`: the capacity retry is now one
lane of a shared fresh-session retry helper. The new receipt-limit lane
creates a `scheduled_retry` run due in 5 seconds with
`forceFreshSession` and a liveness instruction that tells the agent to
make fewer parallel calls.
- `status-decision-committer.ts` and `native-run-finalizer.ts`: wire the
new lane, and require the task owner under the issue lock, as for the
capacity retry.

- `acpx_provider_session.rs` (Claude, Cursor and other ACPX agents)
handles the same retryable error per call: it drops the pending sidecar
call and resolves only that call with the retryable error. Other
`begin_call` errors still fail closed.
- The external provider path (Dot/Muse) is out of scope and unchanged:
it still fails closed on this overflow, as on master. Making a
same-requestId retry safe there needs retry generations across the
executor, the driver command ids and the broker receipts. That is a
follow-up.
- The receipt-limit backstop reads only the diagnostic of the final turn
in the run's session.
- A person's Stop always wins: the finalizer re-reads the saved Stop on
each arbitration attempt, the retry helper refuses under the run lock,
and the #21734 tool-call loop continuation is not queued, or is
cancelled, for a stopped run.

The runner change is runner-image content. The Daytona runner image must
be rebuilt before sandboxes get the runner fix. The server backstop
works with older images.

## Verification

- Red then green, `provider_bridge.rs` unit test
`parallel_calls_over_the_result_reserve_reject_only_the_overflow_call`:
with about 600 KiB settled, 9 calls are admitted. On master the 10th
returns `is_active_turn_receipt_limit()`. Now it is a retryable
rejection, the durable flag stays false, and the same call is admitted
after one pending result settles.
- Negative, `held_result_bytes_over_the_limit_still_stop_the_turn`: real
held bytes over the limit still return the receipt limit with the
durable flag set.
- `cargo test -p paperclip-runner-core -- --skip task_memory::`: all
pass (640 lib tests plus the integration suites). The `task_memory`
monitor tests are timing-based kernel OOM monitor tests that do not run
correctly on macOS (one hangs); this change does not touch them, and CI
runs them on Linux.
- Red then green, `native-tool-receipt-limit.integration.test.ts` (real
Postgres): a run stopped at the receipt limit gets one `scheduled_retry`
successor with `forceFreshSession` and the hint. The release does not
block the task and creates no recovery action. The task stays
`in_progress`. The presentation shows `retry_scheduled` with no Retry,
then `working` after promotion. With the master arbiter, no successor is
created. A negative case (another diagnostic code) keeps
`cancellation_run_only`.
- Red then green: ACPX
`receiver_rejects_only_the_tool_call_that_overflows_the_result_reserve`
(11-call burst through the fake sidecar).
- Red then green, server: an earlier turn's diagnostic gives no
continuation; a Stop saved before or right after the finalizer's first
read gives no continuation and settles the cancellation with no recovery
action; the retry helper throws `NativeStatusRaceError` for a stopped
run; the loop continuation is not queued, and a queued one is cancelled,
for a stopped run.
- `status-arbiter.test.ts`: the new branch, the 2-continuation bound,
and the `blocked` exclusion.
- Focused server tests pass: the new test,
`native-provider-overload.integration.test.ts`,
`status-arbiter.test.ts`, `native-status-arbiter-corpus.test.ts`,
`heartbeat-run-dispatch-work.test.ts`,
`native-run-finalizer-telemetry.test.ts`,
`native-workspace-finalizer.test.ts` (306 tests). `tsc --noEmit` passes
for `server`.
- `pnpm verify` exits 2 (a runner-core change needs broad coverage), so
required CI supplies it.

## Risks

- Dot/Muse agents still lose the turn on this overflow until the
follow-up lands (no change from master).
- An agent that keeps more than about ten large calls in flight now gets
rejections for the extra calls instead of a stopped turn. It can send
them again after results arrive. Real held bytes still stop the turn.
- The receipt-limit continuation starts a fresh session. The in-turn
conversation is lost; the task, comments, documents and saved workspace
stay. It runs at most 2 times per chain, then the current path applies.
- The retry lane shares the failure-retry count with the capacity lane.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude
Code with tool use and code execution.

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

Refs #21734

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:53:55 -06:00
..