@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/codex/journal.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
+import { assertCodexHomeOwner, CODEX_HOME_JOURNAL_FILE, CodexHomeOwnerRefusal, opencodexHomeForInjection, readCodexHomeJournal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
 import { hasInjectedCodexRouting } from "./injected-marker";
 import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
 
@@ -14,7 +15,7 @@ import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
  * agreed with the producer, and the pair stayed green. One exported constant
  * removes the opportunity.
  */
-export const JOURNAL_PATH = join(CODEX_HOME, "opencodex-journal.json");
+export const JOURNAL_PATH = join(CODEX_HOME, CODEX_HOME_JOURNAL_FILE);
 
 export type JournalOwner =
   | { kind: "process"; pid: number }
@@ -71,12 +72,17 @@ interface Journal {
    * file we actually touched.
    */
   injectedCatalogPath?: string | null;
+  /** Injection binding survives native snapshot replacement and is released by native restore. */
+  opencodexHome?: string;
   pid: number;
   owner?: JournalOwner;
   timestamp: string;
 }
 
 export interface RestoreJournalResult {
+  /** An unchanged generated profile could not be restored; distinct from a preserved user edit. */
+  profileRestoreFailed?: true;
+  ownershipRefusal?: CodexHomeOwnerRefusalReason;
   configRestored: boolean;
   profileRestored: boolean;
   configChanged: boolean;
@@ -146,6 +152,7 @@ export interface WriteJournalOptions {
  * plugins, model choice, and trusted projects.
  */
 export function writeJournal(options: WriteJournalOptions = {}): void {
+  assertCodexHomeOwner(CODEX_HOME);
   if (!existsSync(CODEX_CONFIG_PATH)) return;
   const config = options.configContent ?? readFileSync(CODEX_CONFIG_PATH, "utf-8");
   // Ownership is decided HERE, from the bytes about to be journaled — never taken
@@ -155,7 +162,12 @@ export function writeJournal(options: WriteJournalOptions = {}): void {
   // The caller's verdict only authorizes REPLACEMENT. It is weaker evidence than
   // the check above (it may describe bytes read a moment earlier), so an
   // unclassified call creates a first snapshot but never overwrites one.
-  if (existsSync(JOURNAL_PATH) && readJournal() && options.currentStateIsNative !== true) return;
+  const inspection = readCodexHomeJournal(JOURNAL_PATH);
+  if (inspection.kind === "unknown") {
+    throw new CodexHomeOwnerRefusal("owner-unknown");
+  }
+  const previous = inspection.kind === "read" ? inspection.journal as unknown as Journal : null;
+  if (previous && options.currentStateIsNative !== true) return;
   const profile = existsSync(CODEX_PROFILE_PATH)
     ? readFileSync(CODEX_PROFILE_PATH, "utf-8")
     : null;
@@ -163,6 +175,7 @@ export function writeJournal(options: WriteJournalOptions = {}): void {
     version: 1,
     originalConfig: Buffer.from(config).toString("base64"),
     originalProfile: profile !== null ? Buffer.from(profile).toString("base64") : null,
+    opencodexHome: opencodexHomeForInjection(previous?.opencodexHome),
     pid: process.pid,
     owner: options.owner?.kind === "client"
       ? { kind: "client", apiKeyId: options.owner.apiKeyId }
@@ -187,7 +200,10 @@ export function markJournalInjectedState(
   profile: string | null,
   ownership: InjectedJournalOwnership,
 ): void {
-  const journal = readJournal();
+  assertCodexHomeOwner(CODEX_HOME);
+  const inspection = readCodexHomeJournal(JOURNAL_PATH);
+  if (inspection.kind === "unknown") throw new CodexHomeOwnerRefusal("owner-unknown");
+  const journal = inspection.kind === "read" ? inspection.journal as unknown as Journal : null;
   if (!journal) return;
   // The first exact injected config is the only safe whole-snapshot restore boundary for
   // the first native snapshot. A later reinjection may preserve user edits made while routed;
@@ -204,6 +220,7 @@ export function markJournalInjectedState(
   journal.injectedRootWebSearch = ownership.injectedRootWebSearch ?? null;
   journal.replacedRootWebSearch = ownership.replacedRootWebSearch ?? null;
   journal.injectedCatalogPath = ownership.injectedCatalogPath;
+  journal.opencodexHome = opencodexHomeForInjection(journal.opencodexHome);
   atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
 }
 
@@ -240,19 +257,24 @@ export function journaledInjectedCatalogPath(): string | null {
 }
 
 export function removeJournal(): void {
+  assertCodexHomeOwner(CODEX_HOME);
   try { unlinkSync(JOURNAL_PATH); } catch { /* ignore */ }
 }
 
-function readJournal(cleanInvalid = true): Journal | null {
-  if (!existsSync(JOURNAL_PATH)) return null;
-  try {
-    const journal = JSON.parse(readFileSync(JOURNAL_PATH, "utf-8")) as Journal;
-    if (journal.version !== 1) throw new Error("unknown version");
-    return journal;
-  } catch {
-    if (cleanInvalid) removeJournal();
-    return null;
-  }
+/** Successful field-level native restore releases ownership while retaining recovery evidence. */
+export function releaseJournalHomeBinding(): void {
+  assertCodexHomeOwner(CODEX_HOME);
+  const inspection = readCodexHomeJournal(JOURNAL_PATH);
+  if (inspection.kind === "unknown") throw new CodexHomeOwnerRefusal("owner-unknown");
+  if (inspection.kind === "missing" || inspection.journal.opencodexHome === undefined) return;
+  delete inspection.journal.opencodexHome;
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(inspection.journal));
+}
+
+// Kept compatible with existing read-only callers; invalid evidence is never cleanup authority.
+function readJournal(_cleanInvalid = true): Journal | null {
+  const inspected = readCodexHomeJournal(JOURNAL_PATH);
+  return inspected.kind === "read" ? inspected.journal as unknown as Journal : null;
 }
 
 /**
@@ -274,6 +296,12 @@ export function journalOwner(options: { readOnly?: boolean } = {}): JournalOwner
 }
 
 export function restoreJournalState(): RestoreJournalResult {
+  try { assertCodexHomeOwner(CODEX_HOME); }
+  catch (error) {
+    if (!(error instanceof CodexHomeOwnerRefusal)) throw error;
+    return { configRestored: false, profileRestored: false, configChanged: false, profileChanged: false,
+      complete: false, unverified: true, ownershipRefusal: error.reason };
+  }
   const journal = readJournal();
   if (!journal) {
     return { configRestored: false, profileRestored: false, configChanged: false, profileChanged: false, complete: false, unverified: false };
@@ -295,6 +323,7 @@ export function restoreJournalState(): RestoreJournalResult {
     };
   }
 
+  assertCodexHomeOwner(CODEX_HOME);
   let configRestored = comparison.configAlreadyOriginal;
   let profileRestored = comparison.profileAlreadyOriginal;
   if (configUnchanged && !configRestored) {
@@ -330,6 +359,7 @@ export function restoreJournalState(): RestoreJournalResult {
     profileChanged: !profileUnchanged,
     complete,
     unverified: false,
+    ...(profileUnchanged && !profileRestored ? { profileRestoreFailed: true as const } : {}),
   };
 }
 
@@ -342,6 +372,12 @@ export interface ReconcileJournalOptions {
 }
 
 export function reconcileJournal(options: ReconcileJournalOptions = {}): boolean {
+  try { assertCodexHomeOwner(CODEX_HOME); }
+  catch (error) {
+    if (!(error instanceof CodexHomeOwnerRefusal)) throw error;
+    console.error(error.message);
+    return false;
+  }
   const journal = readJournal();
   if (!journal) return false;
   const owner = journalOwner();

package/src/codex/management-convergence.ts

@@ -143,6 +143,7 @@ export function projectCatalogOnlyOutcome({
  */
 export function createManagementConvergeCodex(
   config: Readonly<OcxConfig>,
+  options: Readonly<{ beforeCommit?: () => boolean; expectedCatalogPath?: string }> = {},
 ): ConvergeCodex {
   const retainedConfig = config;
   return async request => {
@@ -167,6 +168,8 @@ export function createManagementConvergeCodex(
       const snapshot = captureCatalogAdmissionSnapshot(retainedConfig);
       const result = await convergeCodexCatalog(snapshot, request, {
         onCommitBegin: () => { commitBegan = true; },
+        beforeCommit: options.beforeCommit,
+        expectedCatalogPath: options.expectedCatalogPath,
       });
       return projectCatalogOnlyOutcome(result);
     } catch (error) {

package/src/codex/quota-types.ts

@@ -30,6 +30,7 @@ export interface CodexSpendableCredits {
   unlimited?: boolean;
   balance?: number;
   overageLimitReached?: boolean;
+  /** Credit spending control, never the included-plan rate_limit.allowed verdict. */
   allowed?: boolean;
   observedAt: number;
 }
@@ -147,6 +148,8 @@ export type WhamUsageResponse = {
     balance?: unknown;
     overage_limit_reached?: unknown;
   } | null;
+  /** Absent/null imposes no veto; present raw controls require an object with reached:false. */
+  spend_control?: unknown;
   rate_limit_reset_credits?: { available_count: number } | null;
   additional_rate_limits?: WhamAdditionalRateLimit[] | null;
 };

package/src/codex/quota.ts

@@ -904,10 +904,17 @@ function isMeasuredLongWindow(window: WhamUsageWindow | null | undefined): boole
   return isExplicitLongWindow(window) && normalizeUsagePercent(window?.used_percent) !== undefined;
 }
 
+/** Absent/null controls impose no veto; a present control requires reached:false. */
+function spendControlAllowsCredits(control: unknown): boolean | undefined {
+  if (control === undefined || control === null) return undefined;
+  return typeof control === "object" && !Array.isArray(control)
+    && "reached" in control && control.reached === false;
+}
+
 /**
  * Normalize WHAM windows into the display snapshot, preserving declared short-window shape.
  * Finite percentages are clamped for compatibility; policy callers must validate raw readings
- * separately. Return null when neither a quota value/window nor reset credits are available.
+ * separately. Return null when no usage window or credit observation/retraction is available.
  */
 export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuota, "updatedAt"> | null {
   const resetCredits = typeof data.rate_limit_reset_credits?.available_count === "number"
@@ -915,6 +922,7 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
     : undefined;
 
   const quota: Omit<StoredAccountQuota, "updatedAt"> = {};
+  const creditsAllowed = spendControlAllowsCredits(data.spend_control);
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
   if (data.credits !== undefined) {
     quota.credits = null;
@@ -926,11 +934,13 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
         ...(parsed.hasCredits !== undefined ? { hasCredits: parsed.hasCredits } : {}),
         ...(parsed.unlimited !== undefined ? { unlimited: parsed.unlimited } : {}),
         ...(parsed.overageLimitReached !== undefined ? { overageLimitReached: parsed.overageLimitReached } : {}),
-        ...(typeof data.rate_limit?.allowed === "boolean" ? { allowed: data.rate_limit.allowed } : {}),
+        // Included-plan refusal is precisely when opted-in credits take over, not a credit veto.
+        // A declared spending control permits credits only with an explicit unreached verdict.
+        ...(creditsAllowed !== undefined ? { allowed: creditsAllowed } : {}),
         ...(balance !== undefined && Number.isFinite(balance) ? { balance } : {}),
       };
     }
-  } else if (data.rate_limit?.allowed === false) quota.credits = null;
+  } else if (data.rate_limit?.allowed === false || creditsAllowed === false) quota.credits = null;
   if (!data.rate_limit) return snapshotHasCredits(quota) ? quota : null;
   const thirtyDayOnly = codexQuotaWindowForPlan(data.plan_type) === "monthly";
   const primaryWindow = data.rate_limit.primary_window;

package/src/codex/refresh.ts

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { invalidateCodexModelsCache, syncCatalogModels } from "./catalog";
 import type { ComboCatalogOmission } from "./catalog/aggregation";
-import { CODEX_MODELS_CACHE_PATH } from "./paths";
-import { atomicWriteFile } from "../config";
+import { getCodexHome } from "./paths";
+import { withCatalogWriteSerialization, CatalogWritePermitRefusal } from "./catalog-write-serialization";
+import { replaceCodexModelsCache } from "./internal/catalog-writer";
 import type { OcxConfig } from "../types";
 import type { CodexCatalogSyncOptions } from "./catalog/sync";
 
@@ -14,8 +16,12 @@ export interface CodexCatalogRefreshResult {
   cacheSynced: boolean;
   comboOmissions: ComboCatalogOmission[];
   refreshOutcome?: "committed" | "refused";
-  /** Desired OFF observed under K during the catalog commit; no cache write either. */
-  skippedReason?: "desired_disabled";
+  /**
+   * Desired OFF observed under K during the catalog commit, or a write refused because it would
+   * empty routed namespaces config.json does not back (#6529); no cache write either way.
+   */
+  skippedReason?: "desired_disabled" | "unbacked_routed_removal" | "foreign_owner" | "owner_unknown";
+  protectedRoutedNamespaces?: number;
 }
 
 interface RefreshDeps {
@@ -31,8 +37,13 @@ const defaultDeps: RefreshDeps = {
 };
 
 export function syncCodexModelsCacheFromCatalog(catalogPath: string): void {
-  const content = readFileSync(catalogPath, "utf8");
-  atomicWriteFile(CODEX_MODELS_CACHE_PATH, content);
+  const owningCodexHome = getCodexHome();
+  const outcome = withCatalogWriteSerialization(owningCodexHome, permit =>
+    replaceCodexModelsCache(permit, owningCodexHome, {
+      path: join(owningCodexHome, "models_cache.json"),
+      content: readFileSync(catalogPath, "utf8"),
+    }), { intent: "cache", writer: "cache-from-catalog" });
+  if (outcome.kind === "unavailable") throw new CatalogWritePermitRefusal(`Catalog cache synchronization unavailable (${outcome.reason}).`);
 }
 
 /**
@@ -50,9 +61,9 @@ export async function refreshCodexModelCatalog(
   const catalogExists = deps.existsSync(result.path);
   const catalogWritten = result.catalogWritten === true;
   const comboOmissions = result.comboOmissions ?? [];
-  if (result.skippedReason === "desired_disabled" || result.refreshOutcome === "refused") {
-    // The commit path observed OFF under K. Invalidate nothing: rewriting the
-    // models cache here would be exactly the routed-cache write the skip refused.
+  if (result.skippedReason !== undefined || result.refreshOutcome === "refused") {
+    // The commit path observed OFF, or an unbacked routed removal, under K. Invalidate
+    // nothing: rewriting the models cache here would be exactly the write the skip refused.
     return { ...result, catalogExists, catalogWritten: false, cacheSynced: false, comboOmissions };
   }
   if (!catalogExists) {

package/src/codex/runtime.ts

@@ -5,6 +5,7 @@ import { delimiter, join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { codexExecInvocation, isSpawnableCodexCandidate } from "./exec-invocation";
 import { resolveCodexHomeDir } from "./home";
+import { decodeOverlayState } from "./shim-state-file";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 
 export type CodexRuntimeSource =
@@ -516,13 +517,18 @@ function shimCandidates(deps: ResolveCodexRuntimeDeps): string[] {
   const platform = deps.platform ?? process.platform;
   try {
     const state = JSON.parse(read(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, platform)
+      ? [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/shim-diagnostics.ts

@@ -0,0 +1,80 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { SHIM_MARKER, UNIX_SHIM_REVISION_MARKER } from "./shim-templates";
+import { readStateResult, stateFiles, statePath } from "./shim-state-file";
+import { overlayDiagnostic } from "./shim-overlay";
+
+export function isShim(path: string): boolean {
+  try {
+    return readFileSync(path, "utf8").includes(SHIM_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function isHealthyShim(path: string, platform: NodeJS.Platform): boolean {
+  try {
+    const content = readFileSync(path, "utf8");
+    if (content.length < 180 || !content.includes(SHIM_MARKER) || !content.includes("ensure")) return false;
+    if (platform !== "win32" && !content.includes(UNIX_SHIM_REVISION_MARKER)) return false;
+    if (platform !== "win32" && (lstatSync(path).mode & 0o111) === 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface CodexShimDiagnostic {
+  installed: boolean;
+  healthy: boolean;
+  summary: string;
+  runnable?: boolean;
+  active?: boolean | null;
+}
+
+/** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */
+export function diagnoseCodexShim(): CodexShimDiagnostic {
+  const result = readStateResult();
+  const state = result.state;
+  if (!state) {
+    if (result.present) {
+      return {
+        installed: true,
+        healthy: false,
+        runnable: false,
+        active: null,
+        summary: result.warning ?? `Codex autostart shim state is invalid or corrupt at ${statePath()}. Reinstall or remove the shim.`,
+      };
+    }
+    return {
+      installed: false,
+      healthy: false,
+      summary: "Codex autostart shim is not installed.",
+    };
+  }
+  if (state.mode === "path-overlay") return overlayDiagnostic(state);
+  const files = stateFiles(state);
+  const healthy = files.length > 0 && files.every(file => file.preserveOnly
+    ? existsSync(file.backupPath) && !existsSync(file.originalPath)
+    : existsSync(file.wrapperPath)
+      && (existsSync(file.backupPath) || (file.realPath ? existsSync(file.realPath) : false))
+      && isHealthyShim(file.wrapperPath, state.platform));
+  const summary = files.map(file => {
+    const wrapper = existsSync(file.wrapperPath)
+      ? isShim(file.wrapperPath)
+        ? "shim present"
+        : "present but not an opencodex shim"
+      : "missing";
+    const backup = existsSync(file.backupPath) ? "present" : "missing";
+    return `Codex autostart shim: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
+  }).join("\n");
+  // Presence alone is not health: a damaged wrapper still reads "shim present", so state the verdict.
+  const migration = healthy && state.platform !== "win32"
+    ? " Legacy Unix shim installed in place; automatic repair does not migrate it. Run ocx codex-shim install, then source the printed codex-shell-env.sh path and add that line after PATH setup in your shell startup file."
+    : "";
+  return { installed: true, healthy, summary: healthy ? `${summary}${migration}`
+    : `${summary}\nCodex autostart shim is unhealthy. Run ocx codex-shim install to repair it.` };
+}
+
+export function codexShimStatus(): string {
+  return diagnoseCodexShim().summary;
+}

package/src/codex/shim-fingerprint.ts

@@ -1,5 +1,7 @@
 import {
   closeSync,
+  constants,
+  fstatSync,
   existsSync,
   lstatSync,
   linkSync,
@@ -33,8 +35,9 @@ interface StableShimPathProbe {
 }
 
 function readShimProbePrefix(path: string): string {
-  const fd = openSync(path, "r");
+  const fd = openSync(path, process.platform === "win32" ? "r" : constants.O_RDONLY | constants.O_NONBLOCK);
   try {
+    if (process.platform !== "win32" && !fstatSync(fd).isFile()) throw new Error("Shim probe entry is not a regular file");
     const buffer = Buffer.allocUnsafe(CODEX_SHIM_PROBE_BYTES);
     const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
     return buffer.toString("utf8", 0, bytesRead);
@@ -162,14 +165,16 @@ function shimPathFingerprint(path: string): ShimPathFingerprint | null {
  * fails EEXIST on an occupied destination. Checking existence and then renaming
  * would reintroduce exactly the race this function exists to close.
  */
-function restoreWithoutReplacing(from: string, to: string): void {
+function restoreWithoutReplacing(from: string, to: string, guard?: () => void): void {
   const source = lstatSync(from);
   if (source.isSymbolicLink()) {
     symlinkSync(readlinkSync(from), to);
+    guard?.();
     unlinkSync(from);
     return;
   }
   linkSync(from, to);
+  guard?.();
   unlinkSync(from);
 }
 

package/src/codex/shim-migration.ts

@@ -0,0 +1,153 @@
+import { closeSync, fstatSync, linkSync, lstatSync, openSync, readlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { getConfigDir } from "../config";
+import { restoreWithoutReplacing, stableShimPathProbe } from "./shim-fingerprint";
+import { isExecutableCodexCandidate } from "./shim-path-resolution";
+import { readBoundedRegularFile, stateFiles, type ShimState } from "./shim-state-file";
+import { SHIM_MARKER, shQuote } from "./shim-templates";
+
+export type UnixShimMigrationResult =
+  | { status: "native-restored"; launcherPath: string }
+  | { status: "native-repair-required"; message: string }
+  | { status: "refused"; message: string };
+
+type Identity = { dev: number; ino: number; mode: number; size: number; mtimeMs: number; link?: string };
+type MigrationRecord = { original: string; backup: string; wrapper: Identity; saved: Identity };
+
+function identity(path: string): Identity | null {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() && !stat.isSymbolicLink()) throw new Error("Unsupported migration entry");
+    return { dev: stat.dev, ino: stat.ino, mode: stat.mode, size: stat.size, mtimeMs: stat.mtimeMs,
+      ...(stat.isSymbolicLink() ? { link: readlinkSync(path) } : {}) };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+function same(left: Identity | null, right: Identity | null): boolean {
+  return !!left && !!right && JSON.stringify(left) === JSON.stringify(right);
+}
+/** Drop a journal this run created before any migration step, never a replacement at that path. */
+function discardCreatedJournal(journal: string, created: { dev: number; ino: number }): void {
+  try {
+    const now = lstatSync(journal);
+    if (now.isFile() && now.dev === created.dev && now.ino === created.ino) unlinkSync(journal);
+  } catch {
+    // An unreadable or vanished path is left for the next run's ownership checks.
+  }
+}
+function binding(path: string, backup: string): boolean {
+  const probe = stableShimPathProbe(path);
+  return !!probe && probe.fingerprint.kind === "file" && probe.prefix.includes(SHIM_MARKER)
+    && probe.prefix.includes(`exec ${shQuote(backup)} "$@"`);
+}
+
+/** Caller holds the shared lock; legacy state remains intact until overlay commit. */
+export function migrateLegacyUnixShim(state: ShimState): UnixShimMigrationResult {
+  const refused = (message: string): UnixShimMigrationResult => ({ status: "refused", message });
+  const repair = (): UnixShimMigrationResult => ({ status: "native-repair-required", message:
+    "Native Codex entry is missing or unusable. Repair Codex with its package manager, then rerun ocx codex-shim install; the recovery state was retained." });
+  const files = stateFiles(state);
+  if (state.platform !== process.platform || state.platform === "win32" || state.mode || files.length !== 1) {
+    return refused("Legacy Unix shim has ambiguous targets or platform; preserving all files.");
+  }
+  const file = files[0]!;
+  if (file.preserveOnly || file.realPath || file.wrapperPath !== file.originalPath
+    || !isAbsolute(file.originalPath) || /[\x00-\x1f\x7f]/.test(file.originalPath)
+    || file.backupPath !== `${file.originalPath}.opencodex-real`) {
+    return refused("Legacy Unix shim ownership is ambiguous; manual recovery is required.");
+  }
+  const original = file.originalPath;
+  const backup = file.backupPath;
+  const quarantine = `${original}.opencodex-migrating`;
+  const journal = join(getConfigDir(), "codex-shim.migration.json");
+  let journalIdentity: Identity | null = null;
+  try {
+    let record: MigrationRecord | null = null;
+    const journalBefore = identity(journal);
+    if (journalBefore) {
+      const entry = lstatSync(journal);
+      if (!entry.isFile() || entry.uid !== process.getuid?.() || (entry.mode & 0o022)) return refused("Migration journal is not privately owned.");
+    }
+    const stored = readBoundedRegularFile(journal, 16 * 1024);
+    const journalAfter = identity(journal);
+    if (journalBefore || journalAfter) {
+      if (!same(journalBefore, journalAfter)) return refused("Migration journal changed during inspection.");
+    }
+    if (stored) {
+      if ("warning" in stored) return refused("Migration recovery record is unreadable; preserving all artifacts.");
+      record = JSON.parse(stored.content) as MigrationRecord;
+      if (!record || record.original !== original || record.backup !== backup || !record.wrapper || !record.saved) {
+        return refused("Migration recovery record does not match the legacy state.");
+      }
+      journalIdentity = journalBefore;
+    }
+    let current = identity(original);
+    const saved = identity(backup);
+    const evacuated = identity(quarantine);
+    const probe = current && isExecutableCodexCandidate(original) ? stableShimPathProbe(original) : null;
+    if (current && (binding(original, backup) || probe?.prefix.includes(SHIM_MARKER))) {
+      if (!binding(original, backup)) return refused("Legacy wrapper binding changed; preserving it.");
+      if (!saved) return repair();
+      if (!record) {
+        if (evacuated) return refused("Unrecorded migration quarantine requires manual inspection.");
+        record = { original, backup, wrapper: current, saved };
+        const fd = openSync(journal, "wx", 0o600);
+        const created = fstatSync(fd);
+        try {
+          writeFileSync(fd, JSON.stringify(record) + "\n");
+          const written = fstatSync(fd);
+          journalIdentity = identity(journal);
+          if (journalIdentity?.ino !== created.ino || journalIdentity.dev !== created.dev
+            || journalIdentity.size !== written.size || journalIdentity.mtimeMs !== written.mtimeMs) throw new Error("Journal replaced");
+        } catch (error) {
+          // Nothing has moved yet, so a partial journal of ours would only block every retry.
+          discardCreatedJournal(journal, created);
+          journalIdentity = null;
+          throw error;
+        } finally { closeSync(fd); }
+      }
+      if (!same(current, record.wrapper) || !same(saved, record.saved)) return refused("Migration inputs changed; preserving all generations.");
+      if (evacuated) {
+        if (!same(evacuated, record.wrapper)) return refused("Migration quarantine changed; preserving it.");
+      } else {
+        // A hard link is exclusive publication: unlike rename it never overwrites quarantine.
+        linkSync(original, quarantine);
+      }
+      if (!same(identity(original), record.wrapper) || !same(identity(quarantine), record.wrapper)
+        || !same(identity(backup), record.saved)) return refused("Migration inputs changed before evacuation.");
+      unlinkSync(original);
+      current = null;
+    } else if (evacuated && (!record || !same(evacuated, record.wrapper) || !binding(quarantine, backup))) {
+      return refused("Migration quarantine ownership is uncertain; preserving the recovery record.");
+    }
+    if (!current) {
+      if (!saved) return repair();
+      if (!same(identity(backup), record?.saved ?? saved)) return refused("Legacy backup changed; retry after the package manager finishes.");
+      try {
+        restoreWithoutReplacing(backup, original, () => {
+          if (!same(identity(backup), record?.saved ?? saved)) throw new Error("Legacy backup replaced during publication");
+          const restored = identity(original);
+          if (saved.link !== undefined ? restored?.link !== saved.link : !same(restored, saved)) {
+            throw new Error("Native entry changed during restoration");
+          }
+        });
+      }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        // A concurrent package-manager publication wins over the saved generation.
+      }
+    }
+    const native = isExecutableCodexCandidate(original) ? stableShimPathProbe(original) : null;
+    if (!native || native.prefix.includes(SHIM_MARKER)) return repair();
+    if (record && identity(quarantine)) {
+      if (!same(identity(quarantine), record.wrapper) || !binding(quarantine, backup)) return refused("Migration quarantine changed during restoration.");
+      unlinkSync(quarantine);
+    }
+    if (journalIdentity && same(identity(journal), journalIdentity)) unlinkSync(journal);
+    return { status: "native-restored", launcherPath: original };
+  } catch {
+    return refused("Legacy migration could not complete safely; native and recovery artifacts were preserved. Retry after the package manager finishes.");
+  }
+}