@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/capability-types.ts

@@ -0,0 +1,54 @@
+/** A management route a capability drives. Path text only; never a handler reference. */
+export interface CapabilityRoute {
+  readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  readonly path: string;
+}
+
+export interface CapabilityFlag {
+  readonly name: string;
+  readonly value?: "string" | "number" | "boolean";
+  readonly required?: boolean;
+  readonly summary: string;
+}
+
+/**
+ * How a capability emits JSON.
+ *
+ * - `payload`: the API payload, largely unwrapped.
+ * - `envelope`: a CLI-shaped object with its own schema.
+ * - `none`: no `--json` mode.
+ */
+export type CapabilityJsonMode = "payload" | "envelope" | "none";
+
+export interface Capability {
+  /** Command path, e.g. `["account", "pause"]`. */
+  readonly command: readonly string[];
+  readonly summary: string;
+  readonly routes: readonly CapabilityRoute[];
+  readonly flags: readonly CapabilityFlag[];
+  readonly mutates: boolean;
+  readonly json: CapabilityJsonMode;
+  /** Complete CLI usage, including operands, when verified for this leaf. */
+  readonly usage?: string;
+  readonly details?: readonly string[];
+  /**
+   * Extra banner rows this capability owns, for surfaces the banner shows separately
+   * from the bare command (`ocx restore back`, `ocx doctor --reclaim-response-temps`).
+   * Without this the banner cannot equal the capability set: it legitimately carries more
+   * rows than there are commands.
+   */
+  readonly bannerLines?: readonly string[];
+}
+
+/**
+ * Surfaces resolved in the CLI head, before dispatch.
+ *
+ * They belong in `ocx capabilities` output and in the banner, but not in `CLI_COMMANDS`:
+ * `--version`, `-v`, and `version` are answered at `root.ts` and exit, so none of them is
+ * a runner key to parity-check against.
+ */
+export interface HeadCapability {
+  readonly invocations: readonly string[];
+  readonly summary: string;
+  readonly bannerLine: string;
+}

package/src/cli/catalog-command-result.ts

@@ -0,0 +1,57 @@
+import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
+import { CliUsageError, RuntimeApiError, PROXY_NOT_RUNNING_MESSAGE, printData, terminalSafeText } from "./runtime-api";
+
+function own(value: unknown, key: string): unknown {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+
+/** A small error/exit boundary; routes and domain DTO validation belong to callers. */
+export async function runCatalogAction(
+  action: () => Promise<number | void>, knownErrors: Readonly<Record<string, string>> = {},
+): Promise<number> {
+  try {
+    return (await action()) ?? 0;
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      // New domain parsers use static messages instead of raw JSON/validator exceptions.
+      console.error(`Error: ${terminalSafeText(error.message)}`);
+      if (error.usage) for (const line of error.usage.split("\n")) console.error(terminalSafeText(line));
+      return 2;
+    }
+    if (error instanceof RuntimeApiError) {
+      if (error.code) {
+        console.error(`Error: ${error.code === "proxy_not_running" ? PROXY_NOT_RUNNING_MESSAGE
+          : "This listener has no management API. Run management commands on the connected Hub. No request was sent."}`);
+        return 1;
+      }
+      const code = own(error.body, "code") ?? own(own(error.body, "error"), "code");
+      const known = typeof code === "string" && Object.hasOwn(knownErrors, code) ? knownErrors[code] : undefined;
+      const message = error.status === 404 ? "The requested record or operation was not found on the selected target."
+        : error.status === 409 ? "The selected target refused a conflicting change. Read back before trying again."
+          : error.status === 503 ? "Management API is unavailable. Use the intended running proxy; connected clients must make management changes on their Hub. A write outcome may be unknown."
+            : "The management request failed. Inspect the selected target before retrying; the write outcome may be unknown.";
+      console.error(`Error: ${terminalSafeText(known ?? message)}`);
+      return error.status === 404 ? 4 : error.status === 409 ? 5 : 1;
+    }
+    console.error("Error: Management operation did not return a usable outcome. Inspect the selected target before retrying; no rollback is implied.");
+    return 1;
+  }
+}
+
+/**
+ * Caller supplies a validated, rebuilt public DTO, not an arbitrary server body.
+ * This helper normalizes only the shared catalog disposition and preserves its exit.
+ */
+export function printCatalogResult(
+  data: Record<string, unknown>, refresh: unknown, wantsJson: boolean, lines: readonly string[],
+): number {
+  const catalogRefresh = normalizeCatalogDisposition(refresh);
+  if (catalogRefresh === null) throw new Error("Invalid catalog outcome");
+  const converged = catalogRefresh.status === "committed" && !catalogRefresh.degraded;
+  const outcome = converged ? "Catalog committed."
+    : "Change saved, but catalog convergence is incomplete. Read back before retrying.";
+  printData({ ...data, catalogRefresh }, wantsJson, [...lines, outcome]);
+  return converged ? 0 : 1;
+}

