@bitkyc08/opencodex 2.88.0 → 2.90.0

package/src/codex/convergence.ts

@@ -53,7 +53,7 @@ import {
   orderForSubagents,
   } from "./catalog/sync";
   import { multiAgentV2EnabledFromConfigText } from "./features";
-  import { enforceCatalogSlugUniqueness, exactComboCatalogSlugs } from "./catalog/aggregation";
+  import { comboCatalogDescriptions, enforceCatalogSlugUniqueness, exactComboCatalogSlugs } from "./catalog/aggregation";
   import {
   isNativeAliasCatalogEntry,
   accountBoundNativeOpenAiSlugs,
@@ -392,6 +392,7 @@ function prepareCatalog(
     multiAgentV2Enabled,
     keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
     exactComboSlugs,
+    comboDescriptions: comboCatalogDescriptions(config),
     hasPhysicalComboProvider,
     includeNativeOpenAi,
     accountBoundEntries,

package/src/codex/low-quota-desktop-notifier.ts

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { isTestHomeGuardArmed } from "../lib/test-home-guard";
+
+/** What a low-quota notice may tell the operating system. Never an email, raw id or credential. */
+export type LowQuotaNotice = {
+  /** Pseudonymous `p<hex6>` log label of the pool account. */
+  accountLabel: string;
+  window: "short" | "weekly";
+  percentUsed: number;
+  threshold: number;
+  /** Epoch milliseconds of the window reset, when known. */
+  resetAt: number | null;
+};
+
+/** Resolves when the OS notifier accepted the notice; rejects on failure, timeout or abort. */
+export type LowQuotaNoticeSink = (notice: LowQuotaNotice, signal: AbortSignal) => Promise<void>;
+
+type SpawnedNotifier = { exited: Promise<number | null>; kill(): void };
+export type LowQuotaNotifierIo = {
+  platform?: NodeJS.Platform;
+  /** Returns true when the absolute path is an existing executable candidate. */
+  exists?: (path: string) => boolean;
+  spawn?: (argv: string[]) => SpawnedNotifier;
+  timeoutMs?: number;
+  /** Formats the reset time for display; defaults to the host locale. */
+  formatTime?: (epochMs: number) => string;
+};
+
+const OSASCRIPT = "/usr/bin/osascript";
+/** Literal system locations only: a PATH lookup would let any earlier PATH entry run as the proxy. */
+const NOTIFY_SEND_CANDIDATES = ["/usr/bin/notify-send", "/usr/local/bin/notify-send", "/bin/notify-send"];
+const DEFAULT_TIMEOUT_MS = 5_000;
+const TITLE = "OpenCodex quota";
+
+export function formatLowQuotaNotice(notice: LowQuotaNotice, formatTime: (epochMs: number) => string = defaultFormatTime): { title: string; body: string } {
+  const window = notice.window === "short" ? "5-hour" : "weekly";
+  const reset = notice.resetAt === null ? "reset time unknown" : `resets ${formatTime(notice.resetAt)}`;
+  return {
+    title: TITLE,
+    body: `Account ${notice.accountLabel}: ${window} quota at ${Math.round(notice.percentUsed)}% (threshold ${notice.threshold}%), ${reset}.`,
+  };
+}
+
+function defaultFormatTime(epochMs: number): string {
+  return new Date(epochMs).toLocaleString();
+}
+
+/** notify-send bodies may be parsed as markup by the notification server. */
+function escapeMarkup(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/**
+ * Builds the fixed argv for the host notifier. The notice text is always a separate argv item:
+ * the AppleScript source is constant and reads its arguments, and notify-send stops option
+ * parsing at `--`, so no account or quota text is ever interpreted as script or flags.
+ */
+export function lowQuotaNotifierArgv(
+  platform: NodeJS.Platform,
+  exists: (path: string) => boolean,
+  title: string,
+  body: string,
+): string[] | undefined {
+  if (platform === "darwin") {
+    if (!exists(OSASCRIPT)) return undefined;
+    return [OSASCRIPT, "-e", "on run argv", "-e", "display notification (item 2 of argv) with title (item 1 of argv)", "-e", "end run", title, body];
+  }
+  if (platform === "linux") {
+    const notifySend = NOTIFY_SEND_CANDIDATES.find(exists);
+    if (!notifySend) return undefined;
+    return [notifySend, "--app-name=OpenCodex", "--", title, escapeMarkup(body)];
+  }
+  return undefined;
+}
+
+function defaultSpawn(argv: string[]): SpawnedNotifier {
+  const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "ignore", stderr: "ignore", windowsHide: true });
+  return { exited: proc.exited, kill: () => { try { proc.kill(); } catch { /* already gone */ } } };
+}
+
+/**
+ * Returns a sink that hands notices to this host's notification service, or undefined when the
+ * platform has none we support (Windows and others stay log-only). An armed test process never
+ * reaches a real notifier unless a spawn is injected.
+ */
+export function resolveLowQuotaDesktopSink(io: LowQuotaNotifierIo = {}): LowQuotaNoticeSink | undefined {
+  if (!io.spawn && isTestHomeGuardArmed()) return undefined;
+  const platform = io.platform ?? process.platform;
+  const exists = io.exists ?? existsSync;
+  const spawn = io.spawn ?? defaultSpawn;
+  const timeoutMs = io.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const probe = lowQuotaNotifierArgv(platform, exists, TITLE, "");
+  if (!probe) return undefined;
+  return (notice, signal) => {
+    if (signal.aborted) return Promise.reject(new Error("low-quota notice cancelled"));
+    const { title, body } = formatLowQuotaNotice(notice, io.formatTime);
+    const argv = lowQuotaNotifierArgv(platform, exists, title, body);
+    if (!argv) return Promise.reject(new Error("low-quota notifier unavailable"));
+    let child: SpawnedNotifier;
+    try {
+      child = spawn(argv);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const finish = (error?: Error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onAbort);
+        if (error) reject(error);
+        else resolve();
+      };
+      const onAbort = () => { child.kill(); finish(new Error("low-quota notice cancelled")); };
+      const timer = setTimeout(() => { child.kill(); finish(new Error("low-quota notifier timed out")); }, timeoutMs);
+      (timer as { unref?: () => void }).unref?.();
+      signal.addEventListener("abort", onAbort, { once: true });
+      child.exited.then(
+        code => finish(code === 0 ? undefined : new Error(`low-quota notifier exited ${code}`)),
+        error => finish(error instanceof Error ? error : new Error("low-quota notifier failed")),
+      );
+    });
+  };
+}

