@bitkyc08/opencodex 2.7.36 → 2.7.38-preview.20260724

package/src/config.ts

@@ -442,6 +442,10 @@ const configSchema = z.object({
   providerContextCaps: z.record(z.string(), z.number().int().positive()).optional(),
   contextCapValue: z.number().int().positive().optional(),
   multiAgentGuidanceEnabled: 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 +646,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 +672,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.

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/responses/parser.ts

@@ -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/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";
@@ -134,8 +135,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 +189,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);

package/src/server/management/config-routes.ts

@@ -23,6 +23,7 @@ import {
 } from "../../oauth";
 import { removeCredential } from "../../oauth/store";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import { isStreamMode } from "../../lib/bun-stream-caps";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
@@ -58,6 +59,7 @@ import { applySystemEnvToggle } from "../system-env";
 import { getCachedStartupHealth, invalidateStartupHealthCache } from "../startup-health-cache";
 import { runWindowsTrayAction } from "../windows-tray-control";
 import { runStartupInstallAction, type StartupInstallAction } from "../startup-action-control";
+import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../../codex/runtime";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
@@ -74,11 +76,63 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   }
 
   if (url.pathname === "/api/settings" && req.method === "GET") {
+    let resolved: ReturnType<typeof resolveCodexRuntime>;
+    try {
+      // Full alternative discovery (memoized) so newerAvailable warnings work.
+      resolved = resolveCodexRuntime();
+    } catch {
+      resolved = {
+        runtime: { command: "codex", version: null, source: "fallback" },
+        failures: [],
+      };
+    }
+    const lastClamp = loadLastEffortClamp();
+    const clampActive = effortClampAppliesToRuntime(lastClamp, resolved.runtime);
+    const warningParts: string[] = [];
+    if (resolved.replacedConfigured) {
+      warningParts.push(
+        `Preferred Codex runtime is unavailable; using ${displayCodexRuntimePath(resolved.runtime.command)} instead.`,
+      );
+    } else if (
+      resolved.runtime.source === "fallback"
+      && resolved.failures.length > 0
+      && !resolved.runtime.version
+    ) {
+      warningParts.push("No validated Codex runtime found; falling back to `codex`.");
+    }
+    if (clampActive) {
+      const clampVersion = lastClamp?.runtimeVersion ?? resolved.runtime.version ?? "an older binary";
+      warningParts.push(
+        `Some reasoning effort options were hidden because OpenCodex used Codex ${clampVersion}.${resolved.newerAvailable ? " A newer Codex installation is available." : ""}`,
+      );
+    } else if (resolved.newerAvailable) {
+      warningParts.push(
+        `OpenCodex is using an older Codex binary (${resolved.runtime.version ?? "unknown"}). A newer Codex installation is available.`,
+      );
+    }
     return jsonResponse({
       codexAutoStart: codexAutoStartEnabled(config),
       port: config.port,
       hostname: config.hostname ?? "127.0.0.1",
+      streamMode: config.streamMode ?? "auto",
       startupHealth: await getCachedStartupHealth(config),
+      codexRuntime: {
+        path: displayCodexRuntimePath(resolved.runtime.command),
+        version: resolved.runtime.version,
+        source: resolved.runtime.source,
+        newerAvailable: resolved.newerAvailable
+          ? {
+            path: displayCodexRuntimePath(resolved.newerAvailable.command),
+            version: resolved.newerAvailable.version,
+          }
+          : null,
+        catalogClamp: {
+          active: clampActive,
+          removedEfforts: clampActive ? (lastClamp?.removedEfforts ?? []) : [],
+          runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null,
+        },
+        warning: warningParts.length > 0 ? warningParts.join(" ") : null,
+      },
     });
   }
 
