@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/codex/history-provider.ts

@@ -3,7 +3,7 @@ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, re
 import { dirname, join, resolve } from "node:path";
 import { zstdDecompressSync } from "node:zlib";
 import { Database } from "bun:sqlite";
-import { CODEX_HOME } from "./paths";
+import { resolveCodexStateDbPath } from "./paths";
 import { atomicWriteFile, getConfigDir } from "../config";
 
 /**
@@ -13,7 +13,6 @@ import { atomicWriteFile, getConfigDir } from "../config";
  */
 export const MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
 
-const STATE_DB_PATH = join(CODEX_HOME, "state_5.sqlite");
 /**
  * The manifest that shadows one state database.
  *
@@ -26,7 +25,6 @@ export function historyBackupPathFor(stateDbPath: string): string {
   const id = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
   return join(getConfigDir(), `codex-history-backup-${id}.json`);
 }
-const HISTORY_BACKUP_PATH = historyBackupPathFor(STATE_DB_PATH);
 const RESUMABLE_SOURCES = ["cli", "vscode"] as const;
 
 /**
@@ -690,8 +688,8 @@ function openaiRestoreIsNoop(stateDbPath: string, backupPath: string): boolean {
 
 export function syncCodexHistoryProvider(
   provider: CodexHistoryProvider,
-  stateDbPath = STATE_DB_PATH,
-  backupPath = HISTORY_BACKUP_PATH,
+  stateDbPath = resolveCodexStateDbPath(),
+  backupPath = historyBackupPathFor(stateDbPath),
   opts: { skipWhenProvablyNoop?: boolean } = {},
 ): CodexHistorySyncResult {
   // Opt-in steady-state gate (Design B loopback callers only): default semantics of
@@ -824,7 +822,7 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
   }
 }
 
-export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): CodexHistorySyncResult {
+export function restoreLegacyOpenaiHistory(stateDbPath = resolveCodexStateDbPath()): CodexHistorySyncResult {
   if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
   const retried = withHistoryRetryResult(() => {
     const db = openStateDb(stateDbPath);
@@ -844,8 +842,8 @@ export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): CodexHi
  * per tick so a locked DB never stalls the event loop beyond one sqlite busy wait.
  */
 export function migrateHistoryToOpenai(
-  stateDbPath = STATE_DB_PATH,
-  backupPath = HISTORY_BACKUP_PATH,
+  stateDbPath = resolveCodexStateDbPath(),
+  backupPath = historyBackupPathFor(stateDbPath),
   opts: { attempts?: number; delayMs?: number; sleepFn?: (ms: number) => void } = {},
 ): CodexHistorySyncResult {
   if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
@@ -948,7 +946,10 @@ export interface PendingHistoryCount {
  * pending predicate mirrors ejectRemainingOpencodexHistory exactly — rows eject ignores
  * (empty first_user_message) are not counted, so 0 really means "migration done".
  */
-export function countPendingOpencodexHistory(stateDbPath = STATE_DB_PATH, backupPath = HISTORY_BACKUP_PATH): PendingHistoryCount {
+export function countPendingOpencodexHistory(
+  stateDbPath = resolveCodexStateDbPath(),
+  backupPath = historyBackupPathFor(stateDbPath),
+): PendingHistoryCount {
   let backupEntries = 0;
   try {
     const manifest = readBackup(backupPath, stateDbPath);

package/src/codex/inject.ts

@@ -129,6 +129,12 @@ export interface InjectCodexOptions {
    * caller that is willing to wait can raise it.
    */
   lockTimeoutMs?: number;
+  /**
+   * Validate the same config transformations and write-coordination eligibility without
+   * changing the journal, config, profile, catalog, cache, or history. Sync uses this before
+   * provider discovery so a deterministic config refusal cannot degrade an existing catalog.
+   */
+  validateOnly?: boolean;
 }
 
 function configuredManagedSubagentDefaults(
@@ -660,7 +666,7 @@ export async function injectCodexConfig(
   if (activeProvider) {
     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
     // replay that stale snapshot over externally managed config.
-    removeJournal();
+    if (!options.validateOnly) removeJournal();
     const nativeSubagentDefaultsWarning = configuredManagedSubagentDefaults(
       config,
     )
@@ -867,6 +873,13 @@ export async function injectCodexConfig(
     };
   }
 
+  if (options.validateOnly) {
+    return {
+      success: true,
+      message: "Codex config injection preflight passed; no files were changed.",
+    };
+  }
+
   const applyNativeArtifacts = (): void => {
     writeJournal({
       currentStateIsNative: !hasInjectedCodexRouting(rawContent),

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

@@ -20,8 +20,15 @@ export type NativeMainStartupGateSnapshot =
   | { status: "ready"; homeId: string | null }
   | {
       status: "blocked";
-      homeId: string;
-      reason: "recovery-pending" | "manual-recovery" | "owner-conflict" | "owner-unavailable" | "stage-cleanup-required";
+      homeId: string | null;
+      reason:
+        | "foreign-ownership"
+        | "ownership-unknown"
+        | "recovery-pending"
+        | "manual-recovery"
+        | "owner-conflict"
+        | "owner-unavailable"
+        | "stage-cleanup-required";
     };
 
 export interface NativeMainStartupGateDeps {
@@ -42,6 +49,10 @@ export interface NativeMainStartupLifecycle {
 let epoch = 0;
 let snapshot: NativeMainStartupGateSnapshot = { status: "ready", homeId: null };
 let settled: Promise<NativeMainStartupGateSnapshot> = Promise.resolve(snapshot);
+export type NativeMainServiceOwnershipBlockReason =
+  | "foreign-ownership"
+  | "ownership-unknown";
+const serviceOwnershipRefs = new Map<NativeMainServiceOwnershipBlockReason, number>();
 interface StartupEntry {
   homeId: string;
   refs: number;
@@ -295,6 +306,37 @@ export function startNativeMainStartupLifecycle(
   };
 }
 
+function activeServiceOwnershipBlockReason(): NativeMainServiceOwnershipBlockReason | null {
+  if ((serviceOwnershipRefs.get("foreign-ownership") ?? 0) > 0) return "foreign-ownership";
+  if ((serviceOwnershipRefs.get("ownership-unknown") ?? 0) > 0) return "ownership-unknown";
+  return null;
+}
+
+function serviceOwnershipSnapshot(
+  reason: NativeMainServiceOwnershipBlockReason,
+): NativeMainStartupGateSnapshot {
+  return { status: "blocked", homeId: null, reason };
+}
+
+/** Close native-main admission without resolving or creating any CODEX_HOME artifacts. */
+export function blockNativeMainStartupForUnownedServiceHome(
+  reason: NativeMainServiceOwnershipBlockReason,
+): NativeMainStartupLifecycle {
+  serviceOwnershipRefs.set(reason, (serviceOwnershipRefs.get(reason) ?? 0) + 1);
+  let released = false;
+  return {
+    homeId: null,
+    settled: Promise.resolve(serviceOwnershipSnapshot(reason)),
+    async release() {
+      if (released) return;
+      released = true;
+      const remaining = Math.max(0, (serviceOwnershipRefs.get(reason) ?? 0) - 1);
+      if (remaining === 0) serviceOwnershipRefs.delete(reason);
+      else serviceOwnershipRefs.set(reason, remaining);
+    },
+  };
+}
+
 export function bindNativeMainStartupLifecycle(server: object, lifecycle: NativeMainStartupLifecycle): void {
   serverLifecycles.set(server, lifecycle);
 }
@@ -307,7 +349,7 @@ export async function releaseNativeMainStartupLifecycle(server: object): Promise
 }
 
 export function isNativeMainTrafficBlocked(): boolean {
-  return snapshot.status === "blocked";
+  return activeServiceOwnershipBlockReason() !== null || snapshot.status === "blocked";
 }
 
 /**
@@ -340,9 +382,13 @@ export function completeNativeMainRecovery(homeId: string): boolean {
 }
 
 export function nativeMainStartupGateSnapshot(): NativeMainStartupGateSnapshot {
+  const reason = activeServiceOwnershipBlockReason();
+  if (reason) return serviceOwnershipSnapshot(reason);
   return { ...snapshot };
 }
 
 export function waitForNativeMainStartupGate(): Promise<NativeMainStartupGateSnapshot> {
+  const reason = activeServiceOwnershipBlockReason();
+  if (reason) return Promise.resolve(serviceOwnershipSnapshot(reason));
   return settled;
 }

package/src/codex/native-residue.ts

@@ -30,6 +30,7 @@ import {
   DEFAULT_CATALOG_PATH,
   getCodexHome,
   readRootTomlString,
+  resolveCodexStateDbPath,
 } from "./paths";
 
 export type NativeResidueSurface =
@@ -77,7 +78,6 @@ const PROFILE_FILE_NAME = basename(CODEX_PROFILE_PATH);
 const CATALOG_FILE_NAME = basename(DEFAULT_CATALOG_PATH);
 const MODELS_CACHE_FILE_NAME = basename(CODEX_MODELS_CACHE_PATH);
 const JOURNAL_FILE_NAME = "opencodex-journal.json";
-const HISTORY_DATABASE_FILE_NAME = "state_5.sqlite";
 const ROUTED_CATALOG_DESCRIPTION_PREFIX = "Routed via opencodex → ";
 const MAX_ROLLOUT_INSPECTION_BYTES = 64 * 1024 * 1024;
 const ROLLOUT_READ_CHUNK_BYTES = 64 * 1024;
@@ -640,8 +640,20 @@ export function classifyNativeRoutedResidue(): NativeRoutedResidueResult {
     return indeterminate("partial-write", unresolved, `CODEX_HOME cannot be resolved: ${errorReason(error)}`);
   }
 
-  const stateDatabasePath = join(codexHome, HISTORY_DATABASE_FILE_NAME);
   const configPath = join(codexHome, CONFIG_FILE_NAME);
+  let stateDatabasePath: string;
+  try {
+    stateDatabasePath = resolveCodexStateDbPath({ codexHome });
+  } catch (error) {
+    // Residue classification is a total, read-only safety boundary. An
+    // indeterminate SQLite authority must refuse coordination without escaping
+    // as an exception or falling through to a different state database.
+    return indeterminate(
+      "config",
+      configPath,
+      `SQLite home cannot be resolved: ${errorReason(error)}`,
+    );
+  }
   const profilePath = join(codexHome, PROFILE_FILE_NAME);
   const modelsCachePath = join(codexHome, MODELS_CACHE_FILE_NAME);
   const journalPath = join(codexHome, JOURNAL_FILE_NAME);

package/src/codex/paths.ts

@@ -1,4 +1,4 @@
-import { realpathSync, statSync } from "node:fs";
+import { readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { expandUserPath } from "../config";
 import { defaultCodexHome } from "./home";
@@ -34,6 +34,80 @@ export function getCodexHome(): string {
   return resolveCodexHome();
 }
 
+export interface CodexSqliteHomeDeps {
+  env?: NodeJS.ProcessEnv;
+  cwd?: () => string;
+  codexHome?: string;
+  readConfig?: (path: string) => string;
+}
+
+type RootTomlStringState =
+  | { kind: "absent" }
+  | { kind: "value"; value: string }
+  | { kind: "invalid" };
+
+/**
+ * Parse the authoritative SQLite setting without changing the tolerant helper
+ * used by injection/catalog readers. History ownership must distinguish a
+ * missing key from a present value that Codex cannot interpret as a path.
+ */
+function readAuthoritativeRootTomlString(content: string, key: string): RootTomlStringState {
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(content);
+  } catch {
+    return { kind: "invalid" };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "invalid" };
+  const root = parsed as Record<string, unknown>;
+  if (!Object.prototype.hasOwnProperty.call(root, key)) return { kind: "absent" };
+  const value = root[key];
+  if (typeof value !== "string" || value.trim() === "") return { kind: "invalid" };
+  return { kind: "value", value: value.trim() };
+}
+
+/**
+ * Resolve Codex's SQLite state root at call time.
+ *
+ * Codex permits SQLite-backed state to live outside CODEX_HOME, especially for
+ * Windows Desktop sessions whose app-server runs in WSL. Keep the precedence
+ * identical to Codex: root config, then environment, then the effective home.
+ */
+export function resolveCodexSqliteHome(deps: CodexSqliteHomeDeps = {}): string {
+  const codexHome = deps.codexHome ?? getCodexHome();
+  const readConfig = deps.readConfig ?? (path => readFileSync(path, "utf8"));
+  const configPath = join(codexHome, "config.toml");
+  let configured: RootTomlStringState = { kind: "absent" };
+  try {
+    configured = readAuthoritativeRootTomlString(readConfig(configPath), "sqlite_home");
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException | undefined)?.code !== "ENOENT") {
+      throw new Error(
+        `Codex config could not be read while resolving sqlite_home: ${configPath}`,
+        { cause },
+      );
+    }
+    // A genuinely absent config cannot contain the authoritative root override,
+    // so only ENOENT may continue to the documented environment/home fallback.
+  }
+  if (configured.kind === "invalid") {
+    throw new Error(`Codex config has an invalid sqlite_home setting: ${configPath}`);
+  }
+  const raw = configured.kind === "value"
+    ? configured.value
+    : (deps.env ?? process.env).CODEX_SQLITE_HOME?.trim() || "";
+  if (!raw) return codexHome;
+  const expanded = expandUserPath(raw);
+  return isAbsolute(expanded)
+    ? resolve(expanded)
+    : resolve((deps.cwd ?? process.cwd)(), expanded);
+}
+
+/** Active Codex thread-state database, derived from the call-time SQLite root. */
+export function resolveCodexStateDbPath(deps: CodexSqliteHomeDeps = {}): string {
+  return join(resolveCodexSqliteHome(deps), "state_5.sqlite");
+}
+
 export function tomlString(value: string): string {
   return JSON.stringify(value);
 }