@bitkyc08/opencodex 2.83.0 → 2.86.0

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

@@ -776,18 +776,23 @@ function extractSections(raw: string): Map<string, string> {
   }
   if (!Array.isArray(parsed)) return sections;
   for (const item of parsed) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
     const content = (item as { content?: unknown }).content;
     if (!Array.isArray(content)) continue;
-    const text = content.map(part => String((part as { text?: unknown }).text ?? "")).join("");
+    const text = content.map(part => {
+      if (!part || typeof part !== "object" || Array.isArray(part)) return "";
+      const value = (part as { text?: unknown }).text;
+      return typeof value === "string" ? value : "";
+    }).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.
+    // AGENTS.md is NOT tagged: it arrives as a `# AGENTS.md instructions`
+    // 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
@@ -795,8 +800,25 @@ function extractSections(raw: string): Map<string, string> {
     // 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);
+    //
+    // The `for <path>` suffix is OPTIONAL. Upstream emits three shapes from
+    // `contextual_user_fragment().render()` (core/src/context.rs) and this has
+    // to read all three rather than the one that existed when the probe was
+    // written: the legacy single-root form `# AGENTS.md instructions for
+    // <dir>`, the no-directory form `# AGENTS.md instructions`, and the
+    // multi-environment form where each project's block is labeled `for \`<env>\`
+    // with root <cwd>` INSIDE the INSTRUCTIONS wrapper. The labels are part of
+    // what the model sees, so they stay in the captured body.
+    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());
+    else if (/# AGENTS\.md instructions/.test(text)) {
+      // The header rendered but in a shape this extractor does not recognize -
+      // a future upstream format, or prose truncated by the output cap. Claiming
+      // the layer "sent nothing" would be a lie about a block that is plainly
+      // present; the sentinel maps it to `unmapped`, the existing honest answer
+      // for "rendered in a form we cannot show".
+      sections.set("__agents_md_unmatched", "");
+    }
   }
   return sections;
 }
@@ -814,6 +836,13 @@ function mapSectionsToLayers(sections: Map<string, string>): Record<string, Laye
       ? { text: null, reason: "not-rendered", bytes: 0 }
       : { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8") };
   }
+  // `__agents_md_unmatched` is the sentinel for "the AGENTS.md header rendered in
+  // a shape the bounded extractor does not recognize". `unmapped` is the honest
+  // answer for it: the text exists but cannot be shown, which `not-rendered`
+  // would deny outright.
+  if (layers["agents-md"]?.reason === "not-rendered" && sections.has("__agents_md_unmatched")) {
+    layers["agents-md"] = { text: null, reason: "unmapped", bytes: 0 };
+  }
   return layers;
 }
 

package/src/codex/quota.ts

@@ -319,9 +319,12 @@ export function setAccountQuotaFromParsed(
       credentialGeneration: historyEvidence.writer.credentialGeneration, windows: historyWindows(historyEvidence.raw),
     }, updatedAt);
   }
-  // Legacy rotation keeps its existing carry behavior, but never inherits policy-only
+  // Rotation shares validated main-window retirement, but never inherits policy-only
   // evidence that outlived its disk TTL. Policy has a separate, identity-checked base.
