@yansigit/opencodex 2.31.0

package/src/cli/agent.ts

@@ -0,0 +1,290 @@
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+import { readFileSync } from "node:fs";
+
+interface WebSearchModelOption {
+  value: string;
+  model: string;
+  backend: "openai" | "anthropic";
+  authSlot?: boolean;
+}
+
+const USAGE = `Usage:
+  ocx agent [status] [--json]
+  ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
+      [--prompt <text|->] [--guidance <on|off>] [--json]
+  ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
+  ocx agent subagents <status|set|clear> [model,model...] [--json]
+  ocx agent roles <status|set|remove> [--file <path>] [--json]
+  ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
+  ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
+      [--backend web:<openai|anthropic|xai|gemini|exa|-> vision:<openai|anthropic|routed|->]
+      [--reasoning <level>] [--max-descriptions <n>] [--json]`;
+
+function clearable(value: string | undefined): string | null | undefined {
+  return value === "-" ? null : value;
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const [v2, injection, caps, subagents, roles, fallback, sidecars] = await Promise.all([
+    runtimeRequest("/api/v2", {}, deps),
+    runtimeRequest("/api/injection-model", {}, deps),
+    runtimeRequest("/api/effort-caps", {}, deps),
+    runtimeRequest("/api/subagent-models", {}, deps),
+    runtimeRequest("/api/subagent-roles", {}, deps),
+    runtimeRequest("/api/subagent-model-fallback", {}, deps),
+    runtimeRequest("/api/sidecar-settings", {}, deps),
+  ]);
+  const result = { v2, injection, caps, subagents, roles, fallback, sidecars };
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function injection(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/injection-model", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown injection action ${action}`, USAGE);
+  const model = clearable(takeOption(args, "--model"));
+  const effort = clearable(takeOption(args, "--effort"));
+  const prompt = clearable(takeOption(args, "--prompt"));
+  const guidance = takeBooleanOption(args, "--guidance");
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (model !== undefined) body.model = model;
+  if (effort !== undefined) body.effort = effort;
+  if (prompt !== undefined) body.prompt = prompt;
+  if (guidance !== undefined) body.multiAgentGuidanceEnabled = guidance;
+  if (Object.keys(body).length === 0) throw new CliUsageError("at least one injection option is required", USAGE);
+  const result = await runtimeRequest("/api/injection-model", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Agent injection settings updated."]);
+}
+
+async function effort(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/effort-caps", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown effort action ${action}`, USAGE);
+  const main = clearable(takeOption(args, "--main"));
+  const subagent = clearable(takeOption(args, "--subagent"));
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (main !== undefined) body.effortCap = main;
+  if (subagent !== undefined) body.subagentEffortCap = subagent;
+  if (Object.keys(body).length === 0) throw new CliUsageError("--main and/or --subagent is required", USAGE);
+  const result = await runtimeRequest("/api/effort-caps", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Agent effort caps updated."]);
+}
+
+async function subagents(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-models", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  let models: string[];
+  if (action === "clear") models = [];
+  else if (action === "set") {
+    const raw = args.shift();
+    if (!raw) throw new CliUsageError("comma-separated subagent models are required", USAGE);
+    models = csv(raw) ?? [];
+  } else throw new CliUsageError(`unknown subagents action ${action}`, USAGE);
+  rejectArgs(args, USAGE);
+  if (models.length > 5) throw new CliUsageError("at most 5 subagent models are allowed", USAGE);
+  const result = await runtimeRequest("/api/subagent-models", { method: "PUT", body: JSON.stringify({ models }) }, deps);
+  printData(result, wantsJson, [`Subagent roster: ${models.join(", ") || "cleared"}`]);
+}
+
+async function readRolesDocument(deps: RuntimeApiDeps, file: string | undefined): Promise<unknown> {
+  const raw = file
+    ? readFileSync(file, "utf8")
+    : await readStdinDocument(deps);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliUsageError("roles JSON is invalid", USAGE);
+  }
+  if (Array.isArray(parsed)) return { roles: parsed };
+  return parsed;
+}
+
+async function readStdinDocument(deps: RuntimeApiDeps): Promise<string> {
+  const input = deps.stdinImpl ?? process.stdin;
+  if (input.isTTY) throw new CliUsageError("roles set requires --file <path> or JSON on stdin", USAGE);
+  const chunks: Buffer[] = [];
+  for await (const chunk of input) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (!text) throw new CliUsageError("roles JSON was empty", USAGE);
+  return text;
+}
+
+async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-roles", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action === "set") {
+    const file = takeOption(args, "--file");
+    rejectArgs(args, USAGE);
+    const body = await readRolesDocument(deps, file);
+    if (!body || typeof body !== "object" || Array.isArray(body) || !("roles" in body)) {
+      throw new CliUsageError("roles JSON must be { roles: [...] } or an array", USAGE);
+    }
+    const result = await runtimeRequest("/api/subagent-roles", { method: "PUT", body: JSON.stringify(body) }, deps);
+    printData(result, wantsJson, ["Agent roles updated."]);
+    return;
+  }
+  if (action !== "remove") throw new CliUsageError(`unknown roles action ${action}`, USAGE);
+  const id = args.shift();
+  if (!id) throw new CliUsageError("role id is required", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest("/api/subagent-roles", {
+    method: "PUT",
+    body: JSON.stringify({ remove: id }),
+  }, deps);
+  printData(result, wantsJson, [`Removed role ${id}.`]);
+}
+
+async function fallback(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-model-fallback", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  const body: Record<string, unknown> = {};
+  if (action === "clear") body.models = [];
+  else if (action === "set") {
+    const raw = args[0] && !args[0].startsWith("--") ? args.shift() : undefined;
+    if (raw) body.models = csv(raw) ?? [];
+  } else throw new CliUsageError(`unknown fallback action ${action}`, USAGE);
+  const pollMs = takeIntegerOption(args, "--poll-ms", { min: 5_000 });
+  if (pollMs !== undefined) {
+    if (pollMs > 600_000) throw new CliUsageError("--poll-ms must be <= 600000", USAGE);
+    body.pollMs = pollMs;
+  }
+  rejectArgs(args, USAGE);
+  if (Object.keys(body).length === 0) throw new CliUsageError("models and/or --poll-ms is required", USAGE);
+  const result = await runtimeRequest("/api/subagent-model-fallback", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Subagent fallback settings updated."]);
+}
+
+async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const section = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (section === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/sidecar-settings", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (section !== "web" && section !== "vision") throw new CliUsageError("sidecar must be web, vision, or status", USAGE);
+  // --list must be consumed BEFORE rejectArgs sees it. It prints the server's
+  // candidate set — the exact list the GUI picker shows (#2188): the server
+  // computes it once and every surface consumes it, so the CLI cannot drift.
+  const wantsList = takeFlag(args, "--list");
+  if (wantsList) {
+    rejectArgs(args, USAGE);
+    const settings = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
+      webSearchModels?: WebSearchModelOption[];
+      visionModels?: Array<{ value: string; backend?: string; baseline?: boolean }>;
+    };
+    if (section === "web") {
+      const options = settings.webSearchModels ?? [];
+      printData(options, wantsJson, options.length === 0
+        ? ["no runnable web-search sidecar models (log in to ChatGPT or Anthropic)"]
+        : options.map(option => `${option.value} [${option.backend}]${option.authSlot ? " (auth slot)" : ""}`));
+    } else {
+      const options = settings.visionModels ?? [];
+      printData(options, wantsJson, options.length === 0
+        ? ["no eligible vision describers"]
+        : options.map(option => `${option.value}${option.backend ? ` [${option.backend}]` : ""}${option.baseline ? " (baseline)" : ""}`));
+    }
+    return;
+  }
+  const model = takeOption(args, "--model");
+  const backend = takeOption(args, "--backend");
+  const reasoning = takeOption(args, "--reasoning");
+  const maxDescriptionsPerTurn = takeIntegerOption(args, "--max-descriptions", { min: 1 });
+  rejectArgs(args, USAGE);
+  const settings: Record<string, unknown> = {};
+  if (model !== undefined) settings.model = model === "-" ? "" : model;
+  if (backend !== undefined) settings.backend = backend === "-" ? null : backend;
+  if (reasoning !== undefined) settings.reasoning = reasoning;
+  if (maxDescriptionsPerTurn !== undefined) settings.maxDescriptionsPerTurn = maxDescriptionsPerTurn;
+  if (Object.keys(settings).length === 0) throw new CliUsageError("at least one sidecar option is required", USAGE);
+  if (section === "web" && model !== undefined && model !== "-") {
+    const offered = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
+      webSearchModels?: WebSearchModelOption[];
+    };
+    const requestedBackend = backend === "-" ? "openai" : backend;
+    const option = offered.webSearchModels?.find(candidate =>
+      (candidate.value === model || candidate.model === model)
+      && (requestedBackend === undefined || candidate.backend === requestedBackend));
+    if (option) {
+      settings.model = option.model;
+      if (backend !== "-") settings.backend = option.backend;
+    }
+  }
+  const body = section === "web" ? { webSearch: settings } : { vision: settings };
+  const result = await runtimeRequest("/api/sidecar-settings", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, [`${section} sidecar settings updated.`]);
+}
+
+export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "status", ...rest] = argv;
+    if (sub === "status") await status(rest, deps);
+    else if (sub === "injection" || sub === "guidance") await injection(rest, deps);
+    else if (sub === "effort") await effort(rest, deps);
+    else if (sub === "subagents" || sub === "roster") await subagents(rest, deps);
+    else if (sub === "roles") await roles(rest, deps);
+    else if (sub === "fallback") await fallback(rest, deps);
+    else if (sub === "sidecar") await sidecar(rest, deps);
+    else throw new CliUsageError(`unknown agent command ${sub}`, USAGE);
+  });
+}
+
+export const AGENT_USAGE = USAGE;