@@ -127,17 +181,39 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   }
 
   if (url.pathname === "/api/settings" && req.method === "PUT") {
-    let body: { codexAutoStart?: unknown };
+    // Each field is optional but at least one must be present; fields are
+    // validated when present. streamMode-only PUTs must work: Windows-memory
+    // troubleshooting docs tell service users to set it here (a service does
+    // not inherit shell env, so config.json is its only input). A stream-shape
+    // change applies to NEW turns only — the config object is shared by
+    // reference with the request handlers, no restart needed.
+    let body: { codexAutoStart?: unknown; streamMode?: unknown };
     try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
-    if (typeof body.codexAutoStart !== "boolean") {
+    if (body.codexAutoStart === undefined && body.streamMode === undefined) {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
     }
-    config.codexAutoStart = body.codexAutoStart;
+    if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
+      return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
+    }
+    if (body.streamMode !== undefined && !isStreamMode(body.streamMode)) {
+      return jsonResponse({ error: "streamMode must be auto, legacy-tee, or eager-relay" }, 400);
+    }
+    if (typeof body.codexAutoStart === "boolean") {
+      config.codexAutoStart = body.codexAutoStart;
+    }
+    if (body.streamMode !== undefined) {
+      if (body.streamMode === "auto") {
+        delete config.streamMode;
+      } else {
+        config.streamMode = body.streamMode as "legacy-tee" | "eager-relay";
+      }
+    }
     saveConfig(config);
     invalidateStartupHealthCache();
     return jsonResponse({
       ok: true,
       codexAutoStart: codexAutoStartEnabled(config),
+      streamMode: config.streamMode ?? "auto",
       startupHealth: await getCachedStartupHealth(config),
     });
   }

package/src/server/management/shared.ts

@@ -51,7 +51,7 @@ import {
 import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
-import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
+import { estimateComboCost, estimateRequestCost, effectiveServiceTier, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
 import type { PersistedUsageAttempt } from "../../usage/log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
 import { applySystemEnvToggle } from "../system-env";
@@ -88,7 +88,7 @@ export type CostResult =
   | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
   | { kind: "unavailable"; reason: MetricUnavailableReason };
 
-export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "usageStatus" | "usage"> & {
+export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier"> & {
   attempts?: readonly PersistedUsageAttempt[];
 };
 
@@ -124,9 +124,10 @@ export function unavailableCostReason(entry: MetricSource): MetricUnavailableRea
 }
 
 export function costResult(entry: MetricSource): CostResult {
+  const tier = effectiveServiceTier(entry);
   const estimate = entry.attempts?.length
-    ? estimateComboCost(entry.attempts)
-    : estimateRequestCost({ provider: entry.provider, model: entry.model, usage: entry.usage, usageStatus: entry.usageStatus });
+    ? estimateComboCost(entry.attempts, undefined, tier)
+    : estimateRequestCost({ provider: entry.provider, model: entry.model, usage: entry.usage, usageStatus: entry.usageStatus, serviceTier: tier });
   if (!estimate) return { kind: "unavailable", reason: unavailableCostReason(entry) };
   const estimateReasons = [
     entry.usageStatus === "estimated" || entry.usage?.estimated ? "usage_estimated" as const : undefined,
@@ -152,7 +153,7 @@ export function requestLogDto(entry: RequestLogEntry): Record<string, unknown> {
           ...attempt,
           displayMetrics: {
             tokPerSecond: tokPerSecondResult(attempt),
-            cost: costResult({ ...attempt, attempts: undefined }),
+            cost: costResult({ ...attempt, attempts: undefined, requestedServiceTier: entry.requestedServiceTier, configuredServiceTier: entry.configuredServiceTier, responseServiceTier: entry.responseServiceTier }),
           },
         })),
       }
@@ -183,4 +184,3 @@ export function stripRegistryOnlyStaticHeaders(name: string, provider: OcxProvid
   return rest;
 }
 
-

package/src/server/management/system-routes.ts

