@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/codex/catalog-self-heal.ts

@@ -0,0 +1,284 @@
+import { readConfigAdmissionSnapshot } from "../config/diagnostics";
+import { readRuntimePort } from "../config/process-state";
+import { readClientConnectionState } from "../client/state";
+import { getActiveTurnCount, isDraining, isRecyclingForExit, isShutdownDraining } from "../server/lifecycle";
+import type { OcxConfig } from "../types";
+import { observeCatalogHealFile, sameCatalogHealPath, selectCatalogHealPath, type CatalogObservation } from "./catalog/heal-observation";
+import { subscribeCatalogPublication } from "./catalog/publication-observer";
+import { configEnablesRoutedNamespace, ocxRoutedNamespaceCounts } from "./catalog/routed-removal";
+import { inspectCodexHomeOwner } from "./codex-home-owner";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import { JOURNAL_PATH, journalOwner } from "./journal";
+import { CODEX_HOME, DEFAULT_CATALOG_PATH, resolveCodexConfigPath } from "./paths";
+import { siblingOfLivePort } from "./sibling-start";
+
+export type { CatalogObservation } from "./catalog/heal-observation";
+export const CATALOG_HEAL_TICK_MS = 30_000;
+export const CATALOG_HEAL_RECHECK_MS = 5 * 60_000;
+export const CATALOG_HEAL_WINDOW_MS = 60 * 60_000;
+export const CATALOG_HEAL_MAX_ATTEMPTS = 6;
+export const CATALOG_HEAL_MAX_HEALS = 3;
+
+export type CatalogSelfHealGate = "sibling" | "exiting" | "idle" | "runtime-record" | "config-unavailable" | "codex-off" | "not-owner" | "client";
+export interface CatalogSelfHealGates {
+  siblingOfLivePort(): number | null;
+  exiting(): boolean;
+  idle(): boolean;
+  runtimeOwned(): boolean;
+  /** File-backed config authority; missing, malformed or salvaged config returns null. */
+  loadConfig(): OcxConfig | null;
+  ownsCodexHome(): boolean;
+  clientConnected(): boolean;
+  clientJournalOwner(): boolean;
+}
+export interface CatalogHealOutcome { readonly committed: boolean }
+export interface CatalogHealLifecycle {
+  readonly beforeCommit: () => boolean;
+  readonly expectedCatalogPath: string;
+}
+export interface CatalogSelfHealRecord {
+  readonly at: string;
+  readonly lostNamespaces: number;
+  readonly committed: boolean;
+}
+export interface CatalogSelfHealHandle {
+  stop(): void;
+  lastHeal(): CatalogSelfHealRecord | null;
+  tickForTests(): Promise<void>;
+}
+export interface CatalogSelfHealDeps {
+  scheduleFn?: (fn: () => void, ms: number) => { cancel(): void };
+  now?: () => number;
+  catalogPath?: () => string | null;
+  observe?: (path: string, readContent: boolean) => CatalogObservation | null;
+  converge?: (config: OcxConfig, lifecycle: CatalogHealLifecycle) => Promise<CatalogHealOutcome>;
+  subscribe?: typeof subscribeCatalogPublication;
+  gates?: Partial<CatalogSelfHealGates>;
+  log?: Pick<Console, "warn">;
+}
+
+function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
+  const timer = setTimeout(fn, ms);
+  timer.unref?.();
+  return { cancel: () => clearTimeout(timer) };
+}
+
+async function convergeOwnCatalog(config: OcxConfig, lifecycle: CatalogHealLifecycle): Promise<CatalogHealOutcome> {
+  const [{ armDetachedConfigBaseline }, { createManagementConvergeCodex }, { createCatalogConvergeRequest }] = await Promise.all([
+    import("../config"), import("./management-convergence"), import("./catalog-admission"),
+  ]);
+  if (!lifecycle.beforeCommit()) return { committed: false };
+  // Discovery persistence rebases this detached snapshot against current disk config.
+  armDetachedConfigBaseline(config);
+  const outcome = await createManagementConvergeCodex(config, lifecycle)(createCatalogConvergeRequest({ deadlineMs: 1_000 }));
+  return { committed: outcome.kind === "catalog-only" && outcome.catalogRefresh.status === "committed" };
+}
+
+export function evaluateCatalogSelfHealGates(gates: CatalogSelfHealGates):
+  { readonly open: true; readonly config: OcxConfig } | { readonly open: false; readonly gate: CatalogSelfHealGate } {
+  if (gates.siblingOfLivePort() !== null) return { open: false, gate: "sibling" };
+  if (gates.exiting()) return { open: false, gate: "exiting" };
+  if (!gates.idle()) return { open: false, gate: "idle" };
+  if (!gates.runtimeOwned()) return { open: false, gate: "runtime-record" };
+  const config = gates.loadConfig();
+  if (config === null) return { open: false, gate: "config-unavailable" };
+  if (!shouldSyncCodexOnStart(config)) return { open: false, gate: "codex-off" };
+  if (gates.clientConnected() || gates.clientJournalOwner()) return { open: false, gate: "client" };
+  if (!gates.ownsCodexHome()) return { open: false, gate: "not-owner" };
+  return { open: true, config };
+}
+
+type NamespaceObservation = { path: string; signature: string; namespaces: ReadonlySet<string> | null };
+
+/** Owner lifecycle only: importing this module starts no timer or publication subscription. */
+export function startCodexCatalogSelfHeal(options: { port?: number; deps?: CatalogSelfHealDeps } = {}): CatalogSelfHealHandle {
+  const deps = options.deps ?? {};
+  const scheduleFn = deps.scheduleFn ?? defaultSchedule;
+  const clock = deps.now ?? (() => performance.now());
+  const catalogPath = deps.catalogPath ?? (() => selectCatalogHealPath(JOURNAL_PATH, DEFAULT_CATALOG_PATH, resolveCodexConfigPath));
+  const observe = deps.observe ?? observeCatalogHealFile;
+  const converge = deps.converge ?? convergeOwnCatalog;
+  const gates: CatalogSelfHealGates = {
+    siblingOfLivePort,
+    exiting: () => isRecyclingForExit() || isShutdownDraining(),
+    idle: () => !isDraining() && getActiveTurnCount() === 0,
+    runtimeOwned: () => {
+      const runtime = readRuntimePort(process.pid);
+      return runtime !== null && runtime.siblingOfPort === undefined
+        && (options.port === undefined || runtime.port === options.port);
+    },
+    loadConfig: () => {
+      const snapshot = readConfigAdmissionSnapshot();
+      return snapshot.kind === "read" && snapshot.diagnostics.source === "file"
+        ? snapshot.diagnostics.config : null;
+    },
+    ownsCodexHome: () => {
+      const owner = inspectCodexHomeOwner(CODEX_HOME);
+      return owner.kind === "owned" || owner.kind === "unbound";
+    },
+    clientConnected: () => readClientConnectionState().kind !== "disconnected",
+    clientJournalOwner: () => journalOwner({ readOnly: true })?.kind === "client",
+    ...deps.gates,
+  };
+  const log = deps.log ?? console;
+  let stopped = false;
+  let released = false;
+  let generation = 0;
+  let timer: { cancel(): void } | undefined;
+  let running = false;
+  let last: CatalogSelfHealRecord | null = null;
+  let target: string | null = null;
+  let baseline: NamespaceObservation | null = null;
+  let observed: NamespaceObservation | null = null;
+  let pendingRetry: { path: string; lostNamespaces: readonly string[] } | null = null;
+  let recheckAt = 0;
+  const attempts: number[] = [];
+  const heals: number[] = [];
+
+  const read = (path: string): NamespaceObservation | null => {
+    const quick = observe(path, false);
+    if (quick === null) return null;
+    if (observed !== null && sameCatalogHealPath(observed.path, path) && observed.signature === quick.signature) return observed;
+    const seen = observe(path, true);
+    if (seen === null) return null;
+    observed = { path, signature: seen.signature, namespaces: seen.catalog ? new Set(ocxRoutedNamespaceCounts(seen.catalog).keys()) : null };
+    return observed;
+  };
+  const accept = (path: string): void => {
+    const seen = read(path);
+    if (seen?.namespaces != null) baseline = seen;
+  };
+  const clear = (): void => {
+    generation += 1;
+    baseline = observed = null;
+    pendingRetry = null;
+    recheckAt = 0;
+  };
+  const updateTarget = (path: string | null): void => {
+    // Unavailable selection is not evidence of a different target or lost authority.
+    if (path === null) return;
+    if (target !== null && sameCatalogHealPath(target, path)) return;
+    clear();
+    target = path;
+  };
+  const beforeCommit = (path: string, entryGeneration: number): boolean => {
+    try {
+      const selected = catalogPath();
+      return !stopped && !released && generation === entryGeneration
+        && selected !== null && sameCatalogHealPath(selected, path) && evaluateCatalogSelfHealGates(gates).open;
+    } catch { return false; }
+  };
+  const capRetryAt = (now: number): number => {
+    while (attempts.length && now - attempts[0]! >= CATALOG_HEAL_WINDOW_MS) attempts.shift();
+    while (heals.length && now - heals[0]! >= CATALOG_HEAL_WINDOW_MS) heals.shift();
+    return Math.max(
+      attempts.length >= CATALOG_HEAL_MAX_ATTEMPTS ? attempts[0]! + CATALOG_HEAL_WINDOW_MS : 0,
+      heals.length >= CATALOG_HEAL_MAX_HEALS ? heals[0]! + CATALOG_HEAL_WINDOW_MS : 0,
+    );
+  };
+
+  const tick = async (): Promise<void> => {
+    if (stopped || running || released) return;
+    running = true;
+    try {
+      const path = catalogPath();
+      updateTarget(path);
+      if (path === null) return;
+      // Pending cache/funnel failure is independent of catalog stat or apparent repaired rows.
+      if (pendingRetry) {
+        const config = gates.loadConfig();
+        if (config === null) return;
+        const enabled = pendingRetry.lostNamespaces.filter(ns => configEnablesRoutedNamespace(config, ns));
+        if (enabled.length === 0) {
+          pendingRetry = null;
+          recheckAt = 0;
+          const seen = read(path);
+          if (seen?.namespaces != null) baseline = seen;
+          return;
+        }
+        pendingRetry = { path, lostNamespaces: enabled };
+      }
+      const now = clock();
+      if (now < recheckAt) return;
+      const seen = read(path);
+      // Missing/corrupt custom paths are unavailable, never reconstructed from the default.
+      if (seen?.namespaces == null) return;
+      if (baseline === null) { baseline = seen; return; }
+      if (!pendingRetry) {
+        if (baseline.signature === seen.signature) return;
+        const lost = [...baseline.namespaces!].filter(ns => !seen.namespaces!.has(ns));
+        if (lost.length === 0) { baseline = seen; return; }
+        pendingRetry = { path, lostNamespaces: lost };
+      }
+      const gate = evaluateCatalogSelfHealGates(gates);
+      if (!gate.open) { recheckAt = now + CATALOG_HEAL_RECHECK_MS; return; }
+      const lostEnabled = pendingRetry.lostNamespaces.filter(ns => configEnablesRoutedNamespace(gate.config, ns));
+      if (lostEnabled.length === 0) { pendingRetry = null; baseline = seen; return; }
+      pendingRetry = { path, lostNamespaces: lostEnabled };
+      const cappedUntil = capRetryAt(now);
+      if (cappedUntil > now) { recheckAt = cappedUntil; return; }
+      attempts.push(now);
+      const entryGeneration = generation;
+      log.warn(`[catalog-self-heal] republishing ${lostEnabled.length} lost routed provider namespace${lostEnabled.length === 1 ? "" : "s"}`);
+      let committed = false;
+      try { committed = (await converge(gate.config, {
+        beforeCommit: () => beforeCommit(path, entryGeneration), expectedCatalogPath: path,
+      })).committed; }
+      catch { /* Failed attempts retain pending retry and consume the attempt budget. */ }
+      const selected = catalogPath();
+      if (stopped || released || generation !== entryGeneration || selected === null || !sameCatalogHealPath(selected, path)) return;
+      last = { at: new Date().toISOString(), lostNamespaces: lostEnabled.length, committed };
+      if (committed) {
+        heals.push(clock());
+        pendingRetry = null;
+        recheckAt = 0;
+        accept(path); // Authoritative emptiness is a successful owner baseline too.
+      } else recheckAt = clock() + CATALOG_HEAL_RECHECK_MS;
+    } catch {
+      log.warn("[catalog-self-heal] observation unavailable; deferred");
+    } finally { running = false; }
+  };
+
+  const unsubscribe = (deps.subscribe ?? subscribeCatalogPublication)(event => {
+    if (stopped) return;
+    // Native restoration can remove the journal before notification. Fence the known
+    // target (and target-less releases) without resolving possibly unavailable evidence.
+    const release = event.kind === "native-released" || event.intent === "restore";
+    if (release && (event.path === null || (target !== null && sameCatalogHealPath(event.path, target)))) {
+      clear();
+      released = true;
+      return;
+    }
+    const path = catalogPath();
+    if (event.path !== null && (target === null || !sameCatalogHealPath(event.path, target))
+      && (path === null || !sameCatalogHealPath(event.path, path))) return;
+    if (release) {
+      clear();
+      released = true; // Only a later accepted owner publication can re-arm this lifecycle.
+      return;
+    }
+    if (running) return; // Catalog-success/cache-failure must not accept a baseline.
+    // A committed owner publication supplies a read-only baseline even while heal writes are gated.
+    if (event.path === null || path === null || !sameCatalogHealPath(event.path, path)) return;
+    updateTarget(path);
+    released = false;
+    pendingRetry = null;
+    recheckAt = 0;
+    accept(event.path);
+  });
+  // Capture immediately after startup sync, before a foreign write can become the first tick.
+  try { updateTarget(catalogPath()); if (target !== null) accept(target); }
+  catch { /* Unavailable observation can be retried by the scheduled tick. */ }
+  const schedule = (): void => {
+    if (stopped) return;
+    timer = scheduleFn(() => {
+      void tick().catch(() => log.warn("[catalog-self-heal] scheduled observation failed")).finally(schedule);
+    }, CATALOG_HEAL_TICK_MS);
+  };
+  schedule();
+  return {
+    stop() { stopped = true; clear(); timer?.cancel(); timer = undefined; unsubscribe(); },
+    lastHeal: () => last,
+    tickForTests: tick,
+  };
+}

