feat: auto-resume workflows after a provider usage limit resets (closes #27)

[QuintinShaw]

Closes #27.

What

A run that pauses on a provider usage/quota limit (the #26 behavior) now auto-resumes once the quota is likely to have refilled — instead of sitting paused until someone manually runs /workflows resume. Exponential backoff + a hard attempt cap keep it from bouncing off a still-exhausted budget forever.

Design: standalone scheduler

src/usage-limit-scheduler.ts — a UsageLimitScheduler that consumes only the manager's public surface (on/off, listAllRuns, resume, getPersistence). No logic added inside WorkflowManager/executeRun/recoverStaleRuns. This keeps the footprint against the pending #74 manager/persistence rewrite minimal — the only edits to existing files are two additive PersistedRunState fields, ExecOptions.autoResume, and wiring.

Event-driven "fire and watch": arm a timer on a usage_limit pause; when it fires, call resume(); then step back and let the existing paused/complete/error/stopped subscriptions drive backoff and cleanup. An attempt is consumed only when a run enters a usage_limit pause — never when a resume merely fires — so a resume() returning false (lease busy, already gone) doesn't burn an attempt.

Default-on with per-run opt-out

Eligible unless ExecOptions.autoResume === false (persisted, so a cold start respects it). Tunables: attempt cap 5, delay floor 1m, ceiling 6h, resetHint-unparseable fallback 5m.

resetHint & cold start

resetHint is a verbatim human string ("Resets in ~3h") and not guaranteed present — parsed best-effort (~3h, 1h30m, in 5m, missing → fallback). Cold-start re-arm reschedules a still-paused run using time remaining (now − updatedAt), not a fresh full delay.

Tests

tests/usage-limit-scheduler.test.ts — 26 tests using an injectable fake clock/timer that fires callbacks synchronously, so the timer-fire path is genuinely exercised (normal fire, backoff-on-repause, attempt-cap give-up, cold-start remaining-time, opt-out skip, resetHint parsing, delay floor, resume()→false not consuming an attempt). 887 unit tests pass; tsc + biome clean.

Honest notes

• Test boundary: true end-to-end validation needs a real provider usage limit to fire, which isn't reproducible on demand. Reliability here rests on the fake-clock unit tests covering every branch (which the prior attempt lacked) plus the existing real-session pause/resume integration test.
• autoResumeAttempts persistence is best-effort: the scheduler writes it, and the manager's persistRun() would overwrite it while a run is executing — but that only matters for a process crash in the brief window between a resume and the next persist. While paused (when a cold start actually reads it) the value is stable, and the live in-memory counter is always authoritative. Fails safe toward more retries, not fewer.
• feat: make workflow runs observable and resumable #74 overlap: if feat: make workflow runs observable and resumable #74 lands, its migrateRunState() will need to pass through the two new PersistedRunState fields.