@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/providers/registry.ts

@@ -127,6 +127,7 @@ export interface ProviderRegistryEntry {
   adapter: string;
   baseUrl: string;
   apiKeyTransport?: OcxProviderConfig["apiKeyTransport"];
+  alias?: string;
   authKind: ProviderAuthKind;
   codexAccountMode?: CodexAccountMode;
   /** OAuth preset may explicitly honor a persisted API-key billing mode. */
@@ -349,6 +350,38 @@ export type ProviderConfigSeed = Pick<
 // always on, per the official models overview and pricing page (platform.claude.com).
 const ANTHROPIC_MODELS = ["claude-fable-5-1", "claude-fable-5", "claude-sonnet-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"];
 const ANTHROPIC_MODEL_CONTEXT_WINDOWS: Record<string, number> = { "claude-fable-5-1": 1_000_000, "claude-sonnet-5": 1_000_000, "claude-fable-5": 1_000_000, "claude-opus-5": 1_000_000, "claude-opus-4-8": 1_000_000, "claude-opus-4-7": 1_000_000, "claude-opus-4-6": 1_000_000, "claude-sonnet-4-6": 1_000_000, "claude-haiku-4-5": 200_000 };
+// Every current Claude family accepts at least 64k output tokens (Haiku 4.5 / Sonnet 4.x
+// through Opus 5 and Fable 5). Anthropic caps max_tokens per model server-side, so a
+// larger request never over-allocates; it only stops the 8192 truncation.
+const ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS = 64_000;
+/**
+ * The effort rungs opencodex exposes for native Anthropic models. Without this the
+ * providers advertised no ladder at all, so every client that keys its effort control off
+ * `reasoningEfforts` — Aside and the rest of the Pi-shaped exports — wrote these models
+ * with no control, while the SAME Claude models routed through `cursor` or
+ * `google-antigravity` had one.
+ *
+ * This is an opencodex ladder, not a claim that each model takes `output_config.effort`.
+ * The adapter serves two wire shapes (src/adapters/anthropic.ts): adaptive families
+ * (fable, sonnet >= 5, opus >= 4.7) send the effort directly, while opus 4.6, sonnet 4.6
+ * and haiku 4.5 take the legacy path where `reasoningBudget` TRANSLATES each rung into
+ * `thinking.budget_tokens`. Anthropic documents `low|medium|high|max` for the 4.6 models
+ * and no effort parameter at all for haiku 4.5; the budget translation is what makes five
+ * rungs meaningful there, and it clamps below `max_tokens` so none of them 400.
+ *
+ * Deliberately excluded, each because advertising it would offer a control that does not
+ * do what it says:
+ * - `minimal`: `adaptiveEffort` rewrites it to `low` (the adaptive wire 400s on it), so
+ *   it is not a distinct setting.
+ * - `none`: only sonnet >= 5 accepts an explicit thinking disable
+ *   (`EXPLICIT_THINKING_DISABLE_FAMILY_MINIMUMS`); Fable rejects one outright.
+ * - `ultra`: not an Anthropic concept, and it is degraded to `max` at the request
+ *   boundary anyway (src/responses/parser.ts).
+ */
+const ANTHROPIC_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+const ANTHROPIC_MODEL_REASONING_EFFORTS: Record<string, string[]> = Object.fromEntries(
+  ANTHROPIC_MODELS.map(id => [id, [...ANTHROPIC_REASONING_EFFORTS]]),
+);
 
 // 260814 GLM-5.3 is registered pre-emptively alongside 5.2 everywhere 5.2 appears. Z.AI's
 // devpack "How to Switch Models" page (docs.z.ai/devpack/latest-model) lists glm-5.3 and
@@ -600,7 +633,7 @@ const OPENCODE_FREE_DEEPSEEK_MODELS = ["deepseek-v4-flash-free"];
  * `mimo-v2.5-free` and `longcat-2.0-free` ACCEPT images and are deliberately
  * absent. Adding them would silently replace a working image with a caption,
  * which is worse than the loud 400 this list exists to prevent — see the negative
- * assertion in tests/provider-registry-parity.test.ts.
+ * assertion in tests/providers/provider-registry-parity.test.ts.
  *
  * Zen's roster is discovered live while this list is static, so it is a dated
  * exception list, not a capability model. Re-probe before extending it.
@@ -656,7 +689,7 @@ const DEEPSEEK_FLASH_REASONING_MAP: Record<string, string> = {
 /**
  * Flash-versus-Pro classification for DeepSeek V4 model ids, including prefixed
  * (`deepseek/deepseek-v4-pro`) and suffixed (`deepseek-v4-flash-free`) forms.
- * `tests/provider-registry-parity.test.ts` enumerates every id the registry
+ * `tests/providers/provider-registry-parity.test.ts` enumerates every id the registry
  * actually passes here, so a future id this substring test would misread cannot
  * land silently.
  */
@@ -1222,20 +1255,20 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // than the seeded ones do.
     supportsVerbosity: false,
     defaultModel: "grok-4.5",
-    // Keep 4.6/4.5 Responses callers on the compatibility Chat wire until xAI can replay
-    // opaque reasoning continuation and compaction state across later turns. Multi-agent has
-    // no Chat wire, so Responses callers use its only working wire under both auth modes.
+    // Grok 4.6/4.5 subscription Responses callers use the native wire with the existing
+    // namespace/web-search/replay normalization. Chat remains an explicit modelAdapters
+    // opt-in. Multi-agent has no Chat wire and uses Responses under both auth modes.
     // Caller-owned service tiers stay off the unclassified OAuth subscription route; key-auth
     // Fast remains proxy-owned and is still selected through keyAuthServiceTier above.
     modelWireDefaults: {
       "grok-4.6": {
-        wire: "openai-chat",
+        wire: "openai-responses",
         inbound: ["responses"],
         authModes: ["oauth"],
         forwardCallerServiceTier: false,
       },
       "grok-4.5": {
-        wire: "openai-chat",
+        wire: "openai-responses",
         inbound: ["responses"],
         authModes: ["oauth"],
         forwardCallerServiceTier: false,
@@ -1340,6 +1373,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     note: "Log in with your Claude account",
     models: [...ANTHROPIC_MODELS],
     modelContextWindows: { ...ANTHROPIC_MODEL_CONTEXT_WINDOWS },
+    modelReasoningEfforts: { ...ANTHROPIC_MODEL_REASONING_EFFORTS },
+    // Codex omits max_output_tokens; without a provider budget the Anthropic adapter
+    // falls back to 8192, which truncates long answers with stop_reason=max_tokens.
+    defaultMaxOutputTokens: ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
     defaultModel: "claude-sonnet-5",
   },
   {
@@ -1356,6 +1393,8 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     models: [...ANTHROPIC_MODELS],
     liveModels: true,
     modelContextWindows: { ...ANTHROPIC_MODEL_CONTEXT_WINDOWS },
+    modelReasoningEfforts: { ...ANTHROPIC_MODEL_REASONING_EFFORTS },
+    defaultMaxOutputTokens: ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
     defaultModel: "claude-sonnet-5",
   },
   {
@@ -1458,12 +1497,13 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     featured: true,
     dashboardUrl: "https://platform.openai.com/api-keys",
     defaultModel: "gpt-5.5",
-    models: ["gpt-5.5", ...OPENAI_GPT56_MODELS, ...OPENAI_GPT56_PRO_MODELS, ...OPENAI_DAYBREAK_MODELS],
+    models: ["gpt-5.5", ...OPENAI_GPT56_MODELS, ...OPENAI_GPT56_PRO_MODELS, ...OPENAI_DAYBREAK_MODELS, "gpt-6-astra"],
     liveModels: true,
-    modelContextWindows: { ...OPENAI_API_GPT56_CONTEXT_WINDOWS, ...OPENAI_DAYBREAK_CONTEXT_WINDOWS },
-    modelMaxInputTokens: { ...OPENAI_API_GPT56_MAX_INPUT_TOKENS, ...OPENAI_DAYBREAK_MAX_INPUT_TOKENS },
+    modelContextWindows: { ...OPENAI_API_GPT56_CONTEXT_WINDOWS, ...OPENAI_DAYBREAK_CONTEXT_WINDOWS, "gpt-6-astra": 1_050_000 },
+    modelMaxInputTokens: { ...OPENAI_API_GPT56_MAX_INPUT_TOKENS, ...OPENAI_DAYBREAK_MAX_INPUT_TOKENS, "gpt-6-astra": 922_000 },
+    modelMaxOutputTokens: { "gpt-6-astra": 128_000 },
     modelInputModalities: Object.fromEntries(
-      ["gpt-5.5", ...OPENAI_GPT56_MODELS, ...OPENAI_GPT56_PRO_MODELS, ...OPENAI_DAYBREAK_MODELS]
+      ["gpt-5.5", ...OPENAI_GPT56_MODELS, ...OPENAI_GPT56_PRO_MODELS, ...OPENAI_DAYBREAK_MODELS, "gpt-6-astra"]
         .map(id => [id, ["text", "image"]]),
     ),
     modelReasoningEfforts: {
@@ -1471,6 +1511,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
         [...OPENAI_GPT56_MODELS, ...OPENAI_GPT56_PRO_MODELS].map(id => [id, OPENAI_API_GPT56_REASONING_EFFORTS]),
       ),
       ...OPENAI_DAYBREAK_REASONING_EFFORTS,
+      "gpt-6-astra": ["low", "medium", "high", "xhigh", "max"],
     },
     virtualModels: OPENAI_API_GPT56_VIRTUAL_MODELS,
   },
@@ -1503,7 +1544,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_CONTEXT_WINDOW])),
     // text+image only. Meta also documents video, audio (degraded on 1.3), and PDF, but
     // the catalog modality enum is text/image and over-advertising poisons the exported