package/src/codex/catalog-write-serialization.ts

@@ -28,12 +28,16 @@ import { chmodSync, lstatSync, realpathSync } from "node:fs";
 
 import { Database } from "bun:sqlite";
 
+import { currentOpencodexHome, inspectCodexHomeOwner } from "./codex-home-owner";
+import { appendCatalogWriteAudit } from "./catalog/write-audit";
+import type { CatalogWriteAuditDetails, CatalogWriteIntent } from "./catalog/write-audit-contract";
 import {
   CodexUserIdentityRefusal,
   resolveCodexCatalogSerializationDatabasePath,
   resolveEffectiveUserIdentity,
   samePathIdentity,
 } from "./user-identity";
+import { assertNotRealCodexHomeUnderTest } from "../lib/test-home-guard";
 
 /**
  * Authorization to perform the fixed sequence of catalog mutations inside ONE
@@ -51,9 +55,16 @@ export interface CatalogWritePermit {
 
 declare const catalogWritePermitBrand: unique symbol;
 
+export type { CatalogWriteIntent } from "./catalog/write-audit-contract";
+
+export interface CatalogWriteOptions {
+  readonly intent: CatalogWriteIntent;
+  readonly writer: string;
+}
+
 export type CatalogSerializationOutcome<T> =
   | { kind: "completed"; value: T }
-  | { kind: "unavailable"; reason: "busy" | "database" | "unsafe-path" };
+  | { kind: "unavailable"; reason: "busy" | "database" | "unsafe-path" | "foreign-owner" | "owner-unknown" };
 
 export class CatalogWritePermitRefusal extends Error {
   readonly code = "CODEX_CATALOG_WRITE_PERMIT_REFUSED";
@@ -69,6 +80,8 @@ interface PermitRegistration {
   readonly canonicalCodexHome: string;
   /** Identifies the acquisition, so a permit cannot outlive its transaction. */
   readonly transactionId: string;
