@bitkyc08/opencodex 2.37.0 → 2.38.0

package/src/codex/cli-install-provenance.ts

@@ -0,0 +1,795 @@
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  constants as fsConstants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { posix, win32 } from "node:path";
+import { getConfigDir } from "../config";
+import { parseStrictSemver } from "../lib/strict-semver";
+import { CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS } from "../update/codex-cli-update-launch-policy.mjs";
+import { isSpawnableCodexCandidate } from "./exec-invocation";
+import {
+  codexRuntimeStatePath,
+  parsePersistedCodexRuntime,
+} from "./runtime";
+import {
+  inspectCodexShimBackingForCommand,
+  isLocalAbsoluteInspectionPath,
+  isVersionManagerOwnedCodexPath,
+  type CodexShimBackingForCommand,
+} from "./shim";
+
+const CODEX_PACKAGE = "@openai/codex";
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_RUNTIME_STATE_BYTES = 256 * 1024;
+const MAX_MANIFEST_ANCESTORS = 12;
+
+export type CodexCliInstallKind =
+  | "npm-global"
+  | "app-bundle"
+  | "version-manager"
+  | "standalone-unverified"
+  | "unknown";
+
+export type CodexCliInstallReason =
+  | "candidate_unavailable"
+  | "candidate_path_unavailable"
+  | "candidate_path_unsafe"
+  | "windows_inspection_deferred"
+  | "shim_state_unknown"
+  | "shim_update_deferred"
+  | "app_bundle"
+  | "version_manager_owned"
+  | "npm_global_unverified"
+  | "selection_unattested"
+  | "version_mismatch"
+  | "unverified_standalone"
+  | "inspection_failed";
+
+export type CodexCliCandidateSource = "environment" | "persisted";
+export type CodexCliInstallEvidence =
+  | "canonical_path"
+  | "app_bundle_path"
+  | "version_manager_path"
+  | "package_manifest"
+  | "package_manifest_digest"
+  | "shim_backing"
+  | "global_npm_layout";
+
+export interface ReadOnlyCodexRuntimeCandidate {
+  readonly command: string;
+  readonly version: string | null;
+  readonly evidence: CodexCliCandidateSource;
+}
+
+export interface CodexCliInstallReport {
+  readonly schemaVersion: 1;
+  readonly candidateAvailable: boolean;
+  readonly candidateVersion: string | null;
+  readonly candidateSource: CodexCliCandidateSource | null;
+  readonly selectionAttested: boolean;
+  readonly versionEvidence: Readonly<{
+    kind: "package-manifest" | "advisory-runtime" | "unavailable";
+  }>;
+  readonly provenance: CodexCliInstallKind;
+  readonly managed: boolean;
+  readonly reason: CodexCliInstallReason;
+  readonly location: string | null;
+  readonly packageVersion: string | null;
+  readonly shim: Readonly<{
+    status: "not-tracked" | "matched" | "unknown";
+    backingKind: "backup" | "real" | null;
+  }>;
+  readonly evidence: readonly CodexCliInstallEvidence[];
+}
+
+export interface CodexCliInstallProvenanceDeps {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly platform?: NodeJS.Platform;
+  readonly configDir?: string;
+  readonly exists?: (path: string) => boolean;
+  readonly lstat?: typeof lstatSync;
+  readonly stat?: typeof statSync;
+  readonly readFile?: (path: string) => Buffer;
+  readonly boundedFileReadMode?: "native-hardened" | "injected-test";
+  readonly realpath?: (path: string) => string;
+  readonly inspectShim?: (
+    command: string,
+    platform: NodeJS.Platform,
+    configDir: string,
+  ) => CodexShimBackingForCommand;
+}
+
+interface PackageManifestEvidence {
+  readonly path: string;
+  readonly root: string;
+  readonly binPath: string;
+  readonly version: string;
+  readonly digest: string;
+}
+
+function sha256(domain: string, value: string | Uint8Array): string {
+  return createHash("sha256")
+    .update(domain, "utf8")
+    .update("\0", "utf8")
+    .update(value)
+    .digest("hex");
+}
+
+function validatedVersion(value: string | null | undefined): string | null {
+  if (typeof value !== "string" || value !== value.trim()) return null;
+  return parseStrictSemver(value, 96)?.raw ?? null;
+}
+
+function publicExecutableLocation(path: string, platform: NodeJS.Platform): string {
+  const raw = pathTools(platform).basename(path).toLowerCase();
+  const safe = ["codex", "codex.exe", "codex.cmd", "codex.bat", "codex.com", "codex.js"].includes(raw)
+    ? raw : "codex";
+  return `<path>/${safe}`;
+}
+
+function freezeReport(report: CodexCliInstallReport): CodexCliInstallReport {
+  Object.freeze(report.shim);
+  Object.freeze(report.evidence);
+  return Object.freeze(report);
+}
+
+function unknownReport(
+  reason: CodexCliInstallReason,
+  candidate?: ReadOnlyCodexRuntimeCandidate,
+  extra: Partial<Pick<CodexCliInstallReport, "location">> = {},
+): CodexCliInstallReport {
+  return freezeReport({
+    schemaVersion: 1,
+    candidateAvailable: Boolean(candidate),
+    candidateVersion: candidate?.version ?? null,
+    candidateSource: candidate?.evidence ?? null,
+    selectionAttested: false,
+    versionEvidence: Object.freeze({
+      kind: candidate?.version ? "advisory-runtime" as const : "unavailable" as const,
+    }),
+    provenance: "unknown",
+    managed: false,
+    reason,
+    location: extra.location ?? null,
+    packageVersion: null,
+    shim: Object.freeze({ status: "not-tracked", backingKind: null }),
+    evidence: Object.freeze([]),
+  });
+}
+
+function unknownWindowsReport(
+  reason: CodexCliInstallReason,
+  candidate?: ReadOnlyCodexRuntimeCandidate,
+  extra: Partial<Pick<CodexCliInstallReport, "location">> = {},
+): CodexCliInstallReport {
+  return freezeReport({
+    ...unknownReport(reason, candidate, extra),
+    shim: Object.freeze({ status: "unknown", backingKind: null }),
+  });
+}
+
+function readPersistedCandidate(
+  deps: CodexCliInstallProvenanceDeps,
+): ReadOnlyCodexRuntimeCandidate | null {
+  // A pathname-only Windows read cannot prove that a writable ancestor stayed
+  // local and non-reparse between validation and open. PR1 therefore accepts
+  // only the proof-captured environment candidate on Windows; persisted-state
+  // inspection requires the later handle-bound Windows provenance layer.
+  if ((deps.platform ?? process.platform) === "win32") return null;
+  const configDir = deps.configDir ?? getConfigDir();
+  if (!isSafeLocalInspectionPath(configDir, deps)) return null;
+  try {
+    const statePath = codexRuntimeStatePath(configDir);
+    const bytes = readBoundedFile(statePath, MAX_RUNTIME_STATE_BYTES, deps);
+    if (!bytes) return null;
+    const parsed = parsePersistedCodexRuntime(
+      bytes,
+    );
+    if (!parsed) return null;
+    return {
+      command: parsed.command,
+      version: validatedVersion(parsed.selectedVersion),
+      evidence: "persisted",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Observe configured candidate evidence without launching Codex, creating a
+ * probe home, or persisting a replacement selection.
+ */
+export function observeCodexRuntimeCandidateReadOnly(
+  deps: CodexCliInstallProvenanceDeps = {},
+): ReadOnlyCodexRuntimeCandidate | null {
+  const env = deps.env ?? process.env;
+  const configured = env.CODEX_CLI_PATH?.trim();
+  if (configured) {
+    return {
+      command: configured,
+      version: null,
+      evidence: "environment",
+    };
+  }
+  return readPersistedCandidate(deps);
+}
+
+function pathTools(platform: NodeJS.Platform): typeof posix | typeof win32 {
+  return platform === "win32" ? win32 : posix;
+}
+
+function isWindowsPlatform(platform: NodeJS.Platform): boolean {
+  return platform === "win32";
+}
+
+function isSafeLocalInspectionPath(
+  path: string,
+  deps: CodexCliInstallProvenanceDeps,
+): boolean {
+  const platform = deps.platform ?? process.platform;
+  return isLocalAbsoluteInspectionPath(path, platform);
+}
+
+function caseInsensitiveEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+  const entry = Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase());
+  return entry?.[1];
+}
+
+function resolveCandidateCommandPath(
+  command: string,
+  deps: CodexCliInstallProvenanceDeps,
+): string | null {
+  const platform = deps.platform ?? process.platform;
+  // Windows inspection returns before this resolver until the next slice can
+  // bind command resolution and wrapper reads to stable filesystem handles.
+  if (isWindowsPlatform(platform)) return null;
+  const exists = deps.exists ?? existsSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const stat = deps.stat ?? statSync;
+  const usable = (path: string): boolean => {
+    if (!isSafeLocalInspectionPath(path, deps)) return false;
+    try {
+      const entry = lstat(path);
+      if (!exists(path) || (!entry.isFile() && !entry.isSymbolicLink()) || !isSpawnableCodexCandidate(path, platform)) return false;
+      if (platform !== "win32") {
+        const target = stat(path);
+        if (!target.isFile() || (target.mode & 0o111) === 0) return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const env = deps.env ?? process.env;
+  const tools = pathTools(platform);
+  const explicit = tools.isAbsolute(command) || command.includes("/") || command.includes("\\");
+  if (explicit) return usable(command) ? command : null;
+  const pathValue = env.PATH ?? "";
+  const names = [command];
+  for (const entry of pathValue.split(tools.delimiter)) {
+    // Empty and relative entries name the current working directory. Either can
+    // shadow a later absolute hit and therefore makes the candidate path unknown.
+    if (!entry || !isSafeLocalInspectionPath(entry, deps)) return null;
+    for (const name of names) {
+      const candidate = tools.join(entry, name);
+      if (usable(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function canonicalize(path: string, deps: CodexCliInstallProvenanceDeps): string | null {
+  if (!isSafeLocalInspectionPath(path, deps)) return null;
+  try {
+    const canonical = (deps.realpath ?? realpathSync.native)(path);
+    return isSafeLocalInspectionPath(canonical, deps) ? canonical : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizePath(path: string, platform: NodeJS.Platform): string {
+  const slashNormalized = platform === "win32" ? path.replace(/\\/g, "/") : path;
+  const normalized = platform !== "win32" && /^\/+$/u.test(slashNormalized)
+    ? "/"
+    : slashNormalized.replace(/\/+$/, "");
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function samePath(left: string, right: string, platform: NodeJS.Platform): boolean {
+  return normalizePath(left, platform) === normalizePath(right, platform);
+}
+
+export function isAppBundledCodexPath(path: string, platform: NodeJS.Platform): boolean {
+  const normalized = normalizePath(path, platform);
+  if (platform === "win32") {
+    return normalized.includes("/windowsapps/")
+      || normalized.includes("/microsoft/windowsapps/")
+      || normalized.includes("/packages/openai.codex_");
+  }
+  if (platform === "darwin") return /[.]app\/contents\//i.test(normalized);
+  return normalized.startsWith("/snap/") || normalized.includes("/flatpak/app/");
+}
+
+/** Updater ownership is intentionally broader than shim-repair refusal. */
+export function isCodexCliUpdateVersionManagerPath(
+  path: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  const normalized = (platform === "win32"
+    ? win32.normalize(path).replace(/\\/g, "/")
+    : posix.normalize(path)).toLowerCase();
+  if (isVersionManagerOwnedCodexPath(normalized, platform)) return true;
+  return normalized.includes("/.nvm/")
+    || normalized.includes("/nvm/versions/")
+    || /\/nvm\/v?\d+(?:[.]\d+){1,2}(?:\/|$)/.test(normalized)
+    || normalized.includes("/.proto/")
+    || normalized.includes("/proto/tools/")
+    || normalized.includes("/.nodenv/")
+    || normalized.includes("/nodenv/versions/")
+    || normalized.includes("/.nvs/")
+    || normalized.includes("/nvs/node/")
+    || normalized.includes("/.fnm/")
+    || normalized.includes("/fnm/node-versions/")
+    || normalized.includes("/fnm_multishells/")
+    || (platform === "win32" && (
+      normalized.includes("/scoop/apps/")
+      || normalized.includes("/scoop/shims/")
+    ));
+}
+
+function configuredVersionManagerRoots(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  deps: CodexCliInstallProvenanceDeps,
+): readonly string[] {
+  const roots: string[] = [];
+  for (const name of CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS) {
+    const raw = platform === "win32" ? caseInsensitiveEnv(env, name) : env[name];
+    if (!raw || !isLocalAbsoluteInspectionPath(raw, platform)) continue;
+    // Windows roots are advisory lexical labels only in this first slice. Do
+    // not resolve or open them until the handle-bound Windows layer exists.
+    if (platform === "win32") {
+      roots.push(normalizePath(win32.normalize(raw), platform));
+      continue;
+    }
+    const canonical = isSafeLocalInspectionPath(raw, deps) ? canonicalize(raw, deps) : null;
+    if (canonical) roots.push(normalizePath(canonical, platform));
+  }
+  return Object.freeze([...new Set(roots)]);
+}
+
+function isWithinConfiguredVersionManagerRoot(path: string, roots: readonly string[], platform: NodeJS.Platform): boolean {
+  const candidate = normalizePath(path, platform);
+  return roots.some(root => {
+    const filesystemRoot = root === "/" || (platform === "win32" && /^[a-z]:$/i.test(root));
+    return candidate === root || (!filesystemRoot && candidate.startsWith(`${root}/`));
+  });
+}
+
+function readBoundedFile(
+  path: string,
+  maxBytes: number,
+  deps: CodexCliInstallProvenanceDeps,
+): Buffer | null {
+  if (!isSafeLocalInspectionPath(path, deps)) return null;
+  // Production inspection accepts only a direct regular file. This prevents a
+  // persisted-state or manifest symlink from silently redirecting a nominally
+  // local check. Virtual filesystem tests may omit lstat and retain their
+  // injected stat/read behavior.
+  const inspectLexical = deps.lstat
+    ?? (deps.stat === undefined && deps.readFile === undefined ? lstatSync : null);
+  let lexicalBefore: ReturnType<typeof lstatSync> | null = null;
+  if (inspectLexical) {
+    try {
+      lexicalBefore = inspectLexical(path);
+      if (lexicalBefore.isSymbolicLink() || !lexicalBefore.isFile()) return null;
+    } catch {
+      return null;
+    }
+  }
+  const useInjectedReader = deps.boundedFileReadMode === "injected-test";
+  if (!useInjectedReader) {
+    let fd: number | null = null;
+    try {
+      const flags = process.platform === "win32"
+        ? fsConstants.O_RDONLY
+        : fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
+      fd = openSync(path, flags);
+      const before = fstatSync(fd);
+      if (!before.isFile() || before.size > maxBytes) return null;
+      const bytes = Buffer.allocUnsafe(before.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+        if (count <= 0) return null;
+        offset += count;
+      }
+      const extra = Buffer.allocUnsafe(1);
+      if (readSync(fd, extra, 0, 1, offset) !== 0) return null;
+      const after = fstatSync(fd);
+      const lexicalAfter = inspectLexical ? inspectLexical(path) : null;
+      if (lexicalAfter?.isSymbolicLink()) return null;
+      if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+        || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+        || (lexicalBefore !== null && (lexicalAfter === null || lexicalAfter.isSymbolicLink()
+          || lexicalBefore.dev !== before.dev || lexicalBefore.ino !== before.ino
+          || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino
+          || lexicalAfter.size !== after.size || lexicalAfter.mtimeMs !== after.mtimeMs
+          || lexicalAfter.ctimeMs !== after.ctimeMs))) return null;
+      return bytes;
+    } catch {
+      return null;
+    } finally {
+      if (fd !== null) closeSync(fd);
+    }
+  }
+  if (!deps.stat || !deps.readFile) return null;
+  const stat = deps.stat;
+  const read = deps.readFile;
+  try {
+    const before = stat(path);
+    if (!before.isFile() || before.size > maxBytes) return null;
+    const bytes = read(path);
+    const after = stat(path);
+    const lexicalAfter = inspectLexical ? inspectLexical(path) : null;
+    if (
+      bytes.byteLength !== before.size
+      || before.dev !== after.dev
+      || before.ino !== after.ino
+      || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs
+      || (lexicalBefore !== null && (lexicalAfter === null || lexicalAfter.isSymbolicLink()
+        || lexicalBefore.dev !== before.dev || lexicalBefore.ino !== before.ino
+        || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino))
+    ) return null;
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+
+function manifestCandidates(
+  logicalPath: string,
+  canonicalPath: string,
+  platform: NodeJS.Platform,
+): string[] {
+  const tools = pathTools(platform);
+  const candidates: string[] = [];
+  let cursor = tools.dirname(canonicalPath);
+  for (let depth = 0; depth < MAX_MANIFEST_ANCESTORS; depth += 1) {
+    candidates.push(tools.join(cursor, "package.json"));
+    const parent = tools.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  const binDir = tools.dirname(logicalPath);
+  if (platform === "win32") {
+    candidates.push(tools.join(binDir, "node_modules", "@openai", "codex", "package.json"));
+  } else {
+    const prefix = tools.dirname(binDir);
+    candidates.push(tools.join(prefix, "lib", "node_modules", "@openai", "codex", "package.json"));
+    candidates.push(tools.join(prefix, "node_modules", "@openai", "codex", "package.json"));
+  }
+  return [...new Set(candidates)];
+}
+
+function manifestBinPath(bin: unknown): string | null {
+  const raw = typeof bin === "string"
+    ? bin
+    : bin && typeof bin === "object" && !Array.isArray(bin)
+      ? (bin as Record<string, unknown>).codex
+      : null;
+  if (typeof raw !== "string") return null;
+  const normalized = raw.replace(/\\/g, "/").replace(/^\.\//, "");
+  return normalized === "bin/codex.js" ? normalized : null;
+}
+
+function findCodexPackageManifest(
+  logicalPath: string,
+  canonicalPath: string,
+  deps: CodexCliInstallProvenanceDeps,
+): PackageManifestEvidence | null {
+  const platform = deps.platform ?? process.platform;
+  for (const candidate of manifestCandidates(logicalPath, canonicalPath, platform)) {
+    const bytes = readBoundedFile(candidate, MAX_MANIFEST_BYTES, deps);
+    if (!bytes) continue;
+    try {
+      const value = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
+      const version = validatedVersion(typeof value.version === "string" ? value.version : null);
+      if (value.name !== CODEX_PACKAGE || !version) continue;
+      const binPath = manifestBinPath(value.bin);
+      if (!binPath) continue;
+      const root = canonicalize(pathTools(platform).dirname(candidate), deps);
+      const path = canonicalize(candidate, deps);
+      if (!root || !path) continue;
+      return {
+        path,
+        root,
+        binPath,
+        version,
+        digest: sha256("codex-cli-package-manifest-v1", bytes),
+      };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function launcherIsLinkedToManifest(
+  canonicalOwnershipPath: string,
+  manifest: PackageManifestEvidence,
+  deps: CodexCliInstallProvenanceDeps,
+): boolean {
+  const platform = deps.platform ?? process.platform;
+  const tools = pathTools(platform);
+  const entrypoint = canonicalize(tools.join(manifest.root, ...manifest.binPath.split("/")), deps);
+  if (!entrypoint) return false;
+  const normalizedRoot = normalizePath(manifest.root, platform);
+  const normalizedEntrypoint = normalizePath(entrypoint, platform);
+  if (!normalizedEntrypoint.startsWith(`${normalizedRoot}/`)) return false;
+  if (samePath(canonicalOwnershipPath, entrypoint, platform)) return true;
+  return false;
+}
+
+function isProvenGlobalNpmLayout(
+  launcherPath: string,
+  packageRoot: string,
+  platform: NodeJS.Platform,
+  deps: CodexCliInstallProvenanceDeps,
+): boolean {
+  const tools = pathTools(platform);
+  const launcherName = tools.basename(launcherPath).toLowerCase();
+  if (launcherName !== (platform === "win32" ? "codex.cmd" : "codex")) return false;
+  const root = normalizePath(packageRoot, platform);
+  // Keep the POSIX launcher itself lexical because npm commonly installs it as
+  // a symlink into the package. Canonicalize only its parent so a symlinked or
+  // case-aliased npm prefix is compared against the canonical manifest root.
+  const launcherParent = tools.dirname(launcherPath);
+  const canonicalLauncherParent = platform === "win32"
+    ? launcherParent
+    : canonicalize(launcherParent, deps);
+  if (!canonicalLauncherParent) return false;
+  const launcherDir = normalizePath(canonicalLauncherParent, platform);
+  const suffix = "/node_modules/@openai/codex";
+  if (!root.endsWith(suffix)) return false;
+  const beforeNodeModules = root.slice(0, -suffix.length);
+  if (platform === "win32") return launcherDir === beforeNodeModules;
+  if (!beforeNodeModules.endsWith("/lib")) return false;
+  const prefix = beforeNodeModules.slice(0, -"/lib".length);
+  return launcherDir === `${prefix}/bin`;
+}
+
+function shimReport(shim: CodexShimBackingForCommand): CodexCliInstallReport["shim"] {
+  if (shim.status === "matched") {
+    return Object.freeze({ status: "matched" as const, backingKind: shim.backingKind });
+  }
+  if (shim.status === "unknown") {
+    return Object.freeze({ status: "unknown" as const, backingKind: null });
+  }
+  return Object.freeze({ status: "not-tracked" as const, backingKind: null });
+}
+
+/** Inspect ownership of one configured Codex CLI candidate, without mutation. */
+export async function inspectCodexCliInstall(
+  deps: CodexCliInstallProvenanceDeps = {},
+): Promise<CodexCliInstallReport> {
+  const platform = deps.platform ?? process.platform;
+  const candidate = observeCodexRuntimeCandidateReadOnly(deps);
+  if (!candidate) {
+    return isWindowsPlatform(platform)
+      ? unknownWindowsReport("candidate_unavailable")
+      : unknownReport("candidate_unavailable");
+  }
+
+  const env = deps.env ?? process.env;
+  if (platform === "win32") {
+    // This first slice never opens a candidate-controlled Windows pathname.
+    // A boolean precheck followed by lstat/realpath/open is raceable when an
+    // ancestor can be replaced with a remote reparse point. Preserve only
+    // lexical, report-only classifications until a handle-bound inspector is
+    // introduced; every result remains unattested and unmanaged.
+    const lexicalCandidatePath = win32.isAbsolute(candidate.command)
+      && isLocalAbsoluteInspectionPath(candidate.command, platform)
+      ? win32.normalize(candidate.command)
+      : null;
+    if (!lexicalCandidatePath) {
+      return unknownWindowsReport("candidate_path_unavailable", candidate);
+    }
+    const managerRoots = configuredVersionManagerRoots(env, platform, deps);
+    const appBundle = isAppBundledCodexPath(lexicalCandidatePath, platform);
+    const versionManager = isCodexCliUpdateVersionManagerPath(lexicalCandidatePath, platform)
+      || isWithinConfiguredVersionManagerRoot(lexicalCandidatePath, managerRoots, platform);
+    if (appBundle || versionManager) {
+      return freezeReport({
+        schemaVersion: 1,
+        candidateAvailable: true,
+        candidateVersion: candidate.version,
+        candidateSource: candidate.evidence,
+        selectionAttested: false,
+        versionEvidence: Object.freeze({
+          kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
+        }),
+        provenance: appBundle ? "app-bundle" : "version-manager",
+        managed: false,
+        reason: appBundle ? "app_bundle" : "version_manager_owned",
+        location: publicExecutableLocation(lexicalCandidatePath, platform),
+        packageVersion: null,
+        shim: Object.freeze({ status: "unknown", backingKind: null }),
+        evidence: Object.freeze([appBundle ? "app_bundle_path" : "version_manager_path"]),
+      });
+    }
+    return unknownWindowsReport("windows_inspection_deferred", candidate, {
+      location: publicExecutableLocation(lexicalCandidatePath, platform),
+    });
+  }
+  const configDir = deps.configDir ?? getConfigDir();
+  if (!isSafeLocalInspectionPath(configDir, deps)) {
+    return unknownReport("shim_state_unknown", candidate);
+  }
+  const candidatePath = resolveCandidateCommandPath(candidate.command, deps);
+  if (!candidatePath) {
+    return unknownReport("candidate_path_unavailable", candidate);
+  }
+  const canonicalCandidatePath = canonicalize(candidatePath, deps);
+  if (!canonicalCandidatePath) {
+    return unknownReport("candidate_path_unsafe", candidate);
+  }
+  const inspectShim = deps.inspectShim ?? inspectCodexShimBackingForCommand;
+  const shim = inspectShim(candidatePath, platform, configDir);
+  if (shim.status === "unknown") {
+    return freezeReport({
+      ...unknownReport("shim_state_unknown", candidate, {
+        location: publicExecutableLocation(canonicalCandidatePath, platform),
+      }),
+      shim: shimReport(shim),
+    });
+  }
+  if (shim.status === "matched") {
+    return freezeReport({
+      ...unknownReport("shim_update_deferred", candidate, {
+        location: publicExecutableLocation(canonicalCandidatePath, platform),
+      }),
+      provenance: "standalone-unverified",
+      shim: shimReport(shim),
+      evidence: Object.freeze(["canonical_path", "shim_backing"] as const),
+    });
+  }
+
+  const ownershipPath = candidatePath;
+  const canonicalOwnershipPath = canonicalize(ownershipPath, deps);
+  if (!canonicalOwnershipPath) {
+    return unknownReport("candidate_path_unsafe", candidate);
+  }
+  const location = publicExecutableLocation(canonicalCandidatePath, platform);
+  const canonicalPathSet = [canonicalCandidatePath, canonicalOwnershipPath];
+  if (canonicalPathSet.some(path => isAppBundledCodexPath(path, platform))) {
+    return freezeReport({
+      schemaVersion: 1,
+      candidateAvailable: true,
+      candidateVersion: candidate.version,
+      candidateSource: candidate.evidence,
+      selectionAttested: false,
+      versionEvidence: Object.freeze({
+        kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
+      }),
+      provenance: "app-bundle",
+      managed: false,
+      reason: "app_bundle",
+      location,
+      packageVersion: null,
+      shim: shimReport(shim),
+      evidence: Object.freeze(["canonical_path", "app_bundle_path"]),
+    });
+  }
+  const configuredManagerRoots = configuredVersionManagerRoots(env, platform, deps);
+  if (canonicalPathSet.some(path => isCodexCliUpdateVersionManagerPath(path, platform)
+    || isWithinConfiguredVersionManagerRoot(path, configuredManagerRoots, platform))) {
+    return freezeReport({
+      schemaVersion: 1,
+      candidateAvailable: true,
+      candidateVersion: candidate.version,
+      candidateSource: candidate.evidence,
+      selectionAttested: false,
+      versionEvidence: Object.freeze({
+        kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
+      }),
+      provenance: "version-manager",
+      managed: false,
+      reason: "version_manager_owned",
+      location,
+      packageVersion: null,
+      shim: shimReport(shim),
+      evidence: Object.freeze(["canonical_path", "version_manager_path"]),
+    });
+  }
+  if (/codex[.]opencodex-real(?:[.](?:cmd|bat|exe))?$/i.test(pathTools(platform).basename(candidatePath))) {
+    return freezeReport({
+      ...unknownReport("shim_state_unknown", candidate, { location }),
+      shim: shimReport(shim),
+    });
+  }
+
+  const manifest = findCodexPackageManifest(ownershipPath, canonicalOwnershipPath, deps);
+  if (manifest) {
+    // POSIX npm launchers are commonly symlinks into the package, so their
+    // lexical prefix is the ownership evidence instead.
+    const global = isProvenGlobalNpmLayout(
+      ownershipPath,
+      manifest.root,
+      platform,
+      deps,
+    );
+    const linked = launcherIsLinkedToManifest(
+      canonicalOwnershipPath,
+      manifest,
+      deps,
+    );
+    const manifestOwned = global && linked;
+    const versionMatches = candidate.version === null || candidate.version === manifest.version;
+    const reason: CodexCliInstallReason = !global || !linked
+      ? "npm_global_unverified"
+      : !versionMatches ? "version_mismatch" : "selection_unattested";
+    return freezeReport({
+      schemaVersion: 1,
+      candidateAvailable: true,
+      candidateVersion: candidate.version,
+      candidateSource: candidate.evidence,
+      selectionAttested: false,
+      versionEvidence: Object.freeze({
+        kind: manifestOwned && candidate.version !== null && versionMatches
+          ? "package-manifest" as const
+          : candidate.version !== null ? "advisory-runtime" as const : "unavailable" as const,
+      }),
+      provenance: manifestOwned ? "npm-global" : "standalone-unverified",
+      managed: false,
+      reason,
+      location,
+      packageVersion: manifest.version,
+      shim: shimReport(shim),
+      evidence: Object.freeze<CodexCliInstallEvidence[]>([
+        "canonical_path", "package_manifest", "package_manifest_digest",
+        ...(manifestOwned ? ["global_npm_layout" as const] : []),
+      ]),
+    });
+  }
+
+  const stat = deps.stat ?? statSync;
+  if (!isSafeLocalInspectionPath(canonicalOwnershipPath, deps)) {
+    return unknownReport("candidate_path_unsafe", candidate);
+  }
+  try {
+    if (!stat(canonicalOwnershipPath).isFile()) {
+      return unknownReport("candidate_path_unsafe", candidate);
+    }
+  } catch {
+    return unknownReport("inspection_failed", candidate);
+  }
+  return freezeReport({
+    schemaVersion: 1,
+    candidateAvailable: true,
+    candidateVersion: candidate.version,
+    candidateSource: candidate.evidence,
+    selectionAttested: false,
+    versionEvidence: Object.freeze({
+      kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
+    }),
+    provenance: "standalone-unverified",
+    managed: false,
+    reason: "unverified_standalone",
+    location,
+    packageVersion: null,
+    shim: shimReport(shim),
+    evidence: Object.freeze(["canonical_path"]),
+  });
+}