@bitkyc08/opencodex 2.23.0-preview.20260816 → 2.24.0

package/src/codex/catalog-refresh-status.ts

@@ -1,4 +1,4 @@
-import type { CatalogDisposition, CatalogNotice } from "./convergence-types";
+import type { CatalogDisposition, CatalogFailureCause, CatalogNotice } from "./convergence-types";
 
 const INVALID_CATALOG_DISPOSITION_FIELD = Symbol("invalid-catalog-disposition-field");
 
@@ -69,11 +69,15 @@ export function normalizeCatalogDisposition(value: unknown): CatalogDisposition
       const phase = ownDataProperty(value, "phase");
       const retryable = ownDataProperty(value, "retryable");
       const partialWrite = ownDataProperty(value, "partialWrite");
-      if ((reason !== "provider-auth" && reason !== "provider-network" && reason !== "disk")
+      if ((reason !== "provider-auth" && reason !== "provider-network" && reason !== "disk"
+        && reason !== "request-invalid" && reason !== "admission" && reason !== "internal")
         || (phase !== "gather" && phase !== "commit")
         || typeof retryable !== "boolean"
         || typeof partialWrite !== "boolean") return null;
-      return { status, reason, phase, retryable, partialWrite };
+      // The cause is rebuilt from closed vocabularies, never copied through: this is the
+      // boundary that keeps a message, path or account id from riding out on a failure.
+      const cause = normalizeCatalogFailureCause(ownDataProperty(value, "cause"));
+      return { status, reason, phase, retryable, partialWrite, ...(cause ? { cause } : {}) };
     }
     return null;
   } catch {
@@ -81,6 +85,20 @@ export function normalizeCatalogDisposition(value: unknown): CatalogDisposition
   }
 }
 
