@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/codex/desired-state.ts

@@ -22,6 +22,7 @@
  */
 import { loadConfig, mutatePersistedConfig } from "../config";
 import type { OcxClientIntegrationsConfig, OcxConfig } from "../types";
+import { runStartupReadinessSync, type ReadinessGate, type SyncOutcomeLike } from "../server/readiness";
 
 /** Clients whose durable intent this module owns. */
 export type DurableIntentClientId = keyof OcxClientIntegrationsConfig;
@@ -36,8 +37,11 @@ export type DurableIntentClientId = keyof OcxClientIntegrationsConfig;
 export interface CodexStartupSyncOutcome {
   catalogWritten: boolean;
   cacheSynced: boolean;
+  /** Readiness-observable fields carried by the raw startup sync. */
+  ok?: boolean;
+  warning?: string;
 }
-export type CodexStartupSync = (port: number) => Promise<CodexStartupSyncOutcome | undefined>;
+export type CodexStartupSync = (port: number) => Promise<SyncOutcomeLike | undefined>;
 
 export type CodexDesiredStateResult =
   | { readonly ok: true; readonly status: "committed" | "unchanged"; readonly enabled: boolean }
@@ -66,6 +70,11 @@ export function codexIntegrationEnabled(config: Pick<OcxConfig, "clientIntegrati
   return integrationEnabled(config, "codex");
 }
 
+/** Whether a Codex sync is permitted for this admitted config snapshot. */
+export function shouldSyncCodexOnStart(config: Pick<OcxConfig, "clientIntegrations">): boolean {
+  return codexIntegrationEnabled(config);
+}
+
 /**
  * Grok's toggle SHIPPED without this, which is the bug: it strips the fence in
  * `~/.grok/config.toml` and records nothing, so the next `ocx start` calls
@@ -138,6 +147,20 @@ export function setGrokIntegrationEnabled(enabled: boolean): CodexDesiredStateRe
   return setIntegrationEnabled("grok", enabled);
 }
 
+/** Whether Claude Desktop's managed gateway profile is wanted. */
+export function claudeDesktopIntegrationEnabled(config: Pick<OcxConfig, "clientIntegrations">): boolean {
+  return integrationEnabled(config, "claude-desktop");
+}
+
+/** The same question when no admitted config snapshot is in hand. */
+export function claudeDesktopIntegrationEnabledNow(): boolean {
+  return claudeDesktopIntegrationEnabled(loadConfig());
+}
+
+export function setClaudeDesktopIntegrationEnabled(enabled: boolean): CodexDesiredStateResult {
+  return setIntegrationEnabled("claude-desktop", enabled);
+}
+
 /**
  * The startup gate, as a function rather than an `if` buried in `handleStart`.
  *
@@ -161,13 +184,23 @@ export async function syncCodexOnStartIfEnabled(
   port: number,
   config: Pick<OcxConfig, "clientIntegrations">,
   sync: CodexStartupSync = defaultStartupSync,
+  readinessGate?: ReadinessGate,
 ): Promise<{ ran: boolean; catalogWritten: boolean; cacheSynced: boolean }> {
-  if (!codexIntegrationEnabled(config)) {
+  if (!shouldSyncCodexOnStart(config)) {
+    // The user explicitly turned Codex off: there is nothing to sync, so the
+    // proxy is ready as soon as it is up. The gate is driven here so /readyz
+    // does not stay pending forever for a deployment that deliberately disabled
+    // the native Codex integration.
+    readinessGate?.markReady();
     return { ran: false, catalogWritten: false, cacheSynced: false };
   }
   // The `.catch` is deliberate and stays: a failure to APPLY must not stop the
-  // proxy from coming up. A failed sync simply reports no writes.
-  const outcome = await sync(port).catch(() => undefined);
+  // proxy from coming up. A failed sync simply reports no writes. The readiness
+  // gate observes the real outcome so /readyz reflects the sync state exactly as
+  // the PR contract defines (ready only on ok=true with no warning).
+  const outcome = readinessGate
+    ? await runStartupReadinessSync(readinessGate, async () => (await sync(port)) ?? null)
+    : await sync(port).catch(() => undefined);
   return {
     ran: true,
     catalogWritten: outcome?.catalogWritten === true,

package/src/codex/history-job.ts

@@ -24,6 +24,7 @@ import type {
   HistoryWorkerResult,
 } from "./history-worker";
 import { historyBackupPathFor } from "./history-provider";
+import type { CodexHistoryFailureReason } from "./history-provider";
 import { getCodexHome } from "./paths";
 
 /** Where Codex keeps its resume history, and the manifest that shadows it. */
