@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/codex/catalog/write-audit-contract.ts

@@ -0,0 +1,21 @@
+/** Bottom-layer metadata contract: neither K nor the filesystem adapter owns intent. */
+export type CatalogWriteIntent = "refresh" | "cache" | "pull" | "restore";
+export type CatalogAuditConfigSource = "file" | "default" | "fallback" | "unreadable";
+export type CatalogAuditRefusalReason = "foreign-owner" | "owner-unknown"
+  | "unbacked-routed-removal" | "unbacked-routed-clear";
+
+export interface CatalogWriteAuditDetails {
+  readonly target: "catalog" | "cache";
+  readonly outcome: "written" | "refused";
+  readonly reason?: CatalogAuditRefusalReason;
+  readonly routedBefore?: number | null;
+  readonly routedAfter?: number | null;
+  readonly configSource?: CatalogAuditConfigSource;
+}
+
+export interface CatalogWriteAuditEvent extends CatalogWriteAuditDetails {
+  readonly intent: CatalogWriteIntent;
+  readonly writer: string;
+  /** Supplied by K, never discovered by the adapter. */
+  readonly opencodexHome: string;
+}

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

@@ -0,0 +1,171 @@
+import {
+  closeSync, constants, fstatSync, ftruncateSync, lstatSync, openSync, readSync, writeSync,
+  type Stats,
+} from "node:fs";
+import { join } from "node:path";
+import { redactUserPath } from "../../lib/redact";
+import { hardenSecretPath, windowsSecretAclApplies } from "../../lib/windows-secret-acl";
+import type { CatalogWriteAuditEvent } from "./write-audit-contract";
+
+export const CODEX_CATALOG_AUDIT_FILE = "opencodex-catalog-audit.jsonl";
+export const CATALOG_AUDIT_MAX_BYTES = 256 * 1024;
+export const CATALOG_AUDIT_KEEP_RECORDS = 400;
+export const CATALOG_AUDIT_MAX_EVENT_BYTES = 2 * 1024;
+const MAX_HOME_CHARACTERS = 256;
+const AUDIT_ACL_DEADLINE_MS = 1000;
+const WRITERS = new Set([
+  "convergence", "retained-sync", "cache-from-catalog", "cache-invalidate",
+  "catalog-pull", "catalog-restore", "codex-restore", "sync-cache", "startup-cache",
+]);
+
+export function codexCatalogAuditPath(codexHome: string): string {
+  return join(codexHome, CODEX_CATALOG_AUDIT_FILE);
+}
+
+function safeCount(value: number | null | undefined): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function auditLine(event: CatalogWriteAuditEvent): Buffer {
+  const writer = WRITERS.has(event.writer) ? event.writer : "other";
+  // Explicit projection: no argv, arbitrary event properties, model IDs or provider names.
+  return Buffer.from(`${JSON.stringify({
+    at: new Date().toISOString(), pid: process.pid, ppid: process.ppid,
+    command: writer,
+    opencodexHome: redactUserPath(event.opencodexHome).slice(0, MAX_HOME_CHARACTERS),
+    target: event.target, outcome: event.outcome, reason: event.reason,
+    intent: event.intent, writer,
+    configSource: event.configSource,
+    routedBefore: safeCount(event.routedBefore), routedAfter: safeCount(event.routedAfter),
+  })}\n`);
+}
+
+function regularPrivateFile(stat: Stats): boolean {
+  // POSIX bits cannot prove NTFS privacy. Windows requires fresh-file ACL hardening.
+  return !windowsSecretAclApplies() && stat.isFile() && stat.nlink === 1
+    && stat.uid === process.getuid?.() && (stat.mode & 0o777) === 0o600;
+}
+
+function sameFile(left: Stats, right: Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+    && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+
+/** Read at most the tail budget plus one byte to locate a complete first record. */
+function readTail(fd: number, size: number): Buffer {
+  const start = Math.max(0, size - CATALOG_AUDIT_MAX_BYTES - 1);
+  const bytes = Buffer.alloc(size - start);
+  let length = 0;
+  while (length < bytes.length) {
+    const count = readSync(fd, bytes, length, bytes.length - length, start + length);
+    if (count === 0) break;
+    length += count;
+  }
+  if (length !== bytes.length) throw new Error("audit file changed during read");
+  if (start === 0) return bytes;
+  const boundary = bytes.indexOf(10);
+  return boundary === -1 ? Buffer.alloc(0) : bytes.subarray(boundary + 1);
+}
+
+function completeRecords(bytes: Buffer): { records: Buffer[]; count: number; clean: boolean } {
+  const records: Buffer[] = [];
+  let start = 0;
+  let clean = true;
+  let count = 0;
+  for (let end = bytes.indexOf(10); end !== -1; end = bytes.indexOf(10, start)) {
+    const line = bytes.subarray(start, end);
+    try {
+      const text = line.toString("utf8");
+      if (!line.equals(Buffer.from(text))) throw new Error("invalid UTF-8");
+      JSON.parse(text);
+      records[count % CATALOG_AUDIT_KEEP_RECORDS] = bytes.subarray(start, end + 1);
+      count++;
+    } catch { clean = false; }
+    start = end + 1;
+  }
+  const pivot = count > CATALOG_AUDIT_KEEP_RECORDS ? count % CATALOG_AUDIT_KEEP_RECORDS : 0;
+  return { records: records.slice(pivot).concat(records.slice(0, pivot)), count,
+    clean: clean && start === bytes.length };
+}
+
+function writeAll(fd: number, bytes: Buffer, position: number | null): void {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const count = writeSync(fd, bytes, offset, bytes.length - offset,
+      position === null ? null : position + offset);
+    if (count === 0) throw new Error("audit write made no progress");
+    offset += count;
+  }
+}
+
+/**
+ * Best-effort adapter. Caller MUST hold K, even for a refusal that has no permit.
+ * POSIX owners compact the descriptor; foreign callers only append within both caps.
+ * Windows only publishes into fresh owner files after required ACL hardening.
+ * This diagnostic has no replay or authorization role. Process death may leave a partial line.
+ */
+export function appendCatalogWriteAudit(
+  codexHome: string,
+  event: CatalogWriteAuditEvent,
+  options: { readonly create: boolean },
+): "appended" | "created" | "skipped" {
+  let fd: number | undefined;
+  try {
+    const line = auditLine(event);
+    if (line.length > CATALOG_AUDIT_MAX_EVENT_BYTES) return "skipped";
+    const path = codexCatalogAuditPath(codexHome);
+    const windows = windowsSecretAclApplies();
+    let before: Stats | undefined;
+    try { before = lstatSync(path); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || !options.create) return "skipped";
+    }
+    if (before && !regularPrivateFile(before)) return "skipped";
+    // No mkdir, pathname truncation or chmod. O_EXCL prevents creation over a raced path.
+    const flags = constants.O_RDWR | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)
+      | (before ? (options.create ? 0 : constants.O_APPEND) : constants.O_CREAT | constants.O_EXCL);
+    fd = openSync(path, flags, 0o600);
+    let opened = fstatSync(fd);
+    if (windows) {
+      // Existing files have already been refused: no read-only NTFS privacy verifier exists.
+      if (!opened.isFile() || opened.nlink !== 1 || opened.size !== 0
+        || !sameFile(opened, lstatSync(path))) return "skipped";
+      if (!hardenSecretPath(path, { required: true, deadlineMs: AUDIT_ACL_DEADLINE_MS }).ok) return "skipped";
+      const hardened = fstatSync(fd);
+      // ACL changes legitimately move ctime. Retain object identity, then take a fresh baseline.
+      if (!hardened.isFile() || hardened.nlink !== 1 || hardened.size !== 0
+        || opened.dev !== hardened.dev || opened.ino !== hardened.ino
+        || !sameFile(hardened, lstatSync(path))) return "skipped";
+      opened = hardened;
+    } else if (!regularPrivateFile(opened) || (before && !sameFile(before, opened))) return "skipped";
+    if (!options.create && opened.size + line.length > CATALOG_AUDIT_MAX_BYTES) return "skipped";
+    const tail = readTail(fd, opened.size);
+    const parsed = completeRecords(tail);
+    if (!sameFile(opened, fstatSync(fd)) || !sameFile(opened, lstatSync(path))) return "skipped";
+    if (!options.create) {
+      if (!parsed.clean || parsed.count + 1 > CATALOG_AUDIT_KEEP_RECORDS) return "skipped";
+      writeAll(fd, line, null);
+    } else if (opened.size <= CATALOG_AUDIT_MAX_BYTES - line.length
+      && parsed.clean && parsed.count < CATALOG_AUDIT_KEEP_RECORDS) {
+      writeAll(fd, line, opened.size);
+    } else {
+      const retained: Buffer[] = [line];
+      let bytes = line.length;
+      for (let index = parsed.records.length - 1; index >= 0 && retained.length < CATALOG_AUDIT_KEEP_RECORDS; index--) {
+        const record = parsed.records[index]!;
+        if (bytes + record.length > CATALOG_AUDIT_MAX_BYTES) break;
+        retained.unshift(record);
+        bytes += record.length;
+      }
+      const output = Buffer.concat(retained, bytes);
+      writeAll(fd, output, 0);
+      ftruncateSync(fd, output.length);
+    }
+    return before ? "appended" : "created";
+  } catch {
+    // Deliberately best-effort: an audit IO failure never changes the catalog result.
+    return "skipped";
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* diagnostic only */ } }
+  }
+}

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