@bitkyc08/opencodex 2.30.0-preview.20260821 → 2.31.0

package/src/cli/doctor.ts

@@ -25,6 +25,11 @@ import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHome
 import { scanCodexAgentRolesWithTomlModelFallback } from "../codex/subagent-model-fallback";
 import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
+import {
+  inspectCodexCoordinator,
+  recoverZeroByteCodexCoordinator,
+  type CodexCoordinatorDiagnostic,
+} from "../codex/coordinator-doctor";
 import {
   inspectAbandonedResponseStateTemps,
   reclaimAbandonedResponseStateTemps,
@@ -684,6 +689,7 @@ export async function fetchServiceMemory(
 const mb = (bytes: number): string => `${Math.round(bytes / (1024 * 1024))}MB`;
 
 export const RECLAIM_RESPONSE_TEMPS_FLAG = "--reclaim-response-temps";
+export const RECOVER_ZERO_BYTE_COORDINATOR_FLAG = "--recover-zero-byte-coordinator";
 /** Matches the dry run's entry bound so report and reclaim agree on a large backlog. */
 const RESPONSE_TEMP_RECLAIM_MAX_CLEANUPS = 4_096;
 /** Names the subsystem: other components mint temps with the same shape and are not covered. */
@@ -734,6 +740,60 @@ export function formatResponseTempLines(
   return lines;
 }
 
+export function formatCoordinatorDoctorLines(diagnostic: CodexCoordinatorDiagnostic): string[] {
+  const pathLine = diagnostic.path ? [`       path: ${diagnostic.path}`] : [];
+  const evidenceLines = "evidence" in diagnostic && diagnostic.evidence
+    ? [
+      `       size: ${diagnostic.evidence.sizeBytes} bytes; user_version: ${diagnostic.evidence.schemaVersion}`,
+      `       tables: ${diagnostic.evidence.tables.length === 0 ? "none" : diagnostic.evidence.tables.join(", ")}`,
+      `       transition rows: ${diagnostic.evidence.transitionRows ?? "not inspected"}; singleton=1 rows: ${diagnostic.evidence.singletonRows ?? "not inspected"}`,
+    ]
+    : [];
+  switch (diagnostic.kind) {
+    case "absent":
+      return ["  ok     native-write coordinator not created yet", ...pathLine];
+    case "ready":
+      return ["  ok     native-write coordinator has an authoritative transition row", ...pathLine, ...evidenceLines];
+    case "zero-byte":
+      return [
+        "  !!     native-write coordinator is a zero-byte remnant and has no authority",
+        ...pathLine,
+        ...evidenceLines,
+        `       Action: stop the OpenCodex proxy/service, then run ocx doctor ${RECOVER_ZERO_BYTE_COORDINATOR_FLAG} --yes`,
+      ];
+    case "unversioned-empty":
+      return [
+        "  !!     native-write coordinator is a non-empty unversioned database; automatic recovery is refused",
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "rowless":
+      return [
+        "  !!     native-write coordinator has schema version 1 but no authoritative row; automatic recovery is refused",
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "unversioned-nonempty":
+      return [
+        "  !!     native-write coordinator is unversioned and contains unknown tables; automatic recovery is refused",
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "unsupported":
+      return [
+        `  !!     native-write coordinator schema version ${diagnostic.version} is unsupported; automatic recovery is refused`,
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "changed":
+      return ["  --     native-write coordinator changed during diagnosis; re-run ocx doctor", ...pathLine];
+    case "unsafe":
+      return [`  !!     native-write coordinator path is unsafe: ${diagnostic.reason}`, ...pathLine];
+    case "unreadable":
+      return [`  !!     native-write coordinator is unreadable: ${diagnostic.reason}`, ...pathLine, ...evidenceLines];
+  }
+}
+
 /** Render the doctor "Memory / runtime" section lines (testable without console capture). */
 export function formatServiceMemoryLines(report: ServiceMemoryReport): string[] {
   const lines: string[] = [];
@@ -846,6 +906,33 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     return;
   }
 
+  if (args.includes(RECOVER_ZERO_BYTE_COORDINATOR_FLAG)) {
+    if (!args.includes("--yes")) {
+      console.log(`Recovery is explicit and creates a same-directory backup. Re-run: ocx doctor ${RECOVER_ZERO_BYTE_COORDINATOR_FLAG} --yes`);
+      process.exitCode = 1;
+      return;
+    }
+    const diagnostics = readConfigDiagnostics().config;
+    const live = await findLiveProxy({
+      configFn: () => ({ port: diagnostics.port, hostname: diagnostics.hostname }),
+    });
+    if (live) {
+      console.log(`Recovery refused: OpenCodex proxy pid ${live.pid} is still running. Stop the proxy/service and retry.`);
+      process.exitCode = 1;
+      return;
+    }
+    const recovered = recoverZeroByteCodexCoordinator();
+    if (!recovered.ok) {
+      console.log(`Recovery refused: ${recovered.reason}.`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`Moved the non-authoritative coordinator to ${recovered.backupPath}`);
+    console.log("Run `ocx sync` to retry Codex config injection. The backup was preserved and no Codex config/catalog file was changed by recovery.");
+    process.exitCode = 0;
+    return;
+  }
+
   console.log("opencodex doctor\n");
 
   // Ordering note: the memory/runtime section renders after "Running proxy
@@ -1005,6 +1092,8 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     const reason = cause instanceof CodexUserIdentityRefusal ? cause.message : String(cause);
     console.log(`  --     history coordinator namespace refused: ${reason}`);
   }
+  console.log("\nCodex native-write coordinator");
+  for (const line of formatCoordinatorDoctorLines(inspectCodexCoordinator())) console.log(line);
   const pending = countPendingOpencodexHistory();
   if (pending.failed) {
     console.log("  --     state DB locked or unreadable (Codex app open?) — migration state unknown");

package/src/cli/help.ts

@@ -38,6 +38,8 @@ Usage:
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
   ocx doctor --reclaim-response-temps
                               Reclaim abandoned response-state temp files (works without a running proxy)
+  ocx doctor --recover-zero-byte-coordinator --yes
+                              Back up a proven zero-byte Codex coordinator after stopping the proxy
   ocx debug <scope>           provider/usage/injection/claude on|off|status|reset
   ocx login <provider>        OAuth or API-key provider login
   ocx logout <provider>       Remove a stored OAuth login

package/src/cli/registry.ts

@@ -61,10 +61,11 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "service",
-    usage: "ocx service [install|start|stop|status|uninstall|remove]",
+    usage: "ocx service [install|repair|restart|start|stop|status|uninstall|remove]",
     summary: "Run as a background service.",
     details: [
-      "With no subcommand, installs/updates and starts the background service.",
+      "With no subcommand, installs when absent or repairs/restarts an existing service.",
+      "`restart` is an alias of `repair` and does not re-register an installed service.",
       "Use `ocx service status` to see diagnostics and log paths.",
     ],
   },
@@ -108,6 +109,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     name: "doctor",
     usage: "ocx doctor",
     summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability).",
+    details: [
+      "Default mode is observe-only and reports the native-write coordinator state and exact path.",
+      "After stopping the proxy/service, `--recover-zero-byte-coordinator --yes` moves only a proven zero-byte coordinator to a same-directory backup.",
+    ],
   },
   {
     name: "debug",

package/src/codex/auth-context.ts

@@ -1,3 +1,4 @@
+import { createHmac, randomBytes } from "node:crypto";
 import {
   CodexCredentialGenerationConflictError,
   CodexCredentialRefreshLockTimeoutError,
@@ -38,6 +39,38 @@ import { getAccountQuota } from "./quota";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import { captureConfigGeneration } from "../lib/state-store-sweeper";
+import { retainedUtf8Bytes } from "../lib/admission";
+
+const CODEX_AFFINITY_COMPONENT_MAX_BYTES = 512;
+const CODEX_APP_AFFINITY_KEY = randomBytes(32);
+
+function boundedCodexAffinityComponent(value: string | null): string | undefined {
+  const normalized = value?.trim();
+  if (!normalized) return undefined;
+  if (retainedUtf8Bytes(normalized) > CODEX_AFFINITY_COMPONENT_MAX_BYTES) return undefined;
+  return normalized;
+}
+
+/**
+ * Preserve Codex's parent-thread affinity when present. Desktop App requests can omit that
+ * header while retaining a stable session/thread pair, so derive an opaque process-local key
+ * only from the complete bounded pair. Raw identifiers and durable hashes never enter Pool state.
+ */
+export function codexPoolAffinityKey(headers: Headers): string | undefined {
+  const parentThreadId = boundedCodexAffinityComponent(headers.get("x-codex-parent-thread-id"));
+  if (parentThreadId) return parentThreadId;
+
+  const sessionId = boundedCodexAffinityComponent(headers.get("session-id"));
+  const threadId = boundedCodexAffinityComponent(headers.get("thread-id"));
+  if (!sessionId || !threadId) return undefined;
+
+  return `app:${createHmac("sha256", CODEX_APP_AFFINITY_KEY)
+    .update("opencodex-app-pool-affinity-v1\0")
+    .update(sessionId)
+    .update("\0")
+    .update(threadId)
+    .digest("base64url")}`;
+}
 
 export type CodexAuthContext =
   | { kind: "main"; accountId: null }
@@ -50,6 +83,8 @@ export type CodexAuthContext =
       chatgptAccountId: string;
       /** Bypass Pool selection and suppress quota/transient failover for an exact selector. */
       fixedAccount?: boolean;
+      /** Pool binding key; the Desktop fallback is an opaque process-local HMAC. */
+      affinityKey?: string;
       /**
        * Set when this request was admitted through an active quota cooldown as
        * the account's single probe. Must be echoed into the upstream outcome so
@@ -71,6 +106,8 @@ export type CodexAuthContext =
       chatgptAccountId: string;
       /** Bypass Pool selection and suppress quota/transient failover for an exact selector. */
       fixedAccount?: boolean;
+      /** See `pool.affinityKey`. */
+      affinityKey?: string;
       /** See `pool.probeLeaseId`. */
       probeLeaseId?: string;
       quotaScope?: CodexQuotaScope;
@@ -343,6 +380,7 @@ export async function resolveCodexAuthContext(
     }
     return { kind: "main", accountId: null };
   }
+  const affinityKey = fixedAccountId === undefined ? codexPoolAffinityKey(headers) : undefined;
   const entitlementSnapshot = options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
     ? await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config)
     : undefined;
@@ -369,7 +407,6 @@ export async function resolveCodexAuthContext(
     // routing inspect it. Selectors arriving after the fence skip reconciliation
     // and may still route to non-main pool accounts without touching switch state.
     if (!nativeMainReadsForbidden) reconcileMainCodexAccountRuntimeState();
-    const threadId = headers.get("x-codex-parent-thread-id");
     const resolution = fixedAccountId !== undefined
       ? { status: "selected" as const, accountId: fixedAccountId }
       : options.excludeAccountId
@@ -385,7 +422,7 @@ export async function resolveCodexAuthContext(
             ? { status: "selected" as const, accountId: selected }
             : { status: "none" as const };
         })()
-      : resolveCodexAccountForThreadDetailed(threadId, config, Date.now(), quotaScope, selectionOptions);
+      : resolveCodexAccountForThreadDetailed(affinityKey ?? null, config, Date.now(), quotaScope, selectionOptions);
     if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
     const selected = resolution.status === "selected" ? resolution.accountId : null;
     if (!selected) {
@@ -500,6 +537,7 @@ export async function resolveCodexAuthContext(
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
       ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
+      ...(affinityKey ? { affinityKey } : {}),
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
@@ -516,6 +554,7 @@ export async function resolveCodexAuthContext(
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
       ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
+      ...(affinityKey ? { affinityKey } : {}),
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),

package/src/codex/catalog/effort.ts

@@ -147,7 +147,7 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
     entry.service_tiers = [{
       id: "priority",
       name: "Fast",
-      description: "1.5x speed, increased usage",
+      description: model.fastTierDescription ?? "1.5x speed, increased usage",
     }];
     entry.additional_speed_tiers = ["fast"];
   }

package/src/codex/catalog/parsing.ts

@@ -125,6 +125,8 @@ export interface CatalogModel {
   supportsVerbosity?: boolean;
   /** Whether this exact routed model has a verified OpenAI-compatible service tier. */
   supportsServiceTier?: boolean;
+  /** Optional provider-specific copy for the advertised Fast tier. */
+  fastTierDescription?: string;
   supportsReasoningSummaries?: boolean;
   /**
    * Codex tool calling mode for this routed model.

package/src/codex/catalog/provider-fetch.ts

@@ -34,7 +34,8 @@ import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, r
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import {
   captureFastPolicyAuthority,
-  serviceTierSupportForModel,
+  fastPolicyForModel,
+  serviceTierSupportFromPolicy,
 } from "../../providers/service-tier";
 import type { FastPolicyAuthority } from "../../providers/fastwire";
 import { effectiveGoogleMode, getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
@@ -647,8 +648,13 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
   const defaultReasoningEffort = modelRecordValue(prov.modelDefaultReasoningEfforts, model.id) ?? model.defaultReasoningEffort;
   const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
-  const supportsServiceTier = serviceTierSupportForModel(prov, model.id, name);
-  const { supportsServiceTier: _staleServiceTier, ...modelWithoutServiceTier } = model;
+  const fastPolicy = fastPolicyForModel(prov, model.id, name);
+  const supportsServiceTier = serviceTierSupportFromPolicy(fastPolicy);
+  const {
+    supportsServiceTier: _staleServiceTier,
+    fastTierDescription: _staleFastTierDescription,
+    ...modelWithoutServiceTier
+  } = model;
   // 已发现窗口只允许被配置值压低；缺窗口时，已开的 Context cap 就是实际窗口。
   const discoveredWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
     ? model.contextWindow
@@ -671,6 +677,9 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
     ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
     ...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
     ...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
+    ...(supportsServiceTier === true && fastPolicy.fastTierDescription !== undefined
+      ? { fastTierDescription: fastPolicy.fastTierDescription }
+      : {}),
     ...(prov.adapter === "kiro" ? { supportsVerbosity: false } : {}),
     // Default-on for openai-chat providers (explicit false opts out); other adapters
     // advertise only on explicit opt-in.
@@ -1845,8 +1854,11 @@ async function gatherRoutedModelsUncached(
       ? nativeDefaultReasoningEffort(cm.modelId)
       : undefined;
     const supportsReasoningSummaries = configuredReasoningSummarySupport(rawProvider, cm.modelId);
-    const supportsServiceTier = effectiveProvider
-      ? serviceTierSupportForModel(effectiveProvider, cm.modelId, cm.provider)
+    const fastPolicy = effectiveProvider
+      ? fastPolicyForModel(effectiveProvider, cm.modelId, cm.provider)
+      : undefined;
+    const supportsServiceTier = fastPolicy
+      ? serviceTierSupportFromPolicy(fastPolicy)
       : undefined;
     const base: CatalogModel = {
       id: cm.modelId,
@@ -1883,6 +1895,9 @@ async function gatherRoutedModelsUncached(
       ...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
       ...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
       ...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
+      ...(supportsServiceTier === true && fastPolicy?.fastTierDescription !== undefined
+        ? { fastTierDescription: fastPolicy.fastTierDescription }
+        : {}),
       ...(cm.codexToolMode !== undefined
         ? { codexToolMode: cm.codexToolMode }
         : effectiveProvider?.codexToolMode !== undefined

package/src/codex/coordinator-doctor.ts

@@ -0,0 +1,332 @@
+/**
+ * Observe and explicitly quarantine non-authoritative native-write coordinators.
+ *
+ * Default doctor runs use immutable SQLite reads so diagnostics cannot create
+ * WAL/SHM sidecars. Recovery is deliberately opt-in and moves, never deletes,
+ * only a file that is still the same private regular file observed beforehand.
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  realpathSync,
+  renameSync,
+  type Stats,
+} from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { Database, constants as sqliteConstants } from "bun:sqlite";
+
+import { resolveCodexHomeDir } from "./home";
+import {
+  CodexUserIdentityRefusal,
+  probeCodexCoordinatorNamespace,
+  resolveEffectiveUserIdentity,
+  samePathIdentity,
+} from "./user-identity";
+import {
+  CODEX_COORDINATOR_SCHEMA_VERSION,
+  readCodexCoordinatorState,
+} from "./transition-state";
+
+const IMMUTABLE_READONLY_FLAGS =
+  sqliteConstants.SQLITE_OPEN_READONLY | sqliteConstants.SQLITE_OPEN_URI;
+
+export type FileIdentity = Pick<Stats, "dev" | "ino" | "size" | "mtimeMs" | "ctimeMs">;
+
+export interface CodexCoordinatorDiagnosticEvidence {
+  sizeBytes: number;
+  schemaVersion: number;
+  tables: readonly string[];
+  transitionRows: number | null;
+  singletonRows: number | null;
+}
+
+export type CodexCoordinatorDiagnostic =
+  | { kind: "absent"; path: string | null }
+  | { kind: "zero-byte"; path: string; identity: FileIdentity; evidence: CodexCoordinatorDiagnosticEvidence }
+  | { kind: "unversioned-empty"; path: string; identity: FileIdentity; evidence: CodexCoordinatorDiagnosticEvidence }
+  | { kind: "unversioned-nonempty"; path: string; identity: FileIdentity; evidence: CodexCoordinatorDiagnosticEvidence }
+  | { kind: "rowless"; path: string; identity: FileIdentity; evidence: CodexCoordinatorDiagnosticEvidence }
+  | { kind: "ready"; path: string; identity: FileIdentity; evidence: CodexCoordinatorDiagnosticEvidence }
+  | { kind: "unsupported"; path: string; identity: FileIdentity; version: number; evidence: CodexCoordinatorDiagnosticEvidence }
+  | { kind: "changed"; path: string }
+  | { kind: "unsafe"; path: string | null; reason: string }
+  | { kind: "unreadable"; path: string; reason: string; evidence?: CodexCoordinatorDiagnosticEvidence };
+
+export type CodexCoordinatorRecoveryResult =
+  | { ok: true; backupPath: string }
+  | { ok: false; reason: string };
+
+function errorCode(error: unknown): string {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : "";
+}
+
+function sameIdentity(left: FileIdentity, right: FileIdentity): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.size === right.size
+    && left.mtimeMs === right.mtimeMs
+    && left.ctimeMs === right.ctimeMs;
+}
+
+function sameNodeAndSize(left: FileIdentity, right: FileIdentity): boolean {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size;
+}
+
+function coordinatorPathWithoutCreation(): { kind: "absent"; path: string | null } | { kind: "path"; path: string } {
+  const identity = resolveEffectiveUserIdentity();
+  const canonicalCodexHome = realpathSync.native(resolveCodexHomeDir());
+  const namespace = probeCodexCoordinatorNamespace(identity);
+  if (namespace.status === "missing") return { kind: "absent", path: null };
+
+  const locks = join(namespace.root, "native-write-locks");
+  let locksEntry: Stats;
+  try {
+    locksEntry = lstatSync(locks);
+  } catch (cause) {
+    if (errorCode(cause) === "ENOENT") {
+      const digest = createHash("sha256").update(canonicalCodexHome).digest("hex");
+      return { kind: "absent", path: join(locks, `${digest}.sqlite`) };
+    }
+    throw new CodexUserIdentityRefusal("The coordinator lock directory cannot be inspected.", { cause });
+  }
+  if (locksEntry.isSymbolicLink() || !locksEntry.isDirectory()) {
+    throw new CodexUserIdentityRefusal("The coordinator lock namespace is not a real directory.");
+  }
+  if (identity.platform === "posix") {
+    if (locksEntry.uid !== identity.uid || (locksEntry.mode & 0o777) !== 0o700) {
+      throw new CodexUserIdentityRefusal("The coordinator lock namespace has unsafe ownership or permissions.");
+    }
+  } else if (!samePathIdentity(realpathSync.native(locks), locks, "win32")) {
+    throw new CodexUserIdentityRefusal("The coordinator lock namespace is redirected by a junction or reparse point.");
+  }
+
+  const digest = createHash("sha256").update(canonicalCodexHome).digest("hex");
+  return { kind: "path", path: join(locks, `${digest}.sqlite`) };
+}
+
+function inspectTarget(
+  path: string,
+  options: { allowSqliteSidecars?: boolean } = {},
+): { kind: "absent" } | { kind: "file"; identity: FileIdentity } | { kind: "unsafe"; reason: string } {
+  let entry: Stats;
+  try {
+    entry = lstatSync(path);
+  } catch (cause) {
+    if (errorCode(cause) === "ENOENT") return { kind: "absent" };
+    return { kind: "unsafe", reason: "the coordinator file cannot be inspected" };
+  }
+  if (entry.isSymbolicLink() || !entry.isFile()) {
+    return { kind: "unsafe", reason: "the coordinator path is not a real file" };
+  }
+  try {
+    if (!samePathIdentity(realpathSync.native(path), path)) {
+      return { kind: "unsafe", reason: "the coordinator path is redirected" };
+    }
+  } catch {
+    return { kind: "unsafe", reason: "the coordinator path cannot be resolved" };
+  }
+  if (process.platform !== "win32") {
+    const uid = process.getuid?.();
+    if (uid === undefined || entry.uid !== uid || (entry.mode & 0o777) !== 0o600) {
+      return { kind: "unsafe", reason: "the coordinator file has unsafe ownership or permissions" };
+    }
+  }
+  if (!options.allowSqliteSidecars) {
+    for (const suffix of ["-journal", "-wal", "-shm"]) {
+      if (existsSync(`${path}${suffix}`)) {
+        return { kind: "unsafe", reason: `the coordinator has an active SQLite ${suffix.slice(1)} sidecar` };
+      }
+    }
+  }
+  return { kind: "file", identity: entry };
+}
+
+function classifyOpenedDatabase(
+  database: Database,
+  path: string,
+  identity: FileIdentity,
+): CodexCoordinatorDiagnostic {
+  const version = database.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version ?? 0;
+  const tables = database.query<{ name: string }, []>(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+  ).all().map(row => row.name);
+  const baseEvidence = {
+    sizeBytes: identity.size,
+    schemaVersion: version,
+    tables,
+    transitionRows: null,
+    singletonRows: null,
+  } satisfies CodexCoordinatorDiagnosticEvidence;
+  if (version === 0) {
+    const evidence = tables.length === 0
+      ? { ...baseEvidence, transitionRows: 0, singletonRows: 0 }
+      : baseEvidence;
+    return tables.length === 0
+      ? { kind: "unversioned-empty", path, identity, evidence }
+      : { kind: "unversioned-nonempty", path, identity, evidence };
+  }
+  if (version !== CODEX_COORDINATOR_SCHEMA_VERSION) {
+    return { kind: "unsupported", path, identity, version, evidence: baseEvidence };
+  }
+  if (tables.length !== 1 || tables[0] !== "codex_transition_state") {
+    return tables.length === 0
+      ? { kind: "rowless", path, identity, evidence: baseEvidence }
+      : { kind: "unreadable", path, reason: "the coordinator contains unexpected tables", evidence: baseEvidence };
+  }
+  let rowCounts: { total: number; singleton: number } | null;
+  try {
+    rowCounts = database.query<{ total: number; singleton: number }, []>(
+      "SELECT count(*) AS total, sum(CASE WHEN singleton = 1 THEN 1 ELSE 0 END) AS singleton FROM codex_transition_state",
+    ).get() ?? null;
+  } catch {
+    return {
+      kind: "unreadable",
+      path,
+      reason: "the transition table schema is not recognized",
+      evidence: baseEvidence,
+    };
+  }
+  const evidence = {
+    ...baseEvidence,
+    transitionRows: rowCounts?.total ?? null,
+    singletonRows: rowCounts?.singleton ?? null,
+  };
+  if (!rowCounts || rowCounts.total === 0) return { kind: "rowless", path, identity, evidence };
+  if (rowCounts.total !== 1 || rowCounts.singleton !== 1) {
+    return {
+      kind: "unreadable",
+      path,
+      reason: "the coordinator does not contain exactly one singleton row",
+      evidence,
+    };
+  }
+  try {
+    readCodexCoordinatorState(database);
+  } catch {
+    return {
+      kind: "unreadable",
+      path,
+      reason: "the authoritative transition row is malformed",
+      evidence,
+    };
+  }
+  return { kind: "ready", path, identity, evidence };
+}
+
+export function inspectCodexCoordinator(): CodexCoordinatorDiagnostic {
+  let resolved: ReturnType<typeof coordinatorPathWithoutCreation>;
+  try {
+    resolved = coordinatorPathWithoutCreation();
+  } catch (cause) {
+    return {
+      kind: "unsafe",
+      path: null,
+      reason: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+  if (resolved.kind === "absent") return resolved;
+  return inspectCodexCoordinatorPath(resolved.path);
+}
+
+/** Inspect one already-resolved coordinator path without creating SQLite state. */
+export function inspectCodexCoordinatorPath(path: string): CodexCoordinatorDiagnostic {
+  const target = inspectTarget(path);
+  if (target.kind === "absent") return { kind: "absent", path };
+  if (target.kind === "unsafe") return { kind: "unsafe", path, reason: target.reason };
+
+  let database: Database | undefined;
+  try {
+    const uri = `${pathToFileURL(path).href}?immutable=1`;
+    database = new Database(uri, IMMUTABLE_READONLY_FLAGS);
+    const result = classifyOpenedDatabase(database, path, target.identity);
+    const after = inspectTarget(path);
+    if (after.kind !== "file" || !sameIdentity(target.identity, after.identity)) {
+      return { kind: "changed", path };
+    }
+    // Size alone is not evidence that this is a non-authoritative remnant.
+    // Query the immutable snapshot too, so the recovery label means all three
+    // facts were observed together: zero bytes, schema version zero, no tables.
+    if (target.identity.size === 0 && result.kind === "unversioned-empty") {
+      return { kind: "zero-byte", path, identity: target.identity, evidence: result.evidence };
+    }
+    return result;
+  } catch (cause) {
+    return { kind: "unreadable", path, reason: cause instanceof Error ? cause.message : String(cause) };
+  } finally {
+    try { database?.close(); } catch { /* diagnostics already completed */ }
+  }
+}
+
+function recoverable(diagnostic: CodexCoordinatorDiagnostic): diagnostic is Extract<
+  CodexCoordinatorDiagnostic,
+  { kind: "zero-byte" }
+> {
+  return diagnostic.kind === "zero-byte";
+}
+
+function backupTimestamp(now: Date): string {
+  return now.toISOString().replace(/[-:.]/g, "");
+}
+
+export function recoverZeroByteCodexCoordinator(now = new Date()): CodexCoordinatorRecoveryResult {
+  const observed = inspectCodexCoordinator();
+  if (!recoverable(observed)) {
+    if (observed.kind === "unsafe" || observed.kind === "unreadable") {
+      return { ok: false, reason: `coordinator state is ${observed.kind}: ${observed.reason}` };
+    }
+    return { ok: false, reason: `coordinator state is ${observed.kind}, not a recoverable zero-byte remnant` };
+  }
+
+  let database: Database | undefined;
+  let transactionOpen = false;
+  try {
+    database = new Database(observed.path, { readwrite: true, create: false });
+    database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+    const lockedEntry = inspectTarget(observed.path, { allowSqliteSidecars: true });
+    // SQLite may update file timestamps merely by opening a zero-byte database
+    // for BEGIN IMMEDIATE. Device/inode/size are the stable identity here; the
+    // transaction excludes content writers while we reclassify the database.
+    if (lockedEntry.kind !== "file" || !sameNodeAndSize(observed.identity, lockedEntry.identity)) {
+      return { ok: false, reason: "the coordinator changed before recovery acquired its SQLite lock" };
+    }
+    if (lockedEntry.identity.size !== 0) {
+      return { ok: false, reason: "the coordinator stopped being zero-byte before recovery" };
+    }
+    database.exec("ROLLBACK");
+    transactionOpen = false;
+    database.close();
+    database = undefined;
+
+    const finalEntry = inspectTarget(observed.path);
+    if (finalEntry.kind !== "file" || !sameIdentity(lockedEntry.identity, finalEntry.identity)) {
+      return { ok: false, reason: "the coordinator changed before the backup move" };
+    }
+    const backupPath = `${observed.path}.zero-byte-backup-${backupTimestamp(now)}`;
+    if (existsSync(backupPath)) return { ok: false, reason: "the same-directory backup path already exists" };
+    renameSync(observed.path, backupPath);
+    const backupEntry = inspectTarget(backupPath);
+    // The rename itself can advance ctime, so post-move verification uses the
+    // stable filesystem object and byte size. The full timestamp identity was
+    // already revalidated immediately before rename while the source existed.
+    if (backupEntry.kind !== "file" || !sameNodeAndSize(finalEntry.identity, backupEntry.identity) || existsSync(observed.path)) {
+      return { ok: false, reason: "the coordinator backup move could not be verified" };
+    }
+    return { ok: true, backupPath };
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const busy = errorCode(cause) === "SQLITE_BUSY" || errorCode(cause) === "SQLITE_LOCKED"
+      || /database (?:is|table is) locked/i.test(message);
+    return { ok: false, reason: busy ? "the coordinator is busy; stop active sync/service writers and retry" : message };
+  } finally {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close releases the lock */ }
+    }
+    try { database?.close(); } catch { /* recovery already completed */ }
+  }
+}