@@ -0,0 +1,65 @@
+/**
+ * /api/system/* — service-process runtime/memory introspection (#314 WP3).
+ *
+ * Rides the standard management gate: every /api/* request already passed
+ * requireApiAuth("management") + the origin check before dispatch, so these
+ * routes add no auth of their own. NEVER expose this data on the
+ * unauthenticated /healthz surface.
+ *
+ * The payload is scalar-only (numbers, enum strings): no paths, no tokens, no
+ * account identifiers. `jscHeap` (bun:jsc heapStats) is the js-vs-native
+ * discriminator: a flat JS heap under a growing RSS points at native runtime
+ * memory (the #314 shape), not an app-level JS leak.
+ */
+import { decideEagerRelay } from "../../lib/bun-stream-caps";
+import { getActiveMemoryWatchdog } from "../memory-watchdog";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+const ENDPOINT_SAMPLE_LIMIT = 60;
+
+export async function handleSystemRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config } = ctx;
+  if (url.pathname === "/api/system/memory" && req.method === "GET") {
+    const usage = process.memoryUsage();
+    let jscHeap: { heapSize: number; heapCapacity: number; objectCount: number } | null = null;
+    try {
+      const { heapStats } = await import("bun:jsc");
+      const stats = heapStats();
+      jscHeap = {
+        heapSize: stats.heapSize,
+        heapCapacity: stats.heapCapacity,
+        objectCount: stats.objectCount,
+      };
+    } catch {
+      /* non-Bun tooling or unavailable introspection — omit the discriminator */
+    }
+    const watchdogInstance = getActiveMemoryWatchdog();
+    const watchdog = watchdogInstance
+      ? (() => {
+        const snap = watchdogInstance.snapshot();
+        return {
+          warnThresholdBytes: snap.warnThresholdBytes,
+          lastWarnAt: snap.lastWarnAt,
+          samples: snap.samples.slice(-ENDPOINT_SAMPLE_LIMIT),
+        };
+      })()
+      : null;
+    const streamMode = config.streamMode ?? "auto";
+    return jsonResponse({
+      pid: process.pid,
+      bunVersion: Bun.version,
+      bunRevision: Bun.revision,
+      platform: process.platform,
+      uptimeSeconds: process.uptime(),
+      rss: usage.rss,
+      heapUsed: usage.heapUsed,
+      heapTotal: usage.heapTotal,
+      jscHeap,
+      streamMode,
+      eagerRelay: process.platform === "win32" ? decideEagerRelay(streamMode) : null,
+      watchdog,
+    });
+  }
+  return null;
+}

package/src/server/management-api.ts

@@ -64,6 +64,7 @@ import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
 import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
+import { handleSystemRoutes } from "./management/system-routes";
 import type { ManagementContext } from "./management/context";
 export type { ManagementApiDeps } from "./management/context";
 import { fetchAllModels } from "./management/shared";
@@ -128,7 +129,8 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     ??     (await handleModelRoutes(ctx))
     ??     (await handleAgentSettingsRoutes(ctx))
     ??     (await handleOauthAccountRoutes(ctx))