package/src/codex/low-quota-protection.ts

@@ -4,15 +4,28 @@ import { isCodexAccountPaused, setCodexAccountPaused } from "./account-pause";
 import { createLowQuotaEventLedger, type LowQuotaEvent } from "./low-quota-events";
 import { registerLowQuotaObserver } from "./low-quota-observer";
 import { resetAtToMs } from "./quota-types";
+import { codexAccountLogLabel, fallbackCodexAccountLogLabel } from "./account-label";
+import type { LowQuotaNotice, LowQuotaNoticeSink } from "./low-quota-desktop-notifier";
 
-type Window = "short" | "weekly";
-type Notice = { window: Window; percentUsed: number; threshold: number };
 type Dependencies = {
   persist?: (config: OcxConfig) => void | Promise<void>;
-  notify?: (notice: Notice) => void | Promise<void>;
+  /** Injected sink; takes precedence over desktop delivery. */
+  notify?: (notice: LowQuotaNotice, signal: AbortSignal) => void | Promise<void>;
+  /** Resolved per notice, and only while the live policy opts into actions.desktop. */
+  desktopSink?: () => LowQuotaNoticeSink | undefined;
 };
 type EventBase = Omit<LowQuotaEvent, "timestamp" | "status" | "delivery">;
-type Episode = { reset: string; notice: "in-flight" | "logged" | "delivered" | "failed" | undefined; pausedByUs: boolean; noticeBase?: EventBase };
+type Episode = {
+  reset: string;
+  notice: "in-flight" | "logged" | "delivered" | "failed" | undefined;
+  pausedByUs: boolean;
+  noticeBase?: EventBase;
+  noticeAbort?: AbortController;
+  /** A failed notice may retry only after this time, so a broken notifier is not respawned per request. */
+  noticeRetryAt?: number;
+  /** The episode's log line was written; retries do not repeat it. */
+  warned?: boolean;
+};
 export type LowQuotaRegistration = (() => void) & {
   hasPendingSave(): boolean;
   flush(): Promise<void>;
@@ -20,6 +33,7 @@ export type LowQuotaRegistration = (() => void) & {
 };
 
 const RETRY_DELAYS_MS = [100, 250];
+const NOTICE_RETRY_MS = 5 * 60_000;
 const FLUSH_DEADLINE_MS = 500;
 
 /** Each server owns its own policy, episode state and deferred writer. */
@@ -44,6 +58,12 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
     if (delivery === "pause-save") pauseStatus.set(base, status);
     ledger.publish({ ...base, delivery, status, timestamp: Date.now() });
   }