+const FAILURE_CAUSE_KINDS: ReadonlySet<string> = new Set(["invalid-request", "lock-busy", "io", "unknown"]);
+const FAILURE_CAUSE_CODES: ReadonlySet<string> = new Set([
+  "ENOSPC", "EACCES", "EPERM", "EROFS", "ENOENT", "SQLITE_BUSY",
+]);
+
+function normalizeCatalogFailureCause(value: unknown): CatalogFailureCause | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const kind = ownDataProperty(value, "kind");
+  if (typeof kind !== "string" || !FAILURE_CAUSE_KINDS.has(kind)) return undefined;
+  const code = ownDataProperty(value, "code");
+  const safeCode = typeof code === "string" && FAILURE_CAUSE_CODES.has(code) ? code : undefined;
+  return { kind, ...(safeCode ? { code: safeCode } : {}) } as CatalogFailureCause;
+}
+
 /** Whether a persisted mutation still needs a successful catalog commit. */
 export function catalogRefreshIsPending(disposition: CatalogDisposition): boolean {
   return disposition.status !== "committed";

package/src/codex/catalog.ts

@@ -2,7 +2,7 @@
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
 export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, readCatalog, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
-export { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
+export { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_GPT56_MAX_INPUT_TOKENS, NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeContextLimits, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, type NativeContextLimits, type NativeContextLimitsInput } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } from "./catalog/provider-fetch";

package/src/codex/convergence-types.ts

@@ -161,8 +161,29 @@ export type CatalogDisposition =
   | { status: "skipped";
       reason: "not-requested" | "catalog-unavailable" | "busy" | "stale" | "refused";
       retryable: boolean }
-  | { status: "failed"; reason: "provider-auth" | "provider-network" | "disk";
-      phase: "gather" | "commit"; retryable: boolean; partialWrite: boolean };
+  | { status: "failed";
+      /**
+       * `disk` used to absorb every unclassified failure, so a malformed request and a
+       * genuine ENOSPC were indistinguishable and both reported non-retryable (#1784).
+       */
+      reason: "provider-auth" | "provider-network" | "disk" | "request-invalid" | "admission" | "internal";
+      phase: "gather" | "commit"; retryable: boolean; partialWrite: boolean;
+      /** Allowlisted cause summary. Closed vocabularies only -- never message text. */
+      cause?: CatalogFailureCause };
+
+/**
+ * Why a catalog operation failed, in terms safe to return from the management plane.
+ *
+ * Both fields are closed sets on purpose. An `Error.constructor.name` is dependency- or
+ * input-influenced (any thrown custom class names itself) and an `Error.message` routinely
+ * carries paths, home directories and account identifiers, none of which may cross this
+ * boundary.
+ */
+export type CatalogFailureCause = {
+  kind: "invalid-request" | "lock-busy" | "io" | "unknown";
+  /** Recognized errno/code token, when the underlying error carried one. */
+  code?: "ENOSPC" | "EACCES" | "EPERM" | "EROFS" | "ENOENT" | "SQLITE_BUSY";
+};
 
 /**
  * The ONLY way Codex-owned bytes are written. Startup, ensure, /api/sync, the

package/src/codex/desired-state.ts

@@ -18,7 +18,7 @@
  * depending on the temp root. Convergence takes the write lock; this module only
  * records intent through the config coordinator.
  *
- * Design record: devlog/_plan/260803_codex_desktop_toggle/030_desired_state.md.
+ * Design record: devlog/_fin/260803_codex_desktop_toggle/030_desired_state.md.
  */
 import { loadConfig, mutatePersistedConfig } from "../config";
 import type { OcxClientIntegrationsConfig, OcxConfig } from "../types";

package/src/codex/inject.ts

@@ -30,6 +30,8 @@ import {
 } from "./user-identity";
 import {
   markJournalInjectedState,
+  journaledInjectedOpenaiBaseUrl,
+  journaledInjectedCatalogPath,
   removeJournal,
   restoreJournalState,
   writeJournal,
@@ -52,6 +54,7 @@ import {
   providerTableStart,
   providerTableString,
   rootTomlString,
+  stripJournaledOpenaiBaseUrl,
   tomlStringPattern,
 } from "./injected-marker";
 import {
@@ -1138,12 +1141,18 @@ interface StripOpencodexConfigResult {
  */
 function stripOpencodexConfigResult(
   content: string,
+  journaledBaseUrl: string | null = null,
 ): StripOpencodexConfigResult {
   let out = content;
   const hadRootOcxProvider =
     readRootTomlString(out, "model_provider") === "opencodex";
-  const hadInjectedBaseUrl = hasInjectedOpenaiBaseUrl(out);
+  // #1798: marker adjacency is FORMATTING evidence, and a Codex app rewrite keeps values
+  // while dropping comments. Fall back to VALUE evidence -- the exact URL we recorded
+  // writing -- so an app-rewritten config is still recognized as ours.
+  const hadInjectedBaseUrl = hasInjectedOpenaiBaseUrl(out)
+    || (journaledBaseUrl !== null && rootTomlString(out, "openai_base_url") === journaledBaseUrl);
   out = stripInjectedOpenaiBaseUrl(out); // before removeOcxSection — it keys on the marker line too
+  out = stripJournaledOpenaiBaseUrl(out, journaledBaseUrl);
   if (out.includes("[model_providers.opencodex]")) {
     out = removeOcxSection(out);
   }
@@ -1195,8 +1204,12 @@ export function removeCodexConfig(
   // The unchanged fast path compares in LF space so an untouched file is never rewritten.
   const eol = dominantEol(rawContent);
   const content = applyEol(rawContent, "\n");
-  const had = hasOpencodexRouting(content);
-  const stripped = stripOpencodexConfigResult(content);
+  // Read the recorded injection once: the strip below consumes it, and so does the
+  // ownership verdict, which must agree with what was actually removed.
+  const journaledBaseUrl = journaledInjectedOpenaiBaseUrl();
+  const had = hasOpencodexRouting(content)
+    || (journaledBaseUrl !== null && rootTomlString(content, "openai_base_url") === journaledBaseUrl);
+  const stripped = stripOpencodexConfigResult(content, journaledBaseUrl);
   if (had || stripped.content !== content) {
     atomicWriteFile(CODEX_CONFIG_PATH, applyEol(stripped.content, eol));
   }
@@ -1371,13 +1384,23 @@ function restoreCodexConfigInline(): CodexRestoreConfigResult {
 }
 
 /** The catalog half, always inside its own K acquisition. */
-function restoreCodexCatalogArtifact(revalidateDesiredState: boolean): CodexRestoreCatalogResult {
+/**
+ * The catalog half, always inside its own K acquisition.
+ *
+ * `journaledCatalogPath` must be captured by the CALLER, before the config half runs: a
+ * successful journal restore deletes the journal, and a config restore can remove
+ * `model_catalog_json`. Reading it here would be too late in both cases (#1798).
+ */
+function restoreCodexCatalogArtifact(
+  revalidateDesiredState: boolean,
+  journaledCatalogPath: string | null,
+): CodexRestoreCatalogResult {
   const owningCodexHome = getCodexHome();
   try {
     const restored = withCatalogWriteSerialization(owningCodexHome, permit =>
       revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())
         ? null
-        : restoreCodexCatalogWithPermit(permit, owningCodexHome));
+        : restoreCodexCatalogWithPermit(permit, owningCodexHome, journaledCatalogPath));
     return restored.kind === "completed" && restored.value !== null
       ? { state: "ok", changed: restored.value.removed > 0, ...restored.value, message: "Codex catalog restored." }
       : restored.kind === "completed"
@@ -1435,6 +1458,10 @@ export async function restoreNativeCodexAsync(
     integrationRecord: () => readIntegrationRecord(),
   });
 
+  // Captured before the config half: a successful journal restore DELETES the journal, and
+  // restoring the config can drop `model_catalog_json`. Either one would hide the routed
+  // catalog we actually wrote (#1798).
+  const journaledCatalogPath = journaledInjectedCatalogPath();
   let config: CodexRestoreConfigResult;
   let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
 
@@ -1511,7 +1538,7 @@ export async function restoreNativeCodexAsync(
     config = restoreCodexConfigInline();
   }
 
-  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true);
+  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   const outcome = await runCodexHistoryJob({
     ...resolveCodexHistoryJobTarget(),
     ...(options.revalidateDesiredState ? { expectedDesiredEnabled: false } : {}),
@@ -1561,8 +1588,12 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
   if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
     return desiredEnabledRestoreSkip();
   }
+  // Captured before the config half: a successful journal restore DELETES the journal, and
+  // restoring the config can drop `model_catalog_json`. Either one would hide the routed
+  // catalog we actually wrote (#1798).
+  const journaledCatalogPath = journaledInjectedCatalogPath();
   const config = restoreCodexConfigInline();
-  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true);
+  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   // Design B (loopback) steady state: threads are already tagged openai, so prove the
   // no-op with a readonly probe instead of write-opening a DB the Codex app may hold
   // (Windows: WAL writer lock -> seconds of stalling + a false warning on every stop).

package/src/codex/injected-marker.ts

@@ -50,6 +50,34 @@ export function providerTableString(content: string, provider: string, key: stri
   return null;
 }
 
+/**
+ * Drop a root `openai_base_url` whose VALUE is the one a recorded injection wrote.
+ *
+ * #1798: the marker-adjacency rule below is formatting evidence, and the Codex app
+ * reserializes the file -- values kept, comments dropped. This rule is value evidence
+ * instead, so it still recognizes our URL after that rewrite. It is deliberately an
+ * EXACT value match against what we recorded writing: a user gateway we never wrote
+ * cannot match, so restore can never delete a URL that was not ours.
+ */
+export function stripJournaledOpenaiBaseUrl(content: string, injectedUrl: string | null): string {
+  if (!injectedUrl) return content;
+  const lines = content.split(String.fromCharCode(10));
+  const firstTable = lines.findIndex(l => /^\s*\[/.test(l));
+  const rootEnd = firstTable === -1 ? lines.length : firstTable;
+  const drop = new Set<number>();
+  for (let i = 0; i < rootEnd; i++) {
+    const line = lines[i]!;
+    if (!isRootOpenaiBaseUrlLine(line)) continue;
+    if (rootTomlString(line, "openai_base_url") !== injectedUrl) continue;
+    drop.add(i);
+    // Take an ownership marker directly above it too, so repeated cycles cannot
+    // accumulate orphaned comments.
+    if (i > 0 && lines[i - 1]!.includes(OCX_SECTION_MARKER)) drop.add(i - 1);
+  }
+  if (drop.size === 0) return content;
+  return lines.filter((_, i) => !drop.has(i)).join(String.fromCharCode(10));
+}
+
 export function hasInjectedOpenaiBaseUrl(content: string): boolean {
   const lines = content.split("\n");
   const firstTable = lines.findIndex(l => /^\s*\[/.test(l));

package/src/codex/journal.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
-import { hasInjectedCodexRouting } from "./injected-marker";
+import { hasInjectedCodexRouting, rootTomlString } from "./injected-marker";
 import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
 
 /**
@@ -22,6 +22,24 @@ interface Journal {
   originalProfile: string | null;
   injectedConfigHash?: string;
   injectedProfileHash?: string | null;
+  /**
+   * The exact root `openai_base_url` this injection wrote, when it wrote one.
+   *
+   * #1798: ownership used to be inferred from a marker COMMENT on the preceding line,
+   * which a reserializing Codex app deletes while keeping the value. Recording the value
+   * we actually wrote makes ownership provable from evidence rather than from formatting,
+   * and it is what lets restore tell OUR loopback URL apart from a gateway the user set.
+   */
+  injectedOpenaiBaseUrl?: string | null;
+  /**
+   * The catalog path this injection actually wrote to.
+   *
+   * #1798: restore re-resolves the catalog from the CURRENT config, so a Codex app rewrite
+   * that dropped `model_catalog_json` sends restore to the default catalog while the
+   * proxy-written one is left routed. The injected path is the only durable record of which
+   * file we actually touched.
+   */
+  injectedCatalogPath?: string | null;
   pid: number;
   timestamp: string;
 }
@@ -96,9 +114,30 @@ export function markJournalInjectedState(config: string, profile: string | null)
   if (journal.injectedConfigHash) return;
   journal.injectedConfigHash = sha256(config) ?? undefined;
   journal.injectedProfileHash = sha256(profile);
+  // Read from the bytes we are about to install, not from the file: another writer may
+  // already have rewritten it, and then the recorded value would describe their config.
+  journal.injectedOpenaiBaseUrl = rootTomlString(config, "openai_base_url");
+  journal.injectedCatalogPath = rootTomlString(config, "model_catalog_json");
   atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
 }
 
+/**
+ * The root `openai_base_url` the last injection wrote, or null when it wrote none.
+ *
+ * #1798: the fallback strip recognizes an injected URL by the marker COMMENT above it,
+ * and a Codex app rewrite keeps values while dropping comments. This is the evidence that
+ * survives such a rewrite, so restore can still prove the URL is ours -- and, just as
+ * importantly, prove that a DIFFERENT URL is not.
+ */
+export function journaledInjectedOpenaiBaseUrl(): string | null {
+  return readJournal()?.injectedOpenaiBaseUrl ?? null;
+}
+
+/** The catalog path the last injection wrote to, or null when none was recorded. */
+export function journaledInjectedCatalogPath(): string | null {
+  return readJournal()?.injectedCatalogPath ?? null;
+}
+
 export function removeJournal(): void {
   try { unlinkSync(JOURNAL_PATH); } catch { /* ignore */ }
 }

package/src/codex/management-convergence.ts

@@ -3,6 +3,7 @@ import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
 import { convergeCodexCatalog } from "./convergence";
 import type {
   CatalogDisposition,
+  CatalogFailureCause,
   CatalogOnlyOutcome,
   CodexHistoryState,
   CodexObservedState,
@@ -49,6 +50,58 @@ function notEvaluatedObserved(history: CodexHistoryState): CodexObservedState {
   };
 }
 
+/** Recognized errno/code tokens. Anything else is dropped rather than echoed. */
+const RECOGNIZED_FAILURE_CODES: ReadonlySet<string> = new Set([
+  "ENOSPC", "EACCES", "EPERM", "EROFS", "ENOENT", "SQLITE_BUSY",
+]);
+
+/**
+ * Reduce a caught error to an allowlisted cause (#1784).
+ *
+ * Nothing from the error text reaches the caller: `kind` is chosen from a closed set and
+ * `code` is only emitted when it is a recognized token. An `Error.message` routinely carries
+ * paths, home directories and account ids, and `redactSecretString` masks token shapes but
+ * none of those, so the message is never a safe thing to forward from here.
+ */
+function catalogFailureCause(error: unknown): CatalogFailureCause {
+  const raw = (error as { code?: unknown } | null)?.code;
+  const code = typeof raw === "string" && RECOGNIZED_FAILURE_CODES.has(raw)
+    ? raw as CatalogFailureCause["code"]
+    : undefined;
+  if (error instanceof TypeError || error instanceof RangeError || error instanceof SyntaxError) {
+    return { kind: "invalid-request", ...(code ? { code } : {}) };
+  }
+  if (code === "SQLITE_BUSY") return { kind: "lock-busy", code };
+  if (code !== undefined) return { kind: "io", code };
+  return { kind: "unknown" };
+}
+
+/**
+ * Classify a failure that is NOT a filesystem problem.
+ *
+ * `disk` used to be the catch-all, so an operator saw "non-retryable disk failure" for a
+ * malformed request. Reserve `disk` for real IO and route the rest to honest reasons.
+ */
+function classifiedCatalogFailure(error: unknown, commitBegan: boolean): CatalogDisposition {
+  const cause = catalogFailureCause(error);
+  const reason = cause.kind === "invalid-request"
+    ? "request-invalid" as const
+    : cause.kind === "lock-busy"
+      ? "admission" as const
+      : cause.kind === "io"
+        ? "disk" as const
+        : "internal" as const;
+  return {
+    status: "failed",
+    reason,
+    phase: commitBegan ? "commit" : "gather",
+    // Contention is the one class worth retrying unchanged.
+    retryable: reason === "admission",
+    partialWrite: commitBegan,
+    cause,
+  };
+}
+
 function unexpectedCatalogFailure(commitBegan: boolean): CatalogDisposition {
   return {
     status: "failed",
@@ -64,7 +117,7 @@ function admissionFailure(error: unknown): CatalogDisposition {
   if (message.includes("config generation is busy") || message.includes("config generation is database")) {
     return { status: "skipped", reason: "busy", retryable: true };
   }
-  return unexpectedCatalogFailure(false);
+  return classifiedCatalogFailure(error, false);
 }
 
 /** Project catalog work into the shared no-change/not-evaluated outcome shape. */
@@ -107,7 +160,7 @@ export function createManagementConvergeCodex(
     } catch (error) {
       return projectCatalogOnlyOutcome({
         changed: false,
-        catalogRefresh: commitBegan ? unexpectedCatalogFailure(true) : admissionFailure(error),
+        catalogRefresh: commitBegan ? classifiedCatalogFailure(error, true) : admissionFailure(error),
       });
     }
   };

package/src/codex/quota-rejection.ts

@@ -23,6 +23,63 @@ export interface CodexPreStreamRejection {
   alternateRetryEligible: boolean;
   resetCreditEligible: boolean;
   semanticCode?: CodexResetEligibleExhaustionCode;
+  /**
+   * Structured denial evidence for a 403. Present only when the upstream body names a
+   * workspace/entitlement denial, which proves the CREDENTIAL is valid and the account
+   * simply lacks access here (#1789). Status alone can never set this.
+   */
+  denial?: "workspace" | "entitlement";
+}
+
+/**
+ * Upstream codes that identify a WORKSPACE denial rather than a bad credential.
+ *
+ * #1789: a K12 account whose credential validates and whose WHAM usage returns 200 still
+ * gets 403 `codex_workspace_access_denied` on a routed prompt. Treating that as a credential
+ * failure tells the user to re-authenticate a credential that is already valid, and the loop
+ * repeats forever.
+ */
+const WORKSPACE_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "codex_workspace_access_denied",
+  "workspace_access_denied",
+]);
+
+const ENTITLEMENT_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "codex_entitlement_missing",
+  "entitlement_missing",
+]);
+
+/** Read a structured denial code out of a 403 body. Fails closed to undefined. */
+async function denialFromResponse(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<"workspace" | "entitlement" | undefined> {
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    if (isUnsafeJsonDocument(body.text)) return undefined;
+    const payload = JSON.parse(body.text) as unknown;
+    const code = structuredDenialCode(payload);
+    if (code === undefined) return undefined;
+    if (WORKSPACE_DENIAL_CODES.has(code)) return "workspace";
+    if (ENTITLEMENT_DENIAL_CODES.has(code)) return "entitlement";
+    return undefined;
+  } catch {
+    // Same fail-closed rule as the exhaustion classifier: an unreadable body must not
+    // downgrade a credential failure into a workspace one.
+    return undefined;
+  }
+}
+
+/** Own-property `code` lookup at the top level or under `error`. No coercion, no accessors. */
+function structuredDenialCode(payload: unknown): string | undefined {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const direct = (payload as Record<string, unknown>).code;
+  if (typeof direct === "string") return direct;
+  const error = (payload as Record<string, unknown>).error;
+  if (error === null || typeof error !== "object" || Array.isArray(error)) return undefined;
+  const nested = (error as Record<string, unknown>).code;
+  return typeof nested === "string" ? nested : undefined;
 }
 
 const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);
@@ -205,7 +262,10 @@ export async function classifyCodexPreStreamRejection(
 ): Promise<CodexPreStreamRejection> {
   const status = response.status;
   if (status === 401) return rejection(status, "authentication-error");
-  if (status === 403) return rejection(status, "permission-error");
+  if (status === 403) {
+    const denial = await denialFromResponse(response, options.signal);
+    return { ...rejection(status, "permission-error"), ...(denial ? { denial } : {}) };
+  }
   if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error");
   if (status !== 429 && status !== 402) return rejection(status, "other");
 

package/src/codex/quota.ts

@@ -9,6 +9,20 @@ export type StoredAccountQuota = {
   monthlyPercent?: number;
   weeklyResetAt?: number;
   monthlyResetAt?: number;
+  /**
+   * A sub-day burst window, when upstream declares one (#1791).
+   *
+   * K12 and similar plans enforce a rolling 5-hour limit ALONGSIDE the weekly one.
+   * Not folding it into `weeklyPercent` stopped the mislabeling, but dropping it
+   * entirely hides a limit that genuinely blocks the account: a 429 at 100% here is
+   * real even while the weekly quota is untouched.
+   *
+   * `shortWindowSeconds` is retained because the duration is the only thing that makes
+   * this window self-describing; the slot it arrived in is not stable across plans.
+   */
+  shortPercent?: number;
+  shortResetAt?: number;
+  shortWindowSeconds?: number;
   resetCredits?: number;
   /**
    * True when `monthlyPercent` came from an explicitly-monthly PRIMARY window —
@@ -56,6 +70,19 @@ type WhamUsageWindow = {
 };
 
 const MONTHLY_WINDOW_MIN_SECONDS = 28 * 24 * 60 * 60;
+/**
+ * Shortest window still plausibly the WEEKLY quota (#1791).
+ *
+ * K12 and similar plans send a 5-hour primary window plus a 7-day secondary. Folding the
+ * primary into `weeklyPercent` reported the 5-hour bar as the weekly one and discarded the
+ * real weekly reading entirely, so the dashboard showed a window that reset every few hours
+ * and routing never saw the limit that actually gates the account.
+ *
+ * 24h is the discriminator: anything shorter is a burst window, not a weekly one. A window
+ * with no declared duration is unchanged, because older payloads omit `limit_window_seconds`
+ * and guessing there would break every legacy account.
+ */
+const WEEKLY_WINDOW_MIN_SECONDS = 24 * 60 * 60;
 const MONTHLY_WINDOW_MIN_MINUTES = MONTHLY_WINDOW_MIN_SECONDS / 60;
 
 const accountQuota = new Map<string, StoredAccountQuota>();
@@ -72,13 +99,16 @@ export const CODEX_UNKNOWN_USAGE_SCORE = 101;
 export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
 
 export function isCodexQuotaExhausted(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent"> | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent"> | null,
   plan?: unknown,
 ): boolean {
   if (!quota) return false;
+  // The burst window counts on EVERY plan. It is upstream-enforced independently, so an
+  // account at 100% there is blocked regardless of which longer window governs its plan;
+  // omitting it would route traffic straight into a 429 (#1791).
   const values = codexQuotaWindowForPlan(plan) === "monthly"
-    ? [quota.monthlyPercent]
-    : [quota.weeklyPercent, quota.monthlyPercent];
+    ? [quota.monthlyPercent, quota.shortPercent]
+    : [quota.weeklyPercent, quota.monthlyPercent, quota.shortPercent];
   return values.some(value => typeof value === "number"
     && Number.isFinite(value)
     && value >= CODEX_EXHAUSTED_USAGE_PERCENT);
@@ -104,7 +134,7 @@ export function codexQuotaWindowForPlan(plan?: unknown): "monthly" | "weekly" {
 }
 
 export function isCompleteCodexQuotaRecoverySnapshot(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow"> | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow" | "shortPercent"> | null,
   plan?: unknown,
 ): boolean {
   if (!quota || isCodexQuotaExhausted(quota, plan)) return false;
@@ -160,6 +190,15 @@ function hasKnownQuotaValue(quota: Omit<StoredAccountQuota, "updatedAt">): boole
     .some(value => typeof value === "number" && Number.isFinite(value));
 }
 
+/** True only for a window that DECLARES a duration shorter than a day. */
+function isExplicitShortWindow(window: WhamUsageWindow | null | undefined): boolean {
+  const seconds = window?.limit_window_seconds;
+  return typeof seconds === "number"
+    && Number.isFinite(seconds)
+    && seconds > 0
+    && seconds < WEEKLY_WINDOW_MIN_SECONDS;
+}
+
 function isExplicitMonthlyWindow(window: WhamUsageWindow | null | undefined): boolean {
   const seconds = window?.limit_window_seconds;
   return typeof seconds === "number"
@@ -465,10 +504,25 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   // - 선택한 방식: only an explicit primary duration of at least 28 days changes it to monthly.
   // - 다른 대안 대신 이 방식을 선택한 이유: it accepts calendar-month variance and preserves legacy payloads.
   // - 장점, 단점 및 영향: Team monthly quotas classify correctly; unknown durations remain weekly by design.
-  const weeklyPercent = primaryIsMonthly ? secondaryPercent : primaryPercent ?? secondaryPercent;
+  // #1791: a primary window that declares a sub-day duration is a burst window, not the
+  // weekly one. Skip it so the secondary (the real 7-day window) is what lands in
+  // `weeklyPercent`; without this the 5-hour bar was reported as weekly and the actual
+  // weekly reading was dropped on the floor.
+  const primaryIsShort = isExplicitShortWindow(primaryWindow);
+  const weeklyCandidatePercent = primaryIsShort ? undefined : primaryPercent;
+  const weeklyCandidateResetAt = primaryIsShort ? undefined : primaryResetAt;
+  // Keep the burst reading instead of dropping it on the floor: it is a real limit, and
+  // the account is blocked when it fills even though the weekly window is fine (#1791).
+  if (primaryIsShort && primaryPercent !== undefined) {
+    quota.shortPercent = primaryPercent;
+    if (primaryResetAt !== undefined) quota.shortResetAt = primaryResetAt;
+    const seconds = primaryWindow?.limit_window_seconds;
+    if (typeof seconds === "number" && Number.isFinite(seconds)) quota.shortWindowSeconds = seconds;
+  }
+  const weeklyPercent = primaryIsMonthly ? secondaryPercent : weeklyCandidatePercent ?? secondaryPercent;
   const weeklyResetAt = primaryIsMonthly
     ? secondaryResetAt
-    : primaryPercent !== undefined ? primaryResetAt : secondaryResetAt;
+    : weeklyCandidatePercent !== undefined ? weeklyCandidateResetAt : secondaryResetAt;
   const monthlyPercent = primaryIsMonthly ? primaryPercent ?? tertiaryPercent : tertiaryPercent;
   const monthlyResetAt = primaryIsMonthly && primaryPercent !== undefined ? primaryResetAt : tertiaryResetAt;
   if (thirtyDayOnly) {