@bitkyc08/opencodex 2.76.0 → 2.77.0

package/src/claude/intercept/picker-budget.ts

@@ -0,0 +1,41 @@
+import { jsonUtf8Bytes } from "../../lib/json-byte-size";
+
+export const PICKER_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+const MAX_FIELD_BYTES = 64 * 1024;
+const MAX_ROW_BYTES = 256 * 1024;
+const MAX_ADDED_BYTES = 2 * 1024 * 1024;
+const MAX_ADDED_ROWS = 4096;
+
+/** Inspect references only: no deep copy or serialized string is allocated by preflight. */
+export function pickerRowBytes(row: Record<string, unknown>): number {
+  for (const key of Object.keys(row)) {
+    jsonUtf8Bytes(key, MAX_FIELD_BYTES);
+    if (row[key] !== undefined) jsonUtf8Bytes(row[key], MAX_FIELD_BYTES);
+  }
+  return jsonUtf8Bytes(row, MAX_ROW_BYTES);
+}
+
+/** One budget for the entire response, including duplicate surfaces and the CLI fallback. */
+export class PickerRewriteBudget {
+  private outputBytes: number;
+  private addedBytes = 0;
+  private addedRows = 0;
+
+  constructor(body: unknown) {
+    this.outputBytes = jsonUtf8Bytes(body, PICKER_MAX_OUTPUT_BYTES);
+  }
+
+  reserveBytes(bytes: number): void {
+    if (bytes > MAX_ADDED_BYTES - this.addedBytes || bytes > PICKER_MAX_OUTPUT_BYTES - this.outputBytes) {
+      throw new RangeError("Picker rewrite byte limit");
+    }
+    this.addedBytes += bytes;
+    this.outputBytes += bytes;
+  }
+
+  reserveRow(row: Record<string, unknown>): void {
+    if (++this.addedRows > MAX_ADDED_ROWS) throw new RangeError("Picker rewrite row limit");
+    // Include a separator even for an empty list, conservatively reserving one extra byte.
+    this.reserveBytes(pickerRowBytes(row) + 1);
+  }
+}

package/src/claude/outbound.ts

@@ -248,6 +248,7 @@ export function anthropicIncompleteOutcome(
  */
 export function anthropicFailedStatus(error: Rec, message: string): number {
   const code = typeof error.code === "string" ? error.code : undefined;
+  if (code === "context_length_exceeded") return 400;
   return code === "translation_buffer_limit"
     ? 413
     : typeof error.status === "number"
@@ -726,6 +727,7 @@ export function responsesSseToAnthropicSse(
               status,
               message,
               true,
+              code === "context_length_exceeded" ? code : undefined,
             );
             break;
           }

package/src/claude/subagent-force-status.ts

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { claudeConfigDir } from "./gateway-cache";
+import { commandInvocation } from "../lib/win-exec";
+
+export interface SubagentForceStatus {
+  targetValid: boolean;
+  version: string | null;
+  support: "supported" | "unsupported" | "unknown";
+  settingsOverride: boolean;
+  settingsReadable: boolean;
+}
+
+export function subagentForceSupport(version: string | null): SubagentForceStatus["support"] {
+  const match = version?.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) return "unknown";
+  const [major, minor, patch] = match.slice(1).map(Number);
+  return major! > 2 || (major === 2 && (minor! > 1 || (minor === 1 && patch! >= 257))) ? "supported" : "unsupported";
+}
+
+function installedVersion(): Promise<string | null> {
+  const invocation = commandInvocation("claude", ["--version"]);
+  return new Promise(resolve => {
+    execFile(invocation.file, invocation.args, { ...invocation.options, timeout: 1500, maxBuffer: 4096 }, (error, stdout) => {
+      resolve(error ? null : /^\s*(\d+\.\d+\.\d+)(?:\s|$)/.exec(String(stdout))?.[1] ?? null);
+    });
+  });
+}
+
+/** Server-local observation only: never returns settings values or modifies settings. */
+export async function inspectSubagentForceStatus(
+  targetValid: boolean,
+  configDir = claudeConfigDir(),
+  versionProbe: () => Promise<string | null> = installedVersion,
+): Promise<SubagentForceStatus> {
+  const version = await versionProbe().catch(() => null);
+  let settingsOverride = false;
+  let settingsReadable = true;
+  try {
+    const path = join(configDir, "settings.json");
+    const metadata = await stat(path);
+    if (!metadata.isFile() || metadata.size > 1_048_576) throw new Error("settings unavailable");
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid settings");
+    const env = parsed.env;
+    settingsOverride = !!env && typeof env === "object" && !Array.isArray(env)
+      && (Object.hasOwn(env, "CLAUDE_CODE_SUBAGENT_MODEL") || Object.hasOwn(env, "CLAUDE_CODE_SUBAGENT_MODEL_FORCE"));
+  } catch (error) {
+    settingsReadable = (error as NodeJS.ErrnoException).code === "ENOENT";
+  }
+  return { targetValid, version, support: subagentForceSupport(version), settingsOverride, settingsReadable };
+}

