@bitkyc08/opencodex 2.7.40 → 2.7.41

package/src/server/management-api.ts

@@ -10,7 +10,7 @@ import {
   multiAgentGuidanceEnabled,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
-  saveConfig,
+  saveConfigPreservingClaudeCode,
 } from "../config";
 import {
   clearLoginState,
@@ -48,7 +48,8 @@ import {
   setDebugSettings,
   type DebugFlag,
 } from "../lib/debug-settings";
-import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../types";
+import type { OcxClaudeCodeConfig, OcxClaudeDesktopProfile, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../types";
+import type { DesktopProfileModel } from "../claude/desktop-profile";
 import { drainAndShutdown } from "./lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "./request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../usage/cost";
@@ -135,16 +136,32 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
 
   if (url.pathname === "/api/stop" && req.method === "POST") {
     const { restoreNativeCodex } = await import("../codex/inject");
-    const { stopServiceIfInstalled } = await import("../service");
-    stopServiceIfInstalled();
+    const { stopServiceIfInstalled, isServiceOwnershipError } = await import("../service");
+    try {
+      stopServiceIfInstalled();
+    } catch (err) {
+      if (isServiceOwnershipError(err)) {
+        // The installed service belongs to another CODEX_HOME/OPENCODEX_HOME: it would respawn
+        // this proxy immediately, and its shared config is not ours to tear down. Refuse the
+        // stop instead of half-performing it. 409, not 500 — the request is well-formed.
+        return jsonResponse({ success: false, message: err.message }, 409, req, config);
+      }
+      throw err;
+    }
     const restore = restoreNativeCodex();
+    // Both managed configs come down together on an explicit teardown. The daemon's own
+    // syncCleanup skips this when OCX_SERVICE is set (so a crash/respawn keeps the fence),
+    // which is exactly why an intentional stop has to do it here.
+    const { stripGrokConfig } = await import("../grok/inject");
+    const grok = stripGrokConfig();
     setTimeout(async () => {
       await drainAndShutdown(undefined, config.shutdownTimeoutMs ?? 5000);
       process.exit(0);
     }, 200);
+    const grokNote = grok.ok ? "" : ` Grok config cleanup failed: ${grok.message}`;
     return jsonResponse(restore.success
-      ? { success: true, message: "Proxy stopping, native Codex restored." }
-      : { success: false, message: `Proxy stopping, but native Codex restore failed: ${restore.message}. Run \`ocx restore\`.` });
+      ? { success: true, message: `Proxy stopping, native Codex restored.${grokNote}` }
+      : { success: false, message: `Proxy stopping, but native Codex restore failed: ${restore.message}. Run \`ocx restore\`.${grokNote}` });
   }
 
   if (url.pathname.startsWith("/api/codex-auth/")) {
@@ -156,4 +173,4 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
 }
 
 
-export { fetchAllModels } from "./management/shared";
+export { buildClaudeDesktopState, fetchAllModels } from "./management/shared";

package/src/server/port-reclaim.ts

@@ -0,0 +1,261 @@
+/**
+ * Reclaim a listen port after stop/update so restart can stay on the configured
+ * port instead of hopping to an ephemeral one (Windows CLOSE_WAIT / leftover ocx).
+ *
+ * Killing is never the default: a process may be killed only when the caller
+ * supplies a non-empty explicit PID allowlist for a process it just stopped.
+ */
+import { execFileSync } from "node:child_process";
+import { verifyPidIdentity } from "../config";
+import { isProcessAlive, killProxy } from "../lib/process-control";
+import { isPortAvailable, type WaitForPortOptions } from "./ports";
+import { dropWindowsTcpRowsForLocalPort } from "./windows-tcp-drop";
+
+export type ListenPidScan =
+  | { ok: true; pids: number[] }
+  | { ok: false; error?: string };
+
+export type ReclaimListenPortOptions = WaitForPortOptions & {
+  /**
+   * When true AND `onlyKillPids` is a non-empty allowlist, those PIDs may be
+   * killed after revalidation. Default false — never kill without an allowlist.
+   */
+  killOcxHolders?: boolean;
+  /**
+   * Explicit PIDs the caller just stopped / hard-killed. An omitted or empty
+   * list means no process may be killed.
+   */
+  onlyKillPids?: number[];
+  /**
+   * On Windows, force-delete IPv4 TCP rows for this local port via SetTcpEntry.
+   * Default true on win32. Never kills foreign processes, never runs while a
+   * live foreign / protected ocx listener owns the port, and never runs when
+   * the listener scan failed.
+   */
+  dropTcpRows?: boolean;
+  /** How often to scan for listen PIDs / attempt TCB drop (ms). Default 500. */
+  scanIntervalMs?: number;
+  listListenPidsFn?: (port: number) => ListenPidScan | number[];
+  isAliveFn?: (pid: number) => boolean;
+  verifyOcxFn?: (pid: number) => number | null;
+  killFn?: (pid: number) => void;
+  dropTcpFn?: (port: number) => number | { dropped: number; skippedIpv6: number };
+  isAvailableFn?: (port: number, hostname?: string) => Promise<boolean>;
+  sleepMs?: (ms: number) => Promise<void>;
+};
+
+/**
+ * Parse `netstat -ano` (Windows) / `netstat -anlp` listen lines for a port.
+ * Exported for unit tests.
+ */
+export function parseListenPidsFromNetstat(output: string, port: number): number[] {
+  const pids = new Set<number>();
+  const portSuffix = `:${port}`;
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!/^TCP\b/i.test(line) && !/^tcp\b/i.test(line)) continue;
+    const parts = line.split(/\s+/);
+    // Prefer the first address token that ends with :port (local), not a later foreign one.
+    const localIdx = parts.findIndex(part => part.endsWith(portSuffix) || part.endsWith(`]:${port}`));
+    if (localIdx < 0) continue;
+    const foreign = parts[localIdx + 1] ?? "";
+    // Locale-safe listen detection: English LISTEN*, or unbound foreign wildcard
+    // (German ABHÖREN still shows 0.0.0.0:0 / *:*).
+    const listenWord = /\bLISTEN/i.test(line);
+    const wildcardForeign = /^(0\.0\.0\.0|::|\*|\[::\]):0$/.test(foreign) || foreign === "*:*";
+    if (!listenWord && !wildcardForeign) continue;
+    const last = parts[parts.length - 1] ?? "";
+    const winPid = /^\d+$/.test(last) ? Number(last) : NaN;
+    const unixPid = /^(\d+)(?:\/\S*)?$/.exec(last);
+    const pid = Number.isSafeInteger(winPid) && winPid > 0
+      ? winPid
+      : unixPid
+        ? Number(unixPid[1])
+        : NaN;
+    if (Number.isSafeInteger(pid) && pid > 0) pids.add(pid);
+  }
+  return [...pids];
+}
+
+function normalizeListenPidScan(result: ListenPidScan | number[]): ListenPidScan {
+  if (Array.isArray(result)) return { ok: true, pids: result };
+  return result;
+}
+
+/** Prefer English netstat states; fall back to the UI-locale table. */
+function readWindowsNetstatAno(): string {
+  const netstat = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\netstat.exe`;
+  const cmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
+  try {
+    // chcp 437 forces English LISTENING/ESTABLISHED labels on localized Windows.
+    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,
+    });
+  }
+}
+
+/**
+ * Scan for PIDs currently LISTENing on `port`.
+ * Distinguishes probe failure (`ok: false`) from a successful empty result.
+ */
+export function scanListenPids(port: number): ListenPidScan {
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    return { ok: false, error: "invalid port" };
+  }
+  try {
+    if (process.platform === "win32") {
+      return { ok: true, pids: parseListenPidsFromNetstat(readWindowsNetstatAno(), port) };
+    }
+    try {
+      const output = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 3000,
+      });
+      return {
+        ok: true,
+        pids: output
+          .split(/\r?\n/)
+          .map(line => Number(line.trim()))
+          .filter(pid => Number.isSafeInteger(pid) && pid > 0),
+      };
+    } catch (lsofErr) {
+      try {
+        const output = execFileSync("netstat", ["-anlp"], {
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 3000,
+        });
+        return { ok: true, pids: parseListenPidsFromNetstat(output, Math.trunc(port)) };
+      } catch (netstatErr) {
+        return {
+          ok: false,
+          error: `lsof/netstat unavailable: ${String(lsofErr)} / ${String(netstatErr)}`,
+        };
+      }
+    }
+  } catch (error) {
+    return { ok: false, error: String(error) };
+  }
+}
+
+/** Best-effort PIDs currently LISTENing on `port`. Empty on probe failure. */
+export function listListenPids(port: number): number[] {
+  const scan = scanListenPids(port);
+  return scan.ok ? scan.pids : [];
+}
+
+/**
+ * Wait until `port` can bind.
+ * Never kills a process unless `killOcxHolders === true` and `onlyKillPids` is a
+ * non-empty allowlist of PIDs the caller itself just stopped — then revalidates
+ * immediately before each kill.
+ * Never kills foreign processes. Never drops TCP rows while a live foreign or
+ * protected ocx listener owns the port, or when the listener scan failed.
+ */
+export async function reclaimListenPort(
+  port: number,
+  hostname = "127.0.0.1",
+  opts: ReclaimListenPortOptions = {},
+): Promise<boolean> {
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const intervalMs = opts.intervalMs ?? 100;
+  const scanIntervalMs = opts.scanIntervalMs ?? 500;
+  const allowedKillPids = new Set(
+    (opts.onlyKillPids ?? []).filter(pid => Number.isSafeInteger(pid) && pid > 0),
+  );
+  const mayKill = opts.killOcxHolders === true && allowedKillPids.size > 0;
+  const dropTcpRows = opts.dropTcpRows ?? process.platform === "win32";
+  const listFn = opts.listListenPidsFn ?? scanListenPids;
+  const isAliveFn = opts.isAliveFn ?? isProcessAlive;
+  const verifyOcxFn = opts.verifyOcxFn ?? verifyPidIdentity;
+  const killFn = opts.killFn ?? killProxy;
+  const dropTcpFn = opts.dropTcpFn ?? dropWindowsTcpRowsForLocalPort;
+  const isAvailableFn = opts.isAvailableFn ?? isPortAvailable;
+  const sleep = opts.sleepMs ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
+
+  const deadline = Date.now() + timeoutMs;
+  let lastScan = 0;
+  const killed = new Set<number>();
+
+  for (;;) {
+    if (await isAvailableFn(port, hostname)) return true;
+    if (Date.now() >= deadline) return false;
+
+    if (Date.now() - lastScan >= scanIntervalMs) {
+      lastScan = Date.now();
+
+      const scan = normalizeListenPidScan(listFn(port));
+      if (!scan.ok) {
+        // Failed probe ≠ empty listeners: do not kill and do not reset TCP rows.
+        await sleep(intervalMs);
+        continue;
+      }
+
+      let foreignLive = false;
+      let protectedOcxListener = false;
+
+      for (const pid of scan.pids) {
+        if (pid === process.pid) continue;
+        if (!isAliveFn(pid)) continue; // Windows may still list a dead owner briefly
+        const isOcx = verifyOcxFn(pid) === pid;
+        if (!isOcx) {
+          foreignLive = true;
+          continue;
+        }
+        if (!mayKill || !allowedKillPids.has(pid)) {
+          // Healthy / intentional ocx proxy — never steal its port.
+          protectedOcxListener = true;
+          continue;
+        }
+        if (!killed.has(pid)) {
+          // Revalidate immediately before termination.
+          if (isAliveFn(pid) && verifyOcxFn(pid) === pid && allowedKillPids.has(pid)) {
+            try {
+              killFn(pid);
+              killed.add(pid);
+            } catch {
+              // Kill failed: keep waiting and never reset this listener's TCP rows.
+              protectedOcxListener = true;
+            }
+          } else {
+            // Revalidation failed while the allowlisted listener is still listed live.
+            protectedOcxListener = true;
+          }
+        }
+        // Only reset TCP rows after confirmed process death.
+        if (isAliveFn(pid)) protectedOcxListener = true;
+      }
+
+      if (foreignLive || protectedOcxListener) {
+        // Foreign app or an unprotected live ocx listener owns the port: never
+        // SetTcpEntry-reset their sockets, and fail reclaim once the deadline hits.
+        await sleep(intervalMs);
+        continue;
+      }
+
+      // After hard-kill, browsers often keep ESTABLISHED/CLOSE_WAIT to the dead listener.
+      // Reset those IPv4 TCBs (and ghost LISTEN rows) so the configured port can bind again —
+      // without killing the browser process. Only safe when no live foreign/protected listener remains.
+      if (dropTcpRows) {
+        try {
+          dropTcpFn(port);
+        } catch {
+          /* access denied / unsupported — keep waiting */
+        }
+      }
+    }
+
+    await sleep(intervalMs);
+  }
+}

package/src/server/request-log.ts

@@ -11,6 +11,7 @@ import type { OcxUsage } from "../types";
 import { redactSecretString } from "../lib/redact";
 import {
   appendUsageEntry,
+  isKnownUsageSurface,
   readRecentUsageEntries,
   usageForFinalLog,
   usageStatusForFinalLog,
@@ -33,7 +34,7 @@ export interface RequestLogContext {
   provider: string;
   /** TTFT: ms from request start to the first non-empty model output delta (WP4, devlog 040). */
   firstOutputMs?: number;
-  surface?: "claude";
+  surface?: "claude" | "claude-desktop" | "grok";
   requestedModel?: string;
   /** Internal structural combo identity; omitted from RequestLogEntry/JSONL. */
   comboId?: string;
@@ -58,6 +59,11 @@ export interface RequestLogContext {
   /** Route adapter type ("cursor"/"kiro"/"anthropic"/…): drives estimated-usage detection
    *  independent of the user-chosen provider NAME (devlog 130 B2). */
   providerAdapter?: string;
+  /** Set when the bridge reported raw adapter usage via onUsage: the bridged wire now always
+   *  carries synthetic zero-default token-detail objects (strict-client normalization, see
+   *  responsesUsage in src/bridge.ts), so SSE/JSON re-parsing must not overwrite the raw
+   *  provenance — a synthetic cached_tokens:0 is NOT a measured cache read. */
+  usageFromBridge?: boolean;
   /** Secret-redacted upstream error reason (e.g. the granular Cursor "rate limit exceeded…"
    * message) extracted from a `response.failed` SSE payload or non-streaming error body, so the
    * request log / GUI shows the actual upstream failure rather than only the HTTP-mapped code. */
@@ -76,7 +82,7 @@ export interface RequestLogEntry {
   provider: string;
   /** TTFT: ms from request start to the first non-empty model output delta; unset for non-streaming/tool-only. */
   firstOutputMs?: number;
-  surface?: "claude";
+  surface?: "claude" | "claude-desktop" | "grok";
   requestedModel?: string;
   requestedEffort?: string;
   requestedServiceTier?: string;
@@ -139,7 +145,7 @@ export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): R
     model: entry.model,
     provider: entry.provider,
     ...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
-    ...(entry.surface === "claude" ? { surface: entry.surface } : {}),
+    ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
     ...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
     ...(entry.requestedEffort ? { requestedEffort: entry.requestedEffort } : {}),
     ...(entry.requestedServiceTier ? { requestedServiceTier: entry.requestedServiceTier } : {}),
@@ -215,7 +221,7 @@ export function addRequestLog(entry: RequestLogEntry) {
       timestamp: entry.timestamp,
       provider: entry.provider,
       model: entry.model,
-      ...(entry.surface === "claude" ? { surface: entry.surface } : {}),
+      ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
       ...(entry.resolvedModel ? { resolvedModel: entry.resolvedModel } : {}),
       ...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
       ...(entry.requestedEffort ? { requestedEffort: entry.requestedEffort } : {}),
@@ -338,7 +344,7 @@ export function applyResponseLogMetadata(logCtx: RequestLogContext, payload: unk
   const serviceTier = (source as { service_tier?: unknown }).service_tier;
   if (typeof serviceTier === "string" && serviceTier.trim()) logCtx.responseServiceTier = serviceTier;
   const usage = usageFromResponsesPayload((source as { usage?: unknown }).usage);
-  if (usage) {
+  if (usage && !logCtx.usageFromBridge) {
     logCtx.usage = usage;
     if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
   }

package/src/server/responses/collaboration.ts

@@ -61,6 +61,7 @@ import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } f
 import { listOpenAiForwardSidecarCandidates, resolveFirstUsableOpenAiSidecar, type ResolvedOpenAiForwardSidecar } from "../../providers/openai-sidecar";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { slugsEquivalent } from "../../providers/slug-codec";
+import { subagentFallbackGuidanceText } from "../../codex/subagent-model-fallback";
 import { applyOpenAiVirtualModel, resolveOpenAiCompactModel } from "../../providers/openai-virtual-models";
 import { isUsageDebugEnabled } from "../../usage/debug";
 import { readJsonRequestBody, DecompressedBodyTooLargeError, UnsupportedContentEncodingError } from "../request-decompress";
@@ -160,6 +161,7 @@ export interface MultiAgentGuidanceOptions {
   injectionModel?: string;
   injectionEffort?: string;
   subagentModels?: string[];
+  subagentModelFallback?: string[];
   injectionPrompt?: string;
 }
 
@@ -194,6 +196,7 @@ export async function multiAgentGuidanceText(
     injectionModel,
     injectionEffort,
     subagentModels,
+    subagentModelFallback,
     injectionPrompt,
   } = options;
   const surface = collabSurface(parsed);
@@ -222,11 +225,12 @@ export async function multiAgentGuidanceText(
         .map(item => `${item.configured}:${item.reason}`)
         .join(", ")}`);
     }
