@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/codex/convergence.ts

@@ -1,5 +1,6 @@
 import { projectAntigravitySelectedModels } from "../providers/antigravity-effort-families";
 import { join } from "node:path";
+import { sameCatalogHealPath } from "./catalog/heal-observation";
 
 import { getConfigDir, saveConfigPreservingClaudeCode, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
 import { reconcileSuccessfulModelDiscoveries } from "../providers/new-model-policy";
@@ -83,11 +84,20 @@ import {
   type CodexModelEntitlementSnapshot,
 } from "./model-entitlements";
 import { resolveAdmittedCodexModelEntitlements } from "./model-entitlement-admission";
+import {
+  FOREIGN_CODEX_HOME_OWNER_MESSAGE,
+  UNKNOWN_CODEX_HOME_OWNER_MESSAGE,
+  routedRemovalBackedByConfigFile,
+  unbackedRoutedRemovalMessage,
+  unconfiguredRoutedRemoval,
+  type UnconfiguredRoutedRemoval,
+} from "./catalog/routed-removal";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
 import { providerCodexAccountMode } from "../providers/registry";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { withCatalogWriteSerialization } from "./catalog-write-serialization";
 import {
+  auditRefusedCatalogReplacement,
   publishHashedCodexCatalogBackup,
   publishLegacyCodexCatalogBackup,
   replaceActiveCodexCatalog,
@@ -109,14 +119,20 @@ import type {
 export interface CatalogWriteReceipt {
   readonly keyedBackup: "written" | "preserved" | "not-requested";
   readonly legacyBackup: "written" | "preserved" | "not-requested";
-  readonly catalog: "written" | "not-written";
-  readonly cache: "written" | "not-written";
+  /** `unchanged`: the bytes on disk already matched, so nothing was rewritten. */
+  readonly catalog: "written" | "unchanged" | "not-written";
+  readonly cache: "written" | "unchanged" | "not-written";
 }
 
 export type CodexCatalogCommitResult =
   | { readonly kind: "committed"; readonly changed: boolean; readonly writes: CatalogWriteReceipt }
   | { readonly kind: "stale"; readonly reason: "generation" | "home-selection" | "source-observation" | "process-local" | "target-identity" | "candidate-consumed" | "account-entitlement" }
-  | { readonly kind: "refused"; readonly reason: "source-unreadable" | "source-ambiguous" | "target-unsafe" }
+  /**
+   * `unbacked-routed-removal`: the candidate drops routed namespaces config.json does not back, or
+   * clears every routed row while config.json is unreadable. `foreign-owner`: this Codex home is
+   * bound to another OPENCODEX_HOME (#6529).
+   */
+  | { readonly kind: "refused"; readonly reason: "source-unreadable" | "source-ambiguous" | "target-unsafe" | "unbacked-routed-removal" | "foreign-owner" | "owner-unknown" }
   | { readonly kind: "failed"; readonly surface: "disk"; readonly writes: CatalogWriteReceipt };
 
 declare const catalogCandidateBrand: unique symbol;
@@ -140,10 +156,11 @@ interface CandidateState {
   readonly cache: PreparedCatalogFileWrite;
   readonly keyedBackup?: PreparedCatalogFileWrite;
   readonly legacyBackup?: PreparedCatalogFileWrite;
-  readonly changed: boolean;
   readonly notices: readonly CatalogNotice[];
   readonly modelEntitlements: CodexModelEntitlementSnapshot;
   readonly discoveryConfig?: OcxConfig;
+  /** Routed namespaces this candidate empties only because the driving config lacks them. */
+  readonly routedRemoval: UnconfiguredRoutedRemoval | null;
 }
 
 const candidateStates = new WeakMap<object, CandidateState>();
@@ -537,11 +554,10 @@ export async function gatherCodexCatalogCandidate(
       ...(pristineBytes ? { keyedBackup: { path: paths.keyedBackup, content: pristineBytes } } : {}),
       ...(pristineBytes && paths.legacyBackup
         ? { legacyBackup: { path: paths.legacyBackup, content: pristineBytes } } : {}),
-      changed: Buffer.from(activeBytes ?? []).toString("utf8") !== preparedCatalogBytes
-        || Buffer.from(cacheBytes ?? []).toString("utf8") !== preparedCacheBytes,
       notices: Object.freeze([...notices]),
       modelEntitlements,
       ...(discoveryChanged ? { discoveryConfig } : {}),
+      routedRemoval: unconfiguredRoutedRemoval(active, preparedCatalog, snapshot.config),
     });
     return { kind: "candidate", candidate };
   } catch (error) {
@@ -626,11 +642,14 @@ function fixedCommit(state: CandidateState, permit: Parameters<typeof replaceAct
     if (state.legacyBackup) {
       writes = { ...writes, legacyBackup: publishLegacyCodexCatalogBackup(permit, state.home, state.legacyBackup) };
     }
-    replaceActiveCodexCatalog(permit, state.home, state.catalog);
-    writes = { ...writes, catalog: "written" };
-    replaceCodexModelsCache(permit, state.home, state.cache);
-    writes = { ...writes, cache: "written" };
-    return { kind: "committed", changed: state.changed, writes };
+    const catalog = replaceActiveCodexCatalog(permit, state.home, state.catalog);
+    // The funnel's backstop: every routed row would go while config.json is not a readable file.
+    // Nothing past the pristine backups was written, and the cache must not describe a catalog
+    // that was never published.
+    if (catalog.kind === "refused") return { kind: "refused", reason: "unbacked-routed-removal" };
+    writes = { ...writes, catalog: catalog.kind };
+    writes = { ...writes, cache: replaceCodexModelsCache(permit, state.home, state.cache).kind };
+    return { kind: "committed", changed: writes.catalog === "written" || writes.cache === "written", writes };
   } catch {
     return { kind: "failed", surface: "disk", writes };
   }
@@ -639,6 +658,7 @@ function fixedCommit(state: CandidateState, permit: Parameters<typeof replaceAct
 export async function commitCodexCatalogCandidate(
   candidate: CodexCatalogCandidate,
   deadlineMs: number,
+  lifecycle: Readonly<{ beforeCommit?: () => boolean; expectedCatalogPath?: string }> = {},
 ): Promise<CommitAttempt> {
   const state = candidateStates.get(candidate as object);
   if (!state) return { kind: "refused", reason: "source-ambiguous" };
@@ -649,13 +669,33 @@ export async function commitCodexCatalogCandidate(
       state.consumed = true;
       const guarded = withExpectedConfigGenerationSync(state.generation, () => {
         const invalid = revalidateCandidate(state);
-        return invalid ?? fixedCommit(state, permit);
+        if (invalid) return invalid;
+        if (lifecycle.expectedCatalogPath !== undefined && !sameCatalogHealPath(state.catalog.path, lifecycle.expectedCatalogPath)) {
+          return { kind: "stale", reason: "target-identity" } as const;
+        }
+        if (lifecycle.beforeCommit && lifecycle.beforeCommit() !== true) return { kind: "stale", reason: "process-local" } as const;
+        // A refresh may empty a routed namespace only when config.json on disk agrees it is gone.
+        // Read under K, so a config that fell back to defaults during a transient read failure,
+        // or that belongs to another OPENCODEX_HOME, cannot publish a native-only catalog (#6529).
+        if (state.routedRemoval !== null && !routedRemovalBackedByConfigFile(state.routedRemoval)) {
+          auditRefusedCatalogReplacement(permit, state.home, state.catalog, "unbacked-routed-removal");
+          console.warn(`[opencodex] ${unbackedRoutedRemovalMessage(state.routedRemoval.namespaces.length)}`);
+          return { kind: "refused", reason: "unbacked-routed-removal" } as const;
+        }
+        return fixedCommit(state, permit);
       });
       if (guarded.kind === "conflict") return { kind: "stale", reason: "generation" } as const;
       if (guarded.kind === "unavailable") return { kind: "busy" } as const;
       return guarded.value;
-    });
+    }, { intent: "refresh", writer: "convergence" });
     if (acquired.kind === "completed") return acquired.value;
+    if (acquired.reason === "foreign-owner" || acquired.reason === "owner-unknown") {
+      // Not retryable: another OPENCODEX_HOME owns this Codex home until it restores (#6529).
+      state.consumed = true;
+      console.warn(`[opencodex] ${acquired.reason === "foreign-owner"
+        ? FOREIGN_CODEX_HOME_OWNER_MESSAGE : UNKNOWN_CODEX_HOME_OWNER_MESSAGE}`);
+      return { kind: "refused", reason: acquired.reason };
+    }
     if (acquired.reason !== "busy" || Date.now() >= deadline) return { kind: "busy" };
     await Bun.sleep(Math.min(10, Math.max(1, deadline - Date.now())));
   }
