@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/codex/prompt-lock.ts

@@ -0,0 +1,143 @@
+/**
+ * prompt-lock.ts — advisory cross-process lock for prompt-layer mutations.
+ *
+ * An in-process mutex only serialises browser tabs behind one service. A CLI
+ * invocation, a second service, or a stale process can all reach the same
+ * files, so the lock lives on disk.
+ *
+ * STALE TAKEOVER IS A RENAME, NOT AN UNLINK. Naive breaking is racy: A judges
+ * the lock stale, B removes it and acquires its own, then A unlinks *B's live
+ * lock* and both proceed. Unlinking a path you did not verify is the bug. Here
+ * the contender renames the observed stale lock to a token-quarantined name —
+ * an atomic operation exactly one contender can win — and only the winner
+ * creates the real lock.
+ *
+ * RELEASE ONLY DELETES A LOCK WHOSE TOKEN IS STILL OURS. A mismatch means we
+ * were superseded, and deleting it would hand the critical section to two
+ * writers at once.
+ *
+ * This does NOT cover Codex, which knows nothing about our lock. That residual
+ * is handled by the per-target byte checks in the write path, and the rename
+ * window itself is documented as irreducible from user space.
+ */
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+
+const FILE_MODE = 0o600;
+
+/** A lock younger than this is respected even if its pid looks gone. */
+export const STALE_AFTER_MS = 10_000;
+
+export interface LockRecord {
+  token: string;
+  pid: number;
+  acquiredAt: number;
+}
+
+export interface LockHandle {
+  path: string;
+  token: string;
+}
+
+export type AcquireResult =
+  | { ok: true; handle: LockHandle }
+  | { ok: false; error: "locked" };
+
+export interface LockDeps {
+  /** Injectable so tests can simulate a live or dead owner. */
+  isProcessAlive: (pid: number) => boolean;
+  now: () => number;
+}
+
+const defaultDeps: LockDeps = {
+  isProcessAlive: pid => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM means it exists but belongs to another user.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  },
+  now: () => Date.now(),
+};
+
+function readRecord(path: string): LockRecord | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as LockRecord;
+    if (typeof parsed?.token !== "string" || typeof parsed?.pid !== "number") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** True when the holder is gone AND the lock is older than the grace window. */
+function isStale(record: LockRecord | null, deps: LockDeps): boolean {
+  if (record === null) return true; // unparseable: treat as debris
+  if (deps.isProcessAlive(record.pid)) return false;
+  return deps.now() - record.acquiredAt > STALE_AFTER_MS;
+}
+
+/**
+ * One attempt. The caller decides whether to retry — a loser must go back to
+ * re-reading the lock rather than assuming its quarantine still applies.
+ */
+export function tryAcquire(path: string, deps: LockDeps = defaultDeps): AcquireResult {
+  const token = randomBytes(8).toString("hex");
+  const record: LockRecord = { token, pid: process.pid, acquiredAt: deps.now() };
+  const body = JSON.stringify(record);
+
+  try {
+    writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+    return { ok: true, handle: { path, token } };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+
+  if (!isStale(readRecord(path), deps)) return { ok: false, error: "locked" };
+
+  // Quarantine by rename: atomic, and exactly one contender wins it.
+  const quarantine = `${path}.stale-${token}`;
+  try {
+    renameSync(path, quarantine);
+  } catch {
+    // Someone else won the rename, or the owner released between our checks.
+    // Either way we do NOT touch the path — retry from the top.
+    return { ok: false, error: "locked" };
+  }
+
+  try {
+    writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+  } catch (error) {
+    // A successor acquired the real lock between our rename and this create.
+    // Its lock is live and is not ours to remove.
+    try { unlinkSync(quarantine); } catch { /* debris */ }
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return { ok: false, error: "locked" };
+    throw error;
+  }
+
+  try { unlinkSync(quarantine); } catch { /* debris */ }
+  return { ok: true, handle: { path, token } };
+}
+
+/**
+ * Release. Deletes nothing unless the on-disk token is still ours; returns false
+ * when we were superseded, which the caller surfaces as `write_superseded`.
+ */
+export function release(handle: LockHandle): boolean {
+  const record = readRecord(handle.path);
+  if (record === null || record.token !== handle.token) return false;
+  try {
+    unlinkSync(handle.path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True when the on-disk lock is still the one this handle acquired. */
+export function stillHeld(handle: LockHandle): boolean {
+  if (!existsSync(handle.path)) return false;
+  return readRecord(handle.path)?.token === handle.token;
+}

package/src/codex/quota-rejection.ts

@@ -0,0 +1,224 @@
+import { readBoundedResponseBody } from "../lib/bounded-body";
+
+const RESET_ELIGIBLE_CODE_VALUES = [
+  "usage_limit_exceeded",
+  "insufficient_quota",
+] as const;
+
+export type CodexResetEligibleExhaustionCode =
+  (typeof RESET_ELIGIBLE_CODE_VALUES)[number];
+
+export type CodexPreStreamRejectionKind =
+  | "reset-eligible-exhaustion"
+  | "generic-rate-limit"
+  | "unverified-billing-or-quota"
+  | "transient-server-error"
+  | "authentication-error"
+  | "permission-error"
+  | "other";
+
+export interface CodexPreStreamRejection {
+  kind: CodexPreStreamRejectionKind;
+  status: number;
+  alternateRetryEligible: boolean;
+  resetCreditEligible: boolean;
+  semanticCode?: CodexResetEligibleExhaustionCode;
+}
+
+const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);
+
+const TRANSIENT_SERVER_STATUSES = new Set([500, 502, 503, 504, 520, 521, 522]);
+const JSON_NUMBER_PATTERN = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+
+function rejection(
+  status: number,
+  kind: CodexPreStreamRejectionKind,
+  options: {
+    alternateRetryEligible?: boolean;
+    semanticCode?: CodexResetEligibleExhaustionCode;
+  } = {},
+): CodexPreStreamRejection {
+  return {
+    kind,
+    status,
+    alternateRetryEligible: options.alternateRetryEligible === true,
+    resetCreditEligible: options.semanticCode !== undefined,
+    ...(options.semanticCode ? { semanticCode: options.semanticCode } : {}),
+  };
+}
+
+function hasOwnField(container: Record<string, unknown>, field: string): boolean {
+  return Object.prototype.hasOwnProperty.call(container, field);
+}
+
+type JsonScanResult = {
+  next: number;
+  duplicate: boolean;
+};
+
+function skipJsonWhitespace(text: string, index: number): number {
+  while (index < text.length && /[\t\n\r ]/.test(text[index] ?? "")) index += 1;
+  return index;
+}
+
+function scanJsonStringEnd(text: string, index: number): number {
+  if (text[index] !== '"') throw new SyntaxError("expected JSON string");
+  for (let cursor = index + 1; cursor < text.length; cursor += 1) {
+    const char = text[cursor];
+    if (char === '"') return cursor + 1;
+    if (char === "\\") cursor += 1;
+  }
+  throw new SyntaxError("unterminated JSON string");
+}
+
+function scanJsonValue(text: string, index: number): JsonScanResult {
+  const start = skipJsonWhitespace(text, index);
+  if (text[start] === "{") return scanJsonObject(text, start);
+  if (text[start] === "[") return scanJsonArray(text, start);
+  if (text[start] === '"') return { next: scanJsonStringEnd(text, start), duplicate: false };
+
+  for (const literal of ["true", "false", "null"]) {
+    if (text.startsWith(literal, start)) {
+      return { next: start + literal.length, duplicate: false };
+    }
+  }
+  JSON_NUMBER_PATTERN.lastIndex = start;
+  const number = JSON_NUMBER_PATTERN.exec(text);
+  if (!number) throw new SyntaxError("expected JSON value");
+  return { next: start + number[0].length, duplicate: false };
+}
+
+function scanJsonObject(text: string, index: number): JsonScanResult {
+  const keys = new Set<string>();
+  let duplicate = false;
+  let cursor = skipJsonWhitespace(text, index + 1);
+  if (text[cursor] === "}") return { next: cursor + 1, duplicate: false };
+
+  while (cursor < text.length) {
+    const keyEnd = scanJsonStringEnd(text, cursor);
+    const key = JSON.parse(text.slice(cursor, keyEnd)) as unknown;
+    if (typeof key !== "string") throw new SyntaxError("invalid JSON object key");
+    if (keys.has(key)) duplicate = true;
+    keys.add(key);
+
+    cursor = skipJsonWhitespace(text, keyEnd);
+    if (text[cursor] !== ":") throw new SyntaxError("expected JSON object colon");
+    const value = scanJsonValue(text, cursor + 1);
+    duplicate ||= value.duplicate;
+    cursor = skipJsonWhitespace(text, value.next);
+    if (text[cursor] === "}") return { next: cursor + 1, duplicate };
+    if (text[cursor] !== ",") throw new SyntaxError("expected JSON object separator");
+    cursor = skipJsonWhitespace(text, cursor + 1);
+  }
+  throw new SyntaxError("unterminated JSON object");
+}
+
+function scanJsonArray(text: string, index: number): JsonScanResult {
+  let duplicate = false;
+  let cursor = skipJsonWhitespace(text, index + 1);
+  if (text[cursor] === "]") return { next: cursor + 1, duplicate: false };
+
+  while (cursor < text.length) {
+    const value = scanJsonValue(text, cursor);
+    duplicate ||= value.duplicate;
+    cursor = skipJsonWhitespace(text, value.next);
+    if (text[cursor] === "]") return { next: cursor + 1, duplicate };
+    if (text[cursor] !== ",") throw new SyntaxError("expected JSON array separator");
+    cursor = skipJsonWhitespace(text, cursor + 1);
+  }
+  throw new SyntaxError("unterminated JSON array");
+}
+
+function isUnsafeJsonDocument(text: string): boolean {
+  try {
+    const result = scanJsonValue(text, 0);
+    return result.duplicate || skipJsonWhitespace(text, result.next) !== text.length;
+  } catch {
+    // Scanner disagreement is untrusted input, just like JSON.parse failure.
+    return true;
+  }
+}
+
+function exactResetEligibleCode(
+  container: Record<string, unknown>,
+): CodexResetEligibleExhaustionCode | undefined {
+  const hasCode = hasOwnField(container, "code");
+  const hasType = hasOwnField(container, "type");
+  if (!hasCode && !hasType) return undefined;
+
+  const code = hasCode ? container.code : undefined;
+  const type = hasType ? container.type : undefined;
+  if ((hasCode && typeof code !== "string") || (hasType && typeof type !== "string")) {
+    return undefined;
+  }
+  if (hasCode && hasType && code !== type) return undefined;
+
+  const value = hasCode ? code : type;
+  if (typeof value !== "string") return undefined;
+  return RESET_ELIGIBLE_CODES.has(value as CodexResetEligibleExhaustionCode)
+    ? value as CodexResetEligibleExhaustionCode
+    : undefined;
+}
+
+function structuredResetEligibleCode(payload: unknown): CodexResetEligibleExhaustionCode | undefined {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const root = payload as Record<string, unknown>;
+  const hasRootDiscriminator = hasOwnField(root, "code") || hasOwnField(root, "type");
+
+  if (!hasOwnField(root, "error")) return exactResetEligibleCode(root);
+  if (hasRootDiscriminator) return undefined;
+
+  const nested = root.error;
+  if (!nested || typeof nested !== "object" || Array.isArray(nested)) return undefined;
+  return exactResetEligibleCode(nested as Record<string, unknown>);
+}
+
+async function resetEligibleCodeFromResponse(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<CodexResetEligibleExhaustionCode | undefined> {
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    const payload = JSON.parse(body.text) as unknown;
+    // JSON.parse silently keeps the last duplicate key, making contradictory
+    // payloads order-dependent. Reject any duplicate at any object depth.
+    if (isUnsafeJsonDocument(body.text)) return undefined;
+    return structuredResetEligibleCode(payload);
+  } catch {
+    // Classification must fail closed. A malformed, oversized, consumed, or
+    // cancelled body cannot authorize an irreversible reset-credit operation.
+    return undefined;
+  }
+}
+
+/**
+ * Classify an upstream Codex rejection before any response event is exposed.
+ *
+ * Only an exact structured exhaustion code on HTTP 429/402 is reset-eligible.
+ * Status alone and message text are intentionally insufficient. The broad
+ * alternate-account retry remains eligible for 429/402 to preserve #584.
+ */
+export async function classifyCodexPreStreamRejection(
+  response: Response,
+  options: { signal?: AbortSignal } = {},
+): Promise<CodexPreStreamRejection> {
+  const status = response.status;
+  if (status === 401) return rejection(status, "authentication-error");
+  if (status === 403) return rejection(status, "permission-error");
+  if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error");
+  if (status !== 429 && status !== 402) return rejection(status, "other");
+
+  const semanticCode = await resetEligibleCodeFromResponse(response, options.signal);
+  if (semanticCode) {
+    return rejection(status, "reset-eligible-exhaustion", {
+      alternateRetryEligible: true,
+      semanticCode,
+    });
+  }
+  return rejection(
+    status,
+    status === 429 ? "generic-rate-limit" : "unverified-billing-or-quota",
+    { alternateRetryEligible: true },
+  );
+}

package/src/codex/quota.ts

@@ -9,6 +9,14 @@ export type StoredAccountQuota = {
   weeklyResetAt?: number;
   monthlyResetAt?: number;
   resetCredits?: number;
+  /**
+   * True when `monthlyPercent` came from an explicitly-monthly PRIMARY window —
+   * i.e. it is the account's governing quota reading, not a supplementary
+   * tertiary window. Tertiary-only monthly data lands in the same field but says
+   * nothing about the weekly quota that actually gates a non-Go/Free account,
+   * so recovery must be able to tell the two apart (#967 audit).
+   */
+  monthlyIsPrimaryWindow?: boolean;
   updatedAt: number;
 };
 
@@ -67,8 +75,7 @@ export function isCodexQuotaExhausted(
   plan?: string | null,
 ): boolean {
   if (!quota) return false;
-  const normalizedPlan = plan?.trim().toLowerCase();
-  const values = normalizedPlan === "go" || normalizedPlan === "free"
+  const values = codexQuotaWindowForPlan(plan) === "monthly"
     ? [quota.monthlyPercent]
     : [quota.weeklyPercent, quota.monthlyPercent];
   return values.some(value => typeof value === "number"
@@ -76,6 +83,58 @@ export function isCodexQuotaExhausted(
     && value >= CODEX_EXHAUSTED_USAGE_PERCENT);
 }
 
+/**
+ * Which usage window a plan reports in. This is the SINGLE rule shared by quota
+ * parsing, exhaustion, and recovery — they must not diverge.
+ *
+ * An allowlist of "known" plans was tried here and was wrong: the upstream model
+ * snapshot alone carries 21 distinct plan strings (`edu_plus`, `finserv`, `k12`,
+ * `quorum`, `self_serve_business_usage_based`, ...), and `CodexAccount.plan` is an
+ * unrestricted string, so any list is a list of the plans someone remembered.
+ * Twelve real plans would have been refused recovery and stayed cooled forever —
+ * the very defect this unit exists to fix, reintroduced as a typo-shaped hole.
+ *
+ * The honest rule is the parser's own: Go and Free report a 30-day window,
+ * everything else (including an absent plan) reports weekly. Recovery reads the
+ * window the parser actually wrote rather than second-guessing it.
+ */
+export function codexQuotaWindowForPlan(plan?: string | null): "monthly" | "weekly" {
+  const normalized = plan?.trim().toLowerCase();
+  return normalized === "go" || normalized === "free" ? "monthly" : "weekly";
+}
+
+export function isCompleteCodexQuotaRecoverySnapshot(
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow"> | null,
+  plan?: string | null,
+): boolean {
+  if (!quota || isCodexQuotaExhausted(quota, plan)) return false;
+  // Recovery still fails closed on MISSING EVIDENCE — a credits-only or windowless payload
+  // carries no usage reading at all and must never clear a cooldown. What it does not do is
+  // fail closed on an unfamiliar plan NAME, which only ever meant "cooled forever".
+  //
+  // The parser classifies windows by DURATION, not by plan name: a Team response whose
+  // primary window is explicitly monthly parses to monthlyPercent only (no secondary
+  // window exists), so requiring weeklyPercent because the plan is not go/free would
+  // strand exactly those accounts until their predicted expiry. Accept whichever window(s)
+  // the parser actually wrote; Go/Free never carry a weekly value, so monthly-only is
+  // required there.
+  //
+  // Audit correction: "the parser wrote monthlyPercent" is NOT by itself evidence for a
+  // weekly-quota plan. A tertiary-only response also writes monthlyPercent, and it says
+  // nothing about the weekly quota that actually gates a Team/Plus account — accepting it
+  // would clear the cooldown on a reading of a different window. Only an explicitly-monthly
+  // PRIMARY window is the governing reading, which is what `monthlyIsPrimaryWindow` records.
+  if (codexQuotaWindowForPlan(plan) === "monthly") {
+    return finitePercent(quota.monthlyPercent);
+  }
+  if (finitePercent(quota.weeklyPercent)) return true;
+  return quota.monthlyIsPrimaryWindow === true && finitePercent(quota.monthlyPercent);
+}
+
+function finitePercent(value: number | undefined): boolean {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
 export function normalizeUsagePercent(value: unknown): number | undefined {
   const numeric = typeof value === "number"
     ? value
@@ -147,6 +206,7 @@ export function setAccountQuotaFromParsed(
     if (existing?.weeklyResetAt !== undefined) next.weeklyResetAt = existing.weeklyResetAt;
     if (existing?.monthlyPercent !== undefined) next.monthlyPercent = existing.monthlyPercent;
     if (existing?.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
+    if (existing?.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
     next.resetCredits = quota.resetCredits;
     accountQuota.set(accountId, next);
     schedulePersistAccountQuotas();
@@ -166,9 +226,15 @@ export function setAccountQuotaFromParsed(
   if (snapshotHasMonthly(quota)) {
     if (quota.monthlyPercent !== undefined) next.monthlyPercent = quota.monthlyPercent;
     if (quota.monthlyResetAt !== undefined) next.monthlyResetAt = quota.monthlyResetAt;
+    // Carry the provenance with the value it describes. Recovery reads `freshQuota` directly,
+    // so this is not on its path today — but a cached snapshot that kept `monthlyPercent`
+    // while silently dropping `monthlyIsPrimaryWindow` would look like tertiary-only data to
+    // any future reader, and that failure would be invisible.
+    if (quota.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
   } else if (snapshotHasWeekly(quota) && existing?.monthlyPercent !== undefined) {
     next.monthlyPercent = existing.monthlyPercent;
     if (existing.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
+    if (existing.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
   }
 
   if (quota.resetCredits !== undefined) next.resetCredits = quota.resetCredits;
@@ -201,6 +267,10 @@ export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQ
     if (primaryPercent !== undefined) {
       quota.monthlyPercent = primaryPercent;
       if (primaryResetAt !== undefined) quota.monthlyResetAt = primaryResetAt;
+      // Same provenance rule as parseUsageQuota(): this monthly value is the governing
+      // primary window, not a supplementary tertiary one. Not on the recovery path today,
+      // but the two parsers must agree on what a bare monthlyPercent means.
+      quota.monthlyIsPrimaryWindow = true;
     }
     if (secondaryPercent !== undefined) {
       quota.weeklyPercent = secondaryPercent;
@@ -253,6 +323,11 @@ export function updateAccountQuota(
   const quota: StoredAccountQuota = {
     ...(existing?.weeklyPercent !== undefined ? { weeklyPercent: existing.weeklyPercent } : {}),
     ...(existing?.monthlyPercent !== undefined ? { monthlyPercent: existing.monthlyPercent } : {}),
+    // Carry provenance with the value it describes. Dropping it here would downgrade a proven
+    // explicit-primary reading to "unproven" on the next unrelated weekly update.
+    ...(existing?.monthlyPercent !== undefined && existing.monthlyIsPrimaryWindow === true
+      ? { monthlyIsPrimaryWindow: true }
+      : {}),
     ...(existing?.weeklyResetAt !== undefined ? { weeklyResetAt: existing.weeklyResetAt } : {}),
     ...(existing?.monthlyResetAt !== undefined ? { monthlyResetAt: existing.monthlyResetAt } : {}),
     ...(existing?.resetCredits !== undefined ? { resetCredits: existing.resetCredits } : {}),
@@ -268,6 +343,10 @@ export function updateAccountQuota(
   if (nextMonthly !== undefined) {
     quota.monthlyPercent = nextMonthly;
     if (nextMonthlyResetAt !== undefined) quota.monthlyResetAt = nextMonthlyResetAt;
+    // A caller-supplied monthly value arrives without window provenance, so it REPLACES the
+    // proven reading and must not inherit its flag — otherwise an unproven number would be
+    // treated as governing evidence.
+    delete quota.monthlyIsPrimaryWindow;
   }
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
@@ -367,7 +446,7 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   }
 
   const quota: Omit<StoredAccountQuota, "updatedAt"> = {};
-  const thirtyDayOnly = data.plan_type?.trim().toLowerCase() === "go" || data.plan_type?.trim().toLowerCase() === "free";
+  const thirtyDayOnly = codexQuotaWindowForPlan(data.plan_type) === "monthly";
   const primaryWindow = data.rate_limit.primary_window;
   const secondaryWindow = data.rate_limit.secondary_window;
   const tertiaryWindow = data.rate_limit.tertiary_window;
@@ -404,6 +483,10 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
   if (!thirtyDayOnly && monthlyPercent !== undefined) {
     quota.monthlyPercent = monthlyPercent;
     if (monthlyResetAt !== undefined) quota.monthlyResetAt = monthlyResetAt;
+    // Record WHERE this reading came from. Only an explicitly-monthly primary window is the
+    // account's governing quota; a tertiary window lands in the same field but describes a
+    // different period, so recovery must not treat the two as interchangeable.
+    if (primaryIsMonthly && primaryPercent !== undefined) quota.monthlyIsPrimaryWindow = true;
   }
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;