package/src/cli/catalog-prewarm.ts

@@ -0,0 +1,27 @@
+import type { OcxConfig } from "../types";
+
+type GatherRoutedModels = (config: OcxConfig) => Promise<unknown>;
+
+export type CatalogPrewarmDeps = {
+  loadConfig?: () => OcxConfig;
+  importCatalog?: () => Promise<{ gatherRoutedModels: GatherRoutedModels }>;
+};
+
+/**
+ * After the listen port is bound, kick off live provider discovery so the first
+ * GUI /v1/models and syncModelsToCodex share one gather flight instead of racing
+ * duplicate upstream /models fetches.
+ */
+export function scheduleCatalogPrewarm(deps: CatalogPrewarmDeps = {}): void {
+  void Promise.resolve()
+    .then(async () => {
+      const load = deps.loadConfig ?? (await import("../config")).loadConfig;
+      const { gatherRoutedModels } = await (deps.importCatalog?.() ?? import("../codex/catalog"));
+      return gatherRoutedModels(load());
+    })
+    .catch(error => {
+      if (error && typeof error === "object" && (error as { code?: unknown }).code === "catalog_busy") {
+        console.warn("[catalog] startup discovery skipped: catalog gather is busy");
+      }
+    });
+}

package/src/cli/claude-agent-startup-sync.ts

