@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/codex/history-job.ts

@@ -25,7 +25,7 @@ import type {
   HistoryWorkerResult,
 } from "./history-worker";
 import { historyBackupPathFor } from "./history-provider";
-import type { CodexHistoryFailureReason } from "./history-provider";
+import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
 import { getCodexHome } from "./paths";
 
 /** Where Codex keeps its resume history, and the manifest that shadows it. */
@@ -59,6 +59,47 @@ export function resolveCodexHistoryJobTarget(): {
 
 /** How long a history unit may run before the parent stops waiting on it. */
 const WORKER_TIMEOUT_MS = 30_000;
+/** A terminated Worker must close before its caller can cross the file boundary. */
+const WORKER_CLOSE_TIMEOUT_MS = 5_000;
+
+function historyWorkerOsJoinSettleMs(platform = process.platform): number {
+  if (platform === "win32") return 1_500;
+  if (platform === "darwin" || platform === "linux") return 250;
+  return 0;
+}
+
+async function terminateAndJoinHistoryWorker(
+  worker: Worker,
+  closed: Promise<void>,
+): Promise<boolean> {
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const closeTimeout = new Promise<void>(resolve => {
+    timeout = setTimeout(() => {
+      timedOut = true;
+      resolve();
+    }, WORKER_CLOSE_TIMEOUT_MS);
+  });
+
+  try {
+    worker.terminate();
+  } catch {
+    // A Worker that already closed still resolves through the close listener.
+  }
+
+  try {
+    await Promise.race([closed, closeTimeout]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+
+  const settleMs = historyWorkerOsJoinSettleMs();
+  if (settleMs > 0) {
+    await Bun.sleep(0);
+    await Bun.sleep(settleMs);
+  }
+  return !timedOut;
+}
 
 export interface CodexHistoryJobRequest {
   readonly canonicalCodexHome: string;
@@ -69,7 +110,7 @@ export interface CodexHistoryJobRequest {
 }
 
 export type CodexHistoryJobOutcome =
-  | { readonly kind: "converged"; readonly rows: number; readonly files: number }
+  | { readonly kind: "converged"; readonly rows: number; readonly files: number; readonly proof?: CodexHistoryVerifiedNoopProof }
   | { readonly kind: "skipped" }
   | { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly kind: "failed"; readonly reason: "worker-error" | "worker-died" | "timeout";
@@ -92,8 +133,9 @@ export function isPlausibleWorkerResultForTests(
   message: Record<string, unknown>,
   requestId: string,
   jobId: string,
+  target?: Pick<CodexHistoryJobRequest, "canonicalStateDbPath" | "canonicalBackupPath" | "operation">,
 ): boolean {
-  return isPlausibleWorkerResult(message, requestId, jobId);
+  return isPlausibleWorkerResult(message, requestId, jobId, target);
 }
 
 /**
@@ -108,13 +150,30 @@ function isPlausibleWorkerResult(
   message: Record<string, unknown>,
   requestId: string,
   jobId: string,
+  target?: Pick<CodexHistoryJobRequest, "canonicalStateDbPath" | "canonicalBackupPath" | "operation">,
 ): boolean {
   if (message.requestId !== requestId || message.jobId !== jobId) return false;
   switch (message.type) {
     case "done":
-      return (message.outcome === "converged" || message.outcome === "skipped")
+      if (!((message.outcome === "converged" || message.outcome === "skipped")
         && typeof message.rows === "number"
-        && typeof message.files === "number";
+        && typeof message.files === "number")) return false;
+      if (message.proof === undefined) return true;
+      if (!target || !message.proof || typeof message.proof !== "object" || Array.isArray(message.proof)) return false;
+      {
+        const proof = message.proof as Record<string, unknown>;
+        return target.operation === "migrate-openai"
+          && message.outcome === "converged"
+          && message.rows === 0
+          && message.files === 0
+          && proof.kind === "verified-noop"
+          && proof.pendingRows === 0
+          && proof.backupEntries === 0
+          && proof.canonicalStateDbPath === target.canonicalStateDbPath
+          && proof.stateDbPresent === true
+          && proof.canonicalBackupPath === target.canonicalBackupPath
+          && typeof proof.backupPresent === "boolean";
+      }
     case "blocked":
       return message.reason === "busy" || message.reason === "database" || message.reason === "unsafe-path"
         || message.reason === "desired_disabled" || message.reason === "desired_enabled";
@@ -227,7 +286,7 @@ function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutco
   }
   return result.outcome === "skipped"
     ? { kind: "skipped" }
-    : { kind: "converged", rows: result.rows, files: result.files };
+    : { kind: "converged", rows: result.rows, files: result.files, ...(result.proof ? { proof: result.proof } : {}) };
 }
 
 /**
@@ -263,20 +322,23 @@ export async function runCodexHistoryJob(
 
   return new Promise<CodexHistoryJobOutcome>(resolve => {
     let settled = false;
+    let resolveWorkerClosed!: () => void;
+    const workerClosed = new Promise<void>(closed => {
+      resolveWorkerClosed = closed;
+    });
     const finish = (outcome: CodexHistoryJobOutcome) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      // Terminate and join before settling: see the note above.
-      const done = () => resolve(outcome);
-      try {
-        const terminated = worker.terminate() as unknown;
-        if (terminated && typeof (terminated as Promise<unknown>).then === "function") {
-          void (terminated as Promise<unknown>).then(done, done);
-          return;
-        }
-      } catch { /* already gone */ }
-      done();
+      // Bun 1.3.14 returns void from terminate(); resolving on that return lets
+      // the Worker outlive this job and, under `bun test --isolate`, its file.
+      void terminateAndJoinHistoryWorker(worker, workerClosed).then(joined => {
+        resolve(joined
+          ? outcome
+          : { kind: "failed", reason: "worker-died", message: "history_worker_close_timeout" });
+      }, () => {
+        resolve({ kind: "failed", reason: "worker-died", message: "history_worker_join_failed" });
+      });
     };
 
     const timer = setTimeout(() => {
@@ -303,7 +365,7 @@ export async function runCodexHistoryJob(
         died("history_worker_unknown_message_type");
         return;
       }
-      if (!isPlausibleWorkerResult(message, requestId, jobId)) {
+      if (!isPlausibleWorkerResult(message, requestId, jobId, request)) {
         // A recognized type with a missing payload read as `converged` with
         // undefined fields once — success for work that may not have happened.
         died("history_worker_malformed_payload");
@@ -319,7 +381,10 @@ export async function runCodexHistoryJob(
      * and the Worker always closes after posting its result.
      */
     worker.addEventListener("messageerror", () => died("history_worker_unserializable_message"));
-    worker.addEventListener("close", () => died("history_worker_closed_early"));
+    worker.addEventListener("close", () => {
+      resolveWorkerClosed();
+      died("history_worker_closed_early");
+    }, { once: true });
 
     worker.onerror = (event: ErrorEvent) => {
       finish({

package/src/codex/history-migration-guardian.ts

@@ -1,4 +1,4 @@
-import { countPendingOpencodexHistory, migrateHistoryToOpenai } from "./history-provider";
+import { migrateHistoryToOpenai } from "./history-provider";
 import { resolveCodexHistoryJobTarget, runCodexHistoryJob } from "./history-job";
 
 /**
@@ -23,7 +23,6 @@ export interface HistoryMigrationGuardianHandle {
 }
 
 export interface HistoryMigrationGuardianDeps {
-  countFn?: typeof countPendingOpencodexHistory;
   migrateFn?: () => ReturnType<typeof migrateHistoryToOpenai>
     | Promise<ReturnType<typeof migrateHistoryToOpenai>>;
   log?: Pick<Console, "log">;
@@ -43,7 +42,6 @@ function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
 }
 
 export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps = {}): HistoryMigrationGuardianHandle {
-  const countFn = deps.countFn ?? countPendingOpencodexHistory;
   // The default migration goes through the history job, so the guardian's timer
   // thread never performs the transition itself. A background repair that races
   // an apply or a restore is exactly what H exists to order.
@@ -53,7 +51,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
       operation: "migrate-openai",
     });
     return outcome.kind === "converged"
-      ? { rows: outcome.rows, files: outcome.files }
+      ? { rows: outcome.rows, files: outcome.files, verifiedNoop: outcome.proof?.kind === "verified-noop" }
       : { rows: 0, files: 0, failed: true as const };
   });
   const log = deps.log ?? console;
@@ -73,23 +71,18 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
     if (stopped) return;
     ticks++;
     try {
-      const count = countFn();
-      if (!count.failed && count.pendingRows === 0 && count.backupEntries === 0) {
-        stopped = true; // nothing left to migrate — normal steady state, no log noise
-        return;
-      }
-      // Locked probe or pending work: attempt one migration pass.
+      // The worker re-derives state under H on every pass; no pre-lock probe is
+      // allowed to stop or suppress this attempt.
       const result = await migrateFn();
       if (!result.failed) {
         const moved = result.rows + ((result as { ejectedRows?: number }).ejectedRows ?? 0);
         if (moved > 0) {
           log.log(`🩹 history-migration: ${moved} legacy opencodex thread(s) migrated back to openai.`);
         }
-        // A "successful" zero-row migration can also mean the DB does not exist YET while a
-        // backup manifest still holds restore work (fresh reinstall race). Only stop when a
-        // re-count proves nothing is pending; otherwise keep ticking within the budget.
-        const after = countFn();
-        if (moved > 0 || (!after.failed && after.pendingRows === 0 && after.backupEntries === 0)) {
+        // Zero mutations are authoritative only when the worker verified the
+        // exact DB/manifest state while H was held.
+        const verifiedNoop = (result as { verifiedNoop?: boolean }).verifiedNoop === true;
+        if (moved > 0 || verifiedNoop) {
           stopped = true;
           return;
         }
@@ -99,7 +92,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
     }
     if (ticks >= maxTicks) {
       stopped = true;
-      log.log("⚠️ history-migration: Codex history DB stayed locked; legacy threads not yet migrated. Close the Codex app and run 'ocx sync' (or check 'ocx doctor').");
+      log.log("⚠️ history-migration: Could not verify that legacy threads were migrated; the history database may be busy, unavailable, or not yet ready. Run 'ocx sync' (or check 'ocx doctor').");
       return;
     }
     schedule();

package/src/codex/history-provider.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { zstdDecompressSync } from "node:zlib";
 import { Database } from "bun:sqlite";
@@ -200,6 +200,49 @@ interface BackupManifest {
   entries: Record<string, BackupEntry>;
 }
 
+export interface CodexHistoryVerifiedNoopProof {
+  readonly kind: "verified-noop";
+  readonly pendingRows: 0;
+  readonly backupEntries: 0;
+  readonly canonicalStateDbPath: string;
+  readonly stateDbPresent: true;
+  readonly canonicalBackupPath: string;
+  readonly backupPresent: boolean;
+}
+
+export type CodexHistoryNoopSnapshot =
+  | CodexHistoryVerifiedNoopProof
+  | {
+      readonly kind: "work-pending";
+      readonly pendingRows: number;
+      readonly backupEntries: number;
+      readonly canonicalStateDbPath: string;
+      readonly stateDbPresent: boolean;
+      readonly canonicalBackupPath: string;
+      readonly backupPresent: boolean;
+    }
+  | {
+      readonly kind: "unknown";
+      readonly pendingRows: null;
+      readonly backupEntries: null;
+      readonly canonicalStateDbPath: string;
+      readonly stateDbPresent: boolean;
+      readonly canonicalBackupPath: string;
+      readonly backupPresent: boolean;
+      readonly reason: "backup-path" | "database-absent" | "manifest-read" | "manifest-schema" | "manifest-foreign" | "database-query" | "snapshot-race";
+    };
+
+type StrictBackupInspection =
+  | { readonly kind: "known"; readonly present: boolean; readonly entries: number; readonly fingerprint: string }
+  | { readonly kind: "unknown"; readonly present: boolean; readonly reason: "manifest-read" | "manifest-schema" | "manifest-foreign" };
+
+let afterNoopPendingCountForTests: (() => void) | undefined;
+
+/** Test seam: runs after the pending count and before stability validation. */
+export function setAfterNoopPendingCountForTests(hook: (() => void) | undefined): void {
+  afterNoopPendingCountForTests = hook;
+}
+
 interface NativeRestoreTarget {
   modelProvider: string;
   source: string;
@@ -212,6 +255,65 @@ function samePath(a: string, b: string): boolean {
   return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 
+function inspectBackupForNoop(path: string, stateDbPath: string): StrictBackupInspection {
+  if (!existsSync(path)) return { kind: "known", present: false, entries: 0, fingerprint: "absent" };
+  let parsed: unknown;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "unknown", present: true, reason: "manifest-read" };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { kind: "unknown", present: true, reason: "manifest-schema" };
+  }
+  const manifest = parsed as Partial<BackupManifest>;
+  if (manifest.version !== 1 || typeof manifest.stateDbPath !== "string") {
+    return { kind: "unknown", present: true, reason: "manifest-schema" };
+  }
+  if (!samePath(manifest.stateDbPath, stateDbPath)) {
+    return { kind: "unknown", present: true, reason: "manifest-foreign" };
+  }
+  if (!manifest.entries || typeof manifest.entries !== "object" || Array.isArray(manifest.entries)) {
+    return { kind: "unknown", present: true, reason: "manifest-schema" };
+  }
+  for (const [id, value] of Object.entries(manifest.entries)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return { kind: "unknown", present: true, reason: "manifest-schema" };
+    }
+    const entry = value as Partial<BackupEntry>;
+    if (entry.id !== id
+      || typeof entry.rolloutPath !== "string"
+      || typeof entry.modelProvider !== "string"
+      || typeof entry.source !== "string"
+      || typeof entry.hasUserEvent !== "number") {
+      return { kind: "unknown", present: true, reason: "manifest-schema" };
+    }
+  }
+  return {
+    kind: "known",
+    present: true,
+    entries: Object.keys(manifest.entries).length,
+    fingerprint: createHash("sha256").update(raw).digest("hex"),
+  };
+}
+
+function historyFileIdentity(path: string): string | null {
+  try {
+    const stat = statSync(path);
+    return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+  } catch {
+    return null;
+  }
+}
+
+function readHistoryDataVersion(db: Database): number | null {
+  const row = db.query<{ data_version: number }, []>("PRAGMA data_version").get();
+  const value = row?.data_version;
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : null;
+}
+
 function readBackup(path: string, stateDbPath?: string): BackupManifest {
   if (!existsSync(path)) return { version: 1, stateDbPath, entries: {} };
   try {
@@ -756,6 +858,81 @@ export function migrateHistoryToOpenai(
   return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
 }
 
+/**
+ * Captures no-op evidence while the caller holds the history serialization
+ * lock H. This function does not acquire H itself. Unknown or foreign backup
+ * state is never collapsed into an empty manifest.
+ */
+export function snapshotCodexHistoryNoop(
+  stateDbPath: string,
+  backupPath: string,
+): CodexHistoryNoopSnapshot {
+  const canonicalStateDbPath = resolve(stateDbPath);
+  const canonicalBackupPath = resolve(backupPath);
+  const stateDbPresent = existsSync(stateDbPath);
+  const backupPresent = existsSync(backupPath);
+  const base = { canonicalStateDbPath, stateDbPresent, canonicalBackupPath, backupPresent };
+  if (!samePath(backupPath, historyBackupPathFor(stateDbPath))) {
+    return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "backup-path" };
+  }
+  const backup = inspectBackupForNoop(backupPath, stateDbPath);
+  if (backup.kind === "unknown") {
+    return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: backup.reason };
+  }
+  if (!stateDbPresent) {
+    return backup.entries > 0
+      ? { kind: "work-pending", pendingRows: 0, backupEntries: backup.entries, ...base }
+      : { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-absent" };
+  }
+  const stateDbIdentity = historyFileIdentity(stateDbPath);
+  if (stateDbIdentity === null) {
+    return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "snapshot-race" };
+  }
+  let monitor: Database | undefined;
+  try {
+    monitor = new Database(stateDbPath, { readonly: true });
+    monitor.exec("PRAGMA busy_timeout = 100");
+    const dataVersionBefore = readHistoryDataVersion(monitor);
+    if (dataVersionBefore === null) {
+      return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+    }
+    const pending = countPendingOpencodexHistory(stateDbPath, backupPath);
+    if (pending.failed) {
+      return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+    }
+    afterNoopPendingCountForTests?.();
+    const backupAfter = inspectBackupForNoop(backupPath, stateDbPath);
+    if (backupAfter.kind === "unknown") {
+      return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: backupAfter.reason };
+    }
+    const dataVersionAfter = readHistoryDataVersion(monitor);
+    if (dataVersionAfter === null) {
+      return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+    }
+    if (dataVersionAfter !== dataVersionBefore
+      || pending.backupEntries !== backup.entries
+      || backupAfter.entries !== backup.entries
+      || backupAfter.present !== backup.present
+      || backupAfter.fingerprint !== backup.fingerprint
+      || historyFileIdentity(stateDbPath) !== stateDbIdentity
+      || existsSync(stateDbPath) !== stateDbPresent
+      || existsSync(backupPath) !== backupPresent) {
+      return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "snapshot-race" };
+    }
+    return pending.pendingRows === 0 && backup.entries === 0
+      ? { kind: "verified-noop", pendingRows: 0, backupEntries: 0, ...base, stateDbPresent: true }
+      : { kind: "work-pending", pendingRows: pending.pendingRows, backupEntries: backup.entries, ...base };
+  } catch {
+    return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+  } finally {
+    try {
+      monitor?.close();
+    } catch {
+      // Read-only monitor cleanup cannot make an uncertain snapshot authoritative.
+    }
+  }
+}
+
 export interface PendingHistoryCount {
   /** Threads still tagged opencodex that the eject path WOULD move (mirrors its WHERE). */
   pendingRows: number;

package/src/codex/history-transition.ts

@@ -33,11 +33,11 @@ function classify(outcome: CodexHistoryJobOutcome, txId: string | null): CodexHi
         attempts: 1,
         nextRetryAt: null,
         txId,
-        // Mutation counts, not probe counts. The durable counts come from the
-        // final probe, which this path does not run — null rather than a
-        // manufactured zero.
-        pendingRows: null,
-        backupEntries: null,
+        // A zero is durable only when the worker proved the exact DB/manifest
+        // state while H was held. Without proof, keep the counts unknown. Keep
+        // `??`: `||` would discard a verified zero.
+        pendingRows: outcome.proof?.pendingRows ?? null,
+        backupEntries: outcome.proof?.backupEntries ?? null,
       };
     case "skipped":
       // The user opting out is a completed decision, not a failure — converged

package/src/codex/history-worker.ts

@@ -31,7 +31,11 @@ import {
   writeLegacyOpenaiHistoryRecovery,
   type HistoryWriteTarget,
 } from "./internal/history-writer";
-import type { CodexHistoryFailureReason } from "./history-provider";
+import {
+  snapshotCodexHistoryNoop,
+  type CodexHistoryFailureReason,
+  type CodexHistoryVerifiedNoopProof,
+} from "./history-provider";
 
 /**
  * The durable operation, mirrored into the request for diagnostics only.
@@ -65,7 +69,8 @@ export interface HistoryWorkerRunMessage {
 export type HistoryWorkerResult =
   | { readonly type: "done"; readonly requestId: string; readonly jobId: string;
       readonly outcome: "converged" | "skipped";
-      readonly rows: number; readonly files: number }
+      readonly rows: number; readonly files: number;
+      readonly proof?: CodexHistoryVerifiedNoopProof }
   | { readonly type: "blocked"; readonly requestId: string; readonly jobId: string;
       readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly type: "error"; readonly requestId: string; readonly jobId: string;
@@ -133,6 +138,10 @@ export function runHistoryUnitUnderLock(
       if (operation === "recover-legacy-openai") {
         return writeLegacyOpenaiHistoryRecovery(permit, target);
       }
+      if (operation === "migrate-openai") {
+        const proof = snapshotCodexHistoryNoop(message.canonicalStateDbPath, message.canonicalBackupPath);
+        if (proof.kind === "verified-noop") return { verifiedNoop: proof } as const;
+      }
       // apply-opencodex routes history to opencodex; migrate/restore return it to
       // native. The provider is derived from the operation, never from a caller.
       const provider = operation === "apply-opencodex" ? "opencodex" : "openai";
@@ -152,6 +161,17 @@ export function runHistoryUnitUnderLock(
       reason: message.expectedDesiredEnabled ? "desired_disabled" : "desired_enabled",
     };
   }
+  if ("verifiedNoop" in result) {
+    return {
+      type: "done",
+      requestId,
+      jobId,
+      outcome: "converged",
+      rows: 0,
+      files: 0,
+      proof: result.verifiedNoop,
+    };
+  }
   if (result.failed === true) {
     return {
       type: "error",

package/src/codex/native-profile-store.ts

@@ -383,7 +383,7 @@ function readBounded(path: string, limit: number, testSeam?: BoundedReadTestSeam
     testSeam?.beforeOpen?.(path);
     const flags = process.platform === "win32"
       ? fsConstants.O_RDONLY
-      : fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW;
+      : fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
     fd = openSync(path, flags);
     const opened = fstatSync(fd, { bigint: true });
     if (!opened.isFile() || opened.size > BigInt(limit)) throw new Error("invalid bounded file");

package/src/codex/plan.ts

@@ -0,0 +1,15 @@
+/** Preserve user/provider plan labels only when they are usable strings. */
+export function codexPlanValue(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return value.trim() ? value : undefined;
+}
+
+/** Case-insensitive key used by quota, capacity, and collision policy. */
+export function codexPlanKey(value: unknown): string | undefined {
+  return codexPlanValue(value)?.trim().toLowerCase();
+}
+
+export function isThirtyDayOnlyCodexPlan(value: unknown): boolean {
+  const key = codexPlanKey(value);
+  return key === "go" || key === "free";
+}

package/src/codex/quota.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
+import { isThirtyDayOnlyCodexPlan } from "./plan";
 
 export type StoredAccountQuota = {
   weeklyPercent?: number;
@@ -36,7 +37,7 @@ let persistTimer: ReturnType<typeof setTimeout> | null = null;
 
 export type WhamUsageResponse = {
   email?: string | null;
-  plan_type?: string | null;
+  plan_type?: unknown;
   rate_limit?: {
     // Live WHAM payloads send explicit nulls for absent windows (issue #315 repro).
     primary_window?: WhamUsageWindow | null;
@@ -72,7 +73,7 @@ export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
 
 export function isCodexQuotaExhausted(
   quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent"> | null,
-  plan?: string | null,
+  plan?: unknown,
 ): boolean {
   if (!quota) return false;
   const values = codexQuotaWindowForPlan(plan) === "monthly"
@@ -98,14 +99,13 @@ export function isCodexQuotaExhausted(
  * 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 codexQuotaWindowForPlan(plan?: unknown): "monthly" | "weekly" {
+  return isThirtyDayOnlyCodexPlan(plan) ? "monthly" : "weekly";
 }
 
 export function isCompleteCodexQuotaRecoverySnapshot(
   quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow"> | null,
-  plan?: string | null,
+  plan?: unknown,
 ): boolean {
   if (!quota || isCodexQuotaExhausted(quota, plan)) return false;
   // Recovery still fails closed on MISSING EVIDENCE — a credits-only or windowless payload

package/src/codex/routing.ts

@@ -18,6 +18,7 @@ import {
   selectPriorityTier,
 } from "./pool-rotation";
 import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
+import { isThirtyDayOnlyCodexPlan } from "./plan";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "./main-account";
 import { isSelectableCodexPoolAccount } from "./account-id";
 import type { OcxConfig } from "../types";
@@ -314,10 +315,9 @@ function deleteScopedHealth(accountId: string, scope: CodexQuotaScope): void {
 export function computeCodexUsageScore(quota: {
   weeklyPercent?: number;
   monthlyPercent?: number;
-} | null, plan?: string | null): number {
+} | null, plan?: unknown): number {
   if (!quota) return CODEX_UNKNOWN_USAGE_SCORE;
-  const normalizedPlan = plan?.trim().toLowerCase();
-  if (normalizedPlan === "go" || normalizedPlan === "free") {
+  if (isThirtyDayOnlyCodexPlan(plan)) {
     return typeof quota.monthlyPercent === "number" && Number.isFinite(quota.monthlyPercent)
       ? quota.monthlyPercent
       : CODEX_UNKNOWN_USAGE_SCORE;