Paperclip’s Claude adapter kept waking agents through quota and auth walls

paperclipai/paperclip issue #6499 is the inspected primary source: “Claude weekly-limit errors classified as `claude_transient_upstream` and retried → per-company spawn-queue cascade.” The related records below were inspected as supporting context rather than independent confirmation.

The facts

- paperclipai/paperclip issue #6499 was created 2026-05-21T13:09:27Z and was closed at inspection; its title is “Claude weekly-limit errors classified as `claude_transient_upstream` and retried → per-company spawn-queue cascade.” - paperclipai/paperclip issue #6391 was created 2026-05-19T21:39:15Z and was closed at inspection; its title is “claude_local: detect rate-limit on stderr, defer wakeup until reset instead of failing.” - paperclipai/paperclip PR #11073 was created 2026-08-08T00:56:19Z and was open at inspection; its title is “fix(claude-local): classify an unrefreshable OAuth session as auth required.” - The repository reported 75843 stars, 5072 open issues, default branch master, and last push 2026-08-08T00:51:03Z. - The latest tagged-release baseline checked was v2026.722.0 published 2026-07-22T23:05:41Z.

What changed

paperclipai/paperclip issue #6499 reports: Summary When the Claude subscription account hits its **weekly usage limit** (Pro/Max plans only — the Anthropic API has no weekly cap), every claude_local heartbeat run fails fast with Claude run failed: subtype=success: You've hit your weekly limit · resets, ( ). Paperclip classifies this as error_code='claude_transient_upstream' and **retries**, which is wrong: the limit is a hard wall until the named reset (typically multiple days away). The retry flood then saturates the per-company concurrency pool, runs accumulate in running status without process_pid, the 15-minute spawn watchdog reaps them as spawn_watchdog_timeout, and agents flip to status='error'. The fleet is effectively down until a manual recovery (DB cleanup + systemctl restart paperclip.service + agent revival). Real-world incident (2026-05-21) One production fleet, ~17 active agents: | Time (ET) | Event | |---|---| | 00:04 | First claude_transient_upstream failure with weekly limit text | | 00:04–11:03 | 574 retries, all fast-failing with the same weekly-limit error | |

paperclipai/paperclip issue #6391 reports: Summary When the Anthropic claude CLI hits a rate limit during a heartbeat run, the failure currently surfaces as a generic failed wakeup and status='error' on the agent — same error path as a real adapter crash. Wachter Intelligence saw 26 wakeups fail simultaneously at 13:15-13:17 UTC and 4 agents flip to status='error' because of a single Anthropic rate-limit window. They had nothing wrong with them except the bad timing of the limit hit. Proposal: detect the rate-limit signal in @paperclipai/adapter-claude-local, return a new deferred outcome (or an errorCode: "rate_limited" with retryAt), and have the wakeup-retry path requeue the wakeup at the reset time instead of marking it failed. Detection signal The Claude CLI prints the limit message to stderr (and sometimes to the result stream JSON) in the form Claude AI usage limit reached| or You've hit your limit. Try again at In packages/adapters/claude-local/src/server/execute.ts the buildResult helper (~L519) already has proc.stderr and the parsed

paperclipai/paperclip PR #11073 reports: Thinking Path - Paperclip is the open source app people use to manage AI agents for work - Agent runs go through adapters; claude-local shells out to the Claude CLI and classifies each run's outcome into an errorCode so the host can react (retry, wait for quota, prompt a login) - When the CLI's OAuth session dies it prints Failed to authenticate: OAuth session expired and could not be refreshed, which matches none of the auth, quota, or transient patterns - The run therefore lands with no classification at all and fails hard, so the host never surfaces the login path and just keeps waking the agent - Measured over one host's full run-log corpus this was the single largest failure bucket — 2811 of 8179 failed runs, across all 11 agents, in one continuous ~79h window - This pull request teaches CLAUDE_AUTH_REQUIRED_RE that wording, anchored to the CLI's whole failure sentence - The benefit

Why it matters

Error taxonomy controls fleet behavior. Mislabel a multi-day quota wall or dead shared credential as transient and the recovery loop becomes the outage, consuming queue slots until healthy agents appear broken. The operator test is whether the visible result, retained state and authority still describe the same event after retries, background work or restart.

Current

The primary record was closed when captured on 2026-08-08. The release baseline was v2026.722.0 published 2026-07-22T23:05:41Z. Repository metadata, source bodies, pull requests, issues, releases, Google News, Hacker News, Lobsters, Metamesh and the rendered ClawCharts row were inspected. ClawCharts selected the subject; it did not prove the claim.

Evidence

The primary URL is https://github.com/paperclipai/paperclip/issues/6499. Supporting records are https://github.com/paperclipai/paperclip/issues/6391 and https://github.com/paperclipai/paperclip/pull/11073. Source bodies, timestamps and states are preserved in the daily evidence bundle. Test counts and reproductions remain attributed to their authors unless identified as independently rerun.

Source boundary

Open work is described as open, closed work as closed, and operator reports as reports. A pull request is evidence of proposed or reviewed direction, not proof of a shipped release. Search residue, package mirrors and historically published source spines were excluded.

Operator take

Classify quota and auth separately, carry reset or login actions as structured state, pause affected accounts, and prove unrelated companies continue to schedule. Preserve a before-state receipt, make the smallest reversible change, and verify the original failure independently.

Caveat

Public project records are mutable. Status, scope and evidence can change after publication. This brief records the inspected state and does not authorize changes to a reader’s deployment.

Source inspected; source state, environment and release boundary remain explicit.