@bitkyc08/opencodex 2.7.8 → 2.7.9-preview.20260712

package/src/cli/index.ts

@@ -27,6 +27,9 @@ import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-li
 import { stopProxy } from "../lib/process-control";
 import { serviceCommand, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "../service";
 import { drainAndShutdown, startServer } from "../server";
+import { injectSystemEnv, revertSystemEnv } from "../server/system-env";
+import { buildDesktop3pRegistry } from "../claude/desktop-3p";
+import { installShellHook, uninstallShellHook } from "../server/system-env";
 import { startTokenGuardian } from "../oauth/token-guardian";
 import { startHistoryMigrationGuardian } from "../codex/history-migration-guardian";
 import { maybeShowStarPrompt } from "./star-prompt";
@@ -152,6 +155,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     cleaned = true;
     try { guardian.stop(); } catch { /* best-effort */ }
     try { historyGuardian?.stop(); } catch { /* best-effort */ }
+    try { revertSystemEnv(); } catch { /* best-effort */ }
     removePid(process.pid);
     removeRuntimePort(process.pid);
     if (!process.env.OCX_SERVICE) { try { restoreNativeCodex(); } catch { /* best-effort restore */ } }
@@ -192,8 +196,24 @@ async function handleStart(options: { block?: boolean } = {}) {
   process.on("SIGHUP", shutdown);
   process.on("exit", syncCleanup);
 
+  // System-wide env injection AFTER signal handlers are registered (crash safety:
+  // syncCleanup reverts even if injection itself or subsequent startup steps fail).
+  await injectSystemEnv(port, config).catch(() => {});
+  // Auto-install .zshrc hook (idempotent — skips if already present).
+  installShellHook();
+
   await maybeShowStarPrompt(); // once-only [Y/n] GitHub-star prompt on first interactive start
   await syncModelsToCodex(port).catch(() => {});
+  // Build Desktop 3P alias registry so inbound claude-opus-4-8-{code} aliases (and legacy claude-opus-4-{code}) decode correctly.
+  try {
+    const { fetchAllModels } = await import("../server/management-api");
+    const { visibleNativeSlugs, filterCatalogVisibleModels } = await import("../codex/catalog");
+    const models = filterCatalogVisibleModels(await fetchAllModels(config), config);
+    buildDesktop3pRegistry(
+      [...visibleNativeSlugs(config)],
+      models.map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow })),
+    );
+  } catch { /* best-effort — registry rebuilds on first /v1/models call */ }
   if (options.block ?? true) {
     setInterval(() => {}, 60_000);
     await new Promise<void>(() => {});
@@ -208,13 +228,15 @@ async function handleEnsure() {
     return;
   }
   const live = await findLiveProxy();
-  if (live) {
-    await syncModelsToCodex(live.port).catch(e => {
-      console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
-    });
-    console.log(`✅ Proxy running on port ${live.port}`);
-    return;
-  }
+    if (live) {
+      await syncModelsToCodex(live.port).catch(e => {
+        console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
+      });
+      // Ensure env file exists for already-running proxy (may have been deleted or pre-dates this feature).
+      await injectSystemEnv(live.port, config).catch(() => {});
+      console.log(`✅ Proxy running on port ${live.port}`);
+      return;
+    }
 
   const child = spawn(process.execPath, [process.argv[1], "start"], {
     detached: true,
@@ -284,6 +306,9 @@ async function handleStop() {
   }
   const r = restoreNativeCodex();
   console.log(`↩️  ${r.message}`);
+  // Safety net: revert system env vars even if the daemon's syncCleanup didn't run
+  // (e.g. SIGKILL). revertSystemEnv is ownership-checked and idempotent.
+  try { revertSystemEnv(); } catch { /* best-effort */ }
   if (stopFailed) process.exit(1);
 }
 
@@ -319,6 +344,16 @@ async function handleUninstall() {
     if (!r.success) throw new Error(r.message);
   });
 
+  await runStep("system env vars reverted", () => {
+    const r = revertSystemEnv();
+    if (!r.reverted && r.reason !== "no tracking file" && r.reason !== "not macOS") throw new Error(r.reason ?? "revert failed");
+  });
+
+  await runStep("shell hook removed", () => {
+    const r = uninstallShellHook();
+    if (!r.removed && r.reason !== "not installed" && r.reason !== "not macOS") throw new Error(r.reason ?? "remove failed");
+  });
+
   try {
     const { uninstallCodexShim } = await import("../codex/shim");
     const r = uninstallCodexShim();
@@ -580,6 +615,50 @@ switch (command) {
     const { handleModels } = await import("./models");
     handleModels(args.slice(1));
     break;
+  }
+  case "claude": {
+    const { cmdClaude } = await import("./claude");
+    // "ocx claude desktop" → write Desktop 3P config
+    if (args[1] === "desktop") {
+      const config = loadConfig();
+      const { fetchAllModels } = await import("../server/management-api");
+      const { visibleNativeSlugs, filterCatalogVisibleModels } = await import("../codex/catalog");
+      const { parseDesktop3pModeArgs, writeDesktop3pConfig } = await import("../claude/desktop-3p");
+      // Mutually-exclusive mode flags (devlog 138): default static (deterministic; the
+      // static list overrides discovery anyway — no merge).
+      const parsedMode = parseDesktop3pModeArgs(args.slice(2));
+      if ("error" in parsedMode) {
+        console.error(`❌ ${parsedMode.error}`);
+        process.exit(1);
+      }
+      const mode = parsedMode.mode;
+      const live = await findLiveProxy();
+      const port = live?.port ?? config.port ?? 10100;
+      const allModels = await fetchAllModels(config);
+      const models = filterCatalogVisibleModels(allModels, config);
+      const nativeSlugs = [...visibleNativeSlugs(config)];
+      // contextWindow rides along so supports1m derives from authoritative data (감사 R1#1).
+      const routedModels = models.map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow }));
+      const result = writeDesktop3pConfig(port, nativeSlugs, routedModels, undefined, mode);
+      if (result.written) {
+        const oneM = routedModels.filter(m => typeof m.contextWindow === "number" && m.contextWindow >= 1_000_000).length;
+        console.log(`✅ Claude Desktop 3P 설정 완료: ${result.path}`);
+        console.log(`   Gateway: http://127.0.0.1:${port}`);
+        if (mode === "discovery") {
+          console.log(`   모델 목록: 자동 발견만 (프록시 /v1/models에서 ${nativeSlugs.length + models.length}개)`);
+        } else {
+          const suffix = mode === "hybrid" ? " + 자동 발견 병행" : "";
+          console.log(`   모델 ${nativeSlugs.length + models.length}개 고정 등록${suffix} (1M 컨텍스트 별도 행 ${oneM}개)`);
+          if (oneM > 0) console.log(`   1M을 쓰려면 Desktop 모델 피커에서 [1M] 붙은 행을 직접 선택하세요.`);
+        }
+        console.log(`   Claude Desktop을 재시작하면 적용됩니다.`);
+      } else {
+        console.error(`❌ 설정 실패: ${result.reason}`);
+        process.exit(1);
+      }
+      break;
+    }
+    process.exit(await cmdClaude(args.slice(1)));
   }
     case "help":
   case "--help":

