@iislee/opencodex 2.11.0 → 2.31.0

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 */ }
+  }
+}

package/src/codex/custom-model-catalog-migration.ts

@@ -0,0 +1,176 @@
+import { routedSlug, slugEquivalenceKey } from "../providers/slug-codec";
+import type { OcxConfig } from "../types";
+
+const MIGRATION_FIELD = "customModelCatalogMigration";
+const MIGRATION_VERSION = 1;
+
+type ConfigRecord = Record<string, unknown>;
+
+interface SupportedMigrationState {
+  readonly record: ConfigRecord;
+  readonly legacyOwnedSlugs: readonly string[];
+}
+
+type ParsedMigrationState =
+  | { readonly kind: "absent" }
+  | { readonly kind: "supported"; readonly state: SupportedMigrationState }
+  | { readonly kind: "unsupported"; readonly value: unknown };
+
+type CustomModelSlugSet =
+  | { readonly kind: "valid"; readonly byKey: ReadonlyMap<string, string> }
+  | { readonly kind: "invalid" };
+
+function configRecord(value: unknown): ConfigRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as ConfigRecord
+    : null;
+}
+
+function canonicalRoutedSlug(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const slug = value.trim();
+  const slash = slug.indexOf("/");
+  if (slash <= 0 || slash === slug.length - 1) return null;
+  const provider = slug.slice(0, slash).trim();
+  const modelId = slug.slice(slash + 1).trim();
+  if (!provider || !modelId || provider.includes("/")) return null;
+  return routedSlug(provider, modelId);
+}
+
+function canonicalSlugMap(values: readonly unknown[]): ReadonlyMap<string, string> | null {
+  const byKey = new Map<string, string>();
+  for (const value of values) {
+    const slug = canonicalRoutedSlug(value);
+    if (slug === null) return null;
+    byKey.set(slugEquivalenceKey(slug), slug);
+  }
+  return byKey;
+}
+
+function parseMigrationState(config: unknown): ParsedMigrationState {
+  const record = configRecord(config);
+  if (!record || !Object.hasOwn(record, MIGRATION_FIELD)) return { kind: "absent" };
+  const value = record[MIGRATION_FIELD];
+  const state = configRecord(value);
+  if (!state || state.version !== MIGRATION_VERSION || !Array.isArray(state.legacyOwnedSlugs)) {
+    return { kind: "unsupported", value };
+  }
+  const slugs = canonicalSlugMap(state.legacyOwnedSlugs);
+  if (slugs === null) return { kind: "unsupported", value };
+  return {
+    kind: "supported",
+    state: {
+      record: state,
+      legacyOwnedSlugs: [...slugs.values()].sort(),
+    },
+  };
+}
+
+function customModelSlugs(config: unknown): CustomModelSlugSet {
+  const record = configRecord(config);
+  if (!record || record.customModels === undefined) {
+    return { kind: "valid", byKey: new Map() };
+  }
+  if (!Array.isArray(record.customModels)) return { kind: "invalid" };
+  const byKey = new Map<string, string>();
+  for (const value of record.customModels) {
+    const custom = configRecord(value);
+    if (!custom || typeof custom.provider !== "string" || typeof custom.modelId !== "string") {
+      return { kind: "invalid" };
+    }
+    const provider = custom.provider.trim();
+    const modelId = custom.modelId.trim();
+    if (!provider || !modelId || provider.includes("/")) return { kind: "invalid" };
+    const slug = routedSlug(provider, modelId);
+    byKey.set(slugEquivalenceKey(slug), slug);
+  }
+  return { kind: "valid", byKey };
+}
+
+function copyMigrationField(target: OcxConfig, source: OcxConfig): void {
+  const targetRecord = target as unknown as ConfigRecord;
+  const sourceRecord = source as unknown as ConfigRecord;
+  if (Object.hasOwn(sourceRecord, MIGRATION_FIELD)) {
+    targetRecord[MIGRATION_FIELD] = structuredClone(sourceRecord[MIGRATION_FIELD]);
+  } else {
+    delete targetRecord[MIGRATION_FIELD];
+  }
+}
+
+/**
+ * Project one-time legacy custom-model ownership onto a whole-config write.
+ *
+ * The persisted pre-write config is the only authority for pre-marker ownership.
+ * Unknown future/malformed state is carried forward byte-for-value and grants no
+ * deletion authority; an older binary must never reinterpret or erase it.
+ */
+export function projectCustomModelCatalogMigration(
+  persistedConfig: unknown,
+  candidateConfig: OcxConfig,
+): OcxConfig {
+  const persistedState = parseMigrationState(persistedConfig);
+  const candidateState = parseMigrationState(candidateConfig);
+  const projected = { ...candidateConfig } as OcxConfig;
+  const projectedRecord = projected as unknown as ConfigRecord;
+
+  if (persistedState.kind === "unsupported") {
+    projectedRecord[MIGRATION_FIELD] = structuredClone(persistedState.value);
+    return projected;
+  }
+  if (persistedState.kind === "absent" && candidateState.kind === "unsupported") {
+    projectedRecord[MIGRATION_FIELD] = structuredClone(candidateState.value);
+    return projected;
+  }
+
+  const legacyByKey = new Map<string, string>();
+  const addLegacy = (slugs: readonly string[]): void => {
+    for (const slug of slugs) legacyByKey.set(slugEquivalenceKey(slug), slug);
+  };
+  if (persistedState.kind === "supported") addLegacy(persistedState.state.legacyOwnedSlugs);
+  if (candidateState.kind === "supported") addLegacy(candidateState.state.legacyOwnedSlugs);
+
+  const persistedCustom = customModelSlugs(persistedConfig);
+  const candidateCustom = customModelSlugs(candidateConfig);
+  // Only an absent persisted version means these rows can predate the ownership marker.
+  // Never add candidate-only or post-version models: those are born with custom-model-v1.
+  if (persistedState.kind === "absent" && persistedCustom.kind === "valid") {
+    for (const [key, slug] of persistedCustom.byKey) legacyByKey.set(key, slug);
+  }
+
+  // Establish an empty v1 on the first custom-model add too: the cutover, not list
+  // non-emptiness, proves that candidate-only models can never be inferred as legacy.
+  // Unrelated saves for users who never configured custom models remain untouched.
+  const shouldVersion = persistedState.kind === "supported"
+    || candidateState.kind === "supported"
+    || (persistedState.kind === "absent"
+      && ((persistedCustom.kind === "valid" && persistedCustom.byKey.size > 0)
+        || (candidateCustom.kind === "valid" && candidateCustom.byKey.size > 0)));
+  if (!shouldVersion) {
+    delete projectedRecord[MIGRATION_FIELD];
+    return projected;
+  }
+
+  const priorRecord = persistedState.kind === "supported" ? persistedState.state.record : {};
+  const nextRecord = candidateState.kind === "supported" ? candidateState.state.record : {};
+  projectedRecord[MIGRATION_FIELD] = {
+    ...structuredClone(priorRecord),
+    ...structuredClone(nextRecord),
+    version: MIGRATION_VERSION,
+    legacyOwnedSlugs: [...legacyByKey.values()].sort(),
+  };
+  return projected;
+}
+
+/** Copy only the internal migration state after the projected write succeeds. */
+export function adoptCustomModelCatalogMigration(
+  target: OcxConfig,
+  projected: OcxConfig,
+): void {
+  copyMigrationField(target, projected);
+}
+
+/** Canonical slugs that may classify old, unmarked OpenCodex custom rows. */
+export function legacyCustomModelCatalogSlugs(config: OcxConfig): ReadonlySet<string> {
+  const state = parseMigrationState(config);
+  return new Set(state.kind === "supported" ? state.state.legacyOwnedSlugs : []);
+}