+  readonly intent: CatalogWriteIntent;
+  readonly writer: string;
   live: boolean;
 }
 
@@ -121,6 +134,34 @@ export function assertCatalogWritePermit(
   }
 }
 
+/** Only a live acquisition may expose its declared intent and writer. */
+export function catalogWritePermitContext(permit: CatalogWritePermit): CatalogWriteOptions {
+  const registration = activePermits.get(permit as unknown as object);
+  if (!registration?.live) throw new CatalogWritePermitRefusal("The catalog write permit is not live.");
+  return { intent: registration.intent, writer: registration.writer };
+}
+
+/** Audit mutation is subject to the same live-home proof as catalog publication. */
+export function auditCatalogWriteWithPermit(
+  permit: CatalogWritePermit,
+  canonicalCodexHome: string,
+  details: CatalogWriteAuditDetails,
+): "appended" | "created" | "skipped" {
+  assertCatalogWritePermit(permit, canonicalCodexHome);
+  const context = catalogWritePermitContext(permit);
+  try { return appendCatalogWriteAudit(canonicalCodexHome, {
+    target: details.target, outcome: details.outcome, reason: details.reason,
+    routedBefore: details.routedBefore, routedAfter: details.routedAfter,
+    configSource: details.configSource, intent: context.intent, writer: context.writer,
+    opencodexHome: currentOpencodexHome(),
+  }, { create: true }); } catch { return "skipped"; }
+}
+
+function ownerRefusal(canonicalCodexHome: string): "foreign-owner" | "owner-unknown" | null {
+  const owner = inspectCodexHomeOwner(canonicalCodexHome);
+  return owner.kind === "foreign" ? "foreign-owner" : owner.kind === "unknown" ? "owner-unknown" : null;
+}
+
 /**
  * Acquire K for one canonical CODEX_HOME and run `write` while it is held.
  *
@@ -135,7 +176,14 @@ export function assertCatalogWritePermit(
 export function withCatalogWriteSerialization<T>(
   canonicalCodexHome: string,
   write: (permit: CatalogWritePermit) => T,
+  options: CatalogWriteOptions,
 ): CatalogSerializationOutcome<T> {
+  // First, ahead of the owner precheck and its diagnostics: a test process never gets a permit for
+  // the real Codex home, whatever its CODEX_HOME resolved to (#6529).
+  assertNotRealCodexHomeUnderTest(canonicalCodexHome);
+  // Re-evaluate on every acquisition; unknown evidence cannot authorize a takeover.
+  const refusedOwner = ownerRefusal(canonicalCodexHome);
+  // A precheck refusal may still acquire K for append-only diagnostics; it never gets a permit.
   let databasePath: string;
   try {
     databasePath = resolveCodexCatalogSerializationDatabasePath(
@@ -144,9 +192,9 @@ export function withCatalogWriteSerialization<T>(
     );
   } catch (error) {
     if (error instanceof CodexUserIdentityRefusal) {
-      return { kind: "unavailable", reason: "unsafe-path" };
+      return { kind: "unavailable", reason: refusedOwner ?? "unsafe-path" };
     }
-    return { kind: "unavailable", reason: "database" };
+    return { kind: "unavailable", reason: refusedOwner ?? "database" };
   }
 
   let database: Database | undefined;
@@ -159,12 +207,12 @@ export function withCatalogWriteSerialization<T>(
     try {
       const before = lstatSync(databasePath);
       if (before.isSymbolicLink() || !before.isFile()) {
-        return { kind: "unavailable", reason: "unsafe-path" };
+        return { kind: "unavailable", reason: refusedOwner ?? "unsafe-path" };
       }
       if (process.platform !== "win32") {
         const uid = process.getuid?.();
         if (uid === undefined || before.uid !== uid || (before.mode & 0o777) !== 0o600) {
-          return { kind: "unavailable", reason: "unsafe-path" };
+          return { kind: "unavailable", reason: refusedOwner ?? "unsafe-path" };
         }
       }
     } catch (cause) {
@@ -182,16 +230,31 @@ export function withCatalogWriteSerialization<T>(
     const opened = lstatSync(databasePath);
     if (opened.isSymbolicLink() || !opened.isFile()
       || !samePathIdentity(realpathSync.native(databasePath), databasePath)) {
-      return { kind: "unavailable", reason: "unsafe-path" };
+      return { kind: "unavailable", reason: refusedOwner ?? "unsafe-path" };
     }
 
     database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
     transactionOpen = true;
 
+    // Ownership may have changed while opening K. Refuse before minting a permit or invoking work.
+    const lockedOwnerRefusal = refusedOwner ?? ownerRefusal(canonicalCodexHome);
+    if (lockedOwnerRefusal) {
+      try { appendCatalogWriteAudit(canonicalCodexHome, {
+        target: options.intent === "cache" ? "cache" : "catalog",
+        outcome: "refused", reason: lockedOwnerRefusal,
+        intent: options.intent, writer: options.writer, opencodexHome: currentOpencodexHome(),
+      }, { create: false }); } catch { /* Diagnostic metadata cannot mask the owner refusal. */ }
+      database.exec("ROLLBACK");
+      transactionOpen = false;
+      return { kind: "unavailable", reason: lockedOwnerRefusal };
+    }
+
     acquisitionCounter += 1;
     registration = {
       canonicalCodexHome,
       transactionId: `${process.pid}:${acquisitionCounter}`,
+      intent: options.intent,
+      writer: options.writer,
       live: true,
     };
     // A bare object: nothing about it is guessable or reconstructable, because