package/src/cli/v2.ts

@@ -6,12 +6,12 @@
  *  - config.toml writes go through the official `codex features enable|disable`
  *    CLI only (format-preserving TOML edit stays upstream-owned).
  *  - after a successful flip the catalog is RESYNCED so model metadata stays fresh.
- *  - `on` warns when [agents] max_threads is still present (codex-rs refuses to
- *    boot with it while v2 is enabled) — ocx never edits that key itself.
+ *  - flips preserve the active thread limit while moving it between the v1/v2
+ *    config keys, with byte-for-byte rollback when the feature command fails.
  *  - nothing in the catalog build path calls this module; no auto-flip exists.
  */
 import { execFileSync } from "node:child_process";
-import { getMaxConcurrentThreads, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMaxConcurrentThreads } from "../codex/features";
+import { getLogicalMaxThreads, hasAgentsMaxThreads, isMultiAgentV2Enabled, transitionMultiAgentV2 } from "../codex/features";
 
 import { loadConfig, saveConfig } from "../config";
 
@@ -55,8 +55,8 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     log.log(v2StatusLine(isEnabled()));
     const cfg = loadConfig();
     log.log(multiAgentModeLine(cfg.multiAgentMode ?? "default"));
-    const threads = getMaxConcurrentThreads();
-    log.log(`max_concurrent_threads_per_session: ${threads ?? "(unset — codex default)"}`);
+    const threads = getLogicalMaxThreads();
+    log.log(`max_threads: ${threads ?? "(unset — codex default)"}`);
     if (isEnabled() && hasMaxThreads()) {
       log.log("WARNING: [agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove it from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
     }
@@ -68,11 +68,12 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       log.error("v2 threads: pass an integer >= 1 (features.multi_agent_v2.max_concurrent_threads_per_session)");
       return 1;
     }
