@yansigit/opencodex 2.31.0

package/src/codex/features.ts

@@ -0,0 +1,1566 @@
+/**
+ * features.ts — codex feature-flag view for $CODEX_HOME/config.toml.
+ *
+ * Scope boundary: this module mirrors only the flags opencodex has to READ
+ * directly from config.toml:
+ *   - `multi_agent_v2`, because opencodex migrates its concurrency value across
+ *     the v1/v2 boundary and exposes the multi-agent config surface;
+ *   - `default_mode_request_user_input` (Codex Auth page toggle), because the
+ *     management API needs a live reader for the flag it manages.
+ * Every other upstream feature flag is delegated to the native `codex features`
+ * command (see src/cli/v2.ts) and must not be hardcoded here.
+ *
+ * Upstream reshapes flags freely: in the 1f0566d3f..5a1097ed2 range alone,
+ * `code_mode_host` changed from a boolean to a table (it is Stage::Stable and
+ * default-enabled upstream), `enable_fanout` and `item_ids` were retired to
+ * Stage::Removed ("useless but kept for backward compatibility"), and several
+ * under-development flags were added. Delegation is what keeps opencodex out of
+ * that churn.
+ *
+ * Used by the catalog v2-gated-ultra policy (devlog/260709_v2_gated_ultra) and the
+ * `ocx v2` toggle surface. The FLAG itself is never written here — toggling goes
+ * through the official `codex features enable|disable` CLI (format-preserving).
+ * The one write this module owns is the numeric
+ * `features.multi_agent_v2.max_concurrent_threads_per_session` scalar
+ * (setMaxConcurrentThreads): the codex CLI has no persisted setter for nested
+ * feature config (`-c` is per-invocation only), so ocx does a scoped,
+ * EOL-preserving line edit — same practice as codex/inject.ts.
+ *
+ * CODEX_HOME is resolved at CALL time (activeCodexConfigPath pattern, mirrors
+ * 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, 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, 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";
+
+// EOL preservation, local copies of inject.ts dominantEol/applyEol: importing
+// inject here would close a module cycle (features -> inject -> catalog -> features).
+function dominantEol(content: string): "\r\n" | "\n" {
+  const crlf = (content.match(/\r\n/g) ?? []).length;
+  if (crlf === 0) return "\n";
+  const bareLf = (content.match(/\n/g) ?? []).length - crlf;
+  return crlf >= bareLf ? "\r\n" : "\n";
+}
+
+function applyEol(content: string, eol: "\r\n" | "\n"): string {
+  const normalized = content.replace(/\r\n/g, "\n");
+  return eol === "\n" ? normalized : normalized.replace(/\n/g, "\r\n");
+}
+
+function mergeTrailingComments(existing?: string, migrated?: string): string {
+  if (!existing) return migrated ?? "";
+  if (!migrated || existing.trim() === migrated.trim()) return existing;
+  const migratedText = migrated.replace(/^\s*#\s*/, "");
+  if (existing.replace(/^\s*#\s*/, "").split(";").map(part => part.trim()).includes(migratedText.trim())) return existing;
+  return `${existing}; ${migratedText}`;
+}
+
+export function activeCodexConfigPath(): string {
+  const raw = process.env.CODEX_HOME?.trim();
+  if (!raw) return CODEX_CONFIG_PATH;
+  const path = resolve(expandUserPath(raw));
+  try {
+    return join(realpathSync.native(path), "config.toml");
+  } catch {
+    return join(path, "config.toml");
+  }
+}
+
+function readConfigText(configPath?: string): string | null {
+  const path = configPath ?? activeCodexConfigPath();
+  try {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Body lines of a TOML table `[header]` up to (not including) the next table header.
+ *
+ * The implementation body is deliberately unchanged by #1295 — only this comment
+ * is new. The scanner is line-based and string-unaware, so it ends the table at
+ * the first line matching `/^\s*\[/` even inside a multi-line value. Twenty call
+ * sites in this file consume its output, most of them by matching a regex
+ * against the returned text, so widening that text changes what they match. An
+ * earlier attempt at #1295 made this scanner string-aware and thereby gave
+ * `getAgentsEnabled`, `getAgentsMaxDepth`, and `getMaxConcurrentThreads` three
+ * new wrong answers.
+ *
+ * The readers that matter for #1295 use a real TOML parse instead (see
+ * `parsedTomlTable`). This stays as the fallback for documents that do not
+ * parse, and as the reader for the remaining call sites until they are migrated
+ * the same way.
+ */
+function tomlTableBody(content: string, header: string): string | null {
+  const lines = content.split("\n");
+  const escaped = header.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const start = lines.findIndex(l => new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`).test(l));
+  if (start === -1) return null;
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex(l => /^\s*\[/.test(l));
+  return (end === -1 ? rest : rest.slice(0, end)).join("\n");
+}
+
+function tomlBoolInBody(body: string, key: string): boolean | null {
+  const m = body.match(new RegExp(`^\\s*${key}\\s*=\\s*(true|false)\\s*(?:#.*)?$`, "m"));
+  return m ? m[1] === "true" : null;
+}
+
+/**
+ * TRUE when the codex `multi_agent_v2` feature is enabled in config.toml.
+ * Recognizes both shipped forms (codex-rs features/src/tests.rs):
+ *   [features.multi_agent_v2]           [features]
+ *   enabled = true                      multi_agent_v2 = true
+ * plus the inline-table form `multi_agent_v2 = { enabled = true, ... }`.
+ * Missing file/key -> false (upstream default_enabled = false).
+ */
+export function isMultiAgentV2Enabled(configPath?: string): boolean {
+  const content = readConfigText(configPath);
+  return multiAgentV2EnabledFromConfigText(content);
+}
+
+/** Parse `multi_agent_v2` from caller-owned config.toml text without consulting disk. */
+export function multiAgentV2EnabledFromConfigText(content: string | null): boolean {
+  if (content === null) return false;
+
+  // Prefer a real parse. The hand-written table scanner below cannot distinguish
+  // an assignment from prose that looks like one — a `"""` value containing the
+  // line `enabled = true` reads as the key itself — and TOML has enough value
+  // shapes (multi-line arrays opening on the next line, escapes, comments) that
+  // each near-miss costs another special case (#1295).
+  //
+  // The scanner remains only for a document `Bun.TOML.parse` rejects. That is a
+  // statement about Bun's parser, not about Codex's — the two are separate
+  // implementations and no compatibility evidence is claimed here, so a document
+  // Bun rejects may still be one Codex loads. The fallback is therefore
+  // best-effort and inherits the ambiguity above. It exists because reporting a
+  // feature as disabled on account of an unreadable file presents a failure as
+  // a state.
+  const parsed = parsedTomlTable(content, "features");
+  if (parsed !== null) {
+    const table = plainTomlRecord(parsed.multi_agent_v2);
+    if (table !== null) return table.enabled === true;
+    if (typeof parsed.multi_agent_v2 === "boolean") return parsed.multi_agent_v2;
+    return false;
+  }
+
+  // Bun 1.4 enforces TOML's "value must begin on the assignment line" rule that
+  // 1.3.14 did not, so `hint =` followed by `[` on the next line now fails the
+  // real parse and reaches the line-based fallback below — which reads that `[`
+  // as a table header and truncates the table before `enabled`. Codex's own
+  // parser accepts the document, so answering "disabled" would report a parser
+  // disagreement as a feature state (#1295, #1691).
+  //
+  // Joining a dangling `=` to the line that follows is the smallest repair that
+  // keeps the scanner untouched: widening `tomlTableBody` to be string-aware is
+  // what previously broke `getAgentsEnabled`, `getAgentsMaxDepth`, and
+  // `getMaxConcurrentThreads` (see its comment). If the joined document parses,
+  // that answer is authoritative; if it does not, nothing is lost.
+  const joined = joinDanglingTomlAssignments(content);
+  if (joined !== content) {
+    const reparsed = parsedTomlTable(joined, "features");
+    if (reparsed !== null) {
+      const table = plainTomlRecord(reparsed.multi_agent_v2);
+      if (table !== null) return table.enabled === true;
+      if (typeof reparsed.multi_agent_v2 === "boolean") return reparsed.multi_agent_v2;
+      return false;
+    }
+  }
+
+  const table = tomlTableBody(content, "features.multi_agent_v2");
+  if (table !== null) {
+    const enabled = tomlBoolInBody(table, "enabled");
+    if (enabled !== null) return enabled;
+    // A bare [features.multi_agent_v2] table without `enabled` counts as on
+    // (FeatureToml::Config with enabled: None materializes as enabled upstream
+    // only when set; be conservative and require the boolean).
+    return false;
+  }
+
+  const features = tomlTableBody(content, "features");
+  if (features !== null) {
+    const bool = tomlBoolInBody(features, "multi_agent_v2");
+    if (bool !== null) return bool;
+    const inline = features.match(/^\s*multi_agent_v2\s*=\s*\{([^}]*)\}/m);
+    if (inline) {
+      const enabled = inline[1].match(/enabled\s*=\s*(true|false)/);
+      if (enabled) return enabled[1] === "true";
+    }
+  }
+  return false;
+}
+
+function plainTomlRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+/**
+ * Join `key =` to the following line when the value was written on the next
+ * line, so a parser enforcing TOML's same-line rule can read the document.
+ *
+ * Bun 1.3.14 accepted this shape; Bun 1.4 rejects it, correctly — TOML requires
+ * the value to begin on the assignment line. Codex's parser still accepts it, so
+ * this exists to keep the two readers agreeing rather than to endorse the shape.
+ *
+ * Deliberately narrow: it only acts on a line whose LAST non-comment character
+ * is `=`, which cannot occur in a valid assignment. Lines inside multi-line
+ * strings are left alone — a `"""` body line ending in `=` would be rewritten,
+ * but the result is only used when it PARSES, and the unmodified document is
+ * always tried first, so a wrong join cannot displace a correct read.
+ */
+function joinDanglingTomlAssignments(content: string): string {
+  const lines = content.split("\n");
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    // A dangling assignment: trailing `=` with nothing after it on this line.
+    if (/^[^#]*[^=!<>]=\s*$/.test(line) && i + 1 < lines.length) {
+      let j = i + 1;
+      // Skip blank and comment-only lines between the `=` and its value.
+      while (j < lines.length && /^\s*(?:#.*)?$/.test(lines[j]!)) j++;
+      if (j < lines.length) {
+        out.push(`${line.replace(/\s*$/, "")} ${lines[j]!.replace(/^\s*/, "")}`);
+        i = j;
+        continue;
+      }
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/**
+ * A top-level table from a full TOML parse, or null when the document does not
+ * parse. A parsed document with no such table yields `{}` rather than null: that
+ * is a real answer ("no keys"), while null means "could not read, fall back".
+ */
+function parsedTomlTable(content: string, name: string): Record<string, unknown> | null {
+  const toml = (globalThis as { Bun?: { TOML?: { parse(input: string): unknown } } }).Bun?.TOML;
+  if (!toml) return null;
+  try {
+    const root = plainTomlRecord(toml.parse(content));
+    if (root === null) return null;
+    return plainTomlRecord(root[name]) ?? {};
+  } catch {
+    return null;
+  }
+}
+
+
+/**
+ * TRUE when the codex `default_mode_request_user_input` feature is enabled in
+ * config.toml — lets a Default-mode session pause and ask the user questions
+ * through `request_user_input` (upstream FeatureSpec: under development,
+ * default_enabled = false). Recognizes the shipped boolean form
+ * `[features] default_mode_request_user_input = true`.
+ * Missing file/key -> false.
+ */
+export function isDefaultModeRequestUserInputEnabled(configPath?: string): boolean {
+  const content = readConfigText(configPath);
+  if (content === null) return false;
+  // Same reason as the v2 reader: a `"""` value whose prose contains
+  // `default_mode_request_user_input = true` is not an assignment, and a raw
+  // regex over the table body cannot tell the difference (#1295).
+  const parsed = parsedTomlTable(content, "features");
+  if (parsed !== null) return parsed[DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY] === true;
+  const features = tomlTableBody(content, "features");
+  if (features === null) return false;
+  return tomlBoolInBody(features, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY) === true;
+}
+
+/**
+ * TRUE when config.toml still carries `[agents] max_threads` — codex-rs REFUSES to
+ * boot with that key while multi_agent_v2 is enabled ("agents.max_threads cannot be
+ * set when features.multi_agent_v2 is enabled", core/src/config/mod.rs:1421). The
+ * `ocx v2 on` flow warns about it instead of editing config itself.
+ */
+export function hasAgentsMaxThreads(configPath?: string): boolean {
+  const content = readConfigText(configPath);
+  if (content === null) return false;
+  const parsed = parsedTomlTable(content, "agents");
+  if (parsed !== null) return Object.hasOwn(parsed, "max_threads");
+  const agents = tomlTableBody(content, "agents");
+  if (agents === null) return false;
+  return /^\s*max_threads\s*=/m.test(agents);
+}
+
+/** Current legacy v1 `[agents] max_threads`, or null when absent/invalid. */
+export function getAgentsMaxThreads(configPath?: string): number | null {
+  const content = readConfigText(configPath);
+  if (content === null) return null;
+  const parsed = parsedTomlTable(content, "agents");
+  if (parsed !== null) {
+    const value = parsed.max_threads;
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null;
+  }
+  const agents = tomlTableBody(content, "agents");
+  if (agents === null) return null;
+  const m = agents.match(/^\s*max_threads\s*=\s*(\d+)\s*(?:#.*)?$/m);
+  if (!m) return null;
+  const value = Number(m[1]);
+  return Number.isInteger(value) && value >= 1 ? value : null;
+}
+
+/**
+ * Current `[agents] enabled`. Upstream defaults this to true and lets an enabled
+ * `features.multi_agent_v2` override it entirely (codex-rs core/src/config/mod.rs
+ * multi_agent_version_override returns V2 first at :1521-1523; `enabled = false`
+ * only takes effect with V2 off), so `null` means "unset, upstream default applies"
+ * and is NOT the same as `true`.
+ */
+export function getAgentsEnabled(configPath?: string): boolean | null {
+  const content = readConfigText(configPath);
+  if (content === null) return null;
+  const agents = tomlTableBody(content, "agents");
+  if (agents === null) return null;
+  const m = agents.match(/^\s*enabled\s*=\s*(true|false)\s*(?:#.*)?$/m);
+  return m ? m[1] === "true" : null;
+}
+
+/**
+ * Current `[agents] max_depth`. Upstream applies this to V1 agent threads only and
+ * ignores it under V2 (config_toml.rs: "Maximum nesting depth for V1 agent threads.
+ * Ignored by V2."). The upstream type is `Option<i32>` with no minimum, so a
+ * negative value is valid config that effectively disables V1 child spawning —
+ * do not "correct" it, and do not present this as an effective V2 limit.
+ */
+export function getAgentsMaxDepth(configPath?: string): number | null {
+  const content = readConfigText(configPath);
+  if (content === null) return null;
+  const agents = tomlTableBody(content, "agents");
+  if (agents === null) return null;
+  const m = agents.match(/^\s*max_depth\s*=\s*(-?\d+)\s*(?:#.*)?$/m);
+  if (!m) return null;
+  const value = Number(m[1]);
+  return Number.isInteger(value) && value >= -2_147_483_648 && value <= 2_147_483_647 ? value : null;
+}
+
+/**
+ * Current `features.multi_agent_v2.max_concurrent_threads_per_session`, from
+ * either the dedicated or inline-table form; null means the Codex default.
+ */
+export function getMaxConcurrentThreads(configPath?: string): number | null {
+  const content = readConfigText(configPath);
+  if (content === null) return null;
+  const table = tomlTableBody(content, "features.multi_agent_v2");
+  const features = tomlTableBody(content, "features");
+  const inline = features?.match(/^\s*multi_agent_v2\s*=\s*\{([^}]*)\}/m);
+  const m = table?.match(/^\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?:#.*)?$/m)
+    ?? inline?.[1].match(/(?:^|,)\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?:,|$)/);
+  if (!m) return null;
+  const value = Number(m[1]);
+  return Number.isFinite(value) && value >= 1 ? value : null;
+}
+
+/** Largest V1 child limit we translate. Well below Number.MAX_SAFE_INTEGER and far
+ *  above any real concurrency setting; upstream's usize saturates, ours would silently
+ *  lose precision. */
+const MAX_TRANSLATABLE_V1_CHILD_LIMIT = 1_000_000;
+/** The V2 side is one larger by construction: it counts the root agent's own slot, so
+ *  the image of the maximum V1 value must itself be translatable back. */
+const MAX_TRANSLATABLE_V2_TOTAL_LIMIT = MAX_TRANSLATABLE_V1_CHILD_LIMIT + 1;
+
+export function isTranslatableV1ChildLimit(limit: number): boolean {
+  return Number.isInteger(limit) && limit >= 1 && limit <= MAX_TRANSLATABLE_V1_CHILD_LIMIT;
+}
+
+export function isTranslatableV2TotalLimit(limit: number): boolean {
+  return Number.isInteger(limit) && limit >= 1 && limit <= MAX_TRANSLATABLE_V2_TOTAL_LIMIT;
+}
+
+/**
+ * Upstream counts the root agent inside the V2 thread limit but not inside the legacy
+ * `[agents]` limit (codex-rs core/src/config/mod.rs resolve_multi_agent_v2_config applies
+ * saturating_add(1) to the [agents] value; the inverse saturating_sub(1) appears at
+ * mod.rs:1555). These helpers keep our migrations on the same side of that boundary.
+ */
+export function v1ChildLimitToV2TotalLimit(childLimit: number): number {
+  if (!isTranslatableV1ChildLimit(childLimit)) {
+    throw new RangeError(`v1 child limit out of translatable range: ${childLimit}`);
+  }
+  return childLimit + 1;
+}
+
+/**
+ * Inverse of `v1ChildLimitToV2TotalLimit`. A V2 total of 1 means "root only, no
+ * children", which has no representable legacy child count >= 1, so it clamps to 1
+ * rather than writing 0 and tripping upstream's `>= 1` validation.
+ */
+export function v2TotalLimitToV1ChildLimit(totalLimit: number): number {
+  if (!isTranslatableV2TotalLimit(totalLimit)) {
+    throw new RangeError(`v2 total limit out of translatable range: ${totalLimit}`);
+  }
+  return Math.max(1, totalLimit - 1);
+}
+
+/**
+ * Persist `features.multi_agent_v2.max_concurrent_threads_per_session = value`.
+ * Scoped edit in either the dedicated table or `[features]` boolean/inline form.
+ * Boolean form is upgraded to an inline config so the numeric value remains
+ * attached to the feature without a TOML key conflict. Idempotent on equal value.
+ */
+export function setMaxConcurrentThreads(value: number, configPath?: string, migratedComment?: string): { ok: true; changed: boolean } | { ok: false; error: string } {
+  if (!Number.isInteger(value) || value < 1) {
+    return { ok: false, error: "max_concurrent_threads_per_session must be an integer >= 1" };
+  }
+  const path = configPath ?? activeCodexConfigPath();
+  const content = readConfigText(path);
+  if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
+
+  const eol = dominantEol(content);
+  const lines = content.split(/\r?\n/);
+  const headerRe = /^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/;
+  const headerIdx = lines.findIndex(l => headerRe.test(l));
+  if (headerIdx === -1) {
+    const featuresHeader = lines.findIndex(l => /^\s*\[features\]\s*(?:#.*)?$/.test(l));
+    if (featuresHeader === -1) return { ok: false, error: "multi_agent_v2 feature config not found — enable v2 first (ocx v2 on)" };
+    let featuresEnd = lines.length;
+    for (let i = featuresHeader + 1; i < lines.length; i++) {
+      if (/^\s*\[/.test(lines[i])) { featuresEnd = i; break; }
+    }
+    const boolRe = /^(\s*)multi_agent_v2\s*=\s*(true|false)(\s*#.*)?$/;
+    const inlineRe = /^(\s*)multi_agent_v2\s*=\s*\{([^}]*)\}(\s*#.*)?$/;
+    for (let i = featuresHeader + 1; i < featuresEnd; i++) {
+      const bool = lines[i].match(boolRe);
+      if (bool) {
+        lines[i] = `${bool[1]}multi_agent_v2 = { enabled = ${bool[2]}, max_concurrent_threads_per_session = ${value} }${mergeTrailingComments(bool[3], migratedComment)}`;
+        atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+        return { ok: true, changed: true };
+      }
+      const inline = lines[i].match(inlineRe);
+      if (!inline) continue;
+      const existing = inline[2].match(/(?:^|,)\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?=,|$)/);
+      if (existing && Number(existing[1]) === value && (!migratedComment || migratedComment === inline[3])) return { ok: true, changed: false };
+      const body = existing
+        ? inline[2].replace(/(^|,)\s*max_concurrent_threads_per_session\s*=\s*\d+\s*(?=,|$)/, `$1 max_concurrent_threads_per_session = ${value}`)
+        : `${inline[2].trim()}${inline[2].trim() ? ", " : ""}max_concurrent_threads_per_session = ${value}`;
+      lines[i] = `${inline[1]}multi_agent_v2 = { ${body.trim()} }${mergeTrailingComments(inline[3], migratedComment)}`;
+      atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+      return { ok: true, changed: true };
+    }
+    return { ok: false, error: "multi_agent_v2 feature config not found — enable v2 first (ocx v2 on)" };
+  }
+  let end = lines.length;
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) { end = i; break; }
+  }
+  const keyRe = /^(\s*)max_concurrent_threads_per_session\s*=\s*(\d+)(\s*#.*)?$/;
+  for (let i = headerIdx + 1; i < end; i++) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    if (Number(m[2]) === value && (!migratedComment || migratedComment === m[3])) return { ok: true, changed: false };
+    lines[i] = `${m[1]}max_concurrent_threads_per_session = ${value}${mergeTrailingComments(m[3], migratedComment)}`;
+    atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+    return { ok: true, changed: true };
+  }
+  lines.splice(headerIdx + 1, 0, `max_concurrent_threads_per_session = ${value}${migratedComment ?? ""}`);
+  atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+  return { ok: true, changed: true };
+}
+
+type ConfigEditResult = { ok: true; changed: boolean } | { ok: false; error: string };
+
+/**
+ * Encode a string as a TOML single-line basic string.
+ *
+ * Character-by-character on purpose. A chained-replace implementation
+ * (`.replace(/\\/g, "\\\\").replace(/\t/g, "\\t")`) corrupts input: the backslash
+ * pass runs first, then later passes insert NEW backslashes the first pass can no
+ * longer protect. Single-line basic strings handle every case including embedded
+ * `"""`, which a multi-line `"""..."""` form cannot.
+ */
+function encodeTomlBasicString(value: string): string {
+  let out = '"';
+  for (const ch of value) {
+    switch (ch) {
+      case "\\": out += "\\\\"; break;
+      case '"': out += '\\"'; break;
+      case "\n": out += "\\n"; break;
+      case "\r": out += "\\r"; break;
+      case "\t": out += "\\t"; break;
+      case "\b": out += "\\b"; break;
+      case "\f": out += "\\f"; break;
+      default: {
+        const code = ch.codePointAt(0)!;
+        out += code < 0x20 || code === 0x7f
+          ? `\\u${code.toString(16).padStart(4, "0")}`
+          : ch;
+      }
+    }
+  }
+  return out + '"';
+}
+
+/**
+ * Decode one TOML string token INCLUDING its quotes. Basic strings (`"..."`)
+ * unescape; literal strings (`'...'`) are verbatim — a backslash is not special
+ * there. Returns null for anything that is not a string token.
+ */
+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;
+  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;
+      case "n": out += "\n"; break;
+      case "r": out += "\r"; break;
+      case "t": out += "\t"; break;
+      case "b": out += "\b"; break;
+      case "f": out += "\f"; break;
+      case "u": {
+        const code = parseInt(body.slice(i + 1, i + 5), 16);
+        if (Number.isNaN(code)) return null;
+        out += String.fromCodePoint(code);
+        i += 4;
+        break;
+      }
+      case "U": {
+        const code = parseInt(body.slice(i + 1, i + 9), 16);
+        if (Number.isNaN(code)) return null;
+        out += String.fromCodePoint(code);
+        i += 8;
+        break;
+      }
+      default: return null;
+    }
+  }
+  return out;
+}
+
+/**
+ * End index (exclusive) of the TOML value starting at or after `start` in `text`.
+ * String-aware: basic strings honor backslash escapes, literal strings do not.
+ * Inline tables and arrays nest and are scanned with the same awareness.
+ */
+function scanTomlValueEnd(text: string, start: number): number {
+  let i = start;
+  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; }
+      if (text[i] === '"') return i + 1;
+      i++;
+    }
+    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;
+  }
+  if (first === "{") {
+    const close = findInlineTableEnd(text, i);
+    return close === -1 ? text.length : close + 1;
+  }
+  if (first === "[") {
+    let depth = 0;
+    while (i < text.length) {
+      const c = text[i];
+      if (c === '"' || c === "'") { i = scanTomlValueEnd(text, i); continue; }
+      if (c === "[") depth++;
+      else if (c === "]") { depth--; if (depth === 0) return i + 1; }
+      i++;
+    }
+    return text.length;
+  }
+  while (i < text.length && !/[\s,}\]#]/.test(text[i])) i++;
+  return i;
+}
+
+/** Index of the `}` matching the `{` at `openIdx`, string-aware, or -1. */
+function findInlineTableEnd(text: string, openIdx: number): number {
+  let depth = 0;
+  let i = openIdx;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '"' || c === "'") { i = scanTomlValueEnd(text, i); continue; }
+    if (c === "{") depth++;
+    else if (c === "}") { depth--; if (depth === 0) return i; }
+    i++;
+  }
+  return -1;
+}
+
+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.
+ */
+function findInlineEntry(text: string, bodyStart: number, bodyEnd: number, key: string): InlineEntry | null {
+  let i = bodyStart;
+  while (i < bodyEnd) {
+    while (i < bodyEnd && /[\s,]/.test(text[i])) i++;
+    if (i >= bodyEnd) break;
+    const entryStart = i;
+    let keyText: string;
+    if (text[i] === '"' || text[i] === "'") {
+      const keyEnd = scanTomlValueEnd(text, i);
+      keyText = decodeTomlStringToken(text.slice(i, keyEnd)) ?? "";
+      i = keyEnd;
+    } else {
+      const m = /^[A-Za-z0-9_-]+/.exec(text.slice(i, bodyEnd));
+      if (!m) break;
+      keyText = m[0];
+      i += m[0].length;
+    }
+    while (i < bodyEnd && /\s/.test(text[i])) i++;
+    if (text[i] !== "=") { i = entryStart + 1; continue; }
+    i++;
+    while (i < bodyEnd && /\s/.test(text[i])) i++;
+    const valueStart = i;
+    const valueEnd = Math.min(scanTomlValueEnd(text, valueStart), bodyEnd);
+    if (keyText === key) return { keyStart: entryStart, valueStart, valueEnd };
+    i = valueEnd;
+  }
+  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,
+ * which is kept verbatim. `encoded` is the already-serialized RHS
+ * (`encodeTomlBasicString` for strings, `String(n)` for numbers, `"true"`/`"false"`
+ * for booleans); null removes the key. Creates the table when absent. Returns the
+ * new content; returning the input unchanged means no-op.
+ */
+function editScalarInTable(content: string, table: string, key: string, encoded: string | null): string {
+  const eol = dominantEol(content);
+  const lines = content.split(/\r?\n/);
+  const headerRe = new RegExp(`^\\s*\\[${table.replace(/\./g, "\\.")}\\]\\s*(?:#.*)?$`);
+  const headerIdx = lines.findIndex(l => headerRe.test(l));
+  if (headerIdx === -1) {
+    if (encoded === null) return content;
+    const separator = lines.length > 0 && lines[lines.length - 1] !== "" ? [""] : [];
+    lines.push(...separator, `[${table}]`, `${key} = ${encoded}`);
+    return applyEol(lines.join("\n"), eol);
+  }
+  let end = lines.length;
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) { end = i; break; }
+  }
+  for (let i = headerIdx + 1; i < end; i++) {
+    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 trailing = line.slice(entry.valueEnd);
+    if (encoded === null) {
+      lines.splice(i, 1);
+      return applyEol(lines.join("\n"), eol);
+    }
+    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;
+  lines.splice(headerIdx + 1, 0, `${key} = ${encoded}`);
+  return applyEol(lines.join("\n"), eol);
+}
+
+/** Persist `[agents] enabled = value`, or remove the key when `value` is null. */
+export function setAgentsEnabled(value: boolean | 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 next = editScalarInTable(content, "agents", "enabled", value === null ? null : String(value));
+  if (next === content) return { ok: true, changed: false };
+  atomicWriteFile(path, next);
+  return { ok: true, changed: true };
+}
+
+/**
+ * Persist `[agents] max_depth = value`, or remove the key when `value` is null.
+ * Validation is exactly the upstream contract: `Option<i32>` with no minimum, so
+ * any integer in signed-i32 range is accepted — writing anything wider would
+ * produce a config upstream cannot deserialize, a hard parse failure for the
+ * user's Codex.
+ */
+export function setAgentsMaxDepth(value: number | null, configPath?: string): ConfigEditResult {
+  if (value !== null && (!Number.isInteger(value) || value < -2_147_483_648 || value > 2_147_483_647)) {
+    return { ok: false, error: "max_depth must be an integer within signed i32 range" };
+  }
+  const path = configPath ?? activeCodexConfigPath();
+  const content = readConfigText(path);
+  if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
+  const next = editScalarInTable(content, "agents", "max_depth", value === null ? null : String(value));
+  if (next === content) return { ok: true, changed: false };
+  atomicWriteFile(path, next);
+  return { ok: true, changed: true };
+}
+
+/**
+ * Current `features.multi_agent_v2.subagent_developer_instructions`.
+ *
+ * Upstream tri-state (codex-rs core/src/config/mod.rs resolve_multi_agent_v2_config):
+ *   unset        -> the child inherits the parent's developer instructions
+ *   non-empty    -> replaces the inherited parent fragment
+ *   empty string -> clears the inherited fragment
+ *
+ * So `null` and `""` are DIFFERENT values and both must round-trip. Upstream
+ * `.trim()`s the configured text, so whitespace-only values are effectively `""`.
+ * Reads both the dedicated-table and inline forms; dedicated wins, mirroring
+ * `getMaxConcurrentThreads` precedence.
+ */
+/**
+ * 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 = tomlTableBodyForStringFields(content, "features.multi_agent_v2");
+  if (table !== null) {
+    const entry = findTomlAssignment(table, key);
+    if (entry) {
+      const token = table.slice(entry.valueStart, entry.valueEnd).trim();
+      return decodeTomlStringToken(token);
+    }
+    return null;
+  }
+  const features = tomlTableBodyForStringFields(content, "features");
+  if (features === null) return null;
+  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, 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
+ * table (scalar edit), the inline table (string-aware edit inside the braces — a
+ * regex over `[^}]*` would corrupt any value containing `}`), and the bare boolean
+ * form (upgraded in place to an inline table, mirroring `setMaxConcurrentThreads`).
+ * With no existing v2 config, creates the dedicated table carrying only this key.
+ * The key name must match upstream character-for-character: the upstream struct
+ * carries `#[serde(deny_unknown_fields)]`, so a misspelling is not ignored — it is
+ * a hard config-parse failure for the user's Codex.
+ */
+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);
+
+  // 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));
+  if (featuresHeader !== -1) {
+    let featuresEnd = lines.length;
+    for (let i = featuresHeader + 1; i < lines.length; i++) {
+      if (/^\s*\[/.test(lines[i])) { featuresEnd = i; break; }
+    }
+    for (let i = featuresHeader + 1; i < featuresEnd; i++) {
+      const line = lines[i];
+      const inlineMatch = line.match(/^(\s*)multi_agent_v2\s*=\s*\{/);
+      if (inlineMatch) {
+        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, key);
+        if (encoded === null) {
+          if (!entry) return { ok: true, changed: false };
+          let start = entry.keyStart;
+          let stop = entry.valueEnd;
+          let j = stop;
+          while (j < closeIdx && line[j] === " ") j++;
+          if (line[j] === ",") {
+            stop = j + 1;
+            while (stop < closeIdx && line[stop] === " ") stop++;
+          } else {
+            let k = start;
+            while (k > openIdx + 1 && line[k - 1] === " ") k--;
+            if (line[k - 1] === ",") start = k - 1;
+          }
+          lines[i] = line.slice(0, start) + line.slice(stop);
+          atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+          return { ok: true, changed: true };
+        }
+        if (entry) {
+          if (line.slice(entry.valueStart, entry.valueEnd).trim() === encoded) return { ok: true, changed: false };
+          lines[i] = line.slice(0, entry.valueStart) + encoded + line.slice(entry.valueEnd);
+        } else {
+          let insertPos = closeIdx;
+          while (insertPos > openIdx + 1 && line[insertPos - 1] === " ") insertPos--;
+          const hasEntries = line.slice(openIdx + 1, insertPos).trim().length > 0;
+          const insertion = hasEntries
+            ? `, ${key} = ${encoded} `
+            : ` ${key} = ${encoded} `;
+          lines[i] = line.slice(0, insertPos) + insertion + line.slice(closeIdx);
+        }
+        atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+        return { ok: true, changed: true };
+      }
+      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]}, ${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}${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);
+}
+
+export const MODE_HINT_CAPABILITY_CACHE_MAX_ENTRIES = 8;
+export const modeHintCapabilityCache = new Map<string, boolean | null>();
+
+export function rememberModeHintCapability(cacheKey: string, capability: boolean | null): void {
+  modeHintCapabilityCache.delete(cacheKey);
+  modeHintCapabilityCache.set(cacheKey, capability);
+  while (modeHintCapabilityCache.size > MODE_HINT_CAPABILITY_CACHE_MAX_ENTRIES) {
+    const oldest = modeHintCapabilityCache.keys().next().value;
+    if (oldest === undefined) break;
+    modeHintCapabilityCache.delete(oldest);
+  }
+}
+
+/**
+ * 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"))) {
+          rememberModeHintCapability(cacheKey, true);
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+    // At least one real binary was inspected and none contained the key.
+    const result = sawBinary ? false : null;
+    rememberModeHintCapability(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);
+  if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
+  const eol = dominantEol(content);
+  const lines = content.split(/\r?\n/);
+  const headerIdx = lines.findIndex(l => /^\s*\[agents\]\s*(?:#.*)?$/.test(l));
+  if (headerIdx === -1) {
+    if (value === null) return { ok: true, changed: false };
+    const separator = lines.length > 0 && lines[lines.length - 1] !== "" ? [""] : [];
+    lines.push(...separator, "[agents]", `max_threads = ${value}${migratedComment ?? ""}`);
+    atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+    return { ok: true, changed: true };
+  }
+  let end = lines.length;
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) { end = i; break; }
+  }
+  const keyRe = /^(\s*)max_threads\s*=\s*(\d+)(\s*#.*)?$/;
+  for (let i = headerIdx + 1; i < end; i++) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    if (value === null) lines.splice(i, 1);
+    else if (Number(m[2]) === value && (!migratedComment || migratedComment === m[3])) return { ok: true, changed: false };
+    else lines[i] = `${m[1]}max_threads = ${value}${mergeTrailingComments(m[3], migratedComment)}`;
+    atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+    return { ok: true, changed: true };
+  }
+  if (value === null) return { ok: true, changed: false };
+  lines.splice(headerIdx + 1, 0, `max_threads = ${value}${migratedComment ?? ""}`);
+  atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+  return { ok: true, changed: true };
+}
+
+function removeMaxConcurrentThreads(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 eol = dominantEol(content);
+  const lines = content.split(/\r?\n/);
+  const headerIdx = lines.findIndex(l => /^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/.test(l));
+  if (headerIdx !== -1) {
+    let end = lines.length;
+    for (let i = headerIdx + 1; i < lines.length; i++) {
+      if (/^\s*\[/.test(lines[i])) { end = i; break; }
+    }
+    const keyIdx = lines.findIndex((line, i) => i > headerIdx && i < end && /^\s*max_concurrent_threads_per_session\s*=/.test(line));
+    if (keyIdx !== -1) {
+      lines.splice(keyIdx, 1);
+      atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+      return { ok: true, changed: true };
+    }
+  }
+  const featuresHeader = lines.findIndex(l => /^\s*\[features\]\s*(?:#.*)?$/.test(l));
+  if (featuresHeader === -1) return { ok: true, changed: false };
+  let featuresEnd = lines.length;
+  for (let i = featuresHeader + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) { featuresEnd = i; break; }
+  }
+  const inlineRe = /^(\s*)multi_agent_v2\s*=\s*\{([^}]*)\}(\s*#.*)?$/;
+  for (let i = featuresHeader + 1; i < featuresEnd; i++) {
+    const inline = lines[i].match(inlineRe);
+    if (!inline || !/(?:^|,)\s*max_concurrent_threads_per_session\s*=/.test(inline[2])) continue;
+    const body = inline[2]
+      .replace(/^\s*max_concurrent_threads_per_session\s*=\s*\d+\s*,?\s*/, "")
+      .replace(/,\s*max_concurrent_threads_per_session\s*=\s*\d+\s*(?=,|$)/, "")
+      .trim();
+    lines[i] = `${inline[1]}multi_agent_v2 = { ${body} }${inline[3] ?? ""}`;
+    atomicWriteFile(path, applyEol(lines.join("\n"), eol));
+    return { ok: true, changed: true };
+  }
+  return { ok: true, changed: false };
+}
+
+function ensureDisabledV2Config(value: number | null, configPath?: string, migratedComment?: string): ConfigEditResult {
+  const path = configPath ?? activeCodexConfigPath();
+  const content = readConfigText(path);
+  if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
+  if (tomlTableBody(content, "features.multi_agent_v2") !== null || tomlTableBody(content, "features")?.match(/^\s*multi_agent_v2\s*=/m)) {
+    if (value === null) return { ok: true, changed: false };
+    return setMaxConcurrentThreads(value, path, migratedComment);
+  }
+  const eol = dominantEol(content);
+  const suffix = content.endsWith("\n") || content.length === 0 ? "" : eol;
+  const table = `[features.multi_agent_v2]${eol}enabled = false${value === null ? "" : `${eol}max_concurrent_threads_per_session = ${value}${migratedComment ?? ""}`}${eol}`;
+  atomicWriteFile(path, `${content}${suffix}${content.length > 0 && !content.endsWith(`${eol}${eol}`) ? eol : ""}${table}`);
+  return { ok: true, changed: true };
+}
+
+/**
+ * The effective concurrency limit expressed in the units of the currently ACTIVE
+ * backend: under V2 the total-thread limit upstream enforces, under V1 the child
+ * limit. The active backend's own key wins; the other backend's key is translated
+ * across the root-agent slot. Display path only — never throws: a stored value
+ * outside the translatable range is returned raw (at that magnitude the ±1 root
+ * slot is already below float precision, and crashing `ocx v2 status` or
+ * `GET /api/v2` is not a price worth paying for a translation that means nothing).
+ * Migration code uses `discoverStoredThreadLimit` instead, which keeps provenance.
+ */
+export function getLogicalMaxThreads(configPath?: string): number | null {
+  if (isMultiAgentV2Enabled(configPath)) {
+    const v2 = getMaxConcurrentThreads(configPath);
+    if (v2 !== null) return v2;
+    const legacy = getAgentsMaxThreads(configPath);
+    if (legacy === null) return null;
+    return isTranslatableV1ChildLimit(legacy) ? v1ChildLimitToV2TotalLimit(legacy) : legacy;
+  }
+  const legacy = getAgentsMaxThreads(configPath);
+  if (legacy !== null) return legacy;
+  const v2 = getMaxConcurrentThreads(configPath);
+  if (v2 === null) return null;
+  return isTranslatableV2TotalLimit(v2) ? v2TotalLimitToV1ChildLimit(v2) : v2;
+}
+
+type ThreadLimitUnits = "v1-child" | "v2-total";
+
+/**
+ * Which storage the active limit lives in, in that storage's native units. The
+ * active backend's own key wins; the other backend's key is the fallback and keeps
+ * ITS units. Never translates and never throws. This is the migration-side sibling
+ * of `getLogicalMaxThreads`: a migration needs to know exactly which storage the
+ * value came from, and a display function's raw fallback would lose that.
+ */
+function discoverStoredThreadLimit(configPath?: string): { value: number; units: ThreadLimitUnits } | null {
+  if (isMultiAgentV2Enabled(configPath)) {
+    const v2 = getMaxConcurrentThreads(configPath);
+    if (v2 !== null) return { value: v2, units: "v2-total" };
+    const legacy = getAgentsMaxThreads(configPath);
+    return legacy === null ? null : { value: legacy, units: "v1-child" };
+  }
+  const legacy = getAgentsMaxThreads(configPath);
+  if (legacy !== null) return { value: legacy, units: "v1-child" };
+  const v2 = getMaxConcurrentThreads(configPath);
+  return v2 === null ? null : { value: v2, units: "v2-total" };
+}
+
+function activeThreadComment(content: string, v2Enabled: boolean): string | undefined {
+  const legacy = tomlTableBody(content, "agents")?.match(/^\s*max_threads\s*=\s*\d+(\s*#.*)$/m)?.[1];
+  const dedicated = tomlTableBody(content, "features.multi_agent_v2")
+    ?.match(/^\s*max_concurrent_threads_per_session\s*=\s*\d+(\s*#.*)$/m)?.[1];
+  const features = tomlTableBody(content, "features");
+  const inlineLine = features?.match(/^\s*multi_agent_v2\s*=\s*\{([^}]*)\}(\s*#.*)$/m);
+  const inline = inlineLine && /(?:^|,)\s*max_concurrent_threads_per_session\s*=\s*\d+\s*(?:,|$)/.test(inlineLine[1])
+    ? inlineLine[2]
+    : undefined;
+  return v2Enabled ? dedicated ?? inline ?? legacy : legacy ?? dedicated ?? inline;
+}
+
+let migrationEditSeq = 0;
+/** Both residual classes gate the memo release: a plain residual and a
+ * secret-bearing one alike keep their destination memo while the file
+ * remains on disk. Exported for the regression seam. */
+export function isAtomicResidualError(error: unknown): boolean {
+  return error instanceof AtomicWriteResidualTempError || error instanceof AtomicWriteSecretResidualError;
+}
+
+function applyConfigEditsAtomically(path: string, edit: (tempPath: string) => ConfigEditResult): ConfigEditResult {
+  const content = readConfigText(path);
+  if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
+  const tempPath = `${path}.ocx-migration.${process.pid}.${++migrationEditSeq}`;
+  // An inner residual temp (AtomicWriteResidualTempError) keeps its
+  // destination-keyed memo: fail-closed while the residual exists.
+  let innerResidual = false;
+  try {
+    atomicWriteFile(tempPath, content);
+    const result = edit(tempPath);
+    if (!result.ok) return result;
+    const edited = readConfigText(tempPath);
+    if (edited === null) return { ok: false, error: "temporary config migration output is unreadable" };
+    if (edited === content) return { ok: true, changed: false };
+    atomicWriteFile(path, edited);
+    return { ok: true, changed: true };
+  } catch (error) {
+    if (isAtomicResidualError(error)) innerResidual = true;
+    throw error;
+  } finally {
+    try {
+      unlinkSync(tempPath);
+      if (!innerResidual) forgetEphemeralSecretPath(tempPath);
+    } catch (error) {
+      // Already absent is also proven-absent; other failures keep the memo.
+      if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
+        if (!innerResidual) forgetEphemeralSecretPath(tempPath);
+      }
+    }
+  }
+}
+
+export type MultiAgentV2TransitionResult =
+  | { ok: true; changed: boolean; threadLimit: number | null }
+  | { ok: false; error: string };
+
+function transitionConfigError(content: string): string | null {
+  if (/^\s*(?:features\.multi_agent_v2(?:\.[A-Za-z0-9_]+)?|agents\.max_threads)\s*=/m.test(content)) {
+    return "dotted multi-agent config keys are not supported for automatic migration";
+  }
+  const dedicatedTables = content.match(/^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/gm) ?? [];
+  const featuresTables = content.match(/^\s*\[features\]\s*(?:#.*)?$/gm) ?? [];
+  const agentsTables = content.match(/^\s*\[agents\]\s*(?:#.*)?$/gm) ?? [];
+  if (dedicatedTables.length > 1 || featuresTables.length > 1 || agentsTables.length > 1) {
+    return "duplicate multi-agent TOML tables cannot be migrated safely";
+  }
+  const features = tomlTableBody(content, "features");
+  const featureDefs = features?.match(/^\s*multi_agent_v2\s*=/gm) ?? [];
+  if (featureDefs.length > 1 || (dedicatedTables.length === 1 && featureDefs.length === 1)) {
+    return "duplicate multi_agent_v2 definitions cannot be migrated safely";
+  }
+  if (features && /^\s*multi_agent_v2\.(?:enabled|max_concurrent_threads_per_session)\s*=/m.test(features)) {
+    return "dotted multi_agent_v2 fields are not supported for automatic migration";
+  }
+  const agents = tomlTableBody(content, "agents");
+  if ((agents?.match(/^\s*max_threads\s*=/gm) ?? []).length > 1) {
+    return "duplicate agents.max_threads definitions cannot be migrated safely";
+  }
+  const dedicated = tomlTableBody(content, "features.multi_agent_v2");
+  if ((dedicated?.match(/^\s*max_concurrent_threads_per_session\s*=/gm) ?? []).length > 1) {
+    return "duplicate v2 thread-limit definitions cannot be migrated safely";
+  }
+  return null;
+}
+
+/**
+ * Toggle native multi_agent_v2 while moving the active thread limit to the key
+ * valid for the destination version. Any failed command/postcondition restores
+ * the exact original config bytes.
+ */
+export function transitionMultiAgentV2(
+  enabled: boolean,
+  toggleFeature: (enabled: boolean) => void,
+  options: { configPath?: string; threadLimit?: number } = {},
+): MultiAgentV2TransitionResult {
+  if (options.threadLimit !== undefined && (!Number.isInteger(options.threadLimit) || options.threadLimit < 1)) {
+    return { ok: false, error: "thread limit must be an integer >= 1" };
+  }
+  const path = options.configPath ?? activeCodexConfigPath();
+  const original = readConfigText(path);
+  if (original === null) return { ok: false, error: `config.toml not readable at ${path}` };
+  const preflightError = transitionConfigError(original);
+  if (preflightError) return { ok: false, error: preflightError };
+  const beforeEnabled = isMultiAgentV2Enabled(path);
+  // A caller-supplied limit is already in the DESTINATION backend's units and is
+  // never translated. A discovered limit carries the units of the storage it was
+  // read from and crosses the root-slot boundary only when those units differ
+  // from the destination's — which covers both backend flips and same-state
+  // storage migrations (legacy-only under V2, V2-only under V1). The range
+  // check runs only when a translation is actually needed, and before the try
+  // block so an out-of-range stored value is a normal error result rather than
+  // a RangeError escaping the rollback contract.
+  const discovered = discoverStoredThreadLimit(path);
+  const destinationUnits: ThreadLimitUnits = enabled ? "v2-total" : "v1-child";
+  let threadLimit = options.threadLimit ?? discovered?.value ?? null;
+  if (options.threadLimit === undefined && discovered !== null && discovered.units !== destinationUnits) {
+    const translatable = discovered.units === "v1-child" ? isTranslatableV1ChildLimit : isTranslatableV2TotalLimit;
+    if (!translatable(discovered.value)) {
+      return { ok: false, error: `stored thread limit out of translatable range: ${discovered.value}` };
+    }
+    threadLimit = discovered.units === "v1-child"
+      ? v1ChildLimitToV2TotalLimit(discovered.value)
+      : v2TotalLimitToV1ChildLimit(discovered.value);
+  }
+  const migratedComment = activeThreadComment(original, beforeEnabled);
+  try {
+    if (enabled) {
+      if (!beforeEnabled) {
+        const staged = applyConfigEditsAtomically(path, tempPath => {
+          const v2 = ensureDisabledV2Config(threadLimit, tempPath, migratedComment);
+          if (!v2.ok) return v2;
+          return editAgentsMaxThreads(null, tempPath);
+        });
+        if (!staged.ok) throw new Error(staged.error);
+        toggleFeature(true);
+      }
+      if (!isMultiAgentV2Enabled(path)) throw new Error("codex feature command did not enable multi_agent_v2");
+      const target = applyConfigEditsAtomically(path, tempPath => {
+        const v2 = threadLimit === null
+          ? removeMaxConcurrentThreads(tempPath)
+          : setMaxConcurrentThreads(threadLimit, tempPath, migratedComment);
+        if (!v2.ok) return v2;
+        return editAgentsMaxThreads(null, tempPath);
+      });
+      if (!target.ok) throw new Error(target.error);
+      if (hasAgentsMaxThreads(path) || getMaxConcurrentThreads(path) !== threadLimit) throw new Error("v2 thread-limit migration postcondition failed");
+    } else {
+      if (beforeEnabled) toggleFeature(false);
+      if (isMultiAgentV2Enabled(path)) throw new Error("codex feature command did not disable multi_agent_v2");
+      const target = applyConfigEditsAtomically(path, tempPath => {
+        const v2 = removeMaxConcurrentThreads(tempPath);
+        if (!v2.ok) return v2;
+        return editAgentsMaxThreads(threadLimit, tempPath, migratedComment);
+      });
+      if (!target.ok) throw new Error(target.error);
+      if (getMaxConcurrentThreads(path) !== null || getAgentsMaxThreads(path) !== threadLimit) throw new Error("v1 thread-limit migration postcondition failed");
+    }
+    return { ok: true, changed: readConfigText(path) !== original, threadLimit };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+      atomicWriteFile(path, original);
+      return { ok: false, error: message };
+    } catch (rollbackErr) {
+      return { ok: false, error: `${message}; rollback failed: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}` };
+    }
+  }
+}