-    // client config (see tests/catalog-input-modality-enum.test.ts).
+    // client config (see tests/codex-integration/catalog-input-modality-enum.test.ts).
     modelInputModalities: Object.fromEntries(META_MUSE_MODELS.map(id => [id, ["text", "image"] as ["text", "image"]])),
     modelReasoningEfforts: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_REASONING_EFFORTS])),
     modelReasoningEffortMap: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_REASONING_EFFORT_MAP])),
@@ -1519,7 +1560,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   - 목적과 의도: Let an operator who already signed the Muse Code CLI in reach Muse Spark with that credential, instead of provisioning a second key.
   - 기존 구현 및 제약 조건: The CLI stores a pointer at ~/.config/muse/auth.json and the secret in the macOS Keychain (ai.meta.dev.credentials/meta). Measured: the OAuth access_token 401s on /v1/models while the sibling api_key returns 200, so the usable artifact is a static key, not a refreshable token.
   - 검토한 주요 대안: spawn `muse login` and poll; reimplement Meta's device grant; treat it as a second key preset; ship nothing.
-  - 선택한 방식: an import-only, macOS-only OAuth provider that reads the existing credential, validates it once, and never spawns or reimplements anything.
+  - 선택한 방식: an OAuth provider that imports the existing credential on macOS and accepts a pasted key elsewhere, validates either once, and never spawns or reimplements anything.
   - 다른 대안 대신 이 방식을 선택한 이유: `muse login` has no non-interactive mode, so a spawned child could outlive cancellation, and polling for the pointer file is satisfied instantly by the one already on disk — reimporting the OLD account on a force-login. Reimplementing the grant would mean guessing a client id the vendor does not publish.
   - 장점, 단점 및 영향: no new credential to provision, and the id is distinct from meta-model so neither pool contaminates the other. Meta scopes this credential to its own CLI, so the provider carries a HIGH_RISK ToS warning, a CLI-side warning before any read, and a note that says plainly what is unsupported.
   */
