@bitkyc08/opencodex 2.6.31-preview.20260707 → 2.7.0

package/src/bridge.ts

@@ -1,5 +1,5 @@
 import type { AdapterEvent, OcxUsage } from "./types";
-import { classifyError, type OcxErrorPayload } from "./lib/errors";
+import { adapterFailureFromMessage, classifyError, type OcxErrorPayload } from "./lib/errors";
 import { encodeCompactionSummary } from "./responses/compaction";
 import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
 import { usageDisplayTotalTokens, usageInputTokensWithCacheDetail } from "./usage/totals";
@@ -20,8 +20,15 @@ function responsesUsage(usage: OcxUsage | undefined): Record<string, unknown> {
     output_tokens: usage.outputTokens,
     total_tokens: usageDisplayTotalTokens(usage) ?? inputTokens + usage.outputTokens,
   };
+  const inputDetails: Record<string, number> = {};
   if (usage.cachedInputTokens !== undefined) {
-    out.input_tokens_details = { cached_tokens: usage.cachedInputTokens };
+    inputDetails.cached_tokens = usage.cachedInputTokens;
+  }
+  if (usage.cacheCreationInputTokens !== undefined) {
+    inputDetails.cache_write_tokens = usage.cacheCreationInputTokens;
+  }
+  if (Object.keys(inputDetails).length > 0) {
+    out.input_tokens_details = inputDetails;
   }
   if (usage.reasoningOutputTokens !== undefined) {
     out.output_tokens_details = { reasoning_tokens: usage.reasoningOutputTokens };
@@ -33,6 +40,8 @@ function responseError(status: number, type: string, message: string): OcxErrorP
   return classifyError(status, type, message);
 }
 