+  /** Publishes one cancellation for an in-flight notice and stops its delivery. */
+  function cancelNotice(episode: Episode): void {
+    if (episode.notice === "in-flight" && episode.noticeBase) event(episode.noticeBase, "notice", "cancelled");
+    episode.noticeAbort?.abort();
+    episode.noticeAbort = undefined;
+  }
   function cancelTimer(): void {
     if (saveTimer) clearTimeout(saveTimer);
     saveTimer = null;
@@ -132,9 +152,7 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
       if (pauseStatus.get(base) === "pending") event(base, "pause-save", "cancelled");
       pendingPauseEvents.delete(key);
     }
-    for (const episode of episodes.values()) {
-      if (episode.notice === "in-flight" && episode.noticeBase) event(episode.noticeBase, "notice", "cancelled");
-    }
+    for (const episode of episodes.values()) cancelNotice(episode);
     dirty = false;
     autoPausedAccounts.clear();
     unregister();
@@ -175,9 +193,7 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
     const policy = config.codexPool?.lowQuotaProtection;
     const nextKey = JSON.stringify(policy);
     if (policyKey !== nextKey) {
-      for (const episode of episodes.values()) {
-        if (episode.notice === "in-flight" && episode.noticeBase) event(episode.noticeBase, "notice", "cancelled");
-      }
+      for (const episode of episodes.values()) cancelNotice(episode);
       episodes.clear();
       autoPausedAccounts.clear();
       policyKey = nextKey;
@@ -187,7 +203,7 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
     for (const id of autoPausedAccounts) if (!liveIds.has(id)) autoPausedAccounts.delete(id);
     for (const [key, episode] of episodes) {
       if (liveIds.has(key.split("\u0000")[0]!)) continue;
-      if (episode.notice === "in-flight" && episode.noticeBase) event(episode.noticeBase, "notice", "cancelled");
+      cancelNotice(episode);
       episodes.delete(key);
     }
     if (!liveIds.has(accountId)) return;
@@ -203,7 +219,7 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
       const key = `${accountId}\u0000${window}`;
       if (percentUsed < policy.threshold) {
         const prior = episodes.get(key);
-        if (prior?.notice === "in-flight" && prior.noticeBase) event(prior.noticeBase, "notice", "cancelled");
+        if (prior) cancelNotice(prior);
         episodes.delete(key);
         continue;
       }
@@ -211,6 +227,7 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
       const reset = resetAt === null ? "unknown" : String(resetAt);
       let episode = episodes.get(key);
       if (!episode || episode.reset !== reset) {
+        if (episode) cancelNotice(episode);
         episode = { reset, notice: undefined, pausedByUs: false };
         episodes.set(key, episode);
       }
@@ -234,32 +251,41 @@ export function registerCodexLowQuotaProtection(config: OcxConfig, deps: Depende
         scheduleSave();
       }
       // A manual resume leaves pausedByUs set until recovery or a new reset episode.
-      if (policy.actions.notify && episode.notice !== "in-flight" && episode.notice !== "logged" && episode.notice !== "delivered") {
-        console.warn(`[codex-low-quota] ${window === "short" ? "5-hour" : "weekly"} quota reached ${percentUsed}% used (threshold ${policy.threshold}%)`);
-        if (!deps.notify) {
+      if (policy.actions.notify && episode.notice !== "in-flight" && episode.notice !== "logged" && episode.notice !== "delivered"
+        && !(episode.notice === "failed" && (episode.noticeRetryAt ?? 0) > Date.now())) {
+        if (!episode.warned) {
+          episode.warned = true;
+          console.warn(`[codex-low-quota] ${window === "short" ? "5-hour" : "weekly"} quota reached ${percentUsed}% used (threshold ${policy.threshold}%)`);
+        }
+        const sink = deps.notify ?? (policy.actions.desktop === true ? deps.desktopSink?.() : undefined);
+        if (!sink) {
           event(base, "notice", "logged");
           episode.notice = "logged";
           continue;
         }
-        episode.notice = "in-flight";
-        episode.noticeBase = base;
+        const account = config.codexAccounts?.find(candidate => candidate.id === accountId);
+        const notice: LowQuotaNotice = {
+          accountLabel: account ? codexAccountLogLabel(account) : fallbackCodexAccountLogLabel(accountId),
+          window, percentUsed, threshold: policy.threshold, resetAt,
+        };
+        const abort = new AbortController();
+        const current = episode;
+        current.notice = "in-flight";
+        current.noticeBase = base;
+        current.noticeAbort = abort;
         event(base, "notice", "pending");
+        const settle = (status: "delivered" | "failed") => {
+          if (closed || abort.signal.aborted || episodes.get(key) !== current) return;
+          event(base, "notice", status);
+          current.notice = status;
+          current.noticeRetryAt = status === "failed" ? Date.now() + NOTICE_RETRY_MS : undefined;
+          current.noticeBase = undefined;
+          current.noticeAbort = undefined;
+        };
         try {
-          void Promise.resolve(deps.notify({ window, percentUsed, threshold: policy.threshold })).then(() => {
-            if (closed || episodes.get(key) !== episode) return;
-            event(base, "notice", "delivered");
-            episode.notice = "delivered";
-            episode.noticeBase = undefined;
-          }, () => {
-            if (closed || episodes.get(key) !== episode) return;
-            event(base, "notice", "failed");
-            episode.notice = "failed";
-            episode.noticeBase = undefined;
-          });
+          void Promise.resolve(sink(notice, abort.signal)).then(() => settle("delivered"), () => settle("failed"));
         } catch {
-          event(base, "notice", "failed");
-          episode.notice = "failed";
-          episode.noticeBase = undefined;
+          settle("failed");
         }
       }
     }

package/src/codex/main-account-cache.ts

@@ -1,3 +1,5 @@
+import { getConfigDir } from "../config/paths";
+import { notifyMainRosterChanged, type MainDecisionRow } from "../lib/decision-quota-sink";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { codexCredentialMutationEpoch } from "./credential-mutation-epoch";
 import type { StoredAccountQuota } from "./quota-types";
@@ -22,11 +24,33 @@ let observedMainQuotaIdentityKey: string | undefined;
 const mainQuotaCredentialKey = randomBytes(32);
 let mainQuotaCredential: { bearerHmac: Buffer; writer: MainQuotaWriter } | undefined;
 let mainQuotaCredentialGeneration = 0;
+let mainDecisionCredentialUsable = true;
+// Advisory-only generation for the decision row and its writers. It follows every core credential
+// generation change and additionally advances when physical presence is lost, so absence retires
+// advisory evidence without touching the core credential binding that policy checks rely on.
+let mainDecisionGeneration = 0;
+// Advisory-only: the retained credential was re-observed since presence was last lost. Absence and
+// presence-forgetting clear it, so the decision row stays unusable until a fresh owned observation.
+let mainDecisionCredentialFresh = false;
+// Config root that owns the observed main identity/credential for advisory decision evidence only.
+// Stamped at identity/credential observations while a sink is active; other transitions never claim a root.
+let mainDecisionRoot: string | undefined;
+/** Existing physical credential owner supplies terminal grant/usability observations. */
+export function observeMainDecisionCredentialUsable(usable: boolean): void {
+  mainDecisionCredentialUsable = usable;
+  publishMainDecisionRoster();
+}
 
 /** Process-local transition fence; no credential material or persisted identity. */
 export function getMainQuotaCredentialGeneration(): number { return mainQuotaCredentialGeneration; }
 
 export type MainQuotaWriter = Readonly<{ identityKey: string; identityGeneration: number }>;
+const decisionWriterGenerations = new WeakMap<MainQuotaWriter, number>();
+/** Return the credential generation a main quota writer was captured under, or undefined once that writer is stale or its credential generation has moved. */
+export function mainDecisionQuotaWriterGeneration(writer: MainQuotaWriter): number | undefined {
+  const generation = decisionWriterGenerations.get(writer);
+  return generation === mainDecisionGeneration && isMainQuotaWriterLive(writer) && mainDecisionRoot === getConfigDir() ? generation : undefined;
+}
 
 function mainQuotaIdentityKey(accountId: string): string {
   return createHash("sha256").update("opencodex-main-quota-v1\0").update(accountId).digest("hex");
@@ -38,16 +62,22 @@ export function observeMainQuotaIdentity(accountId: string): void {
   const identityKey = mainQuotaIdentityKey(accountId);
   if (identityKey === observedMainQuotaIdentityKey) return;
   observedMainQuotaIdentityKey = identityKey;
+  mainDecisionCredentialUsable = true;
   mainAccountIdentityGeneration += 1;
   mainQuotaCredential = undefined;
   mainQuotaCredentialGeneration += 1;
+  mainDecisionGeneration += 1;
+  publishMainDecisionRoster(true);
 }
 
+/** Capture a main quota writer for an account id only when it matches the observed physical identity, remembering the credential generation it was captured under. */
 export function captureMainQuotaWriter(accountId: string): MainQuotaWriter | undefined {
   if (!accountId) return undefined;
   const identityKey = mainQuotaIdentityKey(accountId);
   if (identityKey !== observedMainQuotaIdentityKey) return undefined;
-  return { identityKey, identityGeneration: mainAccountIdentityGeneration };
+  const writer = { identityKey, identityGeneration: mainAccountIdentityGeneration };
+  if (mainQuotaCredential) decisionWriterGenerations.set(writer, mainDecisionGeneration);
+  return writer;
 }
 
 /** Credential material must come from an already-owned read, never an incoming request. */
@@ -56,9 +86,13 @@ export function observeMainQuotaCredential(accessToken: string, accountId: strin
   if (!accessToken || !writer) return undefined;
   const bearerHmac = createHmac("sha256", mainQuotaCredentialKey).update(accessToken).digest();
   if (!mainQuotaCredential || !isMainQuotaWriterLive(mainQuotaCredential.writer)
-    || !timingSafeEqual(bearerHmac, mainQuotaCredential.bearerHmac)) mainQuotaCredentialGeneration += 1;
+    || !timingSafeEqual(bearerHmac, mainQuotaCredential.bearerHmac)) { mainQuotaCredentialGeneration += 1; mainDecisionGeneration += 1; }
   mainQuotaCredential = { bearerHmac, writer };
-  return { ...writer };
+  mainDecisionCredentialFresh = true;
+  publishMainDecisionRoster(true);
+  const result = { ...writer };
+  decisionWriterGenerations.set(result, mainDecisionGeneration);
+  return result;
 }
 
 export function matchesMainQuotaCredential(accessToken: string, effectiveAccountId: string | undefined): boolean {
@@ -140,11 +174,14 @@ export function setMainAccountInfoCache(value: CachedMainAccountInfo): void {
   };
 }
 
+/** Drop the cached main-account info and invalidate the observed identity and credential generation, then republish the main decision roster as unusable. */
 export function clearMainAccountInfoCache(): void {
   cachedMainAccountInfo = null;
   mainAccountIdentityGeneration += 1;
   mainQuotaCredential = undefined;
   mainQuotaCredentialGeneration += 1;
+  mainDecisionGeneration += 1;
+  publishMainDecisionRoster();
 }
 
 /** Last physical credential presence observed while native-main ownership was held. */
@@ -152,10 +189,47 @@ export function getMainAccountCredentialPresence(): boolean | null {
   return cachedMainCredentialPresence;
 }
 
+/** Record whether the main credential is physically present. The core credential binding is left intact (a failed read must not change policy matching); losing presence only retires advisory decision evidence. */
 export function setMainAccountCredentialPresence(present: boolean): void {
+  if (!present && cachedMainCredentialPresence !== false) { mainDecisionGeneration += 1; mainDecisionCredentialFresh = false; }
   cachedMainCredentialPresence = present;
+  publishMainDecisionRoster();
 }
 
+/** Forget the last observed main credential presence; retires advisory decision evidence only, leaving the core credential binding intact. */
 export function clearMainAccountCredentialPresence(): void {
   cachedMainCredentialPresence = null;
+  mainDecisionGeneration += 1;
+  mainDecisionCredentialFresh = false;
+  publishMainDecisionRoster();
+}
+
+/**
+ * Build the single `__main__` decision row from in-memory fields. With no retained credential the
+ * row is a known-unusable main (nothing to misattribute), as before. A retained credential counts only
+ * for the config root that observed it: for any other root the row is undefined (unknown) and the
+ * claimed root is forgotten, so returning to the old root never resurrects it without a new owned
+ * observation.
+ */
+function mainDecisionRow(): MainDecisionRow | undefined {
+  if (mainQuotaCredential === undefined) return { generation: mainDecisionGeneration, usable: false };
+  if (mainDecisionRoot === undefined || mainDecisionRoot !== getConfigDir()) {
+    mainDecisionRoot = undefined;
+    return undefined;
+  }
+  return { generation: mainDecisionGeneration,
+    usable: mainDecisionCredentialFresh && mainDecisionCredentialUsable && cachedMainCredentialPresence !== false };
+}
+
+/** Hand the main decision row to the opt-in decision-quota slot (a no-op unless JEV quota signals are active); identity/credential observations claim the current root. */
+function publishMainDecisionRoster(claimsRoot = false): void {
+  notifyMainRosterChanged(() => {
+    if (claimsRoot) mainDecisionRoot = getConfigDir();
+    return mainDecisionRow();
+  });
+}
+
+/** Activation replay for the JEV quota owner: the current row, or undefined when the observed credential belongs to another config root. */
+export function peekMainDecisionRow(): MainDecisionRow | undefined {
+  return mainDecisionRow();
 }

package/src/codex/main-account-hard-lock.ts

@@ -121,3 +121,17 @@ export function getMainAccountHardLockStatus(
 export function isMainAccountHardLocked(config: PolicyConfig, now = Date.now()): boolean {
   return getMainAccountHardLockStatus(config, now).state === "blocked";
 }
+
+/**
+ * Scheduling evidence only: the latest blocking reset even after it has passed, so recovery can
+ * notice a revised reset that expired between sweeps. Never an admission or unlock signal.
+ */
+export function latestMainBlockingResetAt(config: PolicyConfig): number | undefined {
+  if (!isMainAccountHardLockEnabled(config)) return undefined;
+  const quota = getMainPolicyQuota();
+  if (!quota) return undefined;
+  const thresholds = resolveMainAccountHardLockThresholds(config);
+  const resets = governingWindows(quota)
+    .filter(w => validPercent(w.percent) && w.percent >= thresholds[w.kind]).map(w => resetTimestamp(w.resetAt));
+  return resets.length > 0 && resets.every(r => r !== undefined) ? Math.max(...(resets as number[])) : undefined;
+}

package/src/codex/main-account.ts

@@ -1,3 +1,4 @@
+import { observeMainDecisionCredentialUsable } from "./main-account-cache";
 import { classifyChatgptRefreshFailure, noteChatgptRefreshFailure } from "./chatgpt-refresh-failure";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { createHash } from "node:crypto";
@@ -245,10 +246,12 @@ export function getMainAccountCredentialStatus(now = Date.now()): MainAccountCre
   const current = readMainAuthJsonCredential();
   const refreshGrantRejected = credentialRefreshGrantRejected(current);
   const hasRefreshGrant = !!current?.refreshToken && !refreshGrantRejected;
+  const usable = !refreshGrantRejected && (hasRefreshGrant || mainAccessTokenFresh(current?.accessToken, now, 0));
+  observeMainDecisionCredentialUsable(usable);
   return {
     refreshGrantRejected,
     hasRefreshGrant,
-    usable: !refreshGrantRejected && (hasRefreshGrant || mainAccessTokenFresh(current?.accessToken, now, 0)),
+    usable,
   };
 }
 
@@ -444,6 +447,7 @@ export function beginNativeMainReauth(): {
   };
 }
 
+/** Resolve the main account access token from the owned auth.json read, refreshing through the token endpoint when needed, or return null when no usable credential exists. */
 async function resolveMainAccountToken(
   dependencies: NativeMainRefreshDependencies = {},
   rejectedAccessToken?: string,
@@ -546,7 +550,7 @@ async function resolveMainAccountToken(
           if (signal.aborted) throw signal.reason;
           if (reason === "reauth") {
             assertMainAuthJsonSnapshotUnchanged(locked);
-            markMainRefreshGrantRejected(mainRefreshGrantKey(locked)!);
+            markMainRefreshGrantRejected(mainRefreshGrantKey(locked)!); observeMainDecisionCredentialUsable(false);
           }
           throw new MainAccountTokenRefreshError(reason, { cause });
         }

package/src/codex/native-residue.ts

@@ -17,6 +17,7 @@ import { Database } from "bun:sqlite";
 
 import { getConfigDir } from "../config";
 import { catalogHasRoutedEntries, parseCatalogJson } from "./catalog/parsing";
+import { hasOcxRoutedAuthorship } from "./catalog/ownership";
 import { codexHistoryBackupId, legacyCodexHistoryBackupId, validateCodexHistoryBackupManifest } from "./history-manifest";
 import {
   hasInjectedCodexRouting,
@@ -79,7 +80,6 @@ const PROFILE_FILE_NAME = basename(CODEX_PROFILE_PATH);
 const CATALOG_FILE_NAME = basename(DEFAULT_CATALOG_PATH);
 const MODELS_CACHE_FILE_NAME = basename(CODEX_MODELS_CACHE_PATH);
 const JOURNAL_FILE_NAME = "opencodex-journal.json";
-const ROUTED_CATALOG_DESCRIPTION_PREFIX = "Routed via opencodex → ";
 const MAX_ROLLOUT_INSPECTION_BYTES = 64 * 1024 * 1024;
 const ROLLOUT_READ_CHUNK_BYTES = 64 * 1024;
 // Bound one observation across every referenced rollout, not just each file.
@@ -339,8 +339,7 @@ function classifyProfile(path: string): NativeRoutedResidueResult {
 }
 
 function isOcxRoutedCatalogEntry(entry: Record<string, unknown>): boolean {
-  return typeof entry.description === "string"
-    && entry.description.startsWith(ROUTED_CATALOG_DESCRIPTION_PREFIX);
+  return hasOcxRoutedAuthorship(entry);
 }
 
 function classifyCatalogLike(

package/src/codex/quota.ts

@@ -1,3 +1,5 @@
+import { bindRawCodexDecisionResets, publishCodexDecisionQuota } from "../providers/quota-decision-publication";
+import { clearDecisionAccountQuotas, decisionQuotaSinkActive } from "../lib/decision-quota-sink";
 import { parseCodexCredits } from "./credits";
 import { forgetMainAccountUsage, observeMainAccountUsage, type FreshWindow } from "./main-account-external-usage";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, openSync, readSync, unlinkSync } from "node:fs";
@@ -8,7 +10,7 @@ import { isThirtyDayOnlyCodexPlan } from "./plan";
 import { stampCodexQuotaUsageObservation } from "./quota-observation-freshness";
 import { observeCodexLowQuota } from "./low-quota-observer";
 import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
-import { getObservedMainQuotaIdentityKey, isMainQuotaWriterLive, type MainQuotaWriter } from "./main-account-cache";
+import { getObservedMainQuotaIdentityKey, mainDecisionQuotaWriterGeneration, isMainQuotaWriterLive, type MainQuotaWriter } from "./main-account-cache";
 
 import { CodexQuotaHistory, QUOTA_HISTORY_LIMITS, type QuotaHistoryWindow } from "./quota-history";
 import { isPoolQuotaWriterLive, poolQuotaHistoryIdentity } from "./account-store";
@@ -301,6 +303,9 @@ export function setAccountQuotaFromParsed(
   // writer: when capture failed before dispatch, an absent writer must fail closed instead
   // of reading as a writer-free legacy/login observation.
   poolRequest = false,
+  decisionObservationPartial = true,
+  // Advisory publication is explicit opt-in evidence: display or policy data never becomes it by default.
+  decisionRaw: Omit<StoredAccountQuota, "updatedAt"> | null = null,
 ): void {
   quota = withoutRetiredCodexQuota(quota);
   policyQuota = withoutRetiredCodexQuota(policyQuota);
@@ -315,12 +320,16 @@ export function setAccountQuotaFromParsed(
     ? historyEvidence.writer.accountId === accountId && isPoolQuotaWriterLive(historyEvidence.writer)
     : !poolRequest;
   if (historyEvidence && livePoolEvidence) {
+    publishCodexDecisionQuota(accountId, historyEvidence.writer.credentialGeneration, historyEvidence.raw, historyEvidence.observedAt, "codex", historyEvidence.source === "response-header");
     quotaHistory.append(historyEvidence.writer, { observedAt: historyEvidence.observedAt, source: historyEvidence.source,
       credentialGeneration: historyEvidence.writer.credentialGeneration, windows: historyWindows(historyEvidence.raw),
     }, updatedAt);
   }
   // Rotation shares validated main-window retirement, but never inherits policy-only
   // evidence that outlived its disk TTL. Policy has a separate, identity-checked base.
+  const mainDecisionGeneration = mainWriter && mainDecisionQuotaWriterGeneration(mainWriter);
+  if (isMain && mainDecisionGeneration !== undefined && decisionRaw)
+    publishCodexDecisionQuota(accountId, mainDecisionGeneration, decisionRaw, updatedAt, "codex-main", decisionObservationPartial);
   const displayQuota: MainPolicyQuotaObservation = isMain && mainWriter && policyQuota?.shortWindowAbsent === true
     ? { ...quota, shortWindowAbsent: true }
     : quota;
@@ -544,6 +553,7 @@ export function withoutRetiredCodexQuota<T extends Omit<StoredAccountQuota, "upd
   return snapshotHasUsage(next) || snapshotHasCredits(next) ? next as T : null;
 }
 
+/** Parse `x-codex-*` rate-limit headers into a quota observation, binding the raw reset values so decision evidence can keep invalid resets distinct from the display fields. */
 export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?: string }): Omit<StoredAccountQuota, "updatedAt"> | null {
   if (isRetiredCodexSparkModel(options?.modelId)) return null;
   const primaryRaw = headers.get("x-codex-primary-used-percent");
@@ -610,9 +620,15 @@ export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?
     if (tertiaryResetAt !== undefined) quota.monthlyResetAt = tertiaryResetAt;
   }
 
+  if (decisionQuotaSinkActive()) bindRawCodexDecisionResets(quota, {
+    short: primaryResetRaw,
+    weekly: primaryIsMonthly || primaryIsShort || primaryPercent === undefined ? secondaryResetRaw : primaryResetRaw,
+    monthly: primaryIsMonthly && primaryPercent !== undefined ? primaryResetRaw : tertiaryResetRaw,
+  }, Date.now());
   return hasKnownQuotaValue(quota) ? quota : null;
 }
 
+/** Apply upstream rate-limit headers for an account: publish display and policy quota and, only for a valid observation, the advisory decision evidence. */
 export function applyAccountQuotaFromUpstreamHeaders(
   accountId: string,
   headers: Headers,
@@ -629,7 +645,7 @@ export function applyAccountQuotaFromUpstreamHeaders(
     .some(name => isInvalidPolicyUsagePercent(headers.get(name)));
   setAccountQuotaFromParsed(accountId, quota, writerGeneration, mainWriter, policyQuota,
     options?.poolWriter && validHistory ? { writer: options.poolWriter, observedAt: Date.now(), source: "response-header", raw: quota } : undefined,
-    options?.poolResponse === true);
+    options?.poolResponse === true, true, validHistory ? quota : null);
 }
 
 export function updateAccountQuota(
@@ -822,7 +838,10 @@ function forgetCodexQuotaBaseline(accountId?: string): void {
     });
 }
 
