Files
PaperClipAI/packages
8299f7c389 perf(runner): check a listening Runner's backlog every 10 ms, not every reconnect delay (#21821)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A remote `paperclip_runner` agent runs `paperclip-runnerd` in a
sandbox or VM. A provider ingress proxies Core's WebSocket to a Runner
that listens (`--listen-address`).
> - In listen mode, the Runner checks for an incoming connection only
once per `--reconnect-delay-ms` (default 250 ms). It waits that delay
again after each disconnect, and it backs off after a failed handshake.
> - That delay exists to pace redials in dial mode. A listener never
dials. Core's connection waits in the kernel backlog until the next
`accept`.
> - Every listen-mode connect pays part of that wait. A warm run
attachment pays it in full: the Runner disconnects at the authority
rotation, and Core's new-authority connect then waits up to 250 ms or
more.
> - This pull request makes a listening Runner check for a connection
every 10 ms. Dial mode keeps the configured reconnect delay.
> - The benefit is about 0.4 s less on each warm run attachment and
about 0.1 s less on each cold start, for every listen-mode Runner.

## Linked Issues or Issue Description

**What happened?**
A warm follow-up turn on a listen-mode remote Runner reached its first
turn later than a cold turn on the same agent. In traces, a cold start
makes one Core→Runner connect of 134–178 ms. Each warm attachment makes
an old-authority reconnect (72–233 ms) and then a new-authority connect
of 411–504 ms. This was 6 of 6 warm runs.

**Expected behavior**
A connect to a listening Runner completes in about one network round
trip plus the WebSocket handshake. It does not wait for a reconnect
timer.

**Steps to reproduce**
1. Start `paperclip-runnerd` in listen mode with the default
`--reconnect-delay-ms`.
2. Let it reach the disconnected wait (startup, a park claim, or a
`run.attach` authority rotation).
3. Connect to the listener. The upgrade is not answered until the next
250 ms check.

**Root cause**
`durable/runner.rs` schedules the next `accept` at `now +
config.reconnect_delay` when no connection is pending, after a
disconnect, and as the base of the failure backoff. The Launcher-style
hosts do not pass `--reconnect-delay-ms`, so the 250 ms default applies.
The tests use a 1 ms delay, so they did not show the wait.

## What Changed

- `durable/transport.rs`: add `RunnerTransportEndpoint::retry_delay()`.
A listener returns `min(configured, 10 ms)`. A dial endpoint returns the
configured delay without change.
- `durable/runner.rs`: the four places that waited
`config.reconnect_delay` (no pending connection, failure backoff base,
two disconnect paths) now use
`endpoint.retry_delay(config.reconnect_delay)`.
- `DURABLE_TRANSPORT.md`: document the listen-mode connection check
interval.
- Add a unit test for the listener and dial delays.
- Add `tests/listener_accept.rs`. It starts `paperclip-runnerd` in
listen mode with the default reconnect delay. One connection drops
before authentication, as a superseded route's redial does. The test
then checks that the next upgrade is answered in under 120 ms. Before
this change, that upgrade waited 188–313 ms.

## Verification

- `cargo test -p paperclip-runner-core --lib` passes locally.
- `cargo clippy -p paperclip-runner-core --all-targets` reports no new
findings in the changed files.
- `cargo fmt --all -- --check` passes.
- New tests:
`durable::transport::tests::listener_checks_its_backlog_sooner_than_a_dial_reconnects`
and `tests/listener_accept.rs`.
- `tests/listener_accept.rs` fails on the previous `runner.rs` and
passes with this change (3 runs each).
- Existing listener and warm-attachment tests pass (`listener_*`,
`warm_run_attachment_*`, `warm_external_attachment_*`).
- I did not measure the change on a live host. The effect is visible in
the next deployment as a shorter `runner.transport.registration` on warm
attachments.

## Risks

- Low risk. Dial mode does not change.
- A disconnected listener now wakes every 10 ms instead of every 250 ms.
Each wake is one non-blocking `accept` and a non-blocking host-control
read. The loop already slept in 25 ms steps.
- Failed handshakes on a listener now back off from 10 ms (10, 20, 40 …
320 ms) instead of from 250 ms. Core's own reconnect loop still paces
its redials, and the ingress requires credentials, so this does not
create a hot loop.
- The change needs a Runner release before hosts pick it up.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, trace queries).

## 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-15 22:17:52 +00:00
..