-    ??     (await handleComboRoutes(ctx));
+    ??     (await handleComboRoutes(ctx))
+    ??     (await handleSystemRoutes(ctx));
   if (routed) return routed;
 
   if (url.pathname === "/api/stop" && req.method === "POST") {

package/src/server/memory-watchdog.ts

@@ -0,0 +1,112 @@
+/**
+ * RSS memory watchdog (#314 WP3) — warn-only observability for the Windows
+ * native-memory growth reported upstream (Bun fetch buffers / socket handles).
+ *
+ * Samples process.memoryUsage() on an unref'd interval into a bounded ring and
+ * logs ONE rate-limited warning when RSS crosses the threshold. It never
+ * restarts anything (threshold auto-restart is deliberately deferred; the
+ * service managers' crash-respawn already covers hard failures). The active
+ * instance is a module-level singleton so the management API can expose the
+ * snapshot without threading server state through route contexts.
+ *
+ * Privacy: samples are scalar numbers only; the warn line never interpolates
+ * paths, hostnames, or tokens.
+ */
+
+export type MemorySample = {
+  /** Epoch ms. */
+  at: number;
+  /** Resident set size in bytes. */
+  rss: number;
+  /** JS heap used in bytes (process.memoryUsage().heapUsed). */
+  heapUsed: number;
+  /** JS heap total in bytes. */
+  heapTotal: number;
+};
+
+export type MemoryWatchdogState = {
+  samples: MemorySample[];
+  warnThresholdBytes: number;
+  lastWarnAt: number | null;
+};
+
+export type MemoryWatchdog = {
+  stop(): void;
+  snapshot(): MemoryWatchdogState;
+};
+
+const DEFAULT_INTERVAL_MS = 60_000;
+const DEFAULT_WARN_THRESHOLD_BYTES = 4 * 1024 ** 3; // 4 GiB
+const DEFAULT_RING_SIZE = 360; // ≈6h at 60s
+const WARN_INTERVAL_MS = 30 * 60_000;
+const DOCS_URL = "https://lidge-jun.github.io/opencodex/troubleshooting/windows-memory/";
+
+let active: MemoryWatchdog | null = null;
+
+/** The running watchdog, if any — read by /api/system/memory. */
+export function getActiveMemoryWatchdog(): MemoryWatchdog | null {
+  return active;
+}
+
+function defaultSample(now: () => number): MemorySample {
+  const usage = process.memoryUsage();
+  return { at: now(), rss: usage.rss, heapUsed: usage.heapUsed, heapTotal: usage.heapTotal };
+}
+
+/**
+ * Start (or replace) the process-wide memory watchdog. Idempotent: a previous
+ * active instance is stopped first, so repeated startServer() calls in tests
+ * never accumulate intervals. The timer is unref'd; stop() is exposed for
+ * tests and clears the singleton.
+ */
+export function startMemoryWatchdog(opts?: {
+  intervalMs?: number;
+  warnThresholdBytes?: number;
+  ringSize?: number;
+  now?: () => number;
+  sample?: () => MemorySample;
+  warn?: (msg: string) => void;
+}): MemoryWatchdog {
+  active?.stop();
+  const intervalMs = opts?.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const warnThresholdBytes = opts?.warnThresholdBytes ?? DEFAULT_WARN_THRESHOLD_BYTES;
+  const ringSize = opts?.ringSize ?? DEFAULT_RING_SIZE;
+  const now = opts?.now ?? Date.now;
+  const sample = opts?.sample ?? (() => defaultSample(now));
+  const warn = opts?.warn ?? ((msg: string) => console.warn(msg));
+
+  const samples: MemorySample[] = [];
+  let lastWarnAt: number | null = null;
+
+  const tick = () => {
+    let s: MemorySample;
+    try {
+      s = sample();
+    } catch {
+      return; // sampling must never break the server
+    }
+    samples.push(s);
+    if (samples.length > ringSize) samples.splice(0, samples.length - ringSize);
+    if (s.rss >= warnThresholdBytes && (lastWarnAt === null || now() - lastWarnAt >= WARN_INTERVAL_MS)) {
+      lastWarnAt = now();
+      const rssMb = Math.round(s.rss / (1024 * 1024));
+      const thresholdMb = Math.round(warnThresholdBytes / (1024 * 1024));
+      warn(`⚠️  opencodex RSS ${rssMb}MB exceeds the ${thresholdMb}MB watch threshold. On Windows this is usually the upstream Bun runtime memory issue — see ${DOCS_URL}`);
+    }
+  };
+
+  const timer = setInterval(tick, intervalMs);
+  (timer as { unref?: () => void }).unref?.();
+
+  const instance: MemoryWatchdog = {
+    stop() {
+      clearInterval(timer);
+      if (active === instance) active = null;
+    },
+    snapshot() {
+      return { samples: [...samples], warnThresholdBytes, lastWarnAt };
+    },
+  };
+  active = instance;
+  return instance;
+}