-    if (!injectionModel && roster === "") return null;
+    const fallbackGuidance = subagentFallbackGuidanceText({ subagentModelFallback } as OcxConfig);
+    if (!injectionModel && roster === "" && fallbackGuidance === "") return null;
     if (injectionPrompt) {
-      return `<multi_agent_mode>${applyInjectionPlaceholders(injectionPrompt, injectionModel, injectionEffort, roster)}</multi_agent_mode>`;
+      return `<multi_agent_mode>${applyInjectionPlaceholders(injectionPrompt, injectionModel, injectionEffort, roster, fallbackGuidance)}</multi_agent_mode>`;
     }
-    if (!preferred && roster === "") return null;
+    if (!preferred && roster === "" && fallbackGuidance === "") return null;
     let text = "When the active spawn_agent tool supports optional \"model\" or \"reasoning_effort\" overrides, "
       + "use only models listed for this collaboration surface. "
       + "When setting either override, set fork_turns to \"none\" "
@@ -237,6 +241,7 @@ export async function multiAgentGuidanceText(
         + (injectionEffort ? `, reasoning_effort "${injectionEffort}"` : "")
         + " — use it unless the user names another.";
     }
+    text += fallbackGuidance;
     text += roster;
     if (text.length > V2_GUIDANCE_CHAR_BUDGET) {
       // Roster is the only unbounded part — drop it before breaking the budget.
@@ -256,11 +261,12 @@ export async function multiAgentGuidanceText(
 
 export const V2_GUIDANCE_CHAR_BUDGET = 700;
 
-export function applyInjectionPlaceholders(prompt: string, model?: string, effort?: string, roster?: string): string {
+export function applyInjectionPlaceholders(prompt: string, model?: string, effort?: string, roster?: string, fallback?: string): string {
   return prompt
     .replaceAll("{{model}}", model ?? "")
     .replaceAll("{{effort}}", effort ?? "")
-    .replaceAll("{{roster}}", roster ?? "");
+    .replaceAll("{{roster}}", roster ?? "")
+    .replaceAll("{{fallback}}", fallback ?? "");
 }
 
 
@@ -314,4 +320,3 @@ export function injectDeveloperMessage(parsed: OcxParsedRequest, text: string):
     }
   }
 }
-

package/src/server/responses/compact.ts

@@ -42,6 +42,7 @@ import { createAdapterEventQueue, preflightAdapterEvents } from "../../adapters/
 import {
   applyCodexAuthContextToProvider,
   CodexAccountCooldownError,
+  cooldownErrorResponse,
   CodexAuthContextError,
   CodexDirectAuthenticationError,
   CodexPoolAuthenticationError,
@@ -231,7 +232,7 @@ export async function handleResponsesCompact(
       }
     } 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");