@@ -1540,7 +1581,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelInputModalities: Object.fromEntries(META_MUSE_MODELS.map(id => [id, ["text", "image"] as ["text", "image"]])),
     modelReasoningEfforts: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_REASONING_EFFORTS])),
     modelReasoningEffortMap: Object.fromEntries(META_MUSE_MODELS.map(id => [id, META_MUSE_REASONING_EFFORT_MAP])),
-    note: "Reuses the API key the Muse Code CLI stores after `muse login` (macOS only; requires the CLI installed and signed in). Meta scopes that credential to the Muse Code CLI, so this is an UNSUPPORTED use: Meta does not authorize subscription coverage outside its own CLI, how these calls settle is not observable from the API, and you should treat every call as billable against your account. The imported key is copied into OpenCodex's auth store. OpenCodex reads Meta's subscription windows from streaming responses and shows the last observed value with its age; there is no endpoint to query them on demand, so refreshing one requires another streaming turn, and translated (non-passthrough) turns report none. Rate limits apply per team, not per key. For a supported path use the meta-model provider with your own key (export it as META_MODEL_API_KEY).",
+    note: "Reuses the API key the Muse Code CLI stores after `muse login` (macOS only; requires the CLI installed and signed in). Meta ships no native Windows CLI and the Linux credential storage has not been measured, so on those platforms OpenCodex asks you to paste the Muse Code API key from https://dev.meta.ai instead of importing one; a pasted key faces the same format check and live validation as an imported one. Meta scopes that credential to the Muse Code CLI, so this is an UNSUPPORTED use: Meta does not authorize subscription coverage outside its own CLI, how these calls settle is not observable from the API, and you should treat every call as billable against your account. The key, imported or pasted, is copied into OpenCodex's auth store. OpenCodex reads Meta's subscription windows from streaming responses and shows the last observed value with its age; there is no endpoint to query them on demand, so refreshing one requires another streaming turn, and translated (non-passthrough) turns report none. Rate limits apply per team, not per key. For a supported path use the meta-model provider with your own key (export it as META_MODEL_API_KEY).",
   },
   {
     id: "umans",
@@ -1576,7 +1617,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // finish_reason or [DONE] (#2260). The adapter still rejects incomplete argument JSON.
     openaiChatEofTolerance: true,
     /* [Decision Log]
-    - 목적과 의도: Route the exact models OpenCode Go documents on the Responses endpoint — GPT 5.6 Luna, and Muse Spark 1.2 Contributor (#2617).
+    - 목적과 의도: Route the exact models OpenCode Go documents on the Responses endpoint — GPT 5.6 Luna, Grok 4.6, and Muse Spark Contributor (#2617).
     - 기존 구현 및 제약 조건: The provider is mixed-wire but its provider-wide `openai-chat` adapter sent Luna to `/chat/completions`; explicit user `modelAdapters` entries must remain authoritative.
     - 검토한 주요 대안: Change the whole provider to Responses; infer the wire from model-family names; add one registry-only exact-model default.
     - 선택한 방식: Declare only the named models as `openai-responses` through the existing registry default mechanism; the map stays an exact-model allowlist rather than a family or provider-wide rule.
@@ -1585,6 +1626,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     */
     modelWireDefaults: {
       "gpt-5.6-luna": "openai-responses",
+      "grok-4.6": "openai-responses",
       "muse-spark-1.3-contributor": "openai-responses",
       "muse-spark-1.2-contributor": "openai-responses",
     },
@@ -1614,6 +1656,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     },
     modelReasoningEfforts: {
       "gpt-5.6-luna": OPENAI_API_GPT56_REASONING_EFFORTS,
+      "grok-4.6": ["low", "medium", "high", "xhigh"],
       "glm-5.3": ZAI_GLM_53_REASONING_EFFORTS,
       "glm-5.3-flash": ZAI_GLM_53_REASONING_EFFORTS,
       "glm-5.2": ZAI_GLM_52_REASONING_EFFORTS,
@@ -1625,7 +1668,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       ...Object.fromEntries(OPENCODE_GO_THINKING_BUDGET_MODELS.map(id => [id, THINKING_BUDGET_EFFORTS])),
       ...Object.fromEntries(DEEPSEEK_THINKING_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
     },
-    modelDefaultReasoningEfforts: { "kimi-k3": "max" },
+    modelDefaultReasoningEfforts: { "grok-4.6": "high", "kimi-k3": "max" },
     // glm-5.2 uses identity labels now that `max` is a native Codex level (no alias map);
     // the thinking-toggle map is a REAL wire alias (effort -> enabled/disabled) and stays.
     modelReasoningEffortMap: {
@@ -1858,7 +1901,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // 2026-07-10: defaultModel is frozen pending Vertex-specific Tier-2 evidence; Gemini API
   // evidence from ai.google.dev does not establish Vertex publisher availability.
   { id: "google-vertex", label: "Google Vertex AI", adapter: "google", baseUrl: "https://aiplatform.googleapis.com", authKind: "key", dashboardUrl: "https://console.cloud.google.com/vertex-ai", defaultModel: "gemini-3-pro", googleMode: "vertex", jawcodeBundle: "google", extraMetadataAliases: ["gemini-vertex"] },
-  { id: "google-antigravity", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", allowBaseUrlOverride: true, dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.8-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
+  { id: "google-antigravity", alias: "agy", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", allowBaseUrlOverride: true, dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.8-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
   { id: "azure-openai", label: "Azure OpenAI", adapter: "azure-openai", baseUrl: "https://{resource}.openai.azure.com/openai", authKind: "key", featured: true, dashboardUrl: "https://portal.azure.com" },
   { id: "ollama", label: "Ollama (local)", adapter: "openai-chat", baseUrl: "http://localhost:11434/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
   { id: "vllm", label: "vLLM (local)", adapter: "openai-chat", baseUrl: "http://localhost:8000/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },

package/src/providers/xai-responses-opt-in.ts

@@ -1,15 +1,41 @@
-import type { OcxProviderConfig } from "../types";
+import { MODEL_ADAPTER_OVERRIDE_ALLOWED, type OcxConfig, type OcxProviderConfig } from "../types";
+import { providerModelWireDefault } from "./registry";
 
 export const XAI_RESPONSES_OPT_IN_MODELS = ["grok-4.6", "grok-4.5"] as const;
+export const XAI_RESPONSES_DEFAULT_VERSION = 1;
 
 export type XaiResponsesOptInState = boolean | "mixed";
 
-/** Derived dashboard/API state for the two modelAdapters entries owned by the xAI opt-in. */
+/** Effective Responses-inbound wire; the legacy API field name remains compatible. */
 export function xaiResponsesOptInState(provider: OcxProviderConfig): XaiResponsesOptInState {
-  const enabled = XAI_RESPONSES_OPT_IN_MODELS.map(
-    model => provider.modelAdapters?.[model] === "openai-responses",
-  );
+  const enabled = XAI_RESPONSES_OPT_IN_MODELS.map(model => {
+    const configured = provider.modelAdapters?.[model];
+    const wire = configured && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(configured)
+      ? configured
+      : providerModelWireDefault("xai", provider, model, MODEL_ADAPTER_OVERRIDE_ALLOWED, "responses")
+        ?? provider.adapter;
+    return wire === "openai-responses";
+  });
   if (enabled.every(Boolean)) return true;
   if (enabled.some(Boolean)) return "mixed";
   return false;
 }
+
+/** Upgrade old Chat choices once; a later explicit Chat opt-in must survive restart. */
+export function migrateXaiResponsesDefault(config: OcxConfig): boolean {
+  const provider = config.providers.xai;
+  if (!provider || (provider.xaiResponsesDefaultVersion ?? 0) >= XAI_RESPONSES_DEFAULT_VERSION) return false;
+  if (!XAI_RESPONSES_OPT_IN_MODELS.every(model =>
+    providerModelWireDefault("xai", provider, model, MODEL_ADAPTER_OVERRIDE_ALLOWED, "responses") === "openai-responses")) {
+    return false;
+  }
+  const modelAdapters = { ...provider.modelAdapters };
+  for (const model of XAI_RESPONSES_OPT_IN_MODELS) {
+    if (modelAdapters[model] === "openai-chat") delete modelAdapters[model];
+  }
+  const next = { ...provider, xaiResponsesDefaultVersion: XAI_RESPONSES_DEFAULT_VERSION };
+  if (Object.keys(modelAdapters).length) next.modelAdapters = modelAdapters;
+  else delete next.modelAdapters;
+  config.providers = { ...config.providers, xai: next };
+  return true;
+}

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

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