package/src/cli/chatgpt-command.ts

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig } from "../config";
+import { readConfigFileSnapshot } from "../config/diagnostics";
+import { chatgptDesktopConfigIssue } from "../config/schema/chatgpt-desktop";
 import {
   chatgptShimLauncherPath,
   resolveChatgptCodexBinary,
@@ -21,6 +23,20 @@ function run(command: string, args: string[]) {
   return { ok: result.status === 0, output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() };
 }
 
+/**
+ * Why the config file's `chatgptDesktop` block reads as absent, or null when it is valid, absent
+ * or the file cannot be parsed (the config loader reports that case itself).
+ */
+function chatgptDesktopIssueInFile(): string | null {
+  const { raw } = readConfigFileSnapshot();
+  if (raw === undefined) return null;
+  try {
+    return chatgptDesktopConfigIssue(JSON.parse(raw.replace(/^\uFEFF/, "")));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The installed app, found and confirmed by bundle identifier (com.openai.codex) the same way the
  * desktop restart adapter does. "ChatGPT" is a display name another app can share, so quitting,
@@ -90,7 +106,10 @@ export async function handleChatgptCommand(args: string[], platform: NodeJS.Plat
     const install = discoverApp();
     if (sub === "status") {
       const app = install ? appState(install, launcher) : { running: false, shim: false };
-      console.log(`app-server shim (experimental): ${config.chatgptDesktop?.appServerShim === true ? "on" : "off"}
+      const configIssue = config.chatgptDesktop?.appServerShim === true ? null : chatgptDesktopIssueInFile();
+      const flag = config.chatgptDesktop?.appServerShim === true ? "on"
+        : configIssue ? `off (config.json ${configIssue}; the whole chatgptDesktop block is ignored)` : "off";
+      console.log(`app-server shim (experimental): ${flag}
 launcher: ${existsSync(launcher) ? "present" : "absent"}
 app: ${install ? (app.running ? "running" : "not running") : "not installed"}
 CODEX_CLI_PATH launcher: ${app.shim ? "yes" : "no"}`);
@@ -104,7 +123,11 @@ CODEX_CLI_PATH launcher: ${app.shim ? "yes" : "no"}`);
     let binary: string | undefined;
     if (sub === "launch") {
       if (config.chatgptDesktop?.appServerShim !== true) {
-        console.error('Experimental shim disabled; set chatgptDesktop.appServerShim: true before launching.');
+        // Read the file only to explain a refusal; restore and a valid launch never touch it.
+        const configIssue = chatgptDesktopIssueInFile();
+        console.error(configIssue
+          ? `Experimental shim disabled: config.json ${configIssue}. The whole chatgptDesktop block is ignored until that is fixed.`
+          : "Experimental shim disabled; set chatgptDesktop.appServerShim: true before launching.");
         return 1;
       }
       binary = resolveChatgptCodexBinary(install.root) ?? undefined;

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

@@ -64,6 +64,23 @@ export async function reconcileClientStartupBeforeReady<T>(
   return result;
 }
 
+/** Establish catalog observation before any unrelated startup reconciliation awaits. */
+export async function syncCodexBeforeCatalogObservation<T>(
+  gate: ReadinessGate,
+  syncCodex: (gate: ReadinessGate) => Promise<T>,
+  startObservation: () => void,
+): Promise<T> {
+  let ready = false;
+  const forwardingGate: ReadinessGate = {
+    getStatus: () => gate.getStatus(),
+    markReady: () => { ready = true; gate.markReady(); },
+    markFailed: () => { ready = false; gate.markFailed(); },
+  };
+  const result = await syncCodex(forwardingGate);
+  if (ready) startObservation();
+  return result;
+}
+
 /**
  * Reconcile the generated Claude Code roster after the proxy listener is live.
  *

package/src/cli/claude-desktop-profile.ts

@@ -0,0 +1,100 @@
+/** Runtime-owned Desktop profile editing. Saving never applies a native configuration. */
+import { DESKTOP_FAMILIES, parseDesktopProfile, type DesktopProfile } from "../claude/desktop-profile";
+import { runCatalogAction } from "./catalog-command-result";
+import { readJsonInput, serializeManagementJson } from "./json-input";
+import { CliUsageError, printData, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+export interface DesktopProfileCliDeps extends RuntimeApiDeps {
+  runtimeRequestImpl?: typeof runtimeRequest;
+}
+
+const USAGE = "Usage: ocx claude desktop profile show [--json]\n       ocx claude desktop profile import FILE|- [--json]";
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Desktop state");
+  return value as Record<string, unknown>;
+}
+
+function text(value: unknown): string {
+  if (typeof value !== "string" || !value.length) throw new Error("Invalid Desktop text");
+  return value;
+}
+
+function boolean(value: unknown): boolean {
+  if (typeof value !== "boolean") throw new Error("Invalid Desktop flag");
+  return value;
+}
+
+function modelIdentity(row: Record<string, unknown>) {
+  const route = text(row.route);
+  if (!route.includes("/")) throw new Error("Invalid Desktop route");
+  if (row.contextWindow !== undefined && (typeof row.contextWindow !== "number"
+    || !Number.isSafeInteger(row.contextWindow) || row.contextWindow <= 0)) throw new Error("Invalid Desktop context window");
+  return { route, label: text(row.label), ...(row.contextWindow === undefined ? {} : { contextWindow: row.contextWindow as number }) };
+}
+
+function desktopState(raw: unknown, saved: boolean) {
+  const value = record(raw);
+  if (saved && value.ok !== true) throw new Error("Desktop save was not confirmed");
+  const profile = parseDesktopProfile(value.profile);
+  if (!Array.isArray(value.models) || !Array.isArray(value.rendered)
+    || !Number.isSafeInteger(value.port) || (value.port as number) < 1 || (value.port as number) > 65535) {
+    throw new Error("Invalid Desktop state");
+  }
+  const seen = new Set<string>();
+  const models = value.models.map(rawModel => {
+    const row = record(rawModel), identity = modelIdentity(row), assignment = record(row.assignment);
+    const expected = profile.assignments[identity.route];
+    if (!expected || seen.has(identity.route) || assignment.family !== expected.family || assignment.alias !== expected.alias) {
+      throw new Error("Invalid Desktop assignment");
+    }
+    seen.add(identity.route);
+    return { ...identity, available: boolean(row.available), effortSupported: boolean(row.effortSupported),
+      supports1m: boolean(row.supports1m), assignment: { family: expected.family, alias: expected.alias } };
+  });
+  if (seen.size !== Object.keys(profile.assignments).length) throw new Error("Incomplete Desktop models");
+  const renderedSeen = new Set<string>();
+  const rendered = value.rendered.map(rawModel => {
+    const row = record(rawModel), identity = modelIdentity(row);
+    if (!DESKTOP_FAMILIES.includes(row.family as typeof DESKTOP_FAMILIES[number])
+      || profile.assignments[identity.route]?.family !== row.family || renderedSeen.has(identity.route)
+      || !models.some(model => model.route === identity.route && model.available)) throw new Error("Invalid rendered Desktop model");
+    renderedSeen.add(identity.route);
+    return { ...identity, name: text(row.name), family: row.family as typeof DESKTOP_FAMILIES[number],
+      isFamilyDefault: boolean(row.isFamilyDefault), supports1m: boolean(row.supports1m) };
+  });
+  if (renderedSeen.size !== models.filter(model => model.available).length) throw new Error("Incomplete rendered Desktop models");
+  return { ...(saved ? { ok: true as const } : {}), profile, models, rendered, port: value.port as number };
+}
+
+/** Arguments start immediately after `claude desktop profile`. */
+export async function handleClaudeDesktopProfileCommand(argv: string[], deps: DesktopProfileCliDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv], wantsJson = takeFlag(args, "--json");
+    const action = args.shift();
+    if ((action !== "show" && action !== "import") || (action === "show" && args.length !== 0)
+      || (action === "import" && (args.length !== 1 || !args[0]?.trim() || (args[0]!.startsWith("-") && args[0] !== "-")))) {
+      throw new CliUsageError("Desktop profile accepts show or import with an explicit file or '-'. Saving and applying are separate actions.", USAGE);
+    }
+    let body: string | undefined;
+    if (action === "import") {
+      const input = await readJsonInput(args[0]!, deps);
+      let profile: DesktopProfile;
+      try { profile = parseDesktopProfile(input); }
+      catch { throw new CliUsageError("Desktop profile input is invalid. Supply a version-1 profile with valid assignments and family defaults."); }
+      body = serializeManagementJson({ profile });
+    }
+    const raw = await (deps.runtimeRequestImpl ?? runtimeRequest)("/api/claude-desktop", {
+      method: action === "show" ? "GET" : "PUT", redirect: "error",
+      ...(body === undefined ? {} : { headers: { "content-type": "application/json" }, body }),
+    }, deps);
+    const state = desktopState(raw, action === "import");
+    printData(state, wantsJson, [
+      action === "import" ? "Desktop profile saved on the selected proxy. It has not been applied by this command." : "Desktop profile on the selected proxy.",
+      `Models: ${state.models.length}; available: ${state.models.filter(model => model.available).length}; port: ${state.port}`,
+      ...DESKTOP_FAMILIES.map(family => `${family}: ${state.profile.defaults[family] ?? "none"}`),
+      ...(action === "import" ? ["Next: review with ocx claude desktop profile show; apply separately with ocx claude desktop apply."] : []),
+    ]);
+    return 0;
+  });
+}

package/src/cli/claude-desktop.ts

@@ -321,6 +321,27 @@ export function defaultDesktopApplyMode(
   return connection.kind === "connected" ? "gateway" : "first-party";
 }
 
+const DESKTOP_APPLY_FLAGS = ["--first-party", "--gateway", "--static", "--hybrid", "--discovery-only"] as const;
+
+/**
+ * A rejected argument is never echoed: an option-shaped token can carry a value (`-tVALUE`,
+ * `--opt=VALUE`, a dash-prefixed operand) and any token can carry terminal control characters, so
+ * the error counts them and lists the options that do exist instead.
+ */
+function unknownApplyArgsError(count: number): string {
+  return `알 수 없는 인자 ${count}개 (값은 표시하지 않습니다). 사용 가능한 옵션: ${DESKTOP_APPLY_FLAGS.join(" ")}`;
+}
+
+/** A rejected route is not echoed: whatever sits in that position may be a misplaced credential. */
+const UNAVAILABLE_ROUTE = "현재 사용할 수 없는 모델입니다. 사용 가능한 모델은 ocx claude desktop show로 확인하세요.";
+
+/** Profile files are user-chosen paths; a failure reports the operation and error code only. */
+function profileFileError(operation: "export" | "import", error: unknown): Error {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  const reason = typeof code === "string" && /^E[A-Z]+$/.test(code) ? code : error instanceof SyntaxError ? "invalid JSON" : "failed";
+  return new Error(`Claude Desktop 프로필 ${operation === "export" ? "내보내기" : "가져오기"} 실패: ${reason}`);
+}
+
 export function parseDesktopApplyArgs(
   flags: string[],
   config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole">,
@@ -330,8 +351,8 @@ export function parseDesktopApplyArgs(
   const wantsFirstParty = flags.includes("--first-party");
   const wantsGateway = flags.includes("--gateway") || shapeFlags.length > 0;
   if (wantsFirstParty && wantsGateway) return { error: "--first-party cannot be combined with --gateway or gateway shape flags." };
-  const unknown = flags.filter(arg => !["--first-party", "--gateway", "--static", "--hybrid", "--discovery-only"].includes(arg));
-  if (unknown.length > 0) return { error: `알 수 없는 인자: ${unknown.join(" ")}` };
+  const unknown = flags.filter(arg => !(DESKTOP_APPLY_FLAGS as readonly string[]).includes(arg));
+  if (unknown.length > 0) return { error: unknownApplyArgsError(unknown.length) };
   const kind: ClaudeDesktopMode = wantsFirstParty
     ? "first-party"
     : wantsGateway ? "gateway" : defaultDesktopApplyMode(config, readClientConnectionState(), observed ?? observeClaudeDesktopMode(config));
@@ -679,6 +700,12 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     printDesktopHelp();
     return 0;
   }
+  if (command === "profile") {
+    const { handleClaudeDesktopProfileCommand } = await import("./claude-desktop-profile");
+    return handleClaudeDesktopProfileCommand(argv.slice(1), {
+      runtimeRequestImpl: deps.runtimeRequestImpl, findLiveProxy: deps.findLiveProxyImpl,
+    });
+  }
 
   // Mode flags remain apply aliases and are parsed before subcommands.
   const applyFlags = argv.filter(arg => APPLY_FLAGS.includes(arg));
@@ -806,7 +833,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     if (command === "move") {
       const [, route, familyRaw, ...flags] = argv;
       if (!route || !isFamily(familyRaw) || flags.some(flag => flag !== "--default")) throw new CliUsageError("Usage: ocx claude desktop move <route> <family> [--default]");
-      if (!state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
+      if (!state.models.some(model => model.route === route && model.available)) throw new Error(UNAVAILABLE_ROUTE);
       const profile = moveDesktopRoute(state.profile, route, familyRaw, flags.includes("--default"));
       saveLocalDesktopProfile(profile, config.claudeCode?.desktopProfile, connection, deps);
       console.log(`${route} 모델을 ${familyRaw} 그룹으로 옮겼습니다.`);
@@ -816,7 +843,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       const [, familyRaw, routeRaw] = argv;
       if (!isFamily(familyRaw) || !routeRaw || argv.length !== 3) throw new CliUsageError("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}`);
+      if (route && !state.models.some(model => model.route === route && model.available)) throw new Error(UNAVAILABLE_ROUTE);
       const profile = setDesktopFamilyDefault(state.profile, familyRaw, route);
       saveLocalDesktopProfile(profile, config.claudeCode?.desktopProfile, connection, deps);
       console.log(`${familyRaw} 기본 모델을 ${route ?? "없음"}으로 지정했습니다.`);
@@ -827,14 +854,20 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       if (!target || argv.length !== 2) throw new CliUsageError("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 });
+      else {
+        try { writeFileSync(resolve(target), json, { encoding: "utf8", mode: 0o600 }); }
+        catch (error) { throw profileFileError("export", error); }
+      }
       return 0;
     }
     if (command === "import") {
       const source = argv[1];
       const flags = argv.slice(2);
       if (!source || flags.some(flag => flag !== "--apply")) throw new CliUsageError("Usage: ocx claude desktop import <path> [--apply]");
-      const profile = parseDesktopProfile(JSON.parse(readFileSync(resolve(source), "utf8")));
+      let raw: unknown;
+      try { raw = JSON.parse(readFileSync(resolve(source), "utf8")); }
+      catch (error) { throw profileFileError("import", error); }
+      const profile = parseDesktopProfile(raw);
       const reconciled = (await buildClaudeDesktopState(config, profile)).profile;
       if (flags.includes("--apply")) assertNoClientDisconnectPending();
       if (flags.includes("--apply") && readClientConnectionState().kind !== "disconnected") {

package/src/cli/codex-shim-autorestore.ts

@@ -17,6 +17,7 @@ const DEFAULT_DEPS: CodexShimAutoRestoreCliDeps = {
 
 export function skipsCodexShimAutoRestore(command: string | undefined, args: string[]): boolean {
   if (command === "uninstall" || command === "remove") return true;
+  if (command === "status" || command === "doctor") return true;
   // `lab` is read-only inspection; it must not trigger shim side effects.
   if (command === "lab") return true;
   // `resolve` is read-only inspection for embedding shells: a lookup made to populate
@@ -29,7 +30,7 @@ export function skipsCodexShimAutoRestore(command: string | undefined, args: str
   // or future actions. A later `apply` implementation must own its preflight.
   if (command === "system" && args[1] === "codex-cli-update") return true;
   if (command === "__update-badge") return true;
-  return command === "codex-shim" && ["install", "uninstall", "remove"].includes(args[1] ?? "");
+  return command === "codex-shim" && ["install", "status", "uninstall", "remove"].includes(args[1] ?? "");
 }
 
 export function maybeAutoRestoreCodexShim(

package/src/cli/codex-shim-readiness.ts

@@ -4,6 +4,7 @@ import {
   type CodexRoutingKind,
 } from "../codex/inject";
 import { diagnoseCodexShim, type CodexShimDiagnostic } from "../codex/shim";
+import { overlayActivationHint } from "../codex/shim-overlay";
 import { findFirstCodexOnPath, type CodexPathCandidate } from "../codex/shim-path-resolution";
 import { loadConfig, resolveEnvValue } from "../config";
 
@@ -32,7 +33,7 @@ export interface CodexConnectShimReadiness {
 }
 
 export interface CodexConnectShimInspectionDeps {
-  diagnose?: () => Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary">;
+  diagnose?: () => Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary" | "runnable" | "active">;
   findOnPath?: () => CodexPathCandidate | null;
 }
 
@@ -42,10 +43,29 @@ const CODEX_TOKEN_NOTE = "The connected Codex config uses OPENCODEX_API_AUTH_TOK
 const CODEX_TOKEN_ACTION = `${CODEX_TOKEN_NOTE} Run 'ocx codex-shim install' to repair it.`;
 
 export function codexConnectShimReadiness(inputs: {
-  diagnosis: Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary">;
+  diagnosis: Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary" | "runnable" | "active">;
   commandPath: string | null;
   commandIsShim?: boolean;
 }): CodexConnectShimReadiness {
+  if (inputs.diagnosis.runnable && inputs.diagnosis.active !== undefined) {
+    if (inputs.diagnosis.active === null) {
+      return {
+        status: "unverified",
+        message: `PATH activation could not be verified. Shim state: ${inputs.diagnosis.summary}. `
+          + `Check PATH and retry 'ocx connect'. ${CODEX_TOKEN_NOTE}`,
+      };
+    }
+    if (!inputs.diagnosis.active) {
+      return {
+        status: "missing",
+        message: `installed but not active; ${inputs.commandPath
+          ? `PATH resolves 'codex' to ${inputs.commandPath}`
+          : "no 'codex' executable was found on PATH"}. `
+          + `Shim state: ${inputs.diagnosis.summary}. ${overlayActivationHint()} ${CODEX_TOKEN_NOTE}`,
+      };
+    }
+    return { status: "ready", message: "installed and healthy" };
+  }
   if (inputs.diagnosis.installed && !inputs.diagnosis.healthy) {
     return {
       status: "unhealthy",
@@ -87,7 +107,7 @@ export function codexConnectShimReadiness(inputs: {
 export function inspectCodexShimForConnect(
   deps: CodexConnectShimInspectionDeps = {},
 ): CodexConnectShimReadiness {
-  let diagnosis: Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary">;
+  let diagnosis: Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary" | "runnable" | "active">;
   try {
     diagnosis = (deps.diagnose ?? diagnoseCodexShim)();
   } catch {

package/src/cli/combo-input.ts

@@ -0,0 +1,88 @@
+import { JEV_MAX_CANDIDATE_FIELD_CHARS } from "../combos/types";
+import { isCodexReasoningEffort } from "../reasoning-effort";
+import { readJsonInput } from "./json-input";
+import { CliUsageError, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+type ComboInput = {
+  targets?: Array<Record<string, unknown>>;
+  imageInput?: "auto" | "disabled";
+  reasoningEffortMode?: "strict" | "adaptive";
+  nativeAlias?: boolean;
+};
+const TARGET_KEYS = new Set(["provider", "model", "weight", "reasoningEfforts", "modelProfile", "lastResort"]);
+
+export function parseComboTargets(value: unknown): Array<Record<string, unknown>> {
+  if (!Array.isArray(value) || value.length === 0) throw new CliUsageError("Targets input must be a nonempty array");
+  return value.map(target => {
+    if (target === null || typeof target !== "object" || Array.isArray(target)
+      || Object.keys(target).some(key => !TARGET_KEYS.has(key))) {
+      throw new CliUsageError("Targets input contains an invalid object or unsupported field");
+    }
+    for (const key of ["provider", "model"]) {
+      if (typeof target[key] !== "string" || !target[key].trim() || /[\u0000-\u001f\u007f]/u.test(target[key])) {
+        throw new CliUsageError("Each target requires a nonblank provider and raw model ID without control characters");
+      }
+    }
+    if (Object.hasOwn(target, "weight") && (typeof target.weight !== "number"
+      || !Number.isInteger(target.weight) || target.weight < 1 || target.weight > 10_000)) {
+      throw new CliUsageError("Target weight must be an integer from 1 to 10000");
+    }
+    if (Object.hasOwn(target, "reasoningEfforts") && (!Array.isArray(target.reasoningEfforts)
+      || target.reasoningEfforts.length === 0
+      || target.reasoningEfforts.some((effort: unknown) => typeof effort !== "string" || !isCodexReasoningEffort(effort))
+      || new Set(target.reasoningEfforts).size !== target.reasoningEfforts.length)) {
+      throw new CliUsageError("Target reasoningEfforts must contain unique low, medium, high, xhigh, max or ultra values");
+    }
+    if (Object.hasOwn(target, "modelProfile") && (typeof target.modelProfile !== "string"
+      || !target.modelProfile.trim() || target.modelProfile.length > JEV_MAX_CANDIDATE_FIELD_CHARS
+      || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(target.modelProfile))) {
+      throw new CliUsageError("Target modelProfile must be nonblank, at most 512 characters, with no controls except tab or newline");
+    }
+    if (Object.hasOwn(target, "lastResort") && typeof target.lastResort !== "boolean") {
+      throw new CliUsageError("Target lastResort must be a boolean");
+    }
+    // Preserve raw slashes, target order, explicit false and omitted metadata.
+    return { ...target };
+  });
+}
+
+function takeNativeAlias(args: string[]): boolean | undefined {
+  const flag = "--native-alias";
+  const positions = args.flatMap((value, index) => value === flag || value.startsWith(`${flag}=`) ? [index] : []);
+  if (positions.length === 0) return undefined;
+  if (positions.length !== 1) throw new CliUsageError("--native-alias was given more than once");
+  const index = positions[0]!;
+  const token = args[index]!;
+  const inline = token !== flag;
+  const next = inline ? token.slice(flag.length + 1) : args[index + 1];
+  if (!inline && (next === undefined || next.startsWith("--"))) {
+    args.splice(index, 1);
+    return true;
+  }
+  if (next !== "on" && next !== "off") throw new CliUsageError("--native-alias accepts on, off, or the legacy bare flag");
+  args.splice(index, inline ? 1 : 2);
+  return next === "on";
+}
+
+/** Consume only extension options, before the parent set flow resolves a target or reads HTTP. */
+export async function prepareComboInput(args: string[], deps: RuntimeApiDeps = {}): Promise<ComboInput> {
+  const file = takeOptionWithSyntax(args, "--targets-file")?.value;
+  const image = takeOptionWithSyntax(args, "--image-input")?.value;
+  const reasoning = takeOptionWithSyntax(args, "--reasoning-effort-mode")?.value;
+  const nativeAlias = takeNativeAlias(args);
+  if (file !== undefined && args.some(arg => arg === "--targets" || arg.startsWith("--targets="))) {
+    throw new CliUsageError("--targets-file cannot be combined with --targets");
+  }
+  if (image !== undefined && image !== "auto" && image !== "disabled") {
+    throw new CliUsageError("--image-input must be auto or disabled");
+  }
+  if (reasoning !== undefined && reasoning !== "strict" && reasoning !== "adaptive") {
+    throw new CliUsageError("--reasoning-effort-mode must be strict or adaptive");
+  }
+  return {
+    ...(file === undefined ? {} : { targets: parseComboTargets(await readJsonInput(file, deps)) }),
+    ...(image === undefined ? {} : { imageInput: image }),
+    ...(reasoning === undefined ? {} : { reasoningEffortMode: reasoning }),
+    ...(nativeAlias === undefined ? {} : { nativeAlias }),
+  };
+}

package/src/cli/combo-result.ts

@@ -0,0 +1,52 @@
+import { parseComboTargets } from "./combo-input";
+import { printCatalogResult } from "./catalog-command-result";
+
+const ENUMS: Readonly<Record<string, readonly (string | null)[]>> = {
+  strategy: ["failover", "round-robin", "random", "least-used", "reset-window", "jev"],
+  defaultEffort: [null, "low", "medium", "high", "xhigh", "max", "ultra"],
+  defaultEffortMode: ["fallback", "force"], reasoningEffortMode: ["strict", "adaptive"],
+  imageInput: ["auto", "disabled"], cooldownWaitPolicy: ["before-last-resort"],
+};
+const STRINGS = new Set(["alias", "displayName", "decisionProvider", "decisionModel"]);
+const RANGES: Readonly<Record<string, readonly [number, number]>> = {
+  stickyLimit: [1, 100], cooldownMs: [1, 600_000], waitForCooldownMs: [0, 600_000],
+  decisionTimeoutMs: [1_000, 120_000],
+};
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+function invalid(): never { throw new Error("Invalid combo receipt"); }
+
+/** Shape/field ownership only; target graph/alias semantics remain on the server. */
+function publicCombo(value: unknown): Record<string, unknown> {
+  if (!record(value)) invalid();
+  let targets: Array<Record<string, unknown>>;
+  try { targets = parseComboTargets(value.targets); } catch { return invalid(); }
+  const result: Record<string, unknown> = { targets };
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "targets") continue;
+    if (Object.hasOwn(ENUMS, key)) {
+      if (!ENUMS[key]!.includes(child as string | null)) invalid();
+    } else if (STRINGS.has(key)) {
+      if (typeof child !== "string" || child.length > 4096) invalid();
+    } else if (Object.hasOwn(RANGES, key)) {
+      const [min, max] = RANGES[key]!;
+      if (typeof child !== "number" || !Number.isSafeInteger(child) || child < min || child > max) invalid();
+    } else if (key === "nativeAlias") {
+      if (typeof child !== "boolean") invalid();
+    } else invalid();
+    result[key] = child;
+  }
+  return result;
+}
+
+export function printComboWriteResult(value: unknown, id: string, wantsJson: boolean): number {
+  if (!record(value) || value.success !== true || value.id !== id || typeof value.model !== "string"
+    || Object.keys(value).some(key => !["success", "id", "model", "combo", "catalogRefresh"].includes(key))) invalid();
+  const combo = publicCombo(value.combo);
+  const model = typeof combo.alias === "string" && combo.alias.trim() ? combo.alias.trim() : `combo/${id}`;
+  if (value.model !== model) invalid();
+  return printCatalogResult({ success: true, id, model: value.model, combo }, value.catalogRefresh,
+    wantsJson, [`Saved combo ${id}.`]);
+}