@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/update-restart.ts

@@ -0,0 +1,260 @@
+import { execFileSync, spawn } from "node:child_process";
+import { isIP } from "node:net";
+import { existsSync } from "node:fs";
+import { getRuntimePortPath, readRuntimePort, readProcessCommandLine, isOcxStartCommandLine, type RuntimePortState } from "../config/process-state";
+import { configuredAdminToken } from "../lib/admin-secrets";
+import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
+import { isProcessAlive } from "../lib/process-control";
+import { parseStrictSemver } from "../lib/strict-semver";
+import { startArgv } from "../lib/self-launch-argv";
+import { diagnoseService } from "../service/diagnostics";
+import { inspectGuardedManagerTarget } from "../service/guarded-manager-target";
+import { acquireOwnershipMutationLease, unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
+import { serviceStatePaths } from "../service/state";
+import { findLiveProxy, probeEndpointLiveness, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import { waitForPortAvailable } from "../server/ports";
+import { UPDATE_RESTART_CHILD_ENV, type UpdateRestartChildMarker } from "./update-restart-child";
+import { assertUpdateRestartConfiguration, assertUpdateRestartHome, readUpdateRestartHome, type UpdateRestartHome } from "./update-restart-home";
+import { observeAttestedUpdateReplacement, stopAttestedUpdateTarget } from "./update-restart-transport";
+import type { UpdateRestartCandidate } from "./update-restart-candidate";
+import { INCOMPLETE_INSTALL_RECOVERY } from "./restart-failure";
+import { computeVersionSkew } from "./version-skew";
+
+export interface UpdateRestartChild { pid?: number; exitCode: number | null; signalCode: string | null }
+export interface UpdateRestartIo {
+  now(): number;
+  acquire(): { release(): void };
+  home(): UpdateRestartHome;
+  checkHome(home: UpdateRestartHome): void;
+  runtime(): RuntimePortState | null;
+  standalone(target: UpdateRestartCandidate["target"]): boolean;
+  /** Whether the executable the replacement will run is complete (not the npm `bun` placeholder). */
+  runtimeReady(): boolean;
+  stop(candidate: UpdateRestartCandidate, deadlineAt: number, beforeStop: () => void): Promise<void>;
+  stopped(candidate: UpdateRestartCandidate, deadlineAt: number): Promise<boolean>;
+  start(marker: UpdateRestartChildMarker): UpdateRestartChild;
+  observe(deadlineAt: number, childPid: number): Promise<LiveProxy | null>;
+  wait(ms: number): Promise<void>;
+}
+const ELIGIBILITY_REASONS = ["windows", "unsupported_platform", "foreground", "service", "shared_or_client",
+  "package_tree_fenced", "unverifiable_ancestry", "target_changed", "configuration_changed"] as const;
+export type UpdateRestartEligibilityReason = (typeof ELIGIBILITY_REASONS)[number];
+
+/** Carries only a closed reason code across the eligibility/transport boundary. */
+export class UpdateRestartEligibilityError extends Error {
+  constructor(readonly reason: UpdateRestartEligibilityReason) { super("Update restart eligibility refused"); }
+}
+export type UpdateRestartResult = { ok: true; live: LiveProxy }
+  | { ok: false; code: string; reason?: UpdateRestartEligibilityReason };
+
+function sameRuntime(candidate: UpdateRestartCandidate, current: RuntimePortState | null): boolean {
+  const expected = candidate.runtime;
+  return !!current && current.pid === expected.pid && current.port === expected.port
+    && current.hostname === expected.hostname && current.attestationSecret === expected.attestationSecret
+    && current.siblingOfPort === undefined;
+}
+
+/** A terminal update transaction: it never enters generic restart recovery. */
+export async function runUpdateRestart(candidate: UpdateRestartCandidate, deadlineAt: number, io: UpdateRestartIo): Promise<UpdateRestartResult> {
+  let phase = "eligibility";
+  let lease: { release(): void } | undefined;
+  // Recorded here because the stop transport sanitizes anything thrown by beforeStop.
+  let runtimeRefused = false;
+  let eligibilityReason: UpdateRestartEligibilityReason | undefined;
+  try {
+    if (!parseStrictSemver(candidate.cliVersion) || candidate.cliVersion === "0.0.0"
+      || computeVersionSkew(candidate.cliVersion, candidate.target.version).relation !== "cli-newer") {
+      throw new Error("version");
+    }
+    const withinDeadline = () => { if (io.now() >= deadlineAt) throw new Error("deadline"); };
+    withinDeadline();
+    lease = io.acquire();
+    const home = candidate.home;
+    if (JSON.stringify(io.home()) !== JSON.stringify(home)) throw new Error("home_changed");
+    const revalidate = () => {
+      withinDeadline();
+      io.checkHome(home);
+      const currentRuntime = io.runtime();
+      if (!sameRuntime(candidate, currentRuntime)) {
+        eligibilityReason = currentRuntime?.siblingOfPort !== undefined ? "shared_or_client" : "target_changed";
+        throw new Error("target");
+      }
+      try {
+        if (!io.standalone(candidate.target)) throw new Error("target");
+      } catch (error) {
+        if (error instanceof UpdateRestartEligibilityError && ELIGIBILITY_REASONS.includes(error.reason)) eligibilityReason = error.reason;
+        throw error;
+      }
+      if (!io.runtimeReady()) {
+        runtimeRefused = true;
+        throw new Error("runtime");
+      }
+      withinDeadline();
+    };
+    revalidate();
+    phase = "stop";
+    await io.stop(candidate, deadlineAt, revalidate);
+    withinDeadline();
+    phase = "settle";
+    if (!await io.stopped(candidate, deadlineAt)) throw new Error("stop_unconfirmed");
+    // Shutdown is confirmed from here on and nothing has launched yet.
+    phase = "prelaunch";
+    withinDeadline();
+    io.checkHome(home);
+    // An in-place npm install can still be swapping its Bun in; wait for it inside the deadline,
+    // then repeat the launch preconditions synchronously so the wait opens no gap before spawn.
+    phase = "runtime";
+    while (!io.runtimeReady()) {
+      withinDeadline();
+      await io.wait(Math.min(100, deadlineAt - io.now()));
+    }
+    phase = "prelaunch";
+    withinDeadline();
+    io.checkHome(home);
+    phase = "start";
+    const child = io.start({ home, version: candidate.cliVersion, port: candidate.target.port, hostname: candidate.runtime.hostname ?? "", deadlineAt });
+    // The child must acquire its own lease and validate this frozen handoff before preflight.
+    lease.release();
+    lease = undefined;
+    if (!Number.isSafeInteger(child.pid) || !child.pid || child.pid === candidate.target.pid) throw new Error("launch_unknown");
+    phase = "replacement";
+    while (io.now() < deadlineAt) {
+      if (child.exitCode !== null || child.signalCode !== null) throw new Error("child_exited");
+      io.checkHome(home);
+      const live = await io.observe(deadlineAt, child.pid);
+      withinDeadline();
+      if (live) {
+        io.checkHome(home);
+        if (live.source !== "runtime" || live.pid !== child.pid || live.port !== candidate.target.port
+          || (live.hostname ?? "") !== (candidate.target.hostname ?? "") || live.role === "client"
+          || live.packageTreeFenced || live.version !== candidate.cliVersion) throw new Error("replacement_mismatch");
+        return { ok: true, live };
+      }
+      await io.wait(Math.min(100, deadlineAt - io.now()));
+    }
+    throw new Error("deadline");
+  } catch {
+    return { ok: false, code: runtimeRefused ? "update_restart_runtime_incomplete" : `update_restart_${phase}_failed`,
+      ...(eligibilityReason ? { reason: eligibilityReason } : {}) };
+  }
+  finally { lease?.release(); }
+}
+
+/** Sanitized, actionable text for each terminal update-restart code; it claims only what that phase proved. */
+export function describeUpdateRestartFailure(code: string, reason?: UpdateRestartEligibilityReason): string {
+  if (reason && (code === "update_restart_eligibility_failed" || code === "update_restart_stop_failed")) {
+    const action = (() => {
+      switch (reason) {
+        case "windows": return "Restart from a newer CLI is unavailable on Windows. Run `ocx status`, then restart through the owning service or desktop app.";
+        case "unsupported_platform": return "Restart from a newer CLI requires macOS or Linux. Run `ocx status`, then use the owning lifecycle manager.";
+        case "service": return "An installed or active service owns lifecycle control. Run `ocx status`, then use the owning installation's `ocx service restart`.";
+        case "foreground": return "The proxy is attached to a parent process. Run `ocx status`; if it runs in a terminal, restart it in that terminal, otherwise use its owning app or supervisor.";
+        case "shared_or_client": return "This is a shared or connected-client runtime. Run `ocx status` and restart through its owning Hub, service or desktop app.";
+        case "package_tree_fenced": return `The proxy's package files are unsettled. Wait for the install to finish. ${INCOMPLETE_INSTALL_RECOVERY}`;
+        case "unverifiable_ancestry": return "The proxy's process ancestry or manager could not be verified. Run `ocx status` to identify its owner before restarting.";
+        case "configuration_changed": return "The selected configuration or connection changed. Run `ocx status` to inspect the intended proxy before restarting.";
+        case "target_changed": return "The captured proxy identity changed. Run `ocx status` to inspect the intended proxy before restarting.";
+      }
+    })();
+    return `${action} Nothing was stopped by this restart attempt.`;
+  }
+  switch (code) {
+    case "update_restart_runtime_incomplete":
+      return `This installation's Bun runtime is incomplete; nothing was stopped. Wait for the install to finish, then run \`ocx restart\` again. ${INCOMPLETE_INSTALL_RECOVERY}`;
+    case "update_restart_eligibility_failed":
+      return "The running proxy is not eligible for an update restart from this CLI (it is supervised, shared, or changed); nothing was stopped. Run `ocx status` to inspect the intended proxy.";
+    case "update_restart_stop_failed":
+      return "The guarded stop of the old proxy could not be confirmed; inspect `ocx status` before retrying.";
+    case "update_restart_settle_failed":
+      return "The old proxy was not confirmed stopped, so no second proxy was started; inspect `ocx status` before retrying.";
+    case "update_restart_prelaunch_failed":
+      return "The old proxy stopped, but its home, ownership or deadline changed before launch, so nothing was launched. Check `ocx status`; if no proxy is running, run `ocx start`.";
+    case "update_restart_runtime_failed":
+      return `The old proxy stopped, but this installation's Bun runtime did not finish installing in time, so nothing was launched. ${INCOMPLETE_INSTALL_RECOVERY} Run \`ocx status\`; if no proxy is running, run \`ocx start\` once the install completes.`;
+    case "update_restart_start_failed":
+      return "The old proxy stopped, but the new proxy's launch could not be confirmed. Check `ocx status`; if no proxy is running, run `ocx start`.";
+    case "update_restart_replacement_failed":
+      return "The new proxy did not verify as the expected replacement in time; inspect `ocx status` before retrying.";
+    default:
+      return "Update restart could not be confirmed; inspect `ocx status` before retrying.";
+  }
+}
+
+function standalone(target: UpdateRestartCandidate["target"]): boolean {
+  try { assertUpdateRestartConfiguration(target.hostname ?? ""); }
+  catch { throw new UpdateRestartEligibilityError("configuration_changed"); }
+  if (process.platform !== "darwin" && process.platform !== "linux") {
+    throw new UpdateRestartEligibilityError(process.platform === "win32" ? "windows" : "unsupported_platform");
+  }
+  const host = probeHostname(target.hostname).replace(/^\[|\]$/g, "");
+  if (target.role === "client") throw new UpdateRestartEligibilityError("shared_or_client");
+  if (target.packageTreeFenced) throw new UpdateRestartEligibilityError("package_tree_fenced");
+  if (!isIP(host) || target.source !== "runtime") throw new UpdateRestartEligibilityError("unverifiable_ancestry");
+  const command = readProcessCommandLine(target.pid);
+  if (!command || !isOcxStartCommandLine(command)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
+  if (diagnoseService().installed) throw new UpdateRestartEligibilityError("service");
+  const manager = inspectGuardedManagerTarget(target.pid, target.port);
+  if (manager.kind !== "absent") throw new UpdateRestartEligibilityError(manager.kind === "bound" ? "service" : "unverifiable_ancestry");
+  let parent: string;
+  try {
+    parent = execFileSync("ps", ["-o", "ppid=", "-p", String(target.pid)], {
+      encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch { throw new UpdateRestartEligibilityError("unverifiable_ancestry"); }
+  if (!/^[1-9]\d*$/.test(parent)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
+  if (parent !== "1") throw new UpdateRestartEligibilityError("foreground");
+  return true;
+}
+
+/** Production composition keeps stop/start side effects out of cli/index.ts. */
+export function restartFromCurrentInstallation(candidate: UpdateRestartCandidate, deadlineAt: number, environment: NodeJS.ProcessEnv): Promise<UpdateRestartResult> {
+  const argv = startArgv(candidate.target.port);
+  const executable = process.execPath;
+  return runUpdateRestart(candidate, deadlineAt, {
+    now: Date.now,
+    acquire: () => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs: Math.max(0, Math.min(2000, deadlineAt - Date.now())) }),
+    home: readUpdateRestartHome, checkHome: assertUpdateRestartHome, runtime: readRuntimePort, standalone,
+    runtimeReady: () => isRealBunBinary(executable),
+    stop: async (target, deadline, beforeStop) => {
+      const token = configuredAdminToken();
+      if (!token) throw new Error("update_restart_credential_unavailable");
+      await stopAttestedUpdateTarget({ target: target.target, secret: target.runtime.attestationSecret,
+        cliVersion: target.cliVersion, deadlineAt: deadline, beforeStop, adminToken: token });
+    },
+    stopped: async (target, deadline) => {
+      while (Date.now() < deadline && isProcessAlive(target.target.pid)) await Bun.sleep(Math.min(100, deadline - Date.now()));
+      if (Date.now() >= deadline || existsSync(getRuntimePortPath())) return false;
+      const endpoint = { port: target.target.port, hostname: target.target.hostname };
+      if (!await waitForPortAvailable(endpoint.port, probeHostname(endpoint.hostname),
+        { timeoutMs: Math.max(0, Math.min(1000, deadline - Date.now())), intervalMs: 50 })) return false;
+      if (Date.now() >= deadline) return false;
+      return await probeEndpointLiveness(endpoint, { timeoutMs: Math.min(250, deadline - Date.now()) }) === "dead";
+    },
+    start: marker => {
+      const env = unprivilegedOwnershipMutationEnvironment(environment);
+      env.OPENCODEX_HOME = marker.home.config.path;
+      env.CODEX_HOME = marker.home.codex.path;
+      env[UPDATE_RESTART_CHILD_ENV] = JSON.stringify(marker);
+      const child = spawn(executable, argv, { detached: true, stdio: "ignore", windowsHide: true, env });
+      child.on("error", () => {}); // exit/health evidence reports failure; never retry a possibly launched child.
+      child.unref();
+      return child;
+    },
+    observe: async (deadline, childPid) => {
+      const live = await findLiveProxy({ deadlineAt: deadline, attempts: 1 });
+      if (!live) return null;
+      if (live.pid !== childPid) throw new Error("update_restart_replacement_changed");
+      const runtime = readRuntimePort(childPid);
+      if (!runtime?.attestationSecret || runtime.port !== candidate.target.port
+        || runtime.hostname !== candidate.runtime.hostname || runtime.siblingOfPort !== undefined) {
+        throw new Error("update_restart_replacement_unattested");
+      }
+      const attested = await observeAttestedUpdateReplacement({ target: { ...live, pid: childPid },
+        secret: runtime.attestationSecret, version: candidate.cliVersion, deadlineAt: deadline });
+      const current = readRuntimePort(childPid);
+      if (JSON.stringify(current) !== JSON.stringify(runtime)) throw new Error("update_restart_replacement_changed");
+      return attested;
+    },
+    wait: ms => Bun.sleep(ms),
+  });
+}

package/src/cli/usage-model-search.ts

@@ -0,0 +1,58 @@
+/** Model-row display search; server attribution and report totals stay unchanged. */
+import { CliUsageError } from "./runtime-api";
+
+export interface UsageModelView {
+  query: string;
+  matchedModelCount: number;
+  returnedModelCount: number;
+  limit: 100;
+  truncated: boolean;
+}
+
+interface SearchableModel {
+  model: string;
+  provider: string;
+  resolvedModel?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+  [key: string]: unknown;
+}
+
+/** Unlike exact attribution flags, an explicit empty search is a valid view. */
+export function takeUsageSearchOption(args: string[]): string | undefined {
+  const indices = args.flatMap((arg, index) => arg === "--search" || arg.startsWith("--search=") ? [index] : []);
+  if (indices.length > 1) throw new CliUsageError("--search was given more than once");
+  const index = indices[0];
+  if (index === undefined) return undefined;
+  const arg = args[index]!;
+  if (arg.startsWith("--search=")) {
+    args.splice(index, 1);
+    return arg.slice("--search=".length);
+  }
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) throw new CliUsageError("--search requires a value; use --search= for an empty search");
+  args.splice(index, 2);
+  return value;
+}
+
+export function selectUsageModelView<T extends { models?: unknown }>(report: T, rawQuery: string): Omit<T, "models"> & { models: SearchableModel[]; modelView: UsageModelView } {
+  if (!report || !Array.isArray(report.models)) throw new Error("Invalid usage model rows; retry after checking the runtime.");
+  const models = report.models.map((raw: unknown): SearchableModel => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid usage model row.");
+    const row = raw as Record<string, unknown>;
+    if (typeof row.model !== "string" || typeof row.provider !== "string"
+      || (row.resolvedModel !== undefined && typeof row.resolvedModel !== "string")
+      || ![row.requests, row.totalTokens].every(value => typeof value === "number" && Number.isFinite(value) && value >= 0)
+      || (row.estimatedCostUsd !== undefined && (typeof row.estimatedCostUsd !== "number" || !Number.isFinite(row.estimatedCostUsd)))) {
+      throw new Error("Invalid usage model row.");
+    }
+    return row as SearchableModel;
+  });
+  const query = rawQuery.trim().toLowerCase();
+  const matching = models.toSorted((a, b) => b.totalTokens - a.totalTokens).filter(row => !query
+    || row.model.toLowerCase().includes(query) || row.provider.toLowerCase().includes(query)
+    || (row.resolvedModel ?? "").toLowerCase().includes(query));
+  const selected = matching.slice(0, 100);
+  return { ...report, models: selected, modelView: { query, matchedModelCount: matching.length, returnedModelCount: selected.length, limit: 100, truncated: matching.length > selected.length } };
+}

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."]);
+  });
+}