@bitkyc08/opencodex 2.58.0 → 2.59.0

package/src/codex/cli-installation-identity.ts

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { win32 } from "node:path";
+import { parseStrictSemver } from "../lib/strict-semver";
+
+/** Explicit observation, not runtime selection or authority to run an installer. */
+export interface CodexCliInstallationIdentityInput {
+  readonly candidate: string;
+  readonly npmPrefix: string;
+  readonly npmCli: string;
+  readonly node: string;
+  /** Where the candidate came from; defaults to an explicit CLI argument. */
+  readonly candidateSource?: "explicit-cli" | "selected";
+}
+
+export interface CodexCliInstallationIdentityReport {
+  readonly schemaVersion: 1;
+  readonly candidateSource: "explicit-cli" | "selected";
+  readonly status: "observed" | "refused";
+  readonly reason: string;
+  readonly installationIdentityObserved: boolean;
+  readonly selectionAttested: false;
+  readonly managed: false;
+  readonly applyAllowed: false;
+  readonly packageVersion: string | null;
+  readonly npmVersion: string | null;
+  readonly identityDigest: string | null;
+  readonly proof: "windows-handle-bound" | null;
+  readonly toolchain: "observed-only";
+}
+
+export interface InstallationFileRequest {
+  readonly path: string;
+  readonly maxBytes: number;
+  readonly hashOnly?: boolean;
+}
+
+export interface ObservedInstallationFile {
+  readonly path: string;
+  readonly identity: {
+    readonly volumeSerial: string;
+    readonly fileId: string;
+    readonly size: number;
+    readonly lastWriteTime: string;
+    readonly changeTime: string;
+  };
+  readonly bytes: Uint8Array;
+  readonly digest?: string;
+}
+
+export type InstallationFilesResult =
+  | { readonly kind: "observed"; readonly files: readonly ObservedInstallationFile[] }
+  | { readonly kind: "refused"; readonly reason: string };
+
+export interface CodexCliInstallationIdentityDeps {
+  readonly platform?: NodeJS.Platform;
+  readonly inspectFiles?: (requests: readonly InstallationFileRequest[]) => Promise<InstallationFilesResult>;
+}
+
+const TEXT_LIMIT = 256 * 1024;
+const NODE_LIMIT = 256 * 1024 * 1024;
+const hash = (value: string | Uint8Array): string => createHash("sha256").update(value).digest("hex");
+// NTFS can enable case-sensitive directory entries. Do not collapse different
+// paths merely because ordinary Windows directories usually ignore case.
+const key = (path: string): string => path[0]!.toUpperCase() + path.slice(1);
+
+function localPath(value: string): string | null {
+  if (typeof value !== "string" || value.length > 30_000 || !/^[a-z]:[\\/]/i.test(value)) return null;
+  const path = value.replaceAll("/", "\\");
+  const parts = path.slice(3).split("\\");
+  if (!parts.length || parts.some(part => !part || part === "." || part === ".."
+    || /[\x00-\x1f<>:"|?*]/.test(part) || /[. ]$/.test(part)
+    || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) return null;
+  return path;
+}
+
+function supportedLayoutPath(path: string): boolean {
+  // This slice does not adopt package managers or packaged desktop applications.
+  return !/(?:^|\\)(?:windowsapps|scoop|\.volta|\.nvm|\.asdf|\.mise|\.fnm|\.nvs|\.nodenv)(?:\\|$)|\.app(?:\\|$)/i.test(path);
+}
+
+function report(
+  reason: string,
+  versions?: { codex: string; npm: string; digest: string },
+  candidateSource: CodexCliInstallationIdentityReport["candidateSource"] = "explicit-cli",
+): CodexCliInstallationIdentityReport {
+  return Object.freeze({
+    schemaVersion: 1, candidateSource, status: versions ? "observed" : "refused",
+    reason, installationIdentityObserved: !!versions, selectionAttested: false, managed: false,
+    applyAllowed: false, packageVersion: versions?.codex ?? null, npmVersion: versions?.npm ?? null,
+    identityDigest: versions?.digest ?? null, proof: versions ? "windows-handle-bound" : null,
+    toolchain: "observed-only",
+  });
+}
+
+/** A refusal before any observation ran, e.g. when no selected candidate can be identified. */
+export function codexCliInstallationRefusal(
+  reason: string,
+  candidateSource: CodexCliInstallationIdentityReport["candidateSource"] = "explicit-cli",
+): CodexCliInstallationIdentityReport {
+  return report(reason, undefined, candidateSource);
+}
+
+function manifest(file: ObservedInstallationFile, name: string, bin: string, expected: string): string | null {
+  try {
+    const value: unknown = JSON.parse(Buffer.from(file.bytes).toString("utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    const item = value as Record<string, unknown>;
+    const entry = typeof item.bin === "string" ? item.bin
+      : item.bin && typeof item.bin === "object" ? (item.bin as Record<string, unknown>)[bin] : null;
+    return item.name === name && typeof item.version === "string" && parseStrictSemver(item.version)
+      && entry === expected ? item.version : null;
+  } catch { return null; }
+}
+
+/** Only the standard npm cmd-shim is linked here; arbitrary wrappers remain unverified. */
+function npmCodexCommandShim(bytes: Uint8Array): boolean {
+  const expected = `@ECHO off
+GOTO start
+:find_dp0
+SET dp0=%~dp0
+EXIT /b
+:start
+SETLOCAL
+CALL :find_dp0
+
+IF EXIST "%dp0%\\node.exe" (
+  SET "_prog=%dp0%\\node.exe"
+) ELSE (
+  SET "_prog=node"
+  SET PATHEXT=%PATHEXT:;.JS;=;%
+)
+
+endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\node_modules\\@openai\\codex\\bin\\codex.js" %*`;
+  const normalize = (text: string) => text.replaceAll("\r\n", "\n").trimEnd();
+  return normalize(Buffer.from(bytes).toString("utf8")) === normalize(expected);
+}
+
+function fileDigest(file: ObservedInstallationFile): string {
+  return file.digest ?? hash(file.bytes);
+}
+
+function fileEvidence(file: ObservedInstallationFile): readonly (string | number)[] {
+  const id = file.identity;
+  return [key(file.path), id.volumeSerial, id.fileId, id.size, id.lastWriteTime, id.changeTime, fileDigest(file)];
+}
+
+/** No filesystem or native-library work occurs until this explicit operation is called. */
+export async function inspectCodexCliInstallationIdentity(
+  input: CodexCliInstallationIdentityInput,
+  deps: CodexCliInstallationIdentityDeps = {},
+): Promise<CodexCliInstallationIdentityReport> {
+  const source = input.candidateSource ?? "explicit-cli";
+  const refused = (reason: string) => report(reason, undefined, source);
+  if ((deps.platform ?? process.platform) !== "win32") return refused("unsupported_platform");
+  const candidate = localPath(input.candidate);
+  const prefix = localPath(input.npmPrefix);
+  const npmCli = localPath(input.npmCli);
+  const node = localPath(input.node);
+  if (!candidate || !prefix || !npmCli || !node) return refused("unsafe_path");
+  if (![candidate, prefix, npmCli, node].every(supportedLayoutPath)) return refused("unsupported_layout");
+  const packageRoot = win32.join(prefix, "node_modules", "@openai", "codex");
+  const codexManifest = win32.join(packageRoot, "package.json");
+  const codexBin = win32.join(packageRoot, "bin", "codex.js");
+  const shim = win32.join(prefix, "codex.cmd");
+  // A codex.opencodex-real.cmd backup is npm's renamed launcher: same grammar, same dir.
+  const backingShim = win32.join(prefix, "codex.opencodex-real.cmd");
+  const acceptedCandidates = source === "selected"
+    ? [key(codexBin), key(shim), key(backingShim)]
+    : [key(codexBin), key(shim)];
+  if (!acceptedCandidates.includes(key(candidate))
+    || !/\\node_modules\\npm\\bin\\npm-cli\.js$/i.test(npmCli)
+    || win32.basename(node).toLowerCase() !== "node.exe") return refused("unsupported_layout");
+  const npmManifest = win32.join(win32.dirname(win32.dirname(npmCli)), "package.json");
+  try {
+    const inspect = deps.inspectFiles ?? (await import("./windows-installation-files")).inspectWindowsInstallationFiles;
+    // Read both manifests again with every linked file held open: first-pass bytes cannot
+    // authorize links after a manifest replacement between the two observations.
+    const first = await inspect([{ path: codexManifest, maxBytes: TEXT_LIMIT }, { path: npmManifest, maxBytes: TEXT_LIMIT }]);
+    if (first.kind !== "observed") return refused("native_proof_unavailable");
+    const initial = new Map(first.files.map(file => [key(file.path), file]));
+    const codex = initial.get(key(codexManifest));
+    const npm = initial.get(key(npmManifest));
+    if (!codex || !npm) return refused("read_failed");
+    const codexVersion = manifest(codex, "@openai/codex", "codex", "bin/codex.js");
+    const npmVersion = manifest(npm, "npm", "npm", "bin/npm-cli.js");
+    if (!codexVersion || !npmVersion) return refused("package_mismatch");
+    const requests: InstallationFileRequest[] = [codexManifest, npmManifest, candidate, codexBin, npmCli]
+      .filter((path, index, all) => all.findIndex(other => key(other) === key(path)) === index)
+      .map(path => ({ path, maxBytes: TEXT_LIMIT }));
+    requests.push({ path: node, maxBytes: NODE_LIMIT, hashOnly: true });
+    const second = await inspect(requests);
+    if (second.kind !== "observed") return refused("native_proof_unavailable");
+    const files = new Map(second.files.map(file => [key(file.path), file]));
+    if (requests.some(request => !files.has(key(request.path)))) return refused("read_failed");
+    for (const before of [codex, npm]) {
+      if (JSON.stringify(fileEvidence(before)) !== JSON.stringify(fileEvidence(files.get(key(before.path))!))) {
+        return refused("identity_changed");
+      }
+    }
+    if ([key(shim), key(backingShim)].includes(key(candidate))
+      && !npmCodexCommandShim(files.get(key(candidate))!.bytes)) {
+      return refused("launcher_mismatch");
+    }
+    const observed = [...files.values()].sort((a, b) => key(a.path) < key(b.path) ? -1 : key(a.path) > key(b.path) ? 1 : 0);
+    if (observed.some(file => !/^[a-f0-9]{64}$/i.test(fileDigest(file)))) return refused("read_failed");
+    const digest = hash(JSON.stringify(["opencodex-explicit-installation-observation-v1", key(prefix),
+      key(candidate), key(npmCli), key(node), ...observed.map(fileEvidence)]));
+    return report("identity_observed", { codex: codexVersion, npm: npmVersion, digest }, source);
+  } catch { return refused("read_failed"); }
+}

package/src/codex/cli-installation-targets.ts

@@ -0,0 +1,158 @@
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { win32 } from "node:path";
+import { SHIM_MARKER } from "./shim-templates";
+import type { CodexCliInstallationIdentityInput } from "./cli-installation-identity";
+
+/**
+ * The proof-captured launcher snapshot used to identify the selected candidate.
+ * Every field is optional because older launchers and direct Bun/source runs
+ * supply no snapshot at all; derivation fails closed rather than reading the
+ * ambient environment.
+ */
+export interface CodexCliInstallationSnapshot {
+  readonly codexCliPath?: string | null;
+  readonly path?: string | null;
+  readonly pathExt?: string | null;
+}
+
+export type CodexCliInstallationTargetRefusal =
+  | "unsupported_platform"
+  | "candidate_unavailable"
+  | "unsupported_layout"
+  | "toolchain_unresolved";
+
+export type CodexCliInstallationTargetDerivation =
+  | { readonly kind: "derived"; readonly input: CodexCliInstallationIdentityInput }
+  | { readonly kind: "unavailable"; readonly reason: CodexCliInstallationTargetRefusal };
+
+export interface CodexCliInstallationTargetDeps {
+  readonly platform?: NodeJS.Platform;
+  readonly exists?: (path: string) => boolean;
+  /** Bounded prefix read used only to recognize an OpenCodex-owned wrapper. */
+  readonly fileContains?: (path: string, marker: string) => boolean;
+}
+
+const DEFAULT_PATH_EXT = ".COM;.EXE;.BAT;.CMD;.PS1";
+const SHIM_PROBE_BYTES = 8 * 1024;
+const CODEX_PACKAGE_SUFFIX = "\\node_modules\\@openai\\codex\\bin\\codex.js";
+
+function defaultFileContains(path: string, marker: string): boolean {
+  let descriptor: number | undefined;
+  let contains = false;
+  try {
+    descriptor = openSync(path, "r");
+    const bytes = Buffer.allocUnsafe(SHIM_PROBE_BYTES);
+    const count = readSync(descriptor, bytes, 0, bytes.length, 0);
+    contains = bytes.subarray(0, count).toString("utf8").includes(marker);
+  } catch {
+    contains = false;
+  } finally {
+    if (descriptor !== undefined) {
+      try { closeSync(descriptor); } catch { contains = false; }
+    }
+  }
+  return contains;
+}
+
+/**
+ * First match wins, mirroring PATH resolution: directories in order, and within
+ * each directory every PATHEXT suffix in order (or the exact name when it
+ * already carries an extension). Skipping a hit to keep scanning would attest
+ * something other than the launcher that actually resolves.
+ */
+function scanPath(
+  name: string,
+  pathValue: string | null | undefined,
+  pathExt: string | null | undefined,
+  exists: (path: string) => boolean,
+): string | null {
+  const extensions = (pathExt ?? DEFAULT_PATH_EXT).split(";").map(value => value.trim()).filter(Boolean);
+  const names = /\.[a-z0-9]+$/i.test(name) ? [name] : extensions.map(ext => name + ext.toLowerCase());
+  for (const entry of (pathValue ?? "").split(";")) {
+    const dir = entry.trim().replace(/^"+|"+$/g, "");
+    if (!dir) continue;
+    for (const candidateName of names) {
+      const candidate = win32.join(dir, candidateName);
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Derive the four attestation inputs from the proof-captured launcher snapshot.
+ * Discovery only proposes candidate paths; the held-handle observation remains
+ * the authority, so a stale or racing probe can only produce a refusal, never a
+ * false identity. No ambient environment is read: without a snapshot the result
+ * is unavailable rather than silently trusting the child's environment.
+ */
+export function deriveCodexCliInstallationInput(
+  snapshot: CodexCliInstallationSnapshot,
+  deps: CodexCliInstallationTargetDeps = {},
+): CodexCliInstallationTargetDerivation {
+  if ((deps.platform ?? process.platform) !== "win32") {
+    return { kind: "unavailable", reason: "unsupported_platform" };
+  }
+  const exists = deps.exists ?? existsSync;
+  const fileContains = deps.fileContains ?? defaultFileContains;
+  const configured = snapshot.codexCliPath;
+
+  let candidate: string | null;
+  if (configured) {
+    if (/^[a-z]:[\\/]/i.test(configured)) {
+      if (!exists(configured)) return { kind: "unavailable", reason: "candidate_unavailable" };
+      candidate = win32.normalize(configured);
+    } else {
+      if (configured.includes("/") || configured.includes("\\")) {
+        return { kind: "unavailable", reason: "candidate_unavailable" };
+      }
+      candidate = scanPath(configured, snapshot.path, snapshot.pathExt, exists);
+      if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
+    }
+  } else {
+    candidate = scanPath("codex", snapshot.path, snapshot.pathExt, exists);
+    if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
+  }
+
+  // An OpenCodex wrapper at the npm prefix is our own launcher, not the npm
+  // artifact. The renamed original beside it is the file npm wrote.
+  if (/\.cmd$/i.test(candidate) && fileContains(candidate, SHIM_MARKER)) {
+    const backing = candidate.slice(0, -".cmd".length) + ".opencodex-real.cmd";
+    if (!exists(backing)) return { kind: "unavailable", reason: "unsupported_layout" };
+    candidate = backing;
+  }
+
+  const base = win32.basename(candidate).toLowerCase();
+  let prefix: string;
+  if (base === "codex.cmd" || base === "codex.opencodex-real.cmd") {
+    prefix = win32.dirname(candidate);
+  } else if (candidate.toLowerCase().endsWith(CODEX_PACKAGE_SUFFIX)) {
+    prefix = candidate.slice(0, candidate.length - CODEX_PACKAGE_SUFFIX.length);
+  } else {
+    return { kind: "unavailable", reason: "unsupported_layout" };
+  }
+  if (!exists(win32.join(prefix, "node_modules", "@openai", "codex", "package.json"))) {
+    return { kind: "unavailable", reason: "unsupported_layout" };
+  }
+
+  // The npm cmd-shim itself prefers %dp0%\node.exe before falling back to PATH.
+  let node = win32.join(prefix, "node.exe");
+  if (!exists(node)) {
+    const resolved = scanPath("node.exe", snapshot.path, null, exists);
+    if (!resolved) return { kind: "unavailable", reason: "toolchain_unresolved" };
+    node = resolved;
+  }
+  const npmCli = win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!exists(npmCli)) return { kind: "unavailable", reason: "toolchain_unresolved" };
+
+  return {
+    kind: "derived",
+    input: Object.freeze({
+      candidate,
+      npmPrefix: prefix,
+      npmCli,
+      node,
+      candidateSource: "selected",
+    }),
+  };
+}

package/src/codex/convergence.ts

@@ -36,6 +36,7 @@ import {
   catalogHasRoutedEntries,
   findSupportedNativeTemplate,
   legacyCatalogBackupPath,
+  nativeMultiAgentDefaults,
   parseCatalogJson,
   type RawCatalog,
   type RawEntry,
@@ -69,6 +70,7 @@ import {
   clampCatalogModelsToObservedCodexSupport,
   supportedCodexReasoningEffortsFromObservedCatalog,
 } from "./catalog/effort";
+import { suppressedSyntheticMaxCatalogSlugs } from "./catalog/model-hints";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "./account-namespaces";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
@@ -305,6 +307,7 @@ function prepareCatalog(
     [catalog.models ?? [], ...nativeRecoverySources],
   );
   const catalogModels = nativeCatalogModels;
+  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(config, ordered, catalogModels);
   const routedEntries = buildCatalogEntriesFromObservedState({
     template: template ? JSON.parse(JSON.stringify(template)) : null,
     gptSlugs: [],
@@ -371,8 +374,10 @@ function prepareCatalog(
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    suppressedSyntheticMaxSlugs,
     openaiContextCap,
     nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
+    nativeMultiAgentDefaults: nativeMultiAgentDefaults(baselineCatalogModels),
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],

package/src/codex/history-provider.ts

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { zstdDecompressSync } from "node:zlib";
 import { Database } from "bun:sqlite";
 import { resolveCodexStateDbPath } from "./paths";
+import { openCodexStateForPreflight } from "./history-state-open";
 import { atomicWriteFile, getConfigDir } from "../config";
 import {
   CODEX_HISTORY_RESUMABLE_SOURCES,
@@ -433,7 +434,9 @@ export function preflightCodexHistoryInjection(
     if (!existsSync(resolvedPath)) {
       return restoreEntries.length > 0 ? "history_state_database_missing" : null;
     }
-    db = new Database(resolvedPath, { readonly: true });
+    // Read-only, and narrowed so a cleanly-closed WAL store is inspected rather than refused
+    // (#4943). The open order is the safety property; see history-state-open.ts.
+    db = openCodexStateForPreflight(resolvedPath);
     const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
     const paginatedColumn = columns.some(column => column.name === "history_mode");
     if (paginatedColumn && restoreEntries.length > 0) return HISTORY_RELABEL_STANDS_DOWN;

package/src/codex/history-state-open.ts

@@ -0,0 +1,105 @@
+/**
+ * How the read-only Codex history preflight opens the state store.
+ *
+ * Split out of `history-provider.ts` deliberately. That file is the single largest module in
+ * `src/codex/` and sits just under the repository's 2000-line ratchet; the reasoning below is
+ * load-bearing and long, and appending it there would have pushed the file over. Keeping the
+ * open policy in one small module also puts the decision somewhere it can be read on its own,
+ * which matters because getting it wrong is silent in both directions.
+ */
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { Database, constants as sqliteConstants } from "bun:sqlite";
+
+/**
+ * Read-only open flags that skip WAL shared memory entirely.
+ *
+ * `immutable=1` has to arrive as a `file:` URI, and a URI filename needs SQLITE_OPEN_URI.
+ * Same idiom as the storage scanner, the log-guard inspector and the coordinator doctor, for
+ * the same reason: never touch a foreign store's WAL protocol.
+ */
+const IMMUTABLE_READONLY_FLAGS = sqliteConstants.SQLITE_OPEN_READONLY | sqliteConstants.SQLITE_OPEN_URI;
+
+/** Is this the "there is no shared memory and I may not create it" open failure? */
+export function isStateDbCantOpenError(error: unknown): boolean {
+  const code = typeof error === "object" && error && "code" in error ? String((error as { code?: unknown }).code) : "";
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  // Matched on the code with a message fallback, exactly like classifyRecoverableHistoryError:
+  // the same SQLite condition reaches us as a code on some platforms and as bare text on others.
+  return code === "SQLITE_CANTOPEN" || message.includes("unable to open database file");
+}
+
+/** Which step of the primary attempt a test wants to fail. */
+export type StateDbPreflightOpenPhase = "open" | "first-read";
+
+/**
+ * Test-only knob: force the primary attempt to fail with a supplied error.
+ *
+ * The fallback below turns on a condition this repository cannot reproduce deterministically
+ * from a test: whether a plain read-only open of a cleanly-closed WAL store fails or quietly
+ * creates the `-shm` depends on the platform VFS and on the directory the store sits in.
+ * Pinning the NARROWING — sidecars absent admits the immutable read, either sidecar present
+ * still refuses — therefore needs the failure supplied rather than provoked, or the test would
+ * assert the host's SQLite build instead of this decision (#4943).
+ *
+ * The phase exists because the platforms disagree about WHEN the condition is raised, not only
+ * about whether it is: see the first-read note on `openCodexStateForPreflight`.
+ */
+let openFailureForTests: ((path: string, phase: StateDbPreflightOpenPhase) => unknown) | undefined;
+export function setStateDbPreflightOpenFailureForTests(hook: typeof openFailureForTests): void {
+  openFailureForTests = hook;
+}
+
+/**
+ * Open the Codex state store for the read-only preflight.
+ *
+ * `{ readonly: true }` is tried FIRST and stays the primary path, because it is the only mode
+ * that can see a live WAL: it joins the writer's shared memory, so a thread another process
+ * just migrated to paginated history is visible here and the preflight refuses on it. An
+ * immutable open reads the last checkpointed main database instead. Making that the primary
+ * path would trade a refusal for a stale snapshot, and a refusal this preflight fails to
+ * observe is a config transition that proceeds over history Codex owns — the exact outcome the
+ * whole guard exists to prevent.
+ *
+ * A WAL store closed cleanly is the case that has no shared memory to join. SQLite cannot
+ * create the `-shm` from a read-only connection, so the open fails SQLITE_CANTOPEN on a store
+ * that is perfectly healthy, the catch-all in the preflight folds that into
+ * `history_injection_preflight_unavailable`, and `ocx sync` refuses on every attempt with no
+ * way forward (#4943).
+ *
+ * So the fallback is admitted only in the state where the absent sidecars are what make an
+ * immutable read exact rather than stale: no `-wal` and no `-shm` on disk means no writer is
+ * attached and no committed content sits outside the main database, so the main file IS the
+ * whole store and the two modes cannot disagree. Either sidecar present keeps the original
+ * error and the refusal that follows from it — a `-wal` holds content this connection would
+ * not read, and a `-shm` means a writer is attached, and neither is a store this preflight
+ * may inspect from a snapshot.
+ *
+ * The first read belongs INSIDE this attempt. `sqlite3_open_v2` does not touch page 1, so a
+ * store whose header says WAL is not inspected until the first prepare — which is where the
+ * missing shared memory is discovered on macOS, one caller frame above this function. Opening
+ * here and reading there put the classification and the failure in different scopes: the
+ * fallback was never reached, and the operator got the catch-all refusal the fix was supposed
+ * to remove. Linux hides this because its SQLite materializes the sidecars on that first read
+ * and never fails at all (#4943, macOS CI).
+ */
+export function openCodexStateForPreflight(resolvedPath: string): Database {
+  let db: Database | undefined;
+  try {
+    const forced = openFailureForTests?.(resolvedPath, "open");
+    if (forced) throw forced;
+    db = new Database(resolvedPath, { readonly: true });
+    const forcedRead = openFailureForTests?.(resolvedPath, "first-read");
+    if (forcedRead) throw forcedRead;
+    // Page 1, read while the failure is still this function's to classify.
+    db.query<{ tables: number }, []>("SELECT count(*) AS tables FROM sqlite_master").get();
+    return db;
+  } catch (error) {
+    db?.close();
+    if (!isStateDbCantOpenError(error)) throw error;
+    if (existsSync(`${resolvedPath}-wal`) || existsSync(`${resolvedPath}-shm`)) throw error;
+    // pathToFileURL percent-encodes the reserved characters a naive `file:${path}` would
+    // misparse as a query or fragment.
+    return new Database(`${pathToFileURL(resolvedPath).href}?immutable=1`, IMMUTABLE_READONLY_FLAGS);
+  }
+}

package/src/codex/inject/config-toml.ts

@@ -55,6 +55,46 @@ export function applyEol(content: string, eol: "\r\n" | "\n"): string {
   return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
 }
 
+/** Label Codex shows for the injected provider when the operator has not chosen one. */
+export const DEFAULT_CODEX_PROVIDER_DISPLAY_NAME = "OpenCodex Proxy";
+
+/** Longest label accepted, matching the display-label policy used for provider names. */
+const MAX_CODEX_PROVIDER_DISPLAY_NAME_LENGTH = 128;
+
+/** Would this label put a control character into config.toml? */
+function hasControlCharacter(value: string): boolean {
+  // Checked by code point rather than by a control-character regex, which needs a lint
+  // suppression this repository's hygiene gate rejects — and which reads no more clearly.
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * Which label to write, given whatever the config holds.
+ *
+ * Presentation only, and deliberately separate from identity: routing resolves through the
+ * provider id `opencodex` in the root `model_provider` line and the `[model_providers.opencodex]`
+ * header, neither of which is derived from this value. So a rename cannot reroute a thread or
+ * orphan a row that already names that id (#4810).
+ *
+ * Every rejected value falls back to the default rather than being emitted or omitted. Codex
+ * refuses to load a provider with no name, so writing a blank one would break the whole config
+ * file rather than one thread — strictly worse than the branding it was meant to remove. That is
+ * also why there is no way to suppress the field: suppression here means choosing a neutral
+ * label. A control character or an over-long value is rejected for the same reason, because
+ * `tomlString` would faithfully encode something Codex may still reject.
+ */
+export function resolveCodexProviderDisplayName(configured?: string): string {
+  const trimmed = (configured ?? "").trim();
+  if (!trimmed) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
+  if (trimmed.length > MAX_CODEX_PROVIDER_DISPLAY_NAME_LENGTH) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
+  if (hasControlCharacter(trimmed)) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
+  return trimmed;
+}
+
 export function buildProviderTableBlock(
   port: number,
   supportsWebsockets?: boolean,
@@ -84,12 +124,13 @@ export function buildProviderTableBlock(
 export function buildProviderTableBlockForTarget(
   target: CodexRoutingTarget,
   supportsWebsockets = false,
+  displayName?: string,
 ): string {
   const lines = [
     "",
     OCX_SECTION_MARKER,
     "[model_providers.opencodex]",
-    'name = "OpenCodex Proxy"',
+    `name = ${tomlString(resolveCodexProviderDisplayName(displayName))}`,
     `base_url = ${tomlString(target.baseUrl)}`,
     'wire_api = "responses"',
     // false only in the authless Desktop opt-in (#1107); true keeps the App/TUI account gate.
@@ -518,6 +559,7 @@ export function buildProfileFileForTarget(
   catalogPath?: string | null,
   supportsWebsockets = false,
   fastMode?: boolean,
+  displayName?: string,
 ): string {
   const origin = routingTargetOrigin(target);
   const host = new URL(origin).host;
@@ -542,7 +584,7 @@ export function buildProfileFileForTarget(
   ];
   if (catalogPath) lines.push(`model_catalog_json = ${tomlString(catalogPath)}`);
   if (fastMode !== undefined) lines.push("", "[features]", `fast_mode = ${fastMode ? "true" : "false"}`);
-  lines.push(buildProviderTableBlockForTarget(target, supportsWebsockets).trimEnd(), "");
+  lines.push(buildProviderTableBlockForTarget(target, supportsWebsockets, displayName).trimEnd(), "");
   return lines.join("\n");
 }
 

package/src/codex/inject.ts

@@ -369,7 +369,7 @@ async function injectCodexConfigImpl(
     content =
       content.trimEnd() +
       "\n" +
-      buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}));
+      buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}), config?.codexProviderDisplayName);
     // 3) Keep existing `openai`-tagged threads reaching the proxy (see above). Ownership rules
     // are the Design B ones: a user's own root line is never replaced.
     if (keepRootOverrideAlongsideTable) {
@@ -430,6 +430,7 @@ async function injectCodexConfigImpl(
     catalogPath,
     websocketsEnabled(config ?? {}),
     config?.fastMode,
+    config?.codexProviderDisplayName,
   );
   content = applyEol(content, eol);
 
@@ -492,7 +493,7 @@ async function injectCodexConfigImpl(
    */
   if (hadOcxProviderTableOnDisk && !providerTableMode) {
     content = applyEol(
-      content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {})),
+      content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}), config?.codexProviderDisplayName),
       eol,
     );
   }