@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/codex/features.ts

@@ -30,12 +30,14 @@
  * catalog.ts:40-54) so tests can point fixtures via env or the explicit
  * `configPath` parameter without fighting the module-load-time const in paths.ts.
  */
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
 import { realpathSync } from "node:fs";
-import { AtomicWriteResidualTempError, AtomicWriteSecretResidualError, atomicWriteFile, expandUserPath } from "../config";
+import { AtomicWriteResidualTempError, AtomicWriteSecretResidualError, atomicWriteFile, expandUserPath, getConfigDir } from "../config";
 import { forgetEphemeralSecretPath } from "../lib/windows-secret-acl";
 import { CODEX_CONFIG_PATH } from "./paths";
+import { resolveAndPersistCodexRuntime } from "./runtime";
 
 /** Upstream codex-rs feature key: allow `request_user_input` in Default mode. */
 export const DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY = "default_mode_request_user_input";
@@ -451,16 +453,46 @@ function encodeTomlBasicString(value: string): string {
  */
 function decodeTomlStringToken(token: string): string | null {
   if (token.length < 2) return null;
+  // Multi-line literal string: `'''...'''` verbatim (backslashes not special).
+  if (token.startsWith("'''")) {
+    return token.endsWith("'''") && token.length >= 6
+      ? normalizeTomlMultilineBody(token.slice(3, -3))
+      : null;
+  }
+  // Multi-line basic string: `"""..."""` with escapes.
+  if (token.startsWith('"""')) {
+    if (!token.endsWith('"""') || token.length < 6) return null;
+    return decodeBasicStringBody(normalizeTomlMultilineBody(token.slice(3, -3)), true);
+  }
   if (token.startsWith("'")) {
     return token.endsWith("'") ? token.slice(1, -1) : null;
   }
   if (!token.startsWith('"') || !token.endsWith('"')) return null;
-  const body = token.slice(1, -1);
+  return decodeBasicStringBody(token.slice(1, -1));
+}
+
+/** Apply TOML's multi-line newline rules before string-body decoding. */
+function normalizeTomlMultilineBody(body: string): string {
+  const normalized = body.replace(/\r\n/g, "\n");
+  return normalized.startsWith("\n") ? normalized.slice(1) : normalized;
+}
+
+/** Unescape the body of a TOML basic string (single- or multi-line). */
+function decodeBasicStringBody(body: string, multiline = false): string | null {
   let out = "";
   for (let i = 0; i < body.length; i++) {
     const ch = body[i];
     if (ch !== "\\") { out += ch; continue; }
     const esc = body[++i];
+    if (multiline) {
+      let newline = i;
+      while (body[newline] === " " || body[newline] === "\t") newline++;
+      if (body[newline] === "\n") {
+        i = newline;
+        while (body[i + 1] === " " || body[i + 1] === "\t" || body[i + 1] === "\n") i++;
+        continue;
+      }
+    }
     switch (esc) {
       case "\\": out += "\\"; break;
       case '"': out += '"'; break;
@@ -499,6 +531,28 @@ function scanTomlValueEnd(text: string, start: number): number {
   while (i < text.length && (text[i] === " " || text[i] === "\t")) i++;
   const first = text[i];
   if (first === '"') {
+    // Multi-line basic string: `"""..."""`. The closing delimiter is a triple
+    // quote; a single or double quote inside the body does not end the token.
+    if (text[i + 1] === '"' && text[i + 2] === '"') {
+      i += 3;
+      while (i < text.length) {
+        if (text[i] === "\\") { i += 2; continue; }
+        if (text[i] === '"' && text[i + 1] === '"' && text[i + 2] === '"') {
+          // TOML permits up to two quotes immediately inside the closing
+          // delimiter, so a 4- or 5-quote run means the extra one or two
+          // quotes are part of the value. Consume the full valid run and
+          // keep the surplus quotes in the body.
+          let end = i + 3;
+          if (text[end] === '"') {
+            end++;
+            if (text[end] === '"') end++;
+          }
+          return end;
+        }
+        i++;
+      }
+      return text.length;
+    }
     i++;
     while (i < text.length) {
       if (text[i] === "\\") { i += 2; continue; }
@@ -508,6 +562,24 @@ function scanTomlValueEnd(text: string, start: number): number {
     return text.length;
   }
   if (first === "'") {
+    // Multi-line literal string: `'''...'''`.
+    if (text[i + 1] === "'" && text[i + 2] === "'") {
+      i += 3;
+      while (i < text.length) {
+        if (text[i] === "'" && text[i + 1] === "'" && text[i + 2] === "'") {
+          // Same as multi-line basic: up to two surplus single quotes can
+          // precede the closing delimiter and remain part of the value.
+          let end = i + 3;
+          if (text[end] === "'") {
+            end++;
+            if (text[end] === "'") end++;
+          }
+          return end;
+        }
+        i++;
+      }
+      return text.length;
+    }
     const close = text.indexOf("'", i + 1);
     return close === -1 ? text.length : close + 1;
   }
@@ -546,6 +618,40 @@ function findInlineTableEnd(text: string, openIdx: number): number {
 
 interface InlineEntry { keyStart: number; valueStart: number; valueEnd: number }
 
+/** Locate a top-level assignment while skipping complete (possibly multiline) values. */
+function findTomlAssignment(text: string, key: string): InlineEntry | null {
+  let lineStart = 0;
+  while (lineStart < text.length) {
+    let i = lineStart;
+    while (text[i] === " " || text[i] === "\t") i++;
+    const keyStart = i;
+    let keyText = "";
+    if (text[i] === '"' || text[i] === "'") {
+      const keyEnd = scanTomlValueEnd(text, i);
+      keyText = decodeTomlStringToken(text.slice(i, keyEnd)) ?? "";
+      i = keyEnd;
+    } else {
+      const match = /^[A-Za-z0-9_-]+/.exec(text.slice(i));
+      if (match) {
+        keyText = match[0];
+        i += match[0].length;
+      }
+    }
+    while (text[i] === " " || text[i] === "\t") i++;
+    if (keyText && text[i] === "=") {
+      const valueStart = i + 1;
+      const valueEnd = scanTomlValueEnd(text, valueStart);
+      if (keyText === key) return { keyStart, valueStart, valueEnd };
+      const nextLine = text.indexOf("\n", valueEnd);
+      lineStart = nextLine === -1 ? text.length : nextLine + 1;
+      continue;
+    }
+    const nextLine = text.indexOf("\n", lineStart);
+    lineStart = nextLine === -1 ? text.length : nextLine + 1;
+  }
+  return null;
+}
+
 /**
  * Locate `key = value` inside the inline-table body spanning [bodyStart, bodyEnd)
  * (exclusive of the braces), string-aware on both keys and values, or null.
@@ -579,6 +685,24 @@ function findInlineEntry(text: string, bodyStart: number, bodyEnd: number, key:
   return null;
 }
 
+/** Whether a TOML assignment's value starts with a triple-quoted string. */
+function isMultilineTomlString(text: string, valueStart: number): boolean {
+  let start = valueStart;
+  while (text[start] === " " || text[start] === "\t") start++;
+  return text.startsWith('"""', start) || text.startsWith("'''", start);
+}
+
+/** Whether one field in a supported inline `multi_agent_v2` table is triple-quoted. */
+function hasInlineMultilineTomlString(text: string, assignment: InlineEntry, key: string): boolean {
+  let openIdx = assignment.valueStart;
+  while (text[openIdx] === " " || text[openIdx] === "\t") openIdx++;
+  if (text[openIdx] !== "{") return false;
+  const closeIdx = findInlineTableEnd(text, openIdx);
+  if (closeIdx === -1) return false;
+  const entry = findInlineEntry(text, openIdx + 1, closeIdx, key);
+  return entry !== null && isMultilineTomlString(text, entry.valueStart);
+}
+
 /**
  * Set or remove one scalar key inside a top-level TOML table, preserving every
  * other line byte-for-byte — including the existing value's trailing comment,
@@ -602,22 +726,19 @@ function editScalarInTable(content: string, table: string, key: string, encoded:
   for (let i = headerIdx + 1; i < lines.length; i++) {
     if (/^\s*\[/.test(lines[i])) { end = i; break; }
   }
-  const keyRe = new RegExp(`^(\\s*)${key}\\s*=\\s*`);
   for (let i = headerIdx + 1; i < end; i++) {
-    const m = lines[i].match(keyRe);
-    if (!m) continue;
+    const entry = findTomlAssignment(lines[i], key);
+    if (!entry) continue;
     // The existing value may itself contain '#', so scan the value token
     // string-aware instead of splitting on '#'.
     const line = lines[i];
-    const valueStart = m[0].length;
-    const valueEnd = scanTomlValueEnd(line, valueStart);
-    const trailing = line.slice(valueEnd);
+    const trailing = line.slice(entry.valueEnd);
     if (encoded === null) {
       lines.splice(i, 1);
       return applyEol(lines.join("\n"), eol);
     }
-    if (line.slice(valueStart, valueEnd).trim() === encoded) return content;
-    lines[i] = `${m[1]}${key} = ${encoded}${trailing}`;
+    if (line.slice(entry.valueStart, entry.valueEnd).trim() === encoded) return content;
+    lines[i] = `${line.slice(0, entry.keyStart)}${key} = ${encoded}${trailing}`;
     return applyEol(lines.join("\n"), eol);
   }
   if (encoded === null) return content;
@@ -669,31 +790,95 @@ export function setAgentsMaxDepth(value: number | null, configPath?: string): Co
  * Reads both the dedicated-table and inline forms; dedicated wins, mirroring
  * `getMaxConcurrentThreads` precedence.
  */
-export function getSubagentDeveloperInstructions(configPath?: string): string | null {
+/**
+ * Read a string-valued `features.multi_agent_v2` scalar (dedicated table or inline
+ * form; dedicated wins, mirroring `getMaxConcurrentThreads` precedence). Returns
+ * `null` when the key is absent or the config is unreadable. A present empty string
+ * round-trips faithfully — some upstream keys treat `""` and `null` differently.
+ */
+function getV2StringField(key: string, configPath?: string): string | null {
   const content = readConfigText(configPath);
   if (content === null) return null;
-  const table = tomlTableBody(content, "features.multi_agent_v2");
+  const table = tomlTableBodyForStringFields(content, "features.multi_agent_v2");
   if (table !== null) {
-    const m = table.match(/^\s*subagent_developer_instructions\s*=\s*/m);
-    if (m) {
-      const valueStart = m.index! + m[0].length;
-      const token = table.slice(valueStart, scanTomlValueEnd(table, valueStart)).trim();
+    const entry = findTomlAssignment(table, key);
+    if (entry) {
+      const token = table.slice(entry.valueStart, entry.valueEnd).trim();
       return decodeTomlStringToken(token);
     }
     return null;
   }
-  const features = tomlTableBody(content, "features");
+  const features = tomlTableBodyForStringFields(content, "features");
   if (features === null) return null;
-  const m = features.match(/multi_agent_v2\s*=\s*\{/);
-  if (!m) return null;
-  const openIdx = m.index! + m[0].length - 1;
+  const v2Entry = findTomlAssignment(features, "multi_agent_v2");
+  if (!v2Entry) return null;
+  let openIdx = v2Entry.valueStart;
+  while (features[openIdx] === " " || features[openIdx] === "\t") openIdx++;
+  if (features[openIdx] !== "{") return null;
   const closeIdx = findInlineTableEnd(features, openIdx);
   if (closeIdx === -1) return null;
-  const entry = findInlineEntry(features, openIdx + 1, closeIdx, "subagent_developer_instructions");
+  const entry = findInlineEntry(features, openIdx + 1, closeIdx, key);
   if (!entry) return null;
   return decodeTomlStringToken(features.slice(entry.valueStart, entry.valueEnd).trim());
 }
 
+/**
+ * A table body scanner that skips complete TOML values before recognizing the
+ * next header. Unlike the legacy line scanner, bracket-shaped prose inside a
+ * multi-line string cannot truncate the table.
+ */
+function tomlTableBodyForStringFields(content: string, header: string): string | null {
+  const escaped = escapeRegExp(header);
+  const match = new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`, "m").exec(content);
+  if (!match) return null;
+  const newline = content.indexOf("\n", match.index + match[0].length);
+  if (newline === -1) return "";
+  const bodyStart = newline + 1;
+  let lineStart = bodyStart;
+  while (lineStart < content.length) {
+    let cursor = lineStart;
+    while (content[cursor] === " " || content[cursor] === "\t") cursor++;
+    if (content[cursor] === "[") return content.slice(bodyStart, lineStart);
+    const lineEnd = content.indexOf("\n", cursor);
+    const boundedEnd = lineEnd === -1 ? content.length : lineEnd;
+    let keyEnd = cursor;
+    if (content[keyEnd] === '"' || content[keyEnd] === "'") {
+      keyEnd = scanTomlValueEnd(content, keyEnd);
+    } else {
+      const keyMatch = /^[A-Za-z0-9_.-]+/.exec(content.slice(keyEnd, boundedEnd));
+      if (keyMatch) keyEnd += keyMatch[0].length;
+    }
+    while (content[keyEnd] === " " || content[keyEnd] === "\t") keyEnd++;
+    if (content[keyEnd] === "=" && keyEnd < boundedEnd) {
+      const valueEnd = scanTomlValueEnd(content, keyEnd + 1);
+      const nextLine = content.indexOf("\n", valueEnd);
+      lineStart = nextLine === -1 ? content.length : nextLine + 1;
+    } else {
+      lineStart = lineEnd === -1 ? content.length : lineEnd + 1;
+    }
+  }
+  return content.slice(bodyStart);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Bare and quoted TOML forms of one known-safe key. */
+function tomlKeyPattern(key: string): string {
+  const escaped = escapeRegExp(key);
+  return `(?:${escaped}|"${escaped}"|'${escaped}')`;
+}
+
+export function getSubagentDeveloperInstructions(configPath?: string): string | null {
+  return getV2StringField("subagent_developer_instructions", configPath);
+}
+
+/** Current `features.multi_agent_v2.multi_agent_mode_hint_text`, or null when unset. */
+export function getMultiAgentModeHintText(configPath?: string): string | null {
+  return getV2StringField("multi_agent_mode_hint_text", configPath);
+}
+
 /**
  * Persist `features.multi_agent_v2.subagent_developer_instructions`, or remove the
  * key when `value` is null. Handles all three existing encodings: the dedicated
@@ -705,19 +890,49 @@ export function getSubagentDeveloperInstructions(configPath?: string): string |
  * carries `#[serde(deny_unknown_fields)]`, so a misspelling is not ignored — it is
  * a hard config-parse failure for the user's Codex.
  */
-export function setSubagentDeveloperInstructions(value: string | null, configPath?: string): ConfigEditResult {
+function setV2StringField(key: string, value: string | null, configPath?: string): ConfigEditResult {
   const path = configPath ?? activeCodexConfigPath();
   const content = readConfigText(path);
   if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
   const encoded = value === null ? null : encodeTomlBasicString(value);
 
-  if (tomlTableBody(content, "features.multi_agent_v2") !== null) {
-    const next = editScalarInTable(content, "features.multi_agent_v2", "subagent_developer_instructions", encoded);
+  // A parsed V2 object without one of the supported source forms came from
+  // dotted/quoted path segments. Appending a dedicated table would redefine it
+  // and make Codex reject the file, so fail closed without changing any bytes.
+  const parsedFeatures = parsedTomlTable(content, "features");
+  const parsedV2 = parsedFeatures === null ? null : plainTomlRecord(parsedFeatures.multi_agent_v2);
+  const dedicatedV2 = tomlTableBodyForStringFields(content, "features.multi_agent_v2") !== null;
+  const featuresBody = tomlTableBodyForStringFields(content, "features");
+  const featuresV2Entry = featuresBody === null ? null : findTomlAssignment(featuresBody, "multi_agent_v2");
+  const supportedFeaturesEntry = featuresV2Entry !== null;
+  if (parsedV2 !== null && !dedicatedV2 && !supportedFeaturesEntry) {
+    return { ok: false, error: "dotted or quoted multi_agent_v2 config is not supported for managed string fields" };
+  }
+
+  const dedicatedStringBody = tomlTableBodyForStringFields(content, "features.multi_agent_v2");
+  if (dedicatedStringBody !== null) {
+    // Multiline TOML strings ("""...""" / '''...''') span multiple lines and the
+    // single-line table editor cannot rewrite or remove them without corrupting
+    // the document. Scope this guard to the target V2 table so an unrelated
+    // table carrying the same key does not block an otherwise safe edit.
+    const dedicatedEntry = findTomlAssignment(dedicatedStringBody, key);
+    if (dedicatedEntry !== null && isMultilineTomlString(dedicatedStringBody, dedicatedEntry.valueStart)) {
+      return { ok: false, error: `multi-line TOML string for ${key} is not editable; convert it to a single-line string first` };
+    }
+    const legacyDedicatedBody = tomlTableBody(content, "features.multi_agent_v2") ?? "";
+    if (dedicatedEntry !== null && findTomlAssignment(legacyDedicatedBody, key) === null) {
+      return { ok: false, error: `cannot edit ${key} after a header-shaped multiline value safely` };
+    }
+    const next = editScalarInTable(content, "features.multi_agent_v2", key, encoded);
     if (next === content) return { ok: true, changed: false };
     atomicWriteFile(path, next);
     return { ok: true, changed: true };
   }
 
+  if (featuresBody !== null && featuresV2Entry !== null && hasInlineMultilineTomlString(featuresBody, featuresV2Entry, key)) {
+    return { ok: false, error: `multi-line TOML string for ${key} is not editable; convert it to a single-line string first` };
+  }
+
   const eol = dominantEol(content);
   const lines = content.split(/\r?\n/);
   const featuresHeader = lines.findIndex(l => /^\s*\[features\]\s*(?:#.*)?$/.test(l));
@@ -733,7 +948,7 @@ export function setSubagentDeveloperInstructions(value: string | null, configPat
         const openIdx = inlineMatch[0].length - 1;
         const closeIdx = findInlineTableEnd(line, openIdx);
         if (closeIdx === -1) return { ok: false, error: "malformed multi_agent_v2 inline table" };
-        const entry = findInlineEntry(line, openIdx + 1, closeIdx, "subagent_developer_instructions");
+        const entry = findInlineEntry(line, openIdx + 1, closeIdx, key);
         if (encoded === null) {
           if (!entry) return { ok: true, changed: false };
           let start = entry.keyStart;
@@ -760,8 +975,8 @@ export function setSubagentDeveloperInstructions(value: string | null, configPat
           while (insertPos > openIdx + 1 && line[insertPos - 1] === " ") insertPos--;
           const hasEntries = line.slice(openIdx + 1, insertPos).trim().length > 0;
           const insertion = hasEntries
-            ? `, subagent_developer_instructions = ${encoded} `
-            : ` subagent_developer_instructions = ${encoded} `;
+            ? `, ${key} = ${encoded} `
+            : ` ${key} = ${encoded} `;
           lines[i] = line.slice(0, insertPos) + insertion + line.slice(closeIdx);
         }
         atomicWriteFile(path, applyEol(lines.join("\n"), eol));
@@ -770,21 +985,212 @@ export function setSubagentDeveloperInstructions(value: string | null, configPat
       const boolMatch = line.match(/^(\s*)multi_agent_v2\s*=\s*(true|false)(\s*(?:#.*)?)$/);
       if (boolMatch) {
         if (encoded === null) return { ok: true, changed: false };
-        lines[i] = `${boolMatch[1]}multi_agent_v2 = { enabled = ${boolMatch[2]}, subagent_developer_instructions = ${encoded} }${boolMatch[3]}`;
+        lines[i] = `${boolMatch[1]}multi_agent_v2 = { enabled = ${boolMatch[2]}, ${key} = ${encoded} }${boolMatch[3]}`;
         atomicWriteFile(path, applyEol(lines.join("\n"), eol));
         return { ok: true, changed: true };
       }
     }
+    if (featuresV2Entry !== null) {
+      return { ok: false, error: "multi_agent_v2 inside a multiline [features] table is not editable safely" };
+    }
   }
 
   if (encoded === null) return { ok: true, changed: false };
   const suffix = content.endsWith("\n") || content.length === 0 ? "" : eol;
   const separator = content.length > 0 && !content.endsWith(`${eol}${eol}`) ? eol : "";
-  const tableText = `[features.multi_agent_v2]${eol}subagent_developer_instructions = ${encoded}${eol}`;
+  const tableText = `[features.multi_agent_v2]${eol}${key} = ${encoded}${eol}`;
   atomicWriteFile(path, `${content}${suffix}${separator}${tableText}`);
   return { ok: true, changed: true };
 }
 
+export function setSubagentDeveloperInstructions(value: string | null, configPath?: string): ConfigEditResult {
+  return setV2StringField("subagent_developer_instructions", value, configPath);
+}
+
+export const MODE_HINT_UNSUPPORTED_ERROR =
+  "installed Codex does not support multi_agent_mode_hint_text; update Codex first";
+
+/**
+ * Persist `features.multi_agent_v2.multi_agent_mode_hint_text`, or remove the key
+ * when `value` is null. Same encoding coverage and upstream-name discipline as
+ * `setSubagentDeveloperInstructions`; the upstream struct rejects unknown fields,
+ * so the key spelling must match codex-rs exactly.
+ */
+export function setMultiAgentModeHintText(value: string | null, configPath?: string): ConfigEditResult {
+  // The upstream `multi_agent_mode_hint_text` key is newer than the v2 config
+  // surface opencodex already manages; an older Codex build rejects the unknown
+  // member (`#[serde(deny_unknown_fields)]`) and fails to start. Probe the
+  // installed runtime binary for the key string and refuse the write when the
+  // binary provably lacks it. A probe that cannot run (missing binary,
+  // unreadable file) does not block: that is the test/hermetic path and the
+  // headless runtime fallback.
+  if (value !== null) {
+    const probe = probeCodexSupportsModeHint();
+    if (probe === false) {
+      return {
+        ok: false,
+        error: MODE_HINT_UNSUPPORTED_ERROR,
+      };
+    }
+  }
+  return setV2StringField("multi_agent_mode_hint_text", value, configPath);
+}
+
+const modeHintCapabilityCache = new Map<string, boolean | null>();
+
+/**
+ * True when the installed Codex runtime binary contains the
+ * `multi_agent_mode_hint_text` config key, false when it provably does not, and
+ * null when the probe could not run (missing binary, unreadable file).
+ */
+export function probeCodexSupportsModeHint(): boolean | null {
+  try {
+    const runtime = resolveAndPersistCodexRuntime({ env: process.env }).runtime;
+    const selectedPath = resolveSelectedCommandPath(runtime.command);
+    let selectedIdentity = selectedPath ?? "";
+    try { if (selectedPath) selectedIdentity = realpathSync(selectedPath); } catch { /* keep lexical path */ }
+    const candidates = codexNativeBinaryCandidates(runtime.command);
+    const binaryStatFingerprint = candidates.map(candidate => {
+      try {
+        const stat = statSync(candidate);
+        return `${candidate}\0${stat.dev}\0${stat.ino}\0${stat.size}\0${stat.mtimeMs}\0${stat.ctimeMs}`;
+      } catch {
+        return `${candidate}\0missing`;
+      }
+    }).join("\0");
+    const cacheKey = `${runtime.command}\0${runtime.version ?? ""}\0${selectedIdentity}\0${binaryStatFingerprint}`;
+    const cached = modeHintCapabilityCache.get(cacheKey);
+    if (cached !== undefined) return cached;
+    let sawBinary = false;
+    for (const candidate of candidates) {
+      try {
+        if (!existsSync(candidate)) continue;
+        const buf = readFileSync(candidate);
+        if (!isNativeExecutable(buf)) continue;
+        sawBinary = true;
+        if (buf.includes(Buffer.from("multi_agent_mode_hint_text", "utf8"))) {
+          modeHintCapabilityCache.set(cacheKey, true);
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+    // At least one real binary was inspected and none contained the key.
+    const result = sawBinary ? false : null;
+    modeHintCapabilityCache.set(cacheKey, result);
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+const CODEX_PLATFORM_PACKAGES = [
+  ["codex-darwin-arm64", "aarch64-apple-darwin", "codex"],
+  ["codex-darwin-x64", "x86_64-apple-darwin", "codex"],
+  ["codex-linux-x64", "x86_64-unknown-linux-musl", "codex"],
+  ["codex-linux-arm64", "aarch64-unknown-linux-musl", "codex"],
+  ["codex-win32-x64", "x86_64-pc-windows-msvc", "codex.exe"],
+  ["codex-win32-arm64", "aarch64-pc-windows-msvc", "codex.exe"],
+] as const;
+
+function isNativeExecutable(buf: Buffer): boolean {
+  if (buf.length < 4) return false;
+  if (buf[0] === 0x4d && buf[1] === 0x5a) return true; // PE/COFF
+  const magic = buf.readUInt32BE(0);
+  return magic === 0x7f454c46 // ELF
+    || magic === 0xfeedface || magic === 0xfeedfacf
+    || magic === 0xcefaedfe || magic === 0xcffaedfe
+    || magic === 0xcafebabe || magic === 0xbebafeca; // Mach-O/fat Mach-O
+}
+
+/**
+ * Candidate native codex binaries to probe. The resolved `command` may be the
+ * opencodex shim or the npm JS wrapper (`codex.opencodex-real`), neither of
+ * which embeds the Rust config schema. The real binary ships under the
+ * platform package's `vendor/<triple>/bin/codex`; also try adjacent wrappers.
+ */
+function codexNativeBinaryCandidates(command: string): string[] {
+  const out = new Set<string>();
+  const resolverBases = new Set<string>();
+  const selectedPath = resolveSelectedCommandPath(command);
+
+  const addSelectedTarget = (target: string) => {
+    try {
+      const real = realpathSync(target);
+      out.add(target);
+      out.add(real);
+      if (/[\\/]@openai[\\/]codex[\\/]bin[\\/]/.test(real)) resolverBases.add(real);
+    } catch {
+      // Missing backing paths cannot establish capability either way.
+    }
+  };
+
+  // Follow the resolved command to its real location. The opencodex shim and
+  // the npm JS wrapper resolve to `@openai/codex/bin/codex.js`; the native
+  // binary lives in the sibling platform package's vendor directory.
+  if (selectedPath) {
+    addSelectedTarget(selectedPath);
+    for (const target of selectedShimBackingPaths(selectedPath)) addSelectedTarget(target);
+  }
+
+  // npm's Windows wrappers are ordinary scripts. Resolve from both the global
+  // prefix layout and a project-local node_modules/.bin layout; createRequire
+  // then follows the selected installation's own dependency tree (including
+  // pnpm/nested optional dependencies) without consulting unrelated PATH bins.
+  const wrapperPath = selectedPath ?? command;
+  if (/\.(?:cmd|ps1)$/i.test(wrapperPath)) {
+    resolverBases.add(resolve(dirname(wrapperPath), "node_modules", "@openai", "codex", "bin", "codex.js"));
+    resolverBases.add(resolve(dirname(wrapperPath), "..", "@openai", "codex", "bin", "codex.js"));
+  }
+
+  for (const base of resolverBases) {
+    const requireFromSelected = createRequire(base);
+    for (const [pkg, triple, exe] of CODEX_PLATFORM_PACKAGES) {
+      try {
+        const manifest = requireFromSelected.resolve(`@openai/${pkg}/package.json`);
+        out.add(join(dirname(manifest), "vendor", triple, "bin", exe));
+      } catch {
+        // Optional platform packages for other targets are normally absent.
+      }
+    }
+  }
+  return [...out];
+}
+
+/** Backing paths tied to this exact OCX shim entry in codex-shim.json. */
+function selectedShimBackingPaths(commandPath: string): string[] {
+  try {
+    const state = JSON.parse(readFileSync(join(getConfigDir(), "codex-shim.json"), "utf8")) as {
+      wrapperPath?: unknown;
+      originalPath?: unknown;
+      backupPath?: unknown;
+      realPath?: unknown;
+      wrappers?: Array<Record<string, unknown>>;
+    };
+    const entries = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
+    const selected = resolve(commandPath);
+    for (const entry of entries) {
+      if (typeof entry.wrapperPath !== "string" || resolve(entry.wrapperPath) !== selected) continue;
+      return [entry.backupPath, entry.realPath, entry.originalPath]
+        .filter((value): value is string => typeof value === "string" && value.length > 0 && resolve(value) !== selected);
+    }
+  } catch {
+    // Not an OCX-owned shim, or no readable state.
+  }
+  return [];
+}
+
+/** Resolve only the selected bare command against PATH; never enumerate peers. */
+function resolveSelectedCommandPath(command: string): string | null {
+  if (command.includes("/") || command.includes("\\")) return existsSync(command) ? resolve(command) : null;
+  for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const candidate = join(dir, command);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 function editAgentsMaxThreads(value: number | null, configPath?: string, migratedComment?: string): ConfigEditResult {
   const path = configPath ?? activeCodexConfigPath();
   const content = readConfigText(path);

package/src/codex/history-job.ts

@@ -18,7 +18,6 @@
  */
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { join } from "node:path";
 
 import type {
   CodexHistoryWorkerOperation,
@@ -26,19 +25,15 @@ import type {
 } from "./history-worker";
 import { historyBackupPathFor } from "./history-provider";
 import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
-import { getCodexHome } from "./paths";
-
-/** Where Codex keeps its resume history, and the manifest that shadows it. */
-const STATE_DB_FILE = "state_5.sqlite";
+import { getCodexHome, resolveCodexStateDbPath } from "./paths";
 
 /**
  * Resolve the paths a history job needs, at CALL time.
  *
- * `history-provider.ts` resolves its equivalents at module load (`:16`, `:22`),
- * which is fine in one process and wrong for a Worker: the Worker does not
- * inherit them, so anything derived from those constants would address a
- * different home than the caller intended. Resolving here also means a test that
- * moves `CODEX_HOME` is honoured rather than ignored.
+ * The SQLite root can differ from CODEX_HOME and both environment/config inputs
+ * can change between invocations. The parent resolves one exact target and hands
+ * those canonical paths to the Worker rather than asking the Worker to infer a
+ * possibly different environment.
  */
 export function resolveCodexHistoryJobTarget(): {
   readonly canonicalCodexHome: string;
@@ -46,7 +41,7 @@ export function resolveCodexHistoryJobTarget(): {
   readonly canonicalBackupPath: string;
 } {
   const home = getCodexHome();
-  const stateDb = join(home, STATE_DB_FILE);
+  const stateDb = resolveCodexStateDbPath({ codexHome: home });
   return {
     canonicalCodexHome: home,
     canonicalStateDbPath: stateDb,