@@ -224,8 +287,9 @@ export function withCatalogWriteSerialization<T>(
       if (permit) activePermits.delete(permit as unknown as object);
     }
     if (error instanceof CodexUserIdentityRefusal) {
-      return { kind: "unavailable", reason: "unsafe-path" };
+      return { kind: "unavailable", reason: refusedOwner ?? "unsafe-path" };
     }
+    if (refusedOwner) return { kind: "unavailable", reason: refusedOwner };
     if (isBusy(error)) return { kind: "unavailable", reason: "busy" };
     // A callback failure is the caller's error, not a lock outcome: K acquired
     // fine. Reporting it as `unavailable` would tell the caller to retry

package/src/codex/codex-home-owner.ts

@@ -0,0 +1,124 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { getConfigDir } from "../config/paths";
+import { samePathIdentity } from "./user-identity";
+
+export const CODEX_HOME_JOURNAL_FILE = "opencodex-journal.json";
+const MAX_JOURNAL_BYTES = 1024 * 1024;
+
+/** K imports this module; keep it independent of the config barrel and journal writer. */
+export function currentOpencodexHome(): string {
+  const configured = getConfigDir();
+  try { return realpathSync.native(configured); }
+  catch { return resolve(configured); }
+}
+
+export type CodexHomeOwnership =
+  | { readonly kind: "unbound" }
+  | { readonly kind: "owned" }
+  | { readonly kind: "stale"; readonly boundHome: string }
+  | { readonly kind: "foreign"; readonly boundHome: string }
+  | { readonly kind: "unknown" };
+
+export type CodexHomeJournalInspection =
+  | { kind: "missing" }
+  | { kind: "read"; journal: Record<string, unknown> }
+  | { kind: "unknown" };
+
+function absent(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException)?.code === "ENOENT";
+}
+
+/** ENOENT through a dangling link or an unresolvable ancestor is not proven absence. */
+function provenAbsent(path: string): boolean {
+  try { lstatSync(path); return false; }
+  catch (error) { if (!absent(error)) return false; }
+  const parent = dirname(path);
+  if (parent === path) return false;
+  try { return statSync(realpathSync.native(parent)).isDirectory(); }
+  catch (error) { return absent(error) && provenAbsent(parent); }
+}
+
+function validJournal(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const journal = value as Record<string, unknown>;
+  return journal.version === 1 && typeof journal.originalConfig === "string"
+    && (journal.originalProfile === null || typeof journal.originalProfile === "string")
+    && (journal.opencodexHome === undefined || (typeof journal.opencodexHome === "string"
+      && isAbsolute(journal.opencodexHome) && !journal.opencodexHome.includes("\0")));
+}
+
+/** Bounded, regular-file-only observation. Failure never supplies cleanup authority. */
+export function readCodexHomeJournal(journalPath: string): CodexHomeJournalInspection {
+  let fd: number | undefined;
+  try {
+    const before = lstatSync(journalPath);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_JOURNAL_BYTES) return { kind: "unknown" };
+    fd = openSync(journalPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.size > MAX_JOURNAL_BYTES || before.dev !== opened.dev || before.ino !== opened.ino) return { kind: "unknown" };
+    const bytes = Buffer.alloc(opened.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, null);
+      if (!count) break;
+      length += count;
+    }
+    const after = lstatSync(journalPath);
+    if (length !== opened.size || !after.isFile() || after.dev !== opened.dev || after.ino !== opened.ino
+      || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) return { kind: "unknown" };
+    const journal: unknown = JSON.parse(bytes.subarray(0, length).toString("utf8"));
+    return validJournal(journal) ? { kind: "read", journal } : { kind: "unknown" };
+  } catch (error) {
+    return fd === undefined && absent(error) && provenAbsent(journalPath) ? { kind: "missing" } : { kind: "unknown" };
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function inspectBinding(boundHome: string, current: string): CodexHomeOwnership {
+  let physical: string;
+  try {
+    physical = realpathSync.native(boundHome);
+    if (!statSync(physical).isDirectory()) return { kind: "unknown" };
+  } catch { return provenAbsent(boundHome) ? { kind: "stale", boundHome } : { kind: "unknown" }; }
+  try {
+    const own = realpathSync.native(current);
+    if (!statSync(own).isDirectory()) return { kind: "unknown" };
+    return samePathIdentity(physical, own) ? { kind: "owned" } : { kind: "foreign", boundHome };
+  } catch { return { kind: "unknown" }; }
+}
+
+export function inspectCodexHomeOwner(canonicalHome: string, current = currentOpencodexHome()): CodexHomeOwnership {
+  const read = readCodexHomeJournal(join(canonicalHome, CODEX_HOME_JOURNAL_FILE));
+  if (read.kind === "unknown") return { kind: "unknown" };
+  if (read.kind === "missing" || read.journal.opencodexHome === undefined) return { kind: "unbound" };
+  return inspectBinding(read.journal.opencodexHome as string, current);
+}
+
+/** Preserve extant and uncertain bindings; only legacy or proven stale records are adopted. */
+export function opencodexHomeForInjection(recorded: string | undefined, current = currentOpencodexHome()): string {
+  if (recorded === undefined) return current;
+  return inspectBinding(recorded, current).kind === "stale" ? current : recorded;
+}
+
+export type CodexHomeOwnerRefusalReason = "foreign-owner" | "owner-unknown";
+export class CodexHomeOwnerRefusal extends Error {
+  constructor(readonly reason: CodexHomeOwnerRefusalReason) {
+    super(reason === "foreign-owner"
+      ? "Codex home is bound to another OpenCodex home; configuration and journal were preserved. Restore from the owning home first."
+      : "Codex home ownership could not be verified; configuration and journal were preserved.");
+    this.name = "CodexHomeOwnerRefusal";
+  }
+}
+export function assertCodexHomeOwner(home: string): void {
+  const owner = inspectCodexHomeOwner(home);
+  if (owner.kind === "foreign" || owner.kind === "unknown") {
+    throw new CodexHomeOwnerRefusal(owner.kind === "foreign" ? "foreign-owner" : "owner-unknown");
+  }
+}
+
+/** Compensation must not replace evidence another home published during this operation. */
+export function codexHomeOwnerBlocksCompensation(home: string, error: unknown): boolean {
+  if (!(error instanceof CodexHomeOwnerRefusal)) return false;
+  const owner = inspectCodexHomeOwner(home);
+  return owner.kind === "foreign" || owner.kind === "unknown";
+}