Usage-limit rescue is scrape-only and unreliable; the `StopFailure` hook already fires for usage limits (`error: "rate_limit"`) but is only wired to the overload path

[shaunmower]

Summary

The usage-limit path (waiting state, hours-scale reset) depends entirely on screen-scraping the banner out of the pane tail. The session-limit banner is emitted by Claude Code as an inline, one-shot isApiErrorMessage turn in response to a submission — it is not a persistently-redrawn banner — so whether any 5s poll happens to catch it is a coin-flip. When the poll loses that race, detection never fires, the tool never sends, the banner is never re-emitted, and the session sits idle until the user returns manually.

Meanwhile the StopFailure hook already fires for usage limits with error: "rate_limit" and carries the session_id — a reliable, timestamped, non-scraping signal that is currently only used to drive the overload (seconds-scale backoff) path, never the wait-until-reset path.

Proposed fix: treat a rate_limit StopFailure marker as a first-class usage-limit trigger — read the reset time from that session's transcript (via the session_id the marker already carries), enter the existing waiting state until the reset, then send the retry. This removes the scrape from the critical path for usage limits entirely.

Relationship to #38

This overlaps #38 (the fixed RATE_LIMIT_TAIL_LINES = 12 window) but is more fundamental, not a duplicate. #38 makes the scrape miss less often by widening the window. The event-driven path proposed here removes the scrape from the usage-limit critical path entirely, so the banner's on-screen position stops mattering at all — it can't be pushed out of a window that's no longer consulted. In that sense this supersedes #38 for usage-limit detection when the hook is installed.

#38 still stands on its own, because the scrape doesn't go away completely: it remains for the /rate-limit-options menu detection (isRateLimitOptionsPrompt / menuStepsToWaitOption), overload detection, and as the fallback when the hook isn't installed. So the two are complementary — this issue makes usage-limit detection reliable via the event channel; #38 hardens the scrape that's still needed elsewhere.

Evidence (two concurrent sessions, same account-wide limit, v0.5.1)

Two panes (%0, %32) hit the same session limit within ~3 minutes. Both fired the StopFailure hook — the markers, straight off disk:

// events/_0.json
{ "pane": "%0",  "error": "rate_limit", "session_id": "…", "ts": … }   // written 10:33:57
// events/_32.json
{ "pane": "%32", "error": "rate_limit", "session_id": "…", "ts": … }   // written 10:36:27

error: "rate_limit" confirms a usage/session limit raises StopFailure and passes isRetryableError() (events.js). The banner text lives in each session's transcript:

You've hit your session limit · resets 12:10pm (Australia/Melbourne)

Outcome:

• %0 recovered — but via the scraping path getting lucky (log shows Rate limit detected … → menu select → wait → Sent retry message (attempt 1) → User already continued). Its hook marker was never consumed (still on disk).
• %32 did not recover — its monitor (confirmed alive throughout) logged nothing but its startup line, sent nothing, and the session sat idle from 10:36 until manual resume ~2h later. Its hook marker was also never consumed.

So the hook fired for both panes and rescued neither; the one recovery came from a scrape that happened to win the race. On a prior night the same setup lost the race on the interactive pane and idled for 9 hours.

The two code-level gaps

1. Hook markers for usage limits are effectively ignored. readEvent is only reached in the monitoring branch (processOneTick, monitor.js ~L295–311). A marker written while the monitor is in waiting (or outside the eventMaxAgeSeconds window) is never consumed and goes stale on disk — which is what happened to both markers above.
2. Even when consumed, a hook event is routed to the wrong machine. The readEvent branch sets status = 'overload' and schedules nextOverloadWaitMs (seconds), then relies on a subsequent scrape (isRateLimited, monitor.js ~L196/L220) to hand off to enterUsageWait. It never parses the reset time from the event, so a rate_limit event backs off in seconds against a limit that resets in hours.

Proposed fix (sketch)

• In the monitoring (and waiting) handling, check for a rate_limit StopFailure marker before the overload routing.
• On such a marker, resolve the transcript path from session_id (~/.claude/projects/<cwd-slug>/<session_id>.jsonl), read the most recent isApiErrorMessage text, and feed it through the existing parseResetTime / calculateWaitMs → enter waiting until the reset, then the existing retry send.
• Keep the scrape as a fallback for cases where the hook isn't installed.

This reuses the entire existing wait-and-retry mechanism; the change is only the trigger (reliable event instead of scrape) and the reset-time source (transcript instead of on-screen banner).

Environment

• claude-auto-retry v0.5.1 (global npm install)
• Claude Code 2.1.205
• macOS (Apple Silicon), tmux, zsh
• StopFailure hook installed via claude-auto-retry install-hook

Happy to open a PR (with tests) if the approach looks right.

[shaunmower]

Following up, because after reading src/events.js on main I realise this issue lands directly on a deliberate, documented design decision — so let me address that premise head-on rather than talk past it.

The current design rests on this (src/events.js, on the RETRYABLE set):

rate_limit is deliberately EXCLUDED. ... Session/usage limits are owned by the scraper usage path (it reliably reads the persistent "…resets <time>" banner and waits).

The load-bearing word is persistent. The whole rationale for excluding rate_limit from the event path is that the scraper can be trusted to read the banner off the pane. That premise doesn't hold, and I think it's the actual root cause here.

