## TL;DR
Do not busy-wait and do not restart from scratch. Persist the queue with a completed-item watermark, sleep until the reset timestamp from the rate limit headers, then resume exactly where the agent stopped. The queue drains on its own after the window rolls over.

## Verbatim error
```text
rate limit resets in 47 minutes: agent's review queue stuck mid-run
```

## Steps

1. Read the reset time from the API instead of guessing. Call the rate limit endpoint or read `X-RateLimit-Reset` from the last 403; it is a Unix timestamp. Compute sleep seconds as reset minus now, plus a 60-second safety margin.
   Expected: you have an exact wake-up time, not a vague "about an hour".

2. Persist the queue state now, before sleeping. Write the list of pending items and the id of the last completed item to a state file (JSON is fine).
   Expected: the state file on disk lists every unprocessed item, so a crash during the wait loses nothing.

3. Sleep until the reset time, then verify the budget recovered with one cheap call to the rate limit endpoint.
   Expected: `remaining` shows a fresh quota before the agent resumes real work.

4. Resume from the watermark: skip items marked completed, process the rest, and update the watermark after each item.
   Expected: the queue drains to empty with no item processed twice and none skipped.

## Use this when
- An agent must wait out a GitHub rate limit reset with work remaining.
- You need a resume-from-watermark pattern for an agent queue.
- A review queue stalls mid-run and must not lose its place.

## Not for this skill when
- The wait is caused by the secondary / abuse limit (that clears in a minute or so with backoff, not at the hourly reset).
- The queue is stuck for a non-rate-limit reason like a crash loop (fix the crash, the wait will not help).
- The reset is far away and the work is urgent (then reduce scope or add a second token rather than waiting).

## Variant phrasings
- GitHub rate limit reset wait resume agent queue
- agent paused waiting for rate limit reset how to resume
- review queue stuck on rate limit reset timer

## Why it happens
Hourly quotas are fixed windows: once the budget is spent, every call fails until the window rolls over. Agents that keep no progress state face a cruel choice when this hits mid-queue: wait blindly and hope, or restart and redo hours of work. A persisted watermark turns the reset from a disaster into a scheduled pause.

## Edge cases
- The agent process may get killed during a long sleep (deploys, spot instances). The state file is the real resume mechanism; the sleep is just politeness. Design for the process dying.
- Clock skew: if the machine clock is off, the computed sleep can be short. The 60-second margin plus a verification call covers it.
- Do not spend the fresh budget re-checking completed items. The first calls after reset should be the next unprocessed item, verified by the watermark.
- If resets keep hitting every hour, the queue is bigger than the budget. Shrink per-item call cost (see the call-reduction skills) instead of waiting every hour forever.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7ok4q4suBbo6kWcBxLGkGg