fix codex usage-limit recovery copy

amknight · amknight · commit b7a7301ef322 · 2026-05-25T13:45:40.000+10:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@ Docs: https://docs.openclaw.ai
 - Tests: normalize bundled plugin lifecycle probe paths and state-root lookup so native Windows release sweeps accept valid packaged plugin installs.
 - Config: keep benign legacy metadata write anomalies out of default doctor and config command output while preserving explicit anomaly logging for diagnostics.
 - Codex: log when implicit app-server `never` approvals are promoted for OpenClaw tool policy, including whether the trigger was a `before_tool_call` hook or trusted tool policy.
+- Codex harness: make subscription usage-limit errors without reset times explain that OpenClaw cannot determine the reset and point users to wait until Codex is available, use another Codex account, or switch to another configured model/provider. Thanks @amknight.
 - Google Vertex: support production ADC modes such as Workload Identity Federation, service-account credentials, and metadata-server ADC for the native Vertex transport. (#83971) Thanks @damianFelixPago.
 - Telegram: route normal `[telegram][diag]` polling diagnostics through `runtime.log` while keeping non-diag warnings and persistence failures on `runtime.error`, so healthy polling startup no longer looks like an error. Fixes #82957. (#82958) Thanks @galiniliev.
 
diff --git a/extensions/codex/src/app-server/event-projector.test.ts b/extensions/codex/src/app-server/event-projector.test.ts
@@ -718,7 +718,7 @@ describe("CodexAppServerEventProjector", () => {
 
     expect(result.promptError).toContain("You've reached your Codex subscription usage limit.");
     expect(result.promptError).toContain("Next reset in");
-    expect(result.promptError).toContain("Run /codex account");
+    expect(result.promptError).toContain("Wait until the reset time");
     expect(result.promptErrorSource).toBe("prompt");
   });
 
diff --git a/extensions/codex/src/app-server/rate-limits.test.ts b/extensions/codex/src/app-server/rate-limits.test.ts
@@ -7,6 +7,30 @@ import {
 } from "./rate-limits.js";
 
 describe("formatCodexUsageLimitErrorMessage", () => {
+  it("gives actionable guidance when Codex omits reset details", () => {
+    const message = formatCodexUsageLimitErrorMessage({
+      message: "You've reached your usage limit.",
+      codexErrorInfo: "usageLimitExceeded",
+      rateLimits: {
+        rateLimits: {
+          limitId: "codex",
+          primary: { usedPercent: 100, windowDurationMins: 10_080, resetsAt: null },
+          secondary: null,
+        },
+      },
+      nowMs: Date.UTC(2026, 4, 10, 23, 0, 0),
+    });
+
+    expect(message).toContain("You've reached your Codex subscription usage limit.");
+    expect(message).toContain("Your weekly Codex usage limit is reached.");
+    expect(message).toContain("OpenClaw could not determine a reset time from Codex.");
+    expect(message).toContain("Wait until Codex becomes available");
+    expect(message).toContain("use another Codex account if available");
+    expect(message).toContain("switch to another configured model/provider");
+    expect(message).not.toContain("Codex did not return a reset time");
+    expect(message).not.toContain("/codex account");
+  });
+
   it("preserves Codex retry hints when structured reset windows are absent", () => {
     const message = formatCodexUsageLimitErrorMessage({
       message:
@@ -24,6 +48,7 @@ describe("formatCodexUsageLimitErrorMessage", () => {
 
     expect(message).toContain("You've reached your Codex subscription usage limit.");
     expect(message).toContain("Codex says to try again at May 11th, 2026 9:00 AM.");
+    expect(message).toContain("Wait until the retry time");
     expect(message).not.toContain("Codex did not return a reset time");
   });
 
@@ -42,10 +67,67 @@ describe("formatCodexUsageLimitErrorMessage", () => {
     });
 
     expect(message).toContain("Next reset in 1 hour, ");
+    expect(message).toContain("Wait until the reset time");
     expect(message).toMatch(/\b[A-Z][a-z]{2} \d{1,2}(?:, \d{4})? at \d{1,2}:\d{2} [AP]M\b/u);
     expect(message).not.toMatch(/\(\d{4}-\d{2}-\d{2}T/u);
     expect(message).not.toContain("Codex did not return a reset time");
   });
+
+  it("uses the blocking reset when multiple Codex windows are exhausted", () => {
+    const nowMs = 1_700_000_000_000;
+    const nowSeconds = nowMs / 1000;
+    const message = formatCodexUsageLimitErrorMessage({
+      message: "You've reached your usage limit.",
+      codexErrorInfo: "usageLimitExceeded",
+      rateLimits: {
+        rateLimits: {
+          limitId: "codex",
+          primary: { usedPercent: 100, windowDurationMins: 300, resetsAt: nowSeconds + 3600 },
+          secondary: {
+            usedPercent: 100,
+            windowDurationMins: 10_080,
+            resetsAt: nowSeconds + 24 * 3600,
+          },
+        },
+      },
+      nowMs,
+    });
+
+    expect(message).toContain("Next reset in 1 day");
+    expect(message).not.toContain("Next reset in 1 hour");
+    expect(message).toContain("Wait until the reset time");
+  });
+
+  it("does not use sibling bucket resets when the blocked Codex bucket omits a reset", () => {
+    const nowMs = 1_700_000_000_000;
+    const nowSeconds = nowMs / 1000;
+    const message = formatCodexUsageLimitErrorMessage({
+      message: "You've reached your usage limit.",
+      codexErrorInfo: "usageLimitExceeded",
+      rateLimits: {
+        rateLimitsByLimitId: {
+          codex: {
+            limitId: "codex",
+            limitName: "Codex",
+            primary: { usedPercent: 100, windowDurationMins: 300, resetsAt: null },
+            secondary: null,
+          },
+          "gpt-5.3-codex-spark": {
+            limitId: "gpt-5.3-codex-spark",
+            limitName: "GPT 5.3 Codex Spark",
+            primary: { usedPercent: 0, windowDurationMins: 300, resetsAt: nowSeconds + 3600 },
+            secondary: null,
+          },
+        },
+      },
+      nowMs,
+    });
+
+    expect(message).toContain("OpenClaw could not determine a reset time from Codex.");
+    expect(message).toContain("Wait until Codex becomes available");
+    expect(message).not.toContain("Next reset");
+    expect(message).not.toContain("1 hour");
+  });
 });
 
 describe("Codex rate limit blocking resets", () => {
diff --git a/extensions/codex/src/app-server/rate-limits.ts b/extensions/codex/src/app-server/rate-limits.ts
@@ -41,19 +41,31 @@ export function formatCodexUsageLimitErrorMessage(params: {
     return undefined;
   }
   const nowMs = params.nowMs ?? Date.now();
-  const nextReset = selectNextRateLimitReset(params.rateLimits, nowMs);
+  const usageSummary = summarizeCodexAccountUsage(params.rateLimits, nowMs);
+  const blockingReset = selectBlockingRateLimitReset(params.rateLimits, nowMs);
+  const nextReset =
+    blockingReset ??
+    (usageSummary?.blocked ? undefined : selectNextRateLimitReset(params.rateLimits, nowMs));
   const parts = ["You've reached your Codex subscription usage limit."];
+  let recoveryAction = "Wait until Codex becomes available";
   if (nextReset) {
     parts.push(`Next reset ${formatResetTime(nextReset.resetsAtMs, nowMs)}.`);
+    recoveryAction = "Wait until the reset time";
   } else {
     const codexRetryHint = extractCodexRetryHint(message);
     if (codexRetryHint) {
       parts.push(`Codex says to try again ${codexRetryHint}.`);
+      recoveryAction = "Wait until the retry time";
     } else {
-      parts.push("Codex did not return a reset time for this limit.");
+      if (usageSummary?.blockingPeriod && usageSummary.blockingReason) {
+        parts.push(`Your ${usageSummary.blockingReason}.`);
+      }
+      parts.push("OpenClaw could not determine a reset time from Codex.");
     }
   }
-  parts.push("Run /codex account for current usage details.");
+  parts.push(
+    `${recoveryAction}, use another Codex account if available, or switch to another configured model/provider.`,
+  );
   return parts.join(" ");
 }
 
@@ -126,10 +138,12 @@ export function summarizeCodexAccountUsage(
   const blockedSnapshots = snapshots.filter(snapshotHasLimitBlock);
   const blockingSnapshot =
     blockedSnapshots.find(isCodexLimitSnapshot) ?? blockedSnapshots[0] ?? undefined;
-  const blockingReset = blockingSnapshot
-    ? selectSnapshotBlockingReset(blockingSnapshot, nowMs)
+  const blockingWindow = blockingSnapshot
+    ? selectSnapshotBlockingWindow(blockingSnapshot, nowMs)
     : undefined;
-  const blockingPeriod = formatBlockingLimitPeriod(blockingReset?.windowDurationMins);
+  const blockingReset =
+    blockingWindow && blockingWindow.resetsAtMs > nowMs ? blockingWindow : undefined;
+  const blockingPeriod = formatBlockingLimitPeriod(blockingWindow?.windowDurationMins);
   const blockedUntilText = blockingReset
     ? formatAccountResetTime(blockingReset.resetsAtMs, nowMs)
     : undefined;
@@ -426,6 +440,22 @@ function selectSnapshotBlockingReset(
   return candidates.toSorted(resetSort)[0];
 }
 
+function selectSnapshotBlockingWindow(
+  snapshot: JsonObject,
+  nowMs: number,
+): RateLimitReset | undefined {
+  const resetWindow = selectSnapshotBlockingReset(snapshot, nowMs);
+  if (resetWindow) {
+    return resetWindow;
+  }
+  const exhaustedWindows = readWindowEntries(snapshot)
+    .map((entry) => entry.window)
+    .filter((window) => window.usedPercent !== undefined && window.usedPercent >= 100);
+  return exhaustedWindows.toSorted(
+    (left, right) => (right.windowDurationMins ?? 0) - (left.windowDurationMins ?? 0),
+  )[0];
+}
+
 function readWindowEntries(snapshot: JsonObject): RateLimitWindowEntry[] {
   return LIMIT_WINDOW_KEYS.flatMap((key) => {
     const window = readRateLimitWindow(snapshot, key);
