@bitkyc08/opencodex 2.42.0 → 2.43.0

package/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;
+}

package/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" };
+  });
+}

package/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;
+}