fix(core): honor a RetryInfo delay of zero when classifying quota errors - #29532

Summary

classifyGoogleError() discarded a server-supplied RetryInfo delay of zero,
so a routine rate limit that the server said to retry immediately was
misclassified as a terminal quota error. That aborted retries and fired the
terminal quota / model-fallback / credits flow instead of simply retrying. This
changes two truthiness checks into comparisons against the documented sentinel
values.

Details

Root cause

parseDurationInSeconds() in packages/core/src/utils/googleQuotaErrors.ts
documents null as its "cannot parse" sentinel and returns a number otherwise,
so "0s" and "0ms" parse to 0. But classifyGoogleError() guarded the
result with a truthiness check:

const parsedDelay = parseDurationInSeconds(retryInfo.retryDelay);
if (parsedDelay) {          // 0 is falsy
  delaySeconds = parsedDelay;
}

A delay of zero — "retry immediately" — was therefore thrown away and
delaySeconds stayed undefined, indistinguishable from a malformed duration.
Two call sites downstream then took the wrong branch:

1. Cloud Code RATE_LIMIT_EXCEEDED explicitly returns a TerminalQuotaError
   when delaySeconds === undefined, so a routine rate limit became terminal.
2. The generic RetryInfo path was guarded by
   retryInfo?.retryDelay && delaySeconds, so a zero delay skipped the
   retryable branch and fell through to the generic tail, losing the
   Suggested retry after ... message and the delay.

The sibling Please retry in X fallback in the same function already compares
against the documented sentinel (if (retryDelaySeconds !== null)), so this was
an internal inconsistency rather than intended behaviour.

Fix

Compare against the documented sentinels at both sites: parsedDelay !== null
when reading RetryInfo, and delaySeconds !== undefined at the RetryInfo
classification branch. Two lines plus a comment; no other behaviour changes.

Unparsable durations still leave delaySeconds undefined and keep their current
behaviour (Cloud Code RATE_LIMIT_EXCEEDED with a garbage duration stays
terminal), and the 5-minute terminal threshold is untouched.

Note on the resulting delay: RetryableQuotaError's constructor maps a 0 s
delay to retryDelayMs === undefined, so retryWithBackoff uses its normal
exponential backoff rather than retrying with no pause. The behavioural change
is purely in the classification — terminal to retryable — which is the point; it
deliberately does not introduce a zero-delay hot retry loop.

Related Issues

Fixes #29049.

How to Validate

From the repository root:

# The directly affected suite
npx vitest run src/utils/googleQuotaErrors.test.ts --root packages/core

# Plus the consumers that branch on TerminalQuotaError vs RetryableQuotaError
npx vitest run src/utils/googleQuotaErrors.test.ts src/utils/retry.test.ts \
  src/utils/googleErrors.test.ts --root packages/core

What actually ran here (node v24.20.0, vitest 3.2.4, macOS):

• googleQuotaErrors.test.ts — 52 tests, all pass.
• googleQuotaErrors.test.ts + retry.test.ts + googleErrors.test.ts —
  3 files, 118 tests, all pass.
• prettier --check, eslint, and tsc --noEmit -p packages/core are clean on
  the changed files.

Four cases were added to googleQuotaErrors.test.ts: Cloud Code
RATE_LIMIT_EXCEEDED with retryDelay: "0s" and with "0ms" (both now
RetryableQuotaError), a bare RetryInfo with "0s" (now
RetryableQuotaError carrying Suggested retry after 0s.), and a guard case
asserting that an unparsable duration still yields a TerminalQuotaError with
reason RATE_LIMIT_EXCEEDED.

To confirm the first three are genuine regression tests, revert only the source
file and re-run:

git stash push -- packages/core/src/utils/googleQuotaErrors.ts   # keep the tests
npx vitest run src/utils/googleQuotaErrors.test.ts --root packages/core
git stash pop

They fail on unmodified main with
expected TerminalQuotaError: Rate limit exceeded to be an instance of RetryableQuotaError
and
expected 'Too many requests' to be 'Too many requests\nSuggested retry after 0s.'.
The fourth (unparsable duration) passes on both sides by design — it is a guard
against over-correction, not a regression test.

Not run: the full npm run preflight and the integration test suites.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed) — n/a, no
  user-facing surface change beyond the corrected error classification
• Added/updated tests (if needed)
• Noted breaking changes (if any) — none
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

Left unchecked deliberately: this is a pure classification-logic change inside
packages/core, exercised by the unit tests above on macOS. It was not
validated by driving the CLI end-to-end on each platform/method, so I have not
claimed those boxes.

🤖 Generated with Claude Code