diff --git a/devlog/_plan/260828_quota_reset_detection/000_plan.md b/devlog/_plan/260828_quota_reset_detection/000_plan.md
new file mode 100644
index 0000000000..ce77bd0420
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/000_plan.md
@@ -0,0 +1,160 @@
+# Quota reset detection and notification
+
+Unit: `260828_quota_reset_detection`
+Branch: `codex/quota-reset-detection` (target `dev`)
+Class: C4 (new subsystem, config surface, background timer, outbound network sink)
+
+## Objective
+
+When a usage window resets, opencodex should notice and say so exactly once.
+
+Two reset shapes matter and they are not the same event:
+
+- **scheduled** — the window's own clock ran out. The previous snapshot carried a
+  `resetAt` in the future, wall-clock passed it, and the next snapshot reports a
+  lower used-percent. This is the weekly/5-hour rollover an operator can already predict.
+- **surprise** — used-percent drops while the previous `resetAt` is *still in the
+  future*, or `resetAt` jumps forward before its own deadline. Upstream moved the window
+  out of band. Nobody can predict this one, which is exactly why it needs a signal.
+
+The deliverable is detection plus a default-OFF notification sink, not a routing change.
+
+## Constraints
+
+- Bun-native TypeScript, strict `tsc`. No Node-only APIs.
+- `src/router.ts`, `src/server/lifecycle.ts`, `src/server/responses/core.ts` must not
+  gain a transitive `src/lab/` import (`tests/core-lab-boundary.test.ts`). The new
+  subsystem is itself optional and must not become a second core-path passenger.
+- Notification default OFF. A user with no reset config runs no timer and invokes no sink.
+- Event payloads carry closed-union labels and numbers only. No account ids, no emails,
+  no tokens, no paths. `bun run privacy:scan` scans *repository files*, not runtime
+  output, so payload privacy is a design obligation the scanner cannot enforce.
+- `src/codex/reset-credit-recovery.ts` owns credit *consumption* and stays untouched.
+  A deliberate credit redemption is not a surprise reset.
+
+## Current state (verified 260828)
+
+Detection is absent. `rg -ni 'resetdetect|quotareset|reset-event|resetEvent' src` returns
+three hits, all inside `function quotaResetAt(...)` in `src/providers/quota.ts:1646` — a
+DTO field reader. Notification is absent: `rg -n 'webhook' src scripts docs-site/src`
+returns zero matches.
+
+What does exist, and what the design leans on:
+
+| Fact | Location |
+|---|---|
+| Codex per-account windows (`weeklyResetAt`, `shortResetAt`, `monthlyResetAt`, `resetCredits`) | `src/codex/quota.ts:7` |
+| The one writer holding both prev and next in scope | `src/codex/quota.ts:274` (`const existing = accountQuota.get(accountId)`) |
+| Commit points that snapshot becomes durable through | `src/codex/quota.ts:289`, `:336` |
+| Disk snapshot, version 1, 6-hour read-side age limit | `src/codex/quota.ts:40`, `:41`, `:485` |
+| Provider-side windows (`fiveHourResetAt` etc.) | `src/providers/quota.ts:93` |
+| Provider-level snapshot commit — the ONLY place a newer report displaces an older one | `src/providers/quota.ts:2343`, with `previous` in scope at `:2290` |
+| Provider per-account cache replacement sites | `src/providers/quota.ts:1585`, `:1592`, `:1603` |
+| Provider quota has NO background refresh — one caller, request-driven | `src/server/management/provider-routes.ts:421` |
+| Reset-sentinel normalization (`0`/negative are not clocks) | `src/providers/quota.ts:279` |
+| Opt-in background job pattern (unref'd timer, gate in the callee) | `src/storage/policy-scheduler.ts:13`, `src/storage/policy-job.ts:445` |
+| Bounded ring + snapshot accessor for a read route | `src/server/memory-watchdog.ts:48` |
+| Optional-subsystem teardown registry | `src/lib/optional-shutdown-hooks.ts:32` |
+| Strict optional config section template | `src/config.ts:843`, `:898`, `:2058`, `:2179` |
+| SSRF policy for an operator-supplied URL | `src/lib/destination-policy.ts:377` |
+
+## Four traps the design has to survive
+
+These are the reasons a naive "percent went down, fire" detector is wrong here.
+
+1. **Credits-only writes rewrite `updatedAt` with byte-identical windows.**
+   `src/codex/quota.ts:276` (`creditsOnly`) copies every window field from `existing`
+   and changes only `resetCredits`. Keying on `updatedAt` fires on nothing.
+2. **Writers never hydrate from disk.** `hydrateAccountQuotasFromDisk` is called by the
+   three readers only (`src/codex/quota.ts:511`, `:516`, `:542`). A cold-start write can
+   see `existing === undefined` while a valid snapshot sits on disk. Treating absent-prev
+   as a reset invents an event on every restart.
+3. **Rows get deleted for reasons that are not resets.** Reauth clears the row on purpose
+   (`src/codex/auth-api.ts:2019`), reconciliation drops non-live accounts
+   (`src/codex/quota.ts:540`), and account purge clears it
+   (`src/codex/account-lifecycle.ts:39`). Delete-then-readd looks like 0% arriving fresh.
+4. **Header writes are partial snapshots.** `src/server/responses/core.ts:3793` writes on
+   every pooled response and may omit the burst tuple entirely; the merge at
+   `src/codex/quota.ts:323` carries forward what the payload lacks. A detector must diff
+   the *committed* snapshot, not the incoming payload.
+
+5. **Provider reports are keyed by provider, not by account.** `clearProviderQuotaCache()` plus
+   an account switch makes the next `anthropic` report a *different account's* usage — lower
+   percent, different `resetAt`. That is an identity change, not a reset. Events must be keyed
+   by `(provider, account, window)`.
+6. **Provider quota is never refreshed on its own.** `fetchProviderQuotaReports` has exactly
+   one caller — the `/api/provider-quotas` route. With no dashboard open and no CLI call, no
+   two consecutive snapshots exist, so a reset passes unobserved indefinitely. The opt-in
+   poller in wp3 is therefore load-bearing, not a nicety.
+7. **Two `normalizeResetAt` implementations disagree.** `src/providers/quota.ts:279` treats
+   `<= 0` as a sentinel and scales seconds to ms; `src/codex/quota.ts:192` admits `0` and
+   does no scaling. The detector normalizes at its own boundary rather than trusting either.
+
+Consequence: absent-prev is never a reset, identity is `(scope, account, window)`, and window
+values — not the write timestamp — decide whether anything happened.
+
+Observation cadence is also bounded by design: the provider cache TTL is 5 minutes
+(`src/providers/quota.ts:37`) and the per-account TTL is 10 (`:1425`), so a reset instant can
+only ever be bracketed between two observations, never timestamped exactly. Events carry
+`detectedAt` and the observed `resetAt`, and never claim to know when the reset occurred.
+
+## Detection contract
+
+```
+observe(scope, windowLabel, prev, next, now) -> ResetEvent | null
+```
+
+`kind: "scheduled"` requires `prev.resetAt !== undefined && now >= prev.resetAt` and
+a percent drop. `kind: "surprise"` requires a material percent drop (>= 5 points, so
+rounding noise cannot trip it) while `prev.resetAt` is still ahead of `now`, or
+`next.resetAt` advancing past `prev.resetAt` before that deadline. Every other
+transition, including any missing `prev`, returns `null`.
+
+Idempotence key: `scope | windowLabel | resetAtBucket`. Persisted, because "exactly once"
+has to hold across a restart, and the whole point of a surprise reset is that it happens
+while nobody is watching.
+
+## Work-phase map (dependency-ordered)
+
+Locked at the close of the wp1 docs cycle. Files named here are the authoritative
+deliverable list; a later cycle amends its own doc rather than reinterpreting this table.
+
+| Phase | Doc | Delivers | New files | Depends on |
+|---|---|---|---|---|
+| wp1 | `000`, `001`, `010`–`040` | roadmap, contract, 7 traps, audit response | 6 docs | — |
+| wp2 amendment | `002_wp2_audit_response.md` | the 9-blocker A-gate response | 1 doc | wp1 |
+| wp2 | `010_phase2_detection_core.md` | pure detector + durable claim store | `src/quota/reset-detector.ts`, `src/quota/reset-seen-store.ts`, 2 test files | wp1 |
+| wp3 | `020_phase3_observation_wiring.md` | codex + provider seams, opt-in poller | `src/quota/reset-observer.ts`, `src/quota/reset-poller.ts`, 1 test file; edits `src/codex/quota.ts`, `src/providers/quota.ts`, `src/server/background-lifecycle.ts` | wp2 |
+| wp4 | `030_phase4_sinks_and_surface.md` | config section, sinks, event ring, API + CLI | `src/quota/reset-notify-config.ts`, `src/quota/reset-sinks.ts`, `src/server/management/quota-reset-routes.ts`, 1 test file; edits `src/types/config.ts`, `src/config.ts` (schema, register, write-validate, warn ×3, `validFileConfigDiagnostics`), `src/cli/config-command.ts` (redact `webhookUrl`), `src/server/management-api.ts`, `src/cli/provider-runtime.ts`, `src/cli/registry.ts` | wp3 |
+| wp5 | `040_phase5_hardening_delivery.md` | boundary guard, full gates, docs, evidence, PR | `tests/quota-reset-core-boundary.test.ts`, `050_activation_evidence.md`, `060_closeout.md`; edits 3 docs-site pages | wp4 |
+
+Ordering is structural: nothing can be wired before the contract exists, no sink can fire
+before something detects, and delivery proves the whole chain. Each phase closes with
+something independently verifiable.
+
+## Out of scope
+
+Routing/failover reaction to a reset; automatic credit consumption; GUI work beyond what
+an operator needs to read the event log; any credential or OAuth change; `src/lab/`.
+
+## Verifiers (run, not assumed)
+
+| Command | Exit | Observes this change? |
+|---|---|---|
+| `bun x tsc --noEmit` | 0 on baseline 295860825 | Yes — `tsconfig.json` includes `src/**/*.ts` |
+| `bun test tests/<file>.test.ts` | 0 (8 pass on `codex-quota-parser-parity`) | Yes — names the new test file directly |
+| `bun run test` | full suite | Yes |
+| `bun run privacy:scan` | 0 | Repository text only — NOT runtime payloads |
+| `bun test tests/core-lab-boundary.test.ts` | 0 | Yes — walks the runtime import graph |
+| `bun test tests/quota-reset-core-boundary.test.ts` | added in wp5 | Yes — the existing Lab guard hardcodes `/src/lab/` (`tests/core-lab-boundary.test.ts:63`) and cannot see `src/quota/` |
+
+`bun install` was required first: a fresh worktree fails with
+`Cannot find module 'zod/v4'` and every focused run reports a spurious single error.
+
+## Bypass ledger
+
+The default-OFF guarantee is enforced by a test (E7-class), not by anything unbypassable.
+Executing surface: `bun run test`. Known bypass: a contributor who wires the sink into a
+path the test does not observe. Residual risk: a future caller invoking the sink directly
+rather than through the gate. Final enforcement layer: none — the boundary is the test plus
+review. Wording is deliberately "early warning", not "enforcement".
diff --git a/devlog/_plan/260828_quota_reset_detection/001_audit_response.md b/devlog/_plan/260828_quota_reset_detection/001_audit_response.md
new file mode 100644
index 0000000000..d050774ddf
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/001_audit_response.md
@@ -0,0 +1,93 @@
+# A-phase audit response
+
+Two dispatched grok-4.6 auditors did not return: the first errored with
+`Selected model is at capacity`, the second went silent through three bounded wait cycles
+and was retired under DISPATCH-RETIRE-01. The audit below was performed directly against
+the tree at `c752929d7`. Stating that plainly because a claimed-but-absent reviewer is the
+one failure mode the A gate exists to catch.
+
+## Citation audit — PASS
+
+All 33 cited `path:line` claims were read back and match. Sample:
+`src/codex/quota.ts:274` is `const existing = accountQuota.get(accountId);`;
+`src/providers/quota.ts:2290` is the `previous` binding; `:2343` is the `cache = {...}`
+commit; `src/config.ts:3161` is `SALVAGEABLE_CONFIG_SECTIONS`.
+
+## Verifier reality — PASS
+
+`bun install` then `bun x tsc --noEmit` exits 0 with no output;
+`bun test tests/codex-quota-parser-parity.test.ts` reports 8 pass / 0 fail.
+`bunfig.toml` pins `[test] root = "tests"` and preloads `./tests/preload.ts`, which is why
+a bare `bun test` in a fresh worktree reports one spurious error until `bun install` runs.
+That belongs in the plan and is now recorded there.
+
+## Field chain — PASS
+
+`rg -n "agentTaskRecovery" src/ gui/src` outside `src/config.ts` returns nothing, and
+`tokenGuardian` has only its type declaration plus one comment. There is no config DTO,
+no sanitize path, and no docs generator enumerating sections, so `config.ts` +
+`types/config.ts` really is the whole chain for an optional section. No missed consumer.
+
+## Reachability — PASS with one correction
+
+- A percent DROP does land: `snapshotHasWeekly` (`src/codex/quota.ts:246`) tests
+  `weeklyPercent !== undefined`, so a lower value takes the `:294` branch and is written.
+  The merge only carries values FORWARD when the incoming snapshot omits a window.
+- The poller keeps its own commit authority. `invalidationEpoch += 1` happens at `:2285`,
+  then `const epoch = invalidationEpoch;` at `:2286` captures the bumped value, so the
+  `epoch === invalidationEpoch` check at `:2338` passes for the forced probe itself. My
+  concern that a forced refresh would lose its own commit was wrong.
+- `previous` is non-empty on a poller refresh as long as the cache key is unchanged; the
+  `:2309` comment only resets it when the provider SET changes, which is a config edit.
+
+## Blockers folded into the plan
+
+### 1. HIGH — the boundary claim was unverifiable
+
+`tests/core-lab-boundary.test.ts:63` tests `next.includes("/src/lab/")`. The guard is
+hardcoded to Lab and says nothing about `src/quota/`, so wp5's "verify by hand" was the
+only thing standing behind the claim — exactly the situation AGENTS.md describes as "this
+paragraph was the only thing holding the guarantee".
+
+Fix, folded into `040`: wp5 adds a real guard asserting no static runtime edge reaches
+`src/quota/reset-` from the four protected entrypoints, reusing the same walker.
+
+### 2. MEDIUM — `src/server/management-api.ts` is itself protected
+
+It is the fourth entry in `PROTECTED` (`tests/core-lab-boundary.test.ts:25`), added because
+eagerly importing handlers put ~70 modules on every dashboard request. The wp4 route must
+therefore be lazy for a second, independently sufficient reason. Recorded in `030`.
+
+Worth noting the walker deliberately does NOT propagate through `import()`
+(`tests/core-lab-boundary.test.ts:76`: "a deferred edge, not a load-time one"), which is
+what makes the wp3 lazy-import approach the sanctioned remedy rather than a loophole.
+
+### 3. MEDIUM — check-and-set was not atomic
+
+`hasSeenQuotaReset` followed by `markQuotaResetSeen` is two steps. Two observers racing
+the same key — a poller tick and a live pooled response — can both read false and both
+notify, defeating criterion c-4 under exactly the load that makes detection interesting.
+
+Fix, folded into `010`: replace both with one synchronous claim.
+
+### 4. MEDIUM — 30-day pruning could evict a live key
+
+A monthly window's key can legitimately be older than 30 days while still current, so
+pruning by age alone can drop it and permit a duplicate notification.
+
+Fix, folded into `010`: never prune a key whose `resetAt` is still in the future, and
+raise the age floor to 90 days.
+
+## Residuals accepted, not fixed
+
+- `sweepExpiredProviderAccountQuotaRows` (`src/providers/quota.ts:1485`) has no caller and
+  no registration. Wiring it would add a fourth silent row-removal path with the same
+  misread-as-reset hazard. Out of scope; noted for a separate unit.
+- The two divergent `normalizeResetAt` implementations stay divergent. Unifying them
+  touches every provider parser and belongs in its own unit; the detector normalizes at its
+  own boundary instead, which is already in the plan.
+- `LOCAL_MANAGEMENT_READ_PATHS` (`src/lib/local-management-capability.ts:10`) is an
+  allowlist for bound local reads used by `doctor`/`health`. The new route does not need
+  to join it; not adding it is a deliberate choice, not an oversight.
+
+VERDICT: GO-WITH-FIXES (blockers=4) — all four folded above.
diff --git a/devlog/_plan/260828_quota_reset_detection/002_wp2_audit_response.md b/devlog/_plan/260828_quota_reset_detection/002_wp2_audit_response.md
new file mode 100644
index 0000000000..9a6027164f
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/002_wp2_audit_response.md
@@ -0,0 +1,91 @@
+# wp2 A-gate audit response
+
+The retired plan auditor (grok-4.6, `audit-quota-reset-plan-2`) returned after its third
+wait cycle with `GO-WITH-FIXES (blockers=9)` — after I had already audited directly. Both
+audits are recorded; this one found things mine did not. I re-verified every blocker I acted
+on rather than taking the verdict on trust.
+
+## Blocker 1 — Critical, and correct. The provider seam could never have fired.
+
+`src/providers/quota.ts:2290` binds `previous` only when `cache.key === key`. I had read
+the `:2309` comment saying the key encodes the provider SET and stopped there. The key is
+actually built by `cacheKeyWithAggregationState` (`:193`), which folds
+`quotaSignatureValue` (`:155`) — `weeklyPercent`, `weeklyResetAt`, `monthlyResetAt`,
+`customWindows`, and `updatedAt` — into a sha256 digest appended to the key.
+
+A reset changes exactly those values, so the key rotates, so `previous` is `[]`, so the
+detector's no-prev rule returns null. On a pooled install the key rotates on every quota
+write, since `updatedAt` is in the digest.
+
+Verified by reading `:2273-2290` and `:193-217`. The wp3 seam claim was wrong: `:2343` is
+indeed the only place a newer report displaces an older one, but it displaces under a
+DIFFERENT key, which makes the displacement invisible to a cache-key-equality diff.
+
+Fix folded into `020`: provider observation no longer reads `previous` at all. The detector
+owns its own last-seen map keyed by `(provider, accountTag, window)`, which is immune to
+cache-key rotation by construction. That map is the same store wp2 already persists.
+
+## Blocker 2 — High, and correct. Fixed in this B.
+
+`src/codex/quota.ts:323-329` carries the previous burst tuple forward verbatim when a
+header write omits it. So a partial write reproduces the old deadline AND the old percent;
+once wall-clock passes that copied deadline, my "an expired clock is sufficient evidence"
+rule fired on a snapshot where upstream said nothing — on the once-per-pooled-response path.
+
+My reasoning for dropping the drop-requirement (catching low-usage rollovers) was sound; the
+conclusion was too broad. `scheduled` now requires the expired deadline PLUS corroboration:
+either usage fell, or upstream issued a new deadline. A byte-identical carried-forward window
+supplies neither. Regression test: "a carried-forward window past its deadline is NOT a
+reset".
+
+## Blocker 4 — High, and correct. Three missed consumers.
+
+My field-chain audit searched for `agentTaskRecovery` and concluded `config.ts` plus
+`types/config.ts` was the whole chain. It missed:
+
+- `validFileConfigDiagnostics` (`src/config.ts:1957`) — a diagnostics warning surface
+  SEPARATE from the three `loadConfig` branches, feeding `ocx config show --source`.
+- `SECRET_KEYS` (`src/cli/config-command.ts:18`) matches
+  `apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret`. `webhookUrl`
+  matches none of them, so a Slack or Discord webhook — whose secret IS the URL — would be
+  echoed in plaintext by `ocx config show` and written by `config export`. That is a real
+  credential-disclosure defect, not a style nit.
+- `safeConfigDTO` (`src/server/auth-cors.ts:695`) is an explicit whitelist, so the section
+  is correctly invisible to the GUI. Right outcome, undocumented.
+
+All three added to the wp4 file map in `030`, with `webhookUrl` redaction as a named
+requirement.
+
+## Blockers 3, 5, 7, 8 — accepted, folded into their phases
+
+- **3:** `loadConfig` (`src/config.ts:1805`) is a `readFileSync` plus a full
+  `safeParse` with no memoization. Calling it per pooled response to ask "is this feature
+  off" is absurd. The gate becomes generation-cached via `captureConfigGeneration`.
+- **5:** `PROTECTED` has FOUR entries and all four reach `src/codex/quota.ts` statically,
+  so the lazy-import requirement is load-bearing and nothing enforced it. wp5's guard is
+  parameterized over a target set and gets a synthetic attack case.
+- **7:** `Bun.spawn` rejects a string `stdin`; encoded bytes it is.
+- **8:** two concurrent forced refreshes make the loser skip both the commit and the notify.
+  Once observation moves off `cache.key` (blocker 1) the loser still observes, so this
+  largely dissolves — but the residual window is stated in `020` rather than hidden.
+
+## Blocker 9 — Low, correct
+
+`QUOTA_PERSIST_DEBOUNCE_MS` is at `src/codex/quota.ts:43`, not `:493` (that line is the
+function). And `000_plan.md` promised docs `010`–`050` for wp1 while `050` is a wp5
+deliverable. Both corrected.
+
+## Blocker 6 — already fixed before the verdict arrived
+
+The racy has/mark pair became one atomic `claimQuotaReset` during my own audit. The
+reviewer noticed the shipped code already says "claim".
+
+## Found by me, not the reviewer
+
+`quotaResetKey` used `resetAt ?? "none"`. For the several provider parsers that never emit
+a reset clock, every reset of one window collapsed onto a single key, so the first claim
+would have permanently suppressed all later ones. Now falls back to the expired deadline
+before "none", and a window with no deadline on either side is not evaluated at all.
+
+VERDICT ACCEPTED: GO-WITH-FIXES (blockers=9). Two fixed in wp2, seven folded forward, none
+rebutted.
diff --git a/devlog/_plan/260828_quota_reset_detection/003_wp3_audit_response.md b/devlog/_plan/260828_quota_reset_detection/003_wp3_audit_response.md
new file mode 100644
index 0000000000..8b2ce8a4ab
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/003_wp3_audit_response.md
@@ -0,0 +1,88 @@
+# wp3 A-gate audit response
+
+A third grok-4.6 reviewer (`review-wp3-observation-wiring`) went silent through four bounded
+wait cycles and was retired under DISPATCH-RETIRE-01. Two of three dispatched reviewers have
+now failed this way — one on provider capacity, two on silence — so the audits below were run
+directly. Recording that rather than implying a reviewer signed off.
+
+## 1. Does the provider seam actually fire? — PROVEN YES
+
+This is the question that killed the original design, so it gets a live probe rather than a
+reading. Two consecutive committed reports for one anthropic account, driven through the same
+calls `notifyProviderQuotaSnapshot` makes:
+
+```
+after report1 hits: 0
+after report2 hits: 1 kinds: scheduled:5h
+payload: {"kind":"scheduled","scope":"anthropic","accountTag":"1aw4hwbh","window":"5h",
+          "percentBefore":94,"percentAfter":3,"previousResetAt":...,"resetAt":...,
+          "detectedAt":...,"key":"anthropic|1aw4hwbh|5h|..."}
+after report3 hits (idempotent): 1
+```
+
+First report is a baseline and fires nothing. The second is detected. A third identical
+observation does not re-notify. The cache-key rotation that made the old design dead is now
+irrelevant, because the baseline comes from the persisted swap map rather than
+`cache.key === key`.
+
+The payload contains only closed-union labels and numbers — no account id, no email, no path.
+
+## 2. Lazy-import contract — VERIFIED
+
+`rg` for a static `import ... from ".../quota/reset-"` in `src/codex/quota.ts` and
+`src/providers/quota.ts` returns nothing; only the two dynamic `import()` calls exist
+(`src/codex/quota.ts:359`, `:362`; `src/providers/quota.ts:2281`, `:2284`). None of the
+four protected entrypoints names `quota/reset-` at all.
+
+Residual, stated rather than fixed: because the seams do not await, observation order for two
+writes in quick succession is promise-resolution order. Both compute the same idempotence key
+for the same new deadline, so the claim ledger collapses them to one notification; the only
+consequence is which one defines the baseline. wp5's guard will make the no-static-edge half
+of this enforceable instead of grep-verified.
+
+## 3. Found by me: the generation-cached enable gate was stale by construction — FIXED
+
+The wp2 audit told me to cache the enable check against `captureConfigGeneration()`, and I
+did. That was wrong, and I caught it while verifying the reviewer's fourth question myself.
+
+`configGeneration` is only assigned at `src/lib/state-store-sweeper.ts:149`, inside
+`reconcileStateGeneration`, which runs from `reconcileLiveStateStores` on account and
+provider changes. Editing `quotaResetNotify` alone never bumps it. So enabling the feature
+would have had NO effect until some unrelated account edit happened to reconcile — the exact
+"toggling enabled takes effect on the next tick" property the doc claimed.
+
+Now keyed on the config file's mtime and size, with a 5-second TTL bounding how often the hot
+path stats. A config edit is picked up within 5 seconds; a quiet install pays one `statSync`
+per 5 seconds rather than a full `safeParse` per request.
+
+Worth naming the pattern: a cache key that does not actually change when the cached input
+changes is worse than no cache, because it converts a performance concern into a correctness
+bug that only shows up as "the feature does nothing".
+
+## 4. Detector regressions since the last review — checked for missed REAL resets
+
+The tightened rules could in principle suppress a genuine reset. Cases checked:
+
+- rolling 5h window that genuinely resets: usage falls, so the drop carries it. Fires.
+- weekly window at 0% on both sides past its deadline: no drop, but upstream issues a new
+  deadline, so the corroboration branch fires.
+- account that resets while completely unused with NO new deadline: returns null. This is a
+  deliberate false negative — the snapshot is byte-identical to a carried-forward one, and
+  there is no way to tell them apart. Recorded as a known limitation.
+- rollover immediately followed by heavy use (3% -> 24% past the deadline): returns null via
+  the rise check. Also deliberate; also recorded.
+
+## 5. Test honesty
+
+`settle()` in `tests/quota-reset-observation.test.ts` drains microtasks then waits 5 ms,
+which is a race in principle. It is load-bearing only for the two seam tests, and the
+observer-contract tests call `observeQuotaSnapshot` synchronously and assert its return
+value, so the same behavior is covered without any timing dependency. If CI ever flakes here,
+the fix is to assert the synchronous return rather than to raise the sleep.
+
+Two assertions were weak and are now real: the account-tag test asserts the salt actually
+changes the tag across installs (it previously only checked length and the absence of "@",
+which any digest satisfies), and the claim-durability test now spawns a real second process
+instead of calling a test-only flush.
+
+VERDICT (direct audit): GO-WITH-FIXES (blockers=1) — the stale enable gate, fixed above.
diff --git a/devlog/_plan/260828_quota_reset_detection/004_wp3_review_response.md b/devlog/_plan/260828_quota_reset_detection/004_wp3_review_response.md
new file mode 100644
index 0000000000..2ab415ab6a
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/004_wp3_review_response.md
@@ -0,0 +1,144 @@
+# wp3 adversarial review — response
+
+Reviewer: independent subagent, dispatched against `f4fcbb547` (HEAD moved to `2e4b3be3e`
+mid-review; the reviewer noted this and verified both). Verdict: GO-WITH-FIXES, 4 blockers.
+
+Every blocker was reproduced here before being accepted, and every fix was driven red
+against the pre-fix code before being committed green. Two of the reviewer's proposed
+remedies were rejected on evidence and replaced; both are recorded below, because a review
+response that only records agreement is not evidence of independent judgement.
+
+## Blocker 1 (Critical) — out-of-order observations manufacture false resets
+
+Accepted, reproduced, fixed.
+
+The seam awaited two `import()` calls before swapping the baseline. Bun does not resolve
+concurrent dynamic imports in call order, so a burst arrives reordered. Reproduced through
+the real writer with 21 monotonically RISING writes (10% -> 90%, no reset anywhere):
+
+```
+write order: 10,14,18,...,90
+events:      [{"k":"surprise","w":"5h","pb":82,"pa":10}]   # 4/4 isolated runs
+```
+
+The compounding harm is the durable claim: the false event takes the idempotence key, so
+the genuine reset on that window is then suppressed permanently. That is what makes this a
+correctness defect rather than noise.
+
+**Fix.** Both seams now serialize observations through a module-level promise chain
+reassigned SYNCHRONOUSLY at call time (`pendingObservation = pendingObservation.then(...)`),
+so each link starts only after the previous one committed its baseline. The snapshot is also
+copied before the boundary, because `next` is the live map value and the following write
+mutates it.
+
+The reviewer's alternative — statically import `window-mapping` and observe synchronously —
+was rejected: it adds a static edge from a file that `src/server/responses/core.ts` reaches,
+and `tests/quota-reset-core-boundary.test.ts` (added this phase) forbids exactly that. The
+promise chain achieves the same ordering guarantee without spending the boundary.
+
+Evidence, pre-fix vs post-fix, isolated `OPENCODEX_HOME` per run:
+
+```
+pre-fix:  FALSE_EVENT_COUNT: 1  1  1  1
+post-fix: EVENTS: []  []  []  []
+```
+
+## Blockers 2 and 3 (High) — the account key was wrong in two ways
+
+Accepted, fixed together, because both are the same mistake: identity was resolved
+asynchronously from mutable global state, after the commit it describes.
+
+- **Key-auth pool collapse.** `getAccountSet()` reads the OAuth store, so every key in a
+  key-auth provider's `apiKeyPool` fell through to `"default"`. Rotating from a spent key to
+  a fresh one inherited the spent key's history and read as a reset.
+- **Mid-flight failover.** `promoteAnthropicActiveAccount` rewrites `activeAccountId` during
+  request routing, so a 429 between the commit and a later async read attributes this
+  report to a different account. `fetchAnthropicQuota` already captures `probedAccountId`
+  before awaiting for precisely this reason.
+
+**Fix.** `providerObservationAccountKey` resolves identity synchronously at the commit site,
+and mirrors the discriminator the report cache already uses (`apiKeyPoolEntryId`) instead of
+inventing a second notion of identity.
+
+## Blocker 4 — the trap-3 regression test was vacuous
+
+Accepted; this was the most useful finding, because the test was green and wrong.
+
+`tests/quota-reset-observation.test.ts` called `resetQuotaResetStoreForTests()` between the
+row clear and the fresh write. No production path does that: real reauth clears the quota
+row only, and the observer's baseline lives in a separate file. Removing the line:
+
+```
+REAUTH_EVENTS: [{"k":"surprise","w":"5h","pb":91,"pa":0}]
+```
+
+So reauth of a used account fired a false reset on every occurrence, and the test that
+existed to prevent it was simulating a state that never happens.
+
+**Fix.** `forgetLastObservedWindows` in the store, `forgetQuotaBaseline` in the observer
+(which owns the salted tag), called from `clearAccountQuota` on the same serialized chain so
+it cannot be overtaken by an in-flight observation. The claim ledger is deliberately NOT
+released — a cleared row must not re-notify a reset it already reported.
+
+## Finding 6 (Medium) — fixed, but NOT by the proposed remedy
+
+The finding is correct: a rolling window's percent decays naturally, and the surprise branch
+accepted a bare drop. Confirmed at 88% -> 61% one hour into a 5h window, no reset.
+
+The proposed remedy — bound the drop by `elapsed/windowLength * previousPercent` — was
+implemented, measured, and **rejected**. Decay magnitude cannot be bounded from elapsed time:
+the percent that ages out depends on WHEN the usage occurred, so an hour of idling can retire
+a burst that all landed in one minute. Measured against the proportional bound, 88% -> 5%
+one hour in (a 83-point drop) was suppressed as "explainable decay" while the genuine
+27-point decay case it was written for still fired. It was wrong in both directions.
+
+**What shipped instead:** deadline MOVEMENT against elapsed time. While a window is merely
+rolling, its deadline advances by roughly the elapsed gap; a genuine out-of-band reset issues
+a deadline a full window into the future, hours beyond a gap measured in minutes. A deadline
+that stands still while usage falls is the clearest surprise signature there is, and is
+explicitly allowed through. Fails OPEN whenever the evidence is missing.
+
+## Finding 5 (Medium) — accepted
+
+The eviction comment described behavior the code did not have: re-setting a key does not move
+it in a Map, so the EARLIEST-INSERTED row was evicted — on a real install the long-lived
+codex account, while 63 transient rows survived. Fixed with delete-then-set, making it a true
+LRU and making the existing comment true. The regression test fails against the old code.
+
+## Findings 4 and 7 — deferred to wp5, with reasons
+
+- **Finding 4 (debounce starvation).** Real: a write cadence under 250 ms defers the baseline
+  write indefinitely, so a SIGKILL loses the baseline. Not a correctness defect in the
+  detection contract (the trailing write lands once traffic quiesces, and a lost baseline
+  re-baselines rather than misfires), and the maximum-staleness cap belongs with the other
+  persistence hardening in wp5. Recorded in `040_phase5_hardening_delivery.md`.
+- **Finding 7 (`updateAccountQuota` does not notify).** Has no in-repo caller, but is public
+  API through `src/codex/auth-api.ts`. wp5 will either notify or state why not.
+
+## Reviewer claim NOT accepted
+
+`settle()` flakiness: the reviewer measured it and concluded it is sound (0.51 ms against a
+5 ms budget, 14 runs clean including under CPU load). Agreed, and the earlier plan to
+rewrite it is dropped. The burst test does not rely on it — it spawns a child process,
+because an in-process burst test PASSED against the unfixed seam: earlier tests in the file
+leave the observer module cached, and a cached import resolves in call order. Only a cold
+module registry reproduces the defect. A test that cannot fail is worth less than no test,
+so this one was driven red 3/3 in a child process before being trusted.
+
+## Boundary guard (the wp3 deliverable itself)
+
+`tests/quota-reset-core-boundary.test.ts`. `tests/core-lab-boundary.test.ts:63` hardcodes
+`/src/lab/`, so nothing enforced the same obligation for `src/quota/`. The walker was
+EXTRACTED to `tests/helpers/import-graph.ts` and shared rather than copied, because the Lab
+guard already records what a duplicated predicate costs: its own self-test re-declared a
+private copy of the matcher and so proved a local literal behaved, not that the guard did.
+
+Guards: no load-time edge from the 4 protected entrypoints into `src/quota/` (whole
+directory, not a `reset-` prefix — a prefix would let a future sibling through); both seams
+reach the observer and reach it ONLY dynamically; the composition-root exemption is pinned to
+an exact chain and the poller is asserted to pull in nothing at load time.
+
+Driven red three ways: a static import in `src/router.ts` (4 assertions fail, including the
+two files that transitively reach it), a seam converted to a static import (1 fails), and the
+observer wiring deleted entirely (the reachability assertion fails, proving the
+dynamic-only check is not vacuously satisfiable by absent wiring).
diff --git a/devlog/_plan/260828_quota_reset_detection/010_phase2_detection_core.md b/devlog/_plan/260828_quota_reset_detection/010_phase2_detection_core.md
new file mode 100644
index 0000000000..423bffb377
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/010_phase2_detection_core.md
@@ -0,0 +1,155 @@
+# wp2 — Detection core
+
+Pure detection plus the durable store that makes "exactly once" true across restarts.
+Nothing in this phase touches an existing call path; it closes with its own tests green.
+
+## NEW `src/quota/reset-detector.ts`
+
+Pure functions only: no imports from `config`, no clock of its own, no I/O. `now` is a
+parameter so tests drive time instead of waiting for it.
+
+```ts
+/** One observed usage window, normalized away from provider-specific field names. */
+export type QuotaWindowObservation = {
+  /** Closed-union window identity. Custom provider windows arrive as "custom:<label>". */
+  readonly window: string;
+  /** 0-100 used percent, already normalized. Absent when upstream stopped reporting it. */
+  readonly percent?: number;
+  /** Epoch ms. Absent when upstream declares no clock, or declared a sentinel. */
+  readonly resetAt?: number;
+};
+
+export type QuotaResetKind = "scheduled" | "surprise";
+
+export type QuotaResetEvent = {
+  readonly kind: QuotaResetKind;
+  /** "codex" or a provider name. Never an account id. */
+  readonly scope: string;
+  /** Opaque, non-identifying account discriminator (see accountTag below). */
+  readonly accountTag: string;
+  readonly window: string;
+  readonly percentBefore?: number;
+  readonly percentAfter?: number;
+  readonly previousResetAt?: number;
+  readonly resetAt?: number;
+  /** When WE noticed. Deliberately not "when the reset happened" — see 000_plan.md. */
+  readonly detectedAt: number;
+  /** Idempotence key: scope|accountTag|window|resetAtBucket. */
+  readonly key: string;
+};
+
+/**
+ * A drop smaller than this is rounding noise or a same-window correction, not a reset.
+ * 5 points is deliberately coarse: upstream percents are integers and a genuine window
+ * rollover drops by tens of points, so nothing real sits under this floor.
+ */
+export const MIN_SURPRISE_DROP_PERCENT = 5;
+
+export function detectQuotaReset(input: {
+  readonly scope: string;
+  readonly accountTag: string;
+  readonly previous: QuotaWindowObservation | undefined;
+  readonly next: QuotaWindowObservation;
+  readonly now: number;
+}): QuotaResetEvent | null;
+```
+
+### Decision order (first match wins, and no-prev short-circuits before everything)
+
+1. `previous === undefined` -> `null`. A first observation is a baseline. This single line is
+   what stops trap 2 (writers do not hydrate), trap 3 (delete-then-readd), and trap 5
+   (account switch) from manufacturing events.
+2. Window identity differs -> `null` (caller error; defensive).
+3. `previous.resetAt !== undefined && now >= previous.resetAt` and the percent did not
+   rise -> `"scheduled"`. The window's own clock expired. A drop is not required: a window
+   that rolls over while unused legitimately reports the same low percent, and the expired
+   deadline is the evidence.
+4. `previous.resetAt` still in the future, and either
+   (a) `percentBefore - percentAfter >= MIN_SURPRISE_DROP_PERCENT`, or
+   (b) `next.resetAt > previous.resetAt`
+   -> `"surprise"`. Upstream moved the window before its own deadline.
+5. Anything else -> `null`. Includes usage rising, sub-threshold noise, an unchanged
+   snapshot, and a percent that vanished (upstream stopped reporting the window).
+
+`resetAtBucket` is `String(next.resetAt ?? "none")`. Keying on the NEW deadline is what
+makes repeated observation of the same post-reset state idempotent: every later poll of the
+same window computes the same key.
+
+### `accountTag`
+
+Events must not carry account identity (privacy), yet must distinguish accounts (trap 5).
+A short non-reversible digest of the account key serves both: stable within a process
+lifetime and across restarts, meaningless outside. Derived with `Bun.hash` rendered as
+base36, truncated to 8 chars. Not a secret and not reversible to an email.
+
+## NEW `src/quota/reset-seen-store.ts`
+
+```ts
+/**
+ * Atomically claim a reset key. Returns true for the FIRST caller only.
+ *
+ * One synchronous check-and-set, not a separate has/mark pair: a poller tick and a live
+ * pooled response can observe the same transition concurrently, and two callers that both
+ * read "unseen" would both notify. Synchronous because Bun runs one JS turn at a time, so
+ * a function with no await inside is indivisible with respect to other observers.
+ */
+export function claimQuotaReset(key: string, at: number): boolean;
+/** Read-only probe for tests and the operator surface. Never used to gate a notification. */
+export function hasSeenQuotaReset(key: string): boolean;
+/** Ring of recent events for the operator surface (wp4). Newest last. */
+export function recordQuotaResetEvent(event: QuotaResetEvent): void;
+export function listRecentQuotaResetEvents(limit?: number): QuotaResetEvent[];
+export function resetQuotaResetStoreForTests(): void;
+```
+
+Persistence: `join(getConfigDir(), "quota-reset-state.json")`, version 1, written with
+`atomicWriteFile` (mode 0600) under the same 250 ms trailing debounce as the codex quota
+cache (`QUOTA_PERSIST_DEBOUNCE_MS` at `src/codex/quota.ts:43`; the scheduler itself is at
+`:493`). Deliberately NOT `config.json`: this is high-frequency
+job state, and `mutatePersistedConfig` fails closed when config came from anywhere but a
+file. Hydration is lazy-once, mirroring `src/codex/quota.ts:473`, and a corrupt or
+version-mismatched file is discarded rather than throwing — a broken cache must never break
+quota refresh.
+
+Bounds: 512 seen keys and 100 ring events, both FIFO. Pruning is age-based (90 days) and
+skips any key whose `resetAt` is still in the future. A monthly window's key can
+legitimately be older than a month while remaining current, so pruning on age alone would
+drop a live key and let the same reset notify twice — which is the one thing this store
+exists to prevent. The stored value is therefore `{ at, resetAt }`, not a bare timestamp.
+
+When the 512-key bound is hit, eviction takes the oldest key whose `resetAt` has passed;
+if every key is live the store refuses to grow and logs nothing. Silently evicting a live
+key to honour a bound would trade a memory limit for a correctness bug.
+
+## NEW `tests/quota-reset-detector.test.ts`
+
+Drives the detector directly with fixture snapshots and a fixed `now`:
+
+- scheduled rollover: prev 96% resetAt T, now T+1min, next 2% -> `kind === "scheduled"`
+- scheduled with no drop: prev 3% resetAt T, now T+1min, next 3% -> `"scheduled"`
+- surprise drop: prev 96% resetAt T+2h, now T, next 4% -> `kind === "surprise"`
+- surprise deadline jump: prev resetAt T+2h, next resetAt T+9h, percent flat -> `"surprise"`
+- usage increase 40% -> 65% -> `null`
+- rounding noise 61% -> 58% inside an unexpired window -> `null` (below the 5-point floor)
+- `previous === undefined` at 0% -> `null` (cold start / reauth / account switch)
+- vanished percent -> `null`
+- identical key for two observations of the same post-reset window
+- `accountTag` differs for two account keys, and contains no "@"
+
+## NEW `tests/quota-reset-seen-store.test.ts`
+
+- `claimQuotaReset` returns true once and false on every repeat for the same key
+- two claims interleaved without an await between them yield exactly one true
+- a fresh hydration (store reset + reload from the same `OPENCODEX_HOME`) still reports
+  the key seen — the restart proof for criterion c-4
+- a corrupt file hydrates to empty without throwing
+- ring keeps the newest 100 and drops the oldest
+- a key older than 90 days whose `resetAt` has passed is pruned
+- a key older than 90 days whose `resetAt` is still in the future is KEPT
+
+## Accept criteria
+
+`bun test tests/quota-reset-detector.test.ts tests/quota-reset-seen-store.test.ts` exits 0,
+`bun x tsc --noEmit` exits 0, and no file outside `src/quota/` and `tests/` changed.
+Activation evidence for wp2 is the scheduled and surprise assertions naming the returned
+`kind` — the fired-path artifact C-ACTIVATION-GROUNDING-01 requires.
diff --git a/devlog/_plan/260828_quota_reset_detection/020_phase3_observation_wiring.md b/devlog/_plan/260828_quota_reset_detection/020_phase3_observation_wiring.md
new file mode 100644
index 0000000000..b795b474be
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/020_phase3_observation_wiring.md
@@ -0,0 +1,219 @@
+# wp3 — Observation wiring
+
+Feed the wp2 detector real snapshots from both quota subsystems, and add the opt-in poller
+that makes idle detection possible at all.
+
+## Why a poller is required, not optional
+
+`fetchProviderQuotaReports` has exactly one caller — the `/api/provider-quotas` route at
+`src/server/management/provider-routes.ts:421`. With no dashboard open and no CLI call,
+that function never runs, so no second snapshot ever exists. Passive observation alone
+cannot detect a reset that happens overnight, which is precisely the case the user cares
+about. The poller is default-OFF; when off, this phase degrades to passive-only.
+
+## NEW `src/quota/reset-observer.ts`
+
+The one place that turns a (prev, next) pair into a delivered notification. Core-owned
+entry point so the seams below stay one-line calls.
+
+```ts
+/**
+ * Observe one committed snapshot transition. Never throws: a detection or delivery
+ * failure must not break the quota write that triggered it.
+ */
+export function observeQuotaSnapshot(input: {
+  readonly scope: string;
+  readonly accountKey: string;
+  readonly previous: ReadonlyArray<QuotaWindowObservation>;
+  readonly next: ReadonlyArray<QuotaWindowObservation>;
+  readonly now?: number;
+}): void;
+```
+
+Body: bail immediately when the feature is off, then swap in the new windows via
+`swapLastObservedWindows`, call `detectQuotaResets` against the returned prior value,
+`claimQuotaReset` each event's key, and for each winner `recordQuotaResetEvent` plus hand to
+the sink. Everything wrapped in `try/catch` at the top level, matching the fail-safe posture
+of `src/server/memory-watchdog.ts:127`.
+
+**The enable check must be generation-cached (audit blocker 3).** `loadConfig`
+(`src/config.ts:1805`) is a `readFileSync` plus a full `configSchema.safeParse` with no
+memoization, and this observer runs once per pooled response. Calling it there merely to ask
+"is this feature off" would put a config parse on the hot path for a feature nobody enabled.
+`isQuotaResetNotificationEnabled()` therefore caches its resolution against
+`captureConfigGeneration()` — already imported by `src/codex/quota.ts` — so a config edit
+still takes effect without a restart.
+
+Order matters: the key is CLAIMED before dispatch, via the single synchronous
+`claimQuotaReset` from wp2. A sink that fails must not cause a re-notification storm on the
+next poll; delivery failure is recorded on the event (wp4) rather than retried by
+re-detecting. Claiming atomically also closes the concurrency window where a poller tick and
+a live pooled response observe the same transition in the same second.
+
+## MODIFY `src/codex/quota.ts`
+
+Two commit points, both already holding `existing` and `next`.
+
+Before (`:335`):
+```ts
+  accountQuota.set(accountId, next);
+  schedulePersistAccountQuotas();
+}
+```
+After:
+```ts
+  accountQuota.set(accountId, next);
+  schedulePersistAccountQuotas();
+  notifyCodexQuotaSnapshot(accountId, existing, next);
+}
+```
+
+The credits-only commit at `:289` gets NO call. Trap 1: that branch copies every window
+field from `existing` verbatim and changes only `resetCredits`, so there is by construction
+no window transition to detect. Skipping it is cheaper and more honest than detecting
+nothing.
+
+NEW local helper in the same file, keeping the module's import surface unchanged at the top
+level by using a lazy import — `src/codex/quota.ts` is reachable from
+`src/server/responses/core.ts`, so a static import of the observer would pull the whole
+notification subsystem onto the core request path and defeat the default-OFF guarantee:
+
+```ts
+/**
+ * Hand a committed transition to the optional reset observer.
+ *
+ * Lazy import on purpose: this file sits on the hot pooled-response path via
+ * applyAccountQuotaFromUpstreamHeaders, and a static import would load the observer,
+ * its config read, and its sink registry into every install — the same mistake
+ * tests/core-lab-boundary.test.ts exists to prevent for src/lab/.
+ */
+function notifyCodexQuotaSnapshot(
+  accountId: string,
+  previous: StoredAccountQuota | undefined,
+  next: StoredAccountQuota,
+): void {
+  if (previous === undefined) return;
+  void import("../quota/reset-observer")
+    .then(m => m.observeQuotaSnapshot({
+      scope: "codex",
+      accountKey: accountId,
+      previous: codexWindowObservations(previous),
+      next: codexWindowObservations(next),
+    }))
+    .catch(() => {
+      // Detection is best-effort; a quota write must never fail because of it.
+    });
+}
+```
+
+`codexWindowObservations(quota)` maps `StoredAccountQuota` to the neutral shape:
+`shortPercent/shortResetAt` -> `"5h"`, `weeklyPercent/weeklyResetAt` -> `"weekly"`,
+`monthlyPercent/monthlyResetAt` -> `"monthly"`, each `customWindows[]` entry ->
+`"custom:<label>"`. Windows absent from the snapshot are omitted, not zero-filled.
+
+## MODIFY `src/providers/quota.ts`
+
+**Amended after the wp2 audit (blocker 1, Critical).** The original design diffed against
+`previous` at `:2290`. That can never work: `previous` is bound only when
+`cache.key === key`, and `cacheKeyWithAggregationState` (`:193`) folds
+`quotaSignatureValue` (`:155`) — including `weeklyResetAt`, `monthlyResetAt` and
+`updatedAt` — into a digest appended to the key. A reset changes exactly those values, so
+the key rotates, `previous` is empty, and the no-prev rule returns null on every install
+with a Codex pool provider. The seam would have been dead on arrival.
+
+The detector therefore owns its own last-seen map instead of borrowing the report cache.
+`src/quota/reset-seen-store.ts` gains:
+
+```ts
+/** Last observed windows for one (scope, accountTag): returns the prior value, then stores. */
+export function swapLastObservedWindows(
+  scope: string,
+  accountTag: string,
+  windows: ReadonlyArray<QuotaWindowObservation>,
+): ReadonlyArray<QuotaWindowObservation> | undefined;
+```
+
+Persisted in the same version-1 file, bounded to 64 rows. A restart keeps its "before" side,
+which the report cache never could — it is process-memory only, with no `writeFile`
+anywhere in `src/providers/quota.ts`.
+
+### Residual: the dropped-observation window (audit blocker 8)
+
+Two concurrent forced refreshes — a poller tick racing a dashboard `refresh=1` — make the
+loser fail the `epoch === invalidationEpoch` check at `:2338` and skip its commit. With
+observation moved off `cache.key` the loser still observes through the swap map, so the
+transition is not lost; whichever probe swaps first defines the baseline, and both compute
+the same idempotence key for the same new deadline, so the claim store collapses them to one
+notification. Stated rather than hidden.
+
+### The seam itself
+
+Before (`:2337`):
+```ts
+      const reports = response.reports.filter(item => mayCommitProviderQuotaKey(item.provider, writerGeneration));
+      cache = { key, ts: Date.now(), response: { ...response, reports } };
+```
+After:
+```ts
+      const reports = response.reports.filter(item => mayCommitProviderQuotaKey(item.provider, writerGeneration));
+      cache = { key, ts: Date.now(), response: { ...response, reports } };
+      notifyProviderQuotaSnapshot(reports);
+```
+
+Commit first, observe second: the cache write is the source of truth and must not be delayed
+by observation. No `previous` is passed — the observer swaps against its own last-seen map.
+
+`notifyProviderQuotaSnapshot` mirrors the codex helper (lazy import, per-provider windows,
+`accountKey` = the provider's active-account id so a switch cannot inherit another
+account's history). Providers absent from `reports` are skipped WITHOUT clearing their
+last-seen row: trap 3 and the terminal-failure deletion at `:2330` remove rows for reasons
+that are not resets, and forgetting the baseline would turn the next reappearance into a
+false event.
+
+## NEW `src/quota/reset-poller.ts`
+
+Follows the repo's canonical opt-in job shape: `src/storage/policy-scheduler.ts:13` for the
+timer, `src/storage/policy-job.ts:445` for gating in the callee rather than the timer.
+
+```ts
+export function startQuotaResetPoller(intervalMs?: number): void;
+export function stopQuotaResetPoller(): void;
+```
+
+- Idempotent: `if (timer) return;`
+- `timer.unref?.()` so it never keeps the process alive — the rule
+  `src/storage/policy-scheduler.ts:3` states and every loop in this repo follows
+- Each tick re-reads config and returns immediately when disabled, so toggling `enabled`
+  takes effect without a restart (the rationale spelled out at
+  `src/oauth/token-guardian.ts:276`)
+- Default interval 15 minutes, floored at 60 s. Above the 5-minute provider TTL and the
+  10-minute account TTL, so a tick costs at most one upstream probe per window.
+- Tick calls `fetchProviderQuotaReports(loadConfig(), true)`; the forced probe is what
+  produces a second snapshot. Failures are swallowed.
+- Registers teardown via `registerOptionalShutdownHook("quota-reset-poller", stop)`
+  (`src/lib/optional-shutdown-hooks.ts:32`) at start, so a process that never enables it
+  registers nothing.
+
+Started from `src/server/background-lifecycle.ts:54` alongside
+`startStorageCleanupScheduler()`, inside the existing try/rollback block. That file is not
+one of the three core-boundary-protected entrypoints.
+
+## NEW `tests/quota-reset-observation.test.ts`
+
+- a codex weekly rollover driven through `setAccountQuotaFromParsed` twice fires exactly
+  one event, with the fake sink capturing `kind === "scheduled"`
+- a surprise drop driven the same way fires `kind === "surprise"`
+- the credits-only path (`{ resetCredits: 3 }` only) fires nothing despite a new
+  `updatedAt` — trap 1 regression
+- a first-ever snapshot fires nothing — trap 2 regression
+- `clearAccountQuota` then a fresh low-percent write fires nothing — trap 3 regression
+- a provider report whose provider disappears from the new report fires nothing
+- with the feature disabled, the sink is never invoked and no timer exists
+- poller: `startQuotaResetPoller` twice creates one timer; `stopQuotaResetPoller` clears it
+
+## Accept criteria
+
+`bun test tests/quota-reset-observation.test.ts` exits 0; the wp2 suites stay green;
+`bun test tests/core-lab-boundary.test.ts` exits 0; `bun x tsc --noEmit` exits 0.
+Activation evidence: the captured-sink assertions naming `scheduled` and `surprise` through
+the REAL writer, not the detector in isolation.
diff --git a/devlog/_plan/260828_quota_reset_detection/030_phase4_sinks_and_surface.md b/devlog/_plan/260828_quota_reset_detection/030_phase4_sinks_and_surface.md
new file mode 100644
index 0000000000..67df431bdb
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/030_phase4_sinks_and_surface.md
@@ -0,0 +1,204 @@
+# wp4 — Notification sinks and operator surface
+
+The config section, the sinks that actually fire the token, and the surfaces an operator
+reads. Everything here is inert until config says otherwise.
+
+## MODIFY `src/types/config.ts`
+
+Add to `OcxConfig` (near the other optional feature sections, before `corsAllowOrigins`):
+
+```ts
+  /** Quota-reset detection and notification. Off by default; see OcxQuotaResetNotifyConfig. */
+  quotaResetNotify?: OcxQuotaResetNotifyConfig;
+```
+
+And the shape:
+
+```ts
+export interface OcxQuotaResetNotifyConfig {
+  /** Global kill-switch. Default false — nothing detects, nothing polls, nothing fires. */
+  enabled?: boolean;
+  /** Which reset kinds to notify on. Default both. */
+  kinds?: Array<"scheduled" | "surprise">;
+  /** Poll interval seconds for idle detection. Default 900. Min 60. 0 disables polling. */
+  pollSeconds?: number;
+  /** POST a JSON event here. Must resolve public unless allowPrivateNetwork. */
+  webhookUrl?: string;
+  /** Allow a loopback/private webhook target (self-hosted receivers). Default false. */
+  allowPrivateNetwork?: boolean;
+  /** Webhook timeout ms. Default 5000. */
+  timeoutMs?: number;
+  /** Run a local command with the event as JSON on stdin. */
+  command?: string[];
+}
+```
+
+## MODIFY `src/config.ts`
+
+Follow the `agentTaskRecovery` template exactly — it is the only optional section wired
+through all four places, and skipping any one of them produces a section that silently
+vanishes or a write path that accepts garbage.
+
+1. Schema beside `agentTaskRecoverySchema` (`:843`):
+```ts
+const quotaResetNotifySchema = z.object({
+  enabled: z.boolean().optional(),
+  kinds: z.array(z.enum(["scheduled", "surprise"])).optional(),
+  pollSeconds: z.number().int().min(0).optional(),
+  webhookUrl: z.string().url().optional(),
+  allowPrivateNetwork: z.boolean().optional(),
+  timeoutMs: z.number().int().positive().optional(),
+  command: z.array(z.string()).optional(),
+}).strict();
+```
+2. Register in `configSchema` beside `:898`, with the same rationale comment:
+```ts
+  // Invalid optional notify config must not discard unrelated provider/account state.
+  quotaResetNotify: quotaResetNotifySchema.optional().catch(undefined),
+```
+3. `quotaResetNotifyError(value)` modeled on `:2058`, added to the
+   `validateConfigCandidate` chain at `:2179`.
+4. `warnDegradedQuotaResetNotify(parsed)` modeled on `:1675`, called in ALL THREE
+   `loadConfig` success branches (`:1832`, `:1856`, `:1876`). A new section is not in
+   `SALVAGEABLE_CONFIG_SECTIONS` (`:3161`), so `.catch(undefined)` plus this warning is the
+   whole degradation story — worth stating rather than discovering later.
+5. **`validFileConfigDiagnostics` (`:1957`) — added after the wp2 audit (blocker 4).**
+   A diagnostics surface SEPARATE from the three load branches, feeding
+   `ocx config show --source`. `agentTaskRecovery` appears in both (`:1975` and `:1832`);
+   registering only the load branch leaves the CLI silent about a degraded section.
+
+### Two more consumers the first chain audit missed (blocker 4)
+
+- **`webhookUrl` MUST be redacted.** `SECRET_KEYS` at `src/cli/config-command.ts:18`
+  matches `apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret` —
+  `webhookUrl` matches none. For Slack and Discord the URL *is* the credential, so
+  `ocx config show` would print it and `config export` (`:190`) would write it to disk.
+  Add `webhookUrl` to that pattern; a redaction test comes with it.
+- **`safeConfigDTO` (`src/server/auth-cors.ts:695`) is an explicit whitelist**, so
+  `quotaResetNotify` is correctly invisible to `GET /api/config`. That is the intended
+  outcome, recorded here so a later GUI toggle reads it as a deliberate omission rather than
+  an oversight.
+
+`getDefaultConfig()` is NOT touched: it carries no optional-feature keys, deliberately.
+Absent means off.
+
+## NEW `src/quota/reset-notify-config.ts`
+
+```ts
+export type ResolvedQuotaResetNotify = {
+  readonly enabled: boolean;
+  readonly kinds: ReadonlySet<QuotaResetKind>;
+  readonly pollMs: number;
+  readonly webhookUrl?: string;
+  readonly allowPrivateNetwork: boolean;
+  readonly timeoutMs: number;
+  readonly command?: readonly string[];
+};
+
+export function resolveQuotaResetNotify(raw: unknown): ResolvedQuotaResetNotify;
+export function isQuotaResetNotificationEnabled(): boolean;
+```
+
+Read-time normalization with clamping, the `token-guardian.ts:77` `resolved()` pattern.
+`enabled` is only true when explicitly `true` AND at least one sink is configured — an
+enabled subsystem with nowhere to send is a misconfiguration, and treating it as off keeps
+the "no sink invoked" guarantee honest. `pollSeconds: 0` means passive-only.
+
+## NEW `src/quota/reset-sinks.ts`
+
+```ts
+export type QuotaResetDeliveryResult = {
+  readonly sink: "webhook" | "command";
+  readonly ok: boolean;
+  /** Closed-union failure reason. Never an upstream body or a URL. */
+  readonly reason?: "blocked-destination" | "timeout" | "http-error" | "spawn-failed";
+};
+
+export async function deliverQuotaResetEvent(
+  event: QuotaResetEvent,
+  config: ResolvedQuotaResetNotify,
+): Promise<QuotaResetDeliveryResult[]>;
+```
+
+Webhook: `assertUrlResolvesPublic(url)` from `src/lib/destination-policy.ts:377` unless
+`allowPrivateNetwork` — an operator-supplied URL is an SSRF surface and this repo already
+has the policy for it. Then `fetch` with `signalWithTimeout(timeoutMs)` from
+`src/lib/abort.ts:101` plus its `cleanup()`, `POST`, `application/json`, body =
+`JSON.stringify(event)`, response body cancelled via `cancelResponseBodyBestEffort`.
+No retry: a reset notification is only interesting while it is fresh, and the mark-seen
+ordering in wp3 already forbids re-delivery.
+
+Command: `Bun.spawn` with the event JSON on stdin as ENCODED BYTES —
+`stdin: new TextEncoder().encode(json)`. A plain string throws `ERR_INVALID_ARG_TYPE` on
+Bun 1.4.0 (audit blocker 7), and every existing call site in this repo uses `"ignore"` or
+`"inherit"` (`src/oauth/kiro.ts:98`, `src/codex/user-identity.ts:128`), so there is no
+in-repo precedent to copy. The argv form is used deliberately: the command is NOT shell
+interpreted, so an operator-supplied string cannot become an injection surface.
+
+Both sinks are independently try/caught, so one failing never suppresses the other, and
+neither ever throws to the caller (criterion c-6).
+
+### Payload — the privacy contract
+
+```json
+{
+  "type": "quota_reset",
+  "kind": "surprise",
+  "scope": "codex",
+  "accountTag": "k3f9x2ab",
+  "window": "weekly",
+  "percentBefore": 96,
+  "percentAfter": 4,
+  "previousResetAt": 1772000000000,
+  "resetAt": 1772400000000,
+  "detectedAt": 1771900000000
+}
+```
+
+Closed-union labels and numbers only. No email, no account id, no token, no path, no URL.
+`bun run privacy:scan` cannot verify this — it scans repository text, not runtime output
+(`scripts/privacy-scan.ts:227`) — so the type is the enforcement, exactly as
+`src/server/management/system-routes.ts:126` argues for its own key union.
+
+## NEW management route
+
+`GET /api/quota-resets` in a new `src/server/management/quota-reset-routes.ts`, prefix-guarded
+like `request-history-routes.ts:47`, chained into `src/server/management-api.ts:220` with a
+lazy import mirroring `handleLabRoutesOnDemand` (`:121`).
+
+The lazy import is mandatory, not stylistic. `src/server/management-api.ts` is the FOURTH
+entry in the protected set at `tests/core-lab-boundary.test.ts:25`, added precisely because
+eagerly importing handlers there put ~70 modules on every dashboard request. A static import
+would make this subsystem the next instance of that bug, and the boundary walker
+deliberately does not follow `import()` edges (`tests/core-lab-boundary.test.ts:76`), so
+lazy loading is the sanctioned remedy rather than a way around the guard.
+Returns `{ enabled, events: QuotaResetEvent[] }` via `jsonResponse`. Auth is inherited from
+`requireManagementAuth` at `src/server/index.ts:1016` — a GET route adds no auth code of
+its own, and this one spends no user identity.
+
+## NEW CLI subcommand
+
+`ocx provider resets [--limit N] [--json]`, added to the `provider-runtime.ts:179` handler
+map and `src/cli/registry.ts` usage text. Renders one line per event —
+NOT via `summaryLines`, which is a depth-1 flattener that collapsed a whole report to
+"N item(s)" in #2565 (`src/cli/provider-runtime.ts:118`).
+
+## NEW `tests/quota-reset-notify.test.ts`
+
+- absent config -> `isQuotaResetNotificationEnabled() === false`; enabled with no sink -> false
+- `kinds: ["surprise"]` drops a scheduled event and keeps a surprise one
+- webhook sink receives exactly one POST whose parsed body has no `@`, no `/Users/`, and no
+  `accountId` key
+- a throwing webhook returns `ok: false` with a closed-union reason and does not reject
+- a blocked private destination is refused with `"blocked-destination"` unless
+  `allowPrivateNetwork`
+- a webhook failure does not prevent the command sink from running
+- invalid `quotaResetNotify` in config leaves `providers` intact (the `.catch(undefined)`
+  guarantee) and the write path rejects it
+- `GET /api/quota-resets` returns recorded events and requires management auth
+
+## Accept criteria
+
+All wp2-wp4 suites green, `bun x tsc --noEmit` 0, `bun run privacy:scan` 0,
+`bun test tests/core-lab-boundary.test.ts` 0. Activation evidence: the captured webhook
+body from a fired surprise event.
diff --git a/devlog/_plan/260828_quota_reset_detection/040_phase5_hardening_delivery.md b/devlog/_plan/260828_quota_reset_detection/040_phase5_hardening_delivery.md
new file mode 100644
index 0000000000..7102217202
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/040_phase5_hardening_delivery.md
@@ -0,0 +1,105 @@
+# wp5 — Hardening and delivery
+
+Prove the whole chain against the real tree, document the user-facing surface, and open the
+PR. No new behavior here; anything that turns up gets fixed, not extended.
+
+## Full gates
+
+```
+bun install                                   # required in a fresh worktree
+bun x tsc --noEmit                            # must exit 0
+bun run test                                  # full suite
+bun run privacy:scan                          # must exit 0
+bun test tests/core-lab-boundary.test.ts      # boundary, run explicitly as well
+```
+
+Baseline recorded in wp1: `bun x tsc --noEmit` exits 0 at `295860825` with no output. A new
+failure is therefore ours, not inherited. If `bun run test` shows failures, each one is
+either fixed or proven pre-existing by re-running it on the merge-base — a remembered
+"that was already broken" is not evidence.
+
+## Boundary audit
+
+`tests/core-lab-boundary.test.ts` hardcodes `src/lab/` (`:63`,
+`next.includes("/src/lab/")`) across four protected entrypoints — `src/router.ts`,
+`src/server/lifecycle.ts`, `src/server/responses/core.ts`, `src/server/management-api.ts`.
+It says nothing about `src/quota/`.
+
+So a hand-run `rg` would be the only thing behind our boundary claim, which is the
+situation AGENTS.md calls out: "this paragraph was the only thing holding the guarantee."
+wp5 therefore ADDS a real guard, `tests/quota-reset-core-boundary.test.ts`, reusing the same
+walker shape:
+
+- the walker is parameterized over a TARGET SET, not a single hardcoded string, so it checks
+  both `/src/lab/` and `/src/quota/reset-` from the four protected entrypoints. Audit
+  blocker 5 confirmed all four reach `src/codex/quota.ts` statically (for example
+  `core.ts -> codex/auth-context.ts -> codex/quota.ts`) and three reach
+  `src/providers/quota.ts` (`core.ts -> oauth/anthropic-routing.ts -> providers/quota.ts`),
+  so the lazy-import requirement is load-bearing rather than precautionary
+- `src/codex/quota.ts` and `src/providers/quota.ts` name the observer ONLY through
+  `import(` — a static import in either is a failure, since both are reachable from
+  `src/server/responses/core.ts`
+- driven red once before landing, by temporarily adding a static import, so it is not
+  vacuous
+
+The walker does not propagate through `import()` by design
+(`tests/core-lab-boundary.test.ts:76`: "a deferred edge, not a load-time one"), which is why
+the wp3 lazy imports are the sanctioned remedy and not an evasion. A static import would
+load the sink registry into every install — the exact failure AGENTS.md documents for Lab,
+where a six-hop chain pulled ~69 modules onto the core path and no single file looked wrong.
+
+## Docs
+
+- `docs-site/src/content/docs/reference/configuration/server.md` — new
+  `quotaResetNotify` section: every field, defaults, the default-OFF statement, and the
+  note that the payload deliberately carries no account identity.
+- `docs-site/src/content/docs/reference/management-api.md` — one table row for
+  `GET /api/quota-resets`, matching the existing row format at line 197.
+- `docs-site/src/content/docs/reference/cli/providers-accounts.md` —
+  `ocx provider resets`.
+
+English source only. Translated locales are left alone rather than machine-translated:
+a stale translation that contradicts the English source is worse than an absent one.
+
+## Activation evidence (C-ACTIVATION-GROUNDING-01)
+
+Every conditional path this unit adds needs a fired-path artifact, recorded in
+`050_activation_evidence.md` with pasted test output:
+
+| Path | Trigger | Observable proof |
+|---|---|---|
+| scheduled detection | prev resetAt in the past + drop | assertion on `kind === "scheduled"` |
+| surprise detection | drop inside an unexpired window | assertion on `kind === "surprise"` |
+| deadline-jump surprise | `next.resetAt > prev.resetAt` early | assertion on `kind === "surprise"` |
+| exactly-once | same key twice + store rehydration | sink call count is 1 |
+| credits-only suppression | `{ resetCredits }` write only | sink call count is 0 |
+| cold-start suppression | no prev | sink call count is 0 |
+| default-OFF | no config | sink never constructed, no timer |
+| sink failure isolation | throwing webhook | `ok: false` + command sink still ran |
+| blocked destination | private URL, flag off | `"blocked-destination"` |
+| poller idempotence | double start | one timer |
+| boundary guard | synthetic static-import fixture, like the existing attack cases at tests/core-lab-boundary.test.ts:301 | the guard fails on the fixture and passes on the real tree |
+| webhookUrl redaction | ocx config show with a configured webhook | the URL prints as `********` |
+
+A green suite with no test driving a trigger does not satisfy any row.
+
+## PR
+
+Branch `codex/quota-reset-detection` -> `dev`. Never `main`. Full
+`.github/PULL_REQUEST_TEMPLATE.md`: Summary, Verification (pasted command tails with exit
+codes), Checklist. No screenshot needed — no GUI change, and the description must avoid
+implying one, since `enforce-target` demands a screenshot from any PR whose title or
+description mentions the GUI.
+
+Commits stay small and per-phase (DEV-GIT-COMMIT-01). Push is user-approved for this task;
+force-push and pushes to `dev`/`main` are not.
+
+## D-phase record
+
+`050_activation_evidence.md` plus a `060_closeout.md` naming the terminal outcome, what did
+NOT improve, and which hypothesis died (LOOP-PESSIMIST-01). Known candidate already:
+detection cadence is bounded by the 5- and 10-minute cache TTLs, so `detectedAt` brackets
+the reset rather than timestamping it. That is a limitation to state, not to hide.
+
+On close, the unit moves to `devlog/_fin/` only once the PR has landed — a `_fin` unit is a
+record of work already visible in public git history.
diff --git a/devlog/_plan/260828_quota_reset_detection/050_activation_evidence.md b/devlog/_plan/260828_quota_reset_detection/050_activation_evidence.md
new file mode 100644
index 0000000000..10675d6130
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/050_activation_evidence.md
@@ -0,0 +1,64 @@
+# wp5 — hardening, activation evidence, delivery
+
+## Deferred review findings, now closed
+
+Both were accepted in `004_wp3_review_response.md` as real but non-blocking, and both are
+fixed here rather than left as known issues.
+
+### Finding 4 — the debounced write was starvable
+
+`schedulePersist` cleared and re-armed its timer on every observation, so any write cadence
+faster than the 250 ms debounce deferred the write indefinitely. Measured on the unfixed
+version:
+
+| Cadence | Observations | Disk writes |
+| --- | --- | --- |
+| every 40 ms for 3 s | 75 | 0 |
+| every 10 ms for 2 s | 200 | 0 |
+| every 400 ms | 5 | 5 |
+
+The trailing write lands once traffic quiesces, so this was starvation rather than breakage —
+but a busy pooled install killed with SIGKILL (container stop, OOM) lost its entire baseline
+and re-baselined on restart, silently missing any reset spanning the gap. That is exactly the
+across-a-restart guarantee the store exists to provide. The module already reasoned about this
+for claims ("a claim MUST NOT ride the debounce") and then left the baseline riding it.
+
+**Fix:** a maximum-staleness cap. `firstDeferredPersistAt` records when the pending write was
+first scheduled; once deferral exceeds 1 s the next call writes immediately. At 0.29 ms per
+serialize-and-write, a forced write per second under sustained load is free.
+
+**Test honesty note.** The first version of the regression test asserted the state file
+EXISTED, passed with the cap removed, and therefore proved nothing — hydration already creates
+the file. It now truncates the file first and asserts the observed row reached disk while
+traffic was still arriving. With the cap removed: `(fail)`. With it: `(pass)`. Worth recording,
+because the vacuous version looked identical from the test list.
+
+### Finding 7 — `updateAccountQuota` committed windows without notifying
+
+It writes `weeklyPercent`/`monthlyPercent` and their deadlines but had no
+`notifyCodexQuotaSnapshot` call. No in-repo caller today, but it is re-exported as public API
+through `src/codex/auth-api.ts`, so a future caller would have bypassed detection *and* left a
+stale baseline that corrupts the next real diff. Now notifies. The credits-only path in
+`setAccountQuotaFromParsed` still deliberately does not — it carries no window values.
+
+## Known limitations, stated rather than buried
+
+- **`detectedAt` brackets a reset; it does not timestamp one.** Observation cadence is bounded
+  by the 5-minute provider cache TTL and the 10-minute per-account TTL, so the reset instant is
+  only ever known to lie between two observations. The field is named `detectedAt` rather than
+  `resetAt` precisely so every consumer sees that.
+- **Two deliberate false negatives** (recorded in `003_wp3_audit_response.md`): a clockless
+  window that resets while unused, and a rollover immediately followed by heavy use that
+  restores the previous percentage. Both are silent by design — the alternative in each case is
+  a rule that also fires on healthy traffic.
+- **Rolling-window creep suppression is heuristic.** A reset whose new deadline lands within 2x
+  the elapsed gap reads as creep. On the observation paths that exist here the gap is minutes
+  and a real window is hours, so the margin is wide; it is not a proof.
+- **Payload privacy is a type obligation, not a scanned one.** `bun run privacy:scan` reads
+  repository text, not runtime output. The payload is built field by field with a closed type
+  and an asserting test; nothing mechanical prevents a future field from being added wrongly.
+
+## Out of scope
+
+`src/codex/reset-credit-recovery.ts` owns credit *consumption*, not window detection, and is
+currently unwired in production. Untouched.
diff --git a/devlog/_plan/260828_quota_reset_detection/060_closeout.md b/devlog/_plan/260828_quota_reset_detection/060_closeout.md
new file mode 100644
index 0000000000..03d4edcc07
--- /dev/null
+++ b/devlog/_plan/260828_quota_reset_detection/060_closeout.md
@@ -0,0 +1,90 @@
+# Closeout — quota-reset detection and notification
+
+**Terminal outcome: shipped as a PR against `dev`.** Five work-phases, each a full PABCD cycle.
+
+## What exists now
+
+OpenCodex notices when a usage window resets and can tell you about it — both the scheduled
+rollover you could predict and an out-of-band reset you could not. Off by default; a default
+install executes no detection code, starts no timer, and writes no state file.
+
+| Piece | File |
+| --- | --- |
+| Pure detection | `src/quota/reset-detector.ts` |
+| Durable claims, baselines, event ring | `src/quota/reset-seen-store.ts` |
+| Observation entry point | `src/quota/reset-observer.ts` |
+| Provider/Codex shape mapping | `src/quota/window-mapping.ts` |
+| Idle poller | `src/quota/reset-poller.ts` |
+| Config resolution | `src/quota/reset-notify-config.ts` |
+| Webhook + command sinks | `src/quota/reset-sinks.ts` |
+| Activation switch | `src/quota/reset-activation.ts` |
+| Management route | `src/server/management/quota-reset-routes.ts` |
+
+Seams: `src/codex/quota.ts` and `src/providers/quota.ts`, both reaching the observer only
+through `import()`. Enforced by `tests/quota-reset-core-boundary.test.ts`.
+
+## Commits
+
+```
+c752929d7  docs(devlog): roadmap                              wp1
+fb958fd5d  docs(devlog): A-phase audit findings               wp1
+19d2447e9  docs(devlog): work-phase map                       wp1
+e3853d84a  feat(quota): detector + claim store                wp2
+aff0ca2ec  fix(quota): scheduled corroboration, clockless key wp2
+f4fcbb547  feat(quota): both seams + idle poller              wp3
+2e4b3be3e  fix(quota): config-mtime notify cache              wp3
+1e5945f61  fix(quota): serialization, identity, boundary      wp3
+6e1cab123  feat(quota): sinks, activation, surfaces           wp4
+453e91542  docs(quota): reference documentation               wp4
+c54333d4c  fix(quota): persistence cap + second writer        wp5
+```
+
+## Defects found and fixed during the work
+
+Eleven, of which four were found by an adversarial review of code that was already green and
+four by attacking my own guards. The ones worth remembering:
+
+1. **The provider seam was dead on arrival.** `previous` binds only when `cache.key === key`,
+   but the key digest includes the quota values themselves — so it is empty exactly when a reset
+   happened. Fixed by giving the detector its own persisted baseline.
+2. **Out-of-order observations manufactured resets.** Two awaits before the baseline swap, and
+   Bun does not resolve concurrent `import()` calls in call order. A burst of rising usage fired
+   a false "surprise" every run, and the false event burned the durable claim key — permanently
+   suppressing the genuine reset. Fixed by serializing on a synchronously-reassigned chain.
+3. **Reauth fired a false reset on every occurrence**, and the test written to prevent it also
+   cleared the observer store, which no production path does. The test simulated a state that
+   never happens.
+4. **The account key collapsed an API-key pool** onto one identity and could be read after a
+   mid-flight failover rewrote it.
+5. **The enable gate could never turn on.** `captureConfigGeneration` only advances on
+   account/provider reconciliation, so editing the notify section never bumped it.
+6. **The observed-window map evicted its hottest row**, because re-setting a key does not move
+   it in a Map, so eviction removed the earliest-inserted rather than the least-recently-used.
+7. **`accountTag` was brute-forceable** — an unsalted hash of an email fell in 36 guesses, and
+   the tag crosses a webhook boundary.
+8. **A rolling window's natural decay read as a surprise reset**, on the most common window in
+   the system.
+
+## Process notes
+
+- **A guard that has never failed is not evidence.** Every guard here was driven red first. Two
+  tests passed against the code they were meant to catch: the burst test (the observer module is
+  already cached in-process, so a child process was required) and the starvation test (it
+  asserted a file existed, which hydration already guarantees).
+- **A reviewer's diagnosis and their prescription are separate claims.** Finding 6's magnitude
+  bound was implemented, measured, and rejected — it suppressed an 83-point real drop while
+  still firing on the 27-point decay it targeted. The diagnosis was right and the remedy was
+  wrong, and only measuring told them apart.
+- **Subagent reliability was poor**: of five reviewers dispatched across the unit, one produced
+  the substantive review above and three went silent. Every blocker it raised was independently
+  reproduced here before being acted on.
+- **SOURCE-DELTA-01 fired once**, correctly, when I committed wp4 before entering B. The
+  remaining docs work became that phase's delta.
+
+## Left undone, deliberately
+
+- No GUI surface. `safeConfigDTO` is a whitelist, so the section is invisible to the dashboard
+  by design; a toggle would need that whitelist extended and a redaction decision for the
+  webhook URL.
+- English docs only. Translated locales are a separate pass, not a machine translation.
+- `src/codex/reset-credit-recovery.ts` untouched: it owns credit consumption, not detection.
diff --git a/docs-site/src/content/docs/reference/cli/providers-accounts.md b/docs-site/src/content/docs/reference/cli/providers-accounts.md
index a343c01d71..6396a68c41 100644
--- a/docs-site/src/content/docs/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/reference/cli/providers-accounts.md
@@ -23,6 +23,7 @@ both `--adapter` and `--base-url`.
 | `set-default <name>` | `--json` | Select an existing provider as the default. |
 | `selected <name>` | `--set <ids>`, `--clear`, `--json` | Read or update the provider model allowlist. |
 | `quota` | `--refresh`, `--json` | Read provider quota reports. |
+| `resets` | `--limit <n>`, `--json` | List recently detected quota-window resets. |
 | `presets` | `--json` | List dashboard provider presets. |
 | `account-mode` | `pool`, `direct`, `--json` | Select pooled or direct Codex account routing. |
 
diff --git a/docs-site/src/content/docs/reference/configuration/providers.md b/docs-site/src/content/docs/reference/configuration/providers.md
index baaf32a8e5..d7b7172dc8 100644
--- a/docs-site/src/content/docs/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/reference/configuration/providers.md
@@ -177,6 +177,7 @@ predictions. Explicit provider/model price overrides still take precedence.
 | `googleMode?` | `"ai-studio" \| "vertex" \| "cloud-code-assist"` | Google transport/auth mode. Default `ai-studio`. |
 | `directGeminiWireRenames?` | `boolean` | Google only. Applies only to direct AI Studio requests. Omitted or `true` keeps the `-tiered` wire rename for Gemini Flash ids (`gemini-3.7-flash` -> `gemini-3.7-flash-tiered`); `false` sends the requested bare ids to the wire unchanged. Vertex preserves the requested model ID, and Cloud Code Assist routing is unchanged. Set `false` when the configured upstream still serves the bare ids. |
 | `project?` | `string` | Vertex or Antigravity Cloud Code Assist project id. |
+| — | — | Antigravity account quota probes (`retrieveUserQuota` and `retrieveUserQuotaSummary`) always go to Google's own Cloud Code host through the pinned outbound transport, regardless of a configured `baseUrl`; the account bearer is never sent to an operator-configured endpoint and a redirect aborts the probe. Only the model-list fallback still honors `baseUrl`. |
 | `location?` | `string` | Vertex location; environment fallback is `GOOGLE_CLOUD_LOCATION`. |
 | `mcpServers?` | `Record<string, CursorMcpServerConfig>` | Cursor only: stdio or Streamable HTTP MCP servers. |
 | `desktopExecutor?` | `DesktopExecutorConfig` | Cursor only: external computer-use and record-screen commands. |
diff --git a/docs-site/src/content/docs/reference/configuration/server.md b/docs-site/src/content/docs/reference/configuration/server.md
index b9eaf62883..c6994f74a2 100644
--- a/docs-site/src/content/docs/reference/configuration/server.md
+++ b/docs-site/src/content/docs/reference/configuration/server.md
@@ -171,6 +171,94 @@ either `target.reduceToBytes` or `target.removeOldestPercent`. `mode` defaults t
 Configure it on the Storage page or with `GET`/`PUT /api/storage/cleanup-policy`; trigger a manual run
 with `POST /api/storage/cleanup-policy/run`.
 
+## Quota-reset notifications (`quotaResetNotify`)
+
+Off by default. When the section is absent, no detection runs, no timer starts, and no state
+file is written.
+
+Enable it to be told when a usage window resets — both the scheduled rollover you can predict
+and an out-of-band reset you cannot:
+
+```json
+{
+  "quotaResetNotify": {
+    "enabled": true,
+    "webhookUrl": "https://hooks.slack.com/services/...",
+    "kinds": ["scheduled", "surprise"],
+    "pollSeconds": 900
+  }
+}
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Master switch. Also requires at least one sink, below. |
+| `kinds` | both | `scheduled` (the deadline passed) or `surprise` (quota returned early). |
+| `pollSeconds` | `900` | Idle poll interval; floor 600. `0` observes live traffic only. |
+| `webhookUrl` | — | `https` POST target for the event JSON. Treated as a secret. |
+| `allowPrivateNetwork` | `false` | Permit a loopback or private-network webhook target. |
+| `timeoutMs` | `5000` | Webhook timeout. |
+| `command` | — | Argv array run with the event JSON on stdin. |
+
+`enabled: true` with neither `webhookUrl` nor `command` resolves to off: an enabled subsystem
+with nowhere to deliver is a misconfiguration, not a half-on state.
+
+The floor is 600 seconds because a faster poll cannot see anything new: observation is bounded
+by the 10-minute per-account cache, so a shorter interval only adds load to a quota endpoint
+that rate-limits. A configured value is adopted on the next tick without a restart.
+
+Set `pollSeconds` to `0` only if you accept that a reset happening while the proxy is idle is
+noticed on the next request rather than when it happens. The poll exists because the overnight
+case is the one worth knowing about.
+
+### The delivered event
+
+```json
+{
+  "type": "quota_reset",
+  "kind": "surprise",
+  "scope": "codex",
+  "accountTag": "k3f9x2ab",
+  "window": "weekly",
+  "percentBefore": 96,
+  "percentAfter": 4,
+  "previousResetAt": 1772000000000,
+  "resetAt": 1772400000000,
+  "detectedAt": 1771900000000
+}
+```
+
+`accountTag` is a per-install salted hash, not an account identifier: it distinguishes your
+accounts from each other without telling the receiver who they are. No email, token, path, or
+URL is ever included.
+
+`detectedAt` is when the proxy NOTICED, not when the reset happened. Observation is bounded by
+the 5-minute provider cache and the 10-minute per-account cache, so the reset instant can only
+be bracketed between two observations.
+
+### Security notes
+
+`webhookUrl` is a credential — for Slack and Discord, holding the URL is sufficient to post —
+so it is redacted by `ocx config show` and excluded from `ocx config export`.
+
+A webhook target that resolves to a private or loopback address is refused unless you set
+`allowPrivateNetwork: true`. The proxy can reach hosts your browser cannot, including cloud
+metadata endpoints, so the default assumes an external receiver.
+
+`webhookUrl` must use `https`. The payload and the URL itself are both sensitive, and an
+`http` target would put them in cleartext; an `http` value is rejected when the config is
+written rather than downgraded silently.
+
+A redirect is refused rather than followed. The destination check above validates the URL you
+configured, so following a `3xx` would deliver the payload somewhere unvalidated — a public
+endpoint could bounce the POST to loopback or a metadata address. Configure the final URL
+directly; a redirected delivery reports `blocked-destination`.
+
+`command` is an argv array and is never passed through a shell, so its values cannot become a
+shell-injection surface. Delivery is attempted once; there is no retry.
+
+Read recent detections with `ocx provider resets` or `GET /api/quota-resets`.
+
 ## Claude Code (`claudeCode`)
 
 These settings govern `/v1/messages`, `/v1/messages/count_tokens`, the `ocx claude` launcher, and the Claude dashboard page.
diff --git a/docs-site/src/content/docs/reference/management-api.md b/docs-site/src/content/docs/reference/management-api.md
index c8e67c4791..fef309a2b8 100644
--- a/docs-site/src/content/docs/reference/management-api.md
+++ b/docs-site/src/content/docs/reference/management-api.md
@@ -230,6 +230,7 @@ keys are not returned to dashboard clients.
 | `DELETE /api/providers?name=...` | Delete a provider, reassigning the default when possible | 404 unknown provider; 409 `last_provider`; 409 `provider_has_dependent_combos` |
 | `POST /api/providers/test?name=...` | Perform a bounded live provider connectivity/model-discovery probe | 404 unknown provider; failures are normally returned as `ok: false` evidence |
 | `GET /api/provider-quotas` | Read provider quota reports; `refresh=1` forces refresh | — |
+| `GET /api/quota-resets` | List recently detected quota-window resets and whether detection is enabled; `limit=<n>` caps the count | 400 invalid `limit` |
 | `GET, PUT /api/provider-context-caps` | Read or update global, all-provider, or one-provider context caps | 400 invalid request; 404 unknown provider |
 | `GET /api/provider-presets` | Return GUI provider presets derived from the runtime registry | — |
 
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index 5ec5e305d5..73c7e16254 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -942,6 +942,13 @@
     "quota-401-recovery-runtime.test.ts": "usage",
     "quota-401-recovery.test.ts": "usage",
     "quota-bars-rows.test.ts": "gui",
+    "quota-reset-account-key.test.ts": "usage",
+    "quota-reset-core-boundary.test.ts": "usage",
+    "quota-reset-detector.test.ts": "usage",
+    "quota-reset-notify-config.test.ts": "usage",
+    "quota-reset-notify.test.ts": "usage",
+    "quota-reset-observation.test.ts": "usage",
+    "quota-reset-seen-store.test.ts": "usage",
     "quota-scoring.test.ts": "usage",
     "qwen-cloud-endpoints.test.ts": "gui",
     "qwen38-preserve-reasoning.test.ts": "providers",
diff --git a/src/cli/config-command.ts b/src/cli/config-command.ts
index 796b503f0e..cd33fefd74 100644
--- a/src/cli/config-command.ts
+++ b/src/cli/config-command.ts
@@ -15,7 +15,15 @@ const USAGE = `Usage:
   ocx config export <path|->
   ocx config import <path|-> --yes [--json]`;
 
-const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret)$/i;
+/**
+ * Keys whose VALUE is a credential and must never be printed or exported.
+ *
+ * `webhookUrl` is here because for Slack and Discord the URL itself is the authorization:
+ * anyone holding it can post to the channel. It looks like configuration rather than a secret,
+ * which is exactly why it needs to be named explicitly — none of the other patterns match it,
+ * so `ocx config show` printed it and `config export` wrote it to disk in the clear.
+ */
+const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret|webhookUrl)$/i;
 const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 
 function redact(value: unknown, key = ""): unknown {
diff --git a/src/cli/provider-runtime.ts b/src/cli/provider-runtime.ts
index 6f7a204832..416d5ddb1b 100644
--- a/src/cli/provider-runtime.ts
+++ b/src/cli/provider-runtime.ts
@@ -19,6 +19,21 @@ interface ProviderQuotasDto {
   reports?: ProviderQuotaReportDto[];
 }
 
+interface QuotaResetEventDto {
+  kind?: string;
+  scope?: string;
+  window?: string;
+  percentBefore?: number;
+  percentAfter?: number;
+  resetAt?: number;
+  detectedAt?: number;
+}
+
+interface QuotaResetsDto {
+  enabled?: boolean;
+  events?: QuotaResetEventDto[];
+}
+
 const USAGE = `Usage:
   ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->]
       [--auth-mode <key|forward|oauth|local|->] [--note <text|->]
@@ -28,6 +43,7 @@ const USAGE = `Usage:
       [--allow-private-network <on|off>] [--json]
   ocx provider test <name> [--json]
   ocx provider quota [--refresh] [--json]
+  ocx provider resets [--limit <n>] [--json]
   ocx provider presets [--json]
   ocx provider account-mode <pool|direct> [--json]
   ocx provider selected <name> [--set <model,model...>] [--clear] [--json]
@@ -132,6 +148,48 @@ async function quota(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, lines);
 }
 
+
+/**
+ * Recently detected quota resets, newest first.
+ *
+ * `accountTag` is deliberately NOT rendered: it is a salted hash that means nothing to a human
+ * reading a terminal, and printing it invites treating an opaque tag as an account identifier.
+ */
+function quotaResetLine(event: QuotaResetEventDto): string {
+  const when = typeof event.detectedAt === "number"
+    ? new Date(event.detectedAt).toISOString()
+    : "unknown time";
+  const movement = typeof event.percentBefore === "number" && typeof event.percentAfter === "number"
+    ? `${event.percentBefore}% -> ${event.percentAfter}%`
+    : "usage unknown";
+  const next = typeof event.resetAt === "number"
+    ? `, next ${new Date(event.resetAt).toISOString()}`
+    : "";
+  return `${when}  ${event.scope ?? "?"} ${event.window ?? "?"} ${event.kind ?? "?"}: ${movement}${next}`;
+}
+
+async function resets(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const limitRaw = takeOption(args, "--limit");
+  rejectArgs(args, USAGE);
+  if (limitRaw !== undefined && !/^\d+$/.test(limitRaw)) {
+    throw new CliUsageError("--limit must be a non-negative integer", USAGE);
+  }
+  const query = limitRaw === undefined ? "" : `?limit=${limitRaw}`;
+  const result = await runtimeRequest<QuotaResetsDto>(`/api/quota-resets${query}`, {}, deps);
+  const events = Array.isArray(result?.events) ? result.events : [];
+  // One line per event, NOT summaryLines: that helper is a depth-1 flattener and renders a
+  // non-scalar array as "N item(s)", which is what made `ocx provider quota` useless in #2565.
+  const lines = events.length > 0
+    ? events.map(quotaResetLine)
+    // An empty list is ambiguous, so say which kind of empty it is. Without this an operator
+    // cannot tell "nothing has reset yet" from "I never turned this on".
+    : [result?.enabled === true
+      ? "no resets detected yet"
+      : "quota-reset notifications are disabled (set quotaResetNotify.enabled)"];
+  printData(result, wantsJson, lines);
+}
 async function presets(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
@@ -210,6 +268,7 @@ export async function handleProviderRuntimeCommand(sub: string, argv: string[],
     update: edit,
     test: testProvider,
     quota,
+    resets,
     presets,
     "account-mode": accountMode,
     selected,
diff --git a/src/cli/provider.ts b/src/cli/provider.ts
index ee4c92b8b7..f9ac3b5b21 100644
--- a/src/cli/provider.ts
+++ b/src/cli/provider.ts
@@ -433,6 +433,7 @@ Subcommands:
   set-default <name>    Change the default provider
   selected <name>       Show or set the provider model allowlist
   quota                 Show provider quota reports
+  resets                Show recently detected quota resets
   presets               List GUI provider presets
   account-mode <mode>   Set OpenAI Codex pool/direct mode
 
diff --git a/src/codex/quota.ts b/src/codex/quota.ts
index 87e5766b84..7deff46a80 100644
--- a/src/codex/quota.ts
+++ b/src/codex/quota.ts
@@ -341,6 +341,68 @@ export function setAccountQuotaFromParsed(
 
   accountQuota.set(accountId, next);
   schedulePersistAccountQuotas();
+  notifyCodexQuotaSnapshot(accountId, next);
+}
+
+/**
+ * Hand a committed snapshot to the optional quota-reset observer.
+ *
+ * Lazy import on purpose. This file is statically reachable from
+ * src/server/responses/core.ts (via codex/auth-context.ts), and
+ * applyAccountQuotaFromUpstreamHeaders runs it once per pooled response. A static import
+ * would load the observer, its config resolution, and its sink registry into every install,
+ * including installs that never enable the feature — the same failure mode
+ * tests/core-lab-boundary.test.ts exists to prevent for src/lab/.
+ *
+ * The previous snapshot is deliberately NOT passed. The observer keeps its own persisted
+ * baseline (see swapLastObservedWindows), so every committed write must reach it — including
+ * the first one, which is what establishes that baseline. An earlier version of this
+ * function skipped the call when the in-map `existing` was undefined; that left the observer
+ * with no baseline to compare against, so the write AFTER a rollover was silently treated as
+ * the first observation and no reset ever fired.
+ *
+ * The snapshot is COPIED synchronously, before the import resolves. `next` is the live map
+ * value and the next write mutates it, so an observation that read it after awaiting could
+ * see a later snapshot than the one it was called for.
+ *
+ * Observations are SERIALIZED through a module-level promise chain, because the baseline
+ * swap must happen in call order. An earlier version awaited two imports and then swapped,
+ * and Bun does not resolve concurrent import() calls in call order: a burst of 21
+ * rising-usage writes (10% -> 90%, no reset at all) arrived reordered and fired a false
+ * "surprise" reset on every run. Worse, the false event CLAIMED the durable idempotence
+ * key, so the genuine reset on that window was then permanently suppressed.
+ *
+ * `pendingObservation` is reassigned SYNCHRONOUSLY here, so each link is queued in call
+ * order and only starts once the previous one has committed its baseline. A FIFO queue
+ * entered after the await would not have fixed it — the enqueue itself would race.
+ */
+let pendingObservation: Promise<void> = Promise.resolve();
+
+function notifyCodexQuotaSnapshot(accountId: string, next: StoredAccountQuota): void {
+  // Copy before the boundary: `next` is the live map value and the following write mutates
+  // it, so an observation that read it after awaiting could see a later snapshot than the
+  // one it was called for.
+  const snapshot = { ...next };
+  pendingObservation = pendingObservation
+    .then(async () => {
+      const observer = await import("../quota/reset-observer");
+      if (!observer.hasQuotaResetSink()) return;
+      const { codexWindowObservations } = await import("../quota/window-mapping");
+      observer.observeQuotaSnapshot({
+        scope: "codex",
+        accountKey: accountId,
+        windows: codexWindowObservations(snapshot),
+      });
+    })
+    .catch(() => {
+      // Detection is best-effort: a quota write must never fail because of it. Swallowing
+      // here also keeps the chain alive — a rejected link would poison every later one.
+    });
+}
+
+/** Await the observation chain. Tests only: production never needs to join it. */
+export function flushQuotaObservationsForTests(): Promise<void> {
+  return pendingObservation;
 }
 
 export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQuota, "updatedAt"> | null {
@@ -474,6 +536,12 @@ export function updateAccountQuota(
 
   accountQuota.set(accountId, quota);
   schedulePersistAccountQuotas();
+  // Observed like the other committed write. This function has no in-repo caller today, but it
+  // is re-exported as public API through src/codex/auth-api.ts, so a future caller would
+  // otherwise bypass detection AND leave a stale baseline that corrupts the next real diff.
+  // The credits-only path at setAccountQuotaFromParsed deliberately does not notify; this one
+  // writes window percentages and deadlines, so it must.
+  notifyCodexQuotaSnapshot(accountId, quota);
 }
 
 function hydrateAccountQuotasFromDisk(): void {
@@ -523,13 +591,37 @@ export function listAccountQuotas(): IterableIterator<[string, StoredAccountQuot
   return accountQuota.entries();
 }
 
+/**
+ * Tell the observer to drop the baseline for a row that was deliberately cleared.
+ *
+ * Queued on the same chain as observations so it cannot overtake an in-flight one and be
+ * immediately re-established by it. Without this, reauth of a used account left the observer
+ * holding the pre-clear percentages and the first fresh write fired a false surprise reset
+ * (measured 91% -> 0%).
+ */
+function forgetCodexQuotaBaseline(accountId?: string): void {
+  pendingObservation = pendingObservation
+    .then(async () => {
+      const observer = await import("../quota/reset-observer");
+      observer.forgetQuotaBaseline({
+        scope: "codex",
+        ...(accountId !== undefined ? { accountKey: accountId } : {}),
+      });
+    })
+    .catch(() => {
+      // Best-effort; a failure can only cost a re-baseline.
+    });
+}
+
 export function clearAccountQuota(accountId?: string): void {
   if (accountId) {
     accountQuota.delete(accountId);
     schedulePersistAccountQuotas();
+    forgetCodexQuotaBaseline(accountId);
     return;
   }
   accountQuota.clear();
+  forgetCodexQuotaBaseline();
   diskHydrated = false;
   if (persistTimer) {
     clearTimeout(persistTimer);
diff --git a/src/config.ts b/src/config.ts
index 11da839570..127f16562b 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -999,6 +999,32 @@ const clientConnectionSchema = z.object({
   }).optional(),
 }).strict();
 
+/**
+ * Quota-reset notification section.
+ *
+ * `.strict()` like its neighbour: a typo in an optional feature section should surface as a
+ * rejected write rather than a silently ignored key that leaves the operator believing they
+ * enabled something.
+ *
+ * `pollSeconds` admits 0 (passive-only, no timer) and the resolver clamps anything between 1
+ * and the 60-second floor. Bounds live in the resolver rather than here so a hand-edited value
+ * degrades to a sane one instead of discarding the whole section.
+ */
+const quotaResetNotifySchema = z.object({
+  enabled: z.boolean().optional(),
+  kinds: z.array(z.enum(["scheduled", "surprise"])).optional(),
+  pollSeconds: z.number().int().min(0).optional(),
+  // `z.string().url()` accepts any scheme. The payload carries account identity and the hook
+  // URL is frequently a bearer-equivalent secret, so an http: sink puts both in cleartext.
+  webhookUrl: z.string().url().refine(
+    value => { try { return new URL(value).protocol === "https:"; } catch { return false; } },
+    { message: "webhookUrl must use https" },
+  ).optional(),
+  allowPrivateNetwork: z.boolean().optional(),
+  timeoutMs: z.number().int().positive().optional(),
+  command: z.array(z.string()).optional(),
+}).strict();
+
 const configSchema = z.object({
   port: z.number().int().min(0).max(65535).default(10100),
   // A malformed hand edit must disable only remote-role behavior, not discard
@@ -1074,6 +1100,8 @@ const configSchema = z.object({
   multiAgentGuidanceEnabled: z.boolean().optional(),
   // Invalid optional recovery config must not discard unrelated provider/account state.
   agentTaskRecovery: agentTaskRecoverySchema.optional().catch(undefined),
+  // Same rationale: a bad notify section must not cost the operator their providers.
+  quotaResetNotify: quotaResetNotifySchema.optional().catch(undefined),
   // These selections pre-date schema validation and used to pass through as
   // unknown fields. Invalid hand edits must disable only the optional
   // delegation/native-default feature, not reject the whole config and hide
@@ -1948,6 +1976,27 @@ function warnDegradedOptionalRemoteBlocks(rawParsed: unknown): void {
   }
 }
 
+function malformedQuotaResetNotifyWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "quotaResetNotify")) return null;
+  const result = quotaResetNotifySchema.safeParse(raw.quotaResetNotify);
+  if (result.success) return null;
+  const field = result.error.issues[0]?.path.join(".");
+  return `quotaResetNotify${field ? `.${field}` : ""} ignored: invalid quota-reset notification configuration`;
+}
+
+/**
+ * Warn once per load that the section was dropped.
+ *
+ * This matters more than a usual degradation notice: the failure is SILENT in the direction
+ * that hurts. A dropped section means notifications are off, so the operator sees nothing —
+ * which is exactly what they would see if the feature were working and no reset had happened.
+ */
+function warnDegradedQuotaResetNotify(rawParsed: unknown): void {
+  const warning = malformedQuotaResetNotifyWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
+}
+
 type NativeSubagentPersistedField = "injectionModel" | "injectionEffort" | "syncCodexSubagentDefaults";
 
 function rawConfigRecord(rawParsed: unknown): Record<string, unknown> | null {
@@ -2104,6 +2153,7 @@ export function loadConfig(): OcxConfig {
       warnDegradedAgentTaskRecovery(parsed);
       warnDegradedRuntimeRole(parsed);
       warnDegradedOptionalRemoteBlocks(parsed);
+      warnDegradedQuotaResetNotify(parsed);
       return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
     // Schema validation failed — merge defaults into the raw object instead of
@@ -2130,6 +2180,7 @@ export function loadConfig(): OcxConfig {
       warnDegradedAgentTaskRecovery(parsed);
       warnDegradedRuntimeRole(parsed);
       warnDegradedOptionalRemoteBlocks(parsed);
+      warnDegradedQuotaResetNotify(parsed);
       return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
     // Still failing, but if every complaint is about one or more named entries
@@ -2152,6 +2203,7 @@ export function loadConfig(): OcxConfig {
         warnDegradedAgentTaskRecovery(parsed);
         warnDegradedRuntimeRole(parsed);
         warnDegradedOptionalRemoteBlocks(parsed);
+        warnDegradedQuotaResetNotify(parsed);
         return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
       }
     }
@@ -2292,6 +2344,8 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   if (remoteGuiWarning) warnings.push(remoteGuiWarning);
   const clientWarning = malformedClientConnectionWarning(rawParsed);
   if (clientWarning) warnings.push(clientWarning);
+  const notifyWarning = malformedQuotaResetNotifyWarning(rawParsed);
+  if (notifyWarning) warnings.push(notifyWarning);
   if (syncDisabledReason) {
     warnings.push(`syncCodexSubagentDefaults ignored: ${syncDisabledReason}`);
   }
@@ -2430,6 +2484,16 @@ function clientRolePairError(value: unknown): string | null {
   return null;
 }
 
+function quotaResetNotifyError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "quotaResetNotify") || raw.quotaResetNotify === undefined) return null;
+  const result = quotaResetNotifySchema.safeParse(raw.quotaResetNotify);
+  if (result.success) return null;
+  const issue = result.error.issues[0];
+  const field = issue?.path.join(".");
+  return `schema_invalid: quotaResetNotify${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`;
+}
+
 /**
  * Same reasoning as {@link blankHostnameError}, and more urgent: the read path degrades a
  * malformed selection-order map to undefined, which on a write would drop every entry the
@@ -2588,6 +2652,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? appOwnedMemoryBudgetError(value)
     ?? upstreamHostCircuitThresholdError(value)
     ?? agentTaskRecoveryError(value)
+    ?? quotaResetNotifyError(value)
     ?? googleAntigravityStaticCatalogVersionError(value)
     ?? codexAccountPrioritiesError(value)
     ?? codexAccountPickerEnabledError(value)
diff --git a/src/providers/quota.ts b/src/providers/quota.ts
index 9cdaafe6b6..49533336c0 100644
--- a/src/providers/quota.ts
+++ b/src/providers/quota.ts
@@ -9,10 +9,12 @@ import type { StoredAccountQuota } from "../codex/quota";
 import { isMainAccountIdentityGenerationLive } from "../codex/main-account-cache";
 import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
 import { codexPlanKey } from "../codex/plan";
+import { resolveEnvValue } from "../config";
 import { resolveProviderApiKey } from "./key-store";
 import { getValidAccessToken, getValidAccessTokenForAccount } from "../oauth";
 import { getAccountCredential, getAccountSet, getCredential } from "../oauth/store";
 import { antigravityUserAgent } from "../adapters/client-fingerprint";
+import { isCanonicalOllamaCloudUrl } from "../adapters/ollama-native-url";
 import { providerOutboundPost, providerRedirectError, type ProviderOutboundDependencies } from "../lib/provider-outbound";
 import { apiKeyPoolEntryId } from "./api-keys";
 import { XAI_GROK_CLIENT_VERSION, XAI_GROK_COMPATIBILITY } from "./xai-transport";
@@ -83,6 +85,8 @@ const OPENCODE_GO_USAGE_URL = `${OPENCODE_GO_BASE_URL}/usage`;
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
 const DEEPSEEK_BASE_URL = "https://api.deepseek.com";
 const CLINE_BASE_URL = "https://api.cline.bot";
+const OLLAMA_CLOUD_BASE_URL = "https://ollama.com";
+const OLLAMA_CLOUD_USAGE_URL = `${OLLAMA_CLOUD_BASE_URL}/api/usage`;
 const ZAI_BASE_URL = "https://api.z.ai";
 const ZAI_CN_BASE_URL = "https://open.bigmodel.cn";
 const MINIMAX_REMAINS_URL = "https://www.minimax.io/v1/token_plan/remains";
@@ -328,6 +332,15 @@ function isCanonicalClineBaseUrl(baseUrl: string): boolean {
   return normalized === CLINE_BASE_URL || normalized === `${CLINE_BASE_URL}/api/v1`;
 }
 
+function isCanonicalOllamaCloudBaseUrl(baseUrl?: string): boolean {
+  if (!baseUrl) return false;
+  try {
+    return isCanonicalOllamaCloudUrl(baseUrl);
+  } catch {
+    return false;
+  }
+}
+
 function isCanonicalZaiBaseUrl(baseUrl: string): boolean {
   const normalized = normalizedBaseUrl(baseUrl);
   return normalized === ZAI_BASE_URL
@@ -659,6 +672,78 @@ async function fetchClineQuota(provider: string, config: OcxProviderConfig): Pro
   return windows > 0 ? report(provider, "cline:plan-usage-limits", quota) : null;
 }
 
+/**
+ * Ollama Cloud `GET https://ollama.com/api/usage` — returns account usage.
+ * Legacy plans report rolling 5-hour `limits.session.usage` and 7-day
+ * `limits.weekly.usage`. Migrated monthly-credit plans report
+ * `limits.monthly.usage`. `usage` values are normalized fractions (0..1).
+ */
+function parseOllamaPercent(usageValue: unknown): number | undefined {
+  const usage = toFiniteNumber(usageValue);
+  if (usage === undefined || usage < 0) return undefined;
+  const percent = Math.round(usage * 10000) / 100;
+  return normalizePercent(percent);
+}
+
+export function parseOllamaCloudQuota(body: Record<string, unknown> | null): ProviderQuota | null {
+  if (!body) return null;
+  const limits = asRecord(body.limits);
+  if (!limits) return null;
+
+  const quota: ProviderQuota = { updatedAt: Date.now() };
+  let windows = 0;
+
+  const session = asRecord(limits.session);
+  if (session) {
+    const percent = parseOllamaPercent(session.usage);
+    if (percent !== undefined) {
+      quota.fiveHourPercent = percent;
+      windows += 1;
+    }
+  }
+
+  const weekly = asRecord(limits.weekly);
+  if (weekly) {
+    const percent = parseOllamaPercent(weekly.usage);
+    if (percent !== undefined) {
+      quota.weeklyPercent = percent;
+      windows += 1;
+    }
+  }
+
+  const monthly = asRecord(limits.monthly);
+  if (monthly) {
+    const percent = parseOllamaPercent(monthly.usage);
+    if (percent !== undefined) {
+      quota.monthlyPercent = percent;
+      windows += 1;
+    }
+  }
+
+  return windows > 0 ? quota : null;
+}
+
+async function fetchOllamaCloudQuota(provider: string, config: OcxProviderConfig): Promise<ProviderQuotaProbeResult> {
+  const effectiveBaseUrl = config.baseUrl ?? getProviderRegistryEntry(provider)?.baseUrl ?? "";
+  if (!isCanonicalOllamaCloudBaseUrl(effectiveBaseUrl)) return null;
+  const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
+  if (!apiKey) return null;
+  const response = await fetch(OLLAMA_CLOUD_USAGE_URL, {
+    headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
+    redirect: "error",
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    if (response.status === 404) return null;
+    return response.status >= 400 && response.status < 500 && response.status !== 408 && response.status !== 429
+      ? TERMINAL_QUOTA_FAILURE
+      : null;
+  }
+  const body = asRecord(await readQuotaJson(response));
+  const quota = parseOllamaCloudQuota(body);
+  return quota ? report(provider, "ollama-cloud:usage", quota) : null;
+}
+
 /**
  * Z.AI GLM Coding Plan `GET /api/monitor/usage/quota/limit` — the coding-plan
  * limits arrive as a `limits` array of `TOKENS_LIMIT` (newer plans call the
@@ -2287,10 +2372,11 @@ function classifyAntigravityFamily(modelId: string, modelInfo: Record<string, un
 }
 
 function antigravityUsedPercent(quotaInfo: Record<string, unknown>): number | undefined {
-  const remaining = normalizePercent(toFiniteNumber(quotaInfo.remainingFraction) !== undefined
-    ? toFiniteNumber(quotaInfo.remainingFraction)! * 100
-    : toFiniteNumber(quotaInfo.remainingPercentage) !== undefined
-      ? toFiniteNumber(quotaInfo.remainingPercentage)! * 100
+  const target = asRecord(quotaInfo.remaining) ?? quotaInfo;
+  const remaining = normalizePercent(toFiniteNumber(target.remainingFraction) !== undefined
+    ? toFiniteNumber(target.remainingFraction)! * 100
+    : toFiniteNumber(target.remainingPercentage) !== undefined
+      ? toFiniteNumber(target.remainingPercentage)! * 100
       : undefined);
   if (remaining === undefined) return undefined;
   return normalizePercent(100 - remaining);
@@ -2325,6 +2411,75 @@ function antigravityWindowsFromModels(body: Record<string, unknown> | null): Pro
   return customWindows;
 }
 
+/**
+ * Parse Google Antigravity quota from `v1internal:retrieveUserQuotaSummary`.
+ * Groups contain Gemini models and Claude/3P models, each with 5h and weekly limit buckets.
+ */
+function parseAntigravityQuotaSummary(body: Record<string, unknown> | null): ProviderQuota | null {
+  const groups = Array.isArray(body?.groups) ? (body.groups as unknown[]) : [];
+  if (groups.length === 0) return null;
+
+  const customWindowsMap = new Map<string, ProviderQuotaWindow>();
+
+  for (const rawGroup of groups) {
+    const group = asRecord(rawGroup);
+    if (!group) continue;
+    const groupName = `${typeof group.displayName === "string" ? group.displayName : ""} ${typeof group.description === "string" ? group.description : ""}`.toLowerCase();
+    const isGemini = groupName.includes("gemini");
+    const isClaude = groupName.includes("claude") || groupName.includes("3p") || groupName.includes("gpt");
+
+    const buckets = Array.isArray(group.buckets) ? (group.buckets as unknown[]) : [];
+    for (const rawBucket of buckets) {
+      const bucket = asRecord(rawBucket);
+      if (!bucket) continue;
+      const windowStr = `${typeof bucket.window === "string" ? bucket.window : ""} ${typeof bucket.bucketId === "string" ? bucket.bucketId : ""} ${typeof bucket.displayName === "string" ? bucket.displayName : ""}`.toLowerCase();
+      const percent = antigravityUsedPercent(bucket);
+      if (percent === undefined) continue;
+      const resetAt = normalizeResetAt(bucket.resetTime);
+
+      const isWeekly = windowStr.includes("week");
+      const is5h = windowStr.includes("5h") || windowStr.includes("five");
+
+      if (isGemini) {
+        const label = is5h ? "Gem" : isWeekly ? "Gem (Weekly)" : "";
+        if (label && !customWindowsMap.has(label)) {
+          customWindowsMap.set(label, { label, percent, ...(resetAt !== undefined ? { resetAt } : {}) });
+        }
+      } else if (isClaude) {
+        const label = is5h ? "Cla" : isWeekly ? "Cla (Weekly)" : "";
+        if (label && !customWindowsMap.has(label)) {
+          customWindowsMap.set(label, { label, percent, ...(resetAt !== undefined ? { resetAt } : {}) });
+        }
+      } else {
+        const baseLabel = typeof group.displayName === "string" ? group.displayName : "Other";
+        const label = isWeekly ? `${baseLabel} (Weekly)` : baseLabel;
+        if (!customWindowsMap.has(label)) {
+          customWindowsMap.set(label, { label, percent, ...(resetAt !== undefined ? { resetAt } : {}) });
+        }
+      }
+    }
+  }
+
+  const PREFERRED_ORDER = ["Gem", "Gem (Weekly)", "Cla", "Cla (Weekly)"];
+  const customWindows = Array.from(customWindowsMap.values()).sort((a, b) => {
+    const ia = PREFERRED_ORDER.indexOf(a.label);
+    const ib = PREFERRED_ORDER.indexOf(b.label);
+    if (ia !== -1 && ib !== -1) return ia - ib;
+    if (ia !== -1) return -1;
+    if (ib !== -1) return 1;
+    return a.label.localeCompare(b.label);
+  });
+
+  if (customWindows.length === 0) {
+    return null;
+  }
+
+  return {
+    customWindows,
+    updatedAt: Date.now(),
+  };
+}
+
 const ANTIGRAVITY_ACCOUNT_QUOTA_BASE = "https://daily-cloudcode-pa.googleapis.com";
 let antigravityOutboundDependencies: ProviderOutboundDependencies = {};
 
@@ -2341,6 +2496,28 @@ export function setAntigravityAccountQuotaTransportForTests(dependencies: Provid
  * A redirect or non-2xx yields null (unavailable), never a partial row.
  */
 export async function fetchAntigravityUsageQuota(accessToken: string, projectId: string): Promise<ProviderQuota | null> {
+  const summaryUrl = `${ANTIGRAVITY_ACCOUNT_QUOTA_BASE}/v1internal:retrieveUserQuotaSummary`;
+  try {
+    const summaryResponse = await providerOutboundPost("google-antigravity", { baseUrl: ANTIGRAVITY_ACCOUNT_QUOTA_BASE }, summaryUrl, {
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": antigravityUserAgent(),
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify({ project: projectId }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }, antigravityOutboundDependencies);
+    if (await providerRedirectError(summaryResponse, summaryUrl)) return null;
+    if (summaryResponse.status === 401 || summaryResponse.status === 403) return null;
+    if (summaryResponse.ok) {
+      const quota = parseAntigravityQuotaSummary(asRecord(await readQuotaJson(summaryResponse)));
+      if (quota) return quota;
+    }
+  } catch {
+    // Fallback to fetchAvailableModels on error
+  }
+
   const url = `${ANTIGRAVITY_ACCOUNT_QUOTA_BASE}/v1internal:fetchAvailableModels`;
   const response = await providerOutboundPost("google-antigravity", { baseUrl: ANTIGRAVITY_ACCOUNT_QUOTA_BASE }, url, {
     headers: {
@@ -2369,6 +2546,35 @@ async function fetchAntigravityQuota(provider: string, config: OcxProviderConfig
     return null;
   }
   const baseUrl = (config.baseUrl || ANTIGRAVITY_ACCOUNT_QUOTA_BASE).replace(/\/+$/, "");
+
+  // The summary probe is pinned to Google's own host through the provider-outbound
+  // transport, mirroring `fetchAntigravityUsageQuota` above: a configured `baseUrl` is a
+  // routing choice for requests, not a second source of Google's accounting, and this
+  // request carries the account bearer.
+  const summaryUrl = `${ANTIGRAVITY_ACCOUNT_QUOTA_BASE}/v1internal:retrieveUserQuotaSummary`;
+  try {
+    const summaryResponse = await providerOutboundPost("google-antigravity", { baseUrl: ANTIGRAVITY_ACCOUNT_QUOTA_BASE }, summaryUrl, {
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": antigravityUserAgent(),
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify({ project: credential.projectId }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }, antigravityOutboundDependencies);
+    if (await providerRedirectError(summaryResponse, summaryUrl)) return null;
+    if (summaryResponse.status === 401 || summaryResponse.status === 403) return null;
+    if (summaryResponse.ok) {
+      const quota = parseAntigravityQuotaSummary(asRecord(await readQuotaJson(summaryResponse)));
+      if (quota) {
+        return report(provider, "google-antigravity:retrieveUserQuotaSummary", quota);
+      }
+    }
+  } catch {
+    // Fallback on network/fetch error
+  }
+
   const response = await fetch(`${baseUrl}/v1internal:fetchAvailableModels`, {
     method: "POST",
     headers: {
@@ -2446,6 +2652,10 @@ async function maybeFetchProviderQuota(
     if ((provider.authMode ?? "key") === "key" && name === "cline-pass") {
       return fetchClineQuota(name, provider);
     }
+    if ((provider.authMode ?? "key") === "key"
+      && (name === "ollama-cloud" || isCanonicalOllamaCloudBaseUrl(provider.baseUrl))) {
+      return fetchOllamaCloudQuota(name, provider);
+    }
     if ((provider.authMode ?? "key") === "key"
       && (name === "zai" || name === "glm" || name === "glm-cn" || name === "zhipu-bigmodel-coding")) {
       return fetchZaiQuota(name, provider);
@@ -2474,6 +2684,94 @@ async function maybeFetchProviderQuota(
   }
 }
 
+/**
+ * Hand freshly committed provider reports to the optional quota-reset observer.
+ *
+ * Lazy import on purpose: this module is statically reachable from
+ * src/server/responses/core.ts (via oauth/anthropic-routing.ts), so a static edge would put
+ * the observer and its sink registry on every install's request path.
+ *
+ * No previous snapshot is passed. The observer keeps its own persisted last-seen map,
+ * because `previous` here is bound only when `cache.key === key` and the key digest at
+ * cacheKeyWithAggregationState includes quota values and updatedAt — so it is empty exactly
+ * when a reset happened.
+ *
+ * Account identity is resolved SYNCHRONOUSLY, before any await. Two reasons, both observed:
+ * pool failover rewrites `activeAccountId` during request routing
+ * (promoteAnthropicActiveAccount -> setActiveAccount), so a 429 between this commit and a
+ * later async read would attribute this report to a different account and overwrite that
+ * account's baseline with these numbers. fetchAnthropicQuota already captures
+ * `probedAccountId` before awaiting for exactly this reason; the observer must not be
+ * sloppier than the cache it observes.
+ *
+ * Observations are serialized through a module-level promise chain for the same reason as
+ * the codex seam: Bun does not resolve concurrent import() calls in call order, and an
+ * out-of-order baseline swap manufactures false resets that then burn the durable
+ * idempotence key.
+ */
+let pendingProviderObservation: Promise<void> = Promise.resolve();
+
+/**
+ * Stable per-account observation key for one provider report.
+ *
+ * OAuth providers key by active account id. Key-auth providers have NO account set, so
+ * every key in `apiKeyPool` would collapse onto "default" and rotating from a spent key to
+ * a fresh one would read as a reset (measured: 97% -> 12% fired a false surprise). The
+ * cache key already discriminates these at cacheKey() via apiKeyPoolEntryId, so this
+ * mirrors that discriminator instead of inventing a second notion of identity.
+ */
+function providerObservationAccountKey(provider: string, config: OcxConfig): string {
+  const oauthAccountId = getAccountSet(provider)?.activeAccountId;
+  if (oauthAccountId !== undefined) return `${provider}\u0000${oauthAccountId}`;
+  const providerConfig = config.providers[provider];
+  const resolvedKey = typeof providerConfig?.apiKey === "string"
+    ? resolveEnvValue(providerConfig.apiKey)?.trim()
+    : undefined;
+  const keyId = resolvedKey ? apiKeyPoolEntryId(resolvedKey) : "default";
+  return `${provider}\u0000key:${keyId}`;
+}
+
+/** Test-only view of the observation account key. */
+export function providerObservationAccountKeyForTests(provider: string, config: OcxConfig): string {
+  return providerObservationAccountKey(provider, config);
+}
+
+function notifyProviderQuotaSnapshot(
+  reports: ReadonlyArray<ProviderQuotaReport>,
+  config: OcxConfig,
+): void {
+  if (reports.length === 0) return;
+  // Resolved here, synchronously, while the identity is still the one that produced these
+  // reports.
+  const observations = reports.map(report => ({
+    scope: report.provider,
+    accountKey: providerObservationAccountKey(report.provider, config),
+    quota: report.quota,
+  }));
+  pendingProviderObservation = pendingProviderObservation
+    .then(async () => {
+      const observer = await import("../quota/reset-observer");
+      if (!observer.hasQuotaResetSink()) return;
+      const { providerWindowObservations } = await import("../quota/window-mapping");
+      for (const observation of observations) {
+        observer.observeQuotaSnapshot({
+          scope: observation.scope,
+          accountKey: observation.accountKey,
+          windows: providerWindowObservations(observation.quota),
+        });
+      }
+    })
+    .catch(() => {
+      // Detection is best-effort: a quota refresh must never fail because of it. Swallowing
+      // here also keeps the chain alive — a rejected link would poison every later one.
+    });
+}
+
+/** Await the observation chain. Tests only: production never needs to join it. */
+export function flushProviderQuotaObservationsForTests(): Promise<void> {
+  return pendingProviderObservation;
+}
+
 export async function fetchProviderQuotaReports(config: OcxConfig, forceRefresh = false): Promise<ProviderQuotaResponse> {
   // A Pool report's cache signature and provider fetch must share one account snapshot.
   // Preserve force semantics when deciding whether that snapshot refreshes upstream data.
@@ -2568,6 +2866,7 @@ export async function fetchProviderQuotaReports(config: OcxConfig, forceRefresh
       const reports = response.reports.filter(item => mayCommitProviderQuotaKey(item.provider, writerGeneration));
       cache = { key, ts: Date.now(), response: { ...response, reports } };
       replaceCachedProviderQuotas(reports);
+      notifyProviderQuotaSnapshot(reports, config);
     }
     return response;
   })();
diff --git a/src/quota/reset-activation.ts b/src/quota/reset-activation.ts
new file mode 100644
index 0000000000..27487aaadf
--- /dev/null
+++ b/src/quota/reset-activation.ts
@@ -0,0 +1,81 @@
+/**
+ * Activation: install the delivery sink so a detected reset actually reaches the operator.
+ *
+ * Separate from the poller because the two are independent. `pollSeconds: 0` is a supported
+ * configuration — observe live quota refreshes, never probe on a timer — and in that mode the
+ * sink must still be installed or detection would run its bookkeeping and deliver nowhere.
+ *
+ * The sink is what the wp3 seams gate on: with none installed, observeQuotaSnapshot returns
+ * immediately and no baseline is even stored. So this module is the single switch that turns the
+ * whole subsystem from inert to live, which is why it re-reads config on every event rather than
+ * capturing it once — an operator who changes `kinds` should not have to restart.
+ */
+
+import type { QuotaResetEvent } from "./reset-detector";
+
+let activated = false;
+
+/**
+ * Install the sink when config asks for it, and remove it when config no longer does.
+ *
+ * Idempotent and cheap to call repeatedly: the enable check is the mtime-cached resolver, not a
+ * config parse. Returns whether a sink is now installed, for the caller's own reporting.
+ */
+export async function syncQuotaResetActivation(): Promise<boolean> {
+  const [{ isQuotaResetNotificationEnabled }, observer] = await Promise.all([
+    import("./reset-notify-config"),
+    import("./reset-observer"),
+  ]);
+
+  if (!isQuotaResetNotificationEnabled()) {
+    // Deliberately clears a previously installed sink. Disabling in config must actually stop
+    // delivery on the next check, not merely stop new observations.
+    if (activated) {
+      observer.setQuotaResetSink(null);
+      activated = false;
+    }
+    return false;
+  }
+
+  if (activated) return true;
+  observer.setQuotaResetSink(dispatch);
+  activated = true;
+  return true;
+}
+
+/**
+ * Hand one event to the sinks.
+ *
+ * Synchronous by signature (the observer contract) and fire-and-forget in body: delivery must
+ * never delay the quota write that triggered it. The observer has already claimed the
+ * idempotence key by the time this runs, so a failed delivery is not retried — see reset-sinks.
+ *
+ * Config is resolved HERE, per event, so a changed `kinds` list or webhook URL takes effect
+ * without a restart.
+ */
+function dispatch(event: QuotaResetEvent): void {
+  void (async () => {
+    try {
+      const [{ currentQuotaResetNotify }, { deliverQuotaResetEvent }] = await Promise.all([
+        import("./reset-notify-config"),
+        import("./reset-sinks"),
+      ]);
+      const config = currentQuotaResetNotify();
+      if (!config.enabled) return;
+      await deliverQuotaResetEvent(event, config);
+    } catch {
+      // Best-effort by contract. deliverQuotaResetEvent does not reject, so reaching here means
+      // the import itself failed, which the next event will retry.
+    }
+  })();
+}
+
+/** Test-only: forget activation state so a suite can re-activate against fresh config. */
+export function resetQuotaResetActivationForTests(): void {
+  activated = false;
+}
+
+/** Test-only: whether this module currently believes a sink is installed. */
+export function isQuotaResetActivatedForTests(): boolean {
+  return activated;
+}
diff --git a/src/quota/reset-detector.ts b/src/quota/reset-detector.ts
new file mode 100644
index 0000000000..dd48a79efe
--- /dev/null
+++ b/src/quota/reset-detector.ts
@@ -0,0 +1,305 @@
+/**
+ * Pure quota-reset detection: two consecutive observations of one usage window in, at most
+ * one reset event out.
+ *
+ * Nothing here reads a clock, a config, or the disk. `now` is a parameter so a test can
+ * place a deadline in the past without waiting for it, and so the same snapshot pair always
+ * yields the same answer.
+ *
+ * Design and the seven false-positive traps this guards against:
+ * devlog/_plan/260828_quota_reset_detection/000_plan.md
+ */
+
+/** One observed usage window, normalized away from provider-specific field names. */
+export type QuotaWindowObservation = {
+  /** Window identity: "5h", "weekly", "monthly", or "custom:<label>". */
+  readonly window: string;
+  /** 0-100 used percent. Absent when upstream stopped reporting this window. */
+  readonly percent?: number;
+  /** Epoch ms. Absent when upstream declares no clock, or declared a sentinel. */
+  readonly resetAt?: number;
+  /**
+   * Window length in seconds, when upstream states it.
+   *
+   * Used only to bound natural decay in a rolling window (see the surprise branch). Absent
+   * for providers that never declare a length; the label table then supplies a conservative
+   * default.
+   */
+  readonly windowSeconds?: number;
+  /**
+   * When this observation was taken, stamped by the observer as it stores the baseline.
+   *
+   * Needed because a rolling window's percent decays with WALL TIME, so distinguishing decay
+   * from a reset requires knowing how much time separates the two observations. Absent in
+   * baselines written before this field existed, and the decay bound is then skipped rather
+   * than guessed.
+   */
+  readonly observedAt?: number;
+};
+
+export type QuotaResetKind = "scheduled" | "surprise";
+
+export type QuotaResetEvent = {
+  readonly kind: QuotaResetKind;
+  /** "codex" or a provider name. Never an account identifier. */
+  readonly scope: string;
+  /** Non-identifying account discriminator; see quotaAccountTag. */
+  readonly accountTag: string;
+  readonly window: string;
+  readonly percentBefore?: number;
+  readonly percentAfter?: number;
+  readonly previousResetAt?: number;
+  readonly resetAt?: number;
+  /**
+   * When WE noticed, not when the reset happened.
+   *
+   * Observation cadence is bounded by the 5-minute provider cache TTL and the 10-minute
+   * per-account TTL, so the reset instant can only ever be bracketed between two
+   * observations. Naming this field `detectedAt` keeps that limitation visible to every
+   * consumer instead of implying a precision we do not have.
+   */
+  readonly detectedAt: number;
+  /** Idempotence key: scope|accountTag|window|resetAt. */
+  readonly key: string;
+};
+
+/**
+ * A drop smaller than this is rounding noise or a same-window correction, not a reset.
+ *
+ * Upstream percents are integers and a real window rollover drops by tens of points, so
+ * nothing genuine sits under this floor. It applies only to the surprise branch: a
+ * scheduled rollover is proven by its own expired deadline and needs no magnitude test.
+ */
+export const MIN_SURPRISE_DROP_PERCENT = 5;
+
+/**
+ * Account discriminator: stable for this install, unlinkable outside it.
+ *
+ * Events must distinguish accounts — a provider report is keyed by provider only, so an
+ * account switch would otherwise inherit the previous account's history — while carrying no
+ * account identity, because the payload crosses a webhook boundary to a third party.
+ *
+ * The salt is what makes the second half true. An unsalted `Bun.hash` of an email is
+ * brute-forceable in tens of guesses against a small, highly guessable input space, which
+ * would let a webhook recipient confirm-or-deny any guessed account. Salted, the tag is
+ * meaningless to anyone without the install salt, and still stable across restarts because
+ * the salt is persisted — which is what the durable idempotence key depends on.
+ *
+ * Not a cryptographic commitment: it defeats an offline dictionary attack by a payload
+ * recipient, which is the threat the privacy constraint names.
+ */
+export function quotaAccountTag(accountKey: string, salt: string): string {
+  return Bun.hash(`${salt}\u0000${accountKey}`).toString(36).slice(0, 8).padStart(8, "0");
+}
+
+export function quotaResetKey(input: {
+  readonly scope: string;
+  readonly accountTag: string;
+  readonly window: string;
+  readonly resetAt?: number;
+  readonly previousResetAt?: number;
+}): string {
+  // Prefer the NEW deadline: every later observation of the same post-reset window computes
+  // the same key, which is what makes repeated detection idempotent.
+  //
+  // Fall back to the deadline that just expired when upstream reports no new one. A bare
+  // "none" discriminator would collapse every clockless reset of one window onto a single
+  // key, so the first claim would permanently suppress all later ones.
+  const discriminator = input.resetAt ?? input.previousResetAt ?? "none";
+  return [input.scope, input.accountTag, input.window, discriminator].join("|");
+}
+
+/**
+ * Percent guard applied at this boundary.
+ *
+ * Both upstream normalizers clamp to 0-100, but a value outside that range means the payload
+ * bypassed them, and admitting a negative would manufacture an enormous apparent drop. Same
+ * philosophy as the resetAt guard below: re-check rather than trust the caller.
+ */
+function finitePercent(value: number | undefined): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return value >= 0 && value <= 100 ? value : undefined;
+}
+
+/**
+ * Epoch-ms guard applied at this boundary on purpose.
+ *
+ * The two callers normalize differently — src/providers/quota.ts:279 treats <= 0 as a
+ * sentinel and scales seconds to ms, while src/codex/quota.ts:192 admits 0 and does not
+ * scale — so the detector cannot trust either and re-checks here.
+ */
+function finiteResetAt(value: number | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * Decide whether one window transition is a reset.
+ *
+ * Returns null for every ambiguous case. The bias is deliberate: a missed notification is
+ * an inconvenience, while a false one trains the operator to ignore the channel.
+ */
+export function detectQuotaReset(input: {
+  readonly scope: string;
+  readonly accountTag: string;
+  readonly previous: QuotaWindowObservation | undefined;
+  readonly next: QuotaWindowObservation;
+  readonly now: number;
+}): QuotaResetEvent | null {
+  const { scope, accountTag, previous, next, now } = input;
+
+  // No baseline, no transition. This one line is what stops a cold start (writers do not
+  // hydrate from disk), a reauth row clear, a reconciliation delete, and an account switch
+  // from each manufacturing an event out of thin air.
+  if (!previous) return null;
+  if (previous.window !== next.window) return null;
+
+  const percentBefore = finitePercent(previous.percent);
+  const percentAfter = finitePercent(next.percent);
+  const previousResetAt = finiteResetAt(previous.resetAt);
+  const resetAt = finiteResetAt(next.resetAt);
+
+  const build = (kind: QuotaResetKind): QuotaResetEvent => ({
+    kind,
+    scope,
+    accountTag,
+    window: next.window,
+    ...(percentBefore !== undefined ? { percentBefore } : {}),
+    ...(percentAfter !== undefined ? { percentAfter } : {}),
+    ...(previousResetAt !== undefined ? { previousResetAt } : {}),
+    ...(resetAt !== undefined ? { resetAt } : {}),
+    detectedAt: now,
+    key: quotaResetKey({
+      scope,
+      accountTag,
+      window: next.window,
+      ...(resetAt !== undefined ? { resetAt } : {}),
+      ...(previousResetAt !== undefined ? { previousResetAt } : {}),
+    }),
+  });
+
+  // A window whose percent vanished says nothing about a reset: upstream simply stopped
+  // reporting it. Treating absence as 0% would fire on every degraded payload.
+  if (percentAfter === undefined) return null;
+
+  const deadlinePassed = previousResetAt !== undefined && now >= previousResetAt;
+
+  if (deadlinePassed) {
+    if (percentBefore !== undefined && percentAfter > percentBefore) return null;
+    // An expired deadline alone is NOT enough. src/codex/quota.ts:323-329 carries the
+    // previous burst tuple forward verbatim when a header write omits it, so a partial
+    // write reproduces the old deadline and the old percent exactly. Once wall-clock passes
+    // that copied deadline, "the clock expired" would fire on a snapshot where upstream
+    // said nothing at all — a false positive on the highest-frequency write path in the
+    // system (one per pooled response).
+    //
+    // Require corroboration that the window actually turned over: either usage fell, or
+    // upstream issued a new deadline. A byte-identical carried-forward window gives
+    // neither, so it stays silent.
+    const usageFell = percentBefore !== undefined && percentAfter < percentBefore;
+    const deadlineAdvanced = resetAt !== undefined && resetAt > previousResetAt!;
+    if (!usageFell && !deadlineAdvanced) return null;
+    return build("scheduled");
+  }
+
+  // Still inside the previous window, so quota coming back means upstream moved the window
+  // out of band.
+  //
+  // A material percent DROP is the only accepted evidence here. An advancing deadline is
+  // deliberately NOT sufficient, even though it looks like a fresh window: a ROLLING window
+  // (Anthropic's five_hour, Codex's burst window) reports a deadline that creeps forward on
+  // every poll by exactly the elapsed time, so "the deadline advanced" is true of every
+  // healthy observation of a rolling window and would fire continuously.
+  //
+  // Nothing is lost by requiring the drop. A surprise reset is worth telling an operator
+  // about because quota came BACK; if usage did not fall, none did, and there is nothing to
+  // report. The scheduled branch above can still accept an advancing deadline as evidence,
+  // because there the previous deadline had genuinely expired.
+  if (
+    previousResetAt !== undefined
+    && percentBefore !== undefined
+    && percentBefore - percentAfter >= MIN_SURPRISE_DROP_PERCENT
+    && !isRollingWindowCreep({
+      previousResetAt,
+      resetAt,
+      previousObservedAt: previous.observedAt,
+      now,
+    })
+  ) {
+    return build("surprise");
+  }
+
+  // A window with no deadline on either side is not evaluated. Several provider parsers
+  // never emit a reset clock at all (credit balances, prepaid pools), and a bare percent
+  // drop there is as likely to be a top-up or a plan change as a window rollover. Firing on
+  // it would make the channel noise; the honest answer is that those providers expose no
+  // window semantics to detect.
+  return null;
+}
+
+/**
+ * True when the deadline merely CREPT forward with the clock, which is what a rolling window
+ * does while nothing resets.
+ *
+ * A rolling window (Anthropic five_hour, Codex burst) has no rollover instant: usage ages out
+ * continuously, so its percent falls on its own and its deadline slides forward by roughly the
+ * elapsed time on every poll. MIN_SURPRISE_DROP_PERCENT only screens integer rounding, so a
+ * healthy rolling window fired false "surprise" events — measured: 88% -> 61% one hour into a
+ * 5h window, a 27-point drop with no reset involved.
+ *
+ * The discriminator is deadline MOVEMENT against elapsed time, not drop magnitude. Decay
+ * magnitude cannot be bounded from elapsed time alone, because the percent that ages out
+ * depends on WHEN the usage happened: an hour of idling can retire a large burst that all
+ * landed in one minute. Deadline movement behaves differently — while a window is merely
+ * rolling, its deadline advances by about the elapsed time, whereas a genuine out-of-band
+ * reset issues a deadline a FULL window into the future, jumping far beyond the elapsed gap.
+ *
+ * Fails OPEN (returns false, letting the event through) whenever the evidence is missing: no
+ * baseline timestamp, no deadline on either side, or a deadline that moved backwards. A
+ * missed reset is an inconvenience; a suppressed one on an unproven guess is a defect.
+ */
+function isRollingWindowCreep(input: {
+  readonly previousResetAt: number | undefined;
+  readonly resetAt: number | undefined;
+  readonly previousObservedAt: number | undefined;
+  readonly now: number;
+}): boolean {
+  const observedAt = finiteResetAt(input.previousObservedAt);
+  const previousResetAt = input.previousResetAt;
+  const resetAt = input.resetAt;
+  if (observedAt === undefined || previousResetAt === undefined || resetAt === undefined) {
+    return false;
+  }
+  const elapsedMs = input.now - observedAt;
+  if (elapsedMs <= 0) return false;
+  const deadlineShiftMs = resetAt - previousResetAt;
+  // A deadline that stood still or moved backwards is not creep. Standing still while usage
+  // fell is the clearest possible surprise-reset signature, so it must reach the operator.
+  if (deadlineShiftMs <= 0) return false;
+  // Creep tracks the clock. The 2x tolerance absorbs polling jitter and upstream rounding to
+  // whole minutes without approaching a real reset, which shifts the deadline by a whole
+  // window — hours, against a gap that is minutes on the observation paths that exist here.
+  return deadlineShiftMs <= elapsedMs * 2;
+}
+
+/** Pair two window lists by identity and yield every detected reset. */
+export function detectQuotaResets(input: {
+  readonly scope: string;
+  readonly accountTag: string;
+  readonly previous: ReadonlyArray<QuotaWindowObservation>;
+  readonly next: ReadonlyArray<QuotaWindowObservation>;
+  readonly now: number;
+}): QuotaResetEvent[] {
+  const before = new Map(input.previous.map(item => [item.window, item]));
+  const events: QuotaResetEvent[] = [];
+  for (const observation of input.next) {
+    const event = detectQuotaReset({
+      scope: input.scope,
+      accountTag: input.accountTag,
+      previous: before.get(observation.window),
+      next: observation,
+      now: input.now,
+    });
+    if (event) events.push(event);
+  }
+  return events;
+}
diff --git a/src/quota/reset-notify-config.ts b/src/quota/reset-notify-config.ts
new file mode 100644
index 0000000000..e783c53e66
--- /dev/null
+++ b/src/quota/reset-notify-config.ts
@@ -0,0 +1,162 @@
+/**
+ * Read-time resolution of the optional quotaResetNotify config section.
+ *
+ * Cached, because loadConfig is a readFileSync plus a full configSchema.safeParse with no
+ * memoization and the enable check runs once per pooled response — a config parse per request
+ * for a feature nobody enabled.
+ *
+ * Keyed on the config file's mtime and size, NOT on captureConfigGeneration. The generation
+ * counter only advances when state-store reconciliation runs
+ * (src/lib/state-store-sweeper.ts:149, reached from reconcileLiveStateStores on
+ * account/provider changes), so editing quotaResetNotify alone would never bump it and the
+ * cached answer would stay stale until an unrelated account edit happened to occur. A short
+ * TTL bounds the stat call so the hot path does not stat on every single write.
+ */
+
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "../config";
+import { getConfigDir } from "../config/paths";
+import type { QuotaResetKind } from "./reset-detector";
+
+export type ResolvedQuotaResetNotify = {
+  readonly enabled: boolean;
+  readonly kinds: ReadonlySet<QuotaResetKind>;
+  /** 0 means passive-only: observe live refreshes, never poll. */
+  readonly pollMs: number;
+  readonly webhookUrl?: string;
+  readonly allowPrivateNetwork: boolean;
+  readonly timeoutMs: number;
+  readonly command?: readonly string[];
+};
+
+const ALL_KINDS: ReadonlySet<QuotaResetKind> = new Set(["scheduled", "surprise"]);
+const DEFAULT_POLL_SECONDS = 900;
+/**
+ * Matches MIN_INTERVAL_MS in ./reset-poller. The two floors must move together: the resolver's
+ * value now reaches setInterval, so a lower floor here would be silently overridden by the
+ * poller and an accepted config value would not be the cadence that runs.
+ */
+const MIN_POLL_SECONDS = 600;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 30_000;
+
+const DISABLED: ResolvedQuotaResetNotify = Object.freeze({
+  enabled: false,
+  kinds: ALL_KINDS,
+  pollMs: 0,
+  allowPrivateNetwork: false,
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+});
+
+type RawNotify = {
+  enabled?: unknown;
+  kinds?: unknown;
+  pollSeconds?: unknown;
+  webhookUrl?: unknown;
+  allowPrivateNetwork?: unknown;
+  timeoutMs?: unknown;
+  command?: unknown;
+};
+
+function positiveInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+function nonBlankStrings(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter((item): item is string => typeof item === "string" && item.trim() !== "");
+  return out.length > 0 ? out : undefined;
+}
+
+export function resolveQuotaResetNotify(raw: unknown): ResolvedQuotaResetNotify {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return DISABLED;
+  const value = raw as RawNotify;
+
+  const webhookUrl = typeof value.webhookUrl === "string" && value.webhookUrl.trim() !== ""
+    ? value.webhookUrl.trim()
+    : undefined;
+  const command = nonBlankStrings(value.command);
+
+  // An "enabled" subsystem with nowhere to send is a misconfiguration. Reporting it as off
+  // keeps the default-OFF guarantee honest: no sink means no timer and no observation.
+  const enabled = value.enabled === true && (webhookUrl !== undefined || command !== undefined);
+  if (!enabled) return DISABLED;
+
+  const requestedKinds = Array.isArray(value.kinds)
+    ? value.kinds.filter((kind): kind is QuotaResetKind => kind === "scheduled" || kind === "surprise")
+    : [];
+  const kinds: ReadonlySet<QuotaResetKind> = requestedKinds.length > 0
+    ? new Set(requestedKinds)
+    : ALL_KINDS;
+
+  const pollSeconds = value.pollSeconds === 0
+    ? 0
+    : positiveInt(value.pollSeconds, DEFAULT_POLL_SECONDS, MIN_POLL_SECONDS, 24 * 60 * 60);
+
+  return Object.freeze({
+    enabled: true,
+    kinds,
+    pollMs: pollSeconds * 1_000,
+    ...(webhookUrl !== undefined ? { webhookUrl } : {}),
+    allowPrivateNetwork: value.allowPrivateNetwork === true,
+    timeoutMs: positiveInt(value.timeoutMs, DEFAULT_TIMEOUT_MS, 100, MAX_TIMEOUT_MS),
+    ...(command !== undefined ? { command } : {}),
+  });
+}
+
+/** Bounds how often the hot path stats the config file. */
+const STAT_TTL_MS = 5_000;
+
+type Cached = {
+  checkedAt: number;
+  signature: string;
+  resolved: ResolvedQuotaResetNotify;
+};
+
+let cached: Cached | null = null;
+
+/** mtime + size of the config file. Cheap, and changes on any edit including an in-place one. */
+function configSignature(): string {
+  try {
+    const stat = statSync(join(getConfigDir(), "config.json"));
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return "absent";
+  }
+}
+
+export function currentQuotaResetNotify(): ResolvedQuotaResetNotify {
+  const now = Date.now();
+  if (cached && now - cached.checkedAt < STAT_TTL_MS) return cached.resolved;
+
+  const signature = configSignature();
+  if (cached && cached.signature === signature) {
+    cached.checkedAt = now;
+    return cached.resolved;
+  }
+
+  let resolved = DISABLED;
+  try {
+    resolved = resolveQuotaResetNotify(
+      (loadConfig() as { quotaResetNotify?: unknown }).quotaResetNotify,
+    );
+  } catch {
+    // An unreadable config must not enable a notifier, and must not throw on a quota write.
+  }
+  cached = { checkedAt: now, signature, resolved };
+  return resolved;
+}
+
+export function isQuotaResetNotificationEnabled(): boolean {
+  return currentQuotaResetNotify().enabled;
+}
+
+export function resolveQuotaResetPollMs(): number {
+  return currentQuotaResetNotify().pollMs;
+}
+
+export function resetQuotaResetNotifyCacheForTests(): void {
+  cached = null;
+}
diff --git a/src/quota/reset-observer.ts b/src/quota/reset-observer.ts
new file mode 100644
index 0000000000..524e4de2e1
--- /dev/null
+++ b/src/quota/reset-observer.ts
@@ -0,0 +1,125 @@
+/**
+ * The one place a quota snapshot becomes a delivered reset notification.
+ *
+ * Kept behind a lazy import from both quota subsystems: src/codex/quota.ts and
+ * src/providers/quota.ts are both statically reachable from
+ * src/server/responses/core.ts, so a static edge here would load this module, its config
+ * resolution, and its sink registry into every install — the failure AGENTS.md documents for
+ * Compatibility Lab, where a six-hop chain pulled ~69 modules onto the core path.
+ *
+ * Never throws. A detection or delivery failure must not break the quota write that
+ * triggered it.
+ */
+
+import {
+  detectQuotaResets,
+  quotaAccountTag,
+  type QuotaResetEvent,
+  type QuotaWindowObservation,
+} from "./reset-detector";
+import {
+  claimQuotaReset,
+  forgetLastObservedWindows,
+  quotaResetAccountSalt,
+  recordQuotaResetEvent,
+  swapLastObservedWindows,
+} from "./reset-seen-store";
+
+export type QuotaResetSink = (event: QuotaResetEvent) => void;
+
+let sink: QuotaResetSink | null = null;
+
+/**
+ * Install the delivery sink. Core owns the slot; wp4 registers into it at activation.
+ *
+ * Until something registers, detection still runs its bookkeeping but delivers nowhere,
+ * which is what keeps the subsystem inert on a default install.
+ */
+export function setQuotaResetSink(next: QuotaResetSink | null): void {
+  sink = next;
+}
+
+/** True when a sink is installed. Used by the seams to skip work entirely. */
+export function hasQuotaResetSink(): boolean {
+  return sink !== null;
+}
+
+/**
+ * Observe one committed snapshot for a (scope, account) pair.
+ *
+ * The baseline comes from the detector's own persisted last-seen map, not from the caller:
+ * see swapLastObservedWindows for why neither upstream cache can supply one.
+ */
+export function observeQuotaSnapshot(input: {
+  readonly scope: string;
+  readonly accountKey: string;
+  readonly windows: ReadonlyArray<QuotaWindowObservation>;
+  readonly now?: number;
+}): QuotaResetEvent[] {
+  try {
+    if (!sink) return [];
+    if (input.windows.length === 0) return [];
+    const now = input.now ?? Date.now();
+    const accountTag = quotaAccountTag(input.accountKey, quotaResetAccountSalt());
+    // Stamp the observation time as it becomes the baseline. The detector needs the gap
+    // between two observations to tell a rolling window's natural decay from a real reset,
+    // and only this layer knows when the snapshot was taken.
+    const stamped = input.windows.map(window => ({ ...window, observedAt: now }));
+    const previous = swapLastObservedWindows(input.scope, accountTag, stamped);
+    if (!previous) return [];
+
+    const detected = detectQuotaResets({
+      scope: input.scope,
+      accountTag,
+      previous,
+      next: input.windows,
+      now,
+    });
+
+    const delivered: QuotaResetEvent[] = [];
+    for (const event of detected) {
+      // Claim BEFORE dispatch. A sink that fails must not cause a re-notification storm on
+      // the next poll, and two observers racing one transition must produce one notification.
+      if (!claimQuotaReset(event.key, now, event.resetAt)) continue;
+      recordQuotaResetEvent(event);
+      delivered.push(event);
+      try {
+        sink(event);
+      } catch {
+        // A sink is best-effort by contract; its failure is recorded by the sink layer.
+      }
+    }
+    return delivered;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Forget the baseline for a (scope, accountKey) whose quota row was deliberately cleared.
+ *
+ * Lives here rather than in the store because the account TAG is derived from the account
+ * key with the per-install salt, and callers hold the key, not the tag. Runs regardless of
+ * whether a sink is installed: a stale baseline written while notifications were enabled
+ * must not survive to fire a false reset after they are re-enabled.
+ *
+ * Never throws, for the same reason observeQuotaSnapshot does not: this is called from
+ * sign-out and reauth paths that must complete.
+ */
+export function forgetQuotaBaseline(input: {
+  readonly scope: string;
+  readonly accountKey?: string;
+}): void {
+  try {
+    if (input.accountKey === undefined) {
+      forgetLastObservedWindows(input.scope);
+      return;
+    }
+    forgetLastObservedWindows(
+      input.scope,
+      quotaAccountTag(input.accountKey, quotaResetAccountSalt()),
+    );
+  } catch {
+    // Best-effort: a failure here can only cost a re-baseline.
+  }
+}
diff --git a/src/quota/reset-poller.ts b/src/quota/reset-poller.ts
new file mode 100644
index 0000000000..43cfd4189f
--- /dev/null
+++ b/src/quota/reset-poller.ts
@@ -0,0 +1,160 @@
+/**
+ * Opt-in idle refresh so a reset is noticed while nobody is looking.
+ *
+ * This is load-bearing, not a convenience. fetchProviderQuotaReports has exactly one caller
+ * — the GET /api/provider-quotas route — so with no dashboard open and no CLI invocation it
+ * never runs, no second snapshot exists, and an overnight reset passes unobserved. That
+ * overnight case is the whole reason the subsystem exists.
+ *
+ * Shape follows src/storage/policy-scheduler.ts: a module-singleton unref'd interval whose
+ * config gate lives in the callee, so toggling `enabled` takes effect on the next tick
+ * without a restart (the rationale spelled out at src/oauth/token-guardian.ts:276).
+ */
+
+const DEFAULT_INTERVAL_MS = 15 * 60_000;
+/**
+ * Above the 5-minute provider cache TTL and the 10-minute per-account TTL, so one tick costs
+ * at most one upstream probe per window rather than hammering a quota endpoint that
+ * rate-limits (src/providers/quota.ts:1425 records an observed 429 under repeated probing).
+ */
+export const MIN_INTERVAL_MS = 10 * 60_000;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let detachShutdownHook: (() => void) | null = null;
+/** The bounded cadence the live timer was created with, so a tick can notice config drift. */
+let liveIntervalMs: number | null = null;
+/**
+ * Bumped by every start and stop. A tick captures it on entry and re-checks before publishing,
+ * so a probe still in flight when the poller stops cannot publish into the next generation.
+ */
+let generation = 0;
+/** setInterval does not skip a firing while the previous callback is still awaiting. */
+let inFlight = false;
+
+/** Number of ticks that have run. Test-only observability; carries no quota data. */
+let tickCount = 0;
+
+function boundedInterval(value: number): number {
+  return Math.max(MIN_INTERVAL_MS, Math.floor(value));
+}
+
+/** Re-arm the timer when the operator changed the cadence since it was created. */
+function restartIfCadenceChanged(configured: number): void {
+  if (timer === null || boundedInterval(configured) === liveIntervalMs) return;
+  stopQuotaResetPoller();
+  startQuotaResetPoller(configured);
+}
+
+async function tick(): Promise<void> {
+  // An interval firing while the previous probe is still awaiting would double the upstream
+  // load precisely when it is already slow.
+  if (inFlight) return;
+  inFlight = true;
+  const entryGeneration = generation;
+  try {
+    const { isQuotaResetNotificationEnabled, resolveQuotaResetPollMs } = await import(
+      "./reset-notify-config"
+    );
+    // Re-sync the sink on every tick, before the enable check bails out. This is what makes
+    // enabling or disabling notifications take effect without a restart: an install that starts
+    // with the section absent has no sink, and the seams therefore skip all work, so something
+    // has to notice the operator turned it on. Cheap — the resolver is mtime-cached.
+    const { syncQuotaResetActivation } = await import("./reset-activation");
+    await syncQuotaResetActivation();
+    if (!isQuotaResetNotificationEnabled()) return;
+    const configured = resolveQuotaResetPollMs();
+    if (configured === 0) return;
+    // A stop or restart landed while the config resolved: this tick no longer owns the timer,
+    // so it must neither count as a probe nor adopt a cadence for a generation that is gone.
+    if (entryGeneration !== generation) return;
+    // Adopt a changed cadence without a restart, which is why the config gate lives in the
+    // callee at all. Only while this tick still owns the timer.
+    restartIfCadenceChanged(configured);
+    tickCount += 1;
+    const [{ loadConfig }, { fetchProviderQuotaReports }] = await Promise.all([
+      import("../config"),
+      import("../providers/quota"),
+    ]);
+    // A stop or restart landed while this probe was in flight: the result belongs to a
+    // generation that no longer owns the timer, so it must not publish.
+    if (entryGeneration !== generation) return;
+    // Forced: an unforced call would be served from the 5-minute cache and produce no new
+    // observation at all.
+    await fetchProviderQuotaReports(loadConfig(), true);
+  } catch {
+    // A failed probe is not an error worth surfacing: the next tick tries again.
+  } finally {
+    inFlight = false;
+  }
+}
+
+/** Idempotent. A second call while running is a no-op, matching startStorageCleanupScheduler. */
+export function startQuotaResetPoller(intervalMs = DEFAULT_INTERVAL_MS): void {
+  if (timer) return;
+  const bounded = boundedInterval(intervalMs);
+  generation += 1;
+  liveIntervalMs = bounded;
+  timer = setInterval(() => void tick(), bounded);
+  // Never keep the process alive for a quota probe.
+  timer.unref?.();
+  void import("../lib/optional-shutdown-hooks")
+    .then(hooks => {
+      detachShutdownHook = hooks.registerOptionalShutdownHook(
+        "quota-reset-poller",
+        stopQuotaResetPoller,
+      );
+    })
+    .catch(() => {
+      // Without the hook the unref'd timer still cannot delay exit.
+    });
+}
+
+export function stopQuotaResetPoller(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+  liveIntervalMs = null;
+  generation += 1;
+  detachShutdownHook?.();
+  detachShutdownHook = null;
+}
+
+export function isQuotaResetPollerRunning(): boolean {
+  return timer !== null;
+}
+
+/**
+ * Adopt the operator's configured cadence at startup.
+ *
+ * The caller starts the poller synchronously with the default interval, because resolving the
+ * config here would mean a static edge to ../config from a module the quota boundary guard
+ * requires to have none. Resolving it through import() keeps that edge dynamic, at the cost of
+ * the timer running at the default for the few microtasks before this settles.
+ */
+export async function syncQuotaResetPollerCadence(): Promise<void> {
+  const { resolveQuotaResetPollMs } = await import("./reset-notify-config");
+  const configured = resolveQuotaResetPollMs();
+  // 0 is passive-only: tick() already returns before probing, and the timer stays unref'd.
+  if (configured === 0) return;
+  restartIfCadenceChanged(configured);
+}
+
+/** Test-only: run one tick synchronously rather than waiting out the interval. */
+export async function runQuotaResetPollerTickForTests(): Promise<void> {
+  await tick();
+}
+
+export function quotaResetPollerTickCountForTests(): number {
+  return tickCount;
+}
+
+/** Test-only: the bounded cadence the live timer is running at, or null when stopped. */
+export function quotaResetPollerIntervalForTests(): number | null {
+  return liveIntervalMs;
+}
+
+export function resetQuotaResetPollerForTests(): void {
+  stopQuotaResetPoller();
+  tickCount = 0;
+}
diff --git a/src/quota/reset-seen-store.ts b/src/quota/reset-seen-store.ts
new file mode 100644
index 0000000000..72cad7a876
--- /dev/null
+++ b/src/quota/reset-seen-store.ts
@@ -0,0 +1,385 @@
+/**
+ * Durable "already notified" ledger plus a bounded ring of recent reset events.
+ *
+ * Exactly-once has to hold across a restart, because the whole point of a surprise reset is
+ * that it happens while nobody is watching. An in-memory set would re-notify every reset
+ * whose window is still open the next time the proxy starts.
+ *
+ * Deliberately NOT stored in config.json: this is high-frequency job state, and
+ * mutatePersistedConfig fails closed when the config did not come from a file.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// Imported from the definition sites, NOT the ../config barrel. The barrel pulls 154 modules
+// (~430 KB) including combos, account-store, pool-rotation and cursor discovery; these two
+// cost 8. This store is reached from the once-per-pooled-response observation path, so the
+// barrel would work directly against the boundary guard wp5 adds.
+import { atomicWriteFile } from "../config/atomic-write";
+import { getConfigDir } from "../config/paths";
+import type { QuotaResetEvent, QuotaWindowObservation } from "./reset-detector";
+
+const STATE_FILENAME = "quota-reset-state.json";
+const PERSIST_DEBOUNCE_MS = 250;
+/**
+ * Longest a pending write may be deferred by continued activity. See schedulePersist.
+ */
+const MAX_PERSIST_DEFERRAL_MS = 1_000;
+
+/**
+ * Age floor for pruning a claimed key.
+ *
+ * 90 days, not 30: a monthly window's key is legitimately older than a month while still
+ * current, and pruning it would let the same reset notify twice.
+ */
+const CLAIM_MAX_AGE_MS = 90 * 24 * 60 * 60_000;
+const MAX_CLAIMS = 512;
+/**
+ * Hard ceiling for the claim map.
+ *
+ * MAX_CLAIMS is the soft budget, honoured by evicting settled claims. When every claim is
+ * still live there is nothing safe to evict, so without a hard stop the map — and the JSON
+ * rewritten beside it — grows without limit. At this ceiling we evict the furthest-future
+ * deadline and accept one theoretical duplicate, which is strictly better than unbounded growth.
+ */
+const HARD_MAX_CLAIMS = 2 * MAX_CLAIMS;
+const MAX_RING_EVENTS = 100;
+/** One row per (scope, accountTag). A large pool plus several providers stays well inside this. */
+const MAX_OBSERVED_SCOPES = 64;
+
+type ClaimRecord = {
+  /** When the claim was made. */
+  at: number;
+  /** The window deadline this claim belongs to; a future value means the claim is live. */
+  resetAt?: number;
+};
+
+type StateFile = {
+  version: 1;
+  claims: Record<string, ClaimRecord>;
+  events: QuotaResetEvent[];
+  /** Last observed windows per "scope\u0000accountTag". Absent in files written before this field. */
+  observed?: Record<string, QuotaWindowObservation[]>;
+  /** Per-install salt for account tagging. Created once, then stable. */
+  accountSalt?: string;
+};
+
+const claims = new Map<string, ClaimRecord>();
+let ring: QuotaResetEvent[] = [];
+const observed = new Map<string, QuotaWindowObservation[]>();
+let hydrated = false;
+let persistTimer: ReturnType<typeof setTimeout> | null = null;
+/** When the currently pending debounced write was FIRST scheduled, or null if none is pending. */
+let firstDeferredPersistAt: number | null = null;
+let accountSalt: string | null = null;
+
+function statePath(): string {
+  return join(getConfigDir(), STATE_FILENAME);
+}
+
+function hydrate(): void {
+  if (hydrated) return;
+  hydrated = true;
+  try {
+    const path = statePath();
+    if (!existsSync(path)) return;
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as StateFile;
+    if (!parsed || parsed.version !== 1) return;
+    if (parsed.claims && typeof parsed.claims === "object") {
+      for (const [key, record] of Object.entries(parsed.claims)) {
+        if (!record || typeof record.at !== "number") continue;
+        claims.set(key, {
+          at: record.at,
+          ...(typeof record.resetAt === "number" ? { resetAt: record.resetAt } : {}),
+        });
+      }
+    }
+    if (Array.isArray(parsed.events)) ring = parsed.events.slice(-MAX_RING_EVENTS);
+    if (parsed.observed && typeof parsed.observed === "object") {
+      for (const [key, windows] of Object.entries(parsed.observed)) {
+        if (Array.isArray(windows)) observed.set(key, windows);
+      }
+    }
+    if (typeof parsed.accountSalt === "string" && parsed.accountSalt.length >= 16) {
+      accountSalt = parsed.accountSalt;
+    }
+  } catch {
+    // A corrupt or partially written cache must never break a quota refresh. Starting empty
+    // risks one duplicate notification; throwing here would break the write that triggered us.
+    claims.clear();
+    ring = [];
+    observed.clear();
+  }
+}
+
+/**
+ * Per-install salt, created on first use and persisted.
+ *
+ * Without it an account tag is a bare unkeyed hash of an email — brute-forceable in tens of
+ * guesses, which turns the webhook payload into an account-identity oracle for whoever
+ * receives it. Salted, the tag stays stable for this install (so the persisted idempotence
+ * key still works across restarts) and is unlinkable to anyone without the salt.
+ */
+export function quotaResetAccountSalt(): string {
+  hydrate();
+  if (accountSalt) return accountSalt;
+  accountSalt = crypto.randomUUID().replaceAll("-", "");
+  persistNow();
+  return accountSalt;
+}
+
+function stateFileBody(): StateFile {
+  return {
+    version: 1,
+    claims: Object.fromEntries(claims),
+    events: ring,
+    observed: Object.fromEntries(observed),
+    ...(accountSalt !== null ? { accountSalt } : {}),
+  };
+}
+
+/**
+ * Write immediately, for anything whose loss breaks correctness.
+ *
+ * A claim MUST NOT ride the debounce: the timer is unref'd, so a process exiting within
+ * 250 ms of claiming — the common case when detection runs on the last pooled request before
+ * shutdown — never writes it, and the next start re-notifies. That is precisely the
+ * across-a-restart guarantee this store exists for, and a shutdown hook would not cover SIGKILL.
+ *
+ * Returns whether the write actually landed. The error is still swallowed rather than thrown —
+ * a quota observation must not fail on a full disk — but a caller that treats success as
+ * "durably claimed" needs to be told the difference.
+ */
+function persistNow(): boolean {
+  if (persistTimer) {
+    clearTimeout(persistTimer);
+    persistTimer = null;
+  }
+  firstDeferredPersistAt = null;
+  try {
+    atomicWriteFile(statePath(), `${JSON.stringify(stateFileBody())}\n`);
+    return true;
+  } catch {
+    // Best-effort persistence only.
+    return false;
+  }
+}
+
+/**
+ * Debounce with a MAXIMUM STALENESS cap.
+ *
+ * A plain re-arming debounce is starvable: it clears and re-sets the timer on every
+ * observation, so any write cadence faster than the debounce pushes the deadline out forever.
+ * Measured on the unfixed version: 75 observations at 40 ms intervals produced ZERO disk writes,
+ * and 200 at 10 ms also produced zero. A busy pooled install that is then SIGKILLed (container
+ * stop, OOM) loses its entire baseline and re-baselines on restart, silently missing any reset
+ * that spans the gap — which defeats the across-a-restart guarantee this store exists for.
+ *
+ * So the deferral is bounded: once a write has been pending for MAX_PERSIST_DEFERRAL_MS, the
+ * next call writes immediately instead of deferring again. At 0.29 ms per serialize-and-write,
+ * a forced write every second under sustained load costs nothing measurable.
+ *
+ * Claims deliberately do NOT use this path — they write synchronously, because an unref'd timer
+ * cannot be trusted to fire before process exit.
+ */
+function schedulePersist(): void {
+  const now = Date.now();
+  if (firstDeferredPersistAt === null) firstDeferredPersistAt = now;
+  else if (now - firstDeferredPersistAt >= MAX_PERSIST_DEFERRAL_MS) {
+    // persistNow clears the timer and resets the window below.
+    persistNow();
+    return;
+  }
+  if (persistTimer) clearTimeout(persistTimer);
+  persistTimer = setTimeout(() => {
+    persistTimer = null;
+    firstDeferredPersistAt = null;
+    try {
+      atomicWriteFile(statePath(), `${JSON.stringify(stateFileBody())}\n`);
+    } catch {
+      // Best-effort persistence, matching the codex quota cache.
+    }
+  }, PERSIST_DEBOUNCE_MS);
+  persistTimer.unref?.();
+}
+
+/**
+ * Drop claims that are both old and settled. A live deadline is never pruned.
+ *
+ * `now` comes from the wall clock, not from the caller's `at`: a backdated or clock-skewed
+ * claim must not change the retention of unrelated keys.
+ */
+function prune(now = Date.now()): void {
+  for (const [key, record] of claims) {
+    // A claim with no deadline is UNKNOWN, not settled. Clockless windows are the common case
+    // for credit-balance providers, so treating them as settled would make them the first
+    // thing evicted. They still age out below, just without that preference.
+    if (record.resetAt === undefined || record.resetAt > now) continue;
+    if (now - record.at <= CLAIM_MAX_AGE_MS) continue;
+    claims.delete(key);
+  }
+  for (const [key, record] of claims) {
+    if (record.resetAt !== undefined) continue;
+    if (now - record.at <= CLAIM_MAX_AGE_MS) continue;
+    claims.delete(key);
+  }
+  if (claims.size <= MAX_CLAIMS) return;
+  // Over budget: evict the oldest SETTLED claims only. Evicting a live one would trade a
+  // memory bound for a duplicate notification, which is the bug this store prevents.
+  const settled = [...claims.entries()]
+    .filter(([, record]) => record.resetAt === undefined || record.resetAt <= now)
+    .sort((left, right) => left[1].at - right[1].at);
+  for (const [key] of settled) {
+    if (claims.size <= MAX_CLAIMS) break;
+    claims.delete(key);
+  }
+  if (claims.size <= HARD_MAX_CLAIMS) return;
+  // Every remaining claim is live. Evict the furthest-future deadlines first: least likely to
+  // be re-observed soon, so a duplicate there is least disruptive.
+  const live = [...claims.entries()].sort(
+    (left, right) => (right[1].resetAt ?? 0) - (left[1].resetAt ?? 0),
+  );
+  for (const [key] of live) {
+    if (claims.size <= HARD_MAX_CLAIMS) break;
+    claims.delete(key);
+  }
+}
+
+/**
+ * Atomically claim a reset key. Returns true for the FIRST caller only.
+ *
+ * One synchronous check-and-set rather than a separate has/mark pair: a poller tick and a
+ * live pooled response can observe the same transition, and two callers that both read
+ * "unseen" would both notify. There is no await inside, so with Bun's single-threaded turn
+ * semantics this is indivisible with respect to other observers.
+ */
+export function claimQuotaReset(key: string, at: number, resetAt?: number): boolean {
+  hydrate();
+  if (claims.has(key)) return false;
+  claims.set(key, { at, ...(resetAt !== undefined ? { resetAt } : {}) });
+  prune();
+  // prune() can evict the claim just added — an already-past deadline older than
+  // CLAIM_MAX_AGE_MS qualifies — and an evicted claim is not a claim.
+  if (!claims.has(key)) return false;
+  // Synchronous: a lost claim means a duplicate notification after restart, and claims are
+  // rare (one per real reset), so the write cost is irrelevant.
+  // A failed write is reported rather than swallowed: the caller reads true as "safe to
+  // dispatch", and an unpersisted claim re-notifies on the next start.
+  return persistNow();
+}
+
+/** Read-only probe. Never used to gate a notification — see claimQuotaReset. */
+export function hasSeenQuotaReset(key: string): boolean {
+  hydrate();
+  return claims.has(key);
+}
+
+export function recordQuotaResetEvent(event: QuotaResetEvent): void {
+  hydrate();
+  ring.push(event);
+  if (ring.length > MAX_RING_EVENTS) ring = ring.slice(-MAX_RING_EVENTS);
+  schedulePersist();
+}
+
+/** Recent events, newest first. */
+export function listRecentQuotaResetEvents(limit = MAX_RING_EVENTS): QuotaResetEvent[] {
+  hydrate();
+  const bounded = Math.max(1, Math.min(limit, MAX_RING_EVENTS));
+  return [...ring].reverse().slice(0, bounded);
+}
+
+function observedKey(scope: string, accountTag: string): string {
+  return `${scope}\u0000${accountTag}`;
+}
+
+/**
+ * Store the newly observed windows for one (scope, accountTag) and return what was there
+ * before, or undefined on the first ever observation.
+ *
+ * The detector owns this map rather than borrowing a caller's previous value, because
+ * neither upstream cache can supply one reliably. The provider report cache keys itself on a
+ * digest that INCLUDES quota values and updatedAt (src/providers/quota.ts:193 via :155), so
+ * its `previous` is empty precisely when a reset happened; and it is process-memory only, so
+ * it has no answer at all after a restart. This map is keyed by identity and persisted.
+ */
+export function swapLastObservedWindows(
+  scope: string,
+  accountTag: string,
+  windows: ReadonlyArray<QuotaWindowObservation>,
+): ReadonlyArray<QuotaWindowObservation> | undefined {
+  hydrate();
+  const key = observedKey(scope, accountTag);
+  const previous = observed.get(key);
+  // Delete before set so the row moves to the END of the insertion order, making this a
+  // true LRU. Re-setting an existing key does NOT move it in a Map, so without the delete
+  // the eviction below removed the EARLIEST-INSERTED row — which on a real install is the
+  // long-lived codex account observed on every response, while 63 transient rows survived.
+  // Measured: the hottest scope was evicted and its next genuine scheduled reset was
+  // silently missed, because a re-baselined row has no previous value to diff against.
+  observed.delete(key);
+  observed.set(key, windows.map(window => ({ ...window })));
+  if (observed.size > MAX_OBSERVED_SCOPES) {
+    // Least-recently-observed first. Evicting only costs a re-baseline, never a duplicate
+    // notification, because the claim ledger is separate — but a re-baseline DOES cost the
+    // next reset on that row, which is why picking the genuinely abandoned row matters.
+    const oldest = observed.keys().next();
+    if (!oldest.done && oldest.value !== key) observed.delete(oldest.value);
+  }
+  schedulePersist();
+  return previous;
+}
+
+/**
+ * Forget the baseline for one (scope, accountTag), or for every scope when no tag is given.
+ *
+ * Called when a quota row is deliberately cleared — reauth, sign-out, account removal. The
+ * quota row and this baseline live in different files, so clearing only the former left the
+ * observer holding the pre-clear percentages: the first fresh write after a reauth of a used
+ * account then read as a surprise reset (measured 91% -> 0%). The existing regression test
+ * missed it because it also called resetQuotaResetStoreForTests(), which real reauth does
+ * not do — the test simulated something that never happens.
+ *
+ * Deliberately does NOT touch the claim ledger. A cleared row must not re-notify a reset it
+ * already reported, and claims are what prevent that.
+ */
+export function forgetLastObservedWindows(scope: string, accountTag?: string): void {
+  hydrate();
+  if (accountTag !== undefined) {
+    if (!observed.delete(observedKey(scope, accountTag))) return;
+    schedulePersist();
+    return;
+  }
+  // No tag: the caller cleared everything for this scope. The account tag is a salted hash,
+  // so it cannot be reversed — matching on the scope prefix is the only available form.
+  const prefix = `${scope}\u0000`;
+  let removed = false;
+  for (const key of [...observed.keys()]) {
+    if (key.startsWith(prefix)) removed = observed.delete(key) || removed;
+  }
+  if (removed) schedulePersist();
+}
+
+/** Test-only: forget in-memory state so the next call re-reads OPENCODEX_HOME. */
+export function resetQuotaResetStoreForTests(): void {
+  claims.clear();
+  ring = [];
+  observed.clear();
+  hydrated = false;
+  accountSalt = null;
+  if (persistTimer) {
+    clearTimeout(persistTimer);
+    persistTimer = null;
+  }
+  firstDeferredPersistAt = null;
+}
+
+/** Test-only: flush the debounced write immediately. */
+export function flushQuotaResetStoreForTests(): void {
+  persistNow();
+}
+
+/** Test-only: claim-map size, for asserting retention bounds. Exposes no keys. */
+export function claimCountForTests(): number {
+  hydrate();
+  return claims.size;
+}
diff --git a/src/quota/reset-sinks.ts b/src/quota/reset-sinks.ts
new file mode 100644
index 0000000000..7fe395830a
--- /dev/null
+++ b/src/quota/reset-sinks.ts
@@ -0,0 +1,199 @@
+/**
+ * Delivery sinks for a detected quota reset: an HTTP webhook and a local command.
+ *
+ * Both are best-effort and independently isolated. Neither ever throws to the caller, and one
+ * failing never suppresses the other — a reset notification is a courtesy, and a courtesy that
+ * can break the quota write that triggered it is a defect.
+ *
+ * There is deliberately NO retry. The wp3 observer claims the idempotence key before dispatch,
+ * so a retry here could only ever duplicate a delivery the ledger already considers done; and a
+ * reset notification is interesting only while it is fresh.
+ *
+ * Imported lazily by the activation path, never statically from a core file: this module
+ * reaches the destination policy and the config barrel, and
+ * tests/usage/quota-reset-core-boundary.test.ts enforces that none of that lands on the request path.
+ */
+
+import { signalWithTimeout } from "../lib/abort";
+import { assertUrlResolvesPublic } from "../lib/destination-policy";
+import { cancelResponseBodyBestEffort } from "../lib/upstream-retry";
+import type { QuotaResetEvent } from "./reset-detector";
+import type { ResolvedQuotaResetNotify } from "./reset-notify-config";
+
+export type QuotaResetSinkName = "webhook" | "command";
+
+/**
+ * Outcome of one delivery attempt.
+ *
+ * `reason` is a CLOSED UNION on purpose. An upstream body, a resolved address, or the webhook
+ * URL itself would all be sensitive — the URL is the credential for Slack and Discord — and this
+ * value reaches logs and the management API.
+ */
+export type QuotaResetDeliveryResult = {
+  readonly sink: QuotaResetSinkName;
+  readonly ok: boolean;
+  readonly reason?: "blocked-destination" | "timeout" | "http-error" | "spawn-failed";
+};
+
+/**
+ * The delivered payload.
+ *
+ * Closed-union labels and numbers only: no email, no account id, no token, no filesystem path,
+ * no URL. `accountTag` is a salted hash whose salt never leaves the install.
+ *
+ * The TYPE is the enforcement. `bun run privacy:scan` reads repository text, not runtime output,
+ * so it cannot check this — stating the obligation in the type is what keeps a later field
+ * addition honest.
+ */
+type QuotaResetPayload = {
+  readonly type: "quota_reset";
+  readonly kind: QuotaResetEvent["kind"];
+  readonly scope: string;
+  readonly accountTag: string;
+  readonly window: string;
+  readonly percentBefore?: number;
+  readonly percentAfter?: number;
+  readonly previousResetAt?: number;
+  readonly resetAt?: number;
+  readonly detectedAt: number;
+};
+
+/**
+ * Build the payload by NAMING every field, never by spreading the event.
+ *
+ * A spread would silently forward whatever the detector gains next — including the internal
+ * idempotence `key`, which encodes the scope and tag and has no business crossing a webhook
+ * boundary to a third party.
+ */
+function payloadFor(event: QuotaResetEvent): QuotaResetPayload {
+  return {
+    type: "quota_reset",
+    kind: event.kind,
+    scope: event.scope,
+    accountTag: event.accountTag,
+    window: event.window,
+    ...(event.percentBefore !== undefined ? { percentBefore: event.percentBefore } : {}),
+    ...(event.percentAfter !== undefined ? { percentAfter: event.percentAfter } : {}),
+    ...(event.previousResetAt !== undefined ? { previousResetAt: event.previousResetAt } : {}),
+    ...(event.resetAt !== undefined ? { resetAt: event.resetAt } : {}),
+    detectedAt: event.detectedAt,
+  };
+}
+
+/** Test seam for the payload contract, so a test cannot drift from what is actually sent. */
+export function quotaResetPayloadForTests(event: QuotaResetEvent): unknown {
+  return payloadFor(event);
+}
+
+async function deliverWebhook(
+  json: string,
+  config: ResolvedQuotaResetNotify,
+): Promise<QuotaResetDeliveryResult> {
+  const url = config.webhookUrl;
+  if (url === undefined) return { sink: "webhook", ok: true };
+
+  // An operator-supplied URL is an SSRF surface: this process can reach loopback services and
+  // cloud metadata endpoints that the operator's browser cannot. The repository already owns
+  // this policy, so the check is reused rather than reinvented. Self-hosted receivers opt in.
+  if (!config.allowPrivateNetwork) {
+    try {
+      await assertUrlResolvesPublic(url);
+    } catch {
+      return { sink: "webhook", ok: false, reason: "blocked-destination" };
+    }
+  }
+
+  const timeout = signalWithTimeout(config.timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: json,
+      // The destination check above validated THIS url. Following a redirect would send the
+      // payload somewhere unvalidated, so a hop is refused rather than re-validated: the
+      // operator can configure the final URL directly, which is the stance
+      // providerRedirectError already takes for provider traffic.
+      redirect: "manual",
+      signal: timeout.signal,
+    });
+    // Nothing reads the body, and an undrained response holds the connection open.
+    cancelResponseBodyBestEffort(response);
+    if (response.status >= 300 && response.status < 400) {
+      return { sink: "webhook", ok: false, reason: "blocked-destination" };
+    }
+    if (!response.ok) return { sink: "webhook", ok: false, reason: "http-error" };
+    return { sink: "webhook", ok: true };
+  } catch (error) {
+    const aborted = error instanceof Error
+      && (error.name === "TimeoutError" || error.name === "AbortError");
+    return { sink: "webhook", ok: false, reason: aborted ? "timeout" : "http-error" };
+  } finally {
+    // Without this the timer keeps the event loop alive for up to timeoutMs after a fast
+    // response, which on a short-lived CLI invocation delays exit for no reason.
+    timeout.cleanup();
+  }
+}
+
+async function deliverCommand(
+  json: string,
+  config: ResolvedQuotaResetNotify,
+): Promise<QuotaResetDeliveryResult> {
+  const command = config.command;
+  if (command === undefined || command.length === 0) return { sink: "command", ok: true };
+
+  try {
+    // argv form, NOT a shell string: an operator-supplied command must not become an injection
+    // surface, and there is no shell here to interpret metacharacters.
+    const proc = Bun.spawn([...command], {
+      // Encoded bytes, not a string. Bun 1.4.0 throws ERR_INVALID_ARG_TYPE on a plain string
+      // here, and no existing call site in this repository pipes stdin, so there was no
+      // in-repo precedent to copy.
+      stdin: new TextEncoder().encode(json),
+      // The event is already delivered by writing it to stdin; the command's own chatter is not
+      // ours to relay, and inheriting it would interleave into whatever is on the terminal.
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) return { sink: "command", ok: false, reason: "spawn-failed" };
+    return { sink: "command", ok: true };
+  } catch {
+    // A missing binary or a permission error. The message could contain a filesystem path, so
+    // it is deliberately not carried through.
+    return { sink: "command", ok: false, reason: "spawn-failed" };
+  }
+}
+
+/**
+ * Deliver one event to every configured sink.
+ *
+ * Sinks run CONCURRENTLY and are settled independently, so a webhook that sits until its
+ * timeout does not delay the local command. Never rejects.
+ */
+export async function deliverQuotaResetEvent(
+  event: QuotaResetEvent,
+  config: ResolvedQuotaResetNotify,
+): Promise<QuotaResetDeliveryResult[]> {
+  // Filtered here as well as at the sink registration, because this function is the public
+  // entry point and a caller should not be able to deliver a kind the operator excluded.
+  if (!config.kinds.has(event.kind)) return [];
+
+  const json = JSON.stringify(payloadFor(event));
+  const attempts: Array<Promise<QuotaResetDeliveryResult>> = [];
+  if (config.webhookUrl !== undefined) attempts.push(deliverWebhook(json, config));
+  if (config.command !== undefined && config.command.length > 0) {
+    attempts.push(deliverCommand(json, config));
+  }
+  if (attempts.length === 0) return [];
+
+  const settled = await Promise.allSettled(attempts);
+  return settled.map((result, index) => {
+    if (result.status === "fulfilled") return result.value;
+    // Both helpers catch internally, so this is unreachable in practice — but a rejected
+    // promise must still not propagate out of a best-effort notifier.
+    const sink: QuotaResetSinkName = index === 0 && config.webhookUrl !== undefined
+      ? "webhook"
+      : "command";
+    return { sink, ok: false, reason: "spawn-failed" };
+  });
+}
diff --git a/src/quota/window-mapping.ts b/src/quota/window-mapping.ts
new file mode 100644
index 0000000000..38c2946553
--- /dev/null
+++ b/src/quota/window-mapping.ts
@@ -0,0 +1,106 @@
+/**
+ * Provider- and Codex-specific quota shapes mapped to the detector's neutral window list.
+ *
+ * Separate from the detector so the detector stays free of any dependency on either quota
+ * subsystem's types, and separate from the observer so the seams can build observations
+ * without loading the sink registry.
+ */
+
+import type { QuotaWindowObservation } from "./reset-detector";
+
+type CodexLikeQuota = {
+  shortPercent?: number;
+  shortResetAt?: number;
+  shortWindowSeconds?: number;
+  weeklyPercent?: number;
+  weeklyResetAt?: number;
+  monthlyPercent?: number;
+  monthlyResetAt?: number;
+  customWindows?: ReadonlyArray<{ label: string; percent: number; resetAt?: number }>;
+};
+
+type ProviderLikeQuota = {
+  fiveHourPercent?: number;
+  fiveHourResetAt?: number;
+  weeklyPercent?: number;
+  weeklyResetAt?: number;
+  monthlyPercent?: number;
+  monthlyResetAt?: number;
+  customWindows?: ReadonlyArray<{ label: string; percent: number; resetAt?: number }>;
+};
+
+function window(
+  label: string,
+  percent: number | undefined,
+  resetAt: number | undefined,
+  windowSeconds?: number,
+): QuotaWindowObservation | null {
+  // A window with neither a percent nor a clock carries no information. Emitting it would
+  // only create a baseline that can never produce a transition.
+  if (percent === undefined && resetAt === undefined) return null;
+  return {
+    window: label,
+    ...(percent !== undefined ? { percent } : {}),
+    ...(resetAt !== undefined ? { resetAt } : {}),
+    ...(typeof windowSeconds === "number" && Number.isFinite(windowSeconds) && windowSeconds > 0
+      ? { windowSeconds }
+      : {}),
+  };
+}
+
+/**
+ * Nominal lengths for the fixed labels, in seconds.
+ *
+ * The detector uses a window length only to bound how much of a percent drop natural decay
+ * can explain in a ROLLING window. Upstream states a length for the short window
+ * (shortWindowSeconds) but not for the others, so these supply it. Weekly and monthly are
+ * calendar-anchored rather than rolling on every provider observed so far, but stating a
+ * length is still the conservative choice: it can only suppress a drop that is small relative
+ * to the elapsed share of a WEEK, which no genuine reset is.
+ */
+const NOMINAL_WINDOW_SECONDS: Readonly<Record<string, number>> = {
+  "5h": 5 * 3600,
+  weekly: 7 * 24 * 3600,
+  monthly: 30 * 24 * 3600,
+};
+
+function customWindows(
+  entries: ReadonlyArray<{ label: string; percent: number; resetAt?: number }> | undefined,
+): QuotaWindowObservation[] {
+  if (!entries) return [];
+  const out: QuotaWindowObservation[] = [];
+  for (const entry of entries) {
+    if (typeof entry?.label !== "string") continue;
+    const mapped = window(`custom:${entry.label}`, entry.percent, entry.resetAt);
+    if (mapped) out.push(mapped);
+  }
+  return out;
+}
+
+/** Windows absent from the snapshot are omitted, never zero-filled: absence is not 0%. */
+export function codexWindowObservations(quota: CodexLikeQuota): QuotaWindowObservation[] {
+  const out: QuotaWindowObservation[] = [];
+  for (const mapped of [
+    // Prefer the length upstream states for the short window; fall back to the nominal 5h.
+    window("5h", quota.shortPercent, quota.shortResetAt, quota.shortWindowSeconds ?? NOMINAL_WINDOW_SECONDS["5h"]),
+    window("weekly", quota.weeklyPercent, quota.weeklyResetAt, NOMINAL_WINDOW_SECONDS["weekly"]),
+    window("monthly", quota.monthlyPercent, quota.monthlyResetAt, NOMINAL_WINDOW_SECONDS["monthly"]),
+  ]) {
+    if (mapped) out.push(mapped);
+  }
+  out.push(...customWindows(quota.customWindows));
+  return out;
+}
+
+export function providerWindowObservations(quota: ProviderLikeQuota): QuotaWindowObservation[] {
+  const out: QuotaWindowObservation[] = [];
+  for (const mapped of [
+    window("5h", quota.fiveHourPercent, quota.fiveHourResetAt, NOMINAL_WINDOW_SECONDS["5h"]),
+    window("weekly", quota.weeklyPercent, quota.weeklyResetAt, NOMINAL_WINDOW_SECONDS["weekly"]),
+    window("monthly", quota.monthlyPercent, quota.monthlyResetAt, NOMINAL_WINDOW_SECONDS["monthly"]),
+  ]) {
+    if (mapped) out.push(mapped);
+  }
+  out.push(...customWindows(quota.customWindows));
+  return out;
+}
diff --git a/src/server/background-lifecycle.ts b/src/server/background-lifecycle.ts
index 5625d6b67b..17a7a7fe57 100644
--- a/src/server/background-lifecycle.ts
+++ b/src/server/background-lifecycle.ts
@@ -10,6 +10,7 @@ import {
   startStorageCleanupScheduler,
   stopStorageCleanupScheduler,
 } from "../storage/policy-scheduler";
+import { startQuotaResetPoller, stopQuotaResetPoller } from "../quota/reset-poller";
 import {
   cancelQueuedStorageWorkerSpawns,
   drainStorageWorkers,
@@ -59,11 +60,31 @@ function startProcessLoops(applyPolicy: PolicyApply): ProcessLoops {
     stateStoreSweeper = startStateStoreSweeper();
     setLivePolicyOwner(applyPolicy);
     startStorageCleanupScheduler();
+    // Opt-in: the tick itself is a no-op unless config.quotaResetNotify is enabled with a
+    // sink, and the interval is unref'd, so a default install pays one dormant timer.
+    startQuotaResetPoller();
+    // The configured cadence is resolved out of band: reading it here would put a static edge
+    // to the config barrel on the load-time path the quota boundary guard pins.
+    void import("../quota/reset-poller")
+      .then(poller => poller.syncQuotaResetPollerCadence())
+      .catch(() => {
+        // The next tick adopts it.
+      });
+    // Install the delivery sink now rather than waiting out the first poll interval, which is 15
+    // minutes by default. Without this, an enabled install would observe nothing for its first
+    // quarter hour — including the live request path, which is gated on the sink existing.
+    // Fire-and-forget: startup must not await an optional subsystem.
+    void import("../quota/reset-activation")
+      .then(activation => activation.syncQuotaResetActivation())
+      .catch(() => {
+        // The next poll tick retries.
+      });
     return { memoryWatchdog, stateStoreSweeper };
   } catch (error) {
     memoryWatchdog?.stop();
     stateStoreSweeper?.stop();
     stopStorageCleanupScheduler();
+    stopQuotaResetPoller();
     setLivePolicyOwner(null);
     throw error;
   }
@@ -75,6 +96,7 @@ function stopProcessLoops(): void {
   loops?.memoryWatchdog.stop();
   loops?.stateStoreSweeper.stop();
   stopStorageCleanupScheduler();
+  stopQuotaResetPoller();
   setLivePolicyOwner(null);
 }
 
@@ -179,4 +201,4 @@ export function acquireServerBackgroundLifecycle(
       releaseFlight = Promise.resolve();
     },
   };
-}
\ No newline at end of file
+}
diff --git a/src/server/management-api.ts b/src/server/management-api.ts
index 57830feb26..f5478a8077 100644
--- a/src/server/management-api.ts
+++ b/src/server/management-api.ts
@@ -132,6 +132,17 @@ async function handleLabRoutesOnDemand(ctx: ManagementContext): Promise<Response
   return handleLabRoutes(ctx);
 }
 
+/**
+ * Lazy like the Lab and routing-profile handlers, and for the same recorded reason: this file is
+ * mounted for every dashboard request, so a static import would put the quota-reset store and
+ * its config resolution on all of them.
+ */
+async function handleQuotaResetRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== "/api/quota-resets") return null;
+  const { handleQuotaResetRoutes } = await import("./management/quota-reset-routes");
+  return handleQuotaResetRoutes(ctx);
+}
+
 export async function handleManagementAPI(
   req: Request,
   url: URL,
@@ -229,6 +240,7 @@ export async function handleManagementAPI(
     ??     (await handleStorageLogGuardRoutes(ctx))
     ??     (await handleLogsUsageRoutes(ctx))
     ??     (await handleRequestHistoryRoutes(ctx))
+    ??     (await handleQuotaResetRoutesOnDemand(ctx))
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))
diff --git a/src/server/management/quota-reset-routes.ts b/src/server/management/quota-reset-routes.ts
new file mode 100644
index 0000000000..bc061c3132
--- /dev/null
+++ b/src/server/management/quota-reset-routes.ts
@@ -0,0 +1,57 @@
+/**
+ * Read-only view of recently detected quota resets.
+ *
+ * Loaded on demand from src/server/management-api.ts, which is the FOURTH entry in the protected
+ * set of tests/core-lab-boundary.test.ts — added precisely because eagerly importing handlers
+ * there put ~70 modules on every dashboard request. A static import here would make this
+ * subsystem the next instance of that bug.
+ *
+ * Authentication is inherited: every /api route passes through requireManagementAuth before the
+ * chain runs, so a read-only GET adds no auth code of its own. It spends no user identity and
+ * mutates nothing.
+ */
+
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+export async function handleQuotaResetRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  if (url.pathname !== "/api/quota-resets") return null;
+  if (req.method !== "GET") return null;
+
+  const rawLimit = url.searchParams.get("limit");
+  if (rawLimit !== null && !/^\d+$/.test(rawLimit)) {
+    return jsonResponse(
+      { error: { code: "invalid_limit", message: "limit must be a non-negative integer" } },
+      400,
+      req,
+      config,
+    );
+  }
+  const limit = rawLimit === null
+    ? DEFAULT_LIMIT
+    : Math.min(MAX_LIMIT, Number.parseInt(rawLimit, 10));
+
+  // Imported here rather than at module scope so a dashboard request that never touches this
+  // route does not load the store or its state file.
+  const [{ listRecentQuotaResetEvents }, { isQuotaResetNotificationEnabled }] = await Promise.all([
+    import("../../quota/reset-seen-store"),
+    import("../../quota/reset-notify-config"),
+  ]);
+
+  // `enabled` is reported alongside the events because an empty list is ambiguous on its own:
+  // it means either "nothing has reset" or "detection was never turned on", and an operator
+  // debugging a missing notification needs to tell those apart.
+  return jsonResponse(
+    {
+      enabled: isQuotaResetNotificationEnabled(),
+      events: listRecentQuotaResetEvents(limit),
+    },
+    200,
+    req,
+    config,
+  );
+}
diff --git a/src/types/config.ts b/src/types/config.ts
index 114a743980..414b8e7511 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -591,6 +591,13 @@ export interface OcxConfig {
     /** Maximum in-memory ciphertext-to-assignment entries. Default: 200. */
     cacheEntries?: number;
   };
+  /**
+   * Quota-reset detection and notification. Absent means off: no detection, no timer, no sink.
+   *
+   * Not in `getDefaultConfig()` on purpose — that function carries no optional-feature keys,
+   * so absence is the only default state this feature has.
+   */
+  quotaResetNotify?: OcxQuotaResetNotifyConfig;
   /** Provider-level Codex-visible context caps. Values only lower known model context windows. */
   providerContextCaps?: Record<string, number>;
   /** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
@@ -1085,6 +1092,51 @@ export interface OcxWebSearchSidecarConfig {
    * stays atomic. Tradeoff: text the model emits BEFORE deciding to search — which buffered mode
    * silently drops — becomes visible to the client and may partially repeat in the post-search
    * answer. Default: false (buffered, previous behavior).
-   */
+  */
   streamRoutedModelOutput?: boolean;
 }
+
+/**
+ * Quota-reset notification settings.
+ *
+ * Every field is optional and the whole section defaults to off. `enabled: true` alone is not
+ * sufficient: without a webhook or a command there is nowhere to deliver, and treating that as
+ * off is what keeps the "a default install runs no detection code" guarantee true rather than
+ * nearly true.
+ */
+export interface OcxQuotaResetNotifyConfig {
+  /** Master switch. Default false — nothing detects, nothing polls, nothing fires. */
+  enabled?: boolean;
+  /** Which reset kinds to deliver. Default: both. */
+  kinds?: Array<"scheduled" | "surprise">;
+  /**
+   * Idle poll interval in seconds. Default 900, floor 60, and 0 disables polling entirely.
+   *
+   * Polling exists because the interesting case is a reset that happens while no request is in
+   * flight: without a poll, a window that reset overnight is only noticed on the next request.
+   */
+  pollSeconds?: number;
+  /**
+   * POST the event as JSON here.
+   *
+   * Treated as a credential: for Slack and Discord the URL itself is the authorization, so it
+   * is redacted by `ocx config show` and excluded from `config export`.
+   */
+  webhookUrl?: string;
+  /**
+   * Permit a loopback or private-network webhook target. Default false.
+   *
+   * An operator-supplied URL is an SSRF surface, so the default refuses anything that resolves
+   * private. Self-hosted receivers are the legitimate case for opting in.
+   */
+  allowPrivateNetwork?: boolean;
+  /** Webhook timeout in milliseconds. Default 5000. */
+  timeoutMs?: number;
+  /**
+   * Run a local command with the event JSON on stdin.
+   *
+   * An argv array, never a shell string: the command is spawned directly, so an operator value
+   * cannot become a shell-injection surface.
+   */
+  command?: string[];
+}
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 4909f508c5..19d4814fcf 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -779,6 +779,13 @@
   "quota-401-recovery-runtime.test.ts": "usage",
   "quota-401-recovery.test.ts": "usage",
   "quota-bars-rows.test.ts": "gui",
+  "quota-reset-account-key.test.ts": "usage",
+  "quota-reset-core-boundary.test.ts": "usage",
+  "quota-reset-detector.test.ts": "usage",
+  "quota-reset-notify-config.test.ts": "usage",
+  "quota-reset-notify.test.ts": "usage",
+  "quota-reset-observation.test.ts": "usage",
+  "quota-reset-seen-store.test.ts": "usage",
   "quota-scoring.test.ts": "usage",
   "qwen-cloud-endpoints.test.ts": "gui",
   "qwen38-preserve-reasoning.test.ts": "providers",
diff --git a/tests/helpers/import-graph.ts b/tests/helpers/import-graph.ts
new file mode 100644
index 0000000000..688cfa911c
--- /dev/null
+++ b/tests/helpers/import-graph.ts
@@ -0,0 +1,152 @@
+/**
+ * Static import-graph walker shared by the repository's boundary guards.
+ *
+ * Two subsystems now need the same question answered -- "can this entrypoint reach that
+ * directory without anyone choosing to load it?" -- and the answer must be computed the
+ * same way for both. tests/core-lab-boundary.test.ts already records what happens when a
+ * guard's predicate is duplicated instead of shared: its self-test re-declared its own copy
+ * of the matcher, so it proved a local literal behaved rather than that the guard did. A
+ * copy cannot fail when the original drifts, which is the specific way a guard rots. This
+ * module exists so the second guard is not a third copy.
+ *
+ * Callers own the policy (which entrypoints are protected, which directory is off-limits);
+ * this module owns only the mechanics.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * fileURLToPath, not URL.pathname: on Windows the latter yields "/C:/...", and resolving
+ * that against the cwd produced "C:\\C:\\..." -- so every guard built on it threw ENOENT
+ * instead of reading a file. A boundary test that cannot open its own sources reports a
+ * broken path as a failure and would report a real violation the same way, which means it
+ * was proving nothing on that platform.
+ */
+export const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** An import edge as written in source, before resolution. */
+export interface ImportEdge {
+  /** The specifier exactly as spelled. */
+  readonly spec: string;
+  /** True for import(...) -- a deferred edge, entered only if that branch runs. */
+  readonly dynamic: boolean;
+}
+
+/** An import edge with its specifier resolved to a file on disk, when it resolves at all. */
+export interface ResolvedImportEdge extends ImportEdge {
+  /** Absolute path, or null for a bare/unresolvable specifier. */
+  readonly resolved: string | null;
+}
+
+/**
+ * Runtime imports only: "import type" is erased and costs nothing at runtime.
+ *
+ * Covers static imports, side-effect imports, runtime re-exports, AND dynamic import().
+ * Dynamic import was a real hole once: an earlier guard matched only the first three forms,
+ * and a void import("./lab/paths") in a protected file passed cleanly while loading Lab at
+ * runtime. Found by attacking the guard rather than trusting it.
+ *
+ * Known limits, stated rather than implied: a static walker cannot resolve a computed
+ * specifier, so import(someVariable) and template-literal specifiers are out of scope, and
+ * bare require() is unavailable because this package is ESM ("type": "module").
+ *
+ * Returned fresh on every call: a shared /g regex carries lastIndex between callers, and a
+ * guard that skips the first edges of every other file it reads is worse than no guard.
+ */
+/** Kept as one string so both guards match on byte-identical mechanics. */
+const IMPORT_PATTERN_SOURCE = "^\\s*import\\s+(?!type\\b)[^;]*?from\\s+[\"']([^\"']+)[\"']|^\\s*import\\s+[\"']([^\"']+)[\"']|^\\s*export\\s+(?!type\\b)[^;]*?from\\s+[\"']([^\"']+)[\"']|\\bimport\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)";
+function importPattern(): RegExp {
+  return new RegExp(IMPORT_PATTERN_SOURCE, "gm");
+}
+
+/** Every runtime import edge in one source text, in source order. */
+export function runtimeImportEdges(source: string): ImportEdge[] {
+  const pattern = importPattern();
+  const edges: ImportEdge[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(source)) !== null) {
+    const spec = match[1] ?? match[2] ?? match[3] ?? match[4];
+    if (!spec) continue;
+    edges.push({ spec, dynamic: match[4] !== undefined });
+  }
+  return edges;
+}
+
+/** Resolve a relative specifier the way the runtime would. Bare specifiers yield null. */
+export function resolveSpec(spec: string, fromFile: string): string | null {
+  if (!spec.startsWith(".")) return null;
+  const base = resolve(dirname(fromFile), spec);
+  for (const candidate of [base + ".ts", join(base, "index.ts"), base + ".mts", base + ".mjs"]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Slash-normalized path.
+ *
+ * resolve/join produce backslashes on Windows, so a literal "/src/lab/" test silently
+ * matched nothing there and the guard reported clean for every possible violation.
+ */
+export function slashed(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+/** Every runtime import edge of one repository file, with specifiers resolved. */
+export function resolvedImportEdges(repoRelativeFile: string): ResolvedImportEdge[] {
+  const absolute = resolve(repoRoot, repoRelativeFile);
+  const source = readFileSync(absolute, "utf8");
+  return runtimeImportEdges(source).map(edge => ({
+    ...edge,
+    resolved: resolveSpec(edge.spec, absolute),
+  }));
+}
+
+/**
+ * Walk the load-time import graph from one entrypoint and return the first chain that
+ * reaches a file the caller recognizes, or null.
+ *
+ * isTarget receives an absolute, slash-normalized path. The returned chain is
+ * repository-relative and slash-spelled, so it reads the same on every platform and callers
+ * can assert on it without knowing the separator.
+ *
+ * A dynamic import() is a deferred edge, not a load-time one: the module graph is only
+ * entered if that branch actually runs. Lazy loading behind an activation check is precisely
+ * the remedy these guards exist to encourage, so a dynamic specifier does not propagate the
+ * walk. Forbidding a DIRECT dynamic import in a protected file is the caller's job, and is
+ * what stops the deferral being a loophole.
+ *
+ * The entrypoint itself is never matched -- only what it reaches. A guard that wants to
+ * reject the entrypoint naming the target directly checks its edges instead.
+ */
+export function firstLoadTimePathTo(
+  entry: string,
+  isTarget: (absoluteSlashedPath: string) => boolean,
+): string[] | null {
+  const start = resolve(repoRoot, entry);
+  const previous = new Map<string, string | null>([[start, null]]);
+  const queue = [start];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (!existsSync(current)) continue;
+    for (const edge of runtimeImportEdges(readFileSync(current, "utf8"))) {
+      if (edge.dynamic) continue;
+      const next = resolveSpec(edge.spec, current);
+      if (!next || previous.has(next)) continue;
+      previous.set(next, current);
+      if (isTarget(slashed(next))) {
+        const chain: string[] = [];
+        let node: string | null = next;
+        while (node) {
+          chain.push(slashed(node.slice(repoRoot.length + 1)));
+          node = previous.get(node) ?? null;
+        }
+        return chain.reverse();
+      }
+      queue.push(next);
+    }
+  }
+  return null;
+}
+
diff --git a/tests/helpers/quota-reset-burst-child.ts b/tests/helpers/quota-reset-burst-child.ts
new file mode 100644
index 0000000000..2d06808a00
--- /dev/null
+++ b/tests/helpers/quota-reset-burst-child.ts
@@ -0,0 +1,35 @@
+/**
+ * Child process for the burst-ordering regression.
+ *
+ * Runs in a FRESH module registry on purpose. Inside one test file the observer module is
+ * already cached by earlier tests, so every dynamic import resolves from cache in call order
+ * and the reordering cannot reproduce — an in-process version of this test passed against the
+ * unfixed seam. Only a cold registry has the concurrent module loads that Bun resolves out of
+ * call order.
+ *
+ * Writes monotonically RISING usage: no reset happens anywhere in this burst, so any event
+ * printed here is false.
+ */
+import { setQuotaResetSink } from "../../src/quota/reset-observer";
+import {
+  flushQuotaObservationsForTests,
+  setAccountQuotaFromParsed,
+} from "../../src/codex/quota";
+
+const events: string[] = [];
+setQuotaResetSink(event => {
+  events.push(`${event.kind}:${event.percentBefore}->${event.percentAfter}`);
+});
+
+const deadline = Date.now() + 4 * 60 * 60_000;
+for (let percent = 10; percent <= 90; percent += 4) {
+  setAccountQuotaFromParsed("acct-burst-child", {
+    shortPercent: percent,
+    shortResetAt: deadline,
+    shortWindowSeconds: 5 * 3600,
+  });
+}
+
+await flushQuotaObservationsForTests();
+await new Promise(resolve => setTimeout(resolve, 50));
+console.log(JSON.stringify(events));
diff --git a/tests/providers/provider-account-quota.test.ts b/tests/providers/provider-account-quota.test.ts
index ccebd5c032..0f0b242df6 100644
--- a/tests/providers/provider-account-quota.test.ts
+++ b/tests/providers/provider-account-quota.test.ts
@@ -438,9 +438,30 @@ describe("google-antigravity per-account quota (#1082)", () => {
     });
   }
 
+  function antigravitySummaryBody(gemRemaining: number, claRemaining: number): string {
+    return JSON.stringify({
+      groups: [
+        {
+          displayName: "Gemini Models",
+          buckets: [
+            { bucketId: "gemini-weekly", window: "weekly", remainingFraction: gemRemaining, resetTime: "2026-09-09T12:00:00Z" },
+            { bucketId: "gemini-5h", window: "5h", remainingFraction: gemRemaining, resetTime: "2026-09-02T12:00:00Z" },
+          ],
+        },
+        {
+          displayName: "Claude and GPT models",
+          buckets: [
+            { bucketId: "3p-weekly", window: "weekly", remainingFraction: claRemaining, resetTime: "2026-09-09T18:00:00Z" },
+            { bucketId: "3p-5h", window: "5h", remainingFraction: claRemaining, resetTime: "2026-09-02T18:00:00Z" },
+          ],
+        },
+      ],
+    });
+  }
+
   afterEach(() => setAntigravityAccountQuotaTransportForTests(null));
 
-  test("probes each account with its own bearer and project id on the fixed Google host over the pinned transport", async () => {
+  test("probes each account with its own bearer and project id on the fixed Google host using retrieveUserQuotaSummary", async () => {
     const expires = Date.now() + 60 * 60_000;
     await saveCredential("google-antigravity", { access: "agy-first", refresh: "r1", expires, projectId: "proj-first", accountId: "agy-a", email: "a@example.com" });
     await saveCredential("google-antigravity", { access: "agy-second", refresh: "r2", expires, projectId: "proj-second", accountId: "agy-b", email: "b@example.com" });
@@ -453,6 +474,9 @@ describe("google-antigravity per-account quota (#1082)", () => {
         const auth = new Headers(requestOptions?.headers).get("authorization") ?? "";
         const project = String(JSON.parse(String(body)).project);
         seen.push({ url, auth, project, address: pinned.address });
+        if (url.endsWith("retrieveUserQuotaSummary")) {
+          return new Response(auth.endsWith("agy-first") ? antigravitySummaryBody(0.86, 0.38) : antigravitySummaryBody(0.97, 0.91), { status: 200, headers: { "content-type": "application/json" } });
+        }
         return new Response(auth.endsWith("agy-first") ? antigravityBody(0.86, 0.38) : antigravityBody(0.97, 0.91), { status: 200, headers: { "content-type": "application/json" } });
       },
     });
@@ -463,16 +487,45 @@ describe("google-antigravity per-account quota (#1082)", () => {
     const [idA, idB] = [idFor("a@example.com"), idFor("b@example.com")];
     expect(Object.keys(byId).sort()).toEqual([idA, idB].sort());
     const windows = (id: string) => byId[id]!.quota!.customWindows!.map(w => `${w.label}=${w.percent}`);
-    expect(windows(idA)).toEqual(["Gem=14", "Cla=62"]);
-    expect(windows(idB)).toEqual(["Gem=3", "Cla=9"]);
+    expect(windows(idA)).toEqual(["Gem=14", "Gem (Weekly)=14", "Cla=62", "Cla (Weekly)=62"]);
+    expect(windows(idB)).toEqual(["Gem=3", "Gem (Weekly)=3", "Cla=9", "Cla (Weekly)=9"]);
     expect(byId[idA]!.quota!.customWindows![0]!.resetAt).toBeDefined();
     expect(seen.map(s => `${s.auth}|${s.project}`).sort()).toEqual(["Bearer agy-first|proj-first", "Bearer agy-second|proj-second"]);
     for (const s of seen) {
-      expect(s.url).toBe("https://daily-cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels");
+      expect(s.url).toBe("https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary");
       expect(s.address).toBe("142.250.0.1");
     }
   });
 
+  test("falls back to fetchAvailableModels when retrieveUserQuotaSummary returns 404", async () => {
+    const expires = Date.now() + 60 * 60_000;
+    await saveCredential("google-antigravity", { access: "agy-first", refresh: "r1", expires, projectId: "proj-first", accountId: "agy-a", email: "a@example.com" });
+    await saveCredential("google-antigravity", { access: "agy-second", refresh: "r2", expires, projectId: "proj-second", accountId: "agy-b", email: "b@example.com" });
+    globalThis.fetch = (async () => { throw new Error("plain fetch must not be used for account bearers"); }) as typeof fetch;
+
+    const seen: Array<{ url: string; auth: string; project: string; address: string }> = [];
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
+      pinnedPost: async (url, pinned, body, _signal, requestOptions) => {
+        const auth = new Headers(requestOptions?.headers).get("authorization") ?? "";
+        const project = String(JSON.parse(String(body)).project);
+        seen.push({ url, auth, project, address: pinned.address });
+        if (url.endsWith("retrieveUserQuotaSummary")) {
+          return new Response(null, { status: 404 });
+        }
+        return new Response(auth.endsWith("agy-first") ? antigravityBody(0.86, 0.38) : antigravityBody(0.97, 0.91), { status: 200, headers: { "content-type": "application/json" } });
+      },
+    });
+
+    const rows = await fetchProviderAccountQuotas("google-antigravity");
+    const byId = Object.fromEntries(rows.map(row => [row.accountId, row]));
+    const [idA, idB] = [idFor("a@example.com"), idFor("b@example.com")];
+    const windows = (id: string) => byId[id]!.quota!.customWindows!.map(w => `${w.label}=${w.percent}`);
+    expect(windows(idA)).toEqual(["Gem=14", "Cla=62"]);
+    expect(windows(idB)).toEqual(["Gem=3", "Cla=9"]);
+    expect(byId[idA]!.quota!.customWindows![0]!.resetAt).toBeDefined();
+  });
+
   test("a rejected destination never receives a bearer; the row is unavailable, not 0%", async () => {
     const expires = Date.now() + 60 * 60_000;
     await saveCredential("google-antigravity", { access: "agy-first", refresh: "r1", expires, projectId: "proj-first", accountId: "agy-a", email: "a@example.com" });
@@ -506,4 +559,3 @@ describe("google-antigravity per-account quota (#1082)", () => {
     }
   });
 });
-
diff --git a/tests/providers/provider-quota.test.ts b/tests/providers/provider-quota.test.ts
index 582b03b457..5a02e53f28 100644
--- a/tests/providers/provider-quota.test.ts
+++ b/tests/providers/provider-quota.test.ts
@@ -13,9 +13,11 @@ import { saveCredential } from "../../src/oauth/store";
 import {
   clearProviderQuotaCache,
   fetchProviderQuotaReports,
+  parseOllamaCloudQuota,
   parseXaiCreditsResponse,
   QUOTA_RESPONSE_MAX_BYTES,
   readProviderQuotaJsonForTests,
+  setAntigravityAccountQuotaTransportForTests,
   setProviderQuotaBeforePublishForTests,
 } from "../../src/providers/quota";
 import type { OcxConfig } from "../../src/types";
@@ -92,6 +94,7 @@ afterEach(() => {
   clearAccountQuota();
   clearProviderQuotaCache();
   setProviderQuotaBeforePublishForTests(null);
+  setAntigravityAccountQuotaTransportForTests(null);
   if (previousOpencodexHome === undefined) delete process.env.OPENCODEX_HOME;
   else process.env.OPENCODEX_HOME = previousOpencodexHome;
   if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
@@ -200,6 +203,14 @@ describe("fetchProviderQuotaReports", () => {
     await saveCredential("google-antigravity", { access: "agy-access-secret", refresh: "agy-refresh-secret", expires: Date.now() + 3600_000, projectId: "agy-project-secret" });
     await saveCredential("kimi", { access: "kimi-access-secret", refresh: "kimi-refresh-secret", expires: Date.now() + 3600_000 });
 
+    // The Antigravity summary probe is pinned to Google's host through the provider-outbound
+    // transport and never touches globalThis.fetch; without this seam the test would make a
+    // real network request. A 404 here exercises the fetchAvailableModels fallback below.
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
+      pinnedPost: async () => new Response("not found", { status: 404 }),
+    });
+
     const seen: { url: string; authorization?: string; body?: string }[] = [];
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = String(input);
@@ -2801,4 +2812,396 @@ describe("fetchProviderQuotaReports", () => {
     const pruned = await fetchProviderQuotaReports(disabledConfig, true);
     expect(pruned.reports).toEqual([]);
   });
+
+  test("Google Antigravity maps 5-hour and weekly quota from retrieveUserQuotaSummary", async () => {
+    await saveCredential("google-antigravity", {
+      access: "agy-summary-access",
+      refresh: "agy-summary-refresh",
+      expires: Date.now() + 3600_000,
+      projectId: "agy-summary-project",
+    });
+
+    const seen: Array<{ url: string; auth?: string; body?: string }> = [];
+    globalThis.fetch = (async () => { throw new Error("plain fetch must not be used for account bearers"); }) as typeof fetch;
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
+      pinnedPost: async (url, _pinned, body, _signal, requestOptions) => {
+        const auth = new Headers(requestOptions?.headers).get("authorization") ?? undefined;
+        seen.push({ url, auth, body: typeof body === "string" ? body : undefined });
+        if (!url.endsWith("retrieveUserQuotaSummary")) return new Response("not found", { status: 404 });
+        return new Response(JSON.stringify({
+          groups: [
+            {
+              displayName: "Gemini Models",
+              description: "Models within this group: Gemini Flash, Gemini Pro",
+              buckets: [
+                {
+                  bucketId: "gemini-weekly",
+                  displayName: "Weekly Limit Remaining",
+                  window: "weekly",
+                  resetTime: "2026-09-11T02:25:41Z",
+                  remainingFraction: 0.88,
+                },
+                {
+                  bucketId: "gemini-5h",
+                  displayName: "Five Hour Limit Remaining",
+                  window: "5h",
+                  resetTime: "2026-09-04T12:25:41Z",
+                  remainingFraction: 0.75,
+                },
+              ],
+            },
+            {
+              displayName: "Claude and GPT models",
+              description: "Models within this group: Claude Opus, Claude Sonnet, GPT-OSS",
+              buckets: [
+                {
+                  bucketId: "3p-weekly",
+                  displayName: "Weekly Limit Remaining",
+                  window: "weekly",
+                  resetTime: "2026-09-04T10:57:22Z",
+                  remainingFraction: 0.95,
+                },
+                {
+                  bucketId: "3p-5h",
+                  displayName: "Five Hour Limit Remaining",
+                  window: "5h",
+                  resetTime: "2026-09-04T12:54:45Z",
+                  remainingFraction: 1.0,
+                },
+              ],
+            },
+          ],
+        }), { status: 200, headers: { "content-type": "application/json" } });
+      },
+    });
+
+    const config = {
+      defaultProvider: "google-antigravity",
+      providers: {
+        "google-antigravity": {
+          adapter: "google",
+          authMode: "oauth",
+          baseUrl: "https://daily-cloudcode-pa.googleapis.com",
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const result = await fetchProviderQuotaReports(config, true);
+    expect(result.reports).toHaveLength(1);
+    const report = result.reports[0]!;
+    expect(report.provider).toBe("google-antigravity");
+    expect(report.source).toBe("google-antigravity:retrieveUserQuotaSummary");
+    expect(report.quota.customWindows).toEqual([
+      { label: "Gem", percent: 25, resetAt: Date.parse("2026-09-04T12:25:41Z") },
+      { label: "Gem (Weekly)", percent: 12, resetAt: Date.parse("2026-09-11T02:25:41Z") },
+      { label: "Cla", percent: 0, resetAt: Date.parse("2026-09-04T12:54:45Z") },
+      { label: "Cla (Weekly)", percent: 5, resetAt: Date.parse("2026-09-04T10:57:22Z") },
+    ]);
+    expect(seen[0]?.url).toBe("https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary");
+    expect(seen[0]?.auth).toBe("Bearer agy-summary-access");
+    expect(seen[0]?.body).toBe(JSON.stringify({ project: "agy-summary-project" }));
+  });
+
+  test("Google Antigravity supports nested remaining object and deduplicates custom windows", async () => {
+    await saveCredential("google-antigravity", {
+      access: "agy-nested-access",
+      refresh: "agy-nested-refresh",
+      expires: Date.now() + 3600_000,
+      projectId: "agy-nested-project",
+    });
+
+    globalThis.fetch = (async () => { throw new Error("plain fetch must not be used for account bearers"); }) as typeof fetch;
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
+      pinnedPost: async (url) => {
+        if (!url.endsWith("retrieveUserQuotaSummary")) return new Response("not found", { status: 404 });
+        return new Response(JSON.stringify({
+          groups: [
+            {
+              displayName: "Gemini Models",
+              buckets: [
+                {
+                  bucketId: "gemini-weekly",
+                  window: "weekly",
+                  resetTime: "2026-09-11T00:00:00Z",
+                  remaining: { remainingFraction: 0.70 },
+                },
+                {
+                  bucketId: "gemini-5h",
+                  window: "5h",
+                  resetTime: "2026-09-04T08:00:00Z",
+                  remaining: { remainingFraction: 0.60 },
+                },
+              ],
+            },
+            {
+              displayName: "Claude and GPT models",
+              buckets: [
+                {
+                  bucketId: "claude-3p-5h-1",
+                  displayName: "Claude 5 Hour Limit",
+                  window: "5h",
+                  resetTime: "2026-09-04T09:00:00Z",
+                  remaining: { remainingFraction: 0.90 },
+                },
+                {
+                  bucketId: "claude-3p-5h-duplicate",
+                  displayName: "GPT 5 Hour Limit",
+                  window: "5h",
+                  resetTime: "2026-09-04T09:30:00Z",
+                  remaining: { remainingFraction: 0.50 },
+                },
+                {
+                  bucketId: "claude-3p-weekly",
+                  displayName: "Claude Weekly Limit",
+                  window: "weekly",
+                  resetTime: "2026-09-11T09:00:00Z",
+                  remaining: { remainingFraction: 0.85 },
+                },
+              ],
+            },
+          ],
+        }), { status: 200, headers: { "content-type": "application/json" } });
+      },
+    });
+
+    const config = {
+      defaultProvider: "google-antigravity",
+      providers: {
+        "google-antigravity": {
+          adapter: "google",
+          authMode: "oauth",
+          baseUrl: "https://daily-cloudcode-pa.googleapis.com",
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const result = await fetchProviderQuotaReports(config, true);
+    expect(result.reports).toHaveLength(1);
+    const report = result.reports[0]!;
+    expect(report.quota.customWindows).toEqual([
+      { label: "Gem", percent: 40, resetAt: Date.parse("2026-09-04T08:00:00Z") },
+      { label: "Gem (Weekly)", percent: 30, resetAt: Date.parse("2026-09-11T00:00:00Z") },
+      { label: "Cla", percent: 10, resetAt: Date.parse("2026-09-04T09:00:00Z") },
+      { label: "Cla (Weekly)", percent: 15, resetAt: Date.parse("2026-09-11T09:00:00Z") },
+    ]);
+  });
+
+  // The provider-level Antigravity probe carries the stored account bearer. A configured
+  // `baseUrl` is a routing choice for model requests, not a second source of Google's
+  // accounting, so the summary probe stays pinned to Google's own host — the same guarantee
+  // `fetchAntigravityUsageQuota` already makes for the per-account path.
+  test("Google Antigravity does not send the account bearer to a configured baseUrl", async () => {
+    await saveCredential("google-antigravity", {
+      access: "agy-pinned-access",
+      refresh: "agy-pinned-refresh",
+      expires: Date.now() + 3600_000,
+      projectId: "agy-pinned-project",
+    });
+
+    const plainFetchUrls: string[] = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      plainFetchUrls.push(String(input));
+      throw new Error("plain fetch must not be used for account bearers");
+    }) as typeof fetch;
+
+    const seen: Array<{ url: string; auth?: string; hostname: string }> = [];
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async (url: string) => {
+        seen.push({ url, hostname: new URL(url).hostname });
+        return { hostname: new URL(url).hostname, addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false };
+      },
+      pinnedPost: async (url, _pinned, _body, _signal, requestOptions) => {
+        seen.push({ url, auth: new Headers(requestOptions?.headers).get("authorization") ?? undefined, hostname: new URL(url).hostname });
+        if (!url.endsWith("retrieveUserQuotaSummary")) return new Response("not found", { status: 404 });
+        return new Response(JSON.stringify({
+          groups: [{
+            displayName: "Gemini Models",
+            buckets: [{ bucketId: "gemini-5h", window: "5h", resetTime: "2026-09-04T08:00:00Z", remainingFraction: 0.6 }],
+          }],
+        }), { status: 200, headers: { "content-type": "application/json" } });
+      },
+    });
+
+    const result = await fetchProviderQuotaReports({
+      defaultProvider: "google-antigravity",
+      providers: {
+        "google-antigravity": {
+          adapter: "google",
+          authMode: "oauth",
+          baseUrl: "http://127.0.0.1:1/",
+        },
+      },
+    } as unknown as OcxConfig, true);
+
+    expect(result.reports).toHaveLength(1);
+    expect(result.reports[0]!.source).toBe("google-antigravity:retrieveUserQuotaSummary");
+    // Every bearer-carrying request went to Google's own host, not the configured loopback base.
+    expect(seen.map(entry => entry.hostname)).toEqual(["daily-cloudcode-pa.googleapis.com", "daily-cloudcode-pa.googleapis.com"]);
+    expect(seen.find(entry => entry.auth)?.url).toBe("https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary");
+    expect(seen.find(entry => entry.auth)?.auth).toBe("Bearer agy-pinned-access");
+    expect(plainFetchUrls).toEqual([]);
+  });
+
+  test("Google Antigravity refuses a redirected summary response", async () => {
+    await saveCredential("google-antigravity", {
+      access: "agy-redirect-access",
+      refresh: "agy-redirect-refresh",
+      expires: Date.now() + 3600_000,
+      projectId: "agy-redirect-project",
+    });
+    globalThis.fetch = (async () => { throw new Error("plain fetch must not be used for account bearers"); }) as typeof fetch;
+
+    const posted: string[] = [];
+    setAntigravityAccountQuotaTransportForTests({
+      resolveAddresses: async () => ({ hostname: "daily-cloudcode-pa.googleapis.com", addresses: [{ address: "142.250.0.1", family: 4 }], privateNetwork: false }),
+      pinnedPost: async (url) => {
+        posted.push(url);
+        return new Response(null, { status: 302, headers: { location: "http://127.0.0.1/" } });
+      },
+    });
+
+    const result = await fetchProviderQuotaReports({
+      defaultProvider: "google-antigravity",
+      providers: {
+        "google-antigravity": {
+          adapter: "google",
+          authMode: "oauth",
+          baseUrl: "https://daily-cloudcode-pa.googleapis.com",
+        },
+      },
+    } as unknown as OcxConfig, true);
+
+    expect(result.reports).toEqual([]);
+    // The redirect short-circuits the summary probe; the redirect target is never fetched.
+    expect(posted).toEqual(["https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary"]);
+  });
+
+  test("Ollama Cloud maps 5-hour session and weekly windows from /api/usage (legacy plan)", async () => {
+    const seen: Array<{ url: string; authorization?: string; redirect?: RequestRedirect }> = [];
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      const headers = init?.headers as Record<string, string> | undefined;
+      seen.push({ url, authorization: headers?.Authorization, redirect: init?.redirect });
+      return new Response(JSON.stringify({
+        activity: { cost: "0.00000", period: { type: "last_4_weeks" }, models: [] },
+        limits: {
+          session: { usage: 0.091, models: [{ name: "glm-5.3-flash", request_count: 228 }] },
+          weekly: { usage: 0.592, models: [{ name: "glm-5.3", request_count: 2572 }] },
+        },
+      }), { status: 200 });
+    }) as typeof fetch;
+
+    const result = await fetchProviderQuotaReports(
+      keyQuotaConfig("ollama-cloud", "https://ollama.com/v1"),
+      true,
+    );
+
+    expect(result.reports).toHaveLength(1);
+    expect(result.reports[0]?.source).toBe("ollama-cloud:usage");
+    expect(result.reports[0]?.quota).toMatchObject({
+      fiveHourPercent: 9.1,
+      weeklyPercent: 59.2,
+    });
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.url).toBe("https://ollama.com/api/usage");
+    expect(seen[0]?.authorization).toBe("Bearer ollama-cloud-secret");
+    expect(seen[0]?.redirect).toBe("error");
+  });
+
+  test("Ollama Cloud maps monthly window from /api/usage (migrated plan)", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({
+        activity: { cost: "1.68054", period: { type: "last_4_weeks" } },
+        limits: {
+          monthly: { usage: 0.004, models: [{ name: "glm-5.3-flash", request_count: 147 }] },
+        },
+      }), { status: 200 });
+    }) as typeof fetch;
+
+    const result = await fetchProviderQuotaReports(
+      keyQuotaConfig("ollama-cloud", "https://ollama.com/v1"),
+      true,
+    );
+
+    expect(result.reports).toHaveLength(1);
+    expect(result.reports[0]?.source).toBe("ollama-cloud:usage");
+    expect(result.reports[0]?.quota).toMatchObject({
+      monthlyPercent: 0.4,
+    });
+    expect(result.reports[0]?.quota.fiveHourPercent).toBeUndefined();
+    expect(result.reports[0]?.quota.weeklyPercent).toBeUndefined();
+  });
+
+  test("Ollama Cloud maps combined windows when both legacy and migrated limits exist", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({
+        limits: {
+          session: { usage: 0.1 },
+          weekly: { usage: 0.2 },
+          monthly: { usage: 0.3 },
+        },
+      }), { status: 200 });
+    }) as typeof fetch;
+
+    const result = await fetchProviderQuotaReports(
+      keyQuotaConfig("ollama-cloud", "https://ollama.com/v1"),
+      true,
+    );
+
+    expect(result.reports).toHaveLength(1);
+    expect(result.reports[0]?.quota).toMatchObject({
+      fiveHourPercent: 10,
+      weeklyPercent: 20,
+      monthlyPercent: 30,
+    });
+  });
+
+  test("Ollama Cloud treats 404 as a no-report, not terminal", async () => {
+    globalThis.fetch = (async () => new Response("not found", { status: 404 })) as typeof fetch;
+    const config = keyQuotaConfig("ollama-cloud", "https://ollama.com/v1");
+
+    const result = await fetchProviderQuotaReports(config, true);
+    expect(result.reports).toEqual([]);
+  });
+
+  test("Ollama Cloud treats 401 as terminal failure (invalid key)", async () => {
+    globalThis.fetch = (async () => new Response(JSON.stringify({ error: "invalid credentials" }), { status: 401 })) as typeof fetch;
+    const config = keyQuotaConfig("ollama-cloud", "https://ollama.com/v1");
+
+    const result = await fetchProviderQuotaReports(config, true);
+    expect(result.reports).toEqual([]);
+  });
+
+  test("Ollama Cloud never sends the key to a non-canonical base URL", async () => {
+    const seen: string[] = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      seen.push(String(input));
+      return new Response("unexpected", { status: 500 });
+    }) as typeof fetch;
+
+    const result = await fetchProviderQuotaReports(
+      keyQuotaConfig("ollama-cloud", "https://attacker.example/v1"),
+      true,
+    );
+
+    expect(result.reports).toEqual([]);
+    expect(seen).toEqual([]);
+  });
+
+  test("parseOllamaCloudQuota handles edge cases", () => {
+    expect(parseOllamaCloudQuota(null)).toBeNull();
+    expect(parseOllamaCloudQuota({})).toBeNull();
+    expect(parseOllamaCloudQuota({ limits: {} })).toBeNull();
+    expect(parseOllamaCloudQuota({ limits: { session: { usage: 0 } } })).toMatchObject({
+      fiveHourPercent: 0,
+    });
+    expect(parseOllamaCloudQuota({ limits: { session: { usage: 1 } } })).toMatchObject({
+      fiveHourPercent: 100,
+    });
+    expect(parseOllamaCloudQuota({ limits: { session: { usage: 1.25 } } })).toMatchObject({
+      fiveHourPercent: 100,
+    });
+  });
 });