package/src/claude/subagent-model.ts

@@ -0,0 +1,93 @@
+import type { OcxConfig } from "../types";
+import { claudeCodeAlias, claudeCodeNativeAlias, resolveAlias } from "./alias";
+import { AUTO_CONTEXT_OFF, shouldMarkOneMillion, stripOneMillionMarker, withOneMillionMarker } from "./context-windows";
+import { hasOwnProvider } from "../config";
+import { knownModelIdsForProvider } from "../router";
+import { decodeRoutedModelIdOrThrow } from "../providers/slug-codec";
+import { SAFE_AGENT_MODEL_ID } from "../config/subagent-models";
+import { resolveDesktop3pAlias } from "./desktop-3p";
+export { SAFE_AGENT_MODEL_ID } from "../config/subagent-models";
+
+/** Roster entry -> alias + display parts. Entries are bare native slugs or "provider/id".
+ * Codex-facing encoded ids (`provider/vendor-model`) decode to the native slash id first
+ * so the alias joins the raw-native context-window map (context-windows.ts). */
+
+/**
+ * Generated subagent defs cannot rely on the parent's auto-context compaction
+ * pairing, so their [1m] marker follows the AUTHORITATIVE window only: mark when
+ * the effective window (exact selector, then the canonical [1m] form, then bare)
+ * is genuinely >= 1M; strip an inherited unsafe marker back to the bare selector;
+ * with no window information, keep the selector as it was. Genuine routed [1m]
+ * ids are preserved through the canonical-exact lookup. (#854)
+ */
+export function withSubagentContextMarker(selector: string, windows: Record<string, number>): string {
+  const bare = stripOneMillionMarker(selector);
+  const wasMarked = selector !== bare;
+  const canonicalExact = wasMarked ? `${bare}[1m]` : selector;
+  const authoritativeWindow = windows[selector] ?? windows[canonicalExact] ?? windows[bare];
+  if (typeof authoritativeWindow === "number" && authoritativeWindow > 0) {
+    return shouldMarkOneMillion(authoritativeWindow, AUTO_CONTEXT_OFF)
+      ? (withOneMillionMarker(selector, windows) ?? selector)
+      : bare;
+  }
+  return wasMarked ? selector : bare;
+}
+export function entryParts(entry: string, config: OcxConfig): { alias: string; id: string; provider: string } {
+  const slash = entry.indexOf("/");
+  if (slash > 0) {
+    const provider = entry.slice(0, slash);
+    const prov = hasOwnProvider(config.providers, provider) ? config.providers[provider] : undefined;
+    const id = prov
+      ? decodeRoutedModelIdOrThrow(entry.slice(slash + 1), knownModelIdsForProvider(provider, prov, config))
+      : entry.slice(slash + 1);
+    return { alias: claudeCodeAlias(provider, id), id, provider };
+  }
+  return { alias: claudeCodeNativeAlias(entry), id: entry, provider: "native" };
+}
+
+export type SubagentForceExposure = { entries: readonly string[] } | { selectors: readonly string[] };
+
+function fullSelectorIdentity(selector: string): string {
+  const route = resolveAlias(selector) ?? resolveDesktop3pAlias(selector) ?? selector;
+  return (route.startsWith("native/") ? route.slice("native/".length) : route).replace(/\[1m\]$/i, "[1m]");
+}
+
+function selectorIdentity(selector: string): string {
+  return fullSelectorIdentity(stripOneMillionMarker(selector));
+}
+
+/** Resolve only currently exposed entries; retained roster rows are not exposure proof. */
+export function resolveSubagentForceModel(config: OcxConfig, windows: Record<string, number>, available: SubagentForceExposure): string | null {
+  const entry = config.claudeCode?.subagentModelForce;
+  if (typeof entry !== "string" || !SAFE_AGENT_MODEL_ID.test(entry)) return null;
+  try {
+    const parts = entryParts(entry, config);
+    if ((config.disabledModels ?? []).some(disabled => {
+      try { return selectorIdentity(entryParts(disabled, config).alias) === selectorIdentity(parts.alias); } catch { return false; }
+    })) return null;
+    const selectors = "selectors" in available ? available.selectors : available.entries.flatMap(candidate => {
+      try { return [entryParts(candidate, config).alias]; } catch { return []; }
+    });
+    const exposed = selectors.some(candidate => selectorIdentity(candidate) === selectorIdentity(parts.alias));
+    if (!exposed) return null;
+    const bare = stripOneMillionMarker(parts.alias);
+    const requestedMarker = bare !== parts.alias;
+    const exactMarkedExposure = requestedMarker && selectors.some(candidate =>
+      fullSelectorIdentity(candidate) === fullSelectorIdentity(parts.alias));
+    const window = windows[parts.alias] ?? windows[`${bare}[1m]`] ?? windows[bare];
+    // Identity admission must not let an appended context promise ride on an
+    // ordinary exposed model. Exact catalog ids such as kimi/k3[1m] remain literal.
+    if (requestedMarker && !exactMarkedExposure && !(typeof window === "number" && Number.isFinite(window) && window >= 1_000_000)) return null;
+    const marked = exactMarkedExposure ? parts.alias : withSubagentContextMarker(parts.alias, windows);
+    // Bare Anthropic names are indistinguishable from the old CLI's fallback.
+    // Encode only the force selector; handlers restore native identity before
+    // their existing credential/model-map checks. Roster generation is unchanged.
+    if (parts.alias.startsWith("claude-") && !resolveAlias(parts.alias) && !resolveDesktop3pAlias(parts.alias)) {
+      const native = claudeCodeNativeAlias(stripOneMillionMarker(marked));
+      return marked === stripOneMillionMarker(marked) ? native : `${native}[1m]`;
+    }
+    return marked;
+  } catch {
+    return null;
+  }
+}