+export { adapterFailureFromMessage } from "./lib/errors";
+
 /**
  * Build the native `WebSearchAction::Search` payload from the queries that ran. codex-rs prefers a
  * non-empty `query` over `queries` for the cell label, and only renders "<first> ..." when `query`
@@ -177,6 +186,7 @@ export function bridgeToResponsesSSE(
           if (currentMsg) closeCurrentMessage();
           if (currentReasoning) closeCurrentReasoning();
           if (currentRawReasoning) closeCurrentRawReasoning();
+          flushHiddenRawReasoning();
           if (currentToolCall) closeCurrentToolCall();
           if (currentWebSearch) closeCurrentWebSearch("failed", []);
           emit("response.incomplete", {
@@ -229,6 +239,23 @@ export function bridgeToResponsesSSE(
         finishedItems.push(item as OutputItem);
         outputIndex++;
       };
+      // hideThinkingSummary for RAW reasoning (openai-chat reasoning_content, kiro tags): no
+      // visible reasoning item is emitted — the app renders nothing, so tool cells keep grouping
+      // like native models — but the text still round-trips in a txt-only ocxr1 envelope so
+      // preserveReasoningContentModels replay (GLM interleaved thinking) keeps working. Direct
+      // encodeReasoningEnvelope: takeReasoningEnvelope's sig/red guard would drop txt-only.
+      let hiddenRawReasoningText = "";
+      const flushHiddenRawReasoning = () => {
+        if (!hiddenRawReasoningText) return;
+        const encrypted = encodeReasoningEnvelope({ txt: hiddenRawReasoningText });
+        hiddenRawReasoningText = "";
+        const itemId = `rs_${uuid()}`;
+        const item = { type: "reasoning", id: itemId, summary: [] as never[], encrypted_content: encrypted };
+        emit("response.output_item.added", { output_index: outputIndex, item });
+        emit("response.output_item.done", { output_index: outputIndex, item });
+        finishedItems.push(item as OutputItem);
+        outputIndex++;
+      };
       // Full assistant text of a compaction turn (across message boundaries) — becomes the
       // synthetic compaction item's payload on done.
       let compactionText = "";
@@ -385,6 +412,7 @@ export function bridgeToResponsesSSE(
             case "text_delta": {
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (!currentMsg) {
                 const itemId = `msg_${uuid()}`;
@@ -410,6 +438,7 @@ export function bridgeToResponsesSSE(
               if (options?.hideThinkingSummary) { hiddenThinkingText += event.thinking; break; }
               if (currentMsg) closeCurrentMessage();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (!currentReasoning) {
                 const itemId = `rs_${uuid()}`;
@@ -441,6 +470,7 @@ export function bridgeToResponsesSSE(
               break;
             }
             case "reasoning_raw_delta": {
+              if (options?.hideThinkingSummary) { hiddenRawReasoningText += event.text; break; }
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentToolCall) closeCurrentToolCall();
@@ -461,6 +491,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               const itemId = `fc_${uuid()}`;
               const mapped = toolNsMap?.get(event.name);
@@ -515,6 +546,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
               emit("response.output_item.added", {
@@ -549,6 +581,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
               // Redacted-only turns (or hidden thinking without a trailing signature event) still
@@ -577,16 +610,18 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("failed", []);
+              const failure = adapterFailureFromMessage(event.message);
               emit("response.failed", {
                 response: {
                   ...responseSnapshot("failed", finishedItems),
                   // Partial consumption from a mid-stream upstream failure: surfaced so the request
                   // log can record real tokens instead of usageStatus "unreported" with 0.
                   ...(event.usage ? { usage: responsesUsage(event.usage) } : {}),
-                  error: responseError(502, "upstream_error", event.message),
-                  last_error: responseError(502, "upstream_error", event.message),
+                  error: failure.error,
+                  last_error: failure.error,
                 },
               });
               reportTerminal("failed");
@@ -596,6 +631,7 @@ export function bridgeToResponsesSSE(
           }
         }
       } catch (err) {
+        flushHiddenRawReasoning();
         if (currentWebSearch) closeCurrentWebSearch("failed", []);
         emit("response.failed", {
           response: {
@@ -616,6 +652,7 @@ export function bridgeToResponsesSSE(
         if (currentMsg) closeCurrentMessage();
         if (currentReasoning) closeCurrentReasoning();
         if (currentRawReasoning) closeCurrentRawReasoning();
+        flushHiddenRawReasoning();
         if (currentToolCall) closeCurrentToolCall();
         if (currentWebSearch) closeCurrentWebSearch("failed", []);
         emit("response.incomplete", {
@@ -716,6 +753,15 @@ export function buildResponseJSON(
   };
   const flushRawReasoning = () => {
     if (!currentRawReasoning) return;
+    if (options?.hideThinkingSummary === true) {
+      // Same contract as the streaming path: no visible reasoning, txt-only envelope round-trip.
+      output.push({
+        type: "reasoning", id: `rs_${uuid()}`, summary: [],
+        encrypted_content: encodeReasoningEnvelope({ txt: currentRawReasoning }),
+      });
+      currentRawReasoning = "";
+      return;
+    }
     output.push({
       type: "reasoning", id: `rs_${uuid()}`, summary: [],
       content: [{ type: "reasoning_text", text: currentRawReasoning }],

package/src/cli/debug.ts

@@ -0,0 +1,203 @@
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { DEBUG_ENV, type DebugSettingsView } from "../lib/debug-settings";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+
+type DebugScope = "provider" | "usage";
+
+async function requireLiveProxy() {
+  const live = await findLiveProxy();
+  if (!live) {
+    console.error("Proxy is not running. Start it with: ocx start");
+    process.exit(1);
+  }
+  return live;
+}
+
+async function fetchDebugSettings(): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  try {
+    const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+      headers: runningProxyUpdateHeaders(),
+    });
+    if (!res.ok) {
+      console.error(`Failed to read debug settings (${res.status})`);
+      process.exit(1);
+    }
+    return await res.json() as DebugSettingsView;
+  } catch (err) {
+    console.error(`Proxy is running but /api/debug is unreachable: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+async function putDebugSettings(body: Record<string, unknown>): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+    method: "PUT",
+    headers: runningProxyUpdateHeaders(),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(`Failed to update debug settings (${res.status})${text ? `: ${text.slice(0, 200)}` : ""}`);
+    process.exit(1);
+  }
+  return await res.json() as DebugSettingsView;
+}
+
+function printScopeStatus(scope: DebugScope, view: DebugSettingsView): void {
+  if (scope === "provider") {
+    console.log(`Provider debug: ${view.enabled ? "ON" : "off"}`);
+    console.log(`  env=${view.env.debug ? "on" : "off"}, runtime=${view.runtimeOverride.debug === undefined ? "env/default" : view.runtimeOverride.debug ? "on" : "off"}`);
+    console.log("  Tail: ocx debug provider logs [-f]");
+  } else {
+    console.log(`Usage debug: ${view.usage ? "ON" : "off"}`);
+    console.log(`  env=${view.env.usage ? "on" : "off"}, runtime=${view.runtimeOverride.usage === undefined ? "env/default" : view.runtimeOverride.usage ? "on" : "off"}`);
+    console.log("  Tail: ocx debug usage logs [-f] (via running proxy API)");
+  }
+}
+
+function envDebugEnabled(): boolean {
+  return process.env.OCX_DEBUG === "1"
+    || process.env.OCX_DEBUG_FRAMES === "1";
+}
+
+async function printProviderLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function printUsageLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/usage-logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read usage debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length === 0) console.log("(empty — enable with: ocx debug usage on)");
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read usage debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Promise<void> {
+  const action = (actionArgv[0] ?? "status").trim().toLowerCase();
+
+  if (action === "on" || action === "off") {
+    const enabled = action === "on";
+    const body = scope === "provider" ? { debug: enabled } : { usage: enabled };
+    printScopeStatus(scope, await putDebugSettings(body));
+    console.log(`\n${scope} debug is now ${enabled ? "enabled" : "disabled"}.`);
+    return;
+  }
+
+  if (action === "status") {
+    printScopeStatus(scope, await fetchDebugSettings());
+    return;
+  }
+
+  if (action === "reset") {
+    const resetKey = scope === "provider" ? "provider" : "usage";
+    printScopeStatus(scope, await putDebugSettings({ reset: resetKey }));
+    console.log(`\nRuntime override cleared for ${scope}; effective value follows env again.`);
+    return;
+  }
+
+  if (action === "logs") {
+    const follow = actionArgv.slice(1).some(arg => arg === "-f" || arg === "--follow");
+    if (scope === "provider") await printProviderLogs(follow);
+    else await printUsageLogs(follow);
+    return;
+  }
+
+  console.error(`Usage: ocx debug ${scope} on|off|status|reset|logs [-f]`);
+  process.exit(1);
+}
+
+function printTopLevelHelp(): void {
+  console.log("Debug commands (proxy must be running):");
+  console.log("");
+  console.log("  ocx debug provider on|off|status|reset|logs [-f]");
+  console.log("  ocx debug usage on|off|status|reset|logs [-f]");
+  console.log("");
+  console.log("Env defaults on start:");
+  console.log("  provider → OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)");
+  console.log(`  usage    → ${DEBUG_ENV.usage}=1`);
+}
+
+export async function handleDebugCommand(argv: string[]): Promise<void> {
+  const sub = (argv[0] ?? "").trim().toLowerCase();
+
+  if (sub === "provider" || sub === "usage") {
+    await handleScopeCommand(sub, argv.slice(1));
+    return;
+  }
+
+  if (sub === "" || sub === "help" || sub === "--help" || sub === "-h") {
+    const live = await findLiveProxy();
+    if (!live) {
+      console.log("Proxy is not running — env defaults for the next start:");
+      console.log(`  provider → OCX_DEBUG = ${envDebugEnabled() ? "on" : "off"}`);
+      console.log(`  usage    → ${DEBUG_ENV.usage} = ${process.env[DEBUG_ENV.usage] === "1" ? "on" : "off"}`);
+      console.log("");
+    }
+    printTopLevelHelp();
+    return;
+  }
+
+  printTopLevelHelp();
+  process.exit(1);
+}

package/src/cli/doctor.ts

@@ -15,6 +15,7 @@ import { readCodexTokens } from "../codex/auth-collision";
 import { resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
 import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
+import { collectProjectCodexConfigWarnings, formatProjectCodexConfigWarningsForDoctor } from "../codex/project-config-warnings";
 export { resolveCodexHomeDir } from "../codex/home";
 
 const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
@@ -373,6 +374,16 @@ export async function runDoctor(): Promise<void> {
     console.log(`  --     ${pending.pendingRows} thread(s) still tagged opencodex, ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"}`);
   }
 
+  console.log("\nProject Codex configs");
+  const projectWarnings = collectProjectCodexConfigWarnings();
+  if (projectWarnings.length === 0) {
+    console.log("  ok     no project-local provider bypass detected");
+  } else {
+    for (const line of formatProjectCodexConfigWarningsForDoctor(projectWarnings)) {
+      console.log(line);
+    }
+  }
+
   const dual = collectWslDualInstall();
   if (dual.wsl) {
     console.log("\nWSL Codex installs");

package/src/cli/help.ts

@@ -54,6 +54,15 @@ const helpEntries: Record<string, HelpEntry> = {
   "sync-cache": { usage: "ocx sync-cache", summary: "Refresh Codex's model cache from the active catalog." },
   status: { usage: "ocx status", summary: "Check proxy server status." },
   doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
+  debug: {
+    usage: "ocx debug [provider on|off|status|reset|logs [-f]|usage on|off|status|reset|logs [-f]]",
+    summary: "Show or toggle runtime provider debug logging on the running proxy.",
+    details: [
+      "Provider: ocx debug provider on | off | status | reset | logs [-f]",
+      "Usage JSONL: ocx debug usage on | off | status | reset | logs [-f]",
+      "Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
+    ],
+  },
   login: { usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
   logout: { usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
   gui: { usage: "ocx gui", summary: "Open the opencodex dashboard." },
@@ -115,6 +124,8 @@ Usage:
   ocx sync-cache              Refresh Codex's model cache from the active catalog
   ocx status                  Check proxy server status
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
+  ocx debug [provider|usage ...]
+                              provider/usage on|off|status|reset|logs [-f]
   ocx login <provider>        OAuth login (xai) — opens browser, stores token in ~/.opencodex/auth.json
   ocx logout <provider>       Remove a stored OAuth login
   ocx gui                     Open the opencodex dashboard

package/src/cli/index.ts

@@ -449,6 +449,11 @@ switch (command) {
     await runDoctor();
     break;
   }
+  case "debug": {
+    const { handleDebugCommand } = await import("./debug");
+    await handleDebugCommand(args.slice(1));
+    break;
+  }
   case "ensure":
     await handleEnsure();
     break;
@@ -468,6 +473,11 @@ switch (command) {
     await syncModelsToCodex((await findLiveProxy())?.port);
     break;
   }
+  case "v2": {
+    const { cmdV2 } = await import("./v2");
+    process.exitCode = await cmdV2(args.slice(1), {}, async () => (await findLiveProxy())?.port);
+    break;
+  }
   case "sync-cache": {
     const { invalidateCodexModelsCache } = await import("../codex/catalog");
     invalidateCodexModelsCache();

package/src/cli/v2.ts

@@ -0,0 +1,131 @@
+/**
+ * `ocx v2 status|on|off` — toggle/report the codex `multi_agent_v2` feature that
+ * controls the multi-agent surface (v1 vs v2 collab mode).
+ *
+ * Contract:
+ *  - 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.
+ *  - 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 { loadConfig, saveConfig } from "../config";
+
+export interface V2CliDeps {
+  execFile?: (file: string, args: string[]) => void;
+  isEnabled?: typeof isMultiAgentV2Enabled;
+  hasMaxThreads?: typeof hasAgentsMaxThreads;
+  sync?: (port?: number) => Promise<unknown>;
+  log?: Pick<Console, "log" | "error">;
+}
+
+function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
+  const exec = deps.execFile ?? ((file: string, args: string[]) => {
+    execFileSync(file, args, { stdio: ["ignore", "pipe", "pipe"], timeout: 15_000, windowsHide: true });
+  });
+  const command = process.env.CODEX_CLI_PATH?.trim() || "codex";
+  exec(command, ["features", action, "multi_agent_v2"]);
+}
+
+export function v2StatusLine(enabled: boolean): string {
+  return enabled
+    ? "multi_agent_v2: ON — v2 multi-agent surface active"
+    : "multi_agent_v2: OFF — v1 multi-agent surface (default install)";
+}
+
+export function multiAgentModeLine(mode: string): string {
+  switch (mode) {
+    case "v1": return "multi_agent_mode: v1 — ALL models forced to v1 surface (upstream pins overridden)";
+    case "v2": return "multi_agent_mode: v2 — ALL models forced to v2 surface (upstream pins overridden)";
+    default: return "multi_agent_mode: default — upstream model pins respected (sol/terra=v2, luna=v1, rest=codex flag)";
+  }
+}
+
+export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
+  const log = deps.log ?? console;
+  const isEnabled = deps.isEnabled ?? isMultiAgentV2Enabled;
+  const hasMaxThreads = deps.hasMaxThreads ?? hasAgentsMaxThreads;
+  const verb = (args[0] ?? "status").trim().toLowerCase();
+
+  if (verb === "status") {
+    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)"}`);
+    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).");
+    }
+    return 0;
+  }
+  if (verb === "threads") {
+    const value = Number((args[1] ?? "").trim());
+    if (!Number.isInteger(value) || value < 1) {
+      log.error("v2 threads: pass an integer >= 1 (features.multi_agent_v2.max_concurrent_threads_per_session)");
+      return 1;
+    }
+    const result = setMaxConcurrentThreads(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.`);
+    return 0;
+  }
+  if (verb === "mode") {
+    const modeArg = (args[1] ?? "").trim().toLowerCase();
+    if (modeArg !== "v1" && modeArg !== "default" && modeArg !== "v2") {
+      log.error("v2 mode: expected v1|default|v2");
+      return 1;
+    }
+    const cfg = loadConfig();
+    if (modeArg === "default") delete cfg.multiAgentMode;
+    else cfg.multiAgentMode = modeArg as "v1" | "v2";
+    saveConfig(cfg);
+    try {
+      const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
+      await sync(findPort ? await findPort() : undefined);
+    } catch (err) {
+      log.error(`catalog resync failed: ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
+      return 1;
+    }
+    log.log(multiAgentModeLine(modeArg));
+    log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version.");
+    return 0;
+  }
+  if (verb !== "on" && verb !== "off") {
+    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|threads <n>)`);
+    return 1;
+  }
+
+  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)}`);
+    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).");
+  }
+
+  // Resync catalog so multi-agent surface metadata stays fresh in both the
+  // on-disk catalog and models_cache.json after the toggle flip.
+  try {
+    const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
+    await sync(findPort ? await findPort() : undefined);
+  } catch (err) {
+    log.error(`catalog resync failed (flag IS flipped): ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
+    return 1;
+  }
+  log.log(v2StatusLine(want));
+  log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version. Restart the Codex app (or wait out its picker cache) to see the ladder change.");
+  return 0;
+}

package/src/codex/account-store.ts

@@ -44,7 +44,10 @@ function isCredentialRecord(value: unknown): value is CodexAccountCredentialReco
     && (value.credential === undefined || isCredential(value.credential))
     && (value.refreshGrantFingerprint === undefined || typeof value.refreshGrantFingerprint === "string")
     && (value.deletedAt === undefined || typeof value.deletedAt === "number")
-    && (value.replacedAt === undefined || typeof value.replacedAt === "number");
+    && (value.replacedAt === undefined || typeof value.replacedAt === "number")
+    && (value.lastCodexValidatedAt === undefined || typeof value.lastCodexValidatedAt === "number")
+    && (value.lastCodexValidationStatus === undefined || value.lastCodexValidationStatus === "ok" || value.lastCodexValidationStatus === "failed")
+    && (value.lastCodexValidationError === undefined || typeof value.lastCodexValidationError === "string");
 }
 
 export function refreshGrantFingerprintForToken(refreshToken: string): string {
@@ -98,6 +101,17 @@ function persist(store: CodexAccountStore): void {
   atomicWriteFile(codexAccountsPath(), JSON.stringify(store, null, 2) + "\n");
 }
 
+function preservedValidationMetadata(record: CodexAccountCredentialRecord | undefined): Pick<
+  CodexAccountCredentialRecord,
+  "lastCodexValidatedAt" | "lastCodexValidationStatus" | "lastCodexValidationError"
+> {
+  return {
+    ...(record?.lastCodexValidatedAt !== undefined ? { lastCodexValidatedAt: record.lastCodexValidatedAt } : {}),
+    ...(record?.lastCodexValidationStatus !== undefined ? { lastCodexValidationStatus: record.lastCodexValidationStatus } : {}),
+    ...(record?.lastCodexValidationError !== undefined ? { lastCodexValidationError: record.lastCodexValidationError } : {}),
+  };
+}
+
 export function getCodexAccountCredential(id: string): CodexAccountCredentials | null {
   const record = readCodexAccountRecord(id);
   if (!record || record.deletedAt != null) return null;
@@ -115,6 +129,32 @@ export function saveCodexAccountCredential(id: string, cred: CodexAccountCredent
     generation: (current?.generation ?? 0) + 1,
     refreshGrantFingerprint,
     replacedAt: current ? Date.now() : undefined,
+    ...preservedValidationMetadata(current),
+  };
+  persist(store);
+}
+
+export function markCodexAccountValidated(id: string, atMs: number = Date.now()): void {
+  const store = loadCodexAccountRecordStore();
+  const current = store[id];
+  if (!current || current.deletedAt != null || !current.credential) return;
+  store[id] = {
+    ...current,
+    lastCodexValidatedAt: atMs,
+    lastCodexValidationStatus: "ok",
+    lastCodexValidationError: undefined,
+  };
+  persist(store);
+}
+
+export function markCodexAccountValidationFailed(id: string, reason: string): void {
+  const store = loadCodexAccountRecordStore();
+  const current = store[id];
+  if (!current || current.deletedAt != null || !current.credential) return;
+  store[id] = {
+    ...current,
+    lastCodexValidationStatus: "failed",
+    lastCodexValidationError: reason,
   };
   persist(store);
 }
@@ -154,6 +194,7 @@ export function saveCodexAccountCredentialIfGeneration(
     generation: generation + 1,
     refreshGrantFingerprint,
     replacedAt: current.replacedAt,
+    ...preservedValidationMetadata(current),
   };
   persist(store);
   return true;