@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/v2.ts

@@ -10,6 +10,10 @@
  *    config keys, with byte-for-byte rollback when the feature command fails.
  *  - nothing in the catalog build path calls this module; no auto-flip exists.
  */
+import { CliUsageError, terminalSafeText, type RuntimeApiDeps } from "./runtime-api";
+import { parseV2Command, V2_USAGE, type V2ParsedCommand } from "./v2-input";
+import { handleV2RuntimeCommand } from "./v2-runtime";
+import { localV2State, v2LocalSyncResult, type V2LocalSync } from "./v2-local-output";
 import { execFileSync } from "node:child_process";
 import { dirname } from "node:path";
 import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
@@ -23,6 +27,9 @@ export interface V2CliDeps {
   isEnabled?: typeof isMultiAgentV2Enabled;
   hasMaxThreads?: typeof hasAgentsMaxThreads;
   sync?: (port?: number) => Promise<unknown>;
+  runtimeApi?: RuntimeApiDeps;
+  /** Internal seam: bypass executable discovery only when an exec implementation is injected. */
+  featuresInvocation?: (action: "enable" | "disable") => SpawnInvocation;
   log?: Pick<Console, "log" | "error">;
 }
 
@@ -79,7 +86,7 @@ export function runCodexFeaturesCommand(
 
 function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
   if (deps.execFile) {
-    const inv = codexFeaturesInvocation(action);
+    const inv = (deps.featuresInvocation ?? codexFeaturesInvocation)(action);
     deps.execFile(inv.file, inv.args, inv.options);
     return;
   }
@@ -106,13 +113,10 @@ function requiresGlobalV2Disabled(multiAgentMode: string | undefined, keepNative
   return multiAgentMode === "v2" && keepNativeChatGptOnV1;
 }
 
-export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
+function printLocalStatus(deps: V2CliDeps): number {
   const log = deps.log ?? console;
   const isEnabled = deps.isEnabled ?? isMultiAgentV2Enabled;
   const hasMaxThreads = deps.hasMaxThreads ?? hasAgentsMaxThreads;
-  const verb = (args[0] ?? "status").trim().toLowerCase();
-
-  if (verb === "status") {
     log.log(v2StatusLine(isEnabled()));
     const cfg = loadConfig();
     const mode = cfg.multiAgentMode ?? "default";
@@ -140,153 +144,107 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       log.log("WARNING: [agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove it from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
     }
     return 0;
+}
+
+/** Parse before selecting either the native writer or the runtime management target. */
+export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
+  const log = deps.log ?? console;
+  let parsed: V2ParsedCommand;
+  try { parsed = parseV2Command(args); }
+  catch (error) {
+    log.error(error instanceof CliUsageError ? error.message : "v2: invalid command");
+    for (const line of V2_USAGE.split("\n")) log.error(line);
+    const boundary = args.indexOf("--");
+    return (boundary < 0 ? args : args.slice(0, boundary)).includes("--live") ? 2 : 1;
   }
-  if (verb === "mode-hint") {
-    const value = args[1];
-    if (value === undefined) {
-      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
-      return 1;
-    }
-    if (value === "--clear") {
-      const result = setMultiAgentModeHintText(null);
-      if (!result.ok) {
-        log.error(`v2 mode-hint: ${result.error}`);
-        return 1;
-      }
-      log.log(result.changed
-        ? "multi_agent_mode_hint_text cleared — effort-derived policy resumes (new sessions)."
-        : "multi_agent_mode_hint_text already unset — nothing to do.");
-      return 0;
-    }
-    // `--clear` is the only reserved token; hints are otherwise arbitrary
-    // nonblank text and may legitimately begin with a hyphen.
-    if (value.trim().length === 0) {
-      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
-      return 1;
-    }
-    const result = setMultiAgentModeHintText(value);
-    if (!result.ok) {
-      log.error(`v2 mode-hint: ${result.error}`);
-      return 1;
+  if (parsed.live) return handleV2RuntimeCommand(parsed, deps.runtimeApi);
+  let changed: boolean | null = false;
+  let sync: V2LocalSync = { status: "not-attempted", ok: false };
+  const emit = (ok: boolean, lines: string[]): number => {
+    // A read-back failure cannot claim rollback or overwrite already observed mutation evidence.
+    let state: ReturnType<typeof localV2State> | null = null;
+    try { state = localV2State(deps.isEnabled, deps.hasMaxThreads); }
+    catch { ok = false; lines = ["Local V2 outcome is unverified. Read ocx v2 status before retrying; no rollback is implied."]; }
+    if (parsed.json) log.log(JSON.stringify({ ok, target: "local", action: parsed.verb, changed, state, sync }));
+    else for (const line of lines) (ok ? log.log : log.error).call(log, terminalSafeText(line));
+    return ok ? 0 : 1;
+  };
+  try {
+    if (parsed.verb === "status") {
+      if (!parsed.json) return printLocalStatus(deps);
+      return emit(true, []);
     }
-    log.log(result.changed
-      ? `multi_agent_mode_hint_text set (new sessions).`
-      : "multi_agent_mode_hint_text already set — nothing to do.");
-    return 0;
-  }
-  if (verb === "threads") {
-    const value = Number((args[1] ?? "").trim());
-    if (!Number.isInteger(value) || value < 1) {
-      log.error("v2 threads: pass an integer >= 1 (features.multi_agent_v2.max_concurrent_threads_per_session)");
-      return 1;
+    if (parsed.verb === "mode-hint") {
+      const result = setMultiAgentModeHintText(parsed.value);
+      if (!result.ok) return emit(false, ["Unable to write the native mode hint. Check Codex support and ownership, then read ocx v2 status."]);
+      changed = result.changed;
+      return emit(true, [result.changed ? "multi_agent_mode_hint_text saved — applies to new sessions." : "multi_agent_mode_hint_text already set — nothing to do."]);
     }
-    const enabled = isEnabled();
-    const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: value });
-    if (!result.ok) { log.error(`v2 threads: ${result.error}`); return 1; }
-    log.log(result.changed
-      ? `max_threads = ${value} (${enabled ? "v2" : "v1"}) — applies to new sessions.`
-      : `max_threads already ${value} — nothing to do.`);
-    return 0;
-  }
-  if (verb === "mode") {
-    const modeArg = (args[1] ?? "").trim().toLowerCase();
-    if (modeArg !== "v1" && modeArg !== "default" && modeArg !== "v2") {
-      log.error("v2 mode: expected v1|default|v2");
-      return 1;
+    if (parsed.verb === "threads") {
+      const enabled = (deps.isEnabled ?? isMultiAgentV2Enabled)();
+      const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: parsed.value });
+      if (!result.ok) return emit(false, ["Unable to update the native thread limit. Read ocx v2 status before retrying."]);
+      changed = result.changed;
+      return emit(true, [changed ? `max_threads = ${parsed.value} (${enabled ? "v2" : "v1"}) — applies to new sessions.` : `max_threads already ${parsed.value} — nothing to do.`]);
     }
-    const cfg = loadConfig();
-    if (modeArg !== "default") {
-      const target = modeArg === "v2" && cfg.keepNativeChatGptOnV1 !== true;
-      const transition = transitionMultiAgentV2(target, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
-      if (!transition.ok) {
-        log.error(`multi-agent mode transition failed: ${transition.error}`);
-        return 1;
+    const config = loadConfig();
+    let successLines: string[];
+    let unchangedKeep: boolean | undefined;
+    if (parsed.verb === "mode") {
+      changed = (config.multiAgentMode ?? "default") !== parsed.value;
+      if (parsed.value !== "default") {
+        const target = parsed.value === "v2" && config.keepNativeChatGptOnV1 !== true;
+        const transition = transitionMultiAgentV2(target, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        if (!transition.ok) { changed = false; return emit(false, ["Native mode transition failed. Read ocx v2 status before retrying."]); }
+        changed ||= transition.changed;
       }
-    }
-    if (modeArg === "default") deleteConfigTopLevelKey(cfg, "multiAgentMode");
-    else cfg.multiAgentMode = modeArg as "v1" | "v2";
-    saveConfig(cfg);
-    try {
-      const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
-      await sync(findPort ? await findPort() : undefined);
-    } catch (err) {
-      log.error(`catalog resync failed: ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
-      return 1;
-    }
-    log.log(multiAgentModeLine(modeArg));
-    log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version.");
-    return 0;
-  }
-  if (verb === "keep-native-v1") {
-    const flag = (args[1] ?? "").trim().toLowerCase();
-    if (flag !== "on" && flag !== "off") {
-      log.error("v2 keep-native-v1: expected on|off");
-      return 1;
-    }
-    const cfg = loadConfig();
-    const next = flag === "on";
-    const already = cfg.keepNativeChatGptOnV1 === true === next;
-    if (next && requiresGlobalV2Disabled(cfg.multiAgentMode, true)) {
-      const transition = transitionMultiAgentV2(false, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
-      if (!transition.ok) {
-        log.error(`keep-native-v1 transition failed: ${transition.error}`);
-        return 1;
+      if (parsed.value === "default") deleteConfigTopLevelKey(config, "multiAgentMode");
+      else config.multiAgentMode = parsed.value;
+      saveConfig(config);
+      successLines = [multiAgentModeLine(parsed.value, config.keepNativeChatGptOnV1 === true),
+        "Applies to NEW sessions; running sessions keep their pinned multi-agent version."];
+    } else if (parsed.verb === "keep-native-v1") {
+      unchangedKeep = (config.keepNativeChatGptOnV1 === true) === parsed.value;
+      changed = !unchangedKeep;
+      if (parsed.value && requiresGlobalV2Disabled(config.multiAgentMode, true)) {
+        const transition = transitionMultiAgentV2(false, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        if (!transition.ok) { changed = false; return emit(false, ["Native hybrid-mode transition failed. Read ocx v2 status before retrying."]); }
+        changed ||= transition.changed;
+      }
+      if (parsed.value) config.keepNativeChatGptOnV1 = true;
+      else deleteConfigTopLevelKey(config, "keepNativeChatGptOnV1");
+      saveConfig(config);
+      successLines = [parsed.value
+        ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2 (new sessions)."
+        : "keep_native_chatgpt_on_v1: OFF — ChatGPT-native rows follow v1/base/v2 (new sessions)."];
+    } else {
+      const want = parsed.verb === "on";
+      if (want && requiresGlobalV2Disabled(config.multiAgentMode, config.keepNativeChatGptOnV1 === true)) {
+        return emit(false, ["v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first."]);
       }
+      const transition = transitionMultiAgentV2(want, next => runCodexFeatures(next ? "enable" : "disable", deps));
+      if (!transition.ok) return emit(false, ["Native feature transition failed. Read ocx v2 status before retrying."]);
+      changed = transition.changed;
+      if (!changed) return emit(true, [`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`]);
+      successLines = [v2StatusLine(want),
+        "Applies to NEW sessions; running sessions keep their pinned multi-agent version. Restart the Codex app (or wait out its picker cache) to see the ladder change."];
     }
-    if (next) cfg.keepNativeChatGptOnV1 = true;
-    else deleteConfigTopLevelKey(cfg, "keepNativeChatGptOnV1");
-    saveConfig(cfg);
+    // Preserve the legacy graph: mode/keep and changed toggles sync even with no port.
     try {
-      const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
-      await sync(findPort ? await findPort() : undefined);
-    } catch (err) {
-      log.error(`catalog resync failed: ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
-      return 1;
-    }
-    if (already) {
-      log.log(next
-        ? "keep_native_chatgpt_on_v1 already ON — catalog re-synced."
-        : "keep_native_chatgpt_on_v1 already OFF — catalog re-synced.");
-      return 0;
-    }
-    log.log(next
-      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2 (new sessions)."
-      : "keep_native_chatgpt_on_v1: OFF — ChatGPT-native rows follow v1/base/v2 (new sessions).");
-    return 0;
-  }
-  if (verb !== "on" && verb !== "off") {
-    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>)`);
-    return 1;
-  }
-
-  const want = verb === "on";
-  if (want) {
-    const cfg = loadConfig();
-    if (requiresGlobalV2Disabled(cfg.multiAgentMode, cfg.keepNativeChatGptOnV1 === true)) {
-      log.error("v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first.");
-      return 1;
+      const port = findPort ? await findPort() : undefined;
+      const result = deps.sync ? await deps.sync(port)
+        : await (await import("../codex/sync")).syncModelsToCodex(port, undefined, parsed.json ? null : log);
+      sync = v2LocalSyncResult(result);
+    } catch { sync = { status: "failed", ok: false }; }
+    if (sync.ok && parsed.verb === "keep-native-v1" && unchangedKeep) {
+      const outcome = sync.status !== "skipped" && "catalog" in sync && sync.catalog?.converged
+        ? "catalog re-synced." : "catalog sync skipped by policy.";
+      successLines = [`keep_native_chatgpt_on_v1 already ${parsed.value ? "ON" : "OFF"} — ${outcome}`];
     }
+    return emit(sync.ok, sync.ok ? successLines
+      : ["catalog resync failed or is unverified; local V2 settings landed. Read ocx v2 status, then run ocx sync."]);
+  } catch {
+    changed = null;
+    return emit(false, ["Local V2 operation failed; native or saved settings may have changed. Read ocx v2 status before retrying; no rollback is implied."]);
   }
-  const transition = transitionMultiAgentV2(want, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
-  if (!transition.ok) {
-    log.error(`codex features ${want ? "enable" : "disable"} multi_agent_v2 failed: ${transition.error}`);
-    return 1;
-  }
-  if (!transition.changed) {
-    log.log(`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`);
-    return 0;
-  }
-
-  // Resync catalog so multi-agent surface metadata stays fresh in both the
-  // on-disk catalog and models_cache.json after the toggle flip.
-  try {
-    const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
-    await sync(findPort ? await findPort() : undefined);
-  } catch (err) {
-    log.error(`catalog resync failed (flag IS flipped): ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
-    return 1;
-  }
-  log.log(v2StatusLine(want));
-  log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version. Restart the Codex app (or wait out its picker cache) to see the ladder change.");
-  return 0;
 }

package/src/clients/config-export/dsh.ts

@@ -130,3 +130,24 @@ export function buildDshContribution(ctx: ExportContext): ManagedContribution {
   const doc = buildDshClientConfig(ctx);
   return singleFragment("dsh", ["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID], doc["llm-pi-ai"].providers[OPENCODE_PROVIDER_ID]);
 }
+
+/**
+ * Where DSH 0.1.7+ reads provider routes: the `llm-pi-ai` row of a profile
+ * patch, a top-level YAML list of loader rows. `$DSH_HOME/settings.yaml` is
+ * imported into the first profile that boots and renamed, so a write there
+ * reaches DSH once at most. The Desktop app runs the `desktop` profile and
+ * owns it alone, and DSH hot reloads that file when it changes.
+ */
+export const DSH_DESKTOP_PROFILE = "desktop";
+export const DSH_PROFILE_PROVIDER_PATH = ["[id=llm-pi-ai]", "config", "providers", OPENCODE_PROVIDER_ID] as const;
+
+/** A profile patch DSH itself would load: a list whose every row is a mapping. */
+export function dshProfilePatchEstablished(parsed: unknown): boolean {
+  return Array.isArray(parsed)
+    && parsed.every(row => typeof row === "object" && row !== null && !Array.isArray(row));
+}
+
+export function buildDshProfilePatchContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildDshClientConfig(ctx);
+  return singleFragment("dsh", DSH_PROFILE_PROVIDER_PATH, doc["llm-pi-ai"].providers[OPENCODE_PROVIDER_ID]);
+}

package/src/clients/config-export.ts

@@ -48,6 +48,7 @@ export {
   zcodeStoreSchemaEstablished,
 } from "./config-export/zcode-store";
 export type { DshReasoningEffort, DshWireReasoningEffort, DshModelEntry, DshProviderBlock, DshGeneratedConfig } from "./config-export/dsh";
+export { DSH_PROFILE_PROVIDER_PATH, dshProfilePatchEstablished, buildDshProfilePatchContribution } from "./config-export/dsh";
 export type { McodeProviderBlock, McodeModelEntry, McodeGeneratedConfig } from "./config-export/mcode";
 export type { RaycastAbility, RaycastAbilityName, RaycastModelEntry, RaycastProviderEntry, RaycastGeneratedConfig } from "./config-export/raycast";
 export { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
@@ -59,7 +60,7 @@ import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENC
 import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, inputBudgetFor, normalizeExportModels, inputModalitiesForClient, opencodeModelCapabilities, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
 import { exportReasoningEfforts, exportDefaultReasoningEffort, legacyReasoningMetadata, type LegacyEffortVariant } from "./config-export/reasoning-metadata";
 import { buildOmpClientConfig, summarizeOmp, buildOmpContribution } from "./config-export/omp";
-import { buildDshClientConfig, summarizeDsh, buildDshContribution } from "./config-export/dsh";
+import { buildDshClientConfig, summarizeDsh, buildDshContribution, DSH_DESKTOP_PROFILE } from "./config-export/dsh";
 import { buildMcodeClientConfig, summarizeMcode, buildMcodeContribution } from "./config-export/mcode";
 import { buildZcodeClientConfig, summarizeZcode, buildZcodeContribution } from "./config-export/zcode";
 import { buildClineClientConfig, summarizeCline, buildClineContribution } from "./config-export/cline";
@@ -435,6 +436,11 @@ export function dshConfigPath(env: OpencodeLaunchEnv = process.env, home: string
   return join(dshHomeDir(env, home), "settings.yaml");
 }
 
+/** The Desktop profile's patch, where DSH 0.1.7+ reads provider routes (see `DSH_PROFILE_PROVIDER_PATH`). */
+export function dshProfilePatchPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(dshHomeDir(env, home), "profiles", DSH_DESKTOP_PROFILE, "cordis.patch.yml");
+}
+
 /**
  * MiniMax Code stores runtime state under `MINIMAX_DATA_DIR`, then the legacy
  * `MAVIS_DATA_DIR`, and finally `~/.minimax`. Relative overrides are refused

package/src/codex/catalog/build-entries.ts

@@ -372,7 +372,7 @@ export function orderForModelPicker(
  * user tooling do not. `owned_by` describes upstream ownership, and `comp_hash`
  * describes history compatibility; neither is an authorship signal.
  */
-function isOcxAuthoredRoutedEntry(entry: RawEntry): boolean {
+export function isOcxAuthoredRoutedEntry(entry: RawEntry): boolean {
   if (isNativeAliasCatalogEntry(entry)) return true;
   const desc = typeof entry.description === "string" ? entry.description : "";
   const slug = typeof entry.slug === "string" ? entry.slug : "";

package/src/codex/catalog/bundled.ts

@@ -29,6 +29,7 @@ import type { NormalizedComboConfig } from "../../combos/types";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { redactSecretString } from "../../lib/redact";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
+import { decodeOverlayState } from "../shim-state-file";
 
 
 import { activeCodexModelsCachePath, catalogBackupPathFor, findNativeTemplate, findSupportedNativeTemplate, isDefaultCatalogPath, legacyCatalogBackupPath, parseCatalogJson, readCatalog, readCatalogBackup, readCodexCatalogPath } from "./parsing";
@@ -196,14 +197,20 @@ export function codexCommandCandidates(): string[] {
 
 export function codexShimCommandCandidates(): 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;
       wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>;
     };
+    const overlay = decodeOverlayState(state, configDir);
+    if ((state.schema !== undefined || state.mode !== undefined) && !overlay) return [];
     const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
-    const out: string[] = [];
+    const out: string[] = overlay && isSpawnableCodexCandidate(overlay.launcherPath)
+      ? [overlay.launcherPath] : [];
     for (const file of files) {
       for (const value of [file.backupPath, file.originalPath, file.wrapperPath]) {
         if (typeof value !== "string" || value.length === 0) continue;

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

@@ -0,0 +1,66 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, type Stats } from "node:fs";
+import { readCodexHomeJournal } from "../codex-home-owner";
+import { samePath, type RawCatalog } from "./parsing";
+
+export const CATALOG_HEAL_MAX_BYTES = 64 * 1024 * 1024;
+
+export interface CatalogObservation {
+  readonly signature: string;
+  readonly catalog: RawCatalog | null;
+}
+
+/** Canonical path equality when available; unavailable paths retain lexical equality. */
+export function sameCatalogHealPath(left: string, right: string): boolean {
+  try { return samePath(realpathSync.native(left), realpathSync.native(right)); }
+  catch { return samePath(left, right); }
+}
+
+/** Resolve authority without reading catalog bytes or cleaning journal evidence. */
+export function selectCatalogHealPath(
+  journalPath: string,
+  defaultPath: string,
+  resolvePath: (path: string) => string,
+): string | null {
+  const inspected = readCodexHomeJournal(journalPath);
+  if (inspected.kind === "unknown") return null;
+  if (inspected.kind === "missing") return defaultPath;
+  const selected = inspected.journal.injectedCatalogPath;
+  if (selected === undefined || selected === null) return defaultPath;
+  // A selected custom catalog remains selected even when missing or corrupt.
+  if (typeof selected !== "string" || !selected.trim() || selected.includes("\0")) return null;
+  try { return resolvePath(selected); }
+  catch { return null; }
+}
+
+function signature(stat: Stats): string {
+  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+}
+
+/** Bounded regular descriptor reads; never open a FIFO/device or follow a replaced symlink. */
+export function observeCatalogHealFile(path: string, readContent: boolean): CatalogObservation | null {
+  let fd: number | undefined;
+  try {
+    const before = lstatSync(path);
+    if (!before.isFile() || before.size > CATALOG_HEAL_MAX_BYTES) return null;
+    if (!readContent) return { signature: signature(before), catalog: null };
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.size > CATALOG_HEAL_MAX_BYTES || signature(before) !== signature(opened)) return null;
+    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 === 0) break;
+      length += count;
+    }
+    if (length !== opened.size || signature(fstatSync(fd)) !== signature(opened)
+      || signature(lstatSync(path)) !== signature(opened)) return null;
+    let catalog: RawCatalog | null = null;
+    try {
+      const value: unknown = JSON.parse(bytes.subarray(0, length).toString("utf8"));
+      if (value && typeof value === "object" && Array.isArray((value as RawCatalog).models)) catalog = value as RawCatalog;
+    } catch { /* Invalid catalog bytes remain unavailable until their stat changes. */ }
+    return { signature: signature(opened), catalog };
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}

package/src/codex/catalog/publication-observer.ts

@@ -0,0 +1,19 @@
+import type { CatalogWriteIntent } from "./write-audit-contract";
+
+export type CatalogPublicationEvent =
+  | { readonly kind: "published"; readonly path: string; readonly intent: CatalogWriteIntent }
+  | { readonly kind: "native-released"; readonly path: string | null };
+
+const listeners = new Set<(event: CatalogPublicationEvent) => void>();
+
+/** Process-local notifications; subscribers never own publication success. */
+export function subscribeCatalogPublication(listener: (event: CatalogPublicationEvent) => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export function notifyCatalogPublication(event: CatalogPublicationEvent): void {
+  for (const listener of [...listeners]) {
+    try { listener(event); } catch { /* A subscriber cannot fail or undo publication. */ }
+  }
+}

package/src/codex/catalog/remote.ts

@@ -7,7 +7,7 @@ import { replaceActiveCodexCatalog } from "../internal/catalog-writer";
 import { resetCodexAppServerCatalogStateCache } from "../app-server-processes";
 import { getCodexHome } from "../paths";
 import { readCodexCatalogPathForHome } from "./parsing";
-import { invalidateCodexModelsCacheWithPermit } from "./sync";
+import { invalidateCodexModelsCacheWithPermitOutcome } from "./sync";
 
 const DEFAULT_TIMEOUT_MS = 15_000;
 const MAX_MODELS = 2_000;
@@ -17,7 +17,7 @@ const ALLOWED_MODALITIES = new Set(["text", "image", "audio"]);
 export type RemoteCatalogFailureCode =
   | "url_invalid" | "insecure_http_refused" | "credential_invalid" | "request_failed"
   | "redirect_refused" | "http_error" | "body_too_large" | "body_invalid"
-  | "catalog_invalid" | "write_failed" | "lock_busy" | "lock_database" | "unsafe_path";
+  | "catalog_invalid" | "write_failed" | "lock_busy" | "lock_database" | "unsafe_path" | "foreign_owner" | "owner_unknown";
 
 export class RemoteCatalogError extends Error {
   constructor(readonly code: RemoteCatalogFailureCode, message: string, readonly status?: number) {
@@ -202,7 +202,10 @@ export async function fetchRemoteCatalog(
 
 function mapSerializationFailure<T>(outcome: CatalogSerializationOutcome<T>): never {
   if (outcome.kind === "completed") throw new RemoteCatalogError("write_failed", "Remote catalog installation failed");
-  const code = outcome.reason === "busy" ? "lock_busy" : outcome.reason === "database" ? "lock_database" : "unsafe_path";
+  const code = outcome.reason === "busy" ? "lock_busy"
+    : outcome.reason === "database" ? "lock_database"
+      : outcome.reason === "foreign-owner" ? "foreign_owner"
+        : outcome.reason === "owner-unknown" ? "owner_unknown" : "unsafe_path";
   throw new RemoteCatalogError(code, `Remote catalog installation unavailable (${outcome.reason})`);
 }
 
@@ -235,23 +238,18 @@ export async function pullRemoteCatalog(input: string, options: PullRemoteCatalo
   const fetched = await fetchRemoteCatalog(input, options);
   const codexHome = options.codexHome ?? getCodexHome();
   const catalogPath = readCodexCatalogPathForHome(codexHome);
-  const current = existsSync(catalogPath) ? readFileSync(catalogPath) : null;
-  const candidate = Buffer.from(fetched.content, "utf8");
-  if (current?.equals(candidate)) {
-    return { status: "unchanged", catalogWritten: false, cacheSynced: false, codexHome, catalogPath, modelCount: fetched.document.models.length };
-  }
   const outcome = withCatalogWriteSerialization(codexHome, permit => {
     // Re-check under K: another writer may have installed these bytes while the request was in flight.
     const lockedCurrent = existsSync(catalogPath) ? readFileSync(catalogPath) : null;
-    if (lockedCurrent?.equals(candidate)) return { catalogWritten: false, cacheSynced: false };
-    replaceActiveCodexCatalog(permit, codexHome, { path: catalogPath, content: fetched.content });
-    const cacheSynced = invalidateCodexModelsCacheWithPermit(permit, codexHome, { allowWhenDesiredDisabled: true });
-    if (!cacheSynced) {
-      restorePreviousCatalog(permit, codexHome, catalogPath, lockedCurrent);
+    const catalog = replaceActiveCodexCatalog(permit, codexHome, { path: catalogPath, content: fetched.content });
+    if (catalog.kind === "refused") throw new RemoteCatalogError("write_failed", "Remote catalog publication refused");
+    const cache = invalidateCodexModelsCacheWithPermitOutcome(permit, codexHome, { allowWhenDesiredDisabled: true });
+    if (cache !== "written" && cache !== "unchanged") {
+      if (catalog.kind === "written") restorePreviousCatalog(permit, codexHome, catalogPath, lockedCurrent);
       throw new RemoteCatalogError("write_failed", "Remote catalog cache synchronization failed");
     }
-    return { catalogWritten: true, cacheSynced: true };
-  });
+    return { catalogWritten: catalog.kind === "written", cacheSynced: cache === "written" };
+  }, { intent: "pull", writer: "catalog-pull" });
   if (outcome.kind !== "completed") return mapSerializationFailure(outcome);
   return {
     status: outcome.value.catalogWritten ? "updated" : "unchanged",

package/src/codex/catalog/restore.ts

@@ -6,9 +6,12 @@ import { RETIRED_NATIVE_OPENAI_MODELS, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./m
 import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
 import {
   withCatalogWriteSerialization,
+  CatalogWritePermitRefusal,
   type CatalogWritePermit,
 } from "../catalog-write-serialization";
 import { replaceActiveCodexCatalog } from "../internal/catalog-writer";
+import { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE } from "./routed-removal";
+import { notifyCatalogPublication } from "./publication-observer";
 
 function visibleAccountReplacementNatives(
   models: readonly RawEntry[],
@@ -72,7 +75,10 @@ export function restoreCodexCatalogWithPermit(
 ): { removed: number; kept: number; path: string } {
   const catalogPath = injectedCatalogPath ?? readCodexCatalogPath();
   const catalog = readCatalog(catalogPath);
-  if (!catalog || !Array.isArray(catalog.models)) return { removed: 0, kept: 0, path: catalogPath };
+  if (!catalog || !Array.isArray(catalog.models)) {
+    notifyCatalogPublication({ kind: "published", path: catalogPath, intent: "restore" });
+    return { removed: 0, kept: 0, path: catalogPath };
+  }
   const disabledModels = currentDisabledModelsForRestore();
   const replacementVisibility = visibleAccountReplacementNatives(catalog.models, disabledModels);
   const backup = readCatalogBackup(catalogPath);
@@ -94,10 +100,11 @@ export function restoreCodexCatalogWithPermit(
       models: [...backup.models.filter(m => typeof m.slug !== "string"
         || !RETIRED_NATIVE_OPENAI_MODELS.has(trustedAccountBoundNativeCatalogSlug(m) ?? m.slug)), ...userNativeAdditions],
     };
-    replaceActiveCodexCatalog(permit, owningCodexHome, {
+    const replacement = replaceActiveCodexCatalog(permit, owningCodexHome, {
       path: catalogPath,
       content: `${JSON.stringify(restored, null, 2)}\n`,
     });
+    if (replacement.kind === "refused") throw new CatalogWritePermitRefusal("Catalog restoration was refused.");
     return { removed, kept: restored.models.length, path: catalogPath };
   }
   const before = catalog.models.length;
@@ -110,11 +117,13 @@ export function restoreCodexCatalogWithPermit(
   const removed = before - native.length;
   if (removed > 0) {
     catalog.models = native;
-    replaceActiveCodexCatalog(permit, owningCodexHome, {
+    const replacement = replaceActiveCodexCatalog(permit, owningCodexHome, {
       path: catalogPath,
       content: `${JSON.stringify(catalog, null, 2)}\n`,
     });
+    if (replacement.kind === "refused") throw new CatalogWritePermitRefusal("Catalog restoration was refused.");
   }
+  if (removed === 0) notifyCatalogPublication({ kind: "published", path: catalogPath, intent: "restore" });
   return { removed, kept: native.length, path: catalogPath };
 }
 
@@ -123,10 +132,14 @@ export function restoreCodexCatalog(): { removed: number; kept: number; path: st
   const outcome = withCatalogWriteSerialization(
     owningCodexHome,
     permit => restoreCodexCatalogWithPermit(permit, owningCodexHome),
+    { intent: "restore", writer: "catalog-restore" },
   );
-  return outcome.kind === "completed"
-    ? outcome.value
-    : { removed: 0, kept: 0, path: readCodexCatalogPath() };
+  if (outcome.kind === "unavailable") {
+    throw new CatalogWritePermitRefusal(outcome.reason === "foreign-owner"
+      ? FOREIGN_CODEX_HOME_OWNER_MESSAGE : outcome.reason === "owner-unknown"
+        ? UNKNOWN_CODEX_HOME_OWNER_MESSAGE : `Catalog restoration unavailable (${outcome.reason}).`);
+  }
+  return outcome.value;
 }
 
 /** Force Codex's models_cache stale from the on-disk catalog. Returns whether a cache write occurred. */