@bitkyc08/opencodex 2.7.40 → 2.7.41

package/src/server/responses/passthrough-error.ts

@@ -0,0 +1,53 @@
+import { formatErrorResponse } from "../../bridge";
+import { parseRetryAfterMs } from "../../combos";
+
+function sanitizedRetryAfter(value: string | null | undefined, now: number): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed || trimmed.length > 128) return undefined;
+  return parseRetryAfterMs(trimmed, now) !== undefined ? trimmed : undefined;
+}
+
+/**
+ * Passthrough adapters historically relayed upstream non-2xx bodies verbatim.
+ * Codex maps an *empty* body to the literal client string "Unknown error"
+ * (UnexpectedResponseError) — issue #452. Only empty bodies need wrapping.
+ *
+ * Non-empty bodies (including ChatGPT `{detail: ...}` account-model 400s and
+ * HTML/text errors) must keep their original bytes and headers so pool-retry
+ * activation and client diagnostics stay honest.
+ *
+ * Normalized (empty-body) responses force `Content-Type: application/json` and
+ * preserve a validated `Retry-After` so Responses clients and the chat-completions
+ * / Claude bridges that copy that header keep correct backoff.
+ */
+export function formatPassthroughUpstreamError(
+  status: number,
+  bodyText: string,
+  options?: {
+    statusText?: string;
+    headers?: Headers;
+    now?: number;
+  },
+): Response {
+  const trimmed = bodyText.trim();
+  const now = options?.now ?? Date.now();
+  const retryAfter = sanitizedRetryAfter(options?.headers?.get("retry-after"), now);
+
+  if (trimmed) {
+    return new Response(bodyText, {
+      status,
+      ...(options?.statusText ? { statusText: options.statusText } : {}),
+      ...(options?.headers ? { headers: options.headers } : { headers: { "Content-Type": "application/json" } }),
+    });
+  }
+
+  const response = formatErrorResponse(
+    status,
+    "upstream_error",
+    `Provider error ${status}: (empty body)`,
+  );
+  const headers = new Headers(response.headers);
+  headers.set("Content-Type", "application/json");
+  if (retryAfter !== undefined) headers.set("Retry-After", retryAfter);
+  return new Response(response.body, { status: response.status, headers });
+}

package/src/server/search.ts