@@ -676,7 +716,7 @@ function projectCommit(result: CommitAttempt, notices: readonly CatalogNotice[])
 export async function convergeCodexCatalog(
   snapshot: CatalogAdmissionSnapshot,
   request: ConvergeRequest,
-  lifecycle: Readonly<{ onCommitBegin?: () => void }> = {},
+  lifecycle: Readonly<{ onCommitBegin?: () => void; beforeCommit?: () => boolean; expectedCatalogPath?: string }> = {},
 ): Promise<Readonly<{ changed: boolean; catalogRefresh: CatalogDisposition }>> {
   if (request.scope !== "catalog" || request.action !== "converge") {
     return {
@@ -688,7 +728,7 @@ export async function convergeCodexCatalog(
   if (gathered.kind === "disposition") return { changed: false, catalogRefresh: gathered.disposition };
   const state = candidateStates.get(gathered.candidate as object)!;
   lifecycle.onCommitBegin?.();
-  const committed = await commitCodexCatalogCandidate(gathered.candidate, request.deadlineMs);
+  const committed = await commitCodexCatalogCandidate(gathered.candidate, request.deadlineMs, lifecycle);
   if (committed.kind === "committed" && state.discoveryConfig) {
     const mutable = snapshot.config as OcxConfig;
     mutable.modelDiscovery = state.discoveryConfig.modelDiscovery;

package/src/codex/features.ts

@@ -38,6 +38,7 @@ import { AtomicWriteResidualTempError, AtomicWriteSecretResidualError, atomicWri
 import { forgetEphemeralSecretPath } from "../lib/windows-secret-acl";
 import { CODEX_CONFIG_PATH } from "./paths";
 import { resolveAndPersistCodexRuntime } from "./runtime";
+import { decodeOverlayState } from "./shim-state-file";
 import { canonicalizeOpenCodexModeHint } from "./multi-agent-mode-policy";
 
 /** Upstream codex-rs feature key: allow `request_user_input` in Default mode. */
@@ -1232,13 +1233,19 @@ function codexNativeBinaryCandidates(command: string): string[] {
 /** Backing paths tied to this exact OCX shim entry in codex-shim.json. */
 function selectedShimBackingPaths(commandPath: string): string[] {
   try {
-    const state = JSON.parse(readFileSync(join(getConfigDir(), "codex-shim.json"), "utf8")) as {
+    const configDir = getConfigDir();
+    const state = JSON.parse(readFileSync(join(configDir, "codex-shim.json"), "utf8")) as {
+      schema?: unknown;
+      mode?: unknown;
       wrapperPath?: unknown;
       originalPath?: unknown;
       backupPath?: unknown;
       realPath?: unknown;
       wrappers?: Array<Record<string, unknown>>;
     };
+    const overlay = decodeOverlayState(state, configDir);
+    if (overlay) return resolve(overlay.wrapperPath) === resolve(commandPath) ? [overlay.launcherPath] : [];
+    if (state.schema !== undefined || state.mode !== undefined) return [];
     const entries = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
     const selected = resolve(commandPath);
     for (const entry of entries) {

package/src/codex/inject/restore.ts

@@ -1,8 +1,11 @@
+import { assertCodexHomeOwner, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
 import { loadConfig } from "../../config";
 import { shouldSyncCodexOnStart } from "../desired-state";
 import { siblingOfLivePort, siblingSkipMessage } from "../sibling-start";
 import { withCatalogWriteSerialization } from "../catalog-write-serialization";
 import { restoreCodexCatalogWithPermit } from "../catalog/sync";
+import { readCodexCatalogPath } from "../catalog/parsing";
+import { notifyCatalogPublication } from "../catalog/publication-observer";
 import { withCodexWriteLock, CodexWriteLockSkipped } from "../codex-write-lock";
 import { inspectNativeCodexOwnership } from "../../integrations/native/ownership-preflight";
 import { resolveCodexHistoryTransition } from "../history-transition";
@@ -24,6 +27,7 @@ import {
 import {
   journaledInjectedCatalogPath,
   removeJournal,
+  releaseJournalHomeBinding,
   restoreJournalState,
 } from "../journal";
 import {
@@ -128,6 +132,7 @@ export interface CodexRestoreHistoryResult {
 }
 
 export interface CodexNativeRestoreResult {
+  ownershipRefusal?: CodexHomeOwnerRefusalReason;
   success: boolean;
   message: string;
   externalProvider?: string;
@@ -339,6 +344,9 @@ export interface RestoreConfigOptions {
 
 /** The config/profile half of a native restore, reported as one artifact. */
 function restoreCodexConfigInline(kind = "sync", options: RestoreConfigOptions = {}): CodexRestoreConfigResult {
+  assertCodexHomeOwner(getCodexHome());
+  beforeRestoreConfigForTests?.(kind);
+  assertCodexHomeOwner(getCodexHome());
   const preImages = captureCodexPreImages();
   const result = restoreCodexConfigInlineImpl(kind, options);
   if (result.state === "failed") {
@@ -350,7 +358,6 @@ function restoreCodexConfigInline(kind = "sync", options: RestoreConfigOptions =
 
 function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOptions): CodexRestoreConfigResult {
   try {
-    beforeRestoreConfigForTests?.(kind);
     const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
     if (disposition.kind === "refuse") {
       return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${disposition.reason}.` };
@@ -368,12 +375,20 @@ function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOption
     // accepting that tagged conversations stop opening.
     const capturedBlock = options.removeProviderTable === true ? null : readOcxProviderTableBlock();
     const journal = restoreJournalState();
+    if (journal.ownershipRefusal) throw new CodexHomeOwnerRefusal(journal.ownershipRefusal);
     if (journal.unverified) {
       return {
         state: "failed", changed: false, action: "failed",
         message: "Codex journal recovery was not verified; current configuration files and the journal were preserved.",
       };
     }
+    if (journal.profileRestoreFailed) {
+      return {
+        state: "failed", changed: false, action: "failed",
+        message: "Codex profile could not be restored; native files and the journal binding were preserved.",
+      };
+    }
+    assertCodexHomeOwner(getCodexHome());
     const restored = journal.configRestored
       ? { success: true, message: "Codex config restored from opencodex journal.", retainedProviderTable: undefined as string[] | undefined }
       : removeCodexConfig({
@@ -403,6 +418,9 @@ function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOption
       if (settled.kind === "stand-down" && settled.retainProviderTable && capturedBlock !== null) {
         retainedLines = retainOcxProviderTableOnDisk(capturedBlock) ?? retainedLines;
       }
+      // All native work and the final migration check succeeded. A field-level
+      // fallback retains its snapshot, but no longer owns this Codex home.
+      releaseJournalHomeBinding();
     }
     if (restored.success && retainedLines !== null) {
       return {
@@ -430,6 +448,7 @@ function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOption
         }
       : { state: "failed", changed: false, action: "failed", message: restored.message };
   } catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) throw error;
     return { state: "failed", changed: false, action: "failed", message: error instanceof Error ? error.message : String(error) };
   }
 }
@@ -451,7 +470,8 @@ function restoreCodexCatalogArtifact(
     const restored = withCatalogWriteSerialization(owningCodexHome, permit =>
       revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())
         ? null
-        : restoreCodexCatalogWithPermit(permit, owningCodexHome, journaledCatalogPath));
+        : restoreCodexCatalogWithPermit(permit, owningCodexHome, journaledCatalogPath),
+      { intent: "restore", writer: "codex-restore" });
     return restored.kind === "completed" && restored.value !== null
       ? { state: "ok", changed: restored.value.removed > 0, ...restored.value, message: "Codex catalog restored." }
       : restored.kind === "completed"
@@ -487,8 +507,10 @@ export async function restoreNativeCodexAsync(
   const sibling = siblingRestoreSkip();
   if (sibling) return sibling;
   try {
+    assertCodexHomeOwner(getCodexHome());
     return await restoreNativeCodexAsyncImpl(options);
   } catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     if (!(error instanceof CodexRestoreRefusal)) throw error;
     return failedConfigRestoreEnvelope(error.config);
   }
@@ -533,7 +555,7 @@ async function restoreNativeCodexAsyncImpl(
   // Captured before the config half: a successful journal restore DELETES the journal, and
   // restoring the config can drop `model_catalog_json`. Either one would hide the routed
   // catalog we actually wrote (#1798).
-  const journaledCatalogPath = journaledInjectedCatalogPath();
+  const journaledCatalogPath = journaledInjectedCatalogPath() ?? readCodexCatalogPath();
   let config: CodexRestoreConfigResult;
   let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
 
@@ -549,6 +571,7 @@ async function restoreNativeCodexAsyncImpl(
         readAdmissionUnderLock: () => witness,
       },
       (ctx) => {
+        assertCodexHomeOwner(getCodexHome());
         if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
           throw new CodexWriteLockSkipped("desired_enabled");
         }
@@ -576,6 +599,7 @@ async function restoreNativeCodexAsyncImpl(
           // Throw inside N so the published remove transition rolls back too.
           if (restored.state === "failed") throw new CodexRestoreRefusal(restored);
         } catch (error) {
+          if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
           const compensated = restoreCodexPreImages(preImages);
           if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
           throw error;
@@ -619,6 +643,7 @@ async function restoreNativeCodexAsyncImpl(
   }
 
   if (config.state === "failed") return failedConfigRestoreEnvelope(config);
+  notifyCatalogPublication({ kind: "native-released", path: journaledCatalogPath });
   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   // Re-asked after the config half, because the store can paginate mid-transaction. Deciding
   // the history job from the pre-write answer alone would spawn a Worker whose own preflight
@@ -681,11 +706,27 @@ async function restoreNativeCodexAsyncImpl(
   };
 }
 
+function homeOwnerRestoreRefusal(error: CodexHomeOwnerRefusal): CodexNativeRestoreResult {
+  return { ...skippedRestoreEnvelope(false, error.message), ownershipRefusal: error.reason };
+}
+
 export function restoreNativeCodex(
   options: { skipHistory?: boolean; revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
 ): CodexNativeRestoreResult {
   const sibling = siblingRestoreSkip();
   if (sibling) return sibling;
+  try {
+    assertCodexHomeOwner(getCodexHome());
+    return restoreNativeCodexImpl(options);
+  } catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
+    throw error;
+  }
+}
+
+function restoreNativeCodexImpl(
+  options: { skipHistory?: boolean; revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
+): CodexNativeRestoreResult {
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
     removeJournal();
@@ -700,9 +741,10 @@ export function restoreNativeCodex(
   // Captured before the config half: a successful journal restore DELETES the journal, and
   // restoring the config can drop `model_catalog_json`. Either one would hide the routed
   // catalog we actually wrote (#1798).
-  const journaledCatalogPath = journaledInjectedCatalogPath();
+  const journaledCatalogPath = journaledInjectedCatalogPath() ?? readCodexCatalogPath();
   const config = restoreCodexConfigInline("sync", options);
   if (config.state === "failed") return failedConfigRestoreEnvelope(config);
+  notifyCatalogPublication({ kind: "native-released", path: journaledCatalogPath });
   // Same mid-transaction pagination re-check as the async path.
   const historyStoodDown = historyStandsDown
     || resolveRestoreHistoryDisposition(options.removeProviderTable).kind === "stand-down";

package/src/codex/inject.ts

@@ -7,6 +7,7 @@ import {
   readConfigAdmissionSnapshot,
   withConfigMutationLockSync,
 } from "../config";
+import { assertCodexHomeOwner, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
 import { CodexWriteLockSkipped, withCodexWriteLock } from "./codex-write-lock";
 import {
   localClientSkipMessage,
@@ -134,6 +135,7 @@ function runClientWriteGuard(guard: InjectCodexOptions["beforeClientWrite"]): vo
 
 
 export interface CodexInjectResult {
+  ownershipRefusal?: CodexHomeOwnerRefusalReason;
   success: boolean;
   message: string;
   /** False when injection intentionally preserves configuration owned by another provider. */
@@ -192,8 +194,9 @@ export async function injectCodexConfig(
   if (siblingOfLivePort() !== null) {
     return { success: true, status: "skipped", skippedReason: "sibling", message: siblingSkipMessage() };
   }
-  try { return await injectCodexConfigImpl(port, config, options); }
+  try { assertCodexHomeOwner(getCodexHome()); return await injectCodexConfigImpl(port, config, options); }
   catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) return { success: false, ownershipRefusal: error.reason, message: error.message };
     if (error instanceof CodexHistoryPreflightRefusal) return { success: false, historyPreflightFailureReason: error.message, message: `Codex config injection refused: ${error.message}. Existing configuration and history were preserved.` };
     if (error instanceof CodexInjectRefusal) return error.result;
     throw error;
@@ -415,6 +418,7 @@ async function injectCodexConfigImpl(
    * flip included — before the result is reported.
    */
   const reconcileAndDerivePlan = (): { plan: CodexInjectionPlanOk; nativeInput: string } => {
+    assertCodexHomeOwner(getCodexHome());
     if (missingConfig) createEmptyCodexConfigInBoundary();
     let nativeInput = rawContent;
     let plan = admittedPlan;
@@ -453,6 +457,7 @@ async function injectCodexConfigImpl(
     beforeHistoryArtifactCommitForTests?.(eligibility.kind);
     plan.historyRelabelRefusal = observeHistoryRefusalOrThrow(plan);
     historyArtifactStageForTests?.("after-preflight");
+    assertCodexHomeOwner(getCodexHome());
     writeJournal({
       currentStateIsNative: journalBaselineIsNative(nativeInput),
       configContent: plan.baselineContent,
@@ -463,6 +468,7 @@ async function injectCodexConfigImpl(
     if (hasUnverifiedJournalBaseline(plan.baselineContent, readCurrentProfile())) throw new Error(unverifiedJournalMessage);
     atomicWriteFile(CODEX_CONFIG_PATH, plan.content);
     historyArtifactStageForTests?.("after-config");
+    assertCodexHomeOwner(getCodexHome());
     atomicWriteFile(CODEX_PROFILE_PATH, plan.profileContent);
     markJournalInjectedState(plan.content, plan.profileContent, {
       // A root override is ours whenever we wrote one and no user-owned value won. That is
@@ -526,6 +532,7 @@ async function injectCodexConfigImpl(
         };
       }
       runClientWriteGuard(options.beforeClientWrite);
+      assertCodexHomeOwner(getCodexHome());
       /*
        * One preimage covers the reconcile and the artifact commit together: a
        * refusal after the feature transition hands back the exact bytes the
@@ -537,6 +544,7 @@ async function injectCodexConfigImpl(
         applyNativeArtifacts(resolved.plan, resolved.nativeInput);
         effectivePlan = resolved.plan;
       } catch (error) {
+        if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
         const restored = restoreCodexPreImages(preImages);
         if (!restored.complete) throw new CodexPartialWriteError(restored.unrestored);
         throw error;
@@ -582,6 +590,7 @@ async function injectCodexConfigImpl(
         // transition or capturing preimages; rejection must not compensate over
         // a disconnect's restored files.
         runClientWriteGuard(options.beforeClientWrite);
+        assertCodexHomeOwner(getCodexHome());
         /*
          * Exact pre-images, captured under the lock and used for compensation.
          *
@@ -630,6 +639,7 @@ async function injectCodexConfigImpl(
           }
           applyNativeArtifacts(resolved.plan, resolved.nativeInput);
         } catch (error) {
+          if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
           // Compensate, then ALWAYS throw. Returning a partial result would let the
           // lock commit a row describing an apply that did not finish.
           const restored = restoreCodexPreImages(preImages);

package/src/codex/internal/catalog-writer.ts

@@ -5,12 +5,21 @@ import {
   AtomicWriteResidualTempError,
   AtomicWriteSecretResidualError,
   atomicWriteFile,
-  getConfigDir,
   resolveWriteTarget,
   type AtomicWriteIO,
-} from "../../config";
+} from "../../config/atomic-write";
+import { getConfigDir } from "../../config/paths";
+import { readConfigAdmissionSnapshot } from "../../config/diagnostics";
+import { ConfigMutationLockError, withConfigMutationLockSync } from "../../config/mutation-lock";
+import { codexCatalogAuditPath } from "../catalog/write-audit";
+import type { CatalogAuditConfigSource, CatalogAuditRefusalReason, CatalogWriteAuditDetails } from "../catalog/write-audit-contract";
+import { ocxRoutedRowCount } from "../catalog/routed-removal";
+import { notifyCatalogPublication } from "../catalog/publication-observer";
 import {
   assertCatalogWritePermit,
+  auditCatalogWriteWithPermit,
+  catalogWritePermitContext,
+  CatalogWritePermitRefusal,
   type CatalogWritePermit,
 } from "../catalog-write-serialization";
 import {
@@ -61,14 +70,15 @@ let backupTempSequence = 0;
  * An unreadable or absent file reports "differs", so the caller performs the real
  * write; that also converges a file that does not exist yet.
  */
-export function preparedBytesDifferFromDisk(prepared: PreparedCatalogFileWrite): boolean {
-  let onDisk: Buffer;
-  try {
-    onDisk = readFileSync(prepared.path);
-  } catch {
-    return true;
-  }
-  return !onDisk.equals(Buffer.from(prepared.content, "utf8"));
+function readExistingCatalogBytes(path: string): Buffer | null {
+  try { return readFileSync(path); } catch { return null; }
+}
+
+export function preparedBytesDifferFromDisk(
+  prepared: PreparedCatalogFileWrite,
+  onDisk: Buffer | null = readExistingCatalogBytes(prepared.path),
+): boolean {
+  return onDisk === null || !onDisk.equals(Buffer.from(prepared.content, "utf8"));
 }
 
 function isMissingPathError(error: unknown): boolean {
@@ -199,16 +209,105 @@ function publishCatalogBackup(
   return "written";
 }
 
-/** Replace the active catalog with the caller's already-prepared bytes. */
+export type CatalogFileReplacement =
+  | { readonly kind: "written" }
+  | { readonly kind: "unchanged" }
+  | { readonly kind: "refused"; readonly reason: "unbacked-routed-clear" };
+
+function routedRowsFromJson(content: string): number | null {
+  try { return ocxRoutedRowCount(JSON.parse(content)); } catch { return null; }
+}
+
+function configSourceNow(): CatalogAuditConfigSource {
+  try {
+    const snapshot = readConfigAdmissionSnapshot();
+    return snapshot.kind === "read" ? snapshot.diagnostics.source
+      : snapshot.diagnostics.source === "default" ? "default" : "unreadable";
+  } catch { return "unreadable"; }
+}
+
+function routedRowsOnDisk(path: string): number | null {
+  try { return routedRowsFromJson(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function auditWrite(
+  permit: CatalogWritePermit,
+  home: string,
+  details: CatalogWriteAuditDetails,
+  register: boolean,
+): void {
+  try {
+    if (auditCatalogWriteWithPermit(permit, home, details) !== "created"
+      || !register || details.configSource !== "file") return;
+    // The manifest rejects external CODEX_HOME paths. Such audit files remain uninstall
+    // residuals; diagnostic creation does not widen config ownership or claim cleanup.
+    if (!recordOwnedConfigPath(getConfigDir(), codexCatalogAuditPath(home))) return;
+  } catch { /* Audit and registration failures cannot change the publication outcome. */ }
+}
+
+/** Audit an actual refusal before the replacement funnel. Caller must avoid a second funnel event. */
+export function auditRefusedCatalogReplacement(
+  permit: CatalogWritePermit,
+  home: string,
+  prepared: PreparedCatalogFileWrite,
+  reason: CatalogAuditRefusalReason,
+): void {
+  assertCatalogWritePermit(permit, home);
+  auditWrite(permit, home, {
+    target: "catalog", outcome: "refused", reason,
+    routedBefore: routedRowsOnDisk(prepared.path), routedAfter: routedRowsFromJson(prepared.content),
+    configSource: configSourceNow(),
+  }, true);
+}
+
+/** One funnel for exact-byte idempotence and intent admission, under a live K permit. */
 export function replaceActiveCodexCatalog(
   permit: CatalogWritePermit,
   owningCodexHome: string,
   prepared: PreparedCatalogFileWrite,
   io?: AtomicWriteIO,
-): void {
+): CatalogFileReplacement {
   assertCatalogWritePermit(permit, owningCodexHome);
+  const { intent } = catalogWritePermitContext(permit);
+  if (intent === "cache") {
+    throw new CatalogWritePermitRefusal("A models-cache permit cannot replace the Codex catalog.");
+  }
+  const onDisk = readExistingCatalogBytes(prepared.path);
+  if (!preparedBytesDifferFromDisk(prepared, onDisk)) {
+    notifyCatalogPublication({ kind: "published", path: prepared.path, intent });
+    return { kind: "unchanged" };
+  }
+  const routedBefore = onDisk === null ? null : routedRowsFromJson(onDisk.toString("utf8"));
+  const routedAfter = routedRowsFromJson(prepared.content);
+  const finish = (result: CatalogFileReplacement): CatalogFileReplacement => {
+    if (result.kind !== "unchanged") auditWrite(permit, owningCodexHome, {
+      target: "catalog", outcome: result.kind,
+      reason: result.kind === "refused" ? result.reason : undefined,
+      routedBefore, routedAfter, configSource: configSourceNow(),
+    }, io === undefined);
+    if (result.kind !== "refused") notifyCatalogPublication({ kind: "published", path: prepared.path, intent });
+    return result;
+  };
+  if (intent === "refresh" && (routedBefore ?? 0) > 0 && routedAfter === 0) {
+    // K -> C, including the replacement: a config save cannot race the authority check.
+    try {
+      return finish(withConfigMutationLockSync(() => {
+        const snapshot = readConfigAdmissionSnapshot();
+        if (snapshot.kind !== "read" || snapshot.diagnostics.source !== "file") {
+          return { kind: "refused", reason: "unbacked-routed-clear" } as const;
+        }
+        atomicWriteFile(prepared.path, prepared.content, io);
+        resetCodexAppServerCatalogStateCache();
+        return { kind: "written" } as const;
+      }));
+    } catch (error) {
+      if (error instanceof ConfigMutationLockError) return finish({ kind: "refused", reason: "unbacked-routed-clear" });
+      throw error;
+    }
+  }
   atomicWriteFile(prepared.path, prepared.content, io);
   resetCodexAppServerCatalogStateCache();
+  return finish({ kind: "written" });
 }
 
 /** Atomically publish the catalog-path-keyed immutable backup without clobbering. */
@@ -242,8 +341,16 @@ export function replaceCodexModelsCache(
   owningCodexHome: string,
   prepared: PreparedCatalogFileWrite,
   io?: AtomicWriteIO,
-): void {
+): Exclude<CatalogFileReplacement, { kind: "refused" }> {
   assertCatalogWritePermit(permit, owningCodexHome);
+  catalogWritePermitContext(permit);
+  if (!preparedBytesDifferFromDisk(prepared)) return { kind: "unchanged" };
+  const routedBefore = routedRowsOnDisk(prepared.path);
   atomicWriteFile(prepared.path, prepared.content, io);
   resetCodexAppServerCatalogStateCache();
+  auditWrite(permit, owningCodexHome, {
+    target: "cache", outcome: "written", routedBefore,
+    routedAfter: routedRowsFromJson(prepared.content), configSource: configSourceNow(),
+  }, io === undefined);
+  return { kind: "written" };
 }