@iislee/opencodex 2.31.0 → 2.35.0

package/src/codex/prompt-text-probe.ts

@@ -0,0 +1,238 @@
+/**
+ * Reading the prompt text Codex actually assembles.
+ *
+ * The read-only dialog used to say Codex "does not expose" a layer's text. That
+ * was wrong: Codex is open source and ships `codex debug prompt-input`, which
+ * renders the model-visible input list as JSON. Reading it is the difference
+ * between describing a layer and showing it.
+ *
+ * What this does NOT cover, stated rather than implied:
+ *
+ * - `base-instructions` is absent. `prompt_debug.rs` returns `prompt.input` and
+ *   discards `base_instructions`, so the base prompt never appears here.
+ * - World-state sections are DIFF-rendered (`add_section` registers state, it does
+ *   not emit text). A section that renders nothing on a first turn is missing
+ *   from this output even though its layer exists.
+ * - The output reflects the invoking directory and the current config, not a
+ *   universal prompt.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveCodexHomeDir } from "./home";
+
+/**
+ * Layer id -> the tag Codex actually renders it under.
+ *
+ * Every entry here was read off live `codex debug prompt-input` output across the
+ * feature flags that enable each section. None is inferred from the Rust section
+ * `ID` constants: those are identifiers for diffing, not wrapper tags, and an
+ * earlier guess from them mapped `permissions` to the wrong name while the real
+ * tag - `permissions instructions`, with a space - went unmatched.
+ *
+ * A layer absent from this map is reported as unsupported, never as silent.
+ */
+const LAYER_SECTION_TAGS: Record<string, string> = {
+  skills: "skills_instructions",
+  apps: "apps_instructions",
+  plugins: "plugins_instructions",
+  environment: "environment_context",
+  permissions: "permissions instructions",
+  // Synthetic: the project doc carries no tag of its own (see extractSections).
+  "agents-md": "__agents_md",
+};
+
+/**
+ * Inventory ids with no confirmed tag in the rendered output. They are listed
+ * explicitly rather than left missing: an absent entry made the dialog report a
+ * successful probe as unavailable.
+ */
+const UNMAPPED_LAYER_IDS = [
+  "model-switch",
+  "context-window-guidance",
+  "environments-instructions",
+  "tools",
+  "multi-agent-mode",
+  // Confirmed absent from live output under their own feature flags, so the
+  // previous `personality` / `realtime` guesses reported these as silent when the
+  // truth is that this extractor has no verified tag for them.
+  "personality",
+  "realtime",
+  "collaboration",
+  // The Rust source names a <git_attribution> marker pair, but a world-state section is
+  // DIFF-rendered: it emits nothing on a turn where its state has not changed. Live
+  // `codex debug prompt-input` (codex-cli 0.145.0, 32978 bytes) showed no such block and
+  // no attribution text. Listing the id here reports "not exposed" honestly instead of
+  // claiming a tag this extractor has never actually matched - the same mistake the
+  // header above records for permissions.
+  "git-attribution",
+] as const;
+
+export interface LayerText {
+  /** Rendered text, when this layer produced a section on the probed turn. */
+  text: string | null;
+  /** Why the text is absent, when it is. */
+  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unavailable";
+  bytes: number;
+  /** For `empty-source`: the file that exists but has nothing in it. */
+  sourcePath?: string;
+}
+
+export interface PromptTextProbe {
+  ok: boolean;
+  /** The Codex home the probe reported on. */
+  codexHome: string;
+  layers: Record<string, LayerText>;
+  detail?: string;
+}
+
+function resolveCodexBinary(): string | null {
+  const candidates = [
+    join(homedir(), ".codex/packages/standalone/current/bin/codex"),
+    join(homedir(), ".local/bin/codex"),
+    "/usr/local/bin/codex",
+    "/opt/homebrew/bin/codex",
+  ];
+  return candidates.find(path => existsSync(path)) ?? null;
+}
+
+/** 8 MiB is far above any real prompt and far below anything that hurts the server. */
+const MAX_PROBE_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+function runProbe(binary: string, cwd: string, timeoutMs: number): Promise<string | null> {
+  return new Promise(resolve => {
+    // A probe must never hang OR balloon the management API: it is bounded in
+    // time AND in bytes, and every failure degrades to "unavailable" rather than
+    // an error page.
+    const child = spawn(binary, ["debug", "prompt-input"], {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let settled = false;
+    // One settlement path: a timeout that resolved before `close` used to leave
+    // the child streaming into a buffer nobody would ever read.
+    const settle = (value: string | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout?.destroy();
+      if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+      resolve(value);
+    };
+    const timer = setTimeout(() => settle(null), timeoutMs);
+    child.stdout?.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_PROBE_OUTPUT_BYTES) { settle(null); return; }
+      chunks.push(chunk);
+    });
+    child.on("error", () => settle(null));
+    child.on("close", code => {
+      // Decode once, at the end: `String(chunk)` per chunk corrupts any UTF-8
+      // character that straddles a chunk boundary.
+      settle(code === 0 ? Buffer.concat(chunks).toString("utf8") : null);
+    });
+  });
+}
+
+/** Pull every `<tag>...</tag>` section out of the rendered developer messages. */
+function extractSections(raw: string): Map<string, string> {
+  const sections = new Map<string, string>();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return sections;
+  }
+  if (!Array.isArray(parsed)) return sections;
+  for (const item of parsed) {
+    const content = (item as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    const text = content.map(part => String((part as { text?: unknown }).text ?? "")).join("");
+    // Tag names are NOT all snake_case: Codex renders `<permissions instructions>`
+    // with a space. A `[a-z_]+` pattern silently skipped it, and the layer was
+    // reported as "sent nothing" while its text sat right there.
+    for (const match of text.matchAll(/<([a-zA-Z_][a-zA-Z0-9_ -]*)>([\s\S]*?)<\/\1>/g)) {
+      sections.set(match[1]!, match[2]!.trim());
+    }
+    // AGENTS.md is NOT tagged: it arrives as a plain `# AGENTS.md instructions
+    // for <path>` block among the tagged sections. Matching only on tags would
+    // report the layer as unrendered while its text sits in the same message.
+    //
+    // Bounded at both ends. Capturing to end-of-message swept up any unrelated
+    // untagged prose that happened to follow, and stripping tag-shaped blocks
+    // first also deleted XML-like text the user had written INSIDE their own
+    // AGENTS.md. Codex wraps the body in <INSTRUCTIONS>, so that is the boundary.
+    // No line anchor: the block is concatenated directly onto the previous
+    // section's closing tag, so requiring a newline before it never matched.
+    const projectDoc = /# AGENTS\.md instructions for [^\n]*\n+<INSTRUCTIONS>\n?([\s\S]*?)\n?<\/INSTRUCTIONS>/.exec(text);
+    if (projectDoc) sections.set("__agents_md", projectDoc[1]!.trim());
+  }
+  return sections;
+}
+
+/** Test seam: the extraction is the part worth pinning, not the spawn. */
+export const extractSectionsForTests = extractSections;
+
+/**
+ * Probe once and map every known layer to its rendered text.
+ *
+ * `cwd` matters: AGENTS.md and environment context are directory-dependent, so a
+ * probe from the wrong place would describe a prompt the user never sees.
+ */
+export async function probePromptText(timeoutMs = 15_000): Promise<PromptTextProbe> {
+  // The probe runs in CODEX_HOME, never in a caller-supplied directory. A `cwd`
+  // parameter let an authenticated request read any readable folder's AGENTS.md,
+  // and it also described a prompt that depends on where Codex happened to run.
+  // The global home is the one context this page can honestly report on.
+  const codexHome = resolveCodexHomeDir();
+  const binary = resolveCodexBinary();
+  if (!binary) {
+    return { ok: false, codexHome, layers: {}, detail: "codex binary not found" };
+  }
+  const raw = await runProbe(binary, codexHome, timeoutMs);
+  if (raw === null) {
+    return { ok: false, codexHome, layers: {}, detail: "codex debug prompt-input failed" };
+  }
+  const sections = extractSections(raw);
+  if (sections.size === 0) {
+    // Zero sections from a zero-exit probe means the output did not parse, which
+    // is a failed read - not fifteen layers that each chose to send nothing.
+    return { ok: false, codexHome, layers: {}, detail: "prompt output could not be parsed" };
+  }
+  const layers: Record<string, LayerText> = {};
+  for (const [layerId, tag] of Object.entries(LAYER_SECTION_TAGS)) {
+    const text = sections.get(tag) ?? null;
+    layers[layerId] = text === null
+      // Registered but not rendered on this turn, which is an ordinary state for
+      // a diff-rendered section rather than an error.
+      ? { text: null, reason: "not-rendered", bytes: 0 }
+      : { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8") };
+  }
+
+  // A file that exists and is empty is not the same as a layer that chose to send
+  // nothing. Reporting "sent nothing" for an empty AGENTS.md tells the user their
+  // layer is idle when the real answer is that the file they wrote is blank.
+  const agentsMdPath = join(codexHome, "AGENTS.md");
+  if (layers["agents-md"]?.reason === "not-rendered" && existsSync(agentsMdPath)) {
+    try {
+      if (statSync(agentsMdPath).size === 0) {
+        layers["agents-md"] = { text: null, reason: "empty-source", bytes: 0, sourcePath: agentsMdPath };
+      }
+    } catch {
+      // An unreadable file stays "not-rendered": we cannot claim it is empty.
+    }
+  }
+  // The base prompt travels outside prompt.input and cannot be read this way.
+  layers["base-instructions"] = { text: null, reason: "not-exposed", bytes: 0 };
+
+  // Layers whose rendered tag we have not confirmed against live output. Leaving
+  // them absent made the GUI fall through to "unavailable", which claims the probe
+  // failed when it succeeded. Saying we have no mapping is the smaller claim.
+  for (const id of UNMAPPED_LAYER_IDS) {
+    layers[id] ??= { text: null, reason: "not-exposed", bytes: 0 };
+  }
+  return { ok: true, codexHome, layers };
+}

package/src/codex/quota.ts

@@ -23,6 +23,7 @@ export type StoredAccountQuota = {
   shortPercent?: number;
   shortResetAt?: number;
   shortWindowSeconds?: number;
+  customWindows?: Array<{ label: string; percent: number; resetAt?: number }>;
   resetCredits?: number;
   /**
    * True when `monthlyPercent` came from an explicitly-monthly PRIMARY window —
@@ -61,6 +62,16 @@ export type WhamUsageResponse = {
   rate_limit_reset_credits?: {
     available_count: number;
   } | null;
+  additional_rate_limits?: WhamAdditionalRateLimit[] | null;
+};
+
+type WhamAdditionalRateLimit = {
+  limit_name?: unknown;
+  metered_feature?: unknown;
+  rate_limit?: {
+    primary_window?: WhamUsageWindow | null;
+    secondary_window?: WhamUsageWindow | null;
+  } | null;
 };
 
 type WhamUsageWindow = {
@@ -84,6 +95,9 @@ const MONTHLY_WINDOW_MIN_SECONDS = 28 * 24 * 60 * 60;
  */
 const WEEKLY_WINDOW_MIN_SECONDS = 24 * 60 * 60;
 const MONTHLY_WINDOW_MIN_MINUTES = MONTHLY_WINDOW_MIN_SECONDS / 60;
+// Derived, never written as a literal: the header parser and the WHAM parser must not be able
+// to drift to different thresholds, which is the class of defect this pair exists to prevent.
+const WEEKLY_WINDOW_MIN_MINUTES = WEEKLY_WINDOW_MIN_SECONDS / 60;
 
 const accountQuota = new Map<string, StoredAccountQuota>();
 let lastReconciledGeneration = 0;
@@ -187,7 +201,8 @@ function normalizeResetAt(value: unknown): number | undefined {
 
 function hasKnownQuotaValue(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
   return [quota.weeklyPercent, quota.monthlyPercent, quota.shortPercent]
-    .some(value => typeof value === "number" && Number.isFinite(value));
+    .some(value => typeof value === "number" && Number.isFinite(value))
+    || !!quota.customWindows?.some(window => Number.isFinite(window.percent));
 }
 
 /** True only for a window that DECLARES a duration shorter than a day. */
@@ -207,14 +222,24 @@ function isExplicitMonthlyWindow(window: WhamUsageWindow | null | undefined): bo
 }
 
 function isExplicitMonthlyWindowMinutes(windowMinutes: unknown): boolean {
-  const minutes = typeof windowMinutes === "number"
-    ? windowMinutes
-    : typeof windowMinutes === "string" && windowMinutes.trim() !== ""
-      ? Number(windowMinutes)
+  const minutes = windowMinutes_(windowMinutes);
+  return minutes !== undefined && minutes >= MONTHLY_WINDOW_MIN_MINUTES;
+}
+
+/** The header wire reports a window duration in MINUTES; WHAM reports it in seconds. */
+function windowMinutes_(value: unknown): number | undefined {
+  const minutes = typeof value === "number"
+    ? value
+    : typeof value === "string" && value.trim() !== ""
+      ? Number(value)
       : undefined;
-  return typeof minutes === "number"
-    && Number.isFinite(minutes)
-    && minutes >= MONTHLY_WINDOW_MIN_MINUTES;
+  return typeof minutes === "number" && Number.isFinite(minutes) ? minutes : undefined;
+}
+
+/** Minutes-domain twin of isExplicitShortWindow. Same strict `<`, same 24h discriminator. */
+function isExplicitShortWindowMinutes(value: unknown): boolean {
+  const minutes = windowMinutes_(value);
+  return minutes !== undefined && minutes > 0 && minutes < WEEKLY_WINDOW_MIN_MINUTES;
 }
 
 
@@ -232,8 +257,12 @@ function snapshotHasShort(quota: Omit<StoredAccountQuota, "updatedAt">): boolean
     || quota.shortWindowSeconds !== undefined;
 }
 
+function snapshotHasCustom(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.customWindows !== undefined;
+}
+
 function snapshotHasUsage(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
-  return snapshotHasWeekly(quota) || snapshotHasMonthly(quota) || snapshotHasShort(quota);
+  return snapshotHasWeekly(quota) || snapshotHasMonthly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota);
 }
 export function setAccountQuotaFromParsed(
   accountId: string,
@@ -255,6 +284,7 @@ export function setAccountQuotaFromParsed(
     if (existing?.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
     if (existing?.shortResetAt !== undefined) next.shortResetAt = existing.shortResetAt;
     if (existing?.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
+    if (existing?.customWindows !== undefined) next.customWindows = existing.customWindows;
     next.resetCredits = quota.resetCredits;
     accountQuota.set(accountId, next);
     schedulePersistAccountQuotas();
@@ -279,7 +309,7 @@ export function setAccountQuotaFromParsed(
     // while silently dropping `monthlyIsPrimaryWindow` would look like tertiary-only data to
     // any future reader, and that failure would be invisible.
     if (quota.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
-  } else if ((snapshotHasWeekly(quota) || snapshotHasShort(quota))
+  } else if ((snapshotHasWeekly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota))
       && existing?.monthlyPercent !== undefined) {
     next.monthlyPercent = existing.monthlyPercent;
     if (existing.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
@@ -298,6 +328,8 @@ export function setAccountQuotaFromParsed(
     if (existing?.shortWindowSeconds !== undefined) next.shortWindowSeconds = existing.shortWindowSeconds;
   }
 
+  if (snapshotHasCustom(quota)) next.customWindows = quota.customWindows;
+
   if (quota.resetCredits !== undefined) next.resetCredits = quota.resetCredits;
   else if (existing?.resetCredits !== undefined) next.resetCredits = existing.resetCredits;
 
@@ -323,6 +355,12 @@ export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQ
   const secondaryResetAt = normalizeResetAt(secondaryResetRaw);
   const tertiaryResetAt = normalizeResetAt(tertiaryResetRaw);
   const primaryIsMonthly = primaryRaw !== null && isExplicitMonthlyWindowMinutes(primaryWindowMinutes);
+  // Codex removed the 5-hour window and has now restored it for Plus and Team (Pro stays
+  // weekly-only). A primary window that DECLARES a sub-day duration is a burst window: folding
+  // it into weeklyPercent both discards the real weekly reading and leaves the account looking
+  // exhausted long after the burst window resets. Duration decides, exactly as parseUsageQuota
+  // already does for the WHAM payload — the two parsers must not disagree about the same data.
+  const primaryIsShort = primaryRaw !== null && isExplicitShortWindowMinutes(primaryWindowMinutes);
 
   if (primaryIsMonthly) {
     if (primaryPercent !== undefined) {
@@ -337,6 +375,19 @@ export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQ
       quota.weeklyPercent = secondaryPercent;
       if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
     }
+  } else if (primaryIsShort) {
+    if (primaryPercent !== undefined) {
+      quota.shortPercent = primaryPercent;
+      if (primaryResetAt !== undefined) quota.shortResetAt = primaryResetAt;
+      const minutes = windowMinutes_(primaryWindowMinutes);
+      if (minutes !== undefined) quota.shortWindowSeconds = Math.round(minutes * 60);
+    }
+    // The burst window vacates the primary slot, so the weekly reading is the secondary — which
+    // is where it was all along. Without this the true weekly value is silently dropped.
+    if (secondaryPercent !== undefined) {
+      quota.weeklyPercent = secondaryPercent;
+      if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
+    }
   } else {
     const weeklyPercent = primaryPercent ?? secondaryPercent;
     const weeklyResetAt = primaryPercent !== undefined
@@ -394,6 +445,7 @@ export function updateAccountQuota(
     ...(existing?.shortPercent !== undefined ? { shortPercent: existing.shortPercent } : {}),
     ...(existing?.shortResetAt !== undefined ? { shortResetAt: existing.shortResetAt } : {}),
     ...(existing?.shortWindowSeconds !== undefined ? { shortWindowSeconds: existing.shortWindowSeconds } : {}),
+    ...(existing?.customWindows !== undefined ? { customWindows: existing.customWindows } : {}),
     ...(existing?.resetCredits !== undefined ? { resetCredits: existing.resetCredits } : {}),
     updatedAt: Date.now(),
   };
@@ -506,6 +558,9 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
     : undefined;
 
   if (!data.rate_limit) {
+    if (data.additional_rate_limits?.length) {
+      return parseUsageQuota({ ...data, rate_limit: {} });
+    }
     return resetCredits !== undefined ? { resetCredits } : null;
   }
 
@@ -567,6 +622,32 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
     // different period, so recovery must not treat the two as interchangeable.
     if (primaryIsMonthly && primaryPercent !== undefined) quota.monthlyIsPrimaryWindow = true;
   }
+
+  const spark = data.additional_rate_limits?.find(additional => {
+    const name = String(additional.limit_name ?? "").toLowerCase();
+    const feature = String(additional.metered_feature ?? "").toLowerCase();
+    return feature === "codex_bengalfox" || name.includes("gpt-5.3-codex-spark");
+  });
+  const sparkWindows = [spark?.rate_limit?.primary_window, spark?.rate_limit?.secondary_window]
+    .filter((window): window is WhamUsageWindow => !!window);
+  const sparkWeekly = sparkWindows.find(window => {
+    const percent = normalizeUsagePercent(window.used_percent);
+    const seconds = window.limit_window_seconds;
+    return percent !== undefined
+      && !isExplicitShortWindow(window)
+      && !isExplicitMonthlyWindow(window)
+      && (seconds === undefined || seconds >= WEEKLY_WINDOW_MIN_SECONDS);
+  });
+  const sparkPercent = normalizeUsagePercent(sparkWeekly?.used_percent);
+  if (sparkPercent !== undefined) {
+    const sparkWindow: { label: string; percent: number; resetAt?: number } = {
+      label: "GPT-5.3-Codex-Spark Weekly",
+      percent: sparkPercent,
+    };
+    const resetAt = normalizeResetAt(sparkWeekly?.reset_at);
+    if (resetAt !== undefined) sparkWindow.resetAt = resetAt;
+    quota.customWindows = [sparkWindow];
+  }
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
   return hasKnownQuotaValue(quota) || resetCredits !== undefined ? quota : null;

package/src/codex/routing.ts

@@ -612,6 +612,15 @@ export function tryAcquireCodexQuotaScopeProbeLease(
   return probeLeaseId;
 }
 
+/** Side-effect-free check for a confirmed model-specific quota probe. */
+export function canAcquireCodexQuotaScopeProbeLease(
+  accountId: string,
+  scope: CodexQuotaScope,
+  now = Date.now(),
+): boolean {
+  return canAcquireQuotaProbeLease(scopedHealthFor(accountId, scope), now);
+}
+
 /**
  * Hand a probe lease back without recording an upstream outcome. Used by paths
  * that take a lease and then fail before any request reaches upstream.

package/src/codex/shim.ts

@@ -603,6 +603,47 @@ function backupPathFor(path: string): string {
   return ext ? `${path.slice(0, -ext.length)}.opencodex-real${ext}` : `${path}.opencodex-real`;
 }
 
+/**
+ * True when a Codex binary lives inside a version manager's install tree.
+ *
+ * These trees are rewritten in place on upgrade, which destroys both the shim
+ * and the sibling .opencodex-real backup it restores from (#2412). The tempting
+ * repair — adopt the newly installed binary as a fresh original — is wrong
+ * twice: it records a provenance that never happened, and the next upgrade wipes
+ * it again, so the repair silently un-repairs on the version manager's schedule.
+ *
+ * Scope is the three managers named in the report. nvm/fnm/npm-prefix are
+ * deliberately excluded: a false positive here refuses a restore that would
+ * otherwise be correct.
+ */
+export function isVersionManagerOwnedCodexPath(path: string): boolean {
+  const normalized = path.replace(/\\/g, "/").toLowerCase();
+  return normalized.includes("/mise/installs/")
+    || normalized.includes("/mise/shims/")
+    || normalized.includes("/.asdf/installs/")
+    || normalized.includes("/.asdf/shims/")
+    || normalized.includes("/.volta/");
+}
+
+/**
+ * Why auto-restore refused, in the operator's own terms. Auto-restore used to
+ * return a bare `{ status: "ineligible" }`, and the CLI warns only when a
+ * message is present, so `ocx start`, `ocx ensure`, and `ocx service repair` all
+ * reported success while routing quietly stayed native (#2412, the cause behind
+ * the misleading green status in #2411).
+ */
+function destroyedShimMessage(file: ShimFileState): string {
+  const wrapper = existsSync(file.wrapperPath)
+    ? isShim(file.wrapperPath) ? "present but unusable" : "present but not an opencodex shim"
+    : "missing";
+  const backup = existsSync(file.backupPath) ? "present" : "missing";
+  const base = `Codex autostart shim not restored: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
+  if (!isVersionManagerOwnedCodexPath(file.wrapperPath)) {
+    return `${base} Re-run 'ocx codex-shim install' once the Codex binary is stable.`;
+  }
+  return `${base} This Codex binary is owned by a version manager (mise/asdf/volta), so opencodex will not wrap it as a new original — the next upgrade would overwrite the shim and its backup again. Route through Codex instead with 'ocx start', and use 'ocx service install' for autostart.`;
+}
+
 function shQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -2039,14 +2080,20 @@ export function autoRestoreCodexShim(options: {
     if (seen.has(file.wrapperPath)) return { status: "ineligible" };
     seen.add(file.wrapperPath);
     if (file.preserveOnly) {
-      if (!existsSync(file.backupPath) || existsSync(file.originalPath)) return { status: "ineligible" };
+      if (!existsSync(file.backupPath) || existsSync(file.originalPath)) {
+        return { status: "ineligible", message: destroyedShimMessage(file) };
+      }
       continue;
     }
-    if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) return { status: "ineligible" };
+    if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) {
+      return { status: "ineligible", message: destroyedShimMessage(file) };
+    }
     const probe = stableShimPathProbe(file.wrapperPath);
     if (!probe) return { status: "deferred" };
     if (probe.prefix.includes(SHIM_MARKER)) {
-      if (!isHealthyShimProbe(probe, state.platform)) return { status: "ineligible" };
+      if (!isHealthyShimProbe(probe, state.platform)) {
+        return { status: "ineligible", message: destroyedShimMessage(file) };
+      }
       if (state.platform !== "win32" && !isCurrentUnixShimProbe(probe)) {
         obsoleteShimProbes.set(file.wrapperPath, probe);
         continue;
@@ -2054,6 +2101,12 @@ export function autoRestoreCodexShim(options: {
       healthyCount += 1;
       continue;
     }
+    // A surviving backup would otherwise let the replacement path below wrap the
+    // version manager's NEW binary as a fresh original — the same adoption the
+    // missing-backup case refuses, arriving through the back door.
+    if (isVersionManagerOwnedCodexPath(file.wrapperPath)) {
+      return { status: "ineligible", message: destroyedShimMessage(file) };
+    }
     replacementProbes.set(file.wrapperPath, probe);
   }