@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/codex/catalog/retained-sync.ts

@@ -33,6 +33,7 @@ import {
   readCodexCatalogPath,
   readCodexCatalogPathForHome,
   readNativeBaseline,
+  nativeMultiAgentDefaults,
 } from "./parsing";
 import type { CatalogModel, MultiAgentMode, RawCatalog, RawEntry } from "./parsing";
 import {
@@ -50,6 +51,7 @@ import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
 import { bundledCatalogCacheState, loadBundledCodexCatalog } from "./bundled";
 import { isMultiAgentV2Enabled } from "../features";
 import { clampCatalogModelsToCodexSupport } from "./effort";
+import { suppressedSyntheticMaxCatalogSlugs } from "./model-hints";
 import { filterCatalogVisibleModels, gatherRoutedModels, type CatalogGatherProviderModelOutcome } from "./provider-fetch";
 import { dedupeCatalogEntriesBySlug, enforceCatalogSlugUniqueness, exactComboCatalogSlugs, type ComboCatalogOmission } from "./aggregation";
 import {
@@ -75,6 +77,7 @@ import {
 import { finishUpstreamNativeEntry } from "./derive-entry";
 import { finalizeAutoReviewModelOverride } from "./auto-review";
 import { gatedNativeAccountLabel, gatedNativeReauthSuppressionReason, warnGatedNativeSuppressedOnce } from "./gated-native-warn";
+import { reserveCatalogSuppressionReason, warnReserveSuppressedOnce } from "./reserve-warn";
 
 interface RetainedCatalogSyncRead {
   readonly catalogPath: string;
@@ -320,6 +323,11 @@ function writeRetainedCatalogSync({
   const enabledGo = filterCatalogVisibleModels(goModels, config);
   const featured = config.subagentModels ?? [];
   const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
+  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(
+    config,
+    orderedGoModels,
+    catalogModelsForMerge,
+  );
   const modelPickerOrder = config.modelPickerOrder ?? [];
   const multiAgentMode: MultiAgentMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
   const exactComboSlugs = exactComboCatalogSlugs(config);
@@ -376,6 +384,14 @@ function writeRetainedCatalogSync({
   const accountTargets = new Map(codexAccountNamespaceEntries(config));
   const reserveMainSelectors = accountSelectors.filter(selector =>
     isMainCodexAccountTarget(accountTargets.get(selector) ?? ""));
+  // #4811: an omitted Reserve row carries no reason, so the explanation has to be emitted here,
+  // where the selector inputs that produced the omission are still in scope. Silent for every
+  // install that did not opt into authless Codex Desktop routing.
+  const reserveSuppression = reserveCatalogSuppressionReason(config, {
+    includeAccountBoundNativeOpenAi,
+    mainSelectors: reserveMainSelectors,
+  });
+  if (reserveSuppression) warnReserveSuppressedOnce(reserveSuppression);
   // The active file can own a bare source even when the bundled catalog is the build base.
   // A previously clamped qualified projection must not shorten a retained genuine ladder.
   const reserveObservations = [
@@ -443,6 +459,7 @@ function writeRetainedCatalogSync({
   // like `gpt-5.5`; those must not delete the native OpenAI/Codex base row.
   const baselineCatalog = readCatalogBackup(catalogPath);
   const baseline = readNativeBaseline(catalogPath);
+  const nativePinBaseline = nativeMultiAgentDefaults(baselineCatalog?.models);
   const gatheredProviderNames = new Set(
     Object.entries(config.providers ?? {})
       .filter(([, prov]) => prov.disabled !== true)
@@ -512,8 +529,10 @@ function writeRetainedCatalogSync({
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    suppressedSyntheticMaxSlugs,
     openaiContextCap,
     nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
+    nativeMultiAgentDefaults: nativePinBaseline,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],

package/src/codex/catalog/routed-gather.ts

@@ -850,6 +850,26 @@ function augmentRoutedModelsWithCapturedOpenAiApiRows(
   ];
 }
 
+/**
+ * Add generated-registry rows the live provider list did not return, and backfill a
+ * published context window onto a live row that arrived without one.
+ *
+ * The backfill is the reason this function has a merge branch at all. It used to skip every
+ * id the live list returned, which is correct for a row that already knows its window and
+ * wrong for the normal OpenCode Go case, where discovery returns an id with no context
+ * field at all. The serialized Codex catalog was unaffected, because
+ * `applyCatalogMetadata` writes `context_window` onto the entry straight from the generated
+ * table; the absence was only visible to consumers that read `CatalogModel.contextWindow`
+ * (#4971). Those are not cosmetic: `buildClaudeContextWindows` drops a routed row with no
+ * window from the map that decides the `[1m]` marker, so a published 1M model could not be
+ * recognized as one, and the Grok config writer and several client exporters omit the field
+ * entirely rather than emit a known value.
+ *
+ * It is a missing-value fill, never an override: a live positive window still wins, because
+ * the upstream is the authority on its own model. The seeded row is re-hinted so operator
+ * precedence is unchanged — a configured window still lowers it and `providerContextCaps`
+ * still caps it, exactly as for an appended row.
+ */
 export function augmentRoutedModelsWithMetadata(
   models: CatalogModel[],
   providerNames: string[],
@@ -858,7 +878,7 @@ export function augmentRoutedModelsWithMetadata(
   metadataModelIdCaseFoldByProvider?: ReadonlyMap<string, boolean>,
 ): CatalogModel[] {
   const out = [...models];
-  const seen = new Set(out.map(m => `${m.provider}/${m.id}`));
+  const indexByKey = new Map(out.map((model, index) => [`${model.provider}/${model.id}`, index]));
   for (const provider of providerNames) {
     if (!JAWCODE_CATALOG_AUGMENT_PROVIDERS.has(provider)) continue;
     if (providers?.[provider]?.liveModels === false) continue;
@@ -866,9 +886,28 @@ export function augmentRoutedModelsWithMetadata(
     if (!jawcodeProvider) continue;
     for (const meta of listModelMetadata(jawcodeProvider)) {
       const key = `${provider}/${meta.id}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
       const contextCap = caps ? providerContextCap(caps, provider) : undefined;
+      const existingIndex = indexByKey.get(key);
+      if (existingIndex !== undefined) {
+        const existing = out[existingIndex]!;
+        const publishedWindow = typeof meta.contextWindow === "number" && meta.contextWindow > 0
+          ? meta.contextWindow
+          : undefined;
+        const liveWindow = typeof existing.contextWindow === "number" && existing.contextWindow > 0;
+        if (liveWindow || publishedWindow === undefined) continue;
+        const seeded: CatalogModel = { ...existing, contextWindow: publishedWindow };
+        out[existingIndex] = providers?.[provider]
+          ? applyProviderConfigHints(
+            provider,
+            providers[provider],
+            seeded,
+            contextCap,
+            metadataModelIdCaseFoldByProvider?.get(provider),
+          )
+          : seeded;
+        continue;
+      }
+      indexByKey.set(key, out.length);
       const model: CatalogModel = {
         provider,
         id: meta.id,

package/src/codex/cli-installation-identity.ts

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { win32 } from "node:path";
+import { parseStrictSemver } from "../lib/strict-semver";
+
+/** Explicit observation, not runtime selection or authority to run an installer. */
+export interface CodexCliInstallationIdentityInput {
+  readonly candidate: string;
+  readonly npmPrefix: string;
+  readonly npmCli: string;
+  readonly node: string;
+  /** Where the candidate came from; defaults to an explicit CLI argument. */
+  readonly candidateSource?: "explicit-cli" | "selected";
+}
+
+export interface CodexCliInstallationIdentityReport {
+  readonly schemaVersion: 1;
+  readonly candidateSource: "explicit-cli" | "selected";
+  readonly status: "observed" | "refused";
+  readonly reason: string;
+  readonly installationIdentityObserved: boolean;
+  readonly selectionAttested: false;
+  readonly managed: false;
+  readonly applyAllowed: false;
+  readonly packageVersion: string | null;
+  readonly npmVersion: string | null;
+  readonly identityDigest: string | null;
+  readonly proof: "windows-handle-bound" | null;
+  readonly toolchain: "observed-only";
+}
+
+export interface InstallationFileRequest {
+  readonly path: string;
+  readonly maxBytes: number;
+  readonly hashOnly?: boolean;
+}
+
+export interface ObservedInstallationFile {
+  readonly path: string;
+  readonly identity: {
+    readonly volumeSerial: string;
+    readonly fileId: string;
+    readonly size: number;
+    readonly lastWriteTime: string;
+    readonly changeTime: string;
+  };
+  readonly bytes: Uint8Array;
+  readonly digest?: string;
+}
+
+export type InstallationFilesResult =
+  | { readonly kind: "observed"; readonly files: readonly ObservedInstallationFile[] }
+  | { readonly kind: "refused"; readonly reason: string };
+
+export interface CodexCliInstallationIdentityDeps {
+  readonly platform?: NodeJS.Platform;
+  readonly inspectFiles?: (requests: readonly InstallationFileRequest[]) => Promise<InstallationFilesResult>;
+}
+
+const TEXT_LIMIT = 256 * 1024;
+const NODE_LIMIT = 256 * 1024 * 1024;
+const hash = (value: string | Uint8Array): string => createHash("sha256").update(value).digest("hex");
+// NTFS can enable case-sensitive directory entries. Do not collapse different
+// paths merely because ordinary Windows directories usually ignore case.
+const key = (path: string): string => path[0]!.toUpperCase() + path.slice(1);
+
+function localPath(value: string): string | null {
+  if (typeof value !== "string" || value.length > 30_000 || !/^[a-z]:[\\/]/i.test(value)) return null;
+  const path = value.replaceAll("/", "\\");
+  const parts = path.slice(3).split("\\");
+  if (!parts.length || parts.some(part => !part || part === "." || part === ".."
+    || /[\x00-\x1f<>:"|?*]/.test(part) || /[. ]$/.test(part)
+    || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) return null;
+  return path;
+}
+
+function supportedLayoutPath(path: string): boolean {
+  // This slice does not adopt package managers or packaged desktop applications.
+  return !/(?:^|\\)(?:windowsapps|scoop|\.volta|\.nvm|\.asdf|\.mise|\.fnm|\.nvs|\.nodenv)(?:\\|$)|\.app(?:\\|$)/i.test(path);
+}
+
+function report(
+  reason: string,
+  versions?: { codex: string; npm: string; digest: string },
+  candidateSource: CodexCliInstallationIdentityReport["candidateSource"] = "explicit-cli",
+): CodexCliInstallationIdentityReport {
+  return Object.freeze({
+    schemaVersion: 1, candidateSource, status: versions ? "observed" : "refused",
+    reason, installationIdentityObserved: !!versions, selectionAttested: false, managed: false,
+    applyAllowed: false, packageVersion: versions?.codex ?? null, npmVersion: versions?.npm ?? null,
+    identityDigest: versions?.digest ?? null, proof: versions ? "windows-handle-bound" : null,
+    toolchain: "observed-only",
+  });
+}
+
+/** A refusal before any observation ran, e.g. when no selected candidate can be identified. */
+export function codexCliInstallationRefusal(
+  reason: string,
+  candidateSource: CodexCliInstallationIdentityReport["candidateSource"] = "explicit-cli",
+): CodexCliInstallationIdentityReport {
+  return report(reason, undefined, candidateSource);
+}
+
+function manifest(file: ObservedInstallationFile, name: string, bin: string, expected: string): string | null {
+  try {
+    const value: unknown = JSON.parse(Buffer.from(file.bytes).toString("utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    const item = value as Record<string, unknown>;
+    const entry = typeof item.bin === "string" ? item.bin
+      : item.bin && typeof item.bin === "object" ? (item.bin as Record<string, unknown>)[bin] : null;
+    return item.name === name && typeof item.version === "string" && parseStrictSemver(item.version)
+      && entry === expected ? item.version : null;
+  } catch { return null; }
+}
+
+/** Only the standard npm cmd-shim is linked here; arbitrary wrappers remain unverified. */
+function npmCodexCommandShim(bytes: Uint8Array): boolean {
+  const expected = `@ECHO off
+GOTO start
+:find_dp0
+SET dp0=%~dp0
+EXIT /b
+:start
+SETLOCAL
+CALL :find_dp0
+
+IF EXIST "%dp0%\\node.exe" (
+  SET "_prog=%dp0%\\node.exe"
+) ELSE (
+  SET "_prog=node"
+  SET PATHEXT=%PATHEXT:;.JS;=;%
+)
+
+endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\node_modules\\@openai\\codex\\bin\\codex.js" %*`;
+  const normalize = (text: string) => text.replaceAll("\r\n", "\n").trimEnd();
+  return normalize(Buffer.from(bytes).toString("utf8")) === normalize(expected);
+}
+
+function fileDigest(file: ObservedInstallationFile): string {
+  return file.digest ?? hash(file.bytes);
+}
+
+function fileEvidence(file: ObservedInstallationFile): readonly (string | number)[] {
+  const id = file.identity;
+  return [key(file.path), id.volumeSerial, id.fileId, id.size, id.lastWriteTime, id.changeTime, fileDigest(file)];
+}
+
+/** No filesystem or native-library work occurs until this explicit operation is called. */
+export async function inspectCodexCliInstallationIdentity(
+  input: CodexCliInstallationIdentityInput,
+  deps: CodexCliInstallationIdentityDeps = {},
+): Promise<CodexCliInstallationIdentityReport> {
+  const source = input.candidateSource ?? "explicit-cli";
+  const refused = (reason: string) => report(reason, undefined, source);
+  if ((deps.platform ?? process.platform) !== "win32") return refused("unsupported_platform");
+  const candidate = localPath(input.candidate);
+  const prefix = localPath(input.npmPrefix);
+  const npmCli = localPath(input.npmCli);
+  const node = localPath(input.node);
+  if (!candidate || !prefix || !npmCli || !node) return refused("unsafe_path");
+  if (![candidate, prefix, npmCli, node].every(supportedLayoutPath)) return refused("unsupported_layout");
+  const packageRoot = win32.join(prefix, "node_modules", "@openai", "codex");
+  const codexManifest = win32.join(packageRoot, "package.json");
+  const codexBin = win32.join(packageRoot, "bin", "codex.js");
+  const shim = win32.join(prefix, "codex.cmd");
+  // A codex.opencodex-real.cmd backup is npm's renamed launcher: same grammar, same dir.
+  const backingShim = win32.join(prefix, "codex.opencodex-real.cmd");
+  const acceptedCandidates = source === "selected"
+    ? [key(codexBin), key(shim), key(backingShim)]
+    : [key(codexBin), key(shim)];
+  if (!acceptedCandidates.includes(key(candidate))
+    || !/\\node_modules\\npm\\bin\\npm-cli\.js$/i.test(npmCli)
+    || win32.basename(node).toLowerCase() !== "node.exe") return refused("unsupported_layout");
+  const npmManifest = win32.join(win32.dirname(win32.dirname(npmCli)), "package.json");
+  try {
+    const inspect = deps.inspectFiles ?? (await import("./windows-installation-files")).inspectWindowsInstallationFiles;
+    // Read both manifests again with every linked file held open: first-pass bytes cannot
+    // authorize links after a manifest replacement between the two observations.
+    const first = await inspect([{ path: codexManifest, maxBytes: TEXT_LIMIT }, { path: npmManifest, maxBytes: TEXT_LIMIT }]);
+    if (first.kind !== "observed") return refused("native_proof_unavailable");
+    const initial = new Map(first.files.map(file => [key(file.path), file]));
+    const codex = initial.get(key(codexManifest));
+    const npm = initial.get(key(npmManifest));
+    if (!codex || !npm) return refused("read_failed");
+    const codexVersion = manifest(codex, "@openai/codex", "codex", "bin/codex.js");
+    const npmVersion = manifest(npm, "npm", "npm", "bin/npm-cli.js");
+    if (!codexVersion || !npmVersion) return refused("package_mismatch");
+    const requests: InstallationFileRequest[] = [codexManifest, npmManifest, candidate, codexBin, npmCli]
+      .filter((path, index, all) => all.findIndex(other => key(other) === key(path)) === index)
+      .map(path => ({ path, maxBytes: TEXT_LIMIT }));
+    requests.push({ path: node, maxBytes: NODE_LIMIT, hashOnly: true });
+    const second = await inspect(requests);
+    if (second.kind !== "observed") return refused("native_proof_unavailable");
+    const files = new Map(second.files.map(file => [key(file.path), file]));
+    if (requests.some(request => !files.has(key(request.path)))) return refused("read_failed");
+    for (const before of [codex, npm]) {
+      if (JSON.stringify(fileEvidence(before)) !== JSON.stringify(fileEvidence(files.get(key(before.path))!))) {
+        return refused("identity_changed");
+      }
+    }
+    if ([key(shim), key(backingShim)].includes(key(candidate))
+      && !npmCodexCommandShim(files.get(key(candidate))!.bytes)) {
+      return refused("launcher_mismatch");
+    }
+    const observed = [...files.values()].sort((a, b) => key(a.path) < key(b.path) ? -1 : key(a.path) > key(b.path) ? 1 : 0);
+    if (observed.some(file => !/^[a-f0-9]{64}$/i.test(fileDigest(file)))) return refused("read_failed");
+    const digest = hash(JSON.stringify(["opencodex-explicit-installation-observation-v1", key(prefix),
+      key(candidate), key(npmCli), key(node), ...observed.map(fileEvidence)]));
+    return report("identity_observed", { codex: codexVersion, npm: npmVersion, digest }, source);
+  } catch { return refused("read_failed"); }
+}

package/src/codex/cli-installation-targets.ts

@@ -0,0 +1,158 @@
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { win32 } from "node:path";
+import { SHIM_MARKER } from "./shim-templates";
+import type { CodexCliInstallationIdentityInput } from "./cli-installation-identity";
+
+/**
+ * The proof-captured launcher snapshot used to identify the selected candidate.
+ * Every field is optional because older launchers and direct Bun/source runs
+ * supply no snapshot at all; derivation fails closed rather than reading the
+ * ambient environment.
+ */
+export interface CodexCliInstallationSnapshot {
+  readonly codexCliPath?: string | null;
+  readonly path?: string | null;
+  readonly pathExt?: string | null;
+}
+
+export type CodexCliInstallationTargetRefusal =
+  | "unsupported_platform"
+  | "candidate_unavailable"
+  | "unsupported_layout"
+  | "toolchain_unresolved";
+
+export type CodexCliInstallationTargetDerivation =
+  | { readonly kind: "derived"; readonly input: CodexCliInstallationIdentityInput }
+  | { readonly kind: "unavailable"; readonly reason: CodexCliInstallationTargetRefusal };
+
+export interface CodexCliInstallationTargetDeps {
+  readonly platform?: NodeJS.Platform;
+  readonly exists?: (path: string) => boolean;
+  /** Bounded prefix read used only to recognize an OpenCodex-owned wrapper. */
+  readonly fileContains?: (path: string, marker: string) => boolean;
+}
+
+const DEFAULT_PATH_EXT = ".COM;.EXE;.BAT;.CMD;.PS1";
+const SHIM_PROBE_BYTES = 8 * 1024;
+const CODEX_PACKAGE_SUFFIX = "\\node_modules\\@openai\\codex\\bin\\codex.js";
+
+function defaultFileContains(path: string, marker: string): boolean {
+  let descriptor: number | undefined;
+  let contains = false;
+  try {
+    descriptor = openSync(path, "r");
+    const bytes = Buffer.allocUnsafe(SHIM_PROBE_BYTES);
+    const count = readSync(descriptor, bytes, 0, bytes.length, 0);
+    contains = bytes.subarray(0, count).toString("utf8").includes(marker);
+  } catch {
+    contains = false;
+  } finally {
+    if (descriptor !== undefined) {
+      try { closeSync(descriptor); } catch { contains = false; }
+    }
+  }
+  return contains;
+}
+
+/**
+ * First match wins, mirroring PATH resolution: directories in order, and within
+ * each directory every PATHEXT suffix in order (or the exact name when it
+ * already carries an extension). Skipping a hit to keep scanning would attest
+ * something other than the launcher that actually resolves.
+ */
+function scanPath(
+  name: string,
+  pathValue: string | null | undefined,
+  pathExt: string | null | undefined,
+  exists: (path: string) => boolean,
+): string | null {
+  const extensions = (pathExt ?? DEFAULT_PATH_EXT).split(";").map(value => value.trim()).filter(Boolean);
+  const names = /\.[a-z0-9]+$/i.test(name) ? [name] : extensions.map(ext => name + ext.toLowerCase());
+  for (const entry of (pathValue ?? "").split(";")) {
+    const dir = entry.trim().replace(/^"+|"+$/g, "");
+    if (!dir) continue;
+    for (const candidateName of names) {
+      const candidate = win32.join(dir, candidateName);
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Derive the four attestation inputs from the proof-captured launcher snapshot.
+ * Discovery only proposes candidate paths; the held-handle observation remains
+ * the authority, so a stale or racing probe can only produce a refusal, never a
+ * false identity. No ambient environment is read: without a snapshot the result
+ * is unavailable rather than silently trusting the child's environment.
+ */
+export function deriveCodexCliInstallationInput(
+  snapshot: CodexCliInstallationSnapshot,
+  deps: CodexCliInstallationTargetDeps = {},
+): CodexCliInstallationTargetDerivation {
+  if ((deps.platform ?? process.platform) !== "win32") {
+    return { kind: "unavailable", reason: "unsupported_platform" };
+  }
+  const exists = deps.exists ?? existsSync;
+  const fileContains = deps.fileContains ?? defaultFileContains;
+  const configured = snapshot.codexCliPath;
+
+  let candidate: string | null;
+  if (configured) {
+    if (/^[a-z]:[\\/]/i.test(configured)) {
+      if (!exists(configured)) return { kind: "unavailable", reason: "candidate_unavailable" };
+      candidate = win32.normalize(configured);
+    } else {
+      if (configured.includes("/") || configured.includes("\\")) {
+        return { kind: "unavailable", reason: "candidate_unavailable" };
+      }
+      candidate = scanPath(configured, snapshot.path, snapshot.pathExt, exists);
+      if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
+    }
+  } else {
+    candidate = scanPath("codex", snapshot.path, snapshot.pathExt, exists);
+    if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
+  }
+
+  // An OpenCodex wrapper at the npm prefix is our own launcher, not the npm
+  // artifact. The renamed original beside it is the file npm wrote.
+  if (/\.cmd$/i.test(candidate) && fileContains(candidate, SHIM_MARKER)) {
+    const backing = candidate.slice(0, -".cmd".length) + ".opencodex-real.cmd";
+    if (!exists(backing)) return { kind: "unavailable", reason: "unsupported_layout" };
+    candidate = backing;
+  }
+
+  const base = win32.basename(candidate).toLowerCase();
+  let prefix: string;
+  if (base === "codex.cmd" || base === "codex.opencodex-real.cmd") {
+    prefix = win32.dirname(candidate);
+  } else if (candidate.toLowerCase().endsWith(CODEX_PACKAGE_SUFFIX)) {
+    prefix = candidate.slice(0, candidate.length - CODEX_PACKAGE_SUFFIX.length);
+  } else {
+    return { kind: "unavailable", reason: "unsupported_layout" };
+  }
+  if (!exists(win32.join(prefix, "node_modules", "@openai", "codex", "package.json"))) {
+    return { kind: "unavailable", reason: "unsupported_layout" };
+  }
+
+  // The npm cmd-shim itself prefers %dp0%\node.exe before falling back to PATH.
+  let node = win32.join(prefix, "node.exe");
+  if (!exists(node)) {
+    const resolved = scanPath("node.exe", snapshot.path, null, exists);
+    if (!resolved) return { kind: "unavailable", reason: "toolchain_unresolved" };
+    node = resolved;
+  }
+  const npmCli = win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!exists(npmCli)) return { kind: "unavailable", reason: "toolchain_unresolved" };
+
+  return {
+    kind: "derived",
+    input: Object.freeze({
+      candidate,
+      npmPrefix: prefix,
+      npmCli,
+      node,
+      candidateSource: "selected",
+    }),
+  };
+}

package/src/codex/convergence.ts

@@ -36,6 +36,7 @@ import {
   catalogHasRoutedEntries,
   findSupportedNativeTemplate,
   legacyCatalogBackupPath,
+  nativeMultiAgentDefaults,
   parseCatalogJson,
   type RawCatalog,
   type RawEntry,
@@ -69,6 +70,7 @@ import {
   clampCatalogModelsToObservedCodexSupport,
   supportedCodexReasoningEffortsFromObservedCatalog,
 } from "./catalog/effort";
+import { suppressedSyntheticMaxCatalogSlugs } from "./catalog/model-hints";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "./account-namespaces";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
@@ -305,6 +307,7 @@ function prepareCatalog(
     [catalog.models ?? [], ...nativeRecoverySources],
   );
   const catalogModels = nativeCatalogModels;
+  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(config, ordered, catalogModels);
   const routedEntries = buildCatalogEntriesFromObservedState({
     template: template ? JSON.parse(JSON.stringify(template)) : null,
     gptSlugs: [],
@@ -371,8 +374,10 @@ function prepareCatalog(
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    suppressedSyntheticMaxSlugs,
     openaiContextCap,
     nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
+    nativeMultiAgentDefaults: nativeMultiAgentDefaults(baselineCatalogModels),
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],

package/src/codex/desktop-switches.ts

@@ -0,0 +1,145 @@
+import type { OcxConfig } from "../types";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import {
+  isEffectiveCodexClientCompaction,
+  isEffectiveCodexDesktopAuthless,
+} from "./loopback-target";
+
+export type CodexDesktopSwitchInertReason =
+  | "client_role"
+  | "non_loopback_bind_requires_admission_token";
+
+export interface CodexDesktopSwitchState {
+  stored: boolean;
+  effective: boolean;
+  inertReason?: CodexDesktopSwitchInertReason;
+}
+
+export type CodexDesktopSwitchApplyReason =
+  | "not_requested"
+  | "proxy_not_running"
+  | "integration_disabled"
+  | "write_lock_busy"
+  | "injection_refused";
+
+export type CodexDesktopSwitchApply =
+  | { applied: true }
+  | {
+      applied: false;
+      reason: CodexDesktopSwitchApplyReason;
+      retryable: boolean;
+      detail?: string;
+    };
+
+export interface CodexDesktopSwitchReport {
+  codexDesktopAuthless: CodexDesktopSwitchState;
+  codexClientCompaction: CodexDesktopSwitchState;
+  apply: CodexDesktopSwitchApply;
+  authSource: { presentsCodexAccount: boolean; summary: string };
+}
+
+type DesktopSwitchConfig = Pick<
+  OcxConfig,
+  | "clientIntegrations"
+  | "runtimeRole"
+  | "hostname"
+  | "unauthenticatedLoopbackListener"
+  | "codexDesktopAuthless"
+  | "codexClientCompaction"
+>;
+
+function describeSwitch(
+  stored: boolean,
+  effective: boolean,
+  config: Pick<OcxConfig, "runtimeRole">,
+): CodexDesktopSwitchState {
+  if (!stored || effective) return { stored, effective };
+  return {
+    stored,
+    effective,
+    inertReason: config.runtimeRole === "client"
+      ? "client_role"
+      : "non_loopback_bind_requires_admission_token",
+  };
+}
+
+export function describeCodexDesktopSwitches(
+  config: DesktopSwitchConfig,
+  apply: CodexDesktopSwitchApply,
+): CodexDesktopSwitchReport {
+  const authlessStored = config.codexDesktopAuthless === true;
+  const authlessEffective = isEffectiveCodexDesktopAuthless(config);
+  const compactionStored = config.codexClientCompaction === true;
+  const compactionEffective = isEffectiveCodexClientCompaction(config);
+
+  return {
+    codexDesktopAuthless: describeSwitch(authlessStored, authlessEffective, config),
+    codexClientCompaction: describeSwitch(compactionStored, compactionEffective, config),
+    apply,
+    authSource: authlessEffective
+      ? {
+          presentsCodexAccount: false,
+          summary: "The Codex app will not require its own account sign-in.",
+        }
+      : {
+          presentsCodexAccount: true,
+          summary: "The Codex app will require its own account sign-in.",
+        },
+  };
+}
+
+export async function applyCodexDesktopSwitches(
+  config: OcxConfig,
+): Promise<CodexDesktopSwitchApply> {
+  if (!shouldSyncCodexOnStart(config)) {
+    return { applied: false, reason: "integration_disabled", retryable: false };
+  }
+
+  const { readRuntimePort } = await import("../config/process-state");
+  const runtime = readRuntimePort(process.pid);
+  if (!runtime) {
+    return { applied: false, reason: "proxy_not_running", retryable: true };
+  }
+
+  try {
+    // Imported at call time, not module load. The settings route reaches this module on
+    // every GET, and pulling the whole injection graph in just to report stored-versus-
+    // effective state would put it on a read path that never writes anything.
+    const { injectCodexConfig } = await import("./inject");
+    const result = await injectCodexConfig(runtime.port, config);
+    if (result.status === "skipped") {
+      return {
+        applied: false,
+        reason: "integration_disabled",
+        retryable: false,
+        detail: result.message,
+      };
+    }
+    if (result.success) {
+      // history_paginated_requires_native_writer stands down only the legacy relabel;
+      // apply still writes the routing and catalog half for paginated Codex homes.
+      return { applied: true };
+    }
+    if (result.retryable === true) {
+      return {
+        applied: false,
+        reason: "write_lock_busy",
+        retryable: true,
+        detail: result.message,
+      };
+    }
+    return {
+      applied: false,
+      reason: "injection_refused",
+      retryable: false,
+      detail: result.message,
+    };
+  } catch (error) {
+    return {
+      applied: false,
+      reason: "injection_refused",
+      retryable: false,
+      detail: error instanceof Error ? error.message : "Codex config injection failed.",
+    };
+  }
+}