+/** Clear stored quota, advisory decision evidence and history for one account, or for all accounts when no id is given. */
 export function clearAccountQuota(accountId?: string): void {
+  clearDecisionAccountQuotas("codex", accountId);
+  if (!accountId || accountId === MAIN_CODEX_ACCOUNT_ID) clearDecisionAccountQuotas("codex-main");
   if (!accountId || accountId === MAIN_CODEX_ACCOUNT_ID) forgetMainAccountUsage();
   if (accountId) hydrateAccountQuotasFromDisk();
   quotaHistory.clear(accountId);
@@ -1009,6 +1028,11 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
 
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
+  if (decisionQuotaSinkActive()) bindRawCodexDecisionResets(quota, {
+    short: primaryWindow?.reset_at,
+    weekly: primaryIsMonthly || weeklyCandidatePercent === undefined ? secondaryWindow?.reset_at : primaryWindow?.reset_at,
+    monthly: primaryIsMonthly && primaryPercent !== undefined ? primaryWindow?.reset_at : tertiaryWindow?.reset_at,
+  }, Date.now());
   return hasKnownQuotaValue(quota) || snapshotHasCredits(quota) ? quota : null;
 }
 

package/src/codex/routing/cooldown-math.ts

@@ -6,6 +6,7 @@ import { isThirtyDayOnlyCodexPlan } from "../plan";
 import { hasSpendableCodexCredits, isTerminalShortWindow, type CodexSpendableCredits } from "../quota-types";
 import type { CodexQuotaScope } from "./health-store";
 import type { TransientProbeGrant } from "./thread-affinity";
+import type { MainQuotaDispatch } from "../main-account-cache";
 
 export { TERMINAL_SHORT_WINDOW_FRESHNESS_MS } from "../quota-types";
 
@@ -99,6 +100,10 @@ export type CodexUpstreamOutcomeMeta = {
    * means the caller cannot supply lineage and the historical unfenced handling stands.
    */
   credentialGeneration?: number;
+  /** Main credential proof captured before dispatch; null means no owned proof was available. */
+  mainFailureWindowDispatch?: MainQuotaDispatch | null;
+  /** Pool sample provenance retained by a terminal callback even if its context is reused. */
+  failureWindowCredentialGeneration?: number;
 };
 
 export function computeCodexUsageScore(quota: {