The limit notice is not a persistent banner — it's an inline, edge-triggered turn

Claude Code records the session-limit notice in its own transcript (~/.claude/projects/<slug>/<session-id>.jsonl) as an isApiErrorMessage assistant turn, emitted once, in direct response to a blocked submission. It is not a status line that gets continuously redrawn at the prompt. Two consecutive turns from one real incident, each paired with the submit that triggered it:

user      12:08:18Z  "…continue check it when…"
assistant 12:08:19Z  isApiErrorMessage: "You've hit your session limit · resets 2:10am (Australia/Melbourne)"
user      12:08:45Z  "Sent at 22:08 Melbourne time"
assistant 12:08:46Z  isApiErrorMessage: "You've hit your session limit · resets 2:10am (Australia/Melbourne)"

After 12:08:46 there is nothing in that transcript for ~9 hours. Nobody submitted, so the notice was never re-emitted. Whether a 5s capture-pane poll sees it therefore depends entirely on landing in the brief window it's on screen — it's a race, not a reliable read.

Live proof it's a race: two panes, same limit, one rescued, one stranded

Two concurrent sessions hit the same account-wide limit within ~3 minutes. Both raised a StopFailure with error: "rate_limit" (markers written by the shipped 0.5.1 hook, straight off disk):

{ "pane": "%0",  "error": "rate_limit", "session_id": "…", "ts": … }
{ "pane": "%32", "error": "rate_limit", "session_id": "…", "ts": … }

Outcome:

• %0 — the scraper happened to catch the banner and recovered (Rate limit detected … → wait → Sent retry message → User already continued).
• %32 — same limit, same banner text, but the scraper never caught it. Its monitor (confirmed alive throughout) logged only its startup line and sent nothing; the session sat idle until manual resume ~2h later.
• Both hook markers were left unconsumed on disk.

So the event fired for both panes and rescued neither; the one recovery came from a scraper poll winning the race. On an earlier night the same setup lost the race on the interactive pane and idled for 9 hours. That's the failure this issue is about, and it's not "the scraper is a bit flaky" — it's structurally a poll against a transient signal, while the reliable signal (the rate_limit event) is currently discarded.

Why this doesn't reintroduce the problem you correctly avoided

Your comment is right that routing rate_limit into the overload seconds-backoff path was wrong — it fired futile "Continue" retries into a limited pane. The fix here is not that. It's to route a rate_limit event into the existing hours-scale usage-wait path, taking the reset time from the transcript the marker already points at (session_id → JSONL → the isApiErrorMessage text → parseResetTime). No scraping in the critical path, no seconds-scale retries, and a built-in disambiguation: if the transcript's latest error carries no reset time (a genuinely transient 429, "temporarily limiting requests"), it falls through to today's behaviour. Session limits get the hours-scale wait; transient 429s don't.

Net: the event channel becomes the authoritative usage-limit trigger, the scraper stays as the fallback for when the hook isn't installed (and #38 still hardens that fallback). Happy to put this up as a PR with tests if the approach looks right to you.

[cheapestinference]

Excellent write-up — the analysis holds, and the two-session evidence (both markers on disk, neither consumed) is exactly the failure. A PR would be very welcome; a few things confirmed from the code so you're set up cleanly:

The marker already carries session_id. writeStopFailureEvent persists { pane, error, session_id, ts } (src/events.js), so the transcript lookup you propose has what it needs — no hook/plumbing change required, just consuming it.

The two gaps, precisely:

1. readEvent is only reached on a monitoring tick, so a rate_limit marker written while the monitor is in waiting (or older than eventMaxAgeSeconds) is never consumed — both your markers went stale this way. A usage-limit trigger needs to be checked in monitoring before the overload routing.
2. rate_limit is deliberately excluded from RETRYABLE (src/events.js) because routing it to the overload (seconds-scale) path made it fire futile Continue retries against an hours-scale limit. Your proposal routes it to the usage-wait path instead, which is the right home — so this is a new, correct route, not re-enabling the old bad one.

Design guidance for the PR:

• Add a distinct classifier (e.g. isUsageLimitError('rate_limit')) rather than folding rate_limit back into RETRYABLE — keep the overload and usage routes separate.
• On a rate_limit marker: resolve the reset time, enterUsageWait, then the existing wait-and-retry runs unchanged. For the reset time, prefer a scrape of the current pane at marker time first (the banner is freshest the instant the limit fires) and fall back to the transcript read via session_id — that way the feature degrades gracefully if the transcript format isn't what's expected.
• Transcript path: the project dir is the cwd with non-alphanumerics mapped to - (verified locally: /home/ubuntu/claude-auto-retry → ~/.claude/projects/-home-ubuntu-claude-auto-retry/, /home/u/.claude → -home-u--claude), then <session_id>.jsonl. Please guard this behind a try/catch + fallback and pin it with a fixture — it's a Claude Code internal that can shift between versions, so it shouldn't be on the critical path without a graceful degrade.
• Keep the scrape as the no-hook fallback (and it's still needed for the /rate-limit-options menu + overload regardless).

Complementary work already merged: #38 widened the scrape capture (120 lines) so the banner behind a tall widget is caught, and the overload scraper stays live for transient 429s — both reduce (not remove) the coin-flip you describe. Your event-driven trigger is the real fix for the usage-limit case; happy to review the PR closely.