package/src/cli/account-api.ts

@@ -27,6 +27,7 @@ export interface AccountRow {
   masked?: string;
   active: boolean;
   needsReauth?: boolean;
+  needsReauthReason?: "verify_account";
   autoSelectable?: boolean;
   skipReason?: "paused" | "needs_reauth" | "suspended" | "cooldown" | "quota_exhausted";
   selectionExcludedReason?: "plan_excluded";
@@ -348,6 +349,7 @@ interface OAuthAccountDto {
   /** Present only for providers that support operator pause (generic OAuth pools). */
   paused?: boolean;
   autoSwitchThresholdOverride?: number | null;
+  needsReauthReason?: "verify_account";
   autoSelectable?: boolean;
   skipReason?: unknown;
   /** Always sent by the management route; explicitly `null` when the tier is unknown. */
@@ -390,6 +392,7 @@ async function fetchOAuthRows(
     needsReauth: a.needsReauth,
     ...(a.paused === true ? { paused: true } : {}),
     ...(name === "anthropic" && Object.hasOwn(a, "autoSwitchThresholdOverride") ? { autoSwitchThresholdOverride: a.autoSwitchThresholdOverride } : {}),
+    ...(a.needsReauthReason === "verify_account" ? { needsReauthReason: a.needsReauthReason } : {}),
     ...(name === "kiro" && typeof a.autoSelectable === "boolean"
       ? { autoSelectable: a.autoSelectable } : {}),
     ...(name === "kiro" && a.autoSelectable === false && isKiroSkipReason(a.skipReason)

package/src/cli/account.ts

@@ -110,7 +110,9 @@ function statusText(row: AccountRow): string {
   // held out -- so printing only one of the two would hide exactly the confusing case (#2703).
   if (row.paused) parts.push("paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
-  if (row.needsReauth && !(row.provider === "kiro" && row.skipReason === "needs_reauth")) parts.push("needs-reauth");
+  if (row.needsReauth && !(row.provider === "kiro" && row.skipReason === "needs_reauth")) {
+    parts.push(row.needsReauthReason === "verify_account" ? "needs-reauth(verify)" : "needs-reauth");
+  }
   // A paused Kiro row already says "paused"; repeating it as a skip reason adds nothing.
   if (row.provider === "kiro" && row.autoSelectable === false && !(row.paused && row.skipReason === "paused"))
     parts.push(row.skipReason ? `not-auto-selected(${row.skipReason})` : "not-auto-selected");

package/src/cli/agent.ts

@@ -28,6 +28,7 @@ const USAGE = `Usage:
   ocx agent injection suggest <work description> [--model <id>] [--apply] [--json]
   ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
   ocx agent subagents <status|set|clear> [model,model...] [--json]
+  ocx agent subagents force <model|-> [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
   ocx agent roles [status|set <role> <model>|suggest [--model <id>] [--apply]] [--json]
   ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
@@ -169,6 +170,15 @@ async function subagents(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     printData(result, wantsJson, summaryLines(result));
     return;
   }
+  if (action === "force") {
+    const model = args.shift();
+    if (!model?.trim()) throw new CliUsageError("a force model or - is required", USAGE);
+    rejectArgs(args, USAGE);
+    const force = clearable(model);
+    const result = await runtimeRequest("/api/subagent-models", { method: "PUT", body: JSON.stringify({ force }) }, deps);
+    printData(result, wantsJson, [force ? `Claude subagent force: ${force}. Applies on the next routed ocx claude launch.` : "Claude subagent force cleared."]);
+    return;
+  }
   let models: string[];
   if (action === "clear") models = [];
   else if (action === "set") {

package/src/cli/capabilities.ts

@@ -1063,6 +1063,15 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "none",
     details: ["The Aside refresh uses the live server; other catalog synchronization also performs local work."],
   },
+  {
+    command: ["agent", "subagents", "force"],
+    summary: "Force Claude Code subagents onto one exposed model at the next routed launch; - clears.",
+    routes: [{ method: "GET", path: "/api/subagent-models" }, { method: "PUT", path: "/api/subagent-models" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the saved force setting." }],
+    mutates: true,
+    json: "payload",
+    details: ["Requires Claude Code 2.1.257+. Plain claude, forks, inherit skills, the main model and small-fast sidecars are unaffected."],
+  },
   {
     command: ["agent", "request-user-input"],
     summary: "Show or set whether default mode may ask the operator a question mid-task.",

package/src/cli/chatgpt-command.ts

@@ -101,23 +101,26 @@ 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.');
         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.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-readiness.ts

@@ -3,6 +3,8 @@ import {
   getCodexRoutingKind,
   type CodexRoutingKind,
 } from "../codex/inject";
+import { diagnoseCodexShim, type CodexShimDiagnostic } from "../codex/shim";
+import { findFirstCodexOnPath, type CodexPathCandidate } from "../codex/shim-path-resolution";
 import { loadConfig, resolveEnvValue } from "../config";
 
 const PROXY_ENV_KEYS = [
@@ -21,6 +23,93 @@ 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">;
+  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">;
+  commandPath: string | null;
+  commandIsShim?: boolean;
+}): CodexConnectShimReadiness {
+  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">;
+  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)}`

package/src/cli/connect.ts

@@ -40,6 +40,10 @@ import {
   terminalSafeText,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import {
+  inspectCodexShimForConnect,
+  type CodexConnectShimReadiness,
+} from "./codex-shim-readiness";
 
 export interface ClientCommandDeps extends RuntimeApiDeps {
   lifecycleLockDeps?: ClientLifecycleLockDeps;
@@ -277,6 +281,19 @@ export type ConnectCompletionReport = {
   readonly failure: string | null;
 };
 
+export function codexShimReadinessLine(
+  selectedClients: readonly OcxConnectedClientId[],
+  inspect: () => CodexConnectShimReadiness = inspectCodexShimForConnect,
+): string | null {
+  if (!selectedClients.includes("codex")) return null;
+  return `Codex autostart shim: ${terminalSafeText(inspect().message)}`;
+}
+
+function printCodexShimReadiness(selectedClients: readonly OcxConnectedClientId[]): void {
+  const line = codexShimReadinessLine(selectedClients);
+  if (line) console.log(line);
+}
+
 /**
  * What `ocx connect` says once the hub and the credential are settled, and whether the command
  * still fails (#4207).
@@ -414,6 +431,7 @@ async function runHubConnect(argv: string[], deps: ClientCommandDeps): Promise<v
   const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {});
   const report = connectCompletionReport(connection, clients, readiness);
   for (const line of report.lines) console.log(line);
+  printCodexShimReadiness(clients);
   if (report.failure) throw new Error(report.failure);
 }
 
@@ -463,6 +481,7 @@ async function runLinkConnect(argv: string[], deps: ClientCommandDeps): Promise<
   const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {});
   const report = connectCompletionReport(connection, clients, readiness);
   for (const line of report.lines) console.log(line);
+  printCodexShimReadiness(clients);
   if (report.failure) throw new Error(report.failure);
 }
 

package/src/cli/dispatch.ts

@@ -17,6 +17,7 @@ import type { LivenessIo, LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import type { OwnedIntegrationRefreshOutcome } from "../integrations/owned-refresh";
 import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
+import { printUnknownCommand } from "./help-recovery";
 import {
   HUB_GATED_SKIP_MESSAGE,
   localClientSkipMessage,
@@ -514,7 +515,7 @@ const commandRunners: Record<string, CommandRunner> = {
             },
             config,
             port: live.port,
-          }, ["mcode", "pi", "raycast", "omo", "cline", "droid"]));
+          }, ["mcode", "pi", "raycast", "omo", "cline", "droid", "opencode", "kilo"]));
         } catch (error) {
           console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
         }
@@ -1167,8 +1168,7 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
   }
   const runner = commandRunners[resolveDispatchCommand(command) ?? ""];
   if (!runner) {
-    console.error(`Unknown command: ${command}`);
-    printUsage();
+    printUnknownCommand(command);
     return 1;
   }
   return await runner(deps);

package/src/cli/export-command.ts

@@ -66,12 +66,13 @@ export interface ExportCommandDeps extends RuntimeApiDeps {
  * `opencodeCatalogFromProxyRows` owns the visibility rules (drop `disabled`, drop dupes,
  * drop native under Codex Direct) — the export core does none of that, so a row filtered
  * here is the only thing keeping a disabled model out of a client's picker. It also carries
- * the effort ladder, so the ladder a client receives comes from the same filtered, deduped
- * row as the model itself: a second lookup over the raw rows would let a hidden or disabled
- * duplicate donate its ladder to the visible entry.
+ * the effort ladder and the effective custom-row projection, so every per-model field a
+ * client receives comes from the same filtered, deduped row as the model itself: a second
+ * lookup over the raw rows would let a hidden or disabled duplicate donate its ladder to
+ * the visible entry.
  *
- * Modalities need no such lookup: `opencodeCatalogFromProxyRows` carries them on the catalog
- * entry, so the clients that filter them are handed the same filtered, deduped row.
+ * The empty-vs-undefined ladder distinction survives the hop: a row declaring `[]` exports
+ * `[]` (explicit "no rungs"), a row declaring nothing exports nothing (unknown).
  */
 export function exportModelsFromProxyRows(
   rows: readonly OpencodeProxyModelRow[],
@@ -87,13 +88,21 @@ export function exportModelsFromProxyRows(
     if (entry.fastRowAvailable !== undefined) model.fastRowAvailable = entry.fastRowAvailable;
     if (entry.displayName) model.displayName = entry.displayName;
     if (entry.contextWindow !== undefined) model.contextWindow = entry.contextWindow;
-    if (entry.reasoningEfforts && entry.reasoningEfforts.length > 0) {
-      model.reasoningEfforts = [...entry.reasoningEfforts];
-    }
+    // The catalog row's own output limit; dropping it here is what once made every CLI
+    // export fall back to the generated-metadata guess the management path never used.
+    if (entry.maxTokens !== undefined) model.maxTokens = entry.maxTokens;
+    if (entry.maxInputTokens !== undefined) model.maxInputTokens = entry.maxInputTokens;
+    if (entry.reasoningEfforts !== undefined) model.reasoningEfforts = [...entry.reasoningEfforts];
     if (entry.defaultReasoningEffort) model.defaultReasoningEffort = entry.defaultReasoningEffort;
     if (entry.inputModalities && entry.inputModalities.length > 0) {
       model.inputModalities = [...entry.inputModalities];
     }
+    // Explicit booleans survive, false included; nothing infers a negative from absence.
+    if (entry.supportsTools !== undefined) model.supportsTools = entry.supportsTools;
+    if (entry.supportsReasoning !== undefined) model.supportsReasoning = entry.supportsReasoning;
+    if (entry.supportsReasoningSummaries !== undefined) {
+      model.supportsReasoningSummaries = entry.supportsReasoningSummaries;
+    }
     return model;
   });
 }
@@ -194,7 +203,9 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     // `--out` is the path that writes the selected client's native format.
     // Format metadata rides in the human lines below.
     printData(clientConfig, wantsJson, [
-      text.trimEnd(),
+      // `lines` entries print one console line each and are control-escaped, so
+      // the document goes in as individual lines rather than one multi-line blob.
+      ...text.trimEnd().split("\n"),
       "",
       ...(out !== undefined ? [`Wrote ${out}`] : []),
       `Destination: ${spec.destination(process.env)}`,