@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

package/src/codex/injected-marker.ts

@@ -15,6 +15,20 @@ export function isRootOpenaiBaseUrlLine(line: string): boolean {
   return /^\s*openai_base_url\s*=/.test(line);
 }
 
+/**
+ * codex-rs root key that redirects the realtime sideband WebSocket (WebRTC voice
+ * join + standalone realtime WS) without touching ordinary provider HTTP. Since
+ * openai/codex 438c9e98d (#35830) the sideband ignores the provider base URL and
+ * dials `https://api.openai.com/v1` unless this key is set, so a Pool-routed
+ * call-create and a directly-joined sideband end up on different accounts (404).
+ * Injected next to `openai_base_url` with the same value.
+ */
+export const REALTIME_WS_BASE_URL_KEY = "experimental_realtime_ws_base_url";
+
+export function isRootRealtimeWsBaseUrlLine(line: string): boolean {
+  return /^\s*experimental_realtime_ws_base_url\s*=/.test(line);
+}
+
 export function tomlStringPattern(key: string): RegExp {
   const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const keyToken = `(?:${escaped}|"${escaped}"|'${escaped}')`;
@@ -65,16 +79,28 @@ export function providerTableString(content: string, provider: string, key: stri
  * EXACT value match against what we recorded writing: a user gateway we never wrote
  * cannot match, so restore can never delete a URL that was not ours.
  */
-export function stripJournaledOpenaiBaseUrl(content: string, injectedUrl: string | null): string {
-  if (!injectedUrl) return content;
+export function stripJournaledOpenaiBaseUrl(
+  content: string,
+  injectedUrl: string | null,
+  injectedRealtimeWsUrl: string | null = null,
+): string {
+  if (!injectedUrl && !injectedRealtimeWsUrl) return content;
   const lines = content.split(String.fromCharCode(10));
   const firstTable = lines.findIndex(l => /^\s*\[/.test(l));
   const rootEnd = firstTable === -1 ? lines.length : firstTable;
   const drop = new Set<number>();
   for (let i = 0; i < rootEnd; i++) {
     const line = lines[i]!;
-    if (!isRootOpenaiBaseUrlLine(line)) continue;
-    if (rootTomlString(line, "openai_base_url") !== injectedUrl) continue;
+    // Each key is matched against ITS OWN recorded value. The realtime override is
+    // journaled separately so a user-owned override that happens to equal the proxy
+    // URL is never mistaken for ours.
+    if (isRootOpenaiBaseUrlLine(line)) {
+      if (!injectedUrl || rootTomlString(line, "openai_base_url") !== injectedUrl) continue;
+    } else if (isRootRealtimeWsBaseUrlLine(line)) {
+      if (!injectedRealtimeWsUrl || rootTomlString(line, REALTIME_WS_BASE_URL_KEY) !== injectedRealtimeWsUrl) continue;
+    } else {
+      continue;
+    }
     drop.add(i);
     // Take an ownership marker directly above it too, so repeated cycles cannot
     // accumulate orphaned comments.

package/src/codex/journal.ts

@@ -35,6 +35,13 @@ interface Journal {
    * and it is what lets restore tell OUR loopback URL apart from a gateway the user set.
    */
   injectedOpenaiBaseUrl?: string | null;
+  /**
+   * The root `experimental_realtime_ws_base_url` this injection wrote, when it wrote one.
+   * Recorded on its own rather than inferred from `injectedOpenaiBaseUrl`: a user can own a
+   * realtime override whose value happens to equal the proxy URL, and restore must not treat
+   * that as ours. Null when the key was preserved or not injected.
+   */
+  injectedRealtimeWsBaseUrl?: string | null;
   /**
    * The catalog path this injection actually wrote to.
    *
@@ -119,6 +126,7 @@ export function writeJournal(options: WriteJournalOptions = {}): void {
 
 export interface InjectedJournalOwnership {
   injectedOpenaiBaseUrl: string | null;
+  injectedRealtimeWsBaseUrl: string | null;
   injectedCatalogPath: string | null;
 }
 
@@ -140,6 +148,7 @@ export function markJournalInjectedState(
   // Only the caller knows which values it actually owns. Deriving these from the final TOML
   // would mistake a preserved user override for injected routing.
   journal.injectedOpenaiBaseUrl = ownership.injectedOpenaiBaseUrl;
+  journal.injectedRealtimeWsBaseUrl = ownership.injectedRealtimeWsBaseUrl;
   journal.injectedCatalogPath = ownership.injectedCatalogPath;
   atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
 }
@@ -156,6 +165,11 @@ export function journaledInjectedOpenaiBaseUrl(): string | null {
   return readJournal()?.injectedOpenaiBaseUrl ?? null;
 }
 
+/** The root `experimental_realtime_ws_base_url` the last injection wrote, or null. */
+export function journaledInjectedRealtimeWsBaseUrl(): string | null {
+  return readJournal()?.injectedRealtimeWsBaseUrl ?? null;
+}
+
 /** The catalog path the last injection wrote to, or null when none was recorded. */
 export function journaledInjectedCatalogPath(): string | null {
   return readJournal()?.injectedCatalogPath ?? null;

package/src/codex/legacy-config-keys.ts

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCodexHomeDir } from "./home";
+import { parseTomlDocument } from "./project-config-warnings";
+import { redactUserPath } from "../lib/redact";
+
+/**
+ * Keys that are valid in model catalog data but not at the top level of the
+ * user config. Codex rejects them when strict config parsing is enabled.
+ */
+const LEGACY_KEYS = ["persistent_instructions"] as const;
+
+export type LegacyCodexConfigKey = (typeof LEGACY_KEYS)[number];
+
+export interface LegacyCodexConfigKeyDiagnostic {
+  readonly path: string;
+  readonly code: LegacyCodexConfigKey;
+  readonly detail: string;
+}
+
+export type LegacyCodexConfigKeyDiagnosticsResult =
+  | { readonly status: "available"; readonly path: string; readonly diagnostics: readonly LegacyCodexConfigKeyDiagnostic[] }
+  | { readonly status: "unavailable"; readonly path: string; readonly reason: "read_failed" | "not_a_file" };
+
+function resolveCodexConfigPath(codexConfigPath?: string): string {
+  if (codexConfigPath) return codexConfigPath;
+  return join(resolveCodexHomeDir(), "config.toml");
+}
+
+export function collectLegacyCodexConfigKeyDiagnostics(
+  options: { codexConfigPath?: string } = {},
+): LegacyCodexConfigKeyDiagnosticsResult {
+  const path = resolveCodexConfigPath(options.codexConfigPath);
+  if (!existsSync(path)) return { status: "available", path, diagnostics: [] };
+  let content: string;
+  try {
+    if (!statSync(path).isFile()) return { status: "unavailable", path, reason: "not_a_file" };
+    content = readFileSync(path, "utf-8");
+  } catch { // no-excuse-ok: catch -- optional doctor diagnostics must not fail on an unreadable file.
+    return { status: "unavailable", path, reason: "read_failed" };
+  }
+  const { root } = parseTomlDocument(content);
+  const found: LegacyCodexConfigKeyDiagnostic[] = [];
+  for (const key of LEGACY_KEYS) {
+    if (key in root) {
+      found.push({
+        path,
+        code: key,
+        detail: `top-level '${key}' is not a valid Codex config key. `
+          + "codex --strict-config rejects the whole file. Remove the key and put durable guidance in AGENTS.md.",
+      });
+    }
+  }
+  return { status: "available", path, diagnostics: found };
+}
+
+export function formatLegacyCodexConfigKeyDiagnosticsForDoctor(
+  result: LegacyCodexConfigKeyDiagnosticsResult,
+): string[] {
+  const displayPath = redactUserPath(result.path);
+  if (result.status === "unavailable") {
+    return [`  --     Codex config at ${displayPath} could not be read (${result.reason}); legacy-key check skipped`];
+  }
+  if (result.diagnostics.length === 0) {
+    return ["  ok     no unsupported legacy top-level keys in the Codex config"];
+  }
+  return result.diagnostics.map(diagnostic => `[WARN] ${redactUserPath(diagnostic.path)}: ${diagnostic.detail}`);
+}

package/src/codex/log-guard/inspect-schema.ts

@@ -0,0 +1,137 @@
+import type { Database } from "bun:sqlite";
+
+interface CurrentLogColumn {
+  name: string;
+  type: string;
+  notnull: number;
+  defaultValue: string | null;
+  pk: number;
+}
+
+// Pinned to Codex logs migration 0002. Keep this schema private: inspection reports
+// compatibility, not column names, so sensitive payload-bearing fields never leak through
+// the management API. Any additive/rebuilt future schema is monitor-only until reviewed.
+const CURRENT_LOG_SCHEMA: readonly CurrentLogColumn[] = [
+  { name: "id", type: "INTEGER", notnull: 0, defaultValue: null, pk: 1 },
+  { name: "ts", type: "INTEGER", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "ts_nanos", type: "INTEGER", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "level", type: "TEXT", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "target", type: "TEXT", notnull: 1, defaultValue: null, pk: 0 },
+  { name: "feedback_log_body", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "module_path", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "file", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "line", type: "INTEGER", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "thread_id", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "process_uuid", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
+  { name: "estimated_bytes", type: "INTEGER", notnull: 1, defaultValue: "0", pk: 0 },
+] as const;
+
+const CURRENT_LOG_TABLE_SQL = `CREATE TABLE logs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  ts_nanos INTEGER NOT NULL,
+  level TEXT NOT NULL,
+  target TEXT NOT NULL,
+  feedback_log_body TEXT,
+  module_path TEXT,
+  file TEXT,
+  line INTEGER,
+  thread_id TEXT,
+  process_uuid TEXT,
+  estimated_bytes INTEGER NOT NULL DEFAULT 0
+)`;
+
+const CURRENT_LOG_INDEX_SQL = {
+  idx_logs_ts: "CREATE INDEX idx_logs_ts ON logs(ts DESC, ts_nanos DESC, id DESC)",
+  idx_logs_thread_id: "CREATE INDEX idx_logs_thread_id ON logs(thread_id)",
+  idx_logs_thread_id_ts: "CREATE INDEX idx_logs_thread_id_ts ON logs(thread_id, ts DESC, ts_nanos DESC, id DESC)",
+  idx_logs_process_uuid_threadless_ts: `CREATE INDEX idx_logs_process_uuid_threadless_ts
+    ON logs(process_uuid, ts DESC, ts_nanos DESC, id DESC)
+    WHERE thread_id IS NULL`,
+} as const;
+
+
+export interface ColumnRow {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+interface SchemaObjectRow { name: string; type: string; sql: string | null }
+
+function normalizeDeclaredType(type: string): string {
+  return String(type ?? "").trim().toUpperCase();
+}
+
+function normalizeDefault(value: string | null): string | null {
+  return value === null ? null : String(value).trim();
+}
+
+function normalizeSchemaSql(sql: string | null | undefined): string {
+  return (sql ?? "").trim().replace(/;\s*$/, "").replace(/\s+/g, " ");
+}
+
+function sameColumns(columns: ColumnRow[]): boolean {
+  if (columns.length !== CURRENT_LOG_SCHEMA.length) return false;
+  return columns.every((column, index) => {
+    const expected = CURRENT_LOG_SCHEMA[index];
+    return column.cid === index
+      && column.name === expected.name
+      && normalizeDeclaredType(column.type) === expected.type
+      && Number(column.notnull) === expected.notnull
+      && normalizeDefault(column.dflt_value) === expected.defaultValue
+      && Number(column.pk) === expected.pk;
+  });
+}
+
+/**
+ * The authoritative compatibility predicate: exact table SQL, exact column
+ * metadata, and every canonical index.
+ *
+ * Exported because the mutation paths must apply the SAME test inside their
+ * write transaction. They used to check column NAMES only, which is strictly
+ * weaker than what the inspector reports, so a schema change landing between
+ * the outer inspection and the locked write let Protect install a row-dropping
+ * trigger and let Reclaim vacuum pages on a database the inspector classifies
+ * as monitor-only. The lock serializes OpenCodex against itself; it does not
+ * stop Codex or another SQLite writer, so that TOCTOU window is real.
+ */
+export function hasCurrentLogsSchema(db: Database): boolean {
+  const columns = db.query<ColumnRow, []>("PRAGMA table_info(logs)").all();
+  return hasCurrentLogsTable(db, columns);
+}
+
+export function hasCurrentLogsTable(db: Database, columns: ColumnRow[]): boolean {
+  const table = db.query<SchemaObjectRow, []>(
+    "SELECT name, type, sql FROM sqlite_schema WHERE name = 'logs' LIMIT 1",
+  ).get();
+  if (table?.type !== "table"
+    || !sameColumns(columns)
+    || normalizeSchemaSql(table.sql) !== normalizeSchemaSql(CURRENT_LOG_TABLE_SQL)) {
+    return false;
+  }
+
+  const indexes = db.query<SchemaObjectRow, []>(`
+    SELECT name, type, sql FROM sqlite_schema
+    WHERE name IN (
+      'idx_logs_ts',
+      'idx_logs_thread_id',
+      'idx_logs_thread_id_ts',
+      'idx_logs_process_uuid_threadless_ts'
+    )
+  `).all();
+  const byName = new Map(indexes.map(row => [row.name, row]));
+  for (const [name, expectedSql] of Object.entries(CURRENT_LOG_INDEX_SQL)) {
+    const row = byName.get(name);
+    if (row?.type !== "index" || normalizeSchemaSql(row.sql) !== normalizeSchemaSql(expectedSql)) {
+      return false;
+    }
+  }
+
+  // Extra indexes and triggers do not redefine the table contract. In particular,
+  // Protect intentionally installs OpenCodex-owned triggers and unrelated user triggers
+  // are supported, so compatibility is based on the canonical table plus required indexes.
+  return true;
+}

package/src/codex/log-guard/inspect.ts

@@ -8,6 +8,8 @@ import {
   resolveCodexSqliteHome,
   type CodexSqliteHomeDeps,
 } from "../paths";
+export { hasCurrentLogsSchema } from "./inspect-schema";
+import { hasCurrentLogsTable, type ColumnRow } from "./inspect-schema";
 
 const IMMUTABLE_READONLY_FLAGS = constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI;
 const KNOWN_LOG_LEVELS = new Set(["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]);
@@ -15,56 +17,6 @@ const KNOWN_LOG_LEVELS = new Set(["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]);
 // alone; skipping all row aggregates above 64 MiB reduced /api/storage to 628ms.
 const MAX_SYNCHRONOUS_METRICS_DATABASE_BYTES = 64 * 1024 * 1024;
 
-interface CurrentLogColumn {
-  name: string;
-  type: string;
-  notnull: number;
-  defaultValue: string | null;
-  pk: number;
-}
-
-// Pinned to Codex logs migration 0002. Keep this schema private: inspection reports
-// compatibility, not column names, so sensitive payload-bearing fields never leak through
-// the management API. Any additive/rebuilt future schema is monitor-only until reviewed.
-const CURRENT_LOG_SCHEMA: readonly CurrentLogColumn[] = [
-  { name: "id", type: "INTEGER", notnull: 0, defaultValue: null, pk: 1 },
-  { name: "ts", type: "INTEGER", notnull: 1, defaultValue: null, pk: 0 },
-  { name: "ts_nanos", type: "INTEGER", notnull: 1, defaultValue: null, pk: 0 },
-  { name: "level", type: "TEXT", notnull: 1, defaultValue: null, pk: 0 },
-  { name: "target", type: "TEXT", notnull: 1, defaultValue: null, pk: 0 },
-  { name: "feedback_log_body", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
-  { name: "module_path", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
-  { name: "file", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
-  { name: "line", type: "INTEGER", notnull: 0, defaultValue: null, pk: 0 },
-  { name: "thread_id", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
-  { name: "process_uuid", type: "TEXT", notnull: 0, defaultValue: null, pk: 0 },
-  { name: "estimated_bytes", type: "INTEGER", notnull: 1, defaultValue: "0", pk: 0 },
-] as const;
-
-const CURRENT_LOG_TABLE_SQL = `CREATE TABLE logs (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts INTEGER NOT NULL,
-  ts_nanos INTEGER NOT NULL,
-  level TEXT NOT NULL,
-  target TEXT NOT NULL,
-  feedback_log_body TEXT,
-  module_path TEXT,
-  file TEXT,
-  line INTEGER,
-  thread_id TEXT,
-  process_uuid TEXT,
-  estimated_bytes INTEGER NOT NULL DEFAULT 0
-)`;
-
-const CURRENT_LOG_INDEX_SQL = {
-  idx_logs_ts: "CREATE INDEX idx_logs_ts ON logs(ts DESC, ts_nanos DESC, id DESC)",
-  idx_logs_thread_id: "CREATE INDEX idx_logs_thread_id ON logs(thread_id)",
-  idx_logs_thread_id_ts: "CREATE INDEX idx_logs_thread_id_ts ON logs(thread_id, ts DESC, ts_nanos DESC, id DESC)",
-  idx_logs_process_uuid_threadless_ts: `CREATE INDEX idx_logs_process_uuid_threadless_ts
-    ON logs(process_uuid, ts DESC, ts_nanos DESC, id DESC)
-    WHERE thread_id IS NULL`,
-} as const;
-
 export type CodexLogGuardCapabilityReason =
   | "database_missing"
   | "database_unreadable"
@@ -124,15 +76,6 @@ export interface CodexLogGuardInspection {
   };
 }
 
-interface ColumnRow {
-  cid: number;
-  name: string;
-  type: string;
-  notnull: number;
-  dflt_value: string | null;
-  pk: number;
-}
-interface SchemaObjectRow { name: string; type: string; sql: string | null }
 interface CountRow { n: number }
 interface LevelRow { level: string; rows: number }
 interface TargetCountRow { rows: number }
@@ -243,81 +186,6 @@ function unavailableInspection(): CodexLogGuardInspection {
   };
 }
 
-function normalizeDeclaredType(type: string): string {
-  return String(type ?? "").trim().toUpperCase();
-}
-
-function normalizeDefault(value: string | null): string | null {
-  return value === null ? null : String(value).trim();
-}
-
-function normalizeSchemaSql(sql: string | null | undefined): string {
-  return (sql ?? "").trim().replace(/;\s*$/, "").replace(/\s+/g, " ");
-}
-
-function sameColumns(columns: ColumnRow[]): boolean {
-  if (columns.length !== CURRENT_LOG_SCHEMA.length) return false;
-  return columns.every((column, index) => {
-    const expected = CURRENT_LOG_SCHEMA[index];
-    return column.cid === index
-      && column.name === expected.name
-      && normalizeDeclaredType(column.type) === expected.type
-      && Number(column.notnull) === expected.notnull
-      && normalizeDefault(column.dflt_value) === expected.defaultValue
-      && Number(column.pk) === expected.pk;
-  });
-}
-
-/**
- * The authoritative compatibility predicate: exact table SQL, exact column
- * metadata, and every canonical index.
- *
- * Exported because the mutation paths must apply the SAME test inside their
- * write transaction. They used to check column NAMES only, which is strictly
- * weaker than what the inspector reports, so a schema change landing between
- * the outer inspection and the locked write let Protect install a row-dropping
- * trigger and let Reclaim vacuum pages on a database the inspector classifies
- * as monitor-only. The lock serializes OpenCodex against itself; it does not
- * stop Codex or another SQLite writer, so that TOCTOU window is real.
- */
-export function hasCurrentLogsSchema(db: Database): boolean {
-  const columns = db.query<ColumnRow, []>("PRAGMA table_info(logs)").all();
-  return hasCurrentLogsTable(db, columns);
-}
-
-function hasCurrentLogsTable(db: Database, columns: ColumnRow[]): boolean {
-  const table = db.query<SchemaObjectRow, []>(
-    "SELECT name, type, sql FROM sqlite_schema WHERE name = 'logs' LIMIT 1",
-  ).get();
-  if (table?.type !== "table"
-    || !sameColumns(columns)
-    || normalizeSchemaSql(table.sql) !== normalizeSchemaSql(CURRENT_LOG_TABLE_SQL)) {
-    return false;
-  }
-
-  const indexes = db.query<SchemaObjectRow, []>(`
-    SELECT name, type, sql FROM sqlite_schema
-    WHERE name IN (
-      'idx_logs_ts',
-      'idx_logs_thread_id',
-      'idx_logs_thread_id_ts',
-      'idx_logs_process_uuid_threadless_ts'
-    )
-  `).all();
-  const byName = new Map(indexes.map(row => [row.name, row]));
-  for (const [name, expectedSql] of Object.entries(CURRENT_LOG_INDEX_SQL)) {
-    const row = byName.get(name);
-    if (row?.type !== "index" || normalizeSchemaSql(row.sql) !== normalizeSchemaSql(expectedSql)) {
-      return false;
-    }
-  }
-
-  // Extra indexes and triggers do not redefine the table contract. In particular,
-  // Protect intentionally installs OpenCodex-owned triggers and unrelated user triggers
-  // are supported, so compatibility is based on the canonical table plus required indexes.
-  return true;
-}
-
 function pragmaNumber(db: Database, pragma: "page_size" | "page_count" | "freelist_count"): number {
   const row = db.query<Record<string, number>, []>(`PRAGMA ${pragma}`).get();
   return Number(row?.[pragma] ?? 0);

package/src/codex/loopback-target.ts

@@ -0,0 +1,54 @@
+import type { OcxConfig } from "../types";
+import type { DataPlaneAdmission } from "../server/auth-cors";
+import { NATIVE_RESERVE_MODEL } from "./catalog/native-models";
+
+export const CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE =
+  "Luna Reserve compatibility is only available as a conversation model, not a vision helper. Choose another vision model.";
+
+/** Callers classify the concrete destination as canonical forward before using this predicate. */
+export function isCodexReserveHelperUnsupported(
+  config: Pick<OcxConfig, "codexDesktopAuthless" | "runtimeRole">,
+  modelId: string,
+  admission: Pick<DataPlaneAdmission, "source"> | undefined,
+  terminalHelper: boolean,
+): boolean {
+  return terminalHelper && modelId === NATIVE_RESERVE_MODEL && isCodexReserveRequestEligible(config, admission);
+}
+
+/** Runtime authority comes from the receiving listener, not the catalog's injection target. */
+export function isCodexReserveRequestEligible(
+  config: Pick<OcxConfig, "codexDesktopAuthless" | "runtimeRole">,
+  admission: Pick<DataPlaneAdmission, "source"> | undefined,
+): boolean {
+  return config.codexDesktopAuthless === true && config.runtimeRole !== "client"
+    && admission?.source === "loopback";
+}
+
+/** Bind scope, not the dial address: wildcard listeners are never loopback-only. */
+export function isLoopbackHostname(hostname: string | undefined): boolean {
+  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase().replace(/\.$/, "");
+  return (
+    normalized === "" ||
+    normalized === "localhost" ||
+    normalized === "127.0.0.1" ||
+    normalized === "::1" ||
+    normalized === "[::1]"
+  );
+}
+
+export function shouldInjectApiAuthHeader(
+  config: Pick<OcxConfig, "hostname" | "unauthenticatedLoopbackListener"> | undefined,
+): boolean {
+  // The dedicated listener binds loopback and does not require an admission credential.
+  if (config?.unauthenticatedLoopbackListener?.enabled) return false;
+  return !isLoopbackHostname(config?.hostname);
+}
+
+/** Match standalone injection, never a remote client's independently supplied routing target. */
+export function isEffectiveCodexDesktopAuthless(
+  config: Pick<OcxConfig, "runtimeRole" | "hostname" | "unauthenticatedLoopbackListener" | "codexDesktopAuthless"> | undefined,
+): boolean {
+  return config?.codexDesktopAuthless === true
+    && config.runtimeRole !== "client"
+    && !shouldInjectApiAuthHeader(config);
+}

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

@@ -1,4 +1,5 @@
-import type { StoredAccountQuota } from "./quota";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type { StoredAccountQuota } from "./quota-types";
 import { truncateRetainedUtf8 } from "../lib/admission";
 
 const MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;
@@ -16,6 +17,65 @@ export interface CachedMainAccountInfo extends MainAccountInfo {
 let cachedMainAccountInfo: CachedMainAccountInfo | null = null;
 let cachedMainCredentialPresence: boolean | null = null;
 let mainAccountIdentityGeneration = 0;
+let observedMainQuotaIdentityKey: string | undefined;
+const mainQuotaCredentialKey = randomBytes(32);
+let mainQuotaCredential: { bearerHmac: Buffer; writer: MainQuotaWriter } | undefined;
+let mainQuotaCredentialGeneration = 0;
+
+/** Process-local transition fence; no credential material or persisted identity. */
+export function getMainQuotaCredentialGeneration(): number { return mainQuotaCredentialGeneration; }
+
+export type MainQuotaWriter = Readonly<{ identityKey: string; identityGeneration: number }>;
+
+function mainQuotaIdentityKey(accountId: string): string {
+  return createHash("sha256").update("opencodex-main-quota-v1\0").update(accountId).digest("hex");
+}
+
+/** Only an existing owned physical-identity read may publish this observation. */
+export function observeMainQuotaIdentity(accountId: string): void {
+  if (!accountId) return;
+  const identityKey = mainQuotaIdentityKey(accountId);
+  if (identityKey === observedMainQuotaIdentityKey) return;
+  observedMainQuotaIdentityKey = identityKey;
+  mainAccountIdentityGeneration += 1;
+  mainQuotaCredential = undefined;
+  mainQuotaCredentialGeneration += 1;
+}
+
+export function captureMainQuotaWriter(accountId: string): MainQuotaWriter | undefined {
+  if (!accountId) return undefined;
+  const identityKey = mainQuotaIdentityKey(accountId);
+  if (identityKey !== observedMainQuotaIdentityKey) return undefined;
+  return { identityKey, identityGeneration: mainAccountIdentityGeneration };
+}
+
+/** Credential material must come from an already-owned read, never an incoming request. */
+export function observeMainQuotaCredential(accessToken: string, accountId: string): MainQuotaWriter | undefined {
+  const writer = captureMainQuotaWriter(accountId);
+  if (!accessToken || !writer) return undefined;
+  const bearerHmac = createHmac("sha256", mainQuotaCredentialKey).update(accessToken).digest();
+  if (!mainQuotaCredential || !isMainQuotaWriterLive(mainQuotaCredential.writer)
+    || !timingSafeEqual(bearerHmac, mainQuotaCredential.bearerHmac)) mainQuotaCredentialGeneration += 1;
+  mainQuotaCredential = { bearerHmac, writer };
+  return { ...writer };
+}
+
+export function matchesMainQuotaCredential(accessToken: string, effectiveAccountId: string | undefined): boolean {
+  const observed = mainQuotaCredential;
+  if (!accessToken || !effectiveAccountId || !observed || !isMainQuotaWriterLive(observed.writer)) return false;
+  if (mainQuotaIdentityKey(effectiveAccountId) !== observed.writer.identityKey) return false;
+  const candidate = createHmac("sha256", mainQuotaCredentialKey).update(accessToken).digest();
+  return timingSafeEqual(candidate, observed.bearerHmac);
+}
+
+export function isMainQuotaWriterLive(writer: MainQuotaWriter): boolean {
+  return writer.identityKey === observedMainQuotaIdentityKey
+    && writer.identityGeneration === mainAccountIdentityGeneration;
+}
+
+export function getObservedMainQuotaIdentityKey(): string | undefined {
+  return observedMainQuotaIdentityKey;
+}
 
 export function captureMainAccountIdentityGeneration(): number {
   return mainAccountIdentityGeneration;
@@ -40,6 +100,8 @@ export function setMainAccountInfoCache(value: CachedMainAccountInfo): void {
 export function clearMainAccountInfoCache(): void {
   cachedMainAccountInfo = null;
   mainAccountIdentityGeneration += 1;
+  mainQuotaCredential = undefined;
+  mainQuotaCredentialGeneration += 1;
 }
 
 /** Last physical credential presence observed while native-main ownership was held. */

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

@@ -0,0 +1,52 @@
+import type { OcxConfig } from "../types";
+import { getMainPolicyQuota } from "./quota";
+
+export const MAIN_ACCOUNT_HARD_LOCK_PERCENT = 99;
+
+export interface MainAccountHardLockStatus {
+  enabled: boolean;
+  state: "off" | "unknown" | "ready" | "blocked";
+  /** Unix milliseconds; absent when a blocking observation has no future reset. */
+  resetAt?: number;
+}
+
+type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock">;
+
+function resetTimestamp(value: number | undefined): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return undefined;
+  return value < 10_000_000_000 ? value * 1000 : value;
+}
+
+/** Observed admission policy, not a reservation of the account's remaining quota. */
+export function getMainAccountHardLockStatus(
+  config: PolicyConfig,
+  now = Date.now(),
+): MainAccountHardLockStatus {
+  if (config.codexMainAccountHardLock !== true) return { enabled: false, state: "off" };
+  const quota = getMainPolicyQuota();
+  if (!quota) return { enabled: true, state: "unknown" };
+  // Account window priority is deliberate: a 5h account uses that window, even if
+  // its weekly bar is higher. An unknown/expired selected window does not change the choice.
+  const hasShort = quota.shortPercent !== undefined || quota.shortResetAt !== undefined
+    || quota.shortWindowSeconds !== undefined;
+  const hasWeekly = quota.weeklyPercent !== undefined || quota.weeklyResetAt !== undefined;
+  const [percent, rawReset] = hasShort
+    ? [quota.shortPercent, quota.shortResetAt]
+    : hasWeekly ? [quota.weeklyPercent, quota.weeklyResetAt] : [quota.monthlyPercent, quota.monthlyResetAt];
+  const resetAt = resetTimestamp(rawReset);
+  // The routing score's unknown sentinel is 101. It is never a raw quota observation.
+  if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100) {
+    return { enabled: true, state: "unknown" };
+  }
+  if (percent < MAIN_ACCOUNT_HARD_LOCK_PERCENT) return { enabled: true, state: "ready" };
+  return {
+    enabled: true,
+    state: "blocked",
+    // A predicted reset is not evidence of recovery. Only a fresh lower reading releases.
+    ...(resetAt !== undefined && resetAt > now ? { resetAt } : {}),
+  };
+}
+
+export function isMainAccountHardLocked(config: PolicyConfig, now = Date.now()): boolean {
+  return getMainAccountHardLockStatus(config, now).state === "blocked";
+}

package/src/codex/main-account.ts

@@ -57,6 +57,8 @@ type MainAuthJsonCredential = {
 export interface NativeMainRefreshDependencies {
   refreshToken?: (refreshToken: string, options: { signal: AbortSignal }) => Promise<OAuthCredentials>;
   signal?: AbortSignal;
+  /** Metadata-only refresh must not retract a concurrent traffic reauth quarantine. */
+  preserveReauth?: boolean;
 }
 
 export class MainAuthJsonChangedDuringRefreshError extends Error {
@@ -283,7 +285,7 @@ async function resolveMainAccountToken(
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
         const result = persistRefreshedMainAuthJson(locked, refreshed);
-        clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+        if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return result;
       }),
       { waitMs: 30_000, signal },