-  const next = mergeAccountQuota(quota, legacyExisting, updatedAt);
+  const displayQuota: MainPolicyQuotaObservation = isMain && mainWriter && policyQuota?.shortWindowAbsent === true
+    ? { ...quota, shortWindowAbsent: true }
+    : quota;
+  const next = mergeAccountQuota(displayQuota, legacyExisting, updatedAt);
   accountQuota.set(accountId, next);
   if (isMain) {
     if (mainWriter && policyQuota && snapshotHasUsage(policyQuota)) {
@@ -440,7 +443,7 @@ function mergeAccountQuota(
     }
     if (quota.shortResetAt !== undefined) next.shortResetAt = quota.shortResetAt;
     if (quota.shortWindowSeconds !== undefined) next.shortWindowSeconds = quota.shortWindowSeconds;
-  } else if (!policyEvidence || quota.shortWindowAbsent !== true) {
+  } else if (quota.shortWindowAbsent !== true) {
     // Unknown usage is not a lower reading. Retain the entire known tuple: pairing
     // its percentage with new metadata would silently extend or shorten its reset.
     // An elapsed reset is the exception. It describes a window that has already rolled over,
@@ -879,14 +882,17 @@ function filterMainPolicyMonthlyQuota(
 /**
  * Parse ordinary main-policy usage, rejecting messages with invalid numeric window percentages.
  * A measured long primary, or explicitly absent primary with measured weekly secondary,
- * proves replacement only with complete long/null topology. Null supplies no usable evidence.
+ * proves replacement with long/null topology; an allowed two-window response may omit tertiary.
+ * Null supplies no usable evidence.
  */
 export function parseMainPolicyUsageQuota(data: WhamUsageResponse): MainPolicyQuotaObservation | null {
   const windows = [data.rate_limit?.primary_window, data.rate_limit?.secondary_window, data.rate_limit?.tertiary_window];
   if (windows.some(window => isInvalidPolicyUsagePercent(window?.used_percent))) return null;
   const quota = filterMainPolicyMonthlyQuota(parseUsageQuota(data), isThirtyDayOnlyCodexPlan(data.plan_type));
   const [primary, secondary, tertiary] = windows;
-  // WHAM explicitly reports absent windows as null; omissions cannot prove replacement.
+  // Primary and secondary must explicitly report their topology. WHAM also sends
+  // two-window responses without tertiary; an explicit allowed verdict disambiguates those
+  // from partial observations. A present tertiary still requires measured long/null evidence.
   // Policy trusts one complete snapshot only when every non-null window is >=24h AND
   // carries a valid usage reading: a long window without used_percent leaves that
   // window's usage unknown, and unknown usage must never release a block.
@@ -894,7 +900,8 @@ export function parseMainPolicyUsageQuota(data: WhamUsageResponse): MainPolicyQu
   if (quota && (isMeasuredLongWindow(primary)
       || (primary === null && isMeasuredLongWindow(secondary) && quota.weeklyPercent !== undefined))
     && (secondary === null || isMeasuredLongWindow(secondary))
-    && (tertiary === null || isMeasuredLongWindow(tertiary))) {
+    && (tertiary === null || isMeasuredLongWindow(tertiary)
+      || (tertiary === undefined && data.rate_limit?.allowed === true))) {
     return { ...quota, shortWindowAbsent: true };
   }
   return quota;

package/src/codex/role-auto-assign.ts

@@ -123,7 +123,7 @@ export type RoleProposal = RoleProposalInput & (
     readonly moveUpIf: string;
     readonly moveDownIf: string;
     readonly proposedModel: string | null;
-    /** Only when the role already carries an effort, unless the caller asks for one always. */
+    /** The sized effort on the picked model's ladder; null only when that model has no ladder. */
     readonly proposedEffort: string | null;
     readonly reason: string | null;
   }
@@ -134,7 +134,6 @@ export function buildRoleProposals(
   roles: readonly RoleProposalInput[],
   sizing: ReadonlyMap<string, RoleSizingOutcome>,
   classified: readonly ClassifiedCandidate[],
-  options: { readonly alwaysProposeEffort?: boolean } = {},
 ): RoleProposal[] {
   return roles.map(role => {
     const outcome = sizing.get(role.role) ?? { unsized: "the role was not sized" };
@@ -151,9 +150,7 @@ export function buildRoleProposals(
         reason: `no available model is classified ${tier} or above`,
       };
     }
-    const proposedEffort = role.effort === null && !options.alwaysProposeEffort
-      ? null
-      : mapEffortToLevel(effort, pick.efforts, pick.defaultEffort);
+    const proposedEffort = mapEffortToLevel(effort, pick.efforts, pick.defaultEffort);
     return { ...sized, status: "proposed", proposedModel: pick.model, proposedEffort, reason: null };
   });
 }

package/src/codex/routing/active-account.ts

@@ -2,6 +2,7 @@ import { saveConfigPreservingClaudeCode } from "../../config";
 import { clearCodexAccountPin, pinnedCodexAccountId } from "../account-priority";
 import {
   POOL_KEY_CODEX,
+  clearPoolRotationState,
   normalizeCodexAccountPoolStrategy,
   seedPoolRotationAccount,
 } from "../pool-rotation";
@@ -74,6 +75,26 @@ export function resetCodexRoutingForManualSelection(accountId: string): void {
   }
 }
 
+/**
+ * Operator released the selection instead of naming a new account: return routing to
+ * automatic without steering. A release names no replacement, so bound threads keep
+ * their captured account and quota-avoidance health stands — nothing new overrules it.
+ * What still has to go is the steering a selection planted: the one-shot manual
+ * preference (releasing account A must not keep blocking every other pick), the
+ * runtime cursor, and the rotation seeds on the shared ring and each independent
+ * quota-scope ring, which would otherwise force the next pick onto that same account.
+ */
+export function resetCodexRoutingForClearedSelection(): void {
+  runtimeActiveCodexAccountId = undefined;
+  manualPreference.delete(POOL_KEY_CODEX);
+  clearPoolRotationState(POOL_KEY_CODEX);
+  for (const scope of new Set(Object.values(NATIVE_MODEL_QUOTA_SCOPES))) {
+    if (isIndependentCodexQuotaScope(scope)) {
+      clearPoolRotationState(codexPoolKeyForScope(scope));
+    }
+  }
+}
+
 /** Effective active: automatic runtime cursor, else operator/persisted selection. */
 /**
  * Unspent operator selections, keyed by pool scope.

package/src/codex/routing/health-store.ts

@@ -163,7 +163,7 @@ export function deleteScopedHealth(accountId: string, scope: CodexQuotaScope): v
 }
 
 /** Live quota-refusal avoidance for an account, including the lane the request belongs to. */
-function codexQuotaAvoidUntil(
+export function codexQuotaAvoidUntil(
   accountId: string,
   quotaScope: CodexQuotaScope | undefined,
   now: number,

package/src/codex/routing/pool-recovery.ts

@@ -0,0 +1,79 @@
+/**
+ * When another stored pool account can serve again, for a main-account hard-lock refusal (#7046).
+ *
+ * A pool request that fell through to the main login and met the main-account quota guard used
+ * to be told to come back at main's own reset, which can be days away while a sibling pool
+ * account recovers within hours. This module answers one question: the earliest KNOWN instant at
+ * which a stored pool account's every temporary hold ends. It changes no routing state, selects
+ * nothing, and never lifts the main guard. The client retries at that time, and ordinary selection
+ * decides again from fresh state; a reset timestamp is a hint, not proof of fresh quota.
+ *
+ * Conservative by construction (the policy Jun is asked to confirm in #7046):
+ * - An account is a candidate only when it is a selectable stored pool account that is not
+ *   paused, plan-excluded, quarantined for sign-in, otherwise unusable, or denied for the model.
+ *   Those are operator or credential states no clock lifts.
+ * - Its recovery time is the LATEST of every routing hold with a known end: quota-health cooldown,
+ *   quota avoidance, transient soft avoidance, pool-refresh backoff, and the credits-off
+ *   usage-limit reset. An account under a hold whose end is unknown, or under the sliding
+ *   failure-window guard (whose end moves with every failure), is skipped rather than guessed.
+ * - For an account-gated model, only accounts the resolved entitlement roster admits count, and
+ *   with no resolved roster nothing does.
+ * - An account with no recorded hold is skipped: nothing says when it became unavailable, so
+ *   nothing says when it will be available again.
+ * - Main itself is never a candidate; its own reset stays on the refusal.
+ */
+import { isCodexAccountPaused } from "../account-pause";
+import { codexUsageLimitResetAt } from "../account-credit-use";
+import { isSelectableCodexPoolAccount } from "../account-id";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import { isCodexAccountUsable } from "../account-usability";
+import { getCodexPoolRefreshCooldownUntil } from "../pool-refresh-backoff";
+import { getAccountQuota } from "../quota";
+import type { OcxConfig } from "../../types";
+import { failureWindowSteersNewThreads } from "./failure-window";
+import {
+  codexQuotaAvoidUntil, getCodexAccountSoftAvoidUntil, getCodexQuotaHealthSnapshot, type CodexQuotaScope,
+} from "./health-store";
+import { getPoolAccountPlanForSelection, isCodexAccountHeldAtUsageLimit, isCodexAccountPlanExcluded } from "./selection";
+
+export function nextCodexPoolRecoveryAt(
+  config: OcxConfig,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+  options: {
+    deniedAccountIds?: ReadonlySet<string>;
+    /** When set, only these accounts may serve the model (account-gated models). */
+    eligibleAccountIds?: ReadonlySet<string>;
+  } = {},
+): number | undefined {
+  let earliest: number | undefined;
+  for (const account of config.codexAccounts ?? []) {
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    const id = account.id;
+    if (options.deniedAccountIds?.has(id) || (options.eligibleAccountIds && !options.eligibleAccountIds.has(id))
+      || isCodexAccountPaused(config, id)
+      || isCodexAccountPlanExcluded(config, id) || isAccountNeedsReauth(id)
+      || !isCodexAccountUsable(config, id) || failureWindowSteersNewThreads(config, id, now)) continue;
+    const holds: number[] = [];
+    const health = getCodexQuotaHealthSnapshot(id, quotaScope, now);
+    if (health) {
+      if (typeof health.cooldownUntil !== "number" || !Number.isFinite(health.cooldownUntil)) continue;
+      holds.push(health.cooldownUntil);
+    }
+    const avoidUntil = codexQuotaAvoidUntil(id, quotaScope, now);
+    if (avoidUntil !== null) holds.push(avoidUntil);
+    const softAvoidUntil = getCodexAccountSoftAvoidUntil(id, now);
+    if (softAvoidUntil !== null) holds.push(softAvoidUntil);
+    const refreshCooldownUntil = getCodexPoolRefreshCooldownUntil(id, now);
+    if (refreshCooldownUntil !== null) holds.push(refreshCooldownUntil);
+    if (isCodexAccountHeldAtUsageLimit(config, id, now)) {
+      const resetAt = codexUsageLimitResetAt(getAccountQuota(id), getPoolAccountPlanForSelection(config, id), now);
+      if (resetAt === undefined) continue;
+      holds.push(resetAt);
+    }
+    if (holds.length === 0) continue;
+    const recoveryAt = Math.max(...holds);
+    if (recoveryAt > now && (earliest === undefined || recoveryAt < earliest)) earliest = recoveryAt;
+  }
+  return earliest;
+}

package/src/codex/routing.ts

@@ -215,7 +215,7 @@ export {
   pickAlternateCodexAccount,
 } from "./routing/selection";
 export {
-  resetCodexRoutingForManualSelection,
+  resetCodexRoutingForManualSelection, resetCodexRoutingForClearedSelection,
   getEffectiveActiveCodexAccountId,
   isEffectiveCodexAccountPinned,
 } from "./routing/active-account";

package/src/codex/runtime.ts

@@ -1,13 +1,14 @@
 import { execFile, execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { delimiter, join } from "node:path";
+import { delimiter, join, posix } 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";
 import { SUBPROCESS_KILL_GRACE_MS, waitForSubprocessExit } from "../lib/bounded-subprocess";
+import { isPassiveRead } from "../lib/passive-read";
 
 export type CodexRuntimeSource =
   | "environment"
@@ -89,6 +90,8 @@ export interface ResolveCodexRuntimeDeps {
   execFile?: RuntimeExecFileAsync;
   existsSync?: (path: string) => boolean;
   readFileSync?: (path: string, encoding: "utf8") => string;
+  /** Bounded in-process macOS bundle identity reader; injected readers bypass the memo. */
+  readBundleIdentifier?: (infoPlistPath: string) => string | null;
   now?: () => number;
   /**
    * When false, stop after the first valid priority candidate (skip PATH-wide
@@ -225,10 +228,11 @@ export function loadLastEffortClamp(
   }
 }
 
+/** Return whether a nonempty observation changed, so catalog notices share persistence's identity. */
 export function persistEffortClamp(
   diagnostic: EffortClampDiagnostic | null,
   deps: ResolveCodexRuntimeDeps = {},
-): void {
+): boolean {
   const configDir = deps.configDir ?? getConfigDir();
   const path = codexRuntimeClampStatePath(configDir);
   if (!diagnostic || diagnostic.removedEfforts.length === 0) {
@@ -237,8 +241,16 @@ export function persistEffortClamp(
     } catch {
       /* absent is fine */
     }
-    return;
+    return false;
   }
+  // This is an observation, not a heartbeat: rewriting updatedAt on every sync both churns disk
+  // and makes identical clamps look new after restart. Compare sets, not catalog enumeration order.
+  const previous = loadLastEffortClamp(deps);
+  const setKey = (values: readonly string[]) => JSON.stringify([...new Set(values)].sort());
+  if (previous && previous.runtimePath === diagnostic.runtimePath
+    && previous.runtimeVersion === diagnostic.runtimeVersion
+    && setKey(previous.removedEfforts) === setKey(diagnostic.removedEfforts)
+    && setKey(previous.affectedModels) === setKey(diagnostic.affectedModels)) return false;
   const payload: PersistedClampState = {
     version: 1,
     updatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
@@ -249,6 +261,7 @@ export function persistEffortClamp(
   };
   mkdirSync(configDir, { recursive: true, mode: 0o700 });
   atomicWriteFile(path, `${JSON.stringify(payload, null, 2)}\n`);
+  return true;
 }
 
 export function displayCodexRuntimePath(command: string): string {
@@ -425,6 +438,9 @@ function versionProbePrecheck(command: string, deps: ResolveCodexRuntimeDeps): V
   // `codex --version` here is ~1s of blocking exec per candidate; on the
   // dashboard probe that cost made Windows report Codex as missing even when
   // the App install was sitting under LOCALAPPDATA/OpenAI/Codex/bin (issue 4458).
+  if (!macCodexAppIdentityMatches(command, deps)) {
+    return { ok: false, reason: "Codex app bundle identity mismatch or unavailable" };
+  }
   if (deps.probeVersion === false) return { ok: true, version: null };
   return null;
 }
@@ -599,6 +615,161 @@ function pathCandidates(deps: ResolveCodexRuntimeDeps): string[] {
   return [...new Set(out)];
 }
 
+/** Conventional Codex desktop bundles, ordered system before user. */
+function macCodexAppBundles(deps: ResolveCodexRuntimeDeps): string[] {
+  const env = deps.env ?? process.env;
+  const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
+  return ["/Applications/ChatGPT.app", posix.join(home, "Applications/ChatGPT.app")];
+}
+
+function macCodexAppCommands(deps: ResolveCodexRuntimeDeps): string[] {
+  return macCodexAppBundles(deps).flatMap(bundle => [
+    `${bundle}/Contents/Resources/codex-cli/bin/codex`, `${bundle}/Contents/Resources/codex`,
+  ]);
+}
+
+function realpathOrNull(path: string): string | null {
+  try { return realpathSync(path); } catch { return null; }
+}
+
+/**
+ * Classify any path inside either bundle, including backing executables, by normalized and
+ * canonical forms with a segment boundary: a symlinked HOME (or /tmp -> /private/tmp) must not
+ * let a canonical bundle path skip the identity check or the handover exclusion.
+ */
+function macCodexAppBundleFor(command: string, deps: ResolveCodexRuntimeDeps): string | undefined {
+  if ((deps.platform ?? process.platform) !== "darwin" || !posix.isAbsolute(command)) return undefined;
+  const forms = [posix.normalize(command), realpathOrNull(command)].filter((form): form is string => Boolean(form));
+  return macCodexAppBundles(deps).find(bundle => {
+    const roots = [posix.normalize(bundle), realpathOrNull(bundle)].filter((root): root is string => Boolean(root));
+    return forms.some(form => roots.some(root => form.startsWith(`${root}/`)));
+  });
+}
+
+function macCodexAppIdentityMatches(command: string, deps: ResolveCodexRuntimeDeps): boolean {
+  const bundle = macCodexAppBundleFor(command, deps);
+  if (!bundle) return true;
+  try {
+    return (deps.readBundleIdentifier ?? readBoundedBundleIdentifier)(`${bundle}/Contents/Info.plist`) === "com.openai.codex";
+  } catch { return false; }
+}
+
+/** XML plist subset only: no external entity expansion, subprocess, or unbounded read. */
+function readBoundedBundleIdentifier(path: string): string | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const st = fstatSync(fd);
+    const limit = 64 * 1024;
+    if (!st.isFile() || st.size > limit) return null;
+    const bytes = Buffer.alloc(limit + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      const count = readSync(fd, bytes, size, bytes.length - size, null);
+      if (!count) break;
+      size += count;
+    }
+    if (size > limit) return null;
+    // XML 1.0 Char: tab, LF, CR, U+0020-D7FF, U+E000-FFFD, U+10000-10FFFF (no surrogates after fatal decoding).
+    const xmlChar = (code: number): boolean => code === 9 || code === 10 || code === 13
+      || (code >= 0x20 && code <= 0xd7ff) || (code >= 0xe000 && code <= 0xfffd) || (code >= 0x10000 && code <= 0x10ffff);
+    const allXmlChars = (text: string): boolean => [...text].every(char => xmlChar(char.codePointAt(0)!));
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, size));
+    // Every character is checked before anything is stripped, the prolog included.
+    if (!allXmlChars(decoded)) return null;
+    // Only a well-formed UTF-8 declaration and Apple's DOCTYPE are accepted, anchored in the prolog, in that order.
+    const declaration = /^<\?xml\s+version=(["'])1\.[0-9]\1(?:\s+encoding=(["'])utf-8\2)?(?:\s+standalone=(["'])(?:yes|no)\3)?\s*\?>/i;
+    if (decoded.startsWith("<?") && !declaration.test(decoded)) return null;
+    const xml = decoded
+      .replace(declaration, "")
+      .replace(/^\s*<!DOCTYPE plist PUBLIC "-\/\/Apple\/\/DTD PLIST 1\.0\/\/EN" "http:\/\/www\.apple\.com\/DTDs\/PropertyList-1\.0\.dtd">/, "");
+    type Node = { name: string; text: string; children: Node[] };
+    const root: Node = { name: "root", text: "", children: [] };
+    const stack = [root];
+    const tokens = xml.match(/<!--[\s\S]*?-->|<[^>]*>|[^<]+/g) ?? [];
+    if (tokens.join("") !== xml) return null;
+    for (const token of tokens) {
+      if (token.startsWith("<!--")) {
+        // A comment may not contain "--" or end in "-" (XML 1.0 §2.5).
+        if (/--|-$/.test(token.slice(4, -3))) return null;
+        continue;
+      }
+      const parent = stack[stack.length - 1]!;
+      if (!token.startsWith("<")) {
+        if (token.includes("]]>")) return null;
+        parent.text += token;
+        continue;
+      }
+      const close = /^<\/(\w+)\s*>$/.exec(token);
+      if (close) {
+        if (stack.length === 1 || parent.name !== close[1]) return null;
+        stack.pop();
+        continue;
+      }
+      const open = /^<(plist|dict|array|key|string|integer|real|date|data|true|false)(?:\s+version="1\.0")?\s*(\/?)>$/.exec(token);
+      if (!open || (token.includes("version=") && open[1] !== "plist")) return null;
+      const node: Node = { name: open[1]!, text: "", children: [] };
+      parent.children.push(node);
+      if (!open[2]) stack.push(node);
+    }
+    if (stack.length !== 1 || root.text.trim() || root.children.length !== 1) return null;
+    const plist = root.children[0]!;
+    if (plist.name !== "plist" || plist.text.trim() || plist.children.length !== 1) return null;
+    const dict = plist.children[0]!;
+    if (dict.name !== "dict" || dict.text.trim() || dict.children.length % 2) return null;
+    const decode = (text: string): string => text.replace(/&([^;]*);|&/g, (_match, entity: string | undefined) => {
+      const named: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+      if (entity && Object.hasOwn(named, entity)) return named[entity]!;
+      if (!entity || !/^#(?:[0-9]+|x[0-9a-fA-F]+)$/.test(entity)) throw new Error("invalid XML entity");
+      const value = entity.startsWith("#x") ? parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+      if (!xmlChar(value)) throw new Error("invalid XML character");
+      return String.fromCodePoint(value);
+    });
+    // The identity only counts inside a document that is valid as a whole: every node, entity and
+    // literal character is checked, not just the CFBundleIdentifier pair.
+    const leafFormats: Record<string, RegExp> = {
+      integer: /^\s*[+-]?(?:\d+|0x[0-9a-fA-F]+)\s*$/,
+      real: /^\s*(?:[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|[+-]?(?:nan|inf(?:inity)?))\s*$/i,
+      date: /^\s*\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\s*$/,
+      data: /^[A-Za-z0-9+/=\s]*$/,
+    };
+    const validNode = (node: Node, inDict: "key" | "value" | null): boolean => {
+      if (!allXmlChars(node.text)) return false;
+      if (inDict === "key" && node.name !== "key") return false;
+      if (inDict !== "key" && node.name === "key") return false;
+      switch (node.name) {
+        case "dict":
+          return !node.text.trim() && node.children.length % 2 === 0
+            && node.children.every((child, index) => validNode(child, index % 2 === 0 ? "key" : "value"));
+        case "array":
+          return !node.text.trim() && node.children.every(child => validNode(child, null));
+        case "key": case "string":
+          decode(node.text);
+          return node.children.length === 0;
+        case "true": case "false":
+          return node.children.length === 0 && !node.text.trim();
+        case "integer": case "real": case "date": case "data":
+          return node.children.length === 0 && leafFormats[node.name]!.test(decode(node.text));
+        default:
+          return false;
+      }
+    };
+    if (!validNode(dict, null)) return null;
+    let identifier: string | null = null;
+    let keys = 0;
+    for (let i = 0; i < dict.children.length; i += 2) {
+      const key = dict.children[i]!, value = dict.children[i + 1]!;
+      if (key.name !== "key" || key.children.length) return null;
+      if (decode(key.text) !== "CFBundleIdentifier") continue;
+      keys++;
+      if (value.name !== "string" || value.children.length) return null;
+      identifier = decode(value.text);
+    }
+    return keys === 1 ? identifier : null;
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
 /**
  * Codex installs that PATH does not necessarily expose.
  *
@@ -647,6 +818,10 @@ function installedCodexCandidates(deps: ResolveCodexRuntimeDeps): string[] {
     "/usr/local/bin/codex",
     "/opt/homebrew/bin/codex",
   ];
+  if (platform === "darwin") {
+    const exists = deps.existsSync ?? existsSync;
+    return [...posix, ...macCodexAppCommands(deps).filter(command => exists(command) && macCodexAppIdentityMatches(command, deps))];
+  }
   if (platform !== "linux") return posix;
   // Windows Codex Desktop in WSL app-server mode ships its Linux binary under the
   // effective Codex home as bin/wsl/<version-hash>/codex, and a Desktop update replaces
@@ -839,6 +1014,7 @@ function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
     || deps.execFile
     || deps.existsSync
     || deps.readFileSync
+    || deps.readBundleIdentifier
     || deps.readdirSync
     || deps.statSync
     || deps.configDir
@@ -974,7 +1150,8 @@ export function getCodexRuntimeSnapshot(): ResolveCodexRuntimeResult {
   const cacheKey = resolveCacheKey({});
   const memo = resolveCache?.key === cacheKey ? resolveCache : null;
   if (memo && Date.now() - memo.at < RESOLVE_CACHE_MS) return cloneAndDeepFreeze(memo.value);
-  resolveCodexRuntimeAsync().catch(() => { /* the next read retries */ });
+  // A passive read (a Remote Link Child's, #6959) starts no version probes on this machine.
+  if (!isPassiveRead()) resolveCodexRuntimeAsync().catch(() => { /* the next read retries */ });
   if (memo) return cloneAndDeepFreeze(memo.value);
   return resolveCodexRuntime({ discoverAlternatives: false, probeVersion: false });
 }
@@ -1020,10 +1197,18 @@ function* resolveCodexRuntimeSteps(
   for (const command of pathCandidates(deps)) {
     ordered.push({ command, source: "path" });
   }
-  for (const command of installedCodexCandidates(deps)) {
+  const installed = installedCodexCandidates(deps);
+  // Order by the generated app commands only: an established install path that links into the
+  // app keeps its precedence, while identity and handover use the canonical classification.
+  const appCommands = new Set(macCodexAppCommands(deps));
+  const appCandidates = installed.filter(command => appCommands.has(command));
+  for (const command of installed.filter(command => !appCommands.has(command))) {
     ordered.push({ command, source: "installed" });
   }
   ordered.push({ command: "codex", source: "fallback" });
+  for (const command of appCandidates) {
+    ordered.push({ command, source: "installed" });
+  }
 
   const seen = new Set<string>();
   const valid: ResolvedCodexRuntime[] = [];
@@ -1045,13 +1230,16 @@ function* resolveCodexRuntimeSteps(
   // there is then nothing to compare it against.
   const persistedIsUnpinned = Boolean(persisted?.command) && !persistedCodexRuntimeIsPinned(persisted);
   for (const candidate of ordered) {
+    // Deferred resolution accepts the bare fallback without proving it exists; when a verified
+    // app CLI is present it must not preempt that app. Other platforms keep the old behaviour.
+    if (candidate.source === "fallback" && deps.probeVersion === false && appCandidates.length > 0) continue;
     const key = candidate.command.toLowerCase();
     if (seen.has(key)) continue;
     seen.add(key);
     if (
       deps.discoverAlternatives === false
       && valid.length > 0
-      && !(persistedIsUnpinned && candidate.source === "installed")
+      && !(persistedIsUnpinned && candidate.source === "installed" && !macCodexAppBundleFor(candidate.command, deps))
     ) {
       continue;
     }
@@ -1111,6 +1299,7 @@ function* resolveCodexRuntimeSteps(
         const newerDiscovered = valid
           .filter(item =>
             !sameRuntimeCommand(item.command, selected.command)
+            && !macCodexAppBundleFor(item.command, deps)
             && typeof item.version === "string"
             && typeof selected.version === "string"
             && compareCodexVersions(item.version, selected.version) > 0)
@@ -1232,6 +1421,5 @@ export function formatClampLogLines(diagnostic: EffortClampDiagnostic): string[]
   const efforts = diagnostic.removedEfforts.join(", ");
   return [
     `[opencodex] Removed unsupported reasoning efforts: ${efforts}`,
-    "[opencodex] Run ocx doctor for diagnosis and recovery.",
   ];
 }

package/src/codex/shim-diagnostics.ts

@@ -29,6 +29,12 @@ export interface CodexShimDiagnostic {
   summary: string;
   runnable?: boolean;
   active?: boolean | null;
+  /**
+   * PATH overlay only: the wrapper and its private state are intact and runnable, but this process
+   * could not see it first on PATH. Reinstalling cannot change that; the shell must source the
+   * environment file. The dashboard's PATH can also differ from the user's shell (#6971).
+   */
+  activationPending?: boolean;
 }
 
 /** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */