@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/codex/catalog/reserve-warn.ts

@@ -0,0 +1,96 @@
+import type { OcxConfig } from "../../types";
+import { isEffectiveCodexDesktopAuthless } from "../loopback-target";
+import { NATIVE_RESERVE_MODEL } from "./native-models";
+
+/**
+ * #4811: why an opted-in install still gets no Luna Reserve row.
+ *
+ * The Reserve projection is account-qualified — its slug is `<selector>/gpt-reserve` — so it
+ * cannot be written without a selector that targets the main Codex account. On a fresh authless
+ * install `codexAccountNamespaces` is empty, the account picker is therefore off, no selectors
+ * exist, and `createReserveCatalogProjection` returns `undefined`. Nothing downstream can
+ * explain that: an omitted row has no place to carry a reason, which is exactly the shape of
+ * #4212 for account-gated natives, and the same answer applies — say it once, here, while the
+ * inputs that produced the omission are still in scope.
+ *
+ * Deliberately scoped to an operator who asked for the feature. A default install has
+ * `codexDesktopAuthless` unset, wants no Reserve row, and must not be told about one. An install
+ * that stores the flag on a bind where it cannot take effect is a different silence, already
+ * reported as `inertReason` by `describeCodexDesktopSwitches`, and is not repeated here.
+ */
+export type ReserveCatalogSuppressionReason =
+  | "no-canonical-openai-provider"
+  | "account-picker-disabled"
+  | "no-account-namespaces"
+  | "no-main-account-selector";
+
+type ReserveSuppressionConfig = Pick<
+  OcxConfig,
+  | "runtimeRole"
+  | "hostname"
+  | "unauthenticatedLoopbackListener"
+  | "codexDesktopAuthless"
+  | "codexAccountNamespaces"
+  | "codexAccountPickerEnabled"
+>;
+
+export interface ReserveSuppressionInput {
+  /** Already resolved by the caller; passed in so this module stays off the metadata graph. */
+  includeAccountBoundNativeOpenAi: boolean;
+  /** Selectors that resolved to the main Codex account. A non-empty list means no suppression. */
+  mainSelectors: readonly string[];
+}
+
+export function reserveCatalogSuppressionReason(
+  config: ReserveSuppressionConfig,
+  input: ReserveSuppressionInput,
+): ReserveCatalogSuppressionReason | undefined {
+  if (!isEffectiveCodexDesktopAuthless(config) || input.mainSelectors.length > 0) return undefined;
+  if (!input.includeAccountBoundNativeOpenAi) return "no-canonical-openai-provider";
+  // Checked before the empty-map case: when an operator has explicitly turned the picker off,
+  // naming the empty map would send them to hand-author selectors that the opt-in generates.
+  if (config.codexAccountPickerEnabled === false) return "account-picker-disabled";
+  if (Object.keys(config.codexAccountNamespaces ?? {}).length === 0) return "no-account-namespaces";
+  return "no-main-account-selector";
+}
+
+const SUPPRESSION_TEXT: Readonly<Record<ReserveCatalogSuppressionReason, {
+  cause: string;
+  action: string;
+}>> = {
+  "no-canonical-openai-provider": {
+    cause: "no enabled canonical OpenAI provider can serve account-qualified native routes",
+    action: "Enable the built-in \"openai\" provider with forwarded ChatGPT auth.",
+  },
+  "account-picker-disabled": {
+    cause: "the Codex account picker is turned off (codexAccountPickerEnabled is false)",
+    action: "Set codexAccountPickerEnabled to true to generate the default account selectors.",
+  },
+  "no-account-namespaces": {
+    cause: "no Codex account selectors are configured (codexAccountNamespaces is empty)",
+    action: "Enable the Codex account picker once to generate the default account selectors.",
+  },
+  "no-main-account-selector": {
+    cause: "no configured selector in codexAccountNamespaces targets the main Codex account",
+    action: "Map one selector to the main Codex account.",
+  },
+};
+
+const warnedReserveSuppression = new Set<string>();
+
+/** Test seam: the warn-once memory is process-global, so a case needs to be able to clear it. */
+export function resetReserveSuppressionWarningsForTests(): void {
+  warnedReserveSuppression.clear();
+}
+
+export function warnReserveSuppressedOnce(reason: ReserveCatalogSuppressionReason): void {
+  if (warnedReserveSuppression.has(reason)) return;
+  warnedReserveSuppression.add(reason);
+  const text = SUPPRESSION_TEXT[reason];
+  console.warn(
+    `[opencodex] catalog sync: authless Codex Desktop routing is on, but the Luna Reserve row `
+      + `(<selector>/${NATIVE_RESERVE_MODEL}) is not being written because ${text.cause}. `
+      + `The Reserve projection is account-qualified and needs a selector for the main Codex `
+      + `account. ${text.action}`,
+  );
+}

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 {
@@ -57,10 +59,12 @@ import {
   type CatalogWritePermit,
 } from "../catalog-write-serialization";
 import {
+  preparedBytesDifferFromDisk,
   publishHashedCodexCatalogBackup,
   publishLegacyCodexCatalogBackup,
   replaceActiveCodexCatalog,
   replaceCodexModelsCache,
+  type PreparedCatalogFileWrite,
 } from "../internal/catalog-writer";
 import { visibleCodexAccountSelectors } from "./account-models";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./native-models";
@@ -75,6 +79,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;
@@ -231,24 +236,6 @@ function revalidateRetainedCatalogSync(
   };
 }
 
