@bitkyc08/opencodex 2.7.36 → 2.7.37

package/src/combos/resolve.ts

@@ -143,13 +143,18 @@ export function noteComboFailure(comboId: string, target: OcxComboTarget): void
 export function advanceComboAfterFailure(
   config: OcxConfig,
   pick: ComboPick,
-  options: { retryAfter?: string | null; now?: number } = {},
+  options: {
+    retryAfter?: string | null;
+    now?: number;
+    eligible?: (target: Required<OcxComboTarget>) => boolean;
+  } = {},
 ): ComboPick | null {
   noteComboFailure(pick.comboId, pick.target);
   coolComboTarget(pick.comboId, pick.target, options);
   return pickComboTarget(config, pick.comboId, {
     exclude: pick.attempted,
-    eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now),
+    eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now)
+      && (options.eligible?.(target) ?? true),
   });
 }
 

package/src/config.ts

@@ -442,6 +442,11 @@ const configSchema = z.object({
   providerContextCaps: z.record(z.string(), z.number().int().positive()).optional(),
   contextCapValue: z.number().int().positive().optional(),
   multiAgentGuidanceEnabled: z.boolean().optional(),
+  codexShimAutoRestore: z.boolean().optional(),
+  // Invalid values degrade to undefined ("auto") instead of failing the whole
+  // parse: a hand-edited typo must never trip the backup-and-defaults repair
+  // path below and wipe providers/pool accounts. Warning emitted in loadConfig.
+  streamMode: z.enum(["auto", "legacy-tee", "eager-relay"]).optional().catch(undefined),
 }).passthrough().superRefine((config, ctx) => {
   for (const name of Object.keys(config.providers)) {
     if (!isValidProviderName(name)) {
@@ -642,6 +647,19 @@ export function hardenExistingSecret(path: string): void {
     }
   }
 }
+/**
+ * The schema's `.catch(undefined)` silently degrades an invalid persisted
+ * `streamMode` to "auto"; surface that once so a hand-edited typo (e.g.
+ * "legacy_tee") is discoverable instead of silently changing stream shape.
+ */
+function warnDegradedStreamMode(rawParsed: unknown, validated: OcxConfig): void {
+  if (!rawParsed || typeof rawParsed !== "object") return;
+  const raw = (rawParsed as Record<string, unknown>).streamMode;
+  if (raw !== undefined && validated.streamMode === undefined) {
+    console.warn(`⚠️  config.json streamMode ${JSON.stringify(raw)} is invalid (expected "auto", "legacy-tee", or "eager-relay") — falling back to "auto"`);
+  }
+}
+
 export function loadConfig(): OcxConfig {
   const dir = getConfigDir();
   const configPath = getConfigPath();
@@ -655,7 +673,10 @@ export function loadConfig(): OcxConfig {
     const raw = readFileSync(configPath, "utf-8").replace(/^\uFEFF/, "");
     const parsed = JSON.parse(raw);
     const result = configSchema.safeParse(parsed);
-    if (result.success) return result.data as OcxConfig;
+    if (result.success) {
+      warnDegradedStreamMode(parsed, result.data as OcxConfig);
+      return result.data as OcxConfig;
+    }
     // Schema validation failed — merge defaults into the raw object instead of
     // discarding it entirely, so pool accounts and providers survive a missing
     // field like defaultProvider.
@@ -773,6 +794,15 @@ export function codexAutoStartEnabled(config: Pick<OcxConfig, "codexAutoStart">)
   return config.codexAutoStart !== false;
 }
 
+export const CODEX_SHIM_AUTO_RESTORE_ENV = "OPENCODEX_CODEX_SHIM_AUTO_RESTORE";
+
+export function codexShimAutoRestoreEnabled(
+  config: Pick<OcxConfig, "codexShimAutoRestore">,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return config.codexShimAutoRestore !== false && env[CODEX_SHIM_AUTO_RESTORE_ENV] !== "0";
+}
+
 export function multiAgentGuidanceEnabled(
   config: Pick<OcxConfig, "multiAgentGuidanceEnabled">,
 ): boolean {
@@ -802,6 +832,7 @@ export function getDefaultConfig(): OcxConfig {
     multiAgentGuidanceEnabled: true,
     websockets: false,
     codexAutoStart: true,
+    codexShimAutoRestore: true,
   };
 }
 

package/src/lib/bun-stream-caps.ts

@@ -0,0 +1,88 @@
+/**
+ * Bun runtime stream-capability gate for the Windows SSE passthrough path (#314).
+ *
+ * The eager bounded relay (src/server/relay-eager.ts) uses a JS async producer
+ * loop — the exact shape of the Bun#32111 use-after-free (fixed upstream by Bun
+ * PR #32120, merged 2026-06-21). No RELEASED Bun version is proven to carry
+ * that fix yet, so `MIN_FIXED_BUN_VERSION` is null: every runtime is
+ * "known-bad" until a bundle-bump commit sets it. Config `streamMode` can force
+ * either path (persisted in config.json because Windows services do not
+ * inherit shell env — see devlog/_plan/260723_win_mem_safestream/001).
+ *
+ * Prerelease conservatism: a version carrying a prerelease suffix (e.g.
+ * `1.4.0-canary.3`) is NEVER treated as fixed even when its numeric triple
+ * reaches the threshold — canaries are exactly the OPENCODEX_BUN_PATH audience
+ * and may predate the fix commit.
+ */
+
+/**
+ * Bump in the SAME commit that bumps package.json's bundled Bun to a version
+ * verified to include Bun PR #32120. null = no released version is known-fixed.
+ */
+export const MIN_FIXED_BUN_VERSION: string | null = null;
+
+export type StreamMode = "auto" | "legacy-tee" | "eager-relay";
+
+export const STREAM_MODES: readonly StreamMode[] = ["auto", "legacy-tee", "eager-relay"];
+
+export function isStreamMode(value: unknown): value is StreamMode {
+  return typeof value === "string" && (STREAM_MODES as readonly string[]).includes(value);
+}
+
+/** Numeric [major, minor, patch] triple, or null for unparseable input. */
+export function parseBunVersion(version: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** Compare two version strings numerically; null when either is unparseable. */
+export function compareBunVersions(a: string, b: string): number | null {
+  const pa = parseBunVersion(a);
+  const pb = parseBunVersion(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i]! !== pb[i]!) return pa[i]! - pb[i]!;
+  }
+  return 0;
+}
+
+function hasPrereleaseSuffix(version: string): boolean {
+  return /^\d+\.\d+\.\d+-/.test(version.trim());
+}
+
+/**
+ * True only when `version` is proven to carry the Bun#32120 async-pull cancel
+ * fix. Conservative: unknown, unparseable, prerelease, or no threshold → false.
+ */
+export function bunHasAsyncPullCancelFix(
+  version: string,
+  minFixed: string | null = MIN_FIXED_BUN_VERSION,
+): boolean {
+  if (!minFixed) return false;
+  if (hasPrereleaseSuffix(version)) return false;
+  const cmp = compareBunVersions(version, minFixed);
+  return cmp !== null && cmp >= 0;
+}
+
+export type EagerRelayDecision = {
+  useEagerRelay: boolean;
+  reason: "config-legacy" | "config-eager" | "auto-fixed-runtime" | "auto-known-bad";
+};
+
+/**
+ * Decide the win32 SSE client-path shape. `version`/`minFixed` are injectable
+ * for tests. Non-win32 callers never consult this (their default path is
+ * unchanged); the caller owns the platform check.
+ */
+export function decideEagerRelay(
+  mode: StreamMode,
+  version: string = Bun.version,
+  minFixed: string | null = MIN_FIXED_BUN_VERSION,
+): EagerRelayDecision {
+  if (mode === "legacy-tee") return { useEagerRelay: false, reason: "config-legacy" };
+  if (mode === "eager-relay") return { useEagerRelay: true, reason: "config-eager" };
+  return bunHasAsyncPullCancelFix(version, minFixed)
+    ? { useEagerRelay: true, reason: "auto-fixed-runtime" }
+    : { useEagerRelay: false, reason: "auto-known-bad" };
+}

package/src/lib/crash-guard.ts

@@ -162,7 +162,9 @@ const BENIGN_LOG_INTERVAL_MS = 5 * 60_000;
  * disconnects mid-SSE on the tee()'d passthrough path (responses.ts Bun#32111
  * workaround), Bun's sink-close teardown tries to cancel the tee-locked source body
  * and rejects off-path. Request lifecycle is already settled at that point; same
- * benign handling applies.
+ * benign handling applies. The tee path remains the DEFAULT passthrough shape;
+ * the gated eager relay (relay-eager.ts, #314) does not tee and may not produce
+ * this shape — detection stays unchanged either way.
  */
 export function isBenignAbortTeardown(err: unknown): boolean {
   if (!(err instanceof TypeError)) return false;

package/src/lib/sse-decoder.ts

@@ -3,6 +3,10 @@ export interface ServerSentEvent {
   data: string;
 }
 
+export type SseRecord =
+  | { kind: "event"; event?: string; data: string }
+  | { kind: "comment"; comment: string };
+
 /**
  * Decode text/event-stream records across arbitrary fetch chunk boundaries.
  *
@@ -10,10 +14,18 @@ export interface ServerSentEvent {
  * final newline. That matters for compatible APIs that place a terminal event in the last bytes of
  * the body: dropping that record turns a successful response into an adapter_eof failure.
  */
+export function decodeServerSentEvents(
+  source: ReadableStream<Uint8Array>,
+  options: { includeComments: true; signal?: AbortSignal },
+): AsyncGenerator<SseRecord>;
+export function decodeServerSentEvents(
+  source: ReadableStream<Uint8Array>,
+  options?: { includeComments?: false; signal?: AbortSignal },
+): AsyncGenerator<ServerSentEvent>;
 export async function* decodeServerSentEvents(
   source: ReadableStream<Uint8Array>,
-  options?: { signal?: AbortSignal },
-): AsyncGenerator<ServerSentEvent> {
+  options?: { includeComments?: boolean; signal?: AbortSignal },
+): AsyncGenerator<ServerSentEvent | SseRecord> {
   const reader = source.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
@@ -27,7 +39,9 @@ export async function* decodeServerSentEvents(
   if (signal?.aborted) onAbort();
   else signal?.addEventListener("abort", onAbort, { once: true });
 
-  const dispatch = (): ServerSentEvent | undefined => {
+  const includeComments = options?.includeComments === true;
+
+  const dispatch = (): ServerSentEvent | SseRecord | undefined => {
     if (dataLines.length === 0) {
       event = undefined;
       return undefined;
@@ -35,13 +49,18 @@ export async function* decodeServerSentEvents(
     const record = { ...(event ? { event } : {}), data: dataLines.join("\n") };
     event = undefined;
     dataLines = [];
-    return record;
+    return includeComments ? { kind: "event", ...record } : record;
   };
 
-  const acceptLine = (rawLine: string): ServerSentEvent | undefined => {
+  const acceptLine = (rawLine: string): ServerSentEvent | SseRecord | undefined => {
     const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
     if (line === "") return dispatch();
-    if (line.startsWith(":")) return undefined;
+    if (line.startsWith(":")) {
+      if (!includeComments) return undefined;
+      let comment = line.slice(1);
+      if (comment.startsWith(" ")) comment = comment.slice(1);
+      return { kind: "comment", comment };
+    }
 
     const colon = line.indexOf(":");
     const field = colon < 0 ? line : line.slice(0, colon);

package/src/responses/parser.ts

@@ -129,7 +129,7 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
       out.push({
         name: t.name,
         description: (t.description as string) ?? "",
-        parameters: { type: "object", properties: { input: { type: "string", description: "Raw tool input (verbatim body, e.g. the apply_patch envelope)." } }, required: ["input"] },
+        parameters: { type: "object", properties: { input: { type: "string", description: "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope." } }, required: ["input"] },
         freeform: true,
       });
     }
@@ -594,6 +594,7 @@ export function parseRequest(body: unknown): OcxParsedRequest {
     stream: data.stream === true,
     options,
     _rawBody: body,
+    ...(replayedInputPrefixLength > 0 ? { _replayPrefixLen: replayedInputPrefixLength } : {}),
     ...(webSearch ? { _webSearch: webSearch } : {}),
     ...(structuredOutput ? { _structuredOutput: true } : {}),
     ...(compactionRequest ? { _compactionRequest: true } : {}),

package/src/responses/state.ts

@@ -241,9 +241,13 @@ export function previousResponseProviderState(responseId: string | undefined): O
   return providers ? structuredClone(providers) : undefined;
 }
 
+/**
+ * Cache completed output and max_output_tokens partial output for previous_response_id replay.
+ * Content-filtered incomplete and failed output are not authoritative replay history.
+ */
 export function rememberResponseState(
   requestBody: unknown,
-  response: { id?: unknown; output?: unknown; status?: unknown },
+  response: { id?: unknown; output?: unknown; status?: unknown; incomplete_details?: unknown },
   providerState?: OcxProviderContinuationState | string,
   opts?: { force?: boolean },
 ): void {
@@ -256,7 +260,11 @@ export function rememberResponseState(
   // real server-side response storage.
   if (request.store === false && !opts?.force) return;
   if (typeof response.id !== "string" || !Array.isArray(response.output)) return;
-  if (response.status !== undefined && response.status !== "completed") return;
+  if (response.status === "incomplete") {
+    const details = response.incomplete_details;
+    if (!details || typeof details !== "object" || Array.isArray(details)
+      || (details as { reason?: unknown }).reason !== "max_output_tokens") return;
+  } else if (response.status !== undefined && response.status !== "completed") return;
   ensureLoaded();
   const normalizedProviderState: OcxProviderContinuationState = typeof providerState === "string"
     ? { cursor: { conversationId: providerState } }

package/src/server/auth-cors.ts

@@ -80,7 +80,10 @@ export function corsHeaders(req?: Request, config?: OcxConfig): Record<string, s
   return {
     "Access-Control-Allow-Origin": allowOrigin,
     "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-OpenCodex-API-Key, X-Api-Key, Anthropic-Version, Anthropic-Beta",
+    // ChatGPT-Account-Id is required for browser/Electron ChatGPT & Codex App voice preflights
+    // (direct forward auth matches the bearer to this account id). The OpenAI-Alpha .. X-OAI-Attestation
+    // block covers GPT-Live voice protocol headers relayed by the /v1/live call-create path.
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-OpenCodex-API-Key, X-Api-Key, Anthropic-Version, Anthropic-Beta, ChatGPT-Account-Id, OpenAI-Alpha, X-Session-Id, Session-Id, Thread-Id, Originator, X-OAI-Attestation",
     "Vary": "Origin",
   };
 }

package/src/server/index.ts

@@ -18,6 +18,7 @@ import {
 } from "../config";
 import { reconcileOAuthProviders } from "../oauth";
 import { invalidateCodexModelsCache } from "../codex/catalog";
+import { startMemoryWatchdog } from "./memory-watchdog";
 import { runOpenAiTierStartupMigration } from "../providers/openai-tier-startup";
 import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
@@ -121,11 +122,90 @@ import { handleChatCompletions } from "./chat-completions";
 import { anthropicErrorResponse } from "../claude/outbound";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
 import { handleImages } from "./images";
+import { handleLive, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "./live";
 import { handleSearch } from "./search";
 import { fetchAllModels, handleManagementAPI, VERSION } from "./management-api";
 
 const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
 const WEBSOCKET_IDLE_TIMEOUT_SECONDS = 0;
+const LIVE_SIDEBAND_PENDING_MAX = 32;
+
+function closeLiveSideband(ws: ServerWebSocket<WsData>, code = 1000, reason = ""): void {
+  try {
+    ws.data.liveUpstream?.close(code, reason);
+  } catch {
+    /* upstream already gone */
+  }
+  ws.data.liveUpstream = undefined;
+  ws.data.livePending = undefined;
+  try {
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close(code, reason);
+    }
+  } catch {
+    /* client already gone */
+  }
+}
+
+function attachLiveSidebandUpstream(ws: ServerWebSocket<WsData>): void {
+  const url = ws.data.liveUpstreamUrl;
+  if (!url) {
+    closeLiveSideband(ws, 1011, "missing upstream");
+    return;
+  }
+  let upstream: WebSocket;
+  try {
+    // Bun accepts per-handshake headers; the DOM lib types only list protocol arrays.
+    upstream = new WebSocket(url, { headers: ws.data.liveUpstreamHeaders ?? {} } as unknown as string[]);
+  } catch {
+    closeLiveSideband(ws, 1011, "upstream connect failed");
+    return;
+  }
+  ws.data.liveUpstream = upstream;
+  ws.data.cancel = () => {
+    try {
+      upstream.close(1000, "client closed");
+    } catch {
+      /* ignore */
+    }
+  };
+
+  upstream.addEventListener("open", () => {
+    ws.data.liveOpened = true;
+    const pending = ws.data.livePending ?? [];
+    ws.data.livePending = undefined;
+    for (const frame of pending) {
+      try {
+        upstream.send(frame);
+      } catch {
+        closeLiveSideband(ws, 1011, "upstream send failed");
+        return;
+      }
+    }
+  });
+  upstream.addEventListener("message", (event) => {
+    try {
+      if (typeof event.data === "string") ws.send(event.data);
+      else if (event.data instanceof ArrayBuffer) ws.send(event.data);
+      else if (ArrayBuffer.isView(event.data)) {
+        ws.send(event.data.buffer.slice(event.data.byteOffset, event.data.byteOffset + event.data.byteLength));
+      } else ws.send(event.data as Buffer);
+    } catch {
+      closeLiveSideband(ws, 1011, "client send failed");
+    }
+  });
+  upstream.addEventListener("close", (event) => {
+    try {
+      ws.close(event.code || 1000, event.reason || "");
+    } catch {
+      /* ignore */
+    }
+    ws.data.liveUpstream = undefined;
+  });
+  upstream.addEventListener("error", () => {
+    closeLiveSideband(ws, 1011, "upstream error");
+  });
+}
 
 // GUI static serving extracted to ./server/gui-static. Re-exported below to keep the
 // "../src/server" import surface stable for tests/callers.
@@ -134,8 +214,12 @@ const WEBSOCKET_IDLE_TIMEOUT_SECONDS = 0;
 
 // Source invariant for tests/passthrough-abort.test.ts after the pure module split:
 // if (isEventStream && upstreamResponse.body) {
-// upstreamResponse.body.tee()
 // const repairConfig = route.provider.responsesItemIdRepair;
+// #314 gated shape (win32-no-repair only; default OFF on the bundled known-bad runtime):
+// decideEagerRelay(config.streamMode ?? "auto")
+// relaySseEagerBounded(upstreamResponse.body, turnAc,
+// Default shape (tee + background inspection):
+// upstreamResponse.body.tee()
 // const repairedBody = hasResponsesItemIdRepair(repairConfig)
 // process.platform === "win32"
 // && !hasResponsesItemIdRepair(repairConfig)
@@ -184,6 +268,9 @@ export function startServer(port?: number) {
   // usage.jsonl already persists every request; rehydrate the in-memory Logs ring so
   // /api/logs (and the GUI) survive `ocx stop` / `ocx start` process restarts.
   hydrateRequestLogsFromDisk();
+  // #314: warn-only RSS observability (unref'd, idempotent — safe under repeated
+  // startServer(0) in tests). Snapshot surfaces via GET /api/system/memory.
+  startMemoryWatchdog();
 
   const listenPort = port ?? config.port ?? 10100;
   setCorsOrigin(listenPort);
@@ -490,6 +577,77 @@ export function startServer(port?: number) {
         return withCors(response, req, config);
       }
 
+      // ChatGPT / Codex App voice (GPT‑Live / Frameless Bidi) + OpenAI Realtime call-create.
+      // Clients hit either /v1/live (Frameless App) or /v1/realtime/calls (codex RealtimeCallClient /
+      // public Realtime API). Sideband WS joins are handled just below.
+      if (
+        req.method === "POST"
+        && (url.pathname === "/v1/live" || url.pathname === "/v1/realtime/calls")
+      ) {
+        disableResponsesRequestTimeout(req, requestServer);
+        if (isDraining()) {
+          return new Response("Service shutting down", {
+            status: 503,
+            headers: { ...corsHeaders(req, config), "Retry-After": "5" },
+          });
+        }
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return withCors(apiAuthError, req, config);
+        if (!isAllowedRequestOrigin(req, config)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, config);
+        }
+        const start = Date.now();
+        const requestId = nextRequestLogId(start);
+        const logCtx: RequestLogContext = { model: "gpt-live", provider: "unknown" };
+        const response = await handleLive(req, config, logCtx);
+        addFinalRequestLog(
+          requestId,
+          start,
+          logCtx,
+          response.status,
+          response.status === 499 ? { closeReason: "client_cancel" } : undefined,
+        );
+        return withCors(response, req, config);
+      }
+
+      // Voice / Realtime sideband WebSocket: Frameless joins /v1/live/{callId}; Realtime v1 joins
+      // /v1/realtime?call_id= (or /v1/realtime/calls/{callId}). Transparent bidirectional relay.
+      const liveSidebandTarget = req.headers.get("upgrade")?.toLowerCase() === "websocket"
+        ? parseLiveSidebandTarget(url.pathname, url.searchParams)
+        : null;
+      if (liveSidebandTarget) {
+        if (isDraining()) {
+          return new Response("Service shutting down", {
+            status: 503,
+            headers: { ...corsHeaders(req, config), "Retry-After": "5" },
+          });
+        }
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return withCors(apiAuthError, req, config);
+        if (!isAllowedRequestOrigin(req, config)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "WebSocket upgrade blocked: non-local Origin"), req, config);
+        }
+        const start = Date.now();
+        const requestId = nextRequestLogId(start);
+        const logCtx: RequestLogContext = { model: "gpt-live", provider: "unknown" };
+        const resolved = await resolveLiveSidebandUpgrade(req, config, logCtx, liveSidebandTarget);
+        if (resolved instanceof Response) {
+          addFinalRequestLog(requestId, start, logCtx, resolved.status);
+          return withCors(resolved, req, config);
+        }
+        addFinalRequestLog(requestId, start, logCtx, 101);
+        if (server.upgrade(req, {
+          data: {
+            kind: "live-sideband",
+            liveUpstreamUrl: resolved.upstreamWsUrl,
+            liveUpstreamHeaders: resolved.headers,
+            livePending: [],
+            liveOpened: false,
+          } satisfies WsData,
+        })) return undefined as unknown as Response;
+        return withCors(formatErrorResponse(426, "upgrade_required", "WebSocket upgrade failed"), req, config);
+      }
+
       // Data-plane guard: unknown /v1/* paths must fail with JSON 404, never fall through to the
       // GUI static handler (extensionless paths would get index.html with HTTP 200 and codex-rs
       // endpoint clients — memories/*, realtime/* — would surface confusing
@@ -511,10 +669,37 @@ export function startServer(port?: number) {
       // Responses WebSocket data plane (phase 120.2). Re-frames the same SSE pipeline onto the
       // socket: parse response.create → run handleResponses unchanged → pump its SSE body as WS
       // Text frames. response.processed is a no-op ack. close() aborts the upstream (RC2 parity).
+      // Live sideband sockets (kind=live-sideband) are a transparent bidirectional relay instead.
       open(ws: ServerWebSocket<WsData>) {
+        if (ws.data.kind === "live-sideband") {
+          attachLiveSidebandUpstream(ws);
+          return;
+        }
         registerCodexWebSocket(ws);
       },
       message(ws: ServerWebSocket<WsData>, raw: string | Buffer) {
+        if (ws.data.kind === "live-sideband") {
+          const upstream = ws.data.liveUpstream;
+          if (!upstream || upstream.readyState === WebSocket.CONNECTING || !ws.data.liveOpened) {
+            const pending = ws.data.livePending ?? (ws.data.livePending = []);
+            if (pending.length >= LIVE_SIDEBAND_PENDING_MAX) {
+              closeLiveSideband(ws, 1009, "too many pending frames");
+              return;
+            }
+            pending.push(raw);
+            return;
+          }
+          if (upstream.readyState !== WebSocket.OPEN) {
+            closeLiveSideband(ws, 1011, "upstream not open");
+            return;
+          }
+          try {
+            upstream.send(raw);
+          } catch {
+            closeLiveSideband(ws, 1011, "upstream send failed");
+          }
+          return;
+        }
         const rawBytes = typeof raw === "string" ? Buffer.byteLength(raw) : raw.byteLength;
         if (rawBytes > MAX_WS_FRAME_BYTES) {
           sendJsonFrame(ws, buildWsErrorFrame(413, {
@@ -631,6 +816,11 @@ export function startServer(port?: number) {
         })();
       },
       close(ws: ServerWebSocket<WsData>) {
+        if (ws.data.kind === "live-sideband") {
+          ws.data.cancel?.();
+          ws.data.liveUpstream = undefined;
+          return;
+        }
         unregisterCodexWebSocket(ws);
         ws.data.cancel?.(); // RC2: abort the upstream when the client disconnects
       },