-    const result = setMaxConcurrentThreads(value);
+    const enabled = isEnabled();
+    const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: value });
     if (!result.ok) { log.error(`v2 threads: ${result.error}`); return 1; }
     log.log(result.changed
-      ? `max_concurrent_threads_per_session = ${value} — applies to new sessions.`
-      : `max_concurrent_threads_per_session already ${value} — nothing to do.`);
+      ? `max_threads = ${value} (${enabled ? "v2" : "v1"}) — applies to new sessions.`
+      : `max_threads already ${value} — nothing to do.`);
     return 0;
   }
   if (verb === "mode") {
@@ -82,6 +83,14 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       return 1;
     }
     const cfg = loadConfig();
+    if (modeArg !== "default") {
+      const target = modeArg === "v2";
+      const transition = transitionMultiAgentV2(target, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
+      if (!transition.ok) {
+        log.error(`multi-agent mode transition failed: ${transition.error}`);
+        return 1;
+      }
+    }
     if (modeArg === "default") delete cfg.multiAgentMode;
     else cfg.multiAgentMode = modeArg as "v1" | "v2";
     saveConfig(cfg);
@@ -102,18 +111,14 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
   }
 
   const want = verb === "on";
-  if (isEnabled() === want) {
-    log.log(`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`);
-    return 0;
-  }
-  try {
-    runCodexFeatures(want ? "enable" : "disable", deps);
-  } catch (err) {
-    log.error(`codex features ${want ? "enable" : "disable"} multi_agent_v2 failed: ${err instanceof Error ? err.message : String(err)}`);
+  const transition = transitionMultiAgentV2(want, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
+  if (!transition.ok) {
+    log.error(`codex features ${want ? "enable" : "disable"} multi_agent_v2 failed: ${transition.error}`);
     return 1;
   }
-  if (want && hasMaxThreads()) {
-    log.log("WARNING: [agents] max_threads is still set — codex will REFUSE to start until you remove it (features.multi_agent_v2.max_concurrent_threads_per_session replaces it).");
+  if (!transition.changed) {
+    log.log(`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`);
+    return 0;
   }
 
   // Resync catalog so multi-agent surface metadata stays fresh in both the

package/src/codex/features.ts

@@ -14,7 +14,7 @@
  * 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 } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { realpathSync } from "node:fs";
 import { atomicWriteFile, expandUserPath } from "../config";
@@ -34,6 +34,14 @@ function applyEol(content: string, eol: "\r\n" | "\n"): string {
   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}`;
+}
+
 function activeCodexConfigPath(): string {
   const raw = process.env.CODEX_HOME?.trim();
   if (!raw) return CODEX_CONFIG_PATH;
@@ -120,16 +128,30 @@ export function hasAgentsMaxThreads(configPath?: string): boolean {
   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 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 `features.multi_agent_v2.max_concurrent_threads_per_session`, or null when
- * the table/key is absent (codex-rs then applies its own default).
+ * 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");
-  if (table === null) return null;
-  const m = table.match(/^\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?:#.*)?$/m);
+  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;
@@ -137,14 +159,11 @@ export function getMaxConcurrentThreads(configPath?: string): number | null {
 
 /**
  * Persist `features.multi_agent_v2.max_concurrent_threads_per_session = value`.
- * Scoped line edit inside the existing `[features.multi_agent_v2]` table only:
- * replaces the key line when present, else inserts it right under the header.
- * Refuses (returns an error string) when the table is missing — creating it next
- * to a boolean-form `multi_agent_v2 = true` would be a TOML key conflict, and the
- * table is exactly what `codex features enable multi_agent_v2` materializes, so
- * "enable first" is the honest remedy. Idempotent: equal value -> no write.
+ * 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): { ok: true; changed: boolean } | { ok: false; error: string } {
+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" };
   }
@@ -157,7 +176,33 @@ export function setMaxConcurrentThreads(value: number, configPath?: string): { o
   const headerRe = /^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/;
   const headerIdx = lines.findIndex(l => headerRe.test(l));
   if (headerIdx === -1) {
-    return { ok: false, error: "[features.multi_agent_v2] table not found — enable v2 first (ocx v2 on)" };
+    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++) {
@@ -167,12 +212,239 @@ export function setMaxConcurrentThreads(value: number, configPath?: string): { o
   for (let i = headerIdx + 1; i < end; i++) {
     const m = lines[i].match(keyRe);
     if (!m) continue;
-    if (Number(m[2]) === value) return { ok: true, changed: false };
-    lines[i] = `${m[1]}max_concurrent_threads_per_session = ${value}${m[3] ?? ""}`;
+    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}`);
+  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 };
+
+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 };
+}
+
+/** Active logical concurrency value, falling back to the inactive storage. */
+export function getLogicalMaxThreads(configPath?: string): number | null {
+  return isMultiAgentV2Enabled(configPath)
+    ? getMaxConcurrentThreads(configPath) ?? getAgentsMaxThreads(configPath)
+    : getAgentsMaxThreads(configPath) ?? getMaxConcurrentThreads(configPath);
+}
+
+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;
+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}`;
+  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 };
+  } finally {
+    try { unlinkSync(tempPath); } catch { /* already absent */ }
+  }
+}
+
+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);
+  const threadLimit = options.threadLimit ?? getLogicalMaxThreads(path);
+  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)}` };
+    }
+  }
+}