diff --git a/tests/usage/quota-reset-account-key.test.ts b/tests/usage/quota-reset-account-key.test.ts
new file mode 100644
index 0000000000..47b3cd460f
--- /dev/null
+++ b/tests/usage/quota-reset-account-key.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import type { OcxConfig } from "../../src/types/config";
+import { providerObservationAccountKeyForTests } from "../../src/providers/quota";
+
+describe("provider observation account key", () => {
+  function configWithKey(apiKey: string): OcxConfig {
+    return {
+      port: 0,
+      hostname: "127.0.0.1",
+      defaultProvider: "deepseek",
+      providers: {
+        deepseek: {
+          adapter: "openai-chat",
+          baseUrl: "https://api.deepseek.com/v1",
+          authMode: "key",
+          apiKey,
+        },
+      },
+    } as OcxConfig;
+  }
+
+  test("two different API keys for one provider do not share an observation identity", () => {
+    // A key-auth provider has NO account set, so `activeAccountId ?? "default"` collapsed every
+    // key in the pool onto one identity: rotating from a spent key to a fresh one inherited the
+    // spent key's usage history and read as a reset (measured 97% -> 12% fired a false
+    // surprise). The report cache already discriminates these via apiKeyPoolEntryId.
+    const spent = providerObservationAccountKeyForTests("deepseek", configWithKey("sk-spent-key-aaa"));
+    const fresh = providerObservationAccountKeyForTests("deepseek", configWithKey("sk-fresh-key-bbb"));
+
+    expect(spent).not.toBe(fresh);
+    // Neither may be the bare provider name, which is what collapsed them.
+    expect(spent).not.toBe("deepseek");
+  });
+
+  test("the same key resolves to the same identity across calls", () => {
+    // Stability is what makes the persisted baseline usable at all.
+    const first = providerObservationAccountKeyForTests("deepseek", configWithKey("sk-stable-key"));
+    const second = providerObservationAccountKeyForTests("deepseek", configWithKey("sk-stable-key"));
+    expect(first).toBe(second);
+  });
+
+  test("a provider with no key at all still yields a usable identity", () => {
+    const config = {
+      port: 0,
+      hostname: "127.0.0.1",
+      defaultProvider: "ollama",
+      providers: { ollama: { adapter: "openai-chat", baseUrl: "http://127.0.0.1:11434/v1" } },
+    } as OcxConfig;
+    expect(providerObservationAccountKeyForTests("ollama", config)).toContain("ollama");
+  });
+});
diff --git a/tests/usage/quota-reset-core-boundary.test.ts b/tests/usage/quota-reset-core-boundary.test.ts
new file mode 100644
index 0000000000..f898bd84ff
--- /dev/null
+++ b/tests/usage/quota-reset-core-boundary.test.ts
@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  firstLoadTimePathTo,
+  repoRoot,
+  resolvedImportEdges,
+  runtimeImportEdges,
+  slashed,
+} from "../helpers/import-graph";
+
+/**
+ * Quota-reset detection is an optional subsystem, so it must stay off the core path.
+ *
+ * AGENTS.md states that obligation for optional subsystems generally, but
+ * tests/core-lab-boundary.test.ts hardcodes "/src/lab/" -- so nothing enforced it for
+ * src/quota/. The gap is not theoretical here. Both quota seams
+ * (src/codex/quota.ts, src/providers/quota.ts) are statically reachable from
+ * src/server/responses/core.ts, so one static import in either puts the detector, its
+ * claim store, and -- through src/quota/reset-notify-config.ts, which pulls the ../config
+ * barrel -- a large module graph onto the request path of a user who never enabled
+ * notifications. The Lab regression AGENTS.md documents reached ~69 modules through a
+ * six-hop chain where no single file looked wrong, and it was caught only after shipping.
+ *
+ * The walker lives in tests/helpers/import-graph.ts and is SHARED with the Lab guard
+ * rather than copied. That guard records why: its own self-test once re-declared a private
+ * copy of the matcher, so it proved a local literal behaved rather than that the guard did.
+ */
+const PROTECTED = [
+  "src/router.ts",
+  "src/server/lifecycle.ts",
+  "src/server/responses/core.ts",
+  "src/server/management-api.ts",
+] as const;
+
+/** The two quota subsystems that observe a committed snapshot. */
+const SEAMS = ["src/codex/quota.ts", "src/providers/quota.ts"] as const;
+
+const OBSERVER_SPEC = "../quota/reset-observer";
+
+/**
+ * The whole directory is the boundary, not just the reset-* prefix.
+ *
+ * src/quota/ holds this subsystem and nothing else, so a core file reaching any part of it
+ * is the defect. A prefix match would have let src/quota/window-mapping.ts onto the core
+ * path unnoticed, and every future sibling would inherit that hole by default.
+ */
+function isQuotaModule(absoluteSlashedPath: string): boolean {
+  return absoluteSlashedPath.includes("/src/quota/");
+}
+
+describe("core / quota-reset boundary", () => {
+  test.each(PROTECTED)("%s reaches no src/quota module at load time", file => {
+    const chain = firstLoadTimePathTo(file, isQuotaModule);
+    // Print the whole chain: a bare verdict would send the next maintainer on the same
+    // multi-hop hunt the Lab decoupling unit required.
+    expect(chain === null ? "clean" : chain.join(" -> ")).toBe("clean");
+  });
+
+  test.each(SEAMS)("%s names the observer only through a dynamic import", seam => {
+    const quotaEdges = resolvedImportEdges(seam).filter(
+      edge => edge.resolved !== null && isQuotaModule(slashed(edge.resolved)),
+    );
+
+    // Assert the seam DOES reach the observer before asserting how. A guard that passes
+    // because the wiring is absent is worthless: delete the observer call and detection
+    // stops silently while a reachability-only assertion stays green.
+    expect(quotaEdges.map(edge => edge.spec)).toContain(OBSERVER_SPEC);
+    expect(quotaEdges.filter(edge => !edge.dynamic).map(edge => edge.spec)).toEqual([]);
+  });
+});
+
+/**
+ * The composition root may know the subsystem exists -- src/server/index.ts is exempt from
+ * the Lab guard for the same reason. What is not free is what that edge drags in, so the
+ * exemption is pinned to an exact shape rather than left open.
+ */
+describe("the poller edge from the composition root stays cheap", () => {
+  test("the only load-time path runs through background-lifecycle to the poller", () => {
+    const chain = firstLoadTimePathTo("src/server/index.ts", isQuotaModule);
+    expect(chain?.join(" -> ")).toBe(
+      "src/server/index.ts -> src/server/background-lifecycle.ts -> src/quota/reset-poller.ts",
+    );
+  });
+
+  test("the poller pulls in nothing at load time", () => {
+    // This keeps the exemption honest. The poller resolves its config gate, the provider
+    // quota refresh, and its shutdown hook through import() inside the callee, so the
+    // static edge above costs exactly one small module. A static import added here would
+    // reach ../config -- a 154-module barrel -- from every install that starts a server,
+    // which is the cost this boundary exists to prevent.
+    const staticEdges = resolvedImportEdges("src/quota/reset-poller.ts").filter(
+      edge => !edge.dynamic,
+    );
+    expect(staticEdges.map(edge => edge.spec)).toEqual([]);
+  });
+});
+
+/**
+ * A guard nobody attacks is a guard nobody can trust.
+ *
+ * These synthesize each import form inside a real protected directory and assert the walker
+ * sees it, so the guard cannot silently regress into matching only the shapes that happen
+ * to exist today. Each case was driven red before being committed green.
+ */
+describe("the quota boundary guard cannot be defeated", () => {
+  // Load-time edges: the graph walk must follow all three.
+  const attacks: Array<[string, string]> = [
+    ["static import", 'import { observeQuotaSnapshot } from "../quota/reset-observer";'],
+    ["side-effect import", 'import "../quota/reset-observer";'],
+    ["runtime re-export", 'export { observeQuotaSnapshot } from "../quota/reset-observer";'],
+  ];
+
+  test.each(attacks)("detects a %s reaching src/quota", (_label, line) => {
+    // The probe sits next to a protected file so its relative specifier resolves exactly as
+    // a real violation would. A probe in a scratch directory would only prove the walker
+    // handles a path shape that no violation can actually have.
+    const probe = join(
+      repoRoot,
+      "src",
+      "server",
+      "__quota_boundary_probe_" + Math.random().toString(36).slice(2) + ".ts",
+    );
+    writeFileSync(probe, line + "\nexport const probe = 1;\n");
+    try {
+      const chain = firstLoadTimePathTo(
+        slashed(probe.slice(repoRoot.length + 1)),
+        isQuotaModule,
+      );
+      expect(chain).not.toBeNull();
+      expect(chain!.join(" -> ")).toContain("src/quota/reset-observer.ts");
+    } finally {
+      rmSync(probe, { force: true });
+    }
+  });
+
+  test("a dynamic import is a deferred edge and does not propagate the walk", () => {
+    // This is the behavior the seams rely on, so it is pinned rather than assumed. If the
+    // walker ever followed import(), both seams would report as violations and the honest
+    // fix would look like deleting the guard.
+    const probe = join(
+      repoRoot,
+      "src",
+      "server",
+      "__quota_boundary_probe_dyn_" + Math.random().toString(36).slice(2) + ".ts",
+    );
+    writeFileSync(
+      probe,
+      'void import("../quota/reset-observer");' + "\nexport const probe = 1;\n",
+    );
+    try {
+      expect(
+        firstLoadTimePathTo(slashed(probe.slice(repoRoot.length + 1)), isQuotaModule),
+      ).toBeNull();
+    } finally {
+      rmSync(probe, { force: true });
+    }
+  });
+
+  test("an import type edge is erased and is not a runtime edge", () => {
+    const edges = runtimeImportEdges(
+      'import type { QuotaResetEvent } from "../quota/reset-detector";' + "\n",
+    );
+    expect(edges).toEqual([]);
+  });
+
+  test("the seam assertion fails when the observer wiring is removed", () => {
+    // Guard on the guard: proves the dynamic-only assertion is not vacuously satisfiable by
+    // a seam that names the observer nowhere at all.
+    const edges = runtimeImportEdges("export const nothing = 1;\n");
+    expect(edges.map(edge => edge.spec)).not.toContain(OBSERVER_SPEC);
+  });
+});
diff --git a/tests/usage/quota-reset-detector.test.ts b/tests/usage/quota-reset-detector.test.ts
new file mode 100644
index 0000000000..3ce61d7b7b
--- /dev/null
+++ b/tests/usage/quota-reset-detector.test.ts
@@ -0,0 +1,326 @@
+import { describe, expect, test } from "bun:test";
+import {
+  detectQuotaReset,
+  detectQuotaResets,
+  MIN_SURPRISE_DROP_PERCENT,
+  quotaAccountTag,
+} from "../../src/quota/reset-detector";
+
+const NOW = 1_772_000_000_000;
+const HOUR = 60 * 60_000;
+const DAY_MS = 24 * HOUR;
+
+function detect(
+  previous: { percent?: number; resetAt?: number } | undefined,
+  next: { percent?: number; resetAt?: number },
+  now = NOW,
+) {
+  return detectQuotaReset({
+    scope: "codex",
+    accountTag: "tag00000",
+    previous: previous ? { window: "weekly", ...previous } : undefined,
+    next: { window: "weekly", ...next },
+    now,
+  });
+}
+
+describe("quota reset detection", () => {
+  test("a passed deadline plus a percent drop is a scheduled rollover", () => {
+    const event = detect(
+      { percent: 96, resetAt: NOW - 60_000 },
+      { percent: 2, resetAt: NOW + 7 * 24 * HOUR },
+    );
+    expect(event?.kind).toBe("scheduled");
+    expect(event?.percentBefore).toBe(96);
+    expect(event?.percentAfter).toBe(2);
+  });
+
+  test("a passed deadline with no drop is still a scheduled rollover", () => {
+    // Barely-used window: percent is unchanged, but upstream issued a NEW deadline, which
+    // is the corroboration that it really turned over.
+    const event = detect(
+      { percent: 3, resetAt: NOW - 60_000 },
+      { percent: 3, resetAt: NOW + 7 * 24 * HOUR },
+    );
+    expect(event?.kind).toBe("scheduled");
+  });
+
+  test("a carried-forward window past its deadline is NOT a reset", () => {
+    // src/codex/quota.ts:323-329 copies the previous burst tuple verbatim when a header
+    // write omits it. Identical percent AND identical deadline means upstream said nothing,
+    // so an expired clock alone must not fire — this path runs once per pooled response.
+    expect(detect(
+      { percent: 42, resetAt: NOW - 60_000 },
+      { percent: 42, resetAt: NOW - 60_000 },
+    )).toBeNull();
+  });
+
+  test("usage rising past a passed deadline is not a reset", () => {
+    expect(detect({ percent: 10, resetAt: NOW - 60_000 }, { percent: 24 })).toBeNull();
+  });
+
+  test("a material drop inside an unexpired window is a surprise reset", () => {
+    const event = detect(
+      { percent: 96, resetAt: NOW + 2 * HOUR },
+      { percent: 4, resetAt: NOW + 9 * HOUR },
+    );
+    expect(event?.kind).toBe("surprise");
+  });
+
+  test("a deadline that jumps forward at a flat percent is NOT a reset", () => {
+    // A rolling window's deadline creeps forward on every poll by the elapsed time, so an
+    // advancing deadline is true of every healthy observation. Firing on it would notify
+    // continuously. And with usage flat, no quota came back, so there is nothing to report.
+    expect(detect(
+      { percent: 40, resetAt: NOW + 2 * HOUR },
+      { percent: 40, resetAt: NOW + 9 * HOUR },
+    )).toBeNull();
+  });
+
+  test("a rolling window creeping forward across many polls never fires", () => {
+    for (let poll = 1; poll <= 5; poll += 1) {
+      const event = detect(
+        { percent: 40, resetAt: NOW + 5 * HOUR + (poll - 1) * 60_000 },
+        { percent: 40 + poll, resetAt: NOW + 5 * HOUR + poll * 60_000 },
+        NOW + poll * 60_000,
+      );
+      expect(event).toBeNull();
+    }
+  });
+
+  test("ordinary usage increase is not a reset", () => {
+    expect(detect({ percent: 40, resetAt: NOW + 2 * HOUR }, { percent: 65, resetAt: NOW + 2 * HOUR })).toBeNull();
+  });
+
+  test("a sub-threshold drop is rounding noise, not a reset", () => {
+    const drop = MIN_SURPRISE_DROP_PERCENT - 1;
+    expect(detect(
+      { percent: 61, resetAt: NOW + 2 * HOUR },
+      { percent: 61 - drop, resetAt: NOW + 2 * HOUR },
+    )).toBeNull();
+  });
+
+  test("a drop exactly at the threshold fires", () => {
+    expect(detect(
+      { percent: 61, resetAt: NOW + 2 * HOUR },
+      { percent: 61 - MIN_SURPRISE_DROP_PERCENT, resetAt: NOW + 2 * HOUR },
+    )?.kind).toBe("surprise");
+  });
+
+  test("no previous observation is never a reset", () => {
+    // Cold start, reauth row clear, reconciliation delete, and account switch all land here.
+    expect(detect(undefined, { percent: 0, resetAt: NOW + HOUR })).toBeNull();
+  });
+
+  test("a vanished percent is not a reset", () => {
+    expect(detect({ percent: 90, resetAt: NOW + HOUR }, { resetAt: NOW + HOUR })).toBeNull();
+  });
+
+  test("sentinel reset clocks are ignored rather than read as 1970", () => {
+    // src/providers/quota.ts:279 and src/codex/quota.ts:192 disagree on whether 0 survives,
+    // so the detector re-checks: a 0 deadline must not read as a long-passed one.
+    expect(detect({ percent: 90, resetAt: 0 }, { percent: 88, resetAt: 0 })).toBeNull();
+  });
+
+  test("the same post-reset window yields a stable idempotence key", () => {
+    const first = detect({ percent: 96, resetAt: NOW - 60_000 }, { percent: 2, resetAt: NOW + HOUR });
+    // A second observer re-reads the same transition a moment later. The key must match, so
+    // whichever one claims it first suppresses the other.
+    const second = detect(
+      { percent: 96, resetAt: NOW - 30_000 },
+      { percent: 2, resetAt: NOW + HOUR },
+      NOW + 1_000,
+    );
+    expect(first?.kind).toBe("scheduled");
+    expect(second?.kind).toBe("scheduled");
+    expect(first?.key).toBe(second?.key);
+  });
+
+  test("account tags differ per account and are salted against brute force", () => {
+    const salt = "0123456789abcdef0123456789abcdef";
+    const left = quotaAccountTag("acct-one@example.test", salt);
+    const right = quotaAccountTag("acct-two@example.test", salt);
+    expect(left).not.toBe(right);
+    expect(left).not.toContain("@");
+    expect(left).toHaveLength(8);
+
+    // The salt is what makes the tag unlinkable to a webhook recipient: the same account
+    // under a different install salt must not produce the same tag, or an offline dictionary
+    // attack against a guessable email space would recover the identity.
+    const otherInstall = quotaAccountTag("acct-one@example.test", "fedcba9876543210fedcba9876543210");
+    expect(otherInstall).not.toBe(left);
+
+    // Stable within an install, which is what the persisted idempotence key depends on.
+    expect(quotaAccountTag("acct-one@example.test", salt)).toBe(left);
+  });
+
+  test("a negative percent is not read as a huge drop", () => {
+    // Both upstream normalizers clamp to 0-100, but the detector re-checks its own inputs
+    // rather than trusting a caller — the same reason it re-validates resetAt.
+    expect(detect(
+      { percent: 10, resetAt: NOW + 2 * HOUR },
+      { percent: -50, resetAt: NOW + 2 * HOUR },
+    )).toBeNull();
+  });
+
+  test("window lists are paired by identity, and a mismatched pairing is refused", () => {
+    const events = detectQuotaResets({
+      scope: "codex",
+      accountTag: "tag00000",
+      previous: [
+        { window: "5h", percent: 88, resetAt: NOW - 60_000 },
+        { window: "weekly", percent: 40, resetAt: NOW + 5 * 24 * HOUR },
+      ],
+      next: [
+        { window: "5h", percent: 1, resetAt: NOW + 5 * HOUR },
+        { window: "weekly", percent: 41, resetAt: NOW + 5 * 24 * HOUR },
+      ],
+      now: NOW,
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0]?.window).toBe("5h");
+    expect(events[0]?.kind).toBe("scheduled");
+  });
+
+  test("a window present only in the new snapshot is a baseline, not a reset", () => {
+    const events = detectQuotaResets({
+      scope: "anthropic",
+      accountTag: "tag00000",
+      previous: [],
+      next: [{ window: "custom:Opus", percent: 0, resetAt: NOW + HOUR }],
+      now: NOW,
+    });
+    expect(events).toEqual([]);
+  });
+
+  test("a clockless reset keys on the expired deadline instead of a shared sentinel", () => {
+    // Upstream reported no NEW deadline. Keying every such reset as "none" would let the
+    // first claim permanently suppress every later reset of this window.
+    const first = detect({ percent: 90, resetAt: NOW - 1_000 }, { percent: 1 });
+    const later = detect(
+      { percent: 90, resetAt: NOW + 30 * DAY_MS },
+      { percent: 1 },
+      NOW + 31 * DAY_MS,
+    );
+    expect(first?.kind).toBe("scheduled");
+    expect(later?.kind).toBe("scheduled");
+    expect(first?.key).not.toBe(later?.key);
+  });
+
+  test("a window with no deadline on either side is not evaluated", () => {
+    // Credit-balance providers never emit a reset clock; a bare drop there is as likely to
+    // be a top-up as a rollover.
+    expect(detect({ percent: 90 }, { percent: 5 })).toBeNull();
+  });
+
+  test("a deadline moving backward before its own expiry is not a reset", () => {
+    expect(detect(
+      { percent: 40, resetAt: NOW + 2 * HOUR },
+      { percent: 40, resetAt: NOW + HOUR },
+    )).toBeNull();
+  });
+
+  test("a deadline exactly equal to now counts as expired", () => {
+    expect(detect({ percent: 90, resetAt: NOW }, { percent: 1, resetAt: NOW + HOUR })?.kind)
+      .toBe("scheduled");
+  });
+
+  test("a clockless snapshot past an expired deadline still fires when usage fell", () => {
+    expect(detect({ percent: 90, resetAt: NOW - 1_000 }, { percent: 1 })?.kind).toBe("scheduled");
+  });
+});
+
+describe("a rolling window's natural creep is not a reset", () => {
+  const base = { scope: "codex", accountTag: "tag00000" } as const;
+
+  test("an hour into a 5h window, a 27-point decay fires nothing", () => {
+    // Measured false positive. A rolling window (Anthropic five_hour, Codex burst) has no
+    // rollover instant: usage ages out continuously, so its percent falls and its deadline
+    // slides forward by about the elapsed time. MIN_SURPRISE_DROP_PERCENT only screens integer
+    // rounding, so 88% -> 61% read as a surprise reset on the most common window in the system.
+    const now = Date.now();
+    expect(detectQuotaReset({
+      ...base,
+      previous: {
+        window: "5h",
+        percent: 88,
+        resetAt: now + 4 * HOUR,
+        windowSeconds: 5 * 3600,
+        observedAt: now - HOUR,
+      },
+      next: { window: "5h", percent: 61, resetAt: now + 5 * HOUR, windowSeconds: 5 * 3600 },
+      now,
+    })).toBeNull();
+  });
+
+  test("a deadline that jumps a whole window is still a surprise reset", () => {
+    // The discriminator is deadline MOVEMENT against elapsed time, not drop magnitude: decay
+    // magnitude cannot be bounded from elapsed time, since an hour of idling can retire a large
+    // burst that all landed in one minute. Two minutes elapsed, deadline forward two hours —
+    // that is a new window, not creep.
+    const now = Date.now();
+    expect(detectQuotaReset({
+      ...base,
+      previous: {
+        window: "5h",
+        percent: 95,
+        resetAt: now + 3 * HOUR,
+        windowSeconds: 5 * 3600,
+        observedAt: now - 120_000,
+      },
+      next: { window: "5h", percent: 3, resetAt: now + 5 * HOUR, windowSeconds: 5 * 3600 },
+      now,
+    })?.kind).toBe("surprise");
+  });
+
+  test("a standing-still deadline with falling usage is the clearest surprise signature", () => {
+    const now = Date.now();
+    const deadline = now + 3 * HOUR;
+    expect(detectQuotaReset({
+      ...base,
+      previous: {
+        window: "5h",
+        percent: 90,
+        resetAt: deadline,
+        windowSeconds: 5 * 3600,
+        observedAt: now - 60_000,
+      },
+      next: { window: "5h", percent: 4, resetAt: deadline, windowSeconds: 5 * 3600 },
+      now,
+    })?.kind).toBe("surprise");
+  });
+
+  test("a baseline written before observedAt existed fails OPEN", () => {
+    // Absent evidence must not suppress a real reset. Old state files have no observedAt.
+    const now = Date.now();
+    expect(detectQuotaReset({
+      ...base,
+      previous: { window: "5h", percent: 95, resetAt: now + 3 * HOUR, windowSeconds: 5 * 3600 },
+      next: { window: "5h", percent: 3, resetAt: now + 5 * HOUR, windowSeconds: 5 * 3600 },
+      now,
+    })?.kind).toBe("surprise");
+  });
+
+  test("the creep rule does not touch the scheduled branch", () => {
+    // A scheduled rollover is proven by its own expired deadline, so it needs no magnitude or
+    // movement test — and a weekly window issuing a week-long deadline must not read as creep.
+    const now = Date.now();
+    expect(detectQuotaReset({
+      ...base,
+      previous: {
+        window: "weekly",
+        percent: 90,
+        resetAt: now - 1_000,
+        windowSeconds: 7 * 24 * 3600,
+        observedAt: now - HOUR,
+      },
+      next: {
+        window: "weekly",
+        percent: 0,
+        resetAt: now + 7 * 24 * HOUR,
+        windowSeconds: 7 * 24 * 3600,
+      },
+      now,
+    })?.kind).toBe("scheduled");
+  });
+});
diff --git a/tests/usage/quota-reset-notify-config.test.ts b/tests/usage/quota-reset-notify-config.test.ts
new file mode 100644
index 0000000000..f869b2b89f
--- /dev/null
+++ b/tests/usage/quota-reset-notify-config.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import { resolveQuotaResetNotify } from "../../src/quota/reset-notify-config";
+import { getDefaultConfig, validateConfigCandidate } from "../../src/config";
+
+describe("quotaResetNotify schema", () => {
+  function candidate(webhookUrl: string): unknown {
+    return { ...getDefaultConfig(), quotaResetNotify: { enabled: true, webhookUrl } };
+  }
+
+  test("an http webhookUrl is rejected as schema_invalid", () => {
+    // The payload carries account identity and the URL itself is often a bearer-equivalent
+    // secret, so cleartext delivery is a boundary violation rather than a preference.
+    const result = validateConfigCandidate(candidate("http://hooks.example.test/abc"));
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error).toContain("schema_invalid: quotaResetNotify.webhookUrl");
+  });
+
+  test("an https webhookUrl is accepted", () => {
+    expect(validateConfigCandidate(candidate("https://hooks.example.test/abc")).ok).toBe(true);
+  });
+});
+
+describe("quotaResetNotify resolution", () => {
+  test("an absent section is off", () => {
+    expect(resolveQuotaResetNotify(undefined).enabled).toBe(false);
+    expect(resolveQuotaResetNotify(null).enabled).toBe(false);
+    expect(resolveQuotaResetNotify({}).enabled).toBe(false);
+  });
+
+  test("enabled with no sink is treated as off", () => {
+    // An enabled notifier with nowhere to send is a misconfiguration. Reporting it as off is
+    // what keeps the default-OFF guarantee honest: no sink means no timer and no observation.
+    expect(resolveQuotaResetNotify({ enabled: true }).enabled).toBe(false);
+    expect(resolveQuotaResetNotify({ enabled: true, command: [] }).enabled).toBe(false);
+    expect(resolveQuotaResetNotify({ enabled: true, webhookUrl: "   " }).enabled).toBe(false);
+  });
+
+  test("enabled with a webhook or a command is on", () => {
+    expect(resolveQuotaResetNotify({
+      enabled: true,
+      webhookUrl: "https://hooks.example.test/abc",
+    }).enabled).toBe(true);
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["notify.sh"] }).enabled).toBe(true);
+  });
+
+  test("kinds default to both and filter to what was asked for", () => {
+    const both = resolveQuotaResetNotify({ enabled: true, command: ["x"] });
+    expect([...both.kinds].sort()).toEqual(["scheduled", "surprise"]);
+
+    const only = resolveQuotaResetNotify({ enabled: true, command: ["x"], kinds: ["surprise"] });
+    expect([...only.kinds]).toEqual(["surprise"]);
+
+    // An unrecognized value must not silently produce an empty set that drops every event.
+    const bogus = resolveQuotaResetNotify({ enabled: true, command: ["x"], kinds: ["nonsense"] });
+    expect([...bogus.kinds].sort()).toEqual(["scheduled", "surprise"]);
+  });
+
+  test("poll seconds clamp, and 0 means passive-only", () => {
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["x"] }).pollMs).toBe(900_000);
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["x"], pollSeconds: 0 }).pollMs).toBe(0);
+    // Below the floor: a 1-second poll would hammer a quota endpoint that rate-limits.
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["x"], pollSeconds: 1 }).pollMs)
+      .toBe(600_000);
+  });
+
+  test("timeout clamps into a sane band", () => {
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["x"] }).timeoutMs).toBe(5_000);
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["x"], timeoutMs: 999_999 }).timeoutMs)
+      .toBe(30_000);
+    expect(resolveQuotaResetNotify({ enabled: true, command: ["x"], timeoutMs: -5 }).timeoutMs)
+      .toBe(100);
+  });
+
+  test("private-network delivery is opt-in", () => {
+    expect(resolveQuotaResetNotify({
+      enabled: true,
+      webhookUrl: "http://127.0.0.1:9000/hook",
+    }).allowPrivateNetwork).toBe(false);
+    expect(resolveQuotaResetNotify({
+      enabled: true,
+      webhookUrl: "http://127.0.0.1:9000/hook",
+      allowPrivateNetwork: true,
+    }).allowPrivateNetwork).toBe(true);
+  });
+
+  test("a garbage section resolves to off rather than throwing", () => {
+    expect(resolveQuotaResetNotify("nope").enabled).toBe(false);
+    expect(resolveQuotaResetNotify([1, 2, 3]).enabled).toBe(false);
+    expect(resolveQuotaResetNotify({ enabled: "yes", webhookUrl: 42 }).enabled).toBe(false);
+  });
+});
diff --git a/tests/usage/quota-reset-notify.test.ts b/tests/usage/quota-reset-notify.test.ts
new file mode 100644
index 0000000000..fb053e10d8
--- /dev/null
+++ b/tests/usage/quota-reset-notify.test.ts
@@ -0,0 +1,551 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handleConfigCommand } from "../../src/cli/config-command";
+import { validateConfigCandidate } from "../../src/config";
+import { handleManagementAPI } from "../../src/server/management-api";
+import type { OcxConfig } from "../../src/types";
+import {
+  recordQuotaResetEvent,
+  resetQuotaResetStoreForTests,
+} from "../../src/quota/reset-seen-store";
+import type { QuotaResetEvent } from "../../src/quota/reset-detector";
+import {
+  resetQuotaResetNotifyCacheForTests,
+  resolveQuotaResetNotify,
+} from "../../src/quota/reset-notify-config";
+import {
+  resetQuotaResetActivationForTests,
+  syncQuotaResetActivation,
+} from "../../src/quota/reset-activation";
+import { hasQuotaResetSink, setQuotaResetSink } from "../../src/quota/reset-observer";
+import {
+  clearAccountQuota,
+  flushQuotaObservationsForTests,
+  setAccountQuotaFromParsed,
+} from "../../src/codex/quota";
+import {
+  deliverQuotaResetEvent,
+  quotaResetPayloadForTests,
+} from "../../src/quota/reset-sinks";
+
+const NOW = Date.now();
+
+function event(overrides: Partial<QuotaResetEvent> = {}): QuotaResetEvent {
+  return {
+    kind: "surprise",
+    scope: "codex",
+    accountTag: "9rhlw1hu",
+    window: "weekly",
+    percentBefore: 96,
+    percentAfter: 4,
+    previousResetAt: NOW + 3 * 86_400_000,
+    resetAt: NOW + 7 * 86_400_000,
+    detectedAt: NOW,
+    key: "codex|9rhlw1hu|weekly|1",
+    ...overrides,
+  };
+}
+
+describe("the delivered payload carries no identity", () => {
+  test("it names its fields rather than spreading the event", () => {
+    // The internal idempotence `key` encodes the scope and account tag and has no business
+    // crossing a webhook boundary. A spread would forward it, and would forward whatever the
+    // detector gains next, silently.
+    const payload = quotaResetPayloadForTests(event()) as Record<string, unknown>;
+
+    expect(payload["key"]).toBeUndefined();
+    expect(Object.keys(payload).sort()).toEqual([
+      "accountTag",
+      "detectedAt",
+      "kind",
+      "percentAfter",
+      "percentBefore",
+      "previousResetAt",
+      "resetAt",
+      "scope",
+      "type",
+      "window",
+    ]);
+  });
+
+  test("absent numbers are omitted rather than sent as null", () => {
+    const payload = quotaResetPayloadForTests({
+      kind: "scheduled",
+      scope: "anthropic",
+      accountTag: "aaaaaaaa",
+      window: "5h",
+      detectedAt: NOW,
+      key: "k",
+    }) as Record<string, unknown>;
+
+    expect("percentBefore" in payload).toBe(false);
+    expect("resetAt" in payload).toBe(false);
+  });
+});
+
+describe("webhook sink", () => {
+  test("a fired event POSTs exactly one JSON body with no identifying data", async () => {
+    const bodies: string[] = [];
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      async fetch(req) {
+        bodies.push(await req.text());
+        return new Response("ok");
+      },
+    });
+    try {
+      const config = resolveQuotaResetNotify({
+        enabled: true,
+        webhookUrl: `http://127.0.0.1:${server.port}/hook`,
+        // Loopback is refused by default; a test receiver is the legitimate opt-in case.
+        allowPrivateNetwork: true,
+      });
+      const results = await deliverQuotaResetEvent(event(), config);
+
+      expect(results).toEqual([{ sink: "webhook", ok: true }]);
+      expect(bodies).toHaveLength(1);
+
+      const raw = bodies[0] ?? "";
+      // The account key fed to the detector is an email on the codex path, so these three
+      // assertions are the privacy contract that privacy:scan structurally cannot check: it
+      // reads repository text, not runtime output.
+      expect(raw).not.toContain("@");
+      expect(raw).not.toContain("/Users/");
+      expect(JSON.parse(raw)).not.toHaveProperty("accountId");
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("a loopback target is refused unless explicitly allowed", async () => {
+    // An operator-supplied URL is an SSRF surface: this process reaches loopback services and
+    // metadata endpoints a browser cannot.
+    const config = resolveQuotaResetNotify({
+      enabled: true,
+      webhookUrl: "http://127.0.0.1:9/blocked",
+    });
+    expect(await deliverQuotaResetEvent(event(), config)).toEqual([
+      { sink: "webhook", ok: false, reason: "blocked-destination" },
+    ]);
+  });
+
+  test("a non-2xx response reports http-error and never throws", async () => {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("nope", { status: 500 }),
+    });
+    try {
+      const config = resolveQuotaResetNotify({
+        enabled: true,
+        webhookUrl: `http://127.0.0.1:${server.port}/hook`,
+        allowPrivateNetwork: true,
+      });
+      expect(await deliverQuotaResetEvent(event(), config)).toEqual([
+        { sink: "webhook", ok: false, reason: "http-error" },
+      ]);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("a webhook that redirects to loopback is refused", async () => {
+    // The initial URL is validated; the redirect target is not. A public HTTPS endpoint can
+    // 302 the POST to loopback or a metadata address, which would re-open the SSRF hole the
+    // destination check just closed. Stubbed rather than served: this asserts the request
+    // mode itself, and a real listener is unavailable under the sandbox.
+    const seen: Array<RequestInit | undefined> = [];
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = (async (_input: unknown, init?: RequestInit) => {
+      seen.push(init);
+      return new Response(null, { status: 302, headers: { location: "http://127.0.0.1:9/" } });
+    }) as unknown as typeof globalThis.fetch;
+    try {
+      const config = resolveQuotaResetNotify({
+        enabled: true,
+        webhookUrl: "https://hooks.example.test/hook",
+        allowPrivateNetwork: true,
+      });
+      expect(await deliverQuotaResetEvent(event(), config)).toEqual([
+        { sink: "webhook", ok: false, reason: "blocked-destination" },
+      ]);
+      // The refusal must come from not following, not from a followed request that failed.
+      expect(seen).toHaveLength(1);
+      expect(seen[0]?.redirect).toBe("manual");
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+
+  test("a hanging receiver times out rather than blocking forever", async () => {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Promise<Response>(() => {
+        // Never resolves: the timeout is the only thing that can end this request.
+      }),
+    });
+    try {
+      const config = resolveQuotaResetNotify({
+        enabled: true,
+        webhookUrl: `http://127.0.0.1:${server.port}/hook`,
+        allowPrivateNetwork: true,
+        timeoutMs: 150,
+      });
+      expect(await deliverQuotaResetEvent(event(), config)).toEqual([
+        { sink: "webhook", ok: false, reason: "timeout" },
+      ]);
+    } finally {
+      server.stop(true);
+    }
+  });
+});
+
+describe("command sink", () => {
+  test("the event JSON arrives on stdin", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-cmd-"));
+    const out = join(dir, "captured.json");
+    const script = join(dir, "sink.ts");
+    writeFileSync(script, [
+      `const body = await Bun.stdin.text();`,
+      `await Bun.write(${JSON.stringify(out)}, body);`,
+    ].join("\n"));
+
+    const config = resolveQuotaResetNotify({ enabled: true, command: ["bun", script] });
+    const results = await deliverQuotaResetEvent(event(), config);
+
+    expect(results).toEqual([{ sink: "command", ok: true }]);
+    const captured = JSON.parse(await Bun.file(out).text()) as Record<string, unknown>;
+    expect(captured["type"]).toBe("quota_reset");
+    expect(captured["kind"]).toBe("surprise");
+    // Pinned because a plain string throws ERR_INVALID_ARG_TYPE on Bun 1.4.0, so the encoded
+    // form is load-bearing rather than stylistic.
+    expect(captured["window"]).toBe("weekly");
+  });
+
+  test("a missing binary reports spawn-failed rather than throwing", async () => {
+    const config = resolveQuotaResetNotify({
+      enabled: true,
+      command: ["ocx-no-such-binary-a7f3", "--go"],
+    });
+    expect(await deliverQuotaResetEvent(event(), config)).toEqual([
+      { sink: "command", ok: false, reason: "spawn-failed" },
+    ]);
+  });
+
+  test("a non-zero exit is reported without inspecting the output", async () => {
+    const config = resolveQuotaResetNotify({ enabled: true, command: ["false"] });
+    expect(await deliverQuotaResetEvent(event(), config)).toEqual([
+      { sink: "command", ok: false, reason: "spawn-failed" },
+    ]);
+  });
+});
+
+describe("sinks are independent", () => {
+  test("a blocked webhook does not stop the command from running", async () => {
+    // The whole point of two sinks is redundancy; one failing must not suppress the other.
+    const dir = mkdtempSync(join(tmpdir(), "ocx-both-"));
+    const out = join(dir, "ran.txt");
+    const script = join(dir, "sink.ts");
+    writeFileSync(script, `await Bun.write(${JSON.stringify(out)}, "ran");`);
+
+    const config = resolveQuotaResetNotify({
+      enabled: true,
+      webhookUrl: "http://127.0.0.1:9/blocked",
+      command: ["bun", script],
+    });
+    const results = await deliverQuotaResetEvent(event(), config);
+
+    expect(results).toContainEqual({ sink: "webhook", ok: false, reason: "blocked-destination" });
+    expect(results).toContainEqual({ sink: "command", ok: true });
+    expect(await Bun.file(out).text()).toBe("ran");
+  });
+});
+
+describe("kind filtering", () => {
+  test("an excluded kind is not delivered at all", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-kind-"));
+    const out = join(dir, "should-not-exist.txt");
+    const script = join(dir, "sink.ts");
+    writeFileSync(script, `await Bun.write(${JSON.stringify(out)}, "ran");`);
+
+    const config = resolveQuotaResetNotify({
+      enabled: true,
+      kinds: ["surprise"],
+      command: ["bun", script],
+    });
+
+    expect(await deliverQuotaResetEvent(event({ kind: "scheduled" }), config)).toEqual([]);
+    expect(await Bun.file(out).exists()).toBe(false);
+
+    expect(await deliverQuotaResetEvent(event({ kind: "surprise" }), config)).toEqual([
+      { sink: "command", ok: true },
+    ]);
+  });
+});
+
+describe("enablement", () => {
+  test("enabled with no sink resolves to off", () => {
+    // An enabled subsystem with nowhere to deliver is a misconfiguration, and reporting it as
+    // off is what keeps the default-OFF guarantee true rather than nearly true.
+    expect(resolveQuotaResetNotify({ enabled: true }).enabled).toBe(false);
+  });
+
+  test("an absent section resolves to off", () => {
+    expect(resolveQuotaResetNotify(undefined).enabled).toBe(false);
+  });
+
+  test("a disabled section with sinks configured stays off", () => {
+    expect(resolveQuotaResetNotify({
+      webhookUrl: "https://example.com/hook",
+    }).enabled).toBe(false);
+  });
+});
+
+describe("config integration", () => {
+  test("an invalid notify section is rejected by the write path", () => {
+    // Live writes stay strict, so an operator is told rather than silently ignored.
+    const result = validateConfigCandidate({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: { openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1" } },
+      quotaResetNotify: { enabled: "yes" },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("quotaResetNotify");
+  });
+
+  test("an unknown key in the notify section is rejected, not ignored", () => {
+    // `.strict()`: a typo that silently does nothing is worse than a rejected write, because the
+    // operator believes they enabled something.
+    const result = validateConfigCandidate({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: { openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1" } },
+      quotaResetNotify: { enabled: true, webhokUrl: "https://example.com/h" },
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("a valid notify section passes the write path", () => {
+    const result = validateConfigCandidate({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: { openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1" } },
+      quotaResetNotify: {
+        enabled: true,
+        kinds: ["surprise"],
+        webhookUrl: "https://hooks.example.com/services/abc",
+        pollSeconds: 0,
+      },
+    });
+
+    expect(result.ok).toBe(true);
+  });
+});
+
+describe("webhookUrl is treated as a credential", () => {
+  test("ocx config show does not print it", async () => {
+    // For Slack and Discord the URL IS the authorization: anyone holding it can post to the
+    // channel. It matches none of the pre-existing secret-key patterns, so it had to be named
+    // explicitly — before that, `config show` printed it and `config export` wrote it to disk.
+    const home = mkdtempSync(join(tmpdir(), "ocx-redact-"));
+    const secret = "https://hooks.slack.com/services/T00000/B00000/zzTOKENzz";
+    writeFileSync(join(home, "config.json"), JSON.stringify({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: {
+        openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1", authMode: "forward" },
+      },
+      quotaResetNotify: { enabled: true, webhookUrl: secret },
+    }));
+
+    const previousHome = process.env["OPENCODEX_HOME"];
+    process.env["OPENCODEX_HOME"] = home;
+    const written: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => { written.push(args.map(String).join(" ")); };
+    try {
+      expect(await handleConfigCommand(["show", "--json"])).toBe(0);
+      const output = written.join("\n");
+      // The whole point: the section is visible, the credential is not.
+      expect(output).toContain("quotaResetNotify");
+      expect(output).not.toContain("zzTOKENzz");
+      expect(output).toContain("********");
+    } finally {
+      console.log = originalLog;
+      if (previousHome === undefined) delete process.env["OPENCODEX_HOME"];
+      else process.env["OPENCODEX_HOME"] = previousHome;
+    }
+  });
+});
+
+describe("GET /api/quota-resets", () => {
+  function managementConfig(): OcxConfig {
+    return {
+      port: 10100,
+      defaultProvider: "openai",
+      providers: {
+        openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1" },
+      },
+    } as OcxConfig;
+  }
+
+  async function get(path: string): Promise<Response | null> {
+    const req = new Request(`http://localhost${path}`, {
+      method: "GET",
+      headers: { host: "localhost" },
+    });
+    return handleManagementAPI(req, new URL(req.url), managementConfig(), {
+      saveConfigPreservingClaudeCode: () => {},
+    });
+  }
+
+  test("it reports recorded events and whether detection is even on", async () => {
+    // An isolated OPENCODEX_HOME, because the event ring is PERSISTED. Without this the store
+    // hydrates from the developer's real state file and the count assertion below reflects
+    // whatever that machine happens to hold — which is how this test first failed only when run
+    // after the suites that write events.
+    const home = mkdtempSync(join(tmpdir(), "ocx-route-"));
+    const previousHome = process.env["OPENCODEX_HOME"];
+    process.env["OPENCODEX_HOME"] = home;
+    try {
+      resetQuotaResetStoreForTests();
+      recordQuotaResetEvent(event({ key: "codex|tag|weekly|route" }));
+
+      const response = await get("/api/quota-resets");
+      expect(response?.status).toBe(200);
+
+      const body = await response?.json() as { enabled: boolean; events: unknown[] };
+      // `enabled` travels with the list because an empty list is otherwise ambiguous: an operator
+      // debugging a missing notification cannot tell "nothing reset" from "never turned on".
+      expect(body.enabled).toBe(false);
+      expect(body.events).toHaveLength(1);
+    } finally {
+      resetQuotaResetStoreForTests();
+      if (previousHome === undefined) delete process.env["OPENCODEX_HOME"];
+      else process.env["OPENCODEX_HOME"] = previousHome;
+    }
+  });
+
+  test("a non-numeric limit is rejected rather than silently defaulted", async () => {
+    const response = await get("/api/quota-resets?limit=lots");
+    expect(response?.status).toBe(400);
+  });
+
+  test("an unrelated management path is left to the rest of the chain", async () => {
+    // The handler is prefix-guarded, so it must return null rather than answering for
+    // everything: returning a response here would shadow every other route.
+    const response = await get("/api/quota-resets/extra");
+    expect(response?.status).not.toBe(200);
+  });
+});
+
+describe("activation is the single switch", () => {
+  test("an absent config section installs no sink at all", async () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-inert-"));
+    writeFileSync(join(home, "config.json"), JSON.stringify({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: {
+        openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1", authMode: "forward" },
+      },
+    }));
+
+    const previousHome = process.env["OPENCODEX_HOME"];
+    process.env["OPENCODEX_HOME"] = home;
+    try {
+      resetQuotaResetNotifyCacheForTests();
+      resetQuotaResetActivationForTests();
+      setQuotaResetSink(null);
+
+      expect(await syncQuotaResetActivation()).toBe(false);
+      // No sink means observeQuotaSnapshot returns before it stores a baseline, which is what
+      // makes "a default install executes no detection" true rather than nearly true.
+      expect(hasQuotaResetSink()).toBe(false);
+    } finally {
+      setQuotaResetSink(null);
+      resetQuotaResetActivationForTests();
+      resetQuotaResetNotifyCacheForTests();
+      if (previousHome === undefined) delete process.env["OPENCODEX_HOME"];
+      else process.env["OPENCODEX_HOME"] = previousHome;
+    }
+  });
+
+  test("a real rollover reaches a webhook once the section is enabled", async () => {
+    // The end-to-end proof: config -> activation -> the production quota writer -> HTTP body.
+    // Every earlier test exercises one link; this is the only one that shows the chain holds.
+    const bodies: string[] = [];
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      async fetch(req) {
+        bodies.push(await req.text());
+        return new Response("ok");
+      },
+    });
+
+    const home = mkdtempSync(join(tmpdir(), "ocx-live-"));
+    writeFileSync(join(home, "config.json"), JSON.stringify({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: {
+        openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1", authMode: "forward" },
+      },
+      quotaResetNotify: {
+        enabled: true,
+        webhookUrl: `http://127.0.0.1:${server.port}/hook`,
+        allowPrivateNetwork: true,
+        // Passive-only: this asserts the live request path fires without any timer involved.
+        pollSeconds: 0,
+      },
+    }));
+
+    const previousHome = process.env["OPENCODEX_HOME"];
+    process.env["OPENCODEX_HOME"] = home;
+    try {
+      resetQuotaResetNotifyCacheForTests();
+      resetQuotaResetStoreForTests();
+      resetQuotaResetActivationForTests();
+      expect(await syncQuotaResetActivation()).toBe(true);
+
+      // An email as the account key on purpose: the payload assertion below is what proves the
+      // salted tag, not the identifier, is what crosses the wire.
+      const expired = Date.now() - 60_000;
+      setAccountQuotaFromParsed("operator@example.com", { weeklyPercent: 96, weeklyResetAt: expired });
+      await flushQuotaObservationsForTests();
+
+      setAccountQuotaFromParsed("operator@example.com", {
+        weeklyPercent: 2,
+        weeklyResetAt: Date.now() + 7 * 86_400_000,
+      });
+      await flushQuotaObservationsForTests();
+      // The sink dispatch is fire-and-forget by contract, so the HTTP round trip needs a moment.
+      for (let attempt = 0; attempt < 40 && bodies.length === 0; attempt += 1) {
+        await new Promise(resolve => setTimeout(resolve, 25));
+      }
+
+      expect(bodies).toHaveLength(1);
+      const payload = JSON.parse(bodies[0] ?? "{}") as Record<string, unknown>;
+      expect(payload["type"]).toBe("quota_reset");
+      expect(payload["kind"]).toBe("scheduled");
+      expect(payload["window"]).toBe("weekly");
+      expect(payload["percentBefore"]).toBe(96);
+      expect(payload["percentAfter"]).toBe(2);
+      expect(bodies[0]).not.toContain("operator@example.com");
+    } finally {
+      setQuotaResetSink(null);
+      resetQuotaResetActivationForTests();
+      resetQuotaResetNotifyCacheForTests();
+      clearAccountQuota();
+      server.stop(true);
+      if (previousHome === undefined) delete process.env["OPENCODEX_HOME"];
+      else process.env["OPENCODEX_HOME"] = previousHome;
+    }
+  });
+});
diff --git a/tests/usage/quota-reset-observation.test.ts b/tests/usage/quota-reset-observation.test.ts
new file mode 100644
index 0000000000..3026e2a59b
--- /dev/null
+++ b/tests/usage/quota-reset-observation.test.ts
@@ -0,0 +1,309 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  clearAccountQuota,
+  flushQuotaObservationsForTests,
+  setAccountQuotaFromParsed,
+} from "../../src/codex/quota";
+import type { QuotaResetEvent } from "../../src/quota/reset-detector";
+import {
+  hasQuotaResetSink,
+  observeQuotaSnapshot,
+  setQuotaResetSink,
+} from "../../src/quota/reset-observer";
+import { resetQuotaResetStoreForTests } from "../../src/quota/reset-seen-store";
+import {
+  isQuotaResetPollerRunning,
+  resetQuotaResetPollerForTests,
+  startQuotaResetPoller,
+  stopQuotaResetPoller,
+} from "../../src/quota/reset-poller";
+import { resetQuotaResetNotifyCacheForTests } from "../../src/quota/reset-notify-config";
+
+const ACCOUNT = "acct_reset_observation";
+const HOUR = 60 * 60_000;
+
+let captured: QuotaResetEvent[] = [];
+
+/** Let the seams' lazy import() chains settle. */
+async function settle(): Promise<void> {
+  for (let index = 0; index < 6; index += 1) await Promise.resolve();
+  await new Promise(resolve => setTimeout(resolve, 5));
+}
+
+beforeEach(() => {
+  captured = [];
+  resetQuotaResetStoreForTests();
+  resetQuotaResetNotifyCacheForTests();
+  resetQuotaResetPollerForTests();
+  clearAccountQuota();
+  setQuotaResetSink(event => {
+    captured.push(event);
+  });
+});
+
+afterEach(() => {
+  setQuotaResetSink(null);
+  resetQuotaResetPollerForTests();
+  clearAccountQuota();
+});
+
+describe("codex quota seam", () => {
+  test("a weekly rollover through the real writer fires exactly one scheduled event", async () => {
+    const expired = Date.now() - 60_000;
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 96, weeklyResetAt: expired });
+    await settle();
+    expect(captured).toEqual([]); // first write is a baseline
+
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 2, weeklyResetAt: Date.now() + 7 * 24 * HOUR });
+    await settle();
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.kind).toBe("scheduled");
+    expect(captured[0]?.window).toBe("weekly");
+    expect(captured[0]?.scope).toBe("codex");
+
+    // Observing the same post-reset state again must not notify twice.
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 3, weeklyResetAt: Date.now() + 7 * 24 * HOUR });
+    await settle();
+    expect(captured).toHaveLength(1);
+  });
+
+  test("a surprise reset through the real writer fires a surprise event", async () => {
+    const future = Date.now() + 2 * HOUR;
+    setAccountQuotaFromParsed(ACCOUNT, { shortPercent: 96, shortResetAt: future, shortWindowSeconds: 18_000 });
+    await settle();
+    captured = [];
+
+    setAccountQuotaFromParsed(ACCOUNT, { shortPercent: 4, shortResetAt: future, shortWindowSeconds: 18_000 });
+    await settle();
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.kind).toBe("surprise");
+    expect(captured[0]?.window).toBe("5h");
+  });
+
+  test("a credits-only write fires nothing despite a fresh updatedAt", async () => {
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 40, weeklyResetAt: Date.now() + 3 * 24 * HOUR });
+    await settle();
+    captured = [];
+
+    // src/codex/quota.ts:276 copies every window field verbatim here.
+    setAccountQuotaFromParsed(ACCOUNT, { resetCredits: 3 });
+    await settle();
+    expect(captured).toEqual([]);
+  });
+
+  test("a cleared row followed by a fresh low percent fires nothing", async () => {
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 91, weeklyResetAt: Date.now() + 3 * 24 * HOUR });
+    await settle();
+    captured = [];
+
+    // Reauth and account purge both do this deliberately — and they clear ONLY the quota row.
+    // This test used to call resetQuotaResetStoreForTests() here too, which no production path
+    // does: it wiped the observer's separate baseline file and so simulated a state that never
+    // occurs. With that line removed the test failed (surprise, 91% -> 0%), which is what
+    // clearAccountQuota now forgetting its baseline fixes.
+    clearAccountQuota(ACCOUNT);
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 0, weeklyResetAt: Date.now() + 7 * 24 * HOUR });
+    await settle();
+    expect(captured).toEqual([]);
+  });
+
+  test("no sink installed means no observation at all", async () => {
+    setQuotaResetSink(null);
+    expect(hasQuotaResetSink()).toBe(false);
+    const expired = Date.now() - 60_000;
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 96, weeklyResetAt: expired });
+    await settle();
+    setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: 1, weeklyResetAt: Date.now() + HOUR });
+    await settle();
+    expect(captured).toEqual([]);
+  });
+});
+
+describe("observer contract", () => {
+  test("the baseline comes from the persisted map, not the caller", () => {
+    const expired = Date.now() - 60_000;
+    expect(observeQuotaSnapshot({
+      scope: "anthropic",
+      accountKey: "anthropic\u0000acct-1",
+      windows: [{ window: "weekly", percent: 88, resetAt: expired }],
+    })).toEqual([]);
+
+    const delivered = observeQuotaSnapshot({
+      scope: "anthropic",
+      accountKey: "anthropic\u0000acct-1",
+      windows: [{ window: "weekly", percent: 2, resetAt: Date.now() + 7 * 24 * HOUR }],
+    });
+    expect(delivered).toHaveLength(1);
+    expect(delivered[0]?.kind).toBe("scheduled");
+  });
+
+  test("two accounts of one provider do not inherit each other's history", () => {
+    const expired = Date.now() - 60_000;
+    observeQuotaSnapshot({
+      scope: "anthropic",
+      accountKey: "anthropic\u0000acct-A",
+      windows: [{ window: "weekly", percent: 96, resetAt: expired }],
+    });
+    // A switch to a different account is an identity change, not a reset.
+    const delivered = observeQuotaSnapshot({
+      scope: "anthropic",
+      accountKey: "anthropic\u0000acct-B",
+      windows: [{ window: "weekly", percent: 1, resetAt: Date.now() + HOUR }],
+    });
+    expect(delivered).toEqual([]);
+  });
+
+  test("a throwing sink does not propagate to the caller", () => {
+    setQuotaResetSink(() => {
+      throw new Error("sink exploded");
+    });
+    const expired = Date.now() - 60_000;
+    observeQuotaSnapshot({
+      scope: "codex",
+      accountKey: "throwing",
+      windows: [{ window: "weekly", percent: 96, resetAt: expired }],
+    });
+    expect(() => observeQuotaSnapshot({
+      scope: "codex",
+      accountKey: "throwing",
+      windows: [{ window: "weekly", percent: 1, resetAt: Date.now() + HOUR }],
+    })).not.toThrow();
+  });
+});
+
+describe("idle poller", () => {
+  test("starting twice creates one timer and stop clears it", () => {
+    expect(isQuotaResetPollerRunning()).toBe(false);
+    startQuotaResetPoller(60_000);
+    startQuotaResetPoller(60_000);
+    expect(isQuotaResetPollerRunning()).toBe(true);
+    stopQuotaResetPoller();
+    expect(isQuotaResetPollerRunning()).toBe(false);
+  });
+
+  test("a disabled config makes a tick a no-op", async () => {
+    const { runQuotaResetPollerTickForTests, quotaResetPollerTickCountForTests } = await import(
+      "../../src/quota/reset-poller"
+    );
+    await runQuotaResetPollerTickForTests();
+    expect(quotaResetPollerTickCountForTests()).toBe(0);
+  });
+
+  test("the interval floor matches the documented per-account TTL", async () => {
+    // The docstring claims the floor sits above the 10-minute per-account TTL; 60s did not.
+    const { MIN_INTERVAL_MS } = await import("../../src/quota/reset-poller");
+    expect(MIN_INTERVAL_MS).toBe(600_000);
+  });
+
+  test("the configured pollSeconds reaches the poller interval", async () => {
+    const { quotaResetPollerIntervalForTests } = await import("../../src/quota/reset-poller");
+    // Above the floor, so the configured cadence is what must survive to setInterval.
+    startQuotaResetPoller(1_800_000);
+    expect(quotaResetPollerIntervalForTests()).toBe(1_800_000);
+    stopQuotaResetPoller();
+
+    // Below the floor: clamped rather than accepted, so no timer outruns the account TTL.
+    startQuotaResetPoller(60_000);
+    expect(quotaResetPollerIntervalForTests()).toBe(600_000);
+    stopQuotaResetPoller();
+  });
+
+  test("an overlapping tick is skipped and a tick completing after stop does not publish", async () => {
+    const {
+      runQuotaResetPollerTickForTests,
+      quotaResetPollerTickCountForTests,
+    } = await import("../../src/quota/reset-poller");
+    // A real enabled config is what carries a tick past its early returns; the resolver reads
+    // the config file rather than exposing an injection seam.
+    const home = mkdtempSync(join(tmpdir(), "ocx-poller-"));
+    writeFileSync(join(home, "config.json"), JSON.stringify({
+      port: 10100,
+      defaultProvider: "openai",
+      providers: {
+        openai: { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1", authMode: "forward" },
+      },
+      quotaResetNotify: { enabled: true, command: ["true"], pollSeconds: 900 },
+    }));
+    const previousHome = process.env["OPENCODEX_HOME"];
+    process.env["OPENCODEX_HOME"] = home;
+    resetQuotaResetNotifyCacheForTests();
+    try {
+      startQuotaResetPoller(900_000);
+      const before = quotaResetPollerTickCountForTests();
+
+      // Two ticks launched without awaiting the first: the second must return immediately
+      // rather than issuing a second forced probe against a rate-limited endpoint.
+      const first = runQuotaResetPollerTickForTests();
+      const second = runQuotaResetPollerTickForTests();
+      await Promise.all([first, second]);
+      expect(quotaResetPollerTickCountForTests()).toBe(before + 1);
+
+      // A tick that starts and then loses the timer under it must not count as a probe:
+      // its result belongs to a generation that no longer owns the poller.
+      const late = runQuotaResetPollerTickForTests();
+      stopQuotaResetPoller();
+      await late;
+      expect(quotaResetPollerTickCountForTests()).toBe(before + 1);
+    } finally {
+      stopQuotaResetPoller();
+      if (previousHome === undefined) delete process.env["OPENCODEX_HOME"];
+      else process.env["OPENCODEX_HOME"] = previousHome;
+      resetQuotaResetNotifyCacheForTests();
+    }
+  });
+});
+
+describe("observation ordering under a burst", () => {
+  test("a rising-usage burst in a COLD process fires nothing", async () => {
+    // The regression this pins: the seam awaited two import() calls before swapping the
+    // baseline, and Bun does not resolve concurrent dynamic imports in call order. A burst of
+    // monotonically RISING usage — no reset anywhere in it — arrived reordered and produced a
+    // false "surprise" event on every run. The false event also claimed the durable
+    // idempotence key, so the genuine reset on that window was then suppressed permanently.
+    //
+    // Runs in a CHILD PROCESS deliberately. An in-process version of this test passed against
+    // the unfixed seam, because earlier tests in this file leave the observer module cached and
+    // a cached import resolves in call order. Only a cold module registry reproduces it. Driven
+    // red before the fix: 3/3 child runs reported a false surprise (82->58, 26->10, 42->22);
+    // after the fix, 3/3 report none.
+    const child = new URL("../helpers/quota-reset-burst-child.ts", import.meta.url).pathname;
+    const proc = Bun.spawn(["bun", child], {
+      // A private OPENCODEX_HOME: the baseline is persisted, so a shared home would let one
+      // run seed the next and turn this into a test of leftover state.
+      env: { ...process.env, OPENCODEX_HOME: mkdtempSync(join(tmpdir(), "ocx-burst-")) },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const out = await new Response(proc.stdout).text();
+    await proc.exited;
+
+    expect(proc.exitCode).toBe(0);
+    expect(JSON.parse(out.trim())).toEqual([]);
+  });
+
+  test("a real rollover at the end of a burst still fires exactly once", async () => {
+    // The ordering fix must not buy its silence by dropping observations. Usage climbs, then
+    // the weekly window genuinely rolls over on the final write.
+    const expired = Date.now() - 60_000;
+    for (let percent = 60; percent <= 96; percent += 4) {
+      setAccountQuotaFromParsed(ACCOUNT, { weeklyPercent: percent, weeklyResetAt: expired });
+    }
+    await flushQuotaObservationsForTests();
+    await settle();
+    captured = [];
+
+    setAccountQuotaFromParsed(ACCOUNT, {
+      weeklyPercent: 1,
+      weeklyResetAt: Date.now() + 7 * 24 * HOUR,
+    });
+    await flushQuotaObservationsForTests();
+    await settle();
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.kind).toBe("scheduled");
+    expect(captured[0]?.window).toBe("weekly");
+  });
+});
diff --git a/tests/usage/quota-reset-seen-store.test.ts b/tests/usage/quota-reset-seen-store.test.ts
new file mode 100644
index 0000000000..7b5620da76
--- /dev/null
+++ b/tests/usage/quota-reset-seen-store.test.ts
@@ -0,0 +1,250 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../../src/config";
+import type { QuotaResetEvent } from "../../src/quota/reset-detector";
+import {
+  claimCountForTests,
+  claimQuotaReset,
+  forgetLastObservedWindows,
+  hasSeenQuotaReset,
+  listRecentQuotaResetEvents,
+  recordQuotaResetEvent,
+  resetQuotaResetStoreForTests,
+  swapLastObservedWindows,
+} from "../../src/quota/reset-seen-store";
+
+const DAY = 24 * 60 * 60_000;
+/**
+ * Real wall clock, not a fixed constant.
+ *
+ * prune() reads Date.now() for age comparisons on purpose (a backdated claim must not change
+ * unrelated keys' retention), so a hardcoded epoch would look decades stale and be pruned the
+ * moment it was written.
+ */
+const NOW = Date.now();
+
+function event(key: string): QuotaResetEvent {
+  return {
+    kind: "surprise",
+    scope: "codex",
+    accountTag: "tag00000",
+    window: "weekly",
+    detectedAt: NOW,
+    key,
+  };
+}
+
+beforeEach(() => {
+  resetQuotaResetStoreForTests();
+});
+
+describe("quota reset claim store", () => {
+  test("claimQuotaReset returns false when the claim is not durable", () => {
+    // The caller reads true as "durably claimed, safe to dispatch". Two paths broke that.
+
+    // 1. prune() evicts the just-added claim: its deadline is already past and it is older
+    //    than CLAIM_MAX_AGE_MS, so the claim is gone before the function returns.
+    const ancient = NOW - 100 * DAY;
+    expect(claimQuotaReset("pruned-immediately", ancient, ancient + 1)).toBe(false);
+    expect(hasSeenQuotaReset("pruned-immediately")).toBe(false);
+
+    // 2. The write fails. persistNow() swallowed every error, so a read-only or full disk
+    //    still reported a durable claim and the next start re-notified.
+    // atomicWriteFile writes a sibling temp file in the config dir, so replacing that
+    // directory with a regular file makes the real write fail without touching the module.
+    const configDir = getConfigDir();
+    rmSync(configDir, { recursive: true, force: true });
+    writeFileSync(configDir, "not a directory");
+    try {
+      expect(claimQuotaReset("write-fails", NOW)).toBe(false);
+    } finally {
+      rmSync(configDir, { force: true });
+      mkdirSync(configDir, { recursive: true });
+    }
+  });
+
+  test("a key can be claimed exactly once", () => {
+    expect(claimQuotaReset("k1", NOW)).toBe(true);
+    expect(claimQuotaReset("k1", NOW)).toBe(false);
+    expect(hasSeenQuotaReset("k1")).toBe(true);
+    expect(hasSeenQuotaReset("k2")).toBe(false);
+  });
+
+  test("concurrent observers of one key produce exactly one winner", () => {
+    // No await between the two calls: this is the poller-versus-live-response race.
+    const results = [claimQuotaReset("race", NOW), claimQuotaReset("race", NOW)];
+    expect(results.filter(Boolean)).toHaveLength(1);
+  });
+
+  test("a claim is on disk the moment it is made, with no flush", () => {
+    // No test-only flush: the claim path writes synchronously, because an unref'd 250 ms
+    // debounce loses the claim when the process exits right after detecting — the exact case a
+    // restart guarantee has to cover.
+    expect(claimQuotaReset("persisted", NOW, NOW + DAY)).toBe(true);
+    const raw = readFileSync(join(getConfigDir(), "quota-reset-state.json"), "utf8");
+    expect(JSON.parse(raw).claims.persisted).toBeDefined();
+
+    resetQuotaResetStoreForTests();
+    expect(hasSeenQuotaReset("persisted")).toBe(true);
+    expect(claimQuotaReset("persisted", NOW + 60_000)).toBe(false);
+  });
+
+  test("a claim survives a real second process", async () => {
+    const script = join(getConfigDir(), "claim-probe.ts");
+    const storeUrl = new URL("../../src/quota/reset-seen-store.ts", import.meta.url).pathname;
+    writeFileSync(script, [
+      `const store = await import(${JSON.stringify(storeUrl)});`,
+      `console.log(String(store.claimQuotaReset("cross-process", Date.now(), Date.now() + 86400000)));`,
+    ].join("\n"));
+
+    const run = async (): Promise<string> => {
+      const proc = Bun.spawn(["bun", script], {
+        env: { ...process.env, OPENCODEX_HOME: getConfigDir() },
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const out = await new Response(proc.stdout).text();
+      await proc.exited;
+      return out.trim();
+    };
+
+    expect(await run()).toBe("true");
+    // A second OS process must see the first one's claim. A debounced write failed this
+    // silently: the timer is unref'd, so the first process exited before persisting.
+    expect(await run()).toBe("false");
+  });
+
+  test("the hard ceiling bounds the map even when every claim is live", () => {
+    const future = NOW + 365 * DAY;
+    for (let index = 0; index < 2_000; index += 1) {
+      claimQuotaReset(`live-${index}`, NOW, future + index);
+    }
+    // 512 is the soft budget, honoured by evicting settled claims. With none settled, the hard
+    // ceiling at 1024 is what stops unbounded growth of the map and the JSON beside it.
+    expect(claimCountForTests()).toBeLessThanOrEqual(1_024);
+  });
+
+  test("a corrupt state file hydrates to empty without throwing", () => {
+    writeFileSync(join(getConfigDir(), "quota-reset-state.json"), "{not json");
+    resetQuotaResetStoreForTests();
+    expect(() => hasSeenQuotaReset("anything")).not.toThrow();
+    expect(hasSeenQuotaReset("anything")).toBe(false);
+  });
+
+  test("an old settled claim is pruned", () => {
+    claimQuotaReset("stale", NOW - 100 * DAY, NOW - 99 * DAY);
+    claimQuotaReset("fresh", NOW);
+    expect(hasSeenQuotaReset("stale")).toBe(false);
+    expect(hasSeenQuotaReset("fresh")).toBe(true);
+  });
+
+  test("an old claim whose window is still open is KEPT", () => {
+    // A monthly key is legitimately older than the age floor while remaining current;
+    // pruning it would let the same reset notify twice.
+    claimQuotaReset("live-monthly", NOW - 100 * DAY, NOW + DAY);
+    claimQuotaReset("fresh", NOW);
+    expect(hasSeenQuotaReset("live-monthly")).toBe(true);
+  });
+
+  test("the event ring is bounded and newest-first", () => {
+    for (let index = 0; index < 120; index += 1) recordQuotaResetEvent(event(`k${index}`));
+    const recent = listRecentQuotaResetEvents();
+    expect(recent).toHaveLength(100);
+    expect(recent[0]?.key).toBe("k119");
+    expect(listRecentQuotaResetEvents(5)).toHaveLength(5);
+  });
+});
+
+describe("the observed-window map evicts the least recently observed row", () => {
+  test("a continuously observed scope survives 64 newcomers", () => {
+    // The bound is 64 rows. Re-setting an existing key does NOT move it in a Map, so before
+    // the delete-then-set fix the EARLIEST-INSERTED row was evicted — which on a real install
+    // is the long-lived codex account observed on every response, while 63 transient rows
+    // survived. The cost is not a duplicate notification (claims are separate) but a MISSED
+    // one: a re-baselined row has no previous value to diff against.
+    const hot = { window: "weekly", percent: 50, resetAt: NOW + DAY } as const;
+    swapLastObservedWindows("codex", "hottag00", [hot]);
+
+    for (let index = 0; index < 64; index += 1) {
+      // Keep re-observing the hot row, exactly as a busy install would.
+      swapLastObservedWindows("codex", "hottag00", [hot]);
+      swapLastObservedWindows(`provider-${index}`, "tag00000", [hot]);
+    }
+
+    // Still present means the next transition on it can still be detected.
+    expect(swapLastObservedWindows("codex", "hottag00", [hot])).toBeDefined();
+  });
+
+  test("an abandoned row is the one that goes", () => {
+    const windows = [{ window: "weekly", percent: 10, resetAt: NOW + DAY }];
+    swapLastObservedWindows("abandoned", "tag00000", windows);
+    for (let index = 0; index < 64; index += 1) {
+      swapLastObservedWindows(`live-${index}`, "tag00000", windows);
+    }
+    // Never observed again, so it is genuinely the least recently used: it re-baselines.
+    expect(swapLastObservedWindows("abandoned", "tag00000", windows)).toBeUndefined();
+  });
+});
+
+describe("a cleared quota row forgets its baseline", () => {
+  test("forgetting one tag leaves the others intact", () => {
+    const windows = [{ window: "weekly", percent: 77, resetAt: NOW + DAY }];
+    swapLastObservedWindows("codex", "tagaaaaa", windows);
+    swapLastObservedWindows("codex", "tagbbbbb", windows);
+
+    forgetLastObservedWindows("codex", "tagaaaaa");
+
+    expect(swapLastObservedWindows("codex", "tagaaaaa", windows)).toBeUndefined();
+    expect(swapLastObservedWindows("codex", "tagbbbbb", windows)).toBeDefined();
+  });
+
+  test("forgetting a whole scope leaves other scopes intact", () => {
+    const windows = [{ window: "weekly", percent: 77, resetAt: NOW + DAY }];
+    swapLastObservedWindows("codex", "tagaaaaa", windows);
+    swapLastObservedWindows("codex", "tagbbbbb", windows);
+    swapLastObservedWindows("anthropic", "tagaaaaa", windows);
+
+    forgetLastObservedWindows("codex");
+
+    expect(swapLastObservedWindows("codex", "tagaaaaa", windows)).toBeUndefined();
+    expect(swapLastObservedWindows("codex", "tagbbbbb", windows)).toBeUndefined();
+    expect(swapLastObservedWindows("anthropic", "tagaaaaa", windows)).toBeDefined();
+  });
+
+  test("forgetting a baseline does NOT release the claim ledger", () => {
+    // A cleared row must not re-notify a reset it already reported, and claims are the only
+    // thing preventing that.
+    expect(claimQuotaReset("codex|tagaaaaa|weekly|1", NOW, NOW + DAY)).toBe(true);
+    forgetLastObservedWindows("codex", "tagaaaaa");
+    expect(claimQuotaReset("codex|tagaaaaa|weekly|1", NOW, NOW + DAY)).toBe(false);
+  });
+});
+
+describe("the debounced write cannot be starved", () => {
+  test("sustained sub-debounce activity still reaches disk", async () => {
+    // Measured on the unfixed version: 75 observations at 40 ms produced ZERO writes, because a
+    // re-arming debounce pushes its own deadline out on every call. A busy install that is then
+    // SIGKILLed loses its whole baseline, which defeats the across-a-restart guarantee.
+    //
+    // Asserts on the CONTENT reaching disk, not on the file existing: the file is already there
+    // from earlier hydration, so an existence check passes with or without the fix and proves
+    // nothing. Verified by removing the cap and watching this fail.
+    resetQuotaResetStoreForTests();
+    const path = join(getConfigDir(), "quota-reset-state.json");
+    writeFileSync(path, JSON.stringify({ version: 1, claims: {}, events: [] }));
+
+    const windows = [{ window: "weekly", percent: 42, resetAt: NOW + DAY }];
+    // ~1.5 s of traffic at 40 ms: far faster than the 250 ms debounce, so every call defers.
+    for (let index = 0; index < 38; index += 1) {
+      swapLastObservedWindows("codex", "starvetag", windows);
+      await new Promise(resolve => setTimeout(resolve, 40));
+    }
+
+    // The staleness cap must have forced a write while the traffic was still arriving.
+    const onDisk = JSON.parse(readFileSync(path, "utf8")) as {
+      observed?: Record<string, unknown>;
+    };
+    expect(Object.keys(onDisk.observed ?? {}).some(key => key.includes("starvetag"))).toBe(true);
+  });
+});