fix: retry a polling 429 only when Retry-After says when to come back (sable-96ex)

[Rome-1]

Closes sable-96ex, raised by the adversarial review of #220 and deliberately not changed there.

The problem

All three surfaces treated an HTTP 429 during polling as fatal, and CLI_SPEC.md enshrined it: "Other 4xx (401/403/429 …) — Not retried". Polling every 10 seconds from every customer repo is exactly the traffic shape a rate limiter targets. The first limiter in front of GET /api/static/scan would fail every customer build instantly, on a condition one sleep would have resolved — and there is no limiter there today, which is precisely why nobody will be looking at the CLI on the day one lands.

A 429 cannot simply join 408/5xx either. On scan submit a 429 means the account is out of credits (EXIT_QUOTA_EXHAUSTED, exit 3), and the CLI cannot tell "out of credits" from "going too fast" — same status code. Retrying a quota rejection for 30 seconds and then failing anyway is worse than failing now.

The rule

Retry-After is the disambiguator: a rate limiter sends one, a quota rejection does not. So:

Condition	Behavior
429 with a usable Retry-After, during polling	Transient. Sleep min(Retry-After, 60s), then retry.
429 without one, during polling	Not retried — fail fast, as today.
429 on scan submit	Unchanged: exit 3, even when it carries the header.

The asymmetry with submit is the point, so both runtimes now pin it with a test rather than leaving it to be "made consistent" later.

Three details that make honoring a server-supplied delay safe:

• Delay-seconds only. The HTTP-date form is not parsed in any of the three surfaces, because the composite action has to reach the same verdict in shell on whatever date the runner ships — a rule the surfaces cannot state identically is worse than a narrow one they can. An unparseable header counts as absent, which means fail fast: the conservative direction.
• Capped at 60s, and the retry still spends a failure from the same budget (5 consecutive / 20 total), so an endlessly-throttling API cannot keep the loop alive. In bash the cap is on length as well as value: [ 1e23 -gt 60 ] is a shell error that evaluates false, so an uncapped 23-digit header would reach sleep intact and hang the job until the runner times out. (sleep 99999999999999999999999 does not return — checked.)
• Never past the deadline. Raising the longest honored delay from 16s to a server-named 60s put it in reach of overrunning timeout-minutes, which sable-l10k had just turned from a poll count into a real wall clock. The honored delay is clamped to what is left of the deadline too. Measured with timeout-minutes: 1 and Retry-After: 60 injected forever: the loop sleeps 50s and the step ends at 60s exactly; without the clamp it ends at 70s.
• Giving up on repeated 429s says we were rate limited, not that the report could not be read. Sending a throttled customer to look at their scan — or at a rafter get that will be throttled too — costs them the entire diagnosis. New action status value rate-limited, alongside unreadable.

Coverage

Every guard was mutation-verified: deleted or inverted one at a time, confirming a named test goes red.

• 20 Node + 18 Python unit tests (parsing, the sleep schedule rather than "it slept", the cap, fail-fast on bare and on malformed headers, budget exhaustion, the give-up wording, and the submit-side asymmetry).
• 5 new drift-detector checks over action.yml — the Retry-After gate in both loops, the digit and length validation, the cap, and the rate-limited status. Each one fails when its guard is removed.
• 3 new e2e jobs against the mock backend: poll rides out a 429 with Retry-After; poll fails fast on a bare one and is asserted to have polled exactly twice (the assertion that catches a "simplification" making every 429 transient); results fetch rides one out. No API key, no credits.

The bash halves were driven end-to-end locally against the mock before this landed — ride-out, fail-fast, malformed header, absurd header, budget exhaustion — each behaving as documented.

Security review

Reviewed with the rafter agent (local secrets tier + the rafter-code-review checklist; rafter run needs an API key this box does not have). Three findings, all fixed in 5ef4ca5:

1. medium — Python accepted a digit int() cannot parse. str.isdigit() is Unicode-aware and int() is not: '²' passes the first and raises ValueError out of the second, from a call site whose only handler is requests.RequestException. One raw \xb2 byte is enough — http.client decodes headers as ISO-8859-1 — so a server could crash the client. Also a three-surface divergence, since Node's /^\d+$/ and the action's case *[!0-9]* both reject it. Now an explicit re.fullmatch(r"[0-9]+").
2. low — the action could read a Retry-After the 429 never sent. curl -D dumps every header block it received, so a 103 Early Hints block carrying the header was read as the final response's own, and a bare 429 got retried — the one thing the gate exists to prevent. Reproduced with real curl. Both loops now scope the extraction to the last header block.
3. low — the length cap had only a grep-over-the-file for coverage. It has an e2e job now: a 23-digit Retry-After injected forever under a 1-minute budget must end at the deadline with status=timeout, which a hung step cannot produce.

The review also suggested a malformed-value ('soon') e2e job. Deliberately not added: at the artifact level a rejected 'soon' and an accepted one are both a failed run with two polls — the difference lives only in the step log, which a later step cannot read. That job would pass with the digit guard deleted, which is the vacuous check sable-d2x2 is about. The digit guard is pinned by drift check 16 and by unit tests in both runtimes instead.

Checked and clean in the review: injection (no unquoted or arithmetic use, no eval), DoS bounds, workflow-command forgery, tmpfile handling on every path, and prototype pollution in retryAfterMs (fuzzed with 20 hostile header shapes).

Known limitation

The HTTP-date form of Retry-After is treated as absent, so a limiter that sends Retry-After: Wed, 21 Oct 2026 07:28:00 GMT still fails the build fast. Filed as a follow-up; the fix is only worth taking with a portable date parse for the shell surface.