package/src/lib/crash-guard.ts

@@ -156,10 +156,20 @@ const BENIGN_LOG_INTERVAL_MS = 5 * 60_000;
  * cancellation cannot fully close the runtime-internal window. Treat this exact shape as benign:
  * keep the process alive, drop the alarmist banner, and fold repeats into a rate-limited summary so
  * crash.log stays readable for genuinely novel faults.
+ *
+ * Second known shape (260712): `TypeError: Invalid state: ReadableStream is locked`
+ * (code ERR_INVALID_STATE, native-only stack ending in onSinkClose*). When a client
+ * disconnects mid-SSE on the tee()'d passthrough path (responses.ts Bun#32111
+ * workaround), Bun's sink-close teardown tries to cancel the tee-locked source body
+ * and rejects off-path. Request lifecycle is already settled at that point; same
+ * benign handling applies.
  */
 export function isBenignAbortTeardown(err: unknown): boolean {
   if (!(err instanceof TypeError)) return false;
-  if (err.message !== "null is not an object") return false; // bare form only (no `(evaluating …)`)
+  const bareNullTeardown = err.message === "null is not an object"; // bare form only (no `(evaluating …)`)
+  const lockedStreamTeardown = err.message === "Invalid state: ReadableStream is locked"
+    && (err as { code?: unknown }).code === "ERR_INVALID_STATE";
+  if (!bareNullTeardown && !lockedStreamTeardown) return false;
   const stack = err.stack ?? "";
   // Native-only: no JS source frame. A real app TypeError would carry a `(file:line:col)` frame.
   return !/\((?!native:)[^)]*:\d+:\d+\)/.test(stack);