@bitkyc08/opencodex 2.87.0 → 2.89.0

package/src/codex/catalog/derive-entry.ts

@@ -26,6 +26,7 @@ import {
   isGpt56NativeSlug,
 } from "./effort";
 import { CATALOG_INACTIVE_REASON_FIELD, SPAWN_PRIORITY_FIELD } from "./subagent-roster";
+import { applyRoutedDescription } from "./ownership";
 
 export function finishUpstreamNativeEntry(clone: RawEntry, priority: number, contextCap?: NativeContextLimitsInput): RawEntry {
   if (priority !== 9) clone.priority = priority;
@@ -128,7 +129,7 @@ export function deriveEntry(
     delete e[SPAWN_PRIORITY_FIELD];
     e.slug = slug;
     e.display_name = routedDisplayName(slug, model);
-    e.description = desc;
+    applyRoutedDescription(e, desc, model);
     e.priority = priority;
     e.visibility = "list";
     if ("upgrade" in e) e.upgrade = null;
@@ -212,6 +213,7 @@ export function deriveEntry(
         : { web_search_tool_type: "text_and_image", supports_search_tool: true }
       : {}),
   };
+  applyRoutedDescription(entry, desc, model);
   if (isRouted) {
     applyRoutedCodexToolMode(entry, model?.codexToolMode);
     applyReasoningLevels(

package/src/codex/catalog/metadata.ts

@@ -38,6 +38,7 @@ import type { RawEntry } from "./parsing";
 import { readCurrentCatalogOrCache, readCurrentCodexCatalog, readCurrentCodexModelsCache, unique } from "./bundled";
 import { trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./account-models";
 import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
+import { ROUTED_ORIGIN_FIELD } from "./ownership";
 import { RESERVE_METADATA_SOURCE_FIELD } from "./reserve";
 import {
   ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
@@ -813,6 +814,7 @@ export function observedReserveCatalogSource(
   }
   source.slug = NATIVE_RESERVE_MODEL;
   delete source.opencodex_catalog_kind;
+  delete source[ROUTED_ORIGIN_FIELD];
   delete source[RESERVE_METADATA_SOURCE_FIELD];
   delete source[ACCOUNT_BOUND_OBSERVED_NATIVE_MARKER];
   delete source[ACCOUNT_BOUND_OBSERVED_SELECTORS_MARKER];

package/src/codex/catalog/model-visibility.ts

@@ -189,7 +189,6 @@ export function warnDroppedConfiguredIdsOnce(name: string, droppedConfiguredIds:
   );
 }
 export function shouldExposeProviderModel(providerName: string, modelId: string): boolean {
-  if (providerName === "opencode-free") return modelId === "big-pickle" || modelId.endsWith("-free");
   // xAI /models advertises both the dated deployment and this floating alias.
   // Keep only grok-4.20-multi-agent-0309; the alias is the same server-side id.
   if (providerName === "xai" && modelId === "grok-4.20-multi-agent-beta-latest") return false;
@@ -205,7 +204,6 @@ export function shouldRetainConfiguredProviderModel(
   prov?: OcxProviderConfig,
 ): boolean {
   if (CALLABLE_CONFIGURED_COMPATIBILITY_MODELS[providerName]?.has(modelId)) return true;
-  if (providerName === "opencode-free") return modelId === "big-pickle" || modelId.endsWith("-free");
   if (modelInList(prov?.retainModels, modelId)) return true;
   return false;
 }

package/src/codex/catalog/ownership.ts

@@ -0,0 +1,71 @@
+import { COMBO_NAMESPACE } from "../../combos/identifiers";
+import type { CatalogModel, RawEntry } from "./parsing";
+
+/**
+ * Authorship of OpenCodex-generated routed catalog rows (#855, #7229).
+ *
+ * A generated routed row normally carries the description prefix below, and that prefix is what
+ * removal, template selection, auto-review and residue detection have always recognized. A combo
+ * may replace its row description (#7229), so such a row carries a stable marker instead. Rows
+ * with the generated description stay byte-identical and keep prefix recognition; only an exact
+ * known marker value confers authorship.
+ */
+export const ROUTED_DESCRIPTION_PREFIX = "Routed via opencodex → ";
+export const ROUTED_ORIGIN_FIELD = "opencodex_routed_origin";
+export const COMBO_ROUTED_ORIGIN = "combo-v1";
+const COMBO_DESCRIPTION_PREFIX = `${ROUTED_DESCRIPTION_PREFIX}${COMBO_NAMESPACE} (`;
+
+function descriptionStartsWith(entry: RawEntry, prefix: string): boolean {
+  return typeof entry.description === "string" && entry.description.startsWith(prefix);
+}
+
+/** True for a row whose description was overridden by a combo and stamped by OpenCodex. */
+export function hasComboRoutedOriginMarker(entry: RawEntry): boolean {
+  return entry[ROUTED_ORIGIN_FIELD] === COMBO_ROUTED_ORIGIN;
+}
+
+/** Generated by OpenCodex routing: the stable marker, or the legacy generated description. */
+export function hasOcxRoutedAuthorship(entry: RawEntry): boolean {
+  return hasComboRoutedOriginMarker(entry) || descriptionStartsWith(entry, ROUTED_DESCRIPTION_PREFIX);
+}
+
+/** Generated for a combo: the stable marker, or the legacy generated combo description. */
+export function hasOcxComboAuthorship(entry: RawEntry): boolean {
+  return hasComboRoutedOriginMarker(entry) || descriptionStartsWith(entry, COMBO_DESCRIPTION_PREFIX);
+}
+
+/** The operator's combo description override, if this routed model has one. */
+export function comboDescriptionOverride(model: CatalogModel | undefined): string | undefined {
+  if (model?.provider !== COMBO_NAMESPACE) return undefined;
+  const description = typeof model.description === "string" ? model.description.trim() : "";
+  return description || undefined;
+}
+
+/**
+ * Set a routed row's description and its authorship marker together. A template clone may carry
+ * another row's marker, so the marker is always rewritten from this model's own override.
+ */
+export function applyRoutedDescription(entry: RawEntry, generated: string, model: CatalogModel | undefined): void {
+  const override = comboDescriptionOverride(model);
+  entry.description = override ?? generated;
+  if (override !== undefined) entry[ROUTED_ORIGIN_FIELD] = COMBO_ROUTED_ORIGIN;
+  else delete entry[ROUTED_ORIGIN_FIELD];
+}
+
+/**
+ * A combo row retained from the previous catalog (its fresh derivation failed, e.g. a member
+ * provider is temporarily unavailable) bypasses deriveEntry. Re-project the combo's CURRENT
+ * description onto it so clearing or changing the description in config still reaches the
+ * picker. A cleared override returns the row to the generated combo text without the marker;
+ * an unmarked row without a current override is left exactly as it was.
+ */
+export function reapplyRetainedComboDescription(entry: RawEntry, current: string | undefined): void {
+  const description = current?.trim();
+  if (description) {
+    entry.description = description;
+    entry[ROUTED_ORIGIN_FIELD] = COMBO_ROUTED_ORIGIN;
+  } else if (hasComboRoutedOriginMarker(entry)) {
+    entry.description = `${ROUTED_DESCRIPTION_PREFIX}${COMBO_NAMESPACE} (${COMBO_NAMESPACE}).`;
+    delete entry[ROUTED_ORIGIN_FIELD];
+  }
+}

package/src/codex/catalog/parsing.ts

@@ -43,6 +43,7 @@ import { NATIVE_OPENAI_CONTEXT_OVERRIDES, SUPPORTED_NATIVE_OPENAI_SLUGS, UPSTREA
 import { clampAutoCompactTokenLimit } from "../../providers/auto-compact-budget";
 import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
 import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
+import { hasComboRoutedOriginMarker, hasOcxRoutedAuthorship } from "./ownership";
 import { NATIVE_GPT6_ASTRA_MODEL } from "./native-models";
 import { recordOwnedConfigPath } from "../../lib/config-ownership";
 
@@ -95,6 +96,12 @@ export interface CatalogModel {
    * which carries no CatalogModel, so a configured displayName can never override a native name.
    */
   displayName?: string;
+  /**
+   * Display-only Codex catalog `description` override, honored for combo rows only (#7229).
+   * Unset keeps the generated "Routed via opencodex → …" text; a set value stamps the row with
+   * the ownership marker in ./ownership so removal and template selection still recognize it.
+   */
+  description?: string;
   owned_by?: string;
   reasoningEfforts?: string[];
   /** Exact CCA family evidence, retained through the in-memory discovery cache. */
@@ -297,7 +304,7 @@ export function findNativeTemplate(catalog: RawCatalog | null): RawEntry | null
       && "base_instructions" in m
       && m.opencodex_catalog_kind !== CODEX_NATIVE_ALIAS_CATALOG_KIND
       && m.owned_by !== COMBO_NAMESPACE
-      && !(typeof m.description === "string" && m.description.startsWith("Routed via opencodex → ")),
+      && !hasOcxRoutedAuthorship(m),
   ) ?? null;
 }
 
@@ -325,7 +332,7 @@ export function findSupportedNativeTemplate(catalog: RawCatalog | null): RawEntr
       && "base_instructions" in m
       && m.opencodex_catalog_kind !== CODEX_NATIVE_ALIAS_CATALOG_KIND
       && m.owned_by !== COMBO_NAMESPACE
-      && !(typeof m.description === "string" && m.description.startsWith("Routed via opencodex → ")),
+      && !hasOcxRoutedAuthorship(m),
   ) ?? null;
 }
 
@@ -925,7 +932,9 @@ export function readCatalogBackup(catalogPath: string): RawCatalog | null {
 
 export function catalogHasRoutedEntries(catalog: RawCatalog | null): boolean {
   return (catalog?.models ?? []).some(m => typeof m.slug === "string"
-    && (m.slug.includes("/") || m.opencodex_catalog_kind === CODEX_NATIVE_ALIAS_CATALOG_KIND));
+    && (m.slug.includes("/")
+      || m.opencodex_catalog_kind === CODEX_NATIVE_ALIAS_CATALOG_KIND
+      || hasComboRoutedOriginMarker(m)));
 }
 
 export function writePristineCatalogBackup(backupPath: string, catalogPath: string, catalog: RawCatalog): void {

package/src/codex/catalog/retained-sync.ts

@@ -60,7 +60,7 @@ import { isMultiAgentV2Enabled } from "../features";
 import { clampCatalogModelsToCodexSupport } from "./effort";
 import { suppressedSyntheticMaxCatalogSlugs } from "./model-hints";
 import { filterCatalogVisibleModels, gatherRoutedModels, type CatalogGatherProviderModelOutcome } from "./provider-fetch";
-import { dedupeCatalogEntriesBySlug, enforceCatalogSlugUniqueness, exactComboCatalogSlugs, type ComboCatalogOmission } from "./aggregation";
+import { comboCatalogDescriptions, dedupeCatalogEntriesBySlug, enforceCatalogSlugUniqueness, exactComboCatalogSlugs, type ComboCatalogOmission } from "./aggregation";
 import {
   withCatalogWriteSerialization,
   type CatalogWritePermit,
@@ -530,6 +530,7 @@ function writeRetainedCatalogSync({
     multiAgentV2Enabled,
     keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
     exactComboSlugs,
+    comboDescriptions: comboCatalogDescriptions(config),
     hasPhysicalComboProvider,
     includeNativeOpenAi,
     accountBoundEntries,

package/src/codex/catalog/routed-gather.ts

@@ -102,7 +102,7 @@ import type {
   CatalogTrustedOpenAiApiPolicySnapshot,
 } from "../convergence-types";
 import type { CatalogGatherProviderAuthOutcome, CatalogGatherProviderModelOutcome, GatherFlightCapture, ModelsAuthResolverFactory } from "./gather-capture";
-import { applyProviderConfigHints, configuredAutoCompactTokenLimit, configuredMaxInputTokens, configuredReasoningSummarySupport, modelInputModalities, routedMaxOutputTokens, withVisionSidecarInput } from "./model-hints";
+import { applyProviderConfigHints, configuredAutoCompactTokenLimit, configuredMaxInputTokens, configuredModelDisplayName, configuredReasoningSummarySupport, modelInputModalities, routedMaxOutputTokens, withVisionSidecarInput } from "./model-hints";
 import { resolveComboCatalogMember } from "./combo-member";
 import { captureGatherFlight, captureTrustedOpenAiApiPolicy, gatherFlightKey, keyedGatherBytesIdentity, withCanonicalOpenAiForwardAuthDefault } from "./gather-capture";
 import { fetchProviderModelsWithAuth, observedModelsAuthResolver, refreshingModelsAuthResolver } from "./provider-models";
@@ -886,10 +886,12 @@ function augmentRoutedModelsWithCapturedOpenAiApiRows(
       undefined,
       metadataConfigDir,
     );
+    const displayName = configuredModelDisplayName(configured, id);
     return {
       provider: OPENAI_API_PROVIDER_ID,
       id,
       owned_by: OPENAI_API_PROVIDER_ID,
+      ...(displayName ? { displayName } : {}),
       ...(contextWindow ? { contextWindow } : {}),
       ...(maxInputTokens ? { maxInputTokens } : {}),
       ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),

package/src/codex/catalog/routed-removal.ts

@@ -4,6 +4,7 @@ import type { OcxConfig } from "../../types";
 import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
 import { isOcxAuthoredRoutedEntry } from "./build-entries";
 import { isNativeAliasCatalogEntry } from "./metadata";
+import { hasOcxRoutedAuthorship } from "./ownership";
 import type { RawCatalog, RawEntry } from "./parsing";
 
 /**
@@ -25,10 +26,9 @@ function routedNamespace(entry: RawEntry): string | null {
   if (trustedAccountBoundNativeCatalogSlug(entry) !== undefined) return null;
   if (isNativeAliasCatalogEntry(entry)) return COMBO_NAMESPACE;
   // Combo aliases may be bare or use an unrelated provider namespace. Ownership selects the
-  // combo namespace only with the same generated-description authorship signal as routed rows.
-  if (entry.owned_by === COMBO_NAMESPACE
-    && typeof entry.description === "string"
-    && entry.description.startsWith("Routed via opencodex → ")) return COMBO_NAMESPACE;
+  // combo namespace only with the same authorship signal as routed rows (generated description or
+  // the #7229 marker a custom combo description carries).
+  if (entry.owned_by === COMBO_NAMESPACE && hasOcxRoutedAuthorship(entry)) return COMBO_NAMESPACE;
   // Foreign rows (Cursor, user tooling) are never removed by the provider rule.
   if (!isOcxAuthoredRoutedEntry(entry)) return null;
   return entry.slug.slice(0, entry.slug.indexOf("/"));

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