@bitkyc08/opencodex 2.11.0 → 2.11.1

package/src/codex/features.ts

@@ -83,7 +83,23 @@ function readConfigText(configPath?: string): string | null {
   }
 }
 
-/** Body lines of a TOML table `[header]` up to (not including) the next table header. */
+/**
+ * Body lines of a TOML table `[header]` up to (not including) the next table header.
+ *
+ * The implementation body is deliberately unchanged by #1295 — only this comment
+ * is new. The scanner is line-based and string-unaware, so it ends the table at
+ * the first line matching `/^\s*\[/` even inside a multi-line value. Twenty call
+ * sites in this file consume its output, most of them by matching a regex
+ * against the returned text, so widening that text changes what they match. An
+ * earlier attempt at #1295 made this scanner string-aware and thereby gave
+ * `getAgentsEnabled`, `getAgentsMaxDepth`, and `getMaxConcurrentThreads` three
+ * new wrong answers.
+ *
+ * The readers that matter for #1295 use a real TOML parse instead (see
+ * `parsedTomlTable`). This stays as the fallback for documents that do not
+ * parse, and as the reader for the remaining call sites until they are migrated
+ * the same way.
+ */
 function tomlTableBody(content: string, header: string): string | null {
   const lines = content.split("\n");
   const escaped = header.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -109,8 +125,34 @@ function tomlBoolInBody(body: string, key: string): boolean | null {
  */
 export function isMultiAgentV2Enabled(configPath?: string): boolean {
   const content = readConfigText(configPath);
+  return multiAgentV2EnabledFromConfigText(content);
+}
+
+/** Parse `multi_agent_v2` from caller-owned config.toml text without consulting disk. */
+export function multiAgentV2EnabledFromConfigText(content: string | null): boolean {
   if (content === null) return false;
 
+  // Prefer a real parse. The hand-written table scanner below cannot distinguish
+  // an assignment from prose that looks like one — a `"""` value containing the
+  // line `enabled = true` reads as the key itself — and TOML has enough value
+  // shapes (multi-line arrays opening on the next line, escapes, comments) that
+  // each near-miss costs another special case (#1295).
+  //
+  // The scanner remains only for a document `Bun.TOML.parse` rejects. That is a
+  // statement about Bun's parser, not about Codex's — the two are separate
+  // implementations and no compatibility evidence is claimed here, so a document
+  // Bun rejects may still be one Codex loads. The fallback is therefore
+  // best-effort and inherits the ambiguity above. It exists because reporting a
+  // feature as disabled on account of an unreadable file presents a failure as
+  // a state.
+  const parsed = parsedTomlTable(content, "features");
+  if (parsed !== null) {
+    const table = plainTomlRecord(parsed.multi_agent_v2);
+    if (table !== null) return table.enabled === true;
+    if (typeof parsed.multi_agent_v2 === "boolean") return parsed.multi_agent_v2;
+    return false;
+  }
+
   const table = tomlTableBody(content, "features.multi_agent_v2");
   if (table !== null) {
     const enabled = tomlBoolInBody(table, "enabled");
@@ -134,6 +176,30 @@ export function isMultiAgentV2Enabled(configPath?: string): boolean {
   return false;
 }
 
+function plainTomlRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+/**
+ * A top-level table from a full TOML parse, or null when the document does not
+ * parse. A parsed document with no such table yields `{}` rather than null: that
+ * is a real answer ("no keys"), while null means "could not read, fall back".
+ */
+function parsedTomlTable(content: string, name: string): Record<string, unknown> | null {
+  const toml = (globalThis as { Bun?: { TOML?: { parse(input: string): unknown } } }).Bun?.TOML;
+  if (!toml) return null;
+  try {
+    const root = plainTomlRecord(toml.parse(content));
+    if (root === null) return null;
+    return plainTomlRecord(root[name]) ?? {};
+  } catch {
+    return null;
+  }
+}
+
+
 /**
  * TRUE when the codex `default_mode_request_user_input` feature is enabled in
  * config.toml — lets a Default-mode session pause and ask the user questions
@@ -145,6 +211,11 @@ export function isMultiAgentV2Enabled(configPath?: string): boolean {
 export function isDefaultModeRequestUserInputEnabled(configPath?: string): boolean {
   const content = readConfigText(configPath);
   if (content === null) return false;
+  // Same reason as the v2 reader: a `"""` value whose prose contains
+  // `default_mode_request_user_input = true` is not an assignment, and a raw
+  // regex over the table body cannot tell the difference (#1295).
+  const parsed = parsedTomlTable(content, "features");
+  if (parsed !== null) return parsed[DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY] === true;
   const features = tomlTableBody(content, "features");
   if (features === null) return false;
   return tomlBoolInBody(features, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY) === true;
@@ -159,6 +230,8 @@ export function isDefaultModeRequestUserInputEnabled(configPath?: string): boole
 export function hasAgentsMaxThreads(configPath?: string): boolean {
   const content = readConfigText(configPath);
   if (content === null) return false;
+  const parsed = parsedTomlTable(content, "agents");
+  if (parsed !== null) return Object.hasOwn(parsed, "max_threads");
   const agents = tomlTableBody(content, "agents");
   if (agents === null) return false;
   return /^\s*max_threads\s*=/m.test(agents);
@@ -168,6 +241,11 @@ export function hasAgentsMaxThreads(configPath?: string): boolean {
 export function getAgentsMaxThreads(configPath?: string): number | null {
   const content = readConfigText(configPath);
   if (content === null) return null;
+  const parsed = parsedTomlTable(content, "agents");
+  if (parsed !== null) {
+    const value = parsed.max_threads;
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null;
+  }
   const agents = tomlTableBody(content, "agents");
   if (agents === null) return null;
   const m = agents.match(/^\s*max_threads\s*=\s*(\d+)\s*(?:#.*)?$/m);

package/src/codex/history-job.ts

@@ -17,6 +17,7 @@
  * Design record: devlog/_fin/260804_codex_write_substrate/020_history_isolation.md.
  */
 import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type {
@@ -135,13 +136,92 @@ export function deriveCodexHistoryOperation(intent: {
   return intent.legacyMode ? "apply-opencodex" : "migrate-openai";
 }
 
+/**
+ * The honest failure clause for one history job outcome.
+ *
+ * The caller adds its own framing ("sync SKIPPED", "could NOT be restored").
+ * The point of the surface argument is that a genuine lock keeps today's
+ * actionable wording, while every other reason stops blaming the Codex app:
+ * an unsafe-path refusal, an unavailable coordinator database, a permission
+ * denial, or a dead worker is a different problem with a different remedy.
+ */
+export function describeHistoryJobFailure(
+  outcome: CodexHistoryJobOutcome,
+  surface: "apply" | "restore" | "recover-legacy",
+  legacyMode = false,
+): string {
+  // Callers only invoke this after observing a failure flag, but that flag is
+  // derived from "not converged", which also covers "skipped". Naming those
+  // two kinds keeps a widened or miscast call site from printing `undefined`.
+  if (outcome.kind === "skipped") {
+    return "the history operation was skipped; no failure was recorded.";
+  }
+  if (outcome.kind === "converged") {
+    return "the history job reported no failure; run 'ocx doctor' if this is unexpected.";
+  }
+  // A busy database reaches here two ways: the lock itself was contended
+  // (blocked/busy), or the lock was acquired and the worker then found SQLite
+  // busy (failed with historyFailureReason "busy"). Both are the same user
+  // situation and deserve the same surface-specific guidance.
+  const busyText = surface === "apply"
+    ? legacyMode
+      ? "the history DB is locked (Codex app/IDE open?). Close it and rerun 'ocx start'."
+      : "the history DB is locked (Codex app/IDE open?). It is retried automatically (while the proxy runs and on every 'ocx start'); to force it now, close the Codex app and run 'ocx sync'."
+    : surface === "recover-legacy"
+      ? "the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command."
+      : "the Codex app appears to be holding the history database. Close Codex and run `ocx restore` again.";
+  if (outcome.kind === "blocked") {
+    if (outcome.reason === "busy") return busyText;
+    switch (outcome.reason) {
+      case "unsafe-path":
+        return "opencodex refused its history lock path (unsafe coordinator namespace); this is not a Codex app lock. Run 'ocx doctor' and check the opencodex runtime directory.";
+      case "database":
+        return "the history coordinator database is unavailable; this is not a Codex app lock. Run 'ocx doctor'.";
+      case "desired_disabled":
+        return "Codex integration is disabled, so the history operation was skipped.";
+      case "desired_enabled":
+        return "Codex integration is enabled, so the history operation was skipped.";
+    }
+  }
+  if (outcome.historyFailureReason === "busy") return busyText;
+  if (outcome.historyFailureReason === "permission") {
+    return "permission was denied while writing Codex history; this is not a Codex app lock. Run 'ocx doctor'.";
+  }
+  switch (outcome.reason) {
+    case "worker-error":
+      return `the history worker failed (${outcome.message}). Run 'ocx doctor'.`;
+    case "worker-died":
+      return "the history worker exited unexpectedly; this is not a Codex app lock. Run 'ocx doctor'.";
+    case "timeout":
+      return "the history worker timed out; this is not a Codex app lock. Run 'ocx doctor'.";
+  }
+}
+
+/**
+ * Worker exceptions travel into user-facing CLI output, and a raw filesystem
+ * error carries absolute paths — on every platform that includes the account
+ * name (`/Users/x`, `/home/x`, `C:\Users\x`). Folding the home directory to
+ * `~` keeps the diagnostic value and drops the identifier.
+ */
+function redactWorkerMessage(message: string): string {
+  const home = homedir();
+  if (home.length <= 1) return message;
+  // Windows spellings vary in case and separator; an exact match would leave
+  // the account name in the message.
+  if (process.platform === "win32") {
+    const escaped = home.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\\/g, "[\\\\/]");
+    return message.replace(new RegExp(escaped, "gi"), "~");
+  }
+  return message.split(home).join("~");
+}
+
 function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutcome {
   if (result.type === "blocked") return { kind: "blocked", reason: result.reason };
   if (result.type === "error") {
     return {
       kind: "failed",
       reason: "worker-error",
-      message: result.message,
+      message: redactWorkerMessage(result.message),
       ...(result.reason ? { historyFailureReason: result.reason } : {}),
     };
   }

package/src/codex/history-lock.ts

@@ -37,6 +37,7 @@ import {
   CodexUserIdentityRefusal,
   resolveCodexHistorySerializationDatabasePath,
   resolveEffectiveUserIdentity,
+  samePathIdentity,
 } from "./user-identity";
 
 /**
@@ -183,7 +184,7 @@ export function withHistoryWriteSerialization<T>(
     }
     const opened = lstatSync(databasePath);
     if (opened.isSymbolicLink() || !opened.isFile()
-      || realpathSync.native(databasePath) !== databasePath) {
+      || !samePathIdentity(realpathSync.native(databasePath), databasePath)) {
       return { kind: "unavailable", reason: "unsafe-path" };
     }
 

package/src/codex/history-provider.ts

@@ -722,16 +722,17 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
   }
 }
 
-export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): { rows: number; files: number; failed?: true } {
+export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): CodexHistorySyncResult {
   if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
-  return withHistoryRetry(() => {
+  const retried = withHistoryRetryResult(() => {
     const db = openStateDb(stateDbPath);
     try {
       return ejectRemainingOpencodexHistory(db);
     } finally {
       db.close();
     }
-  }) ?? { rows: 0, files: 0, failed: true };
+  });
+  return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
 }
 
 /**

package/src/codex/inject.ts

@@ -38,9 +38,11 @@ import { withCatalogWriteSerialization } from "./catalog-write-serialization";
 import { restoreCodexCatalogWithPermit } from "./catalog/sync";
 import { syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
 import {
+  describeHistoryJobFailure,
   deriveCodexHistoryOperation,
   resolveCodexHistoryJobTarget,
   runCodexHistoryJob,
+  type CodexHistoryJobOutcome,
 } from "./history-job";
 import {
   OCX_SECTION_MARKER,
@@ -1034,11 +1036,7 @@ export async function injectCodexConfig(
     config?.syncResumeHistory === false
       ? `  Codex resume history: left unchanged (syncResumeHistory=false).\n`
       : history.failed
-        ? legacyMode
-          ? `  ⚠️ Codex resume history sync SKIPPED: the history DB is locked (Codex app/IDE open?). Close it and rerun 'ocx start'.\n`
-          : // Honest in every caller context: the daemon retries in the background while it runs,
-            // and this inject path re-runs the migration on every future start/sync anyway.
-            `  ⚠️ Codex resume history migration deferred: the history DB is locked (Codex app/IDE open?). It is retried automatically (while the proxy runs and on every 'ocx start'); to force it now, close the Codex app and run 'ocx sync'.\n`
+        ? formatApplyHistoryFailure(historyOutcome, legacyMode)
         : legacyMode
           ? `  Codex resume history: ${history.rows} thread(s) made visible for opencodex; originals backed up for restore.\n`
           : migratedRows > 0
@@ -1250,7 +1248,7 @@ export interface CodexNativeRestoreResult {
   };
 }
 
-function failedHistoryRestore(reason?: CodexHistoryFailureReason): CodexRestoreHistoryResult {
+function failedHistoryRestore(reason?: CodexHistoryFailureReason, detail?: string): CodexRestoreHistoryResult {
   return {
     state: "failed",
     changed: false,
@@ -1260,10 +1258,36 @@ function failedHistoryRestore(reason?: CodexHistoryFailureReason): CodexRestoreH
     ejectedRows: 0,
     message: reason === "permission"
       ? "Codex resume history could NOT be restored because permission was denied."
-      : "Codex resume history could NOT be restored — the Codex app appears to be holding the history database.",
+      : reason === "busy"
+        ? "Codex resume history could NOT be restored — the Codex app appears to be holding the history database."
+        : detail
+          ? `Codex resume history could NOT be restored: ${detail}`
+          : "Codex resume history could NOT be restored; the reason was not recorded. Run 'ocx doctor'.",
   };
 }
 
+/**
+ * Restore failure wording for a Worker outcome.
+ *
+ * Only a genuine busy result blames the Codex app. An unsafe-path refusal, an
+ * unavailable coordinator database, a permission denial, or a dead/timed-out
+ * worker is a different problem; the old collapse made every one of those read
+ * as "the Codex app is holding the database" (issue #1191). `busy` and
+ * `permission` keep the restore-specific sentence built by
+ * `failedHistoryRestore`; every other reason reuses the single formatter so
+ * the two modules cannot drift apart.
+ */
+export function failedHistoryRestoreFromOutcome(
+  outcome: Extract<CodexHistoryJobOutcome, { kind: "blocked" | "failed" }>,
+): CodexRestoreHistoryResult {
+  if (outcome.kind === "blocked" && outcome.reason === "busy") return failedHistoryRestore("busy");
+  if (outcome.kind === "failed" && outcome.historyFailureReason === "busy") return failedHistoryRestore("busy");
+  if (outcome.kind === "failed" && outcome.historyFailureReason === "permission") {
+    return failedHistoryRestore("permission");
+  }
+  return failedHistoryRestore(undefined, describeHistoryJobFailure(outcome, "restore"));
+}
+
 function externalProviderRestoreResult(activeProvider: string): CodexNativeRestoreResult {
   const message = `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`;
   return {
@@ -1499,11 +1523,9 @@ export async function restoreNativeCodexAsync(
               ? "Codex integration was disabled; history restoration was skipped."
               : "Codex integration was enabled; history restoration was skipped.",
           }
-      : outcome.kind === "blocked" && outcome.reason === "busy"
-        ? failedHistoryRestore("busy")
-        : outcome.kind === "failed"
-          ? failedHistoryRestore(outcome.historyFailureReason)
-          : failedHistoryRestore();
+      : outcome.kind === "blocked" || outcome.kind === "failed"
+        ? failedHistoryRestoreFromOutcome(outcome)
+        : failedHistoryRestore();
   const base = catalog.removed > 0
     ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
     : config.message;
@@ -1572,3 +1594,25 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
 export function getCodexConfigPath(): string {
   return CODEX_CONFIG_PATH;
 }
+
+/**
+ * Frame one failed apply history job honestly.
+ *
+ * A genuine lock keeps the established deferred/SKIPPED wording; any other
+ * reason names itself instead of blaming the Codex app/IDE.
+ */
+export function formatApplyHistoryFailure(outcome: CodexHistoryJobOutcome, legacyMode: boolean): string {
+  // A busy database is a deferral no matter which half observed it: the lock
+  // contended (blocked/busy), or the worker acquired the lock and then found
+  // SQLite busy (failed with a busy history reason). Only those keep the
+  // deferred headline; every other failure is a real "NOT changed".
+  const busy =
+    (outcome.kind === "blocked" && outcome.reason === "busy") ||
+    (outcome.kind === "failed" && outcome.historyFailureReason === "busy");
+  const headline = legacyMode
+    ? "Codex resume history sync SKIPPED"
+    : busy
+      ? "Codex resume history migration deferred"
+      : "Codex resume history NOT changed";
+  return `  ⚠️ ${headline}: ${describeHistoryJobFailure(outcome, "apply", legacyMode)}\n`;
+}

package/src/codex/model-cache.ts

@@ -42,7 +42,12 @@ export type ProviderModelDiscoveryFailure = ProviderModelDiscoveryStatus extends
     : never
   : never;
 
+/** Whether clearing cache rows also revokes in-flight discovery authority. */
+export type ModelCacheClearReason = "authority" | "eviction";
+
 const cache = new Map<string, CacheEntry>();
+let globalCacheGeneration = 0;
+const providerCacheGenerations = new Map<string, number>();
 let cacheBytes = 0;
 let oldestCachedProvider: string | undefined;
 let oldestCachedAt: number | null = null;
@@ -155,7 +160,29 @@ export function getStaleCached(provider: string): CatalogModel[] | null {
   return cache.get(provider)?.models ?? null;
 }
 
-export function setCached(provider: string, models: CatalogModel[], now = Date.now()): void {
+/** Capture the cache generation before an asynchronous provider discovery starts. */
+export function captureModelCacheGeneration(provider: string): string {
+  if (!providerCacheGenerations.has(provider)) providerCacheGenerations.set(provider, 0);
+  return `${globalCacheGeneration}:${providerCacheGenerations.get(provider)!}`;
+}
+
+/** Whether a discovery started under {@link captureModelCacheGeneration} may still write. */
+export function isModelCacheGenerationCurrent(provider: string, generation: string): boolean {
+  return generation === captureModelCacheGeneration(provider);
+}
+
+/**
+ * Store a live result unless the cache was cleared while that asynchronous discovery was running.
+ * The optional generation keeps existing direct cache writers unchanged while discovery callers can
+ * prevent a previous OAuth account from repopulating the current account's cache.
+ */
+export function setCached(
+  provider: string,
+  models: CatalogModel[],
+  now = Date.now(),
+  generation?: string,
+): boolean {
+  if (generation !== undefined && !isModelCacheGenerationCurrent(provider, generation)) return false;
   deleteCachedProvider(provider);
   const sizeBytes = modelCacheEncoder.encode(provider).byteLength
     + modelCacheEncoder.encode(JSON.stringify(models)).byteLength;
@@ -166,16 +193,25 @@ export function setCached(provider: string, models: CatalogModel[], now = Date.n
     oldestCachedAt = now;
   }
   enforceAppOwnedMemoryBudget();
+  return true;
 }
 
 /** Drop one provider's cache (or all) so the next resolve forces a live re-fetch. */
-export function clearModelCache(provider?: string): void {
+export function clearModelCache(
+  provider?: string,
+  reason: ModelCacheClearReason = "authority",
+): void {
+  const revokesInFlightDiscovery = reason === "authority";
   if (provider) {
+    if (revokesInFlightDiscovery) {
+      providerCacheGenerations.set(provider, (providerCacheGenerations.get(provider) ?? 0) + 1);
+    }
     deleteCachedProvider(provider);
     failureAt.delete(provider);
     discoveryStatus.delete(provider);
     liveModelCounts.delete(provider);
   } else {
+    if (revokesInFlightDiscovery) globalCacheGeneration += 1;
     cache.clear();
     cacheBytes = 0;
     oldestCachedProvider = undefined;
@@ -192,16 +228,20 @@ export function reconcileModelCacheProviders(
 ): number {
   if (generation <= lastReconciledGeneration) return 0;
   const removedProviders = new Set<string>();
-  for (const store of [failureAt, discoveryStatus, liveModelCounts]) {
-    for (const provider of store.keys()) {
-      if (validProviders.has(provider)) continue;
-      store.delete(provider);
-      removedProviders.add(provider);
-    }
-  }
-  for (const provider of cache.keys()) {
+  const trackedProviders = new Set([
+    ...providerCacheGenerations.keys(),
+    ...failureAt.keys(),
+    ...discoveryStatus.keys(),
+    ...liveModelCounts.keys(),
+    ...cache.keys(),
+  ]);
+  for (const provider of trackedProviders) {
     if (validProviders.has(provider)) continue;
+    providerCacheGenerations.set(provider, (providerCacheGenerations.get(provider) ?? 0) + 1);
     deleteCachedProvider(provider);
+    failureAt.delete(provider);
+    discoveryStatus.delete(provider);
+    liveModelCounts.delete(provider);
     removedProviders.add(provider);
   }
   lastReconciledGeneration = generation;

package/src/codex/transition-state.ts

@@ -34,6 +34,7 @@ import {
   CodexUserIdentityRefusal,
   resolveCodexCoordinatorDatabasePath,
   resolveEffectiveUserIdentity,
+  samePathIdentity,
 } from "./user-identity";
 
 const COORDINATOR_SCHEMA_VERSION = 1;
@@ -352,6 +353,7 @@ export function openCodexCoordinatorTransaction(finalDatabasePath: string): Code
   let lastResult: TransitionStateUpdate | undefined;
   let initialIdentity: string | undefined;
   let databaseWasAbsent = false;
+  let databaseWasEmpty = false;
 
   try {
     try {
@@ -359,6 +361,12 @@ export function openCodexCoordinatorTransaction(finalDatabasePath: string): Code
       if (before.isSymbolicLink() || !before.isFile()) {
         throw new CodexUserIdentityRefusal("The coordinator database path is not a real file.");
       }
+      // sqlite3_open_v2(..., SQLITE_OPEN_CREATE) makes the pathname visible
+      // before the first schema write. A racing process can therefore observe a
+      // real but zero-byte file that carries no coordinator authority yet. Treat
+      // that exact state like ENOENT; any non-empty unversioned database remains
+      // legacy-ambiguous below.
+      databaseWasEmpty = before.size === 0;
       if (process.platform !== "win32") {
         const uid = process.getuid?.();
         // Ownership is decided here; MODE is not.
@@ -415,7 +423,7 @@ export function openCodexCoordinatorTransaction(finalDatabasePath: string): Code
     initialIdentity = `${opened.dev}:${opened.ino}`;
     database.exec("PRAGMA busy_timeout = 0; PRAGMA locking_mode = NORMAL; BEGIN IMMEDIATE");
     transactionOpen = true;
-    initialize(database, databaseWasAbsent);
+    initialize(database, databaseWasAbsent || databaseWasEmpty);
   } catch (cause) {
     if (transactionOpen) {
       try { database?.exec("ROLLBACK"); } catch { /* close releases the transaction */ }
@@ -433,7 +441,7 @@ export function openCodexCoordinatorTransaction(finalDatabasePath: string): Code
     const entry = lstatSync(finalDatabasePath);
     if (entry.isSymbolicLink() || !entry.isFile()
       || `${entry.dev}:${entry.ino}` !== initialIdentity
-      || realpathSync.native(finalDatabasePath) !== finalDatabasePath) {
+      || !samePathIdentity(realpathSync.native(finalDatabasePath), finalDatabasePath)) {
       throw new CodexUserIdentityRefusal("The coordinator database path was substituted.");
     }
   };

package/src/codex/user-identity.ts

@@ -123,7 +123,7 @@ function ensurePrivatePosixDirectory(path: string, uid: number): void {
   assertPrivatePosixDirectory(path, uid);
 }
 
-function resolvePosixRuntimeRoot(uid: number): string {
+function resolveTrustedPosixTmp(): string {
   let realTmp: string;
   try {
     realTmp = realpathSync.native(POSIX_TMP_PATH);
@@ -138,12 +138,82 @@ function resolvePosixRuntimeRoot(uid: number): string {
     if (cause instanceof CodexUserIdentityRefusal) throw cause;
     refuse("The system temporary directory cannot be trusted.", cause);
   }
+  return realTmp;
+}
 
+function resolvePosixRuntimeRoot(uid: number): string {
+  const realTmp = resolveTrustedPosixTmp();
   const root = join(realTmp, `opencodex-runtime-v1-${uid}`);
   ensurePrivatePosixDirectory(root, uid);
   return root;
 }
 
+export type CoordinatorNamespaceProbe =
+  | { readonly status: "ok"; readonly root: string }
+  | { readonly status: "missing" };
+
+/**
+ * Read-only namespace probe for diagnostics (`ocx doctor`).
+ *
+ * Unlike the runtime resolvers, this never creates the root or the lock
+ * directories: a doctor run must observe the namespace, not initialize it.
+ * A missing namespace is reported as `missing` instead of refused, so a fresh
+ * machine does not read as a broken one; an existing but unsafe namespace is
+ * refused exactly like the creating path would refuse it.
+ */
+export function probeCodexCoordinatorNamespace(identity: UserIdentity): CoordinatorNamespaceProbe {
+  if (identity.platform === "posix") {
+    const root = join(resolveTrustedPosixTmp(), `opencodex-runtime-v1-${identity.uid}`);
+    let entry;
+    try {
+      entry = lstatSync(root);
+    } catch (cause) {
+      const code = cause && typeof cause === "object" && "code" in cause
+        ? String((cause as { code?: unknown }).code)
+        : "";
+      if (code === "ENOENT") return { status: "missing" };
+      refuse("The Codex coordinator namespace cannot be inspected.", cause);
+    }
+    if (entry.isSymbolicLink() || !entry.isDirectory()) {
+      refuse("The Codex coordinator namespace is not a real directory.");
+    }
+    if (entry.uid !== identity.uid || (entry.mode & 0o777) !== POSIX_PRIVATE_MODE) {
+      refuse("The Codex coordinator namespace has unsafe ownership or permissions.");
+    }
+    return { status: "ok", root };
+  }
+
+  if (!SID_PATTERN.test(identity.sid)) refuse("The coordinator identity contains an invalid SID.");
+  const localAppData = powershellValue(
+    "[Environment]::GetFolderPath([Environment+SpecialFolder]::LocalApplicationData)",
+  );
+  if (!isAbsolute(localAppData)) refuse("Windows LocalAppData resolution returned a relative path.");
+  const root = resolve(localAppData, "OpenCodex", "Runtime", "v1", identity.sid.toUpperCase());
+  let entry;
+  try {
+    entry = lstatSync(root);
+  } catch (cause) {
+    const code = cause && typeof cause === "object" && "code" in cause
+      ? String((cause as { code?: unknown }).code)
+      : "";
+    if (code === "ENOENT") return { status: "missing" };
+    refuse("The Windows coordinator namespace cannot be inspected.", cause);
+  }
+  if (entry.isSymbolicLink() || !entry.isDirectory()) {
+    refuse("The Windows coordinator namespace is not a real directory.");
+  }
+  try {
+    const real = realpathSync.native(root);
+    if (!samePathIdentity(real, root, "win32")) {
+      refuse("The Windows coordinator namespace is redirected by a junction or reparse point.");
+    }
+    return { status: "ok", root: real };
+  } catch (cause) {
+    if (cause instanceof CodexUserIdentityRefusal) throw cause;
+    refuse("The Windows coordinator namespace cannot be resolved.", cause);
+  }
+}
+
 function resolveWindowsRuntimeRoot(identity: Extract<UserIdentity, { platform: "win32" }>): string {
   if (!SID_PATTERN.test(identity.sid)) refuse("The coordinator identity contains an invalid SID.");
   const localAppData = powershellValue(
@@ -160,7 +230,45 @@ function resolveWindowsRuntimeRoot(identity: Extract<UserIdentity, { platform: "
   } catch (cause) {
     refuse("The Windows coordinator namespace cannot be created.", cause);
   }
-  return root;
+  // Canonicalize before anything is keyed on the path: a junctioned or
+  // differently-cased LocalAppData must land on ONE namespace, or two processes
+  // that share the real directory would build different lock paths and never
+  // contend. The lock modules also compare this path against realpath, so a
+  // non-canonical spelling here would read as "unsafe" on every acquisition.
+  //
+  // Canonicalizing must only ever fold spelling (case, separators). If the
+  // realpath lands somewhere else entirely, a component of the namespace is a
+  // junction/reparse redirect; accepting the target would convert the old
+  // refusal into silently opening the redirected location, so refuse instead.
+  try {
+    const real = realpathSync.native(root);
+    if (!samePathIdentity(real, root, "win32")) {
+      refuse("The Windows coordinator namespace is redirected by a junction or reparse point.");
+    }
+    return real;
+  } catch (cause) {
+    if (cause instanceof CodexUserIdentityRefusal) throw cause;
+    refuse("The Windows coordinator namespace cannot be resolved.", cause);
+  }
+}
+
+/**
+ * Windows path identity is case-insensitive; everywhere else it is exact.
+ *
+ * The lock modules compare a requested lock path against its own realpath, and
+ * byte equality refuses legitimate Windows spellings (drive-letter case, mixed
+ * component casing) as "unsafe". This is the same semantics
+ * `history-provider.ts` already applies to manifest paths; the platform
+ * argument exists so both branches are testable on any host.
+ */
+export function samePathIdentity(
+  a: string,
+  b: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  const left = resolve(a);
+  const right = resolve(b);
+  return platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 
 export const resolveCodexCoordinatorDatabasePath: ResolveCodexCoordinatorDatabasePath = (