@@ -0,0 +1,73 @@
+import type { OcxConfig } from "../types";
+import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { fetchClaudeContextWindows } from "./claude";
+import type { ReadinessGate } from "../server/readiness";
+
+export interface ClaudeAgentStartupSyncDeps {
+  fetchContextWindows?: typeof fetchClaudeContextWindows;
+  injectAgentDefs?: typeof injectClaudeAgentDefs;
+  warn?: (message: string) => void;
+}
+
+/**
+ * Keep the public readiness gate pending until both startup reconciliations have settled.
+ *
+ * The Codex sync remains the authority for ready versus failed. Claude roster repair is
+ * deliberately best-effort (#2200), but readiness must not become observable between the
+ * Codex write and that repair: a service manager could otherwise launch Claude Code against
+ * stale `ocx-*.md` files. A small forwarding gate delays only the successful transition;
+ * terminal Codex failure is still published immediately.
+ */
+export async function reconcileClientStartupBeforeReady<T>(
+  readinessGate: ReadinessGate,
+  syncCodex: (deferredGate: ReadinessGate) => Promise<T>,
+  syncClaudeRoster: () => Promise<unknown>,
+): Promise<T> {
+  let codexReady = false;
+  const deferredGate: ReadinessGate = {
+    getStatus: () => readinessGate.getStatus(),
+    markReady: () => { codexReady = true; },
+    markFailed: () => readinessGate.markFailed(),
+  };
+
+  const result = await syncCodex(deferredGate);
+  await syncClaudeRoster();
+  if (codexReady) readinessGate.markReady();
+  return result;
+}
+
+/**
+ * Reconcile the generated Claude Code roster after the proxy listener is live.
+ *
+ * This belongs to the owning CLI lifecycle rather than `startServer`: the latter is also a
+ * library/test primitive and must not mutate a developer's real `~/.claude` directory merely
+ * because an in-process test server was created. The live Management API supplies the same bounded
+ * context-window map used by `ocx claude`; failure keeps startup available and falls back to an
+ * unmarked roster. Disabled integrations skip discovery and prune verified-owned definitions.
+ */
+export async function syncClaudeAgentDefsAtProxyStartup(
+  config: OcxConfig,
+  port: number,
+  deps: ClaudeAgentStartupSyncDeps = {},
+): Promise<string[] | null> {
+  const inject = deps.injectAgentDefs ?? injectClaudeAgentDefs;
+  const warn = deps.warn ?? (message => console.warn(message));
+
+  try {
+    if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
+      return inject(config, {});
+    }
+
+    let windows: Record<string, number> = {};
+    try {
+      windows = await (deps.fetchContextWindows ?? fetchClaudeContextWindows)(config, port);
+    } catch {
+      // Startup remains best-effort. The next management mutation or `ocx claude` launch can
+      // restore context markers after a transient catalog/Management API failure.
+    }
+    return inject(config, windows);
+  } catch (error) {
+    warn(`⚠ Claude agent definitions could not be synced at proxy startup: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}

package/src/cli/claude-desktop.ts

@@ -0,0 +1,213 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadConfig, saveConfigPreservingClaudeCode } from "../config";
+import { setIntegrationEnabled } from "../codex/desired-state";
+import {
+  DESKTOP_FAMILIES,
+  moveDesktopRoute,
+  parseDesktopProfile,
+  setDesktopFamilyDefault,
+  type DesktopFamily,
+  type DesktopProfile,
+} from "../claude/desktop-profile";
+import { writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import { filterCatalogVisibleModels, desktopVisibleNativeSlugs, nativeContextLimits } from "../codex/catalog";
+import { buildClaudeDesktopState, fetchAllModels } from "../server/management-api";
+import { findLiveProxy } from "../server/proxy-liveness";
+import { runtimeRequest } from "./runtime-api";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+
+function isFamily(value: string | undefined): value is DesktopFamily {
+  return !!value && (DESKTOP_FAMILIES as readonly string[]).includes(value);
+}
+
+function printDesktopHelp(): void {
+  console.log(`Usage:
+  ocx claude desktop [apply] [--static|--hybrid|--discovery-only]
+  ocx claude desktop show [--json]
+  ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]
+  ocx claude desktop default <family> <provider/model|none>
+  ocx claude desktop export <path|->
+  ocx claude desktop import <path> [--apply]`);
+}
+
+export interface ApplyProfileDeps {
+  findLiveProxyImpl?: typeof findLiveProxy;
+  postApplyImpl?: (
+    mode: Desktop3pConfigMode,
+    profile: DesktopProfile,
+  ) => Promise<{ ok?: boolean; path?: string; error?: string }>;
+}
+
+export async function applyProfile(
+  profile: DesktopProfile,
+  mode: Desktop3pConfigMode,
+  deps: ApplyProfileDeps = {},
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  // Explicit apply is an enable action. Persist intent before any Desktop write
+  // so a process crash cannot leave a gateway profile that startup immediately removes.
+  const desired = setIntegrationEnabled("claude-desktop", true);
+  if (!desired.ok) return { ok: false, path: "", reason: desired.message };
+  const config = loadConfig();
+  const state = await buildClaudeDesktopState(config, profile);
+  config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
+  saveConfigPreservingClaudeCode(config);
+  const live = await (deps.findLiveProxyImpl ?? findLiveProxy)();
+  if (live) {
+    // #859: the Desktop alias reverse-map is process-local. Applying through the
+    // serving process installs the map there; a local-only write leaves the
+    // daemon unable to decode aliases, and the provider rejects them (400).
+    const post = deps.postApplyImpl ?? (async (m: Desktop3pConfigMode, p: DesktopProfile) =>
+      runtimeRequest<{ ok?: boolean; path?: string; error?: string; saved?: boolean; warning?: string }>(
+        "/api/claude-desktop/apply",
+        // The daemon's config may be older than what we just saved, so the
+        // profile travels with the request instead of being re-read there.
+        { method: "POST", body: JSON.stringify({ mode: m, profile: p }) },
+      ));
+    try {
+      const applied = await post(mode, state.profile);
+      if (applied.ok === false) return { ok: false, path: applied.path ?? "", reason: applied.error ?? "daemon apply failed" };
+      // Partial success: Desktop was written but the applied marker was not
+      // persisted. Pass the degradation up instead of reporting a clean apply.
+      const partial = (applied as { saved?: boolean; warning?: string }).saved === false;
+      return {
+        ok: true,
+        path: applied.path ?? "",
+        ...(partial ? { warning: (applied as { warning?: string }).warning ?? "applied marker was not saved" } : {}),
+      };
+    } catch (error) {
+      return { ok: false, path: "", reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  const allModels = await fetchAllModels(config);
+  // The toggle can persist OFF while fetchAllModels was awaiting (same race the
+  // management writers fence). Re-read persisted intent immediately before the
+  // writer; a lost race is a discriminated skip, not a write.
+  const { claudeDesktopIntegrationEnabledNow } = await import("../codex/desired-state");
+  if (!claudeDesktopIntegrationEnabledNow()) {
+    return { ok: false, path: "", reason: "desired_state_changed" };
+  }
+  const routed = filterCatalogVisibleModels(allModels, config).map(model => ({
+    provider: model.provider,
+    id: model.id,
+    contextWindow: model.contextWindow,
+  }));
+  const result = writeDesktop3pConfig(
+    config.port ?? 10100,
+    [...desktopVisibleNativeSlugs(config)],
+    routed,
+    config.apiKeys?.[0]?.key,
+    mode,
+    state.profile,
+    nativeContextLimits(config),
+  );
+  return { ok: result.written, path: result.path, reason: result.reason };
+}
+
+export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProfileDeps = {}): Promise<number> {
+  const command = argv[0];
+  if (command === "help" || command === "--help" || command === "-h") {
+    printDesktopHelp();
+    return 0;
+  }
+
+  // Legacy mode flags remain apply aliases and are parsed before subcommands.
+  const legacyFlags = argv.filter(arg => ["--static", "--hybrid", "--discovery-only"].includes(arg));
+  const applyInvocation = argv.length === 0 || command === "apply" || legacyFlags.length > 0;
+  if (applyInvocation) {
+    const nonMode = argv.filter(arg => !["apply", "--static", "--hybrid", "--discovery-only"].includes(arg));
+    if (nonMode.length > 0) {
+      console.error(`알 수 없는 인자: ${nonMode.join(" ")}`);
+      return 1;
+    }
+    const parsedMode = parseDesktop3pModeArgs(legacyFlags);
+    if ("error" in parsedMode) { console.error(parsedMode.error); return 1; }
+    try {
+      const config = loadConfig();
+      const state = await buildClaudeDesktopState(config);
+      const result = await applyProfile(state.profile, parsedMode.mode, deps);
+      if (!result.ok) {
+        console.error(`설정 적용 실패: ${result.reason ?? "unknown error"}`);
+        console.error("프로필은 저장되었지만 Claude Desktop 설정 파일에는 반영되지 않았습니다. 프록시 상태를 확인한 뒤 다시 적용해 주세요.");
+        return 1;
+      }
+      console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
+      // The write landed; only the bookkeeping marker did not. Saying nothing
+      // would leave the saved-vs-applied display wrong with no explanation.
+      if (result.warning) console.warn(`⚠️  ${result.warning}`);
+      console.log("Claude Desktop을 완전히 종료한 뒤 다시 열어 주세요.");
+      return 0;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 1;
+    }
+  }
+
+  try {
+    const config = loadConfig();
+    const state = await buildClaudeDesktopState(config);
+    if (command === "show") {
+      if (argv.length > 2 || (argv[1] && argv[1] !== "--json")) throw new Error("Usage: ocx claude desktop show [--json]");
+      if (argv[1] === "--json") console.log(JSON.stringify(state));
+      else {
+        for (const family of DESKTOP_FAMILIES) {
+          console.log(`${family.toUpperCase()}${state.profile.defaults[family] ? ` (default: ${state.profile.defaults[family]})` : ""}`);
+          for (const model of state.models.filter(item => item.assignment.family === family)) {
+            console.log(`  ${model.available ? "•" : "○"} ${model.route} -> ${model.assignment.alias}${model.available ? "" : " (unavailable)"}`);
+          }
+        }
+      }
+      return 0;
+    }
+    if (command === "move") {
+      const [, route, familyRaw, ...flags] = argv;
+      if (!route || !isFamily(familyRaw) || flags.some(flag => flag !== "--default")) throw new Error("Usage: ocx claude desktop move <route> <family> [--default]");
+      if (!state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
+      const profile = moveDesktopRoute(state.profile, route, familyRaw, flags.includes("--default"));
+      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
+      saveConfigPreservingClaudeCode(config);
+      console.log(`${route} 모델을 ${familyRaw} 그룹으로 옮겼습니다.`);
+      return 0;
+    }
+    if (command === "default") {
+      const [, familyRaw, routeRaw] = argv;
+      if (!isFamily(familyRaw) || !routeRaw || argv.length !== 3) throw new Error("Usage: ocx claude desktop default <family> <route|none>");
+      const route = routeRaw === "none" ? null : routeRaw;
+      if (route && !state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
+      const profile = setDesktopFamilyDefault(state.profile, familyRaw, route);
+      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
+      saveConfigPreservingClaudeCode(config);
+      console.log(`${familyRaw} 기본 모델을 ${route ?? "없음"}으로 지정했습니다.`);
+      return 0;
+    }
+    if (command === "export") {
+      const target = argv[1];
+      if (!target || argv.length !== 2) throw new Error("Usage: ocx claude desktop export <path|->");
+      const json = JSON.stringify(state.profile, null, 2) + "\n";
+      if (target === "-") process.stdout.write(json);
+      else writeFileSync(resolve(target), json, { encoding: "utf8", mode: 0o600 });
+      return 0;
+    }
+    if (command === "import") {
+      const source = argv[1];
+      const flags = argv.slice(2);
+      if (!source || flags.some(flag => flag !== "--apply")) throw new Error("Usage: ocx claude desktop import <path> [--apply]");
+      const profile = parseDesktopProfile(JSON.parse(readFileSync(resolve(source), "utf8")));
+      const reconciled = (await buildClaudeDesktopState(config, profile)).profile;
+      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: reconciled };
+      saveConfigPreservingClaudeCode(config);
+      if (flags.includes("--apply")) {
+        const result = await applyProfile(reconciled, "static", deps);
+        if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }
+        if (result.warning) console.warn(`⚠️  ${result.warning}`);
+      }
+      console.log("Claude Desktop 프로필을 가져왔습니다.");
+      return 0;
+    }
+    printDesktopHelp();
+    return 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}