@@ -63,14 +64,15 @@ export interface CodexHistoryJobRequest {
   readonly canonicalStateDbPath: string;
   readonly canonicalBackupPath: string;
   readonly operation: CodexHistoryWorkerOperation;
+  readonly expectedDesiredEnabled?: boolean;
 }
 
 export type CodexHistoryJobOutcome =
   | { readonly kind: "converged"; readonly rows: number; readonly files: number }
   | { readonly kind: "skipped" }
-  | { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" }
+  | { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly kind: "failed"; readonly reason: "worker-error" | "worker-died" | "timeout";
-      readonly message: string };
+      readonly message: string; readonly historyFailureReason?: CodexHistoryFailureReason };
 
 /**
  * Derive the durable history operation from admitted intent.
@@ -113,9 +115,11 @@ function isPlausibleWorkerResult(
         && typeof message.rows === "number"
         && typeof message.files === "number";
     case "blocked":
-      return message.reason === "busy" || message.reason === "database" || message.reason === "unsafe-path";
+      return message.reason === "busy" || message.reason === "database" || message.reason === "unsafe-path"
+        || message.reason === "desired_disabled" || message.reason === "desired_enabled";
     case "error":
-      return typeof message.message === "string";
+      return typeof message.message === "string"
+        && (message.reason === undefined || message.reason === "busy" || message.reason === "permission");
     default:
       return false;
   }
@@ -134,7 +138,12 @@ export function deriveCodexHistoryOperation(intent: {
 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 };
+    return {
+      kind: "failed",
+      reason: "worker-error",
+      message: result.message,
+      ...(result.reason ? { historyFailureReason: result.reason } : {}),
+    };
   }
   return result.outcome === "skipped"
     ? { kind: "skipped" }
@@ -248,6 +257,7 @@ export async function runCodexHistoryJob(
       canonicalCodexHome: request.canonicalCodexHome,
       canonicalStateDbPath: request.canonicalStateDbPath,
       canonicalBackupPath: request.canonicalBackupPath,
+      ...(request.expectedDesiredEnabled === undefined ? {} : { expectedDesiredEnabled: request.expectedDesiredEnabled }),
       env: {
         ...(process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {}),
         ...(process.env.OPENCODEX_HOME ? { OPENCODEX_HOME: process.env.OPENCODEX_HOME } : {}),

package/src/codex/history-provider.ts

@@ -166,12 +166,16 @@ function patchFirstLineProviderInPlace(path: string, expectedId: string, provide
 
 export type CodexHistoryProvider = "openai" | "opencodex";
 
+export type CodexHistoryFailureReason = "busy" | "permission";
+
 export interface CodexHistorySyncResult {
   rows: number;
   files: number;
   ejectedRows?: number;
   /** Set when a lock/busy error survived retries and the sync was SKIPPED, not empty. */
   failed?: true;