-/**
- * Exact bytes currently on disk at `path`, or null when unreadable/absent.
- *
- * Deliberately a Buffer rather than a decoded string: `readFileSync(path, "utf8")`
- * substitutes U+FFFD for every invalid byte, so a file holding a raw 0x80 decodes
- * equal to prepared content holding a legitimately encoded U+FFFD. Comparing the
- * decoded strings would then classify a malformed catalog as identical, skip the
- * atomic repair write, and leave the corruption on disk while reporting
- * `catalogWritten: false`.
- */
-function currentCatalogFileContent(path: string): Buffer | null {
-  try {
-    return readFileSync(path);
-  } catch {
-    return null;
-  }
-}
-
 function pristineCatalogBytes(read: RetainedCatalogSyncRead): string | null {
   if (read.onDiskCatalog && !catalogHasRoutedEntries(read.onDiskCatalog)) {
     try {
@@ -320,6 +307,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 +368,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 +443,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 +513,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],
@@ -539,15 +542,12 @@ function writeRetainedCatalogSync({
   // nothing about the catalog changed. Skipping the no-op write keeps both the mtime
   // and `catalogWritten` honest; `added` still reports the routed rows the catalog
   // carries, because they are on disk either way.
-  const onDiskBytes = currentCatalogFileContent(catalogPath);
-  if (onDiskBytes !== null && onDiskBytes.equals(Buffer.from(content, "utf8"))) {
+  const preparedCatalog: PreparedCatalogFileWrite = { path: catalogPath, content };
+  if (!preparedBytesDifferFromDisk(preparedCatalog)) {
     return { added, path: catalogPath, catalogWritten: false, comboOmissions };
   }
 
-  replaceActiveCodexCatalog(permit, owningCodexHome, {
-    path: catalogPath,
-    content,
-  });
+  replaceActiveCodexCatalog(permit, owningCodexHome, preparedCatalog);
   return {
     added,
     path: catalogPath,
@@ -694,10 +694,25 @@ export function invalidateCodexModelsCacheWithPermit(
       client_version: "0.0.0",
       models: [...models, ...observedAccountModels],
     };
-    replaceCodexModelsCache(permit, owningCodexHome, {
+    const preparedCache: PreparedCatalogFileWrite = {
       path: cachePath,
       content: `${JSON.stringify(wrapper, null, 2)}\n`,
-    });
+    };
+    // The same no-op rule the active catalog already applies (#1459), for the same
+    // reason and at the second writer that has to obey it.
+    //
+    // This function is what `refreshCodexModelCatalog` reports as `cacheSynced`, and
+    // `handleStart` ORs that into the stale-app-server warning. Rewriting identical
+    // bytes bumped this file's mtime and returned `true`, so on a start where the
+    // catalog reproduced byte-identically — the settled case — the warning still
+    // claimed "Disk catalog/cache were updated" and told the operator their Codex
+    // model list might be stale, when nothing on disk had changed and Codex held the
+    // same model set the file already described. Returning `false` here makes
+    // `cacheSynced` mean what its name and its consumers already assume, and what
+    // `pullRemoteCatalog` and the early returns in `refreshCodexModelCatalog`
+    // already assert: a write happened.
+    if (!preparedBytesDifferFromDisk(preparedCache)) return false;
+    replaceCodexModelsCache(permit, owningCodexHome, preparedCache);
     return true;
   } catch {
     return false;

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

@@ -113,6 +113,15 @@ export interface GatherRoutedModelsOptions {
   providerModelOutcomes?: CatalogGatherProviderModelOutcome[];
   /** Internal convergence sink for the immutable policy that produced the returned rows. */
   discoveryPolicySnapshots?: CatalogProviderDiscoveryPolicySnapshot[];
+  /**
+   * Each provider's cache content revision as of the moment its rows were chosen.
+   *
+   * A caller that derives something from these rows and wants to know later whether the rows are
+   * still current must use this, not a revision sampled after the gather returns: another flight
+   * can publish between the choice and the sample, and the derived value would then carry that
+   * flight's identity while holding these rows.
+   */
+  providerContentRevisions?: Map<string, string>;
 }
 
 interface GatherFlightResult {
@@ -121,6 +130,7 @@ interface GatherFlightResult {
   providerAuthOutcomes: readonly CatalogGatherProviderAuthOutcome[];
   providerModelOutcomes: readonly CatalogGatherProviderModelOutcome[];
   discoveryPolicySnapshots: readonly CatalogProviderDiscoveryPolicySnapshot[];
+  providerContentRevisions: ReadonlyMap<string, string>;
 }
 interface GatherInflightEntry {
   readonly discoveryPolicyIdentity: string;
@@ -256,6 +266,7 @@ async function gatherRoutedModelsWithAuth(
     providerAuthOutcomes,
     providerModelOutcomes,
     discoveryPolicySnapshots,
+    providerContentRevisions,
   } = await entry.promise;
   if (options?.comboOmissions) {
     options.comboOmissions.length = 0;
@@ -269,6 +280,12 @@ async function gatherRoutedModelsWithAuth(
     options.providerModelOutcomes.length = 0;
     options.providerModelOutcomes.push(...providerModelOutcomes);
   }
+  if (options?.providerContentRevisions) {
+    options.providerContentRevisions.clear();
+    for (const [provider, revision] of providerContentRevisions) {
+      options.providerContentRevisions.set(provider, revision);
+    }
+  }
   if (options?.discoveryPolicySnapshots) {
     options.discoveryPolicySnapshots.length = 0;
     options.discoveryPolicySnapshots.push(...discoveryPolicySnapshots);
@@ -763,6 +780,8 @@ async function gatherRoutedModelsUncached(
     providerAuthOutcomes: localProviderAuthOutcomes,
     providerModelOutcomes,
     discoveryPolicySnapshots: capture.discoveryPolicySnapshots,
+    // Stamped by each provider at the moment it chose its rows, not sampled here.
+    providerContentRevisions: new Map(providerResults.map(result => [result.outcome.provider, result.contentRevision])),
   };
 }
 
@@ -850,6 +869,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 +897,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 +905,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"); }
+}