fix(claude): production hardening — 2 BLOCKERs + 8 MAJORs from sol gap audit

BLOCKER fixes:
- outbound.ts: detached pump pattern for SSE streaming — frames now reach
  the client as they arrive instead of buffering until upstream EOF; cancel
  calls reader.cancel() instead of the locked stream (#1)
- system-env.ts: transactional launchctl injection with incremental tracking
  and rollback on mid-flight failure (#2)

MAJOR fixes:
- system-env.ts: POSIX single-quote escaping for all user-controlled values
  in the generated shell file, preventing command injection (#3)
- system-env.ts: exported applySystemEnvToggle for runtime ON/OFF lifecycle (#7)
- claude-messages.ts: 120s hard timeout on native passthrough upstream fetch
  using AbortSignal.timeout, returning Anthropic 504 on expiry (#4)
- management-api.ts: reject non-plain-object PUT bodies (null, array, primitive)
  with 400; strict validation for blockedSkills, tierModels, modelMap, and
  autoCompactWindow (integer, range 100k-1M) (#5, #6)
- management-api.ts: call applySystemEnvToggle after systemEnv config toggle (#7)
- cli/claude.ts: override stale loopback ANTHROPIC_BASE_URL with live port;
  warn on gateway-cache and agent-sync failures instead of swallowing (#8, #10)
- gateway-cache.ts: distinguish discovery failure (keep cache) from authoritative
  empty success (write {models:[]}) (#9)

Test fixes: updated assertions for single-quote shell escaping, empty cache
semantics, validation messages, incremental tracking writes, and PUT response
shape.

Author: lidge-jun

src/claude/gateway-cache.ts

@@ -30,7 +30,6 @@ export function writeGatewayModelCache(baseUrl: string, models: readonly Gateway
   try {
     // Mirror the CLI's usable-id filter so our file matches what it would cache.
     const usable = models.filter(m => /^(claude|anthropic)/i.test(m.id));
-    if (usable.length === 0) return null;
     const cacheDir = join(configDir, "cache");
     mkdirSync(cacheDir, { recursive: true });
     const path = join(cacheDir, "gateway-models.json");
@@ -56,8 +55,9 @@ export async function refreshGatewayModelCacheFromProxy(port: number, timeoutMs
       signal: AbortSignal.timeout(timeoutMs),
     });
     if (!res.ok) return null;
-    const body = await res.json() as { data?: Array<Record<string, unknown>> };
-    const models: GatewayModelRow[] = (Array.isArray(body.data) ? body.data : [])
+    const body = await res.json() as { data?: unknown };
+    if (!Array.isArray(body.data)) return null;
+    const models: GatewayModelRow[] = body.data
       .filter(m => typeof m.id === "string" && (m.id as string).length > 0)
       .map(m => ({
         id: m.id as string,

src/claude/outbound.ts

@@ -105,13 +105,15 @@ export function responsesSseToAnthropicSse(
   let buffer = "";
   let started = false;
   let terminated = false;
+  let cancelled = false;
   let blockIndex = 0;
   let open: OpenBlock | null = null;
   let sawToolUse = false;
   let pingTimer: ReturnType<typeof setInterval> | undefined;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
 
   return new ReadableStream<Uint8Array>({
-    async start(controller) {
+    start(controller) {
       const emit = (name: string, data: Rec) => controller.enqueue(encoder.encode(sseFrame(name, data)));
       const ensureStarted = () => {
         if (started) return;
@@ -267,46 +269,49 @@ export function responsesSseToAnthropicSse(
         }
       };
 
-      const reader = upstream.getReader();
-      try {
-        for (;;) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-          let sep: number;
-          while ((sep = buffer.indexOf("\n\n")) !== -1) {
-            const rawFrame = buffer.slice(0, sep);
-            buffer = buffer.slice(sep + 2);
-            let eventName = "";
-            let dataLine = "";
-            for (const line of rawFrame.split("\n")) {
-              if (line.startsWith("event: ")) eventName = line.slice(7).trim();
-              else if (line.startsWith("data: ")) dataLine += line.slice(6);
+      reader = upstream.getReader();
+      void (async () => {
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep: number;
+            while ((sep = buffer.indexOf("\n\n")) !== -1) {
+              const rawFrame = buffer.slice(0, sep);
+              buffer = buffer.slice(sep + 2);
+              let eventName = "";
+              let dataLine = "";
+              for (const line of rawFrame.split("\n")) {
+                if (line.startsWith("event: ")) eventName = line.slice(7).trim();
+                else if (line.startsWith("data: ")) dataLine += line.slice(6);
+              }
+              if (!eventName || !dataLine) continue;
+              let data: unknown;
+              try { data = JSON.parse(dataLine); } catch { continue; }
+              if (!isRec(data)) continue;
+              if (terminated) continue;
+              handleFrame(eventName, data);
             }
-            if (!eventName || !dataLine) continue;
-            let data: unknown;
-            try { data = JSON.parse(dataLine); } catch { continue; }
-            if (!isRec(data)) continue;
-            if (terminated) continue;
-            handleFrame(eventName, data);
           }
+          // EOF without a terminal frame is a TRUNCATION, not success (devlog 100:
+          // gateways that close such streams politely hand Claude Code an empty/partial
+          // turn with no retryable error — CLIProxyAPI#2189 failure pattern). Fail closed
+          // with a mid-stream Anthropic error event so the client can retry.
+          if (!cancelled) fail(502, "upstream stream ended before a terminal frame (truncated response)");
+        } catch (err) {
+          fail(500, err instanceof Error ? err.message : String(err));
+        } finally {
+          if (pingTimer !== undefined) clearInterval(pingTimer);
+          reader.releaseLock();
+          if (!cancelled) controller.close();
         }
-        // EOF without a terminal frame is a TRUNCATION, not success (devlog 100:
-        // gateways that close such streams politely hand Claude Code an empty/partial
-        // turn with no retryable error — CLIProxyAPI#2189 failure pattern). Fail closed
-        // with a mid-stream Anthropic error event so the client can retry.
-        fail(502, "upstream stream ended before a terminal frame (truncated response)");
-      } catch (err) {
-        fail(500, err instanceof Error ? err.message : String(err));
-      } finally {
-        if (pingTimer !== undefined) clearInterval(pingTimer);
-        reader.releaseLock();
-        controller.close();
-      }
+      })();
     },
     cancel(reason) {
+      cancelled = true;
       if (pingTimer !== undefined) clearInterval(pingTimer);
-      return upstream.cancel(reason);
+      return reader?.cancel(reason);
     },
   });
 }

src/cli/claude.ts

@@ -3,7 +3,8 @@
  *
  * Mirrors `ccr code` UX (devlog/260711_claude_inbound/020, 003 E1/E2/E5/G1):
  * ensures the proxy is running, injects the Anthropic env slots, then execs the
- * `claude` CLI with stdio inherited. User-exported env always wins.
+ * `claude` CLI with stdio inherited. User-exported env wins except when a stale
+ * loopback opencodex base URL points at a different proxy port.
  */
 import { spawn } from "node:child_process";
 import { loadConfig } from "../config";
@@ -20,7 +21,8 @@ export interface ClaudeLaunchEnv {
 /**
  * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
  * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
- * overrides variables the user already exported.
+ * overrides variables the user already exported, apart from stale loopback
+ * ANTHROPIC_BASE_URL values owned by a previous opencodex launch.
  */
 export function buildClaudeEnv(config: OcxConfig, port: number, base: ClaudeLaunchEnv, contextWindows: Record<string, number> = {}): ClaudeLaunchEnv {
   const env: ClaudeLaunchEnv = { ...base };
@@ -30,6 +32,20 @@ export function buildClaudeEnv(config: OcxConfig, port: number, base: ClaudeLaun
     env[name] = value;
   };
   setDefault("ANTHROPIC_BASE_URL", `http://127.0.0.1:${port}`);
+  const existingBaseUrl = env.ANTHROPIC_BASE_URL;
+  if (existingBaseUrl) {
+    try {
+      const parsed = new URL(existingBaseUrl);
+      const isLoopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+      if (isLoopback && parsed.port !== "" && Number(parsed.port) !== port) {
+        const replacement = `http://127.0.0.1:${port}`;
+        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${existingBaseUrl} with ${replacement}.`);
+        env.ANTHROPIC_BASE_URL = replacement;
+      }
+    } catch {
+      // Preserve user-provided values that are not parseable URLs.
+    }
+  }
   // Subscription-preserving default (teamclaude --no-mitm / Vercel gateway pattern):
   // setting ANTHROPIC_AUTH_TOKEN/API_KEY disables claude.ai connectors and overrides
   // the user's Claude login. Only inject a token when the proxy actually requires an
@@ -137,9 +153,25 @@ export async function cmdClaude(args: string[]): Promise<number> {
   const env = buildClaudeEnv(config, port, process.env, contextWindows);
   // 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.
-  await refreshGatewayModelCacheFromProxy(port);
+  try {
+    const cachePath = await refreshGatewayModelCacheFromProxy(port);
+    if (cachePath === null) {
+      console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Gateway model cache could not be refreshed: ${message}`);
+  }
   // Sync roster agents (devlog 070): subagentModels + self -> ~/.claude/agents/ocx-*.md.
-  injectClaudeAgentDefs(config, contextWindows);
+  try {
+    const written = injectClaudeAgentDefs(config, contextWindows);
+    if (written === null) {
+      console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
+  }
   return await new Promise<number>(resolve => {
     const child = spawn("claude", args, { stdio: "inherit", env: env as NodeJS.ProcessEnv });
     child.on("error", (err: NodeJS.ErrnoException) => {

src/server/claude-messages.ts

@@ -178,15 +178,21 @@ async function anthropicNativePassthrough(
   });
   headers.set("content-type", "application/json");
 
+  const timeoutSignal = AbortSignal.timeout(config.connectTimeoutMs ?? 120_000);
+  const upstreamSignal = AbortSignal.any([req.signal, timeoutSignal]);
   let upstream: Response;
   try {
     upstream = await fetch(`${base}${pathname}${search}`, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
-      signal: req.signal,
+      signal: upstreamSignal,
     });
   } catch (err) {
+    if (timeoutSignal.aborted && upstreamSignal.reason === timeoutSignal.reason) {
+      finalize(504, { closeReason: "non_stream" });
+      return anthropicErrorResponse(504, "anthropic passthrough timed out waiting for response headers", "timeout_error");
+    }
     finalize(502, { closeReason: "non_stream" });
     return anthropicErrorResponse(502, `anthropic passthrough failed: ${err instanceof Error ? err.message : String(err)}`, "api_error");
   }

src/server/management-api.ts

@@ -41,6 +41,7 @@ import type { OcxConfig, OcxProviderConfig } from "../types";
 import { drainAndShutdown } from "./lifecycle";
 import { filterRequestLogs, getRequestLogEntries } from "./request-log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "./auth-cors";
+import { applySystemEnvToggle } from "./system-env";
 
 // Single source of truth = package.json (../ from src/), so /healthz + the GUI badge match the
 // installed npm version instead of a stale hardcode.
@@ -734,8 +735,15 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     // supersede tiers; auto-context supersedes the max-context pair; effort rides
     // regardless on 2.1.207). PUT keeps validating them so hand-written configs
     // and older GUIs stay safe; GUI saves omit them and the spread preserves them.
-    let body: { enabled?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; blockedSkills?: unknown; injectAgents?: unknown };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    let parsedBody: unknown;
+    try { parsedBody = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+      const prototype = Object.getPrototypeOf(value);
+      return prototype === Object.prototype || prototype === null;
+    };
+    if (!isPlainObject(parsedBody)) return jsonResponse({ error: "body must be an object" }, 400);
+    const body = parsedBody as { enabled?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; blockedSkills?: unknown; injectAgents?: unknown };
     const next = { ...(config.claudeCode ?? {}) };
     if (body.enabled !== undefined) {
       if (typeof body.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
@@ -797,18 +805,23 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     }
     if (body.tierModels !== undefined) {
       // CONFIG-ONLY back-compat (GUI pickers removed — roster agents supersede tiers).
-      if (!body.tierModels || typeof body.tierModels !== "object" || Array.isArray(body.tierModels)) {
-        return jsonResponse({ error: "tierModels must be an object" }, 400);
-      }
-      const tiers: Record<string, string> = {};
-      for (const tier of ["opus", "sonnet", "haiku", "fable"] as const) {
-        const value = (body.tierModels as Record<string, unknown>)[tier];
-        if (value === undefined || value === null) continue;
-        if (typeof value !== "string") return jsonResponse({ error: `tierModels.${tier} must be a string` }, 400);
-        if (value.trim() !== "") tiers[tier] = value.trim();
+      if (body.tierModels === null) {
+        delete next.tierModels;
+      } else if (!isPlainObject(body.tierModels)) {
+        return jsonResponse({ error: "tierModels must be an object with string values, or null" }, 400);
+      } else {
+        for (const [tier, value] of Object.entries(body.tierModels)) {
+          if (typeof value !== "string") return jsonResponse({ error: `tierModels.${tier} must be a string` }, 400);
+        }
+        const tierModels = body.tierModels as Record<string, string>;
+        const tiers: Record<string, string> = {};
+        for (const tier of ["opus", "sonnet", "haiku", "fable"] as const) {
+          const value = tierModels[tier];
+          if (value !== undefined && value.trim() !== "") tiers[tier] = value.trim();
+        }
+        if (Object.keys(tiers).length > 0) next.tierModels = tiers;
+        else delete next.tierModels;
       }
-      if (Object.keys(tiers).length > 0) next.tierModels = tiers;
-      else delete next.tierModels;
     }
     if (body.fastMode !== undefined) {
       if (body.fastMode !== true && body.fastMode !== false && body.fastMode !== null) {
@@ -824,26 +837,38 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       else next[field] = value.trim();
     }
     if (body.modelMap !== undefined) {
-      if (!body.modelMap || typeof body.modelMap !== "object" || Array.isArray(body.modelMap)) {
-        return jsonResponse({ error: "modelMap must be an object of string->string" }, 400);
-      }
-      const map: Record<string, string> = {};
-      for (const [k, v] of Object.entries(body.modelMap as Record<string, unknown>)) {
-        if (typeof v !== "string" || k.trim() === "" || v.trim() === "") {
-          return jsonResponse({ error: "modelMap entries must be non-empty strings" }, 400);
+      if (body.modelMap === null) {
+        delete next.modelMap;
+      } else {
+        if (!isPlainObject(body.modelMap)) {
+          return jsonResponse({ error: "modelMap must be an object of string->string, or null" }, 400);
         }
-        map[k.trim()] = v.trim();
+        const map: Record<string, string> = {};
+        for (const [k, v] of Object.entries(body.modelMap)) {
+          if (typeof v !== "string" || k.trim() === "" || v.trim() === "") {
+            return jsonResponse({ error: "modelMap entries must be non-empty strings" }, 400);
+          }
+          map[k.trim()] = v.trim();
+        }
+        if (Object.keys(map).length > 0) next.modelMap = map;
+        else delete next.modelMap;
       }
-      if (Object.keys(map).length > 0) next.modelMap = map;
-      else delete next.modelMap;
     }
     config.claudeCode = next;
     const { saveConfig: save } = await import("../config");
     save(config);
+    const warnings: string[] = [];
+    if (body.systemEnv !== undefined) {
+      try {
+        await applySystemEnvToggle(config, config.port);
+      } catch (err) {
+        warnings.push(`Failed to apply system environment setting: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
     // Keep the file-backed live registry symmetric: OFF prunes immediately, while
     // ON and config changes restore definitions without requiring a restart.
     await syncClaudeAgentDefsBestEffort();
-    return jsonResponse({ ok: true, enabled: next.enabled !== false });
+    return jsonResponse({ ok: true, enabled: next.enabled !== false, warnings });
   }
 
   // Per-provider catalog allowlist (issue #52): when a provider has a non-empty selectedModels list,