@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

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"}`);
@@ -101,23 +120,30 @@ CODEX_CLI_PATH launcher: ${app.shim ? "yes" : "no"}`);
       console.error("ChatGPT (com.openai.codex) was not found; install or open it once, then retry.");
       return 1;
     }
+    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;
       }
-      const binary = resolveChatgptCodexBinary(install.root);
+      binary = resolveChatgptCodexBinary(install.root) ?? undefined;
       if (!binary) {
         console.error(`No bundled app-server binary was found in ${install.root}; the shim cannot launch this build.`);
         return 1;
       }
-      const untrusted = untrustedChatgptBundleReason(install.root, binary);
-      if (untrusted) {
-        console.error(`Refusing to launch the shim: ${untrusted}.`);
-        return 1;
-      }
-      writeChatgptShimLauncher(undefined, binary);
     }
+    // Both relaunch paths execute the discovered bundle. Restore validates the app
+    // shell without requiring an app-server binary or the experimental opt-in flag.
+    const untrusted = untrustedChatgptBundleReason(install.root, binary);
+    if (untrusted) {
+      console.error(`Refusing to ${sub === "launch" ? "launch the shim" : "restore ChatGPT"}: ${untrusted}.`);
+      return 1;
+    }
+    if (binary) writeChatgptShimLauncher(undefined, binary);
     if (!(await quitApp(install, launcher))) {
       console.error("ChatGPT did not quit; quit it manually and retry.");
       return 1;

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/claude.ts

@@ -7,12 +7,13 @@
  * `claude` CLI with stdio inherited. User-exported env wins except when a stale
  * loopback opencodex base URL points at a different proxy port.
  */
+import { resolveSubagentForceModel } from "../claude/subagent-model";
 import { spawn } from "node:child_process";
 import { loadConfig } from "../config";
 import { injectClaudeAgentDefs } from "../claude/agents-inject";
 import { CLAUDE_ALIAS_PREFIX_CURRENT, CLAUDE_ALIAS_PREFIX_CURRENT_V2, CLAUDE_ALIAS_PREFIX_V1, CLAUDE_ALIAS_PREFIX_V2 } from "../claude/alias";
 import { claudeToolSearchEnv, effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
-import { claudeConfigDir, refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
+import { claudeConfigDir, fetchGatewayModels, writeGatewayModelCache } from "../claude/gateway-cache";
 import { commandInvocation } from "../lib/win-exec";
 import { isProxyAdmissionSecret } from "../server/auth-cors";
 import { findLiveProxy } from "../server/proxy-liveness";
@@ -50,6 +51,8 @@ export interface ClaudeRoutingTarget {
  * launch base so detection and the spawned process can never disagree (audit R3-3).
  */
 export type ClaudeEnvDeps = {
+  forceAvailable?: readonly string[];
+  forceAvailableSelectors?: readonly string[];
   authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens">;
   /** Test seam; production uses the authenticated Node-launcher context. */
   preBunAnthropicSlots?: readonly AnthropicParentEnvSlot[] | null;
@@ -213,6 +216,15 @@ export function buildClaudeEnv(
     if (env[name] !== undefined && env[name] !== "") return; // user wins
     env[name] = value;
   };
+  if (config.claudeCode?.subagentModelForce !== undefined) {
+    const forced = resolveSubagentForceModel(config, contextWindows, deps.forceAvailableSelectors !== undefined ? { selectors: deps.forceAvailableSelectors } : { entries: deps.forceAvailable ?? [] });
+    if (forced) {
+      setDefault("CLAUDE_CODE_SUBAGENT_MODEL", forced);
+      setDefault("CLAUDE_CODE_SUBAGENT_MODEL_FORCE", "1");
+    } else {
+      (deps.warn ?? console.warn)("⚠ Claude subagent force target is invalid or unavailable; launch override skipped.");
+    }
+  }
   if (deps.allowRootSkipPermissions === true) {
     setDefault("IS_SANDBOX", "1");
   }
@@ -420,6 +432,7 @@ export function buildClaudeEnv(
  * decides to launch natively, so a wrong destination here silently downgrades every launch.
  */
 export interface ClaudeCodeLiveState {
+  forceAvailable?: string[];
   contextWindows: Record<string, number>;
   enabled?: boolean;
 }
@@ -434,9 +447,10 @@ export async function fetchClaudeCodeState(config: OcxConfig, port: number, time
       signal: AbortSignal.timeout(timeoutMs),
     });
     if (!res.ok) return { contextWindows: {} };
-    const body = await res.json() as { contextWindows?: Record<string, number>; enabled?: boolean };
+    const body = await res.json() as { contextWindows?: Record<string, number>; enabled?: boolean; forceAvailable?: string[] };
     return {
       contextWindows: body.contextWindows && typeof body.contextWindows === "object" ? body.contextWindows : {},
+      ...(Array.isArray(body.forceAvailable) ? { forceAvailable: body.forceAvailable.filter(value => typeof value === "string") } : {}),
       ...(typeof body.enabled === "boolean" ? { enabled: body.enabled } : {}),
     };
   } catch {
@@ -774,6 +788,7 @@ export async function cmdClaude(args: string[]): Promise<number> {
   if (preflight.kind === "native") return launchNativeClaude(config, args, preflight.notice);
   let route: number | ClaudeRoutingTarget;
   let contextWindows: Record<string, number>;
+  let forceAvailable: readonly string[] | undefined;
   /** The hub's featured roster on a connected client; undefined means "use local config". */
   let hubRoster: readonly string[] | undefined;
   if (clientState.kind === "connected") {
@@ -792,18 +807,19 @@ export async function cmdClaude(args: string[]): Promise<number> {
     if (plan.kind === "native") return launchNativeClaude(config, args, plan.notice);
     route = port;
     contextWindows = liveState.contextWindows;
+    forceAvailable = liveState.forceAvailable ?? [];
   }
+  const gateway = await fetchGatewayModels(route, { admissionConfig: config });
+  const forceAvailableSelectors = typeof route === "number" ? undefined : gateway?.models.map(model => model.id) ?? [];
   const allowRootSkipPermissions = shouldAllowRootSkipPermissions(args);
-  const env = buildClaudeEnv(config, route, process.env, contextWindows, { allowRootSkipPermissions });
+  const env = buildClaudeEnv(config, route, process.env, contextWindows, { allowRootSkipPermissions, forceAvailable, forceAvailableSelectors });
   if (allowRootSkipPermissions) {
     console.error(rootSkipPermissionsNotice(env));
   }
   // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
   // never refreshes it, so the picker would keep showing yesterday's aliases.
   try {
-    const cachePath = typeof route === "number"
-      ? await refreshGatewayModelCacheFromProxy(route, { admissionConfig: config })
-      : await refreshGatewayModelCacheFromProxy(route, { admissionConfig: config });
+    const cachePath = gateway ? writeGatewayModelCache(gateway.baseUrl, gateway.models) : null;
     if (cachePath === null) {
       console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
     }

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

@@ -3,6 +3,9 @@ import {
   getCodexRoutingKind,
   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";
 
 const PROXY_ENV_KEYS = [
@@ -21,6 +24,112 @@ export interface CodexShimReadinessInputs {
   configuredProxyResolved: boolean;
 }
 
+export type CodexConnectShimStatus = "ready" | "missing" | "unhealthy" | "unverified";
+
+export interface CodexConnectShimReadiness {
+  status: CodexConnectShimStatus;
+  /** Secret-free, actionable text rendered by ocx connect. */
+  message: string;
+}
+
+export interface CodexConnectShimInspectionDeps {
+  diagnose?: () => Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary" | "runnable" | "active">;
+  findOnPath?: () => CodexPathCandidate | null;
+}
+
+const CODEX_TOKEN_NOTE = "The connected Codex config uses OPENCODEX_API_AUTH_TOKEN; "
+  + "without a working shim or when a PATH wrapper replaces it, Codex may fail with "
+  + '"Missing environment variable".';
+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" | "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",
+      message: `installed but unhealthy: ${inputs.diagnosis.summary}. ${CODEX_TOKEN_ACTION}`,
+    };
+  }
+  if (inputs.diagnosis.healthy && inputs.commandPath && !inputs.commandIsShim) {
+    // The shim is installed and healthy, so reinstalling it cannot fix this: only PATH
+    // order (or the wrapper in front of it) can.
+    return {
+      status: "missing",
+      message: `not active; PATH resolves 'codex' to ${inputs.commandPath}, not an OpenCodex shim. `
+        + `Shim state: ${inputs.diagnosis.summary}. Put the directory of the tracked shim ahead of that command on PATH, `
+        + `or remove that wrapper; re-running 'ocx codex-shim install' will not change PATH order. ${CODEX_TOKEN_NOTE}`,
+    };
+  }
+  if (inputs.diagnosis.installed && inputs.diagnosis.healthy) {
+    if (!inputs.commandPath) {
+      return {
+        status: "missing",
+        message: `installed but not active; no 'codex' executable was found on PATH. `
+          + `Shim state: ${inputs.diagnosis.summary}. Add the directory of the tracked shim to PATH. ${CODEX_TOKEN_NOTE}`,
+      };
+    }
+    return { status: "ready", message: "installed and healthy" };
+  }
+  if (inputs.commandPath) {
+    return {
+      status: "missing",
+      message: `not active; PATH resolves 'codex' to ${inputs.commandPath}, not an OpenCodex shim. ${CODEX_TOKEN_ACTION}`,
+    };
+  }
+  return {
+    status: "missing",
+    message: `not installed and no 'codex' executable was found on PATH. ${CODEX_TOKEN_ACTION}`,
+  };
+}
+
+export function inspectCodexShimForConnect(
+  deps: CodexConnectShimInspectionDeps = {},
+): CodexConnectShimReadiness {
+  let diagnosis: Pick<CodexShimDiagnostic, "installed" | "healthy" | "summary" | "runnable" | "active">;
+  try {
+    diagnosis = (deps.diagnose ?? diagnoseCodexShim)();
+  } catch {
+    diagnosis = { installed: true, healthy: false, summary: "diagnostic state could not be read" };
+  }
+  let command: CodexPathCandidate | null = null;
+  try {
+    command = (deps.findOnPath ?? findFirstCodexOnPath)();
+  } catch {
+    return {
+      status: "unverified",
+      message: `PATH activation could not be verified. Shim state: ${diagnosis.summary}. `
+        + `Check PATH and retry 'ocx connect'. ${CODEX_TOKEN_NOTE}`,
+    };
+  }
+  return codexConnectShimReadiness({
+    diagnosis,
+    commandPath: command?.path ?? null,
+    commandIsShim: command?.isShim ?? false,
+  });
+}
+
 function externalProviderLabel(provider: string | null): string {
   return provider
     ? `external model_provider ${JSON.stringify(provider)}`