@@ -11,6 +11,7 @@
 import { formatErrorResponse } from "../bridge";
 import {
   CodexAccountCooldownError,
+  cooldownErrorResponse,
   CodexAuthContextError,
   CodexPoolAuthenticationError,
   CodexThreadAffinityExpiredError,
@@ -77,7 +78,7 @@ export async function handleSearch(
     logCtx.provider = formatCodexProviderForLog(upstream.providerName, codexLogAccountId(upstream.authContext), config);
   } catch (err) {
     if (err instanceof CodexAccountCooldownError) {
-      return formatErrorResponse(429, "rate_limit_error", "Selected Codex account is cooling down");
+      return cooldownErrorResponse(err);
     }
     if (err instanceof CodexThreadAffinityExpiredError) {
       return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");

package/src/server/system-env.ts

@@ -3,8 +3,25 @@ import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
 import { resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
+import { PROXY_MARKER, defaultAuthDetectDeps, detectClaudeAuth, ownAdmissionTokens } from "../claude/auth-detect";
+import { resolveClaudeAuthMode } from "../claude/auth-mode";
 import type { OcxConfig } from "../types";
 
+/**
+ * Does the opencodex dummy marker belong in the system environment?
+ *
+ * Keyed on the SAME resolver `ocx claude` uses, so an auto config with no Claude auth
+ * also reaches plain `claude` launches — before this, auto-absent users got nothing
+ * from auto-connect and the feature looked broken for exactly the people it helps
+ * (devlog 260726_claude_auth_auto/035).
+ *
+ * NOTE this is a SNAPSHOT: the file only changes when this runs (proxy start, `ocx
+ * ensure`, or a settings save). `ocx claude` re-resolves live on every launch.
+ */
+function systemEnvMarkerMode(config: OcxConfig): "proxy" | "subscription" {
+  return resolveClaudeAuthMode(config, detectClaudeAuth(defaultAuthDetectDeps(process.env, ownAdmissionTokens(config)))).markerMode;
+}
+
 // ---------------------------------------------------------------------------
 // Shell-hook env file: written on inject, sourced by the shell hook in .zshrc.
 // This works for ALL new shells immediately, unlike launchctl setenv which only
@@ -31,8 +48,8 @@ function writeShellEnvFile(port: number, config: OcxConfig, modelEnv: Record<str
     `[ -z "\${${name}+x}" ] && export ${name}=${shellValue(value)}`;
   if (config.apiKeys?.length) {
     lines.push(`export ANTHROPIC_AUTH_TOKEN=${shellValue(config.apiKeys[0].key)}`);
-  } else if (config.claudeCode?.authMode === "proxy") {
-    lines.push(conditional("ANTHROPIC_AUTH_TOKEN", "opencodex-proxy"));
+  } else if (systemEnvMarkerMode(config) === "proxy") {
+    lines.push(conditional("ANTHROPIC_AUTH_TOKEN", PROXY_MARKER));
   }
   // Model slots (default + tiers + legacy small-fast) with [1m] applied (devlog 260712 B2).
   if (modelEnv.ANTHROPIC_MODEL) {
@@ -240,11 +257,11 @@ export async function injectSystemEnv(port: number, config: OcxConfig): Promise<
     inject("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
     if (config.apiKeys?.length) {
       inject("ANTHROPIC_AUTH_TOKEN", config.apiKeys[0].key);
-    } else if (config.claudeCode?.authMode === "proxy" && launchctlGetenv("ANTHROPIC_AUTH_TOKEN") === undefined) {
-      inject("ANTHROPIC_AUTH_TOKEN", "opencodex-proxy");
-    } else if (config.claudeCode?.authMode !== "proxy"
+    } else if (systemEnvMarkerMode(config) === "proxy" && launchctlGetenv("ANTHROPIC_AUTH_TOKEN") === undefined) {
+      inject("ANTHROPIC_AUTH_TOKEN", PROXY_MARKER);
+    } else if (systemEnvMarkerMode(config) !== "proxy"
       && injectedKeys.includes("ANTHROPIC_AUTH_TOKEN")
-      && launchctlGetenv("ANTHROPIC_AUTH_TOKEN") === "opencodex-proxy") {
+      && launchctlGetenv("ANTHROPIC_AUTH_TOKEN") === PROXY_MARKER) {
       // Subscription switch-back (devlog 260720_claude_authmode_persist): remove ONLY
       // the opencodex-owned dummy token so a launchd-started Claude regains its own
       // claude.ai OAuth. User-set tokens (not tracked in injectedKeys, or carrying a

package/src/server/windows-tcp-drop.ts

@@ -0,0 +1,174 @@
+/**
+ * Soft SIGTERM-before-/F is NOT available on Windows (process.kill is TerminateProcess).
+ * Graceful drain is stopProxyGracefully(); this module only resets leftover TCBs after hard kill.
+ */
+import { dlopen, ptr, type Pointer } from "bun:ffi";
+import { execFileSync } from "node:child_process";
+
+export type TcpQuad = {
+  localAddr: string;
+  localPort: number;
+  remoteAddr: string;
+  remotePort: number;
+  state: string;
+};
+
+/** Parse netstat -ano rows whose local address uses `port`. Exported for tests. */
+export function parseTcpQuadsForLocalPort(output: string, port: number): TcpQuad[] {
+  const rows: TcpQuad[] = [];
+  const portSuffix = `:${port}`;
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!/^TCP\b/i.test(line)) continue;
+    const parts = line.split(/\s+/);
+    if (parts.length < 4) continue;
+    const local = parts[1]!;
+    const remote = parts[2]!;
+    const state = parts[3]!;
+    if (!local.endsWith(portSuffix) && !local.endsWith(`]:${port}`)) continue;
+    const localAddr = stripPort(local, port);
+    const remoteParsed = splitHostPort(remote);
+    if (!localAddr || !remoteParsed) continue;
+    rows.push({
+      localAddr,
+      localPort: port,
+      remoteAddr: remoteParsed.host,
+      remotePort: remoteParsed.port,
+      state,
+    });
+  }
+  return rows;
+}
+
+function stripPort(addr: string, port: number): string | null {
+  const suffix = `:${port}`;
+  if (addr.endsWith(suffix)) return addr.slice(0, -suffix.length).replace(/^\[|\]$/g, "") || "0.0.0.0";
+  return null;
+}
+
+function splitHostPort(addr: string): { host: string; port: number } | null {
+  if (addr === "0.0.0.0:0" || addr === "*:*" || addr === "[::]:0") {
+    return { host: "0.0.0.0", port: 0 };
+  }
+  const m = /^(?:\[([^\]]+)\]|([^:]+)):(\d+)$/.exec(addr);
+  if (!m) return null;
+  return { host: (m[1] ?? m[2] ?? "0.0.0.0").replace(/^::ffff:/i, ""), port: Number(m[3]) };
+}
+
+function ipv4ToWinUint32(addr: string): number | null {
+  const host = addr.replace(/^::ffff:/i, "");
+  // Refuse bare IPv6 — SetTcpEntry is IPv4-only; coercing "::"/"::1" to 0 would
+  // miss the real TCB and can hit an unrelated IPv4 wildcard row.
+  if (isBareIpv6Address(host)) return null;
+  if (host === "0.0.0.0" || host === "*") return 0;
+  const parts = host.split(".").map(Number);
+  if (parts.length !== 4 || parts.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+  return (parts[0]! | (parts[1]! << 8) | (parts[2]! << 16) | (parts[3]! << 24)) >>> 0;
+}
+
+/** True for bare IPv6 (including :: / ::1), false for dotted IPv4 and IPv4-mapped. */
+export function isBareIpv6Address(addr: string): boolean {
+  const host = String(addr || "").replace(/^\[|\]$/g, "").replace(/^::ffff:/i, "");
+  if (!host) return false;
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(host)) return false;
+  return host.includes(":");
+}
+
+export type WindowsTcpDropResult = {
+  /** Successful SetTcpEntry(DELETE_TCB) calls for IPv4 rows. */
+  dropped: number;
+  /** IPv6 (or unparseable) rows skipped — never coerced into IPv4 wildcards. */
+  skippedIpv6: number;
+};
+
+function htons(port: number): number {
+  return (((port & 0xff) << 8) | ((port >> 8) & 0xff)) >>> 0;
+}
+
+type SetTcpEntryFn = (row: Pointer) => number;
+let setTcpEntryFn: SetTcpEntryFn | null | undefined;
+
+function loadSetTcpEntry(): SetTcpEntryFn | null {
+  if (setTcpEntryFn !== undefined) return setTcpEntryFn;
+  if (process.platform !== "win32") {
+    setTcpEntryFn = null;
+    return null;
+  }
+  try {
+    const lib = dlopen("iphlpapi.dll", {
+      SetTcpEntry: { args: ["ptr"], returns: "u32" },
+    });
+    setTcpEntryFn = (row: Pointer) => lib.symbols.SetTcpEntry(row) as number;
+  } catch {
+    setTcpEntryFn = null;
+  }
+  return setTcpEntryFn;
+}
+
+function readNetstatAno(): string {
+  const netstat = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\netstat.exe`;
+  const cmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
+  try {
+    return execFileSync(cmd, ["/d", "/c", `chcp 437>nul & "${netstat}" -ano -p tcp`], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+      windowsHide: true,
+    });
+  } catch {
+    return execFileSync(netstat, ["-ano", "-p", "tcp"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 4000,
+      windowsHide: true,
+    });
+  }
+}
+
+/**
+ * Force-delete IPv4 TCP rows bound to `localPort` via SetTcpEntry(DELETE_TCB).
+ * Does not kill foreign processes — only resets sockets so the listen port can bind again.
+ * Bare IPv6 rows (`::1`, `::`, etc.) are skipped (not coerced into IPv4 wildcards);
+ * IPv6 TCB reclamation is unsupported on this path.
+ */
+export function dropWindowsTcpRowsForLocalPort(port: number): WindowsTcpDropResult {
+  if (process.platform !== "win32" || !Number.isFinite(port) || port <= 0) {
+    return { dropped: 0, skippedIpv6: 0 };
+  }
+  const setTcpEntry = loadSetTcpEntry();
+  if (!setTcpEntry) return { dropped: 0, skippedIpv6: 0 };
+
+  let output = "";
+  try {
+    output = readNetstatAno();
+  } catch {
+    return { dropped: 0, skippedIpv6: 0 };
+  }
+
+  const rows = parseTcpQuadsForLocalPort(output, Math.trunc(port));
+  let dropped = 0;
+  let skippedIpv6 = 0;
+  for (const row of rows) {
+    const localDw = ipv4ToWinUint32(row.localAddr);
+    const remoteDw = ipv4ToWinUint32(row.remoteAddr);
+    if (localDw === null || remoteDw === null) {
+      if (isBareIpv6Address(row.localAddr) || isBareIpv6Address(row.remoteAddr)) {
+        skippedIpv6 += 1;
+      }
+      continue;
+    }
+    const buf = new ArrayBuffer(20);
+    const view = new DataView(buf);
+    view.setUint32(0, 12, true); // MIB_TCP_STATE_DELETE_TCB
+    view.setUint32(4, localDw, true);
+    view.setUint32(8, htons(row.localPort), true);
+    view.setUint32(12, remoteDw, true);
+    view.setUint32(16, htons(row.remotePort), true);
+    try {
+      if (setTcpEntry(ptr(buf)) === 0) dropped += 1;
+    } catch {
+      /* keep going */
+    }
+  }
+  return { dropped, skippedIpv6 };
+}

package/src/service.ts

@@ -12,6 +12,7 @@ import { dirname, join, resolve } from "node:path";
 import { expandUserPath, getConfigDir, readPid, removePid, removeRuntimePort } from "./config";
 import { loadConfig } from "./config";
 import { restoreNativeCodex } from "./codex/inject";
+import { stripGrokConfig } from "./grok/inject";
 import { isWslRuntime } from "./codex/home";
 import { durableBunPath, durableBunRuntime } from "./lib/bun-runtime";
 import { isProcessAlive, stopProxy } from "./lib/process-control";
@@ -160,13 +161,42 @@ export function serviceReinstallArgs(): string[] {
   return readServiceBackend() === "native" ? ["service", "install", "--native"] : ["service", "install"];
 }
 
+/**
+ * The service was installed under a different CODEX_HOME/OPENCODEX_HOME, so this process may not
+ * touch it. Distinct from "stop failed": the manager was never even contacted, which means the
+ * installed service is still live and shared state (native Codex config, the Grok fence) must be
+ * left alone — tearing it down would strip config out from under a running service.
+ */
+export class ServiceOwnershipError extends Error {
+  readonly code = "service-ownership-mismatch" as const;
+}
+
+export function isServiceOwnershipError(err: unknown): err is ServiceOwnershipError {
+  return err instanceof ServiceOwnershipError;
+}
+
+/**
+ * True when no installed service exists, or the installed one belongs to THIS
+ * CODEX_HOME/OPENCODEX_HOME. Callers use it to decide whether they may tear down shared state
+ * (native Codex config, the Grok fence) that a foreign service would still be relying on.
+ */
+export function serviceEnvironmentOwnedHere(): boolean {
+  try {
+    assertServiceEnvironmentMatchesInstall();
+    return true;
+  } catch (err) {
+    if (isServiceOwnershipError(err)) return false;
+    return true; // unrelated failure: fall back to the previous behavior rather than wedging
+  }
+}
+
 export function assertServiceEnvironmentMatchesInstall(): void {
   const state = readServiceInstallState();
   if (!state) return;
   const expected = normalizePathForCompare(state.codexHome);
   const actual = normalizePathForCompare(currentCodexHome());
   if (expected !== actual) {
-    throw new Error(
+    throw new ServiceOwnershipError(
       `Service was installed with CODEX_HOME=${state.codexHome}, but current CODEX_HOME=${currentCodexHome()}. ` +
         "Run the service command from the same Codex home so native Codex restore updates the correct config.",
     );
@@ -174,7 +204,7 @@ export function assertServiceEnvironmentMatchesInstall(): void {
   const expectedOpenCodexHome = normalizePathForCompare(state.opencodexHome);
   const actualOpenCodexHome = normalizePathForCompare(currentOpenCodexHome());
   if (expectedOpenCodexHome !== actualOpenCodexHome) {
-    throw new Error(
+    throw new ServiceOwnershipError(
       `Service was installed with OPENCODEX_HOME=${state.opencodexHome}, but current OPENCODEX_HOME=${currentOpenCodexHome()}. ` +
         "Run the service command from the same OpenCodex home so service state and secrets match.",
     );
@@ -1148,12 +1178,19 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       break;
     case "stop":
       assertServiceEnvironmentMatchesInstall();
-      ops.stop();
+      // Only stop what is actually installed. The unguarded call ran a real `launchctl unload`
+      // (and its Windows/Linux twins) even with nothing installed.
+      if (ops.status() !== null || isServiceInstalled()) ops.stop();
       await stopTrackedProxyForServiceCommand();
       {
         const restore = restoreNativeCodex();
         if (restore.success) console.log("✅ service stopped + native Codex restored.");
         else console.error(`⚠️ service stopped, but native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` (or check $CODEX_HOME/config.toml) before using native Codex.`);
+        // The Grok fence is the other managed config this command owns. Leaving it behind
+        // pointed grok at a dead endpoint while native Codex was already restored.
+        const grok = stripGrokConfig();
+        if (grok.changed) console.log(`↩️  ${grok.message}`);
+        else if (!grok.ok) console.error(`⚠️  ${grok.message}`);
       }
       break;
     case "status": {
@@ -1181,6 +1218,9 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         if (!restore.success) {
           console.error(`⚠️ native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` before using native Codex.`);
         }
+        const grok = stripGrokConfig();
+        if (grok.changed) console.log(`↩️  ${grok.message}`);
+        else if (!grok.ok) console.error(`⚠️  ${grok.message}`);
       }
       removeServiceInstallState();
       try { if (existsSync(serviceApiTokenFilePath())) unlinkSync(serviceApiTokenFilePath()); } catch { /* best-effort */ }

package/src/types.ts

@@ -308,6 +308,12 @@ export interface OcxUrlCitation {
 export interface OcxUsage {
   inputTokens: number;
   outputTokens: number;
+  /**
+   * Absolute active-context size after the response. Stateful providers can expose this separately
+   * from their per-attempt usage. Responses serialization derives the input side from
+   * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice.
+   */
+  contextTotalTokens?: number;
   totalTokens?: number;
   cachedInputTokens?: number;
   cacheReadInputTokens?: number;
@@ -356,11 +362,26 @@ export interface OcxClaudeCodeConfig {
    */
   systemEnv?: boolean;
   /**
-   * Auth mode for Claude Code inbound requests. "proxy" injects a dummy
-   * ANTHROPIC_AUTH_TOKEN so Claude Code routes through the proxy without a
-   * real Anthropic key. Default: undefined (no token injection).
+   * Auth mode for Claude Code inbound requests — a THREE-state intent.
+   *
+   * "proxy": inject the dummy ANTHROPIC_AUTH_TOKEN so Claude Code routes through the
+   * proxy without a real Anthropic key. "subscription": never inject it. UNSET means
+   * AUTO: the mode is resolved from detected Claude auth on every launch and every
+   * status read (src/claude/auth-mode.ts), so registering a Claude login switches the
+   * behaviour with no migration and no stored state.
+   *
+   * An explicit value always wins over detection and is never rewritten by the auto
+   * logic — that is what makes a manual choice stick (devlog 260726_claude_auth_auto).
+   */
+  authMode?: "proxy" | "subscription";
+  /**
+   * ISO timestamp of the one-time authMode migration. Before auto existed, choosing
+   * "Subscription" DELETED the key, so a pre-upgrade config cannot distinguish an
+   * explicit subscription choice from "never chose". Its ABSENCE identifies a
+   * pre-upgrade block; the migration writes it once and never re-runs, so a user who
+   * later picks Auto (which deletes authMode) is not silently converted back.
    */
-  authMode?: "proxy";
+  authModeMigratedAt?: string;
   /**
    * Context-window override for Claude Code/Desktop clients (devlog 136 B6):
    * injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS + DISABLE_COMPACT=1 (the official
@@ -415,6 +436,27 @@ export interface OcxClaudeCodeConfig {
   webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
   /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
   visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
+  /** Persisted Claude Desktop four-family routing profile. */
+  desktopProfile?: OcxClaudeDesktopProfile;
+  /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
+  desktopAutoApply?: boolean;
+}
+
+export type OcxClaudeDesktopFamily = "opus" | "fable" | "sonnet" | "haiku";
+
+export interface OcxClaudeDesktopAssignment {
+  family: OcxClaudeDesktopFamily;
+  alias: string;
+}
+
+export interface OcxClaudeDesktopProfile {
+  version: 1;
+  assignments: Record<string, OcxClaudeDesktopAssignment>;
+  defaults: Record<OcxClaudeDesktopFamily, string | null>;
+  /** SHA-256 fingerprint of the last successfully applied 3P config content. */
+  appliedFingerprint?: string;
+  /** ISO timestamp of the last successful apply. */
+  appliedAt?: string;
 }
 
 /** 사용자가 대시보드에서 직접 추가한 커스텀 모델 정의. */
@@ -448,6 +490,16 @@ export interface OcxConfig {
    * Codex's spawn_agent only advertises the first 5 routed models, so this picks which 5 appear.
    */
   subagentModels?: string[];
+  /**
+   * Priority-ordered fallback models for spawned sub-agents. When the requested
+   * model is quota-exhausted or recently failed, opencodex rewrites the child
+   * turn to the next available entry before routing.
+   */
+  subagentModelFallback?: string[];
+  /**
+   * TTL (ms) for cached sub-agent model availability probes. Default 60_000.
+   */
+  subagentModelFallbackPollMs?: number;
   injectionModel?: string;
   /**
    * Optional reasoning effort the delegation prompt tells the agent to pass in spawn_agent calls
@@ -455,6 +507,16 @@ export interface OcxConfig {
    * the Codex ladder (src/reasoning-effort.ts CODEX_REASONING_LEVELS) at the API boundary.
    */
   injectionEffort?: string;
+  /**
+   * Model ids the user has EXCLUDED from the Grok Build managed block. Absent or empty
+   * means "everything visible", which is the historical behaviour — so an existing
+   * config keeps the fence it already had.
+   *
+   * Exclusion list rather than an inclusion list on purpose: a newly added provider
+   * model should appear in Grok by default, exactly as it does today. An inclusion list
+   * would silently hide every future model behind a switch nobody knew to flip.
+   */
+  grokExcludedModels?: string[];
   /**
    * When true, OpenAI-routed requests include `service_tier: "priority"` (fast inference).
    * When false, service_tier is stripped so requests use default speed.
@@ -475,7 +537,8 @@ export interface OcxConfig {
    * <multi_agent_mode> tags). When set, it replaces the built-in prompt on whichever
    * collab surface would have fired; firing gates are unchanged. Placeholders:
    * `{{model}}` -> injectionModel, `{{effort}}` -> injectionEffort, `{{roster}}` ->
-   * the resolved sub-agent roster block ("" when nothing resolves).
+   * the resolved sub-agent roster block ("" when nothing resolves), `{{fallback}}` ->
+   * the configured subagent model fallback guidance block ("" when unset).
    */
   injectionPrompt?: string;
   /**
@@ -875,7 +938,12 @@ export interface OcxProviderConfig {
   /** Model ids that expect prior assistant `reasoning_content` to be preserved in chat history. */
   preserveReasoningContentModels?: string[];
   /**
-   * Model ids whose reasoning is a vendor `thinking: {type: enabled|disabled}` toggle on the
+   * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
+   * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
+   */
+  reasoningSplitModels?: string[];
+  /**
+   * Model ids whose reasoning is a vendor `thinking: {type}` toggle on the
    * chat-completions wire (MiMo v2.x, GLM 5/5.1 style), NOT an OpenAI `reasoning_effort` ladder.
    * The openai-chat adapter translates the mapped effort into the thinking toggle for these.
    */

package/src/update/index.ts

@@ -204,6 +204,7 @@ export async function runUpdate(): Promise<void> {
   const capturedListen = {
     port: runtimeTrusted ? preUpdateRt.port : configPort,
     hostname: (runtimeTrusted ? preUpdateRt.hostname : undefined) ?? preUpdateConfig.hostname ?? "127.0.0.1",
+    ...(runtimeTrusted && livePid ? { oldPid: livePid } : {}),
   };
 
   // Never replace package files under a live proxy: the running server dynamic-imports
@@ -281,12 +282,17 @@ export async function runUpdate(): Promise<void> {
     if (serviceWasInstalled) {
       console.log("🔁 Reinstalling the background service with the updated files...");
       const { serviceReinstallArgs } = await import("../service");
-      const { waitForPortAvailable } = await import("../server/ports");
-      const freed = await waitForPortAvailable(capturedListen.port, capturedListen.hostname, {
-        timeoutMs: 5_000,
-        intervalMs: 25,
+      const { reclaimListenPort } = await import("../server/port-reclaim");
+      const freed = await reclaimListenPort(capturedListen.port, capturedListen.hostname, {
+        timeoutMs: 30_000,
+        intervalMs: 100,
+        scanIntervalMs: 500,
+        killOcxHolders: capturedListen.oldPid != null,
+        onlyKillPids: capturedListen.oldPid != null ? [capturedListen.oldPid] : [],
       });
-      if (!freed) console.warn(`⚠️  Port ${capturedListen.port} still busy; reinstalling with pinned --port anyway.`);
+      if (!freed) {
+        console.warn(`⚠️  Port ${capturedListen.port} still busy after 30s; reinstalling service with pinned --port ${capturedListen.port} anyway (refusing to hop).`);
+      }
       const prevBake = process.env.OCX_BAKE_PORT;
       process.env.OCX_BAKE_PORT = String(capturedListen.port);
       try {
@@ -301,26 +307,31 @@ export async function runUpdate(): Promise<void> {
           // On Windows, schtasks /create requires elevation. The CLI inherits the
           // user's (non-admin) token, so the service reinstall can fail with access
           // denied. Fall back to a direct detached proxy start so the update never
-          // leaves the user without a running proxy.
-          console.warn("⚠️  Service refresh failed — starting the proxy directly instead.");
-          console.warn("   Run 'ocx service install' as administrator to refresh the background service.");
-          const env = { ...process.env };
-          delete env.OCX_SERVICE;
-          const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(capturedListen.port)], {
-            detached: true,
-            stdio: "ignore",
-            windowsHide: true,
-            env,
-          });
-          child.unref();
-          console.log(`✅ Proxy starting on port ${capturedListen.port}.`);
+          // leaves the user without a running proxy — but only when the port is free.
+          if (!freed) {
+            console.warn("⚠️  Service refresh failed and the captured port is still busy; not starting on another port.");
+            console.warn(`   Run 'ocx service install' as administrator, then 'ocx start --port ${capturedListen.port}'.`);
+          } else {
+            console.warn("⚠️  Service refresh failed — starting the proxy directly instead.");
+            console.warn("   Run 'ocx service install' as administrator to refresh the background service.");
+            const env = { ...process.env };
+            delete env.OCX_SERVICE;
+            const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(capturedListen.port)], {
+              detached: true,
+              stdio: "ignore",
+              windowsHide: true,
+              env,
+            });
+            child.unref();
+            console.log(`✅ Proxy starting on port ${capturedListen.port}.`);
+          }
         }
       } finally {
         if (prevBake === undefined) delete process.env.OCX_BAKE_PORT;
         else process.env.OCX_BAKE_PORT = prevBake;
       }
     } else {
-      console.log("Restart the proxy:  ocx start");
+      console.log(`Restart the proxy:  ocx start --port ${capturedListen.port}`);
     }
   } else {
     if (trayWasRunning) {