@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/usage-report.ts

@@ -12,6 +12,8 @@
  * (as in `formatAccountTable`), plain text, no ANSI colour.
  */
 
+import type { UsageModelView } from "./usage-model-search";
+
 interface CostRow {
   provider: string;
   model?: string;
@@ -43,7 +45,7 @@ interface UsageReportInput {
   models?: CostRow[];
   providers?: CostRow[];
   days?: { date: string; requests: number; totalTokens: number; estimatedCostUsd?: number }[];
-  filter?: { provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
+  filter?: { apiKeyId?: string | null; provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
   /**
    * Per-account totals the API already returns and the CLI discarded (#2700).
    *
@@ -106,11 +108,12 @@ function describeScope(data: UsageReportInput): string {
   const parts = [`Usage — ${interval}`];
   if (data.surface && data.surface !== "all") parts.push(`surface=${data.surface}`);
   if (data.filter?.provider) parts.push(`provider=${data.filter.provider}`);
+  if (data.filter?.apiKeyId) parts.push(`api-key-id=${data.filter.apiKeyId}`);
   if (data.filter?.model) parts.push(`model=${data.filter.model}`);
   return terminalText(parts.join(", "));
 }
 
-export function formatUsageReport(data: UsageReportInput): string[] {
+export function formatUsageReport(data: UsageReportInput, options?: { modelView?: UsageModelView }): string[] {
   const summary = data.summary ?? {};
   const lines: string[] = [describeScope(data), ""];
   if (data.source === "hub" && data.scope === "client") {
@@ -119,9 +122,14 @@ export function formatUsageReport(data: UsageReportInput): string[] {
   if (data.usageIncomplete === true) {
     lines.push("WARNING: Usage is incomplete; some records could not be included. Totals and rankings reflect readable records only.", "");
   }
+  const view = options?.modelView;
+  if (view) {
+    lines.push(`Model search ${JSON.stringify(view.query)}: ${view.returnedModelCount} of ${view.matchedModelCount} matching model rows (limit ${view.limit}). Report totals are unchanged.`, "");
+    if (view.matchedModelCount === 0) lines.push("No model rows match this search. Change --search or use --search= to show the model view.", "");
+  }
 
   if (data.filter && !data.filter.matched) {
-    const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
+    const what = [data.filter.apiKeyId && `API key "${data.filter.apiKeyId}"`, data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
       .filter(Boolean).join(" and ");
     lines.push(data.usageIncomplete === true
       ? `No matching readable usage records for ${terminalText(what)} in this range; skipped records may contain matches.`
@@ -181,10 +189,10 @@ export function formatUsageReport(data: UsageReportInput): string[] {
     ));
   }
 
-  const models = (data.models ?? []).filter(row => row.requests > 0);
+  const models = view ? (data.models ?? []) : (data.models ?? []).filter(row => row.requests > 0);
   if (models.length > 0) {
     lines.push("");
-    const shown = models.slice(0, MAX_MODEL_ROWS);
+    const shown = models.slice(0, view?.limit ?? MAX_MODEL_ROWS);
     lines.push(...table(
       ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
       shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),

package/src/cli/v2-input.ts

@@ -0,0 +1,66 @@
+import { CliUsageError } from "./runtime-api";
+
+type V2Controls = { json: boolean; live: boolean; acknowledge: boolean };
+export type V2ParsedCommand = V2Controls & (
+  | { verb: "status" | "on" | "off" }
+  | { verb: "mode"; value: "v1" | "default" | "v2" }
+  | { verb: "keep-native-v1"; value: boolean }
+  | { verb: "threads"; value: number }
+  | { verb: "mode-hint"; value: string | null }
+);
+
+export const V2_USAGE = "Usage: ocx v2 [status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>] [--live] [--json]\nFor literal reserved hint text: ocx v2 mode-hint [--live] [--json] -- <text>\nOnly live mode accepts --acknowledge-surface-advisory.";
+
+/** Parse all controls before touching native/config state. A terminator protects literal hints. */
+export function parseV2Command(argv: readonly string[]): V2ParsedCommand {
+  const boundary = argv.indexOf("--");
+  const prefix = boundary < 0 ? argv : argv.slice(0, boundary);
+  const suffix = boundary < 0 ? [] : argv.slice(boundary + 1);
+  const controls: V2Controls = { json: false, live: false, acknowledge: false };
+  const operands: string[] = [];
+  for (const arg of prefix) {
+    const flag = arg === "--json" ? "json" : arg === "--live" ? "live"
+      : arg === "--acknowledge-surface-advisory" ? "acknowledge" : undefined;
+    if (["--json=", "--live=", "--acknowledge-surface-advisory="].some(prefix => arg.startsWith(prefix))) {
+      throw new CliUsageError("v2: control flags do not take values; use -- for literal hint text", V2_USAGE);
+    }
+    if (flag) {
+      if (controls[flag]) throw new CliUsageError("v2: duplicate control flag", V2_USAGE);
+      controls[flag] = true;
+    } else operands.push(arg);
+  }
+  const verb = (operands.shift() ?? "status").trim().toLowerCase();
+  const invalid = (message: string): never => { throw new CliUsageError(message, V2_USAGE); };
+  if (controls.acknowledge && (!controls.live || verb !== "mode")) {
+    invalid("v2: advisory acknowledgment requires explicit live mode");
+  }
+  if (boundary >= 0 && (verb !== "mode-hint" || operands.length !== 0 || suffix.length !== 1)) {
+    invalid("v2: the terminator requires exactly one literal mode-hint operand");
+  }
+  if (verb === "status" || verb === "on" || verb === "off") {
+    if (operands.length) invalid("v2: unexpected operands or flags");
+    return { ...controls, verb };
+  }
+  const values = boundary >= 0 ? suffix : operands;
+  if (values.length !== 1) invalid(verb === "keep-native-v1" ? "v2 keep-native-v1: expected on|off" : "v2: exactly one value is required");
+  const raw = values[0]!;
+  if (verb === "mode-hint") {
+    if (!raw.trim()) invalid("v2 mode-hint: pass nonblank text, or --clear to unset it");
+    // Legacy unreserved hyphen-leading hint strings remain ordinary content.
+    return { ...controls, verb, value: boundary < 0 && raw === "--clear" ? null : raw };
+  }
+  const value = raw.trim().toLowerCase();
+  if (verb === "mode" && (value === "v1" || value === "default" || value === "v2")) {
+    return { ...controls, verb, value };
+  }
+  if (verb === "keep-native-v1" && (value === "on" || value === "off")) {
+    return { ...controls, verb, value: value === "on" };
+  }
+  if (verb === "keep-native-v1") invalid("v2 keep-native-v1: expected on|off");
+  if (verb === "threads") {
+    const count = Number(value);
+    if (Number.isSafeInteger(count) && count >= 1) return { ...controls, verb, value: count };
+    invalid("v2 threads: pass a safe integer >= 1");
+  }
+  return invalid("v2: invalid command or value");
+}

package/src/cli/v2-local-output.ts

@@ -0,0 +1,37 @@
+import { loadConfig } from "../config";
+import { multiAgentSurfaceAdvisory, resolveMultiAgentMode } from "../config/multi-agent-surface";
+import { getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText,
+  getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled } from "../codex/features";
+import { MULTI_AGENT_MODE_HINT_RECOMMENDATION } from "../codex/multi-agent-mode-policy";
+import type { CodexSyncResult } from "../codex/sync";
+import { projectLocalSyncResult, type LocalSyncResult } from "./local-sync-result";
+
+/** Rebuild local state from actual post-write readers; no paths, credentials, or logs. */
+export function localV2State(isEnabled = isMultiAgentV2Enabled, hasMaxThreads = hasAgentsMaxThreads) {
+  const config = loadConfig();
+  const enabled = isEnabled();
+  return { enabled, agentsMaxThreadsConflict: enabled && hasMaxThreads(),
+    multiAgentMode: resolveMultiAgentMode(config), keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
+    multiAgentSurfaceAdvisory: multiAgentSurfaceAdvisory(config), maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
+    agentsEnabled: getAgentsEnabled(), agentsMaxDepth: getAgentsMaxDepth(),
+    agentsMaxDepthAppliesWhenV2Disabled: !enabled, subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+    multiAgentModeHintText: getMultiAgentModeHintText(), multiAgentModeHintRecommendation: MULTI_AGENT_MODE_HINT_RECOMMENDATION };
+}
+
+export type V2LocalSync = LocalSyncResult | { status: "unverified"; ok: false };
+
+/** The existing injected sync contract returns unknown. Validate before the typed shared projection. */
+export function v2LocalSyncResult(value: unknown): V2LocalSync {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { status: "unverified", ok: false };
+  const source = value as Record<string, unknown>;
+  if (typeof source.status !== "string" || !["applied", "catalog-only", "skipped", "refused"].includes(source.status)
+    || typeof source.ok !== "boolean" || typeof source.catalogExists !== "boolean"
+    || typeof source.catalogWritten !== "boolean" || typeof source.cacheSynced !== "boolean"
+    || typeof source.added !== "number" || !Number.isSafeInteger(source.added) || source.added < 0
+    || (source.catalogPath !== null && typeof source.catalogPath !== "string") || typeof source.message !== "string"
+    || (source.refreshOutcome !== undefined && source.refreshOutcome !== "committed" && source.refreshOutcome !== "refused")) {
+    return { status: "unverified", ok: false };
+  }
+  // The checked fields are the complete mandatory backend contract. Private text is never emitted.
+  return projectLocalSyncResult(source as unknown as CodexSyncResult);
+}

package/src/cli/v2-runtime.ts

@@ -0,0 +1,90 @@
+import { SUBAGENT_SURFACE_GUIDE_URL } from "../config/multi-agent-surface";
+import { printCatalogResult, runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+import { RuntimeApiError, printData, runtimeBaseUrl, runtimeRequest, type RuntimeApiDeps } from "./runtime-api";
+import type { V2ParsedCommand } from "./v2-input";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function mode(value: unknown): value is "v1" | "default" | "v2" {
+  return value === "v1" || value === "default" || value === "v2";
+}
+function nullableString(value: unknown): value is string | null { return value === null || typeof value === "string"; }
+
+/** Allowlisted task fields only: neither helper errors nor arbitrary response spreads. */
+function stateDto(value: unknown): Record<string, unknown> {
+  if (!record(value) || !mode(value.multiAgentMode)) throw new Error("Invalid v2 state");
+  const result: Record<string, unknown> = { multiAgentMode: value.multiAgentMode };
+  for (const key of ["enabled", "agentsMaxThreadsConflict", "keepNativeChatGptOnV1", "agentsMaxDepthAppliesWhenV2Disabled"] as const) {
+    if (typeof value[key] !== "boolean") throw new Error("Invalid v2 boolean");
+    result[key] = value[key];
+  }
+  if (value.agentsEnabled !== null && typeof value.agentsEnabled !== "boolean") throw new Error("Invalid agents state");
+  if (value.maxConcurrentThreadsPerSession !== null && !(typeof value.maxConcurrentThreadsPerSession === "number"
+    && Number.isSafeInteger(value.maxConcurrentThreadsPerSession) && value.maxConcurrentThreadsPerSession >= 1)) throw new Error("Invalid thread state");
+  if (value.agentsMaxDepth !== null && !(typeof value.agentsMaxDepth === "number" && Number.isInteger(value.agentsMaxDepth)
+    && value.agentsMaxDepth >= -2147483648 && value.agentsMaxDepth <= 2147483647)) throw new Error("Invalid depth state");
+  for (const key of ["subagentDeveloperInstructions", "multiAgentModeHintText"] as const) {
+    if (!nullableString(value[key])) throw new Error("Invalid text state");
+    result[key] = value[key];
+  }
+  const recommendation = value.multiAgentModeHintRecommendation;
+  if (!record(recommendation) || typeof recommendation.revision !== "string" || typeof recommendation.text !== "string") throw new Error("Invalid hint recommendation");
+  const advisory = value.multiAgentSurfaceAdvisory;
+  if (!record(advisory) || typeof advisory.required !== "boolean" || advisory.mode !== value.multiAgentMode
+    || advisory.recommended !== "v1" || typeof advisory.version !== "number" || !Number.isSafeInteger(advisory.version)
+    || advisory.version < 1 || advisory.docsUrl !== SUBAGENT_SURFACE_GUIDE_URL) throw new Error("Invalid surface advisory");
+  return { ...result, agentsEnabled: value.agentsEnabled, agentsMaxDepth: value.agentsMaxDepth,
+    maxConcurrentThreadsPerSession: value.maxConcurrentThreadsPerSession,
+    multiAgentModeHintRecommendation: { revision: recommendation.revision, text: recommendation.text },
+    multiAgentSurfaceAdvisory: { required: advisory.required, mode: advisory.mode, recommended: "v1",
+      version: advisory.version, docsUrl: advisory.docsUrl } };
+}
+
+function bodyFor(parsed: V2ParsedCommand): Record<string, unknown> {
+  switch (parsed.verb) {
+    case "on": case "off": return { enabled: parsed.verb === "on" };
+    case "mode": return { multiAgentMode: parsed.value,
+      ...(parsed.acknowledge ? { multiAgentSurfaceAdvisoryAcknowledged: true } : {}) };
+    case "keep-native-v1": return { keepNativeChatGptOnV1: parsed.value };
+    case "threads": return { maxConcurrentThreadsPerSession: parsed.value };
+    case "mode-hint": return { multiAgentModeHintText: parsed.value };
+    case "status": return {};
+  }
+}
+
+export async function handleV2RuntimeCommand(parsed: V2ParsedCommand, deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const read = parsed.verb === "status";
+    const body = read ? undefined : serializeManagementJson(bodyFor(parsed));
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    let response: unknown;
+    try {
+      response = await runtimeRequest("/api/v2", { method: read ? "GET" : "PUT", redirect: "error", ...(body ? { body } : {}) }, pinned);
+    } catch (error) {
+      if (error instanceof RuntimeApiError && error.status === 502) {
+        console.error("Error: Native V2 settings may be partially applied. Read ocx v2 status --live before retrying; no rollback is implied.");
+        return 1;
+      }
+      throw error;
+    }
+    const state = stateDto(response);
+    const lines = [`multi_agent_v2: ${state.enabled ? "ON" : "OFF"}`, `multi_agent_mode: ${state.multiAgentMode}`,
+      `keep_native_chatgpt_on_v1: ${state.keepNativeChatGptOnV1 ? "ON" : "OFF"}`,
+      `max_threads: ${state.maxConcurrentThreadsPerSession ?? "unset"}`,
+      `agents.enabled: ${state.agentsEnabled ?? "unset (upstream default)"}`,
+      `agents.max_depth: ${state.agentsMaxDepth ?? "unset"}${state.enabled ? " (V1-only — ignored while V2 is enabled)" : ""}`,
+      `subagent_developer_instructions: ${JSON.stringify(state.subagentDeveloperInstructions)}`,
+      `multi_agent_mode_hint_text: ${JSON.stringify(state.multiAgentModeHintText)}`];
+    if (state.agentsMaxThreadsConflict) lines.push("Native thread-limit conflict: inspect the selected target's Codex configuration before starting Codex.");
+    if (state.enabled && state.agentsEnabled === false) lines.push("agents.enabled=false does not disable multi-agent while the global V2 feature is enabled.");
+    if (record(state.multiAgentSurfaceAdvisory) && state.multiAgentSurfaceAdvisory.required) {
+      lines.push(`Surface advisory: v1 is recommended. ${SUBAGENT_SURFACE_GUIDE_URL}`);
+    }
+    if (read) { printData({ target: "live", ...state }, parsed.json, lines); return 0; }
+    if (!record(response) || response.ok !== true) throw new Error("Invalid write receipt");
+    return printCatalogResult({ ok: true, target: "live", ...state }, response.catalogRefresh, parsed.json,
+      [...lines, "V2 settings saved. Applies to new sessions."]);
+  });
+}

package/src/cli/v2.ts

@@ -10,6 +10,10 @@
  *    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 { CliUsageError, terminalSafeText, type RuntimeApiDeps } from "./runtime-api";
+import { parseV2Command, V2_USAGE, type V2ParsedCommand } from "./v2-input";
+import { handleV2RuntimeCommand } from "./v2-runtime";
+import { localV2State, v2LocalSyncResult, type V2LocalSync } from "./v2-local-output";
 import { execFileSync } from "node:child_process";
 import { dirname } from "node:path";
 import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
@@ -23,6 +27,9 @@ export interface V2CliDeps {
   isEnabled?: typeof isMultiAgentV2Enabled;
   hasMaxThreads?: typeof hasAgentsMaxThreads;
   sync?: (port?: number) => Promise<unknown>;
+  runtimeApi?: RuntimeApiDeps;
+  /** Internal seam: bypass executable discovery only when an exec implementation is injected. */
+  featuresInvocation?: (action: "enable" | "disable") => SpawnInvocation;
   log?: Pick<Console, "log" | "error">;
 }
 
@@ -79,7 +86,7 @@ export function runCodexFeaturesCommand(
 
 function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
   if (deps.execFile) {
-    const inv = codexFeaturesInvocation(action);
+    const inv = (deps.featuresInvocation ?? codexFeaturesInvocation)(action);
     deps.execFile(inv.file, inv.args, inv.options);
     return;
   }
@@ -106,13 +113,10 @@ function requiresGlobalV2Disabled(multiAgentMode: string | undefined, keepNative
   return multiAgentMode === "v2" && keepNativeChatGptOnV1;
 }
 
-export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
+function printLocalStatus(deps: V2CliDeps): 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();
     const mode = cfg.multiAgentMode ?? "default";
@@ -140,153 +144,107 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       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;
+}
+
+/** Parse before selecting either the native writer or the runtime management target. */
+export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
+  const log = deps.log ?? console;
+  let parsed: V2ParsedCommand;
+  try { parsed = parseV2Command(args); }
+  catch (error) {
+    log.error(error instanceof CliUsageError ? error.message : "v2: invalid command");
+    for (const line of V2_USAGE.split("\n")) log.error(line);
+    const boundary = args.indexOf("--");
+    return (boundary < 0 ? args : args.slice(0, boundary)).includes("--live") ? 2 : 1;
   }
-  if (verb === "mode-hint") {
-    const value = args[1];
-    if (value === undefined) {
-      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
-      return 1;
-    }
-    if (value === "--clear") {
-      const result = setMultiAgentModeHintText(null);
-      if (!result.ok) {
-        log.error(`v2 mode-hint: ${result.error}`);
-        return 1;
-      }
-      log.log(result.changed
-        ? "multi_agent_mode_hint_text cleared — effort-derived policy resumes (new sessions)."
-        : "multi_agent_mode_hint_text already unset — nothing to do.");
-      return 0;
-    }
-    // `--clear` is the only reserved token; hints are otherwise arbitrary
-    // nonblank text and may legitimately begin with a hyphen.
-    if (value.trim().length === 0) {
-      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
-      return 1;
-    }
-    const result = setMultiAgentModeHintText(value);
-    if (!result.ok) {
-      log.error(`v2 mode-hint: ${result.error}`);
-      return 1;
+  if (parsed.live) return handleV2RuntimeCommand(parsed, deps.runtimeApi);
+  let changed: boolean | null = false;
+  let sync: V2LocalSync = { status: "not-attempted", ok: false };
+  const emit = (ok: boolean, lines: string[]): number => {
+    // A read-back failure cannot claim rollback or overwrite already observed mutation evidence.
+    let state: ReturnType<typeof localV2State> | null = null;
+    try { state = localV2State(deps.isEnabled, deps.hasMaxThreads); }
+    catch { ok = false; lines = ["Local V2 outcome is unverified. Read ocx v2 status before retrying; no rollback is implied."]; }
+    if (parsed.json) log.log(JSON.stringify({ ok, target: "local", action: parsed.verb, changed, state, sync }));
+    else for (const line of lines) (ok ? log.log : log.error).call(log, terminalSafeText(line));
+    return ok ? 0 : 1;
+  };
+  try {
+    if (parsed.verb === "status") {
+      if (!parsed.json) return printLocalStatus(deps);
+      return emit(true, []);
     }
-    log.log(result.changed
-      ? `multi_agent_mode_hint_text set (new sessions).`
-      : "multi_agent_mode_hint_text already set — nothing to do.");
-    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;
+    if (parsed.verb === "mode-hint") {
+      const result = setMultiAgentModeHintText(parsed.value);
+      if (!result.ok) return emit(false, ["Unable to write the native mode hint. Check Codex support and ownership, then read ocx v2 status."]);
+      changed = result.changed;
+      return emit(true, [result.changed ? "multi_agent_mode_hint_text saved — applies to new sessions." : "multi_agent_mode_hint_text already set — nothing to do."]);
     }
-    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_threads = ${value} (${enabled ? "v2" : "v1"}) — applies to new sessions.`
-      : `max_threads 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;
+    if (parsed.verb === "threads") {
+      const enabled = (deps.isEnabled ?? isMultiAgentV2Enabled)();
+      const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: parsed.value });
+      if (!result.ok) return emit(false, ["Unable to update the native thread limit. Read ocx v2 status before retrying."]);
+      changed = result.changed;
+      return emit(true, [changed ? `max_threads = ${parsed.value} (${enabled ? "v2" : "v1"}) — applies to new sessions.` : `max_threads already ${parsed.value} — nothing to do.`]);
     }
-    const cfg = loadConfig();
-    if (modeArg !== "default") {
-      const target = modeArg === "v2" && cfg.keepNativeChatGptOnV1 !== true;
-      const transition = transitionMultiAgentV2(target, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
-      if (!transition.ok) {
-        log.error(`multi-agent mode transition failed: ${transition.error}`);
-        return 1;
+    const config = loadConfig();
+    let successLines: string[];
+    let unchangedKeep: boolean | undefined;
+    if (parsed.verb === "mode") {
+      changed = (config.multiAgentMode ?? "default") !== parsed.value;
+      if (parsed.value !== "default") {
+        const target = parsed.value === "v2" && config.keepNativeChatGptOnV1 !== true;
+        const transition = transitionMultiAgentV2(target, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        if (!transition.ok) { changed = false; return emit(false, ["Native mode transition failed. Read ocx v2 status before retrying."]); }
+        changed ||= transition.changed;
       }
-    }
-    if (modeArg === "default") deleteConfigTopLevelKey(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 === "keep-native-v1") {
-    const flag = (args[1] ?? "").trim().toLowerCase();
-    if (flag !== "on" && flag !== "off") {
-      log.error("v2 keep-native-v1: expected on|off");
-      return 1;
-    }
-    const cfg = loadConfig();
-    const next = flag === "on";
-    const already = cfg.keepNativeChatGptOnV1 === true === next;
-    if (next && requiresGlobalV2Disabled(cfg.multiAgentMode, true)) {
-      const transition = transitionMultiAgentV2(false, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
-      if (!transition.ok) {
-        log.error(`keep-native-v1 transition failed: ${transition.error}`);
-        return 1;
+      if (parsed.value === "default") deleteConfigTopLevelKey(config, "multiAgentMode");
+      else config.multiAgentMode = parsed.value;
+      saveConfig(config);
+      successLines = [multiAgentModeLine(parsed.value, config.keepNativeChatGptOnV1 === true),
+        "Applies to NEW sessions; running sessions keep their pinned multi-agent version."];
+    } else if (parsed.verb === "keep-native-v1") {
+      unchangedKeep = (config.keepNativeChatGptOnV1 === true) === parsed.value;
+      changed = !unchangedKeep;
+      if (parsed.value && requiresGlobalV2Disabled(config.multiAgentMode, true)) {
+        const transition = transitionMultiAgentV2(false, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        if (!transition.ok) { changed = false; return emit(false, ["Native hybrid-mode transition failed. Read ocx v2 status before retrying."]); }
+        changed ||= transition.changed;
+      }
+      if (parsed.value) config.keepNativeChatGptOnV1 = true;
+      else deleteConfigTopLevelKey(config, "keepNativeChatGptOnV1");
+      saveConfig(config);
+      successLines = [parsed.value
+        ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2 (new sessions)."
+        : "keep_native_chatgpt_on_v1: OFF — ChatGPT-native rows follow v1/base/v2 (new sessions)."];
+    } else {
+      const want = parsed.verb === "on";
+      if (want && requiresGlobalV2Disabled(config.multiAgentMode, config.keepNativeChatGptOnV1 === true)) {
+        return emit(false, ["v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first."]);
       }
+      const transition = transitionMultiAgentV2(want, next => runCodexFeatures(next ? "enable" : "disable", deps));
+      if (!transition.ok) return emit(false, ["Native feature transition failed. Read ocx v2 status before retrying."]);
+      changed = transition.changed;
+      if (!changed) return emit(true, [`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`]);
+      successLines = [v2StatusLine(want),
+        "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."];
     }
-    if (next) cfg.keepNativeChatGptOnV1 = true;
-    else deleteConfigTopLevelKey(cfg, "keepNativeChatGptOnV1");
-    saveConfig(cfg);
+    // Preserve the legacy graph: mode/keep and changed toggles sync even with no port.
     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;
-    }
-    if (already) {
-      log.log(next
-        ? "keep_native_chatgpt_on_v1 already ON — catalog re-synced."
-        : "keep_native_chatgpt_on_v1 already OFF — catalog re-synced.");
-      return 0;
-    }
-    log.log(next
-      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2 (new sessions)."
-      : "keep_native_chatgpt_on_v1: OFF — ChatGPT-native rows follow v1/base/v2 (new sessions).");
-    return 0;
-  }
-  if (verb !== "on" && verb !== "off") {
-    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>)`);
-    return 1;
-  }
-
-  const want = verb === "on";
-  if (want) {
-    const cfg = loadConfig();
-    if (requiresGlobalV2Disabled(cfg.multiAgentMode, cfg.keepNativeChatGptOnV1 === true)) {
-      log.error("v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first.");
-      return 1;
+      const port = findPort ? await findPort() : undefined;
+      const result = deps.sync ? await deps.sync(port)
+        : await (await import("../codex/sync")).syncModelsToCodex(port, undefined, parsed.json ? null : log);
+      sync = v2LocalSyncResult(result);
+    } catch { sync = { status: "failed", ok: false }; }
+    if (sync.ok && parsed.verb === "keep-native-v1" && unchangedKeep) {
+      const outcome = sync.status !== "skipped" && "catalog" in sync && sync.catalog?.converged
+        ? "catalog re-synced." : "catalog sync skipped by policy.";
+      successLines = [`keep_native_chatgpt_on_v1 already ${parsed.value ? "ON" : "OFF"} — ${outcome}`];
     }
+    return emit(sync.ok, sync.ok ? successLines
+      : ["catalog resync failed or is unverified; local V2 settings landed. Read ocx v2 status, then run ocx sync."]);
+  } catch {
+    changed = null;
+    return emit(false, ["Local V2 operation failed; native or saved settings may have changed. Read ocx v2 status before retrying; no rollback is implied."]);
   }
-  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 (!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
-  // 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;
 }