+  /** Why the retry budget was exhausted when `failed` is set. */
+  failureReason?: CodexHistoryFailureReason;
 }
 
 interface ThreadRow {
@@ -515,19 +519,24 @@ function ejectRemainingOpencodexHistory(db: Database): { rows: number; files: nu
   return { rows: rows.length, files };
 }
 
-export function isRecoverableHistoryError(error: unknown): boolean {
+export function classifyRecoverableHistoryError(error: unknown): CodexHistoryFailureReason | null {
   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();
-  return code === "SQLITE_BUSY"
+  if (code === "SQLITE_BUSY"
     || code === "SQLITE_LOCKED"
     || code === "EBUSY"
-    || code === "EPERM"
-    || code === "EACCES"
     || message.includes("database is locked")
     || message.includes("database is busy")
-    || message.includes("resource busy")
+    || message.includes("resource busy")) return "busy";
+  if (code === "EPERM"
+    || code === "EACCES"
     || message.includes("operation not permitted")
-    || message.includes("permission denied");
+    || message.includes("permission denied")) return "permission";
+  return null;
+}
+
+export function isRecoverableHistoryError(error: unknown): boolean {
+  return classifyRecoverableHistoryError(error) !== null;
 }
 
 const HISTORY_RETRY_DELAY_MS = 500;
@@ -540,21 +549,29 @@ const HISTORY_RETRY_ATTEMPTS = 2;
  * error — callers surface that as `failed: true` instead of a silent no-op. Hard errors
  * (corruption, programming bugs) still throw.
  */
-export function withHistoryRetry<T>(fn: () => T, io: { sleepFn?: (ms: number) => void; attempts?: number; delayMs?: number } = {}): T | null {
+function withHistoryRetryResult<T>(fn: () => T, io: { sleepFn?: (ms: number) => void; attempts?: number; delayMs?: number } = {}):
+  | { ok: true; value: T }
+  | { ok: false; reason: CodexHistoryFailureReason } {
   const sleepFn = io.sleepFn ?? Bun.sleepSync;
   const attempts = Math.max(1, io.attempts ?? HISTORY_RETRY_ATTEMPTS);
   const delayMs = io.delayMs ?? HISTORY_RETRY_DELAY_MS;
   for (let attempt = 0; ; attempt++) {
     try {
-      return fn();
+      return { ok: true, value: fn() };
     } catch (error) {
-      if (!isRecoverableHistoryError(error)) throw error;
-      if (attempt >= attempts - 1) return null;
+      const reason = classifyRecoverableHistoryError(error);
+      if (!reason) throw error;
+      if (attempt >= attempts - 1) return { ok: false, reason };
       try { sleepFn(delayMs); } catch { /* sleep is best-effort */ }
     }
   }
 }
 
+export function withHistoryRetry<T>(fn: () => T, io: { sleepFn?: (ms: number) => void; attempts?: number; delayMs?: number } = {}): T | null {
+  const result = withHistoryRetryResult(fn, io);
+  return result.ok ? result.value : null;
+}
+
 /**
  * True when a READONLY probe proves the openai-direction restore would be a no-op:
  * zero threads still tagged opencodex AND an empty backup manifest. Used to skip the
@@ -581,8 +598,8 @@ export function syncCodexHistoryProvider(
     && openaiRestoreIsNoop(stateDbPath, backupPath)) {
     return { rows: 0, files: 0 };
   }
-  return withHistoryRetry(() => syncCodexHistoryProviderUnsafe(provider, stateDbPath, backupPath))
-    ?? { rows: 0, files: 0, failed: true };
+  const retried = withHistoryRetryResult(() => syncCodexHistoryProviderUnsafe(provider, stateDbPath, backupPath));
+  return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
 }
 
 function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbPath: string, backupPath: string): CodexHistorySyncResult {
@@ -734,8 +751,8 @@ export function migrateHistoryToOpenai(
   // nothing. A missing DB with a leftover backup manifest does NOT satisfy the gate
   // (backupEntries > 0), so the guardian's fresh-reinstall re-count protection holds.
   if (openaiRestoreIsNoop(stateDbPath, backupPath)) return { rows: 0, files: 0 };
-  return withHistoryRetry(() => syncCodexHistoryProviderUnsafe("openai", stateDbPath, backupPath), opts)
-    ?? { rows: 0, files: 0, failed: true };
+  const retried = withHistoryRetryResult(() => syncCodexHistoryProviderUnsafe("openai", stateDbPath, backupPath), opts);
+  return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
 }
 
 export interface PendingHistoryCount {

package/src/codex/history-worker.ts

@@ -24,11 +24,14 @@
  * Design record: devlog/_fin/260804_codex_write_substrate/020_history_isolation.md.
  */
 import { withHistoryWriteSerialization } from "./history-lock";
+import { loadConfig } from "../config";
+import { shouldSyncCodexOnStart } from "./desired-state";
 import {
   writeHistoryProviderTransition,
   writeLegacyOpenaiHistoryRecovery,
   type HistoryWriteTarget,
 } from "./internal/history-writer";
+import type { CodexHistoryFailureReason } from "./history-provider";
 
 /**
  * The durable operation, mirrored into the request for diagnostics only.
@@ -53,6 +56,8 @@ export interface HistoryWorkerRunMessage {
   readonly canonicalCodexHome: string;
   readonly canonicalStateDbPath: string;
   readonly canonicalBackupPath: string;
+  /** When set, prove this transition's desired direction while H is held. */
+  readonly expectedDesiredEnabled?: boolean;
   /** Env snapshot: a Worker may not observe parent mutations on every platform. */
   readonly env?: { readonly CODEX_HOME?: string; readonly OPENCODEX_HOME?: string };
 }
@@ -62,9 +67,9 @@ export type HistoryWorkerResult =
       readonly outcome: "converged" | "skipped";
       readonly rows: number; readonly files: number }
   | { readonly type: "blocked"; readonly requestId: string; readonly jobId: string;
-      readonly reason: "busy" | "database" | "unsafe-path" }
+      readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly type: "error"; readonly requestId: string; readonly jobId: string;
-      readonly message: string };
+      readonly message: string; readonly reason?: CodexHistoryFailureReason };
 
 const OPERATIONS: ReadonlySet<string> = new Set<CodexHistoryWorkerOperation>([
   "skip",
@@ -93,7 +98,8 @@ export function isHistoryWorkerRunMessage(data: unknown): data is HistoryWorkerR
     && OPERATIONS.has(message.operation)
     && nonEmpty(message.canonicalCodexHome)
     && nonEmpty(message.canonicalStateDbPath)
-    && nonEmpty(message.canonicalBackupPath);
+    && nonEmpty(message.canonicalBackupPath)
+    && (message.expectedDesiredEnabled === undefined || typeof message.expectedDesiredEnabled === "boolean");
 }
 
 /**
@@ -120,6 +126,10 @@ export function runHistoryUnitUnderLock(
     message.canonicalCodexHome,
     message.canonicalStateDbPath,
     permit => {
+      if (message.expectedDesiredEnabled !== undefined
+        && shouldSyncCodexOnStart(loadConfig()) !== message.expectedDesiredEnabled) {
+        return { desiredStateChanged: true as const };
+      }
       if (operation === "recover-legacy-openai") {
         return writeLegacyOpenaiHistoryRecovery(permit, target);
       }
@@ -134,8 +144,22 @@ export function runHistoryUnitUnderLock(
     return { type: "blocked", requestId, jobId, reason: acquired.reason };
   }
   const result = acquired.value;
+  if ("desiredStateChanged" in result) {
+    return {
+      type: "blocked",
+      requestId,
+      jobId,
+      reason: message.expectedDesiredEnabled ? "desired_disabled" : "desired_enabled",
+    };
+  }
   if (result.failed === true) {
-    return { type: "error", requestId, jobId, message: "history_transition_failed" };
+    return {
+      type: "error",
+      requestId,
+      jobId,
+      message: "history_transition_failed",
+      ...(result.failureReason ? { reason: result.failureReason } : {}),
+    };
   }
   return {
     type: "done",

package/src/codex/inject-coordination.ts

@@ -229,7 +229,19 @@ export function recomputeInjectWitness(options: {
 /** Project a non-acquired lock result into the injection result shape. */
 export function codexInjectLockOutcome(
   result: Exclude<CodexWriteLockResult<unknown>, { status: "acquired" }>,
-): { success: false; message: string; retryable: boolean } {
+): { success: false; message: string; retryable: boolean } | {
+  success: true; status: "skipped"; skippedReason: "desired_disabled" | "desired_enabled"; message: string;
+} {
+  if (result.status === "skipped") {
+    return {
+      success: true,
+      status: "skipped",
+      skippedReason: result.reason,
+      message: result.reason === "desired_disabled"
+        ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
+        : "Codex integration was re-enabled; native restore was skipped.",
+    };
+  }
   if (result.status === "busy") {
     return {
       success: false,