@remodex/rmx 1.0.2

package/src/lib/bounded-body.ts

@@ -0,0 +1,242 @@
+/** Maximum number of response-body bytes that may be retained for an error. */
+export const BOUNDED_BODY_MAX_BYTES = 65_536;
+
+/** Default wall-clock and continuous-silence deadlines. */
+export const BOUNDED_BODY_TIMEOUT_MS = 5_000;
+
+export interface BoundedBodyOptions {
+	/** Abort the read with this signal. Its reason is rethrown by identity. */
+	signal?: AbortSignal;
+	/**
+	 * Reject the returned promise with TypeError on malformed or truncated UTF-8
+	 * instead of replacing invalid bytes, including during timeout-path flushes.
+	 * Reader cancellation and lock release still run. Defaults to false.
+	 */
+	fatalUtf8?: boolean;
+	/**
+	 * Byte ceiling for retained body data. Defaults to BOUNDED_BODY_MAX_BYTES (64 KiB),
+	 * which suits error bodies; callers materializing whole success payloads (e.g. a
+	 * non-streaming upstream JSON completion) pass a larger explicit budget.
+	 */
+	maxBytes?: number;
+	/** Total wall-clock deadline. Exposed for focused tests. */
+	totalTimeoutMs?: number;
+	/** Deadline between non-empty raw chunks. Exposed for focused tests. */
+	inactivityTimeoutMs?: number;
+	/** Deadline for the first non-empty raw chunk. Defaults to inactivityTimeoutMs. */
+	firstByteTimeoutMs?: number;
+}
+
+export interface BoundedBodyResult {
+	/** UTF-8 text retained from the response. Empty when the size limit was exceeded. */
+	text: string;
+	/** True when EOF was not observed. */
+	truncated: boolean;
+	/** True for either total-deadline or inactivity-deadline expiry. */
+	timedOut: boolean;
+	/** Distinguishes the wall-clock deadline from an inactivity deadline. */
+	totalTimedOut: boolean;
+	/** True only when continuous inactivity caused the timeout. */
+	inactivityTimedOut: boolean;
+	/** True when the body was observed to exceed the byte cap. */
+	oversized: boolean;
+	/** False means callers should use a status-only fallback, not `text`. */
+	displaySafe: boolean;
+}
+
+const TOTAL_TIMEOUT = Symbol("bounded body total timeout");
+const INACTIVITY_TIMEOUT = Symbol("bounded body inactivity timeout");
+
+/**
+ * Test-only instrumentation: how many times the retained buffer was reallocated
+ * during the most recent read. The accumulator grows geometrically, so this is
+ * logarithmic in the body size and independent of how many chunks the peer sends.
+ * The per-chunk array it replaced retained one object per chunk instead, which a
+ * fragmenting peer can inflate far past the payload ceiling — a property no
+ * correctness assertion can see, which is why it is observable here.
+ */
+let bufferGrowthsForTests = 0;
+export function boundedBodyBufferGrowthsForTests(): number {
+	return bufferGrowthsForTests;
+}
+
+function timeoutPromise(ms: number, value: symbol): { promise: Promise<symbol>; clear: () => void } {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const promise = new Promise<symbol>((resolve) => {
+		timer = setTimeout(() => resolve(value), Math.max(0, ms));
+	});
+	return {
+		promise,
+		clear: () => {
+			if (timer !== undefined) clearTimeout(timer);
+		},
+	};
+}
+
+function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, reason?: unknown): void {
+	// A hostile/broken stream may reject or never settle cancel(). Neither should
+	// escape as an unhandled rejection or extend this primitive's own deadline.
+	try {
+		void reader.cancel(reason).catch(() => undefined);
+	} catch {
+		// Some stream implementations throw synchronously from cancel().
+	}
+}
+
+function decodeUtf8(chunks: readonly Uint8Array[], fatal: boolean): string {
+	const decoder = new TextDecoder("utf-8", { fatal });
+	let text = "";
+	for (const chunk of chunks) text += decoder.decode(chunk, { stream: true });
+	// Flush an incomplete trailing UTF-8 sequence deterministically.
+	text += decoder.decode();
+	return text;
+}
+
+/**
+ * Consume the original response body under strict memory and time bounds.
+ *
+ * This deliberately calls `getReader()` on `response.body`: it never clones or
+ * tees the response. Once an over-limit byte is observed, all retained raw data
+ * is discarded so an untrusted prefix can never become a client-facing error.
+ */
+export async function readBoundedResponseBody(
+	response: Response,
+	options: BoundedBodyOptions = {},
+): Promise<BoundedBodyResult> {
+	const signal = options.signal;
+	if (signal?.aborted) throw signal.reason;
+
+	const body = response.body;
+	if (!body) {
+		return {
+			text: "",
+			truncated: false,
+			timedOut: false,
+			totalTimedOut: false,
+			inactivityTimedOut: false,
+			oversized: false,
+			displaySafe: true,
+		};
+	}
+
+	const reader = body.getReader();
+	const maxBytes = options.maxBytes ?? BOUNDED_BODY_MAX_BYTES;
+	// Geometrically growing single buffer: per-chunk arrays would retain one object per
+	// transport chunk, which a hostile peer could inflate into metadata amplification far
+	// beyond the payload ceiling on large budgets.
+	let retained = new Uint8Array(Math.min(maxBytes, 64 * 1024));
+	let retainedBytes = 0;
+	bufferGrowthsForTests = 0;
+	let mustCancel = false;
+	let cancelReason: unknown;
+	const total = timeoutPromise(options.totalTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS, TOTAL_TIMEOUT);
+	let inactivity = timeoutPromise(
+		options.firstByteTimeoutMs ?? options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+		INACTIVITY_TIMEOUT,
+	);
+
+	let rejectForAbort: ((reason: unknown) => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectForAbort = reject;
+	});
+	const onAbort = () => rejectForAbort?.(signal?.reason);
+	signal?.addEventListener("abort", onAbort, { once: true });
+	// Close the narrow race between the preflight check and listener install.
+	if (signal?.aborted) onAbort();
+
+	try {
+		while (true) {
+			// Attach a rejection handler before racing. If a deadline wins and
+			// cancellation later rejects this read, it remains observed.
+			const read = reader.read();
+			void read.catch(() => undefined);
+			const outcome = await Promise.race([read, total.promise, inactivity.promise, aborted]);
+			// Cancellation owns the body lifetime even when EOF/readability settles in
+			// the same turn. Promise.race otherwise lets array order hide the abort.
+			if (signal?.aborted) {
+				mustCancel = true;
+				cancelReason = signal.reason;
+				throw signal.reason;
+			}
+
+			if (outcome === TOTAL_TIMEOUT || outcome === INACTIVITY_TIMEOUT) {
+				mustCancel = true;
+				cancelReason = new DOMException(
+					outcome === TOTAL_TIMEOUT ? "Error body total timeout" : "Error body inactivity timeout",
+					"TimeoutError",
+				);
+				return {
+					text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
+					truncated: true,
+					timedOut: true,
+					totalTimedOut: outcome === TOTAL_TIMEOUT,
+					inactivityTimedOut: outcome === INACTIVITY_TIMEOUT,
+					oversized: false,
+					displaySafe: false,
+				};
+			}
+
+			const { value, done } = outcome as ReadableStreamReadResult<Uint8Array>;
+			if (done) {
+				return {
+					text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
+					truncated: false,
+					timedOut: false,
+					totalTimedOut: false,
+					inactivityTimedOut: false,
+					oversized: false,
+					displaySafe: true,
+				};
+			}
+
+			if (!value || value.byteLength === 0) continue;
+
+			inactivity.clear();
+			inactivity = timeoutPromise(
+				options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+				INACTIVITY_TIMEOUT,
+			);
+
+			if (value.byteLength > maxBytes - retainedBytes) {
+				mustCancel = true;
+				cancelReason = new DOMException("Error body size limit reached", "QuotaExceededError");
+				retained = new Uint8Array(0);
+				retainedBytes = 0;
+				return {
+					text: "",
+					truncated: true,
+					timedOut: false,
+					totalTimedOut: false,
+					inactivityTimedOut: false,
+					oversized: true,
+					displaySafe: false,
+				};
+			}
+
+			if (retainedBytes + value.byteLength > retained.length) {
+				const grown = new Uint8Array(
+					Math.min(maxBytes, Math.max(retained.length * 2, retainedBytes + value.byteLength)),
+				);
+				grown.set(retained.subarray(0, retainedBytes));
+				retained = grown;
+				bufferGrowthsForTests += 1;
+			}
+			retained.set(value, retainedBytes);
+			retainedBytes += value.byteLength;
+		}
+	} catch (error) {
+		mustCancel = true;
+		cancelReason = error;
+		throw error;
+	} finally {
+		total.clear();
+		inactivity.clear();
+		signal?.removeEventListener("abort", onAbort);
+		if (mustCancel) cancelWithoutWaiting(reader, cancelReason);
+		try {
+			reader.releaseLock();
+		} catch {
+			// A pending read can keep the lock briefly while cancel settles.
+		}
+	}
+}

package/src/lib/bun-binary-validator.d.mts

@@ -0,0 +1,3 @@
+export declare const REAL_BUN_MIN_BYTES: number;
+
+export declare function isRealBunBinary(path: string): boolean;

package/src/lib/bun-binary-validator.mjs

@@ -0,0 +1,18 @@
+import { existsSync, statSync } from "node:fs";
+
+// The `bun` package leaves a tiny ASCII placeholder at bin/bun.exe until its
+// postinstall downloads the real ~60MB binary. Keep the threshold and the
+// false-on-filesystem-error contract shared by the Node launcher and Bun code.
+export const REAL_BUN_MIN_BYTES = 1_000_000;
+
+/**
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isRealBunBinary(path) {
+  try {
+    return existsSync(path) && statSync(path).size >= REAL_BUN_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}

package/src/lib/bun-runtime.ts

@@ -0,0 +1,184 @@
+/**
+ * Bundled Bun runtime resolution.
+ *
+ * Remodex ships the Bun runtime via the `bun` npm dependency (esbuild-style:
+ * a tiny main package + platform-specific `@oven/bun-*` optionalDependencies,
+ * finalized by the package's own postinstall `node install.js`). The npm `bin`
+ * launcher (bin/ocx.mjs) and the durable service/shim integrations both need a
+ * stable path to that binary. This module is the single source of truth.
+ *
+ * In a from-source dev checkout the `bun` dependency may be absent; callers fall
+ * back to `process.execPath` (which is itself Bun when run via `bun src/cli/index.ts`).
+ */
+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isRealBunBinary } from "./bun-binary-validator.mjs";
+
+export { isRealBunBinary };
+
+const require = createRequire(import.meta.url);
+
+const BUN_OVERRIDE_ENV = "OPENCODEX_BUN_PATH";
+
+/**
+ * Env marker stamped by whichever launcher selected the Bun binary, then read back
+ * inside the launched process.
+ *
+ * Provenance has to travel with the launch because it cannot be recovered afterwards:
+ * resolving it at report time answers "what would this shell pick now", not "what was
+ * this service started with", and those differ exactly when the answer matters.
+ */
+export const BUN_RUNTIME_SOURCE_ENV = "OCX_BUN_RUNTIME_SOURCE";
+
+/**
+ * The binary the marker was minted for. Stamped beside the source so a reader can tell
+ * whether a marker still describes the process holding it, without re-deriving the
+ * selection from an environment that may no longer contain it.
+ */
+export const BUN_RUNTIME_PATH_ENV = "OCX_BUN_RUNTIME_PATH";
+
+export type BunRuntimeSource = "override" | "bundled" | "process";
+
+/** The only provenance values any surface may accept off the wire or out of the env. */
+export const BUN_RUNTIME_SOURCES: readonly BunRuntimeSource[] = ["override", "bundled", "process"];
+
+export type DurableBunRuntime = {
+  path: string;
+  source: BunRuntimeSource;
+  overrideEnv: typeof BUN_OVERRIDE_ENV;
+};
+
+/**
+ * The provenance this process was launched with, or `undefined` when nothing
+ * trustworthy is recorded.
+ *
+ * Deliberately never falls back to `durableBunRuntime()`. A service installed before
+ * the marker existed has no provenance, and guessing one from the current environment
+ * would report a confident wrong answer — "unknown" is the honest result and callers
+ * are expected to say so. Values outside the allowlist are treated as absent rather
+ * than passed through.
+ */
+export function reportedBunRuntimeSource(
+  env: NodeJS.ProcessEnv = process.env,
+): BunRuntimeSource | undefined {
+  const raw = env[BUN_RUNTIME_SOURCE_ENV]?.trim();
+  const source = BUN_RUNTIME_SOURCES.find(candidate => candidate === raw);
+  if (!source) return undefined;
+  // Source and binary are a PAIR: without a recorded path that names THIS
+  // executable, the marker describes some other launch and must not be
+  // reported (a bare OCX_BUN_RUNTIME_SOURCE inherited from an unrelated
+  // parent would otherwise claim a confident wrong origin).
+  const recordedPath = env[BUN_RUNTIME_PATH_ENV]?.trim();
+  if (!recordedPath || !samePath(recordedPath, process.execPath)) return undefined;
+  return source;
+}
+
+/** Env pair a launcher stamps for the binary it just selected. */
+export function bunRuntimeProvenanceEnv(runtime: DurableBunRuntime): Record<string, string> {
+  return { [BUN_RUNTIME_SOURCE_ENV]: runtime.source, [BUN_RUNTIME_PATH_ENV]: runtime.path };
+}
+
+/**
+ * Child environment for a proxy started with `process.execPath` — the runtime this
+ * process is already using.
+ *
+ * These launchers re-exec the current runtime rather than resolving a binary, so the
+ * provenance to report is whatever launched THIS process. Without this the marker would
+ * be silently dropped on `rmx ensure`, GUI start, restart, and update-relaunch, and the
+ * service would report an unknown origin it actually knows.
+ *
+ * An inherited marker is carried forward only when the binary it was minted for is the
+ * one about to be re-executed. Inheritance travels down a process tree, so a marker can
+ * outlive its binary — something started under a marked process but running a different
+ * Bun would otherwise relaunch the daemon with a provenance contradicting the binary
+ * actually serving it. The check compares the recorded path rather than re-deriving the
+ * selection, because a service installed with a shell-local override keeps neither that
+ * shell nor its `OPENCODEX_BUN_PATH`, and re-deriving would demote a correct `override`
+ * to `process` on its first relaunch.
+ */
+export function withProcessRuntimeProvenance(
+  env: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+  return { ...env, ...bunRuntimeProvenanceEnv(currentRuntimeProvenance(env)) };
+}
+
+/**
+ * Provenance for `process.execPath`: the inherited claim when it was minted for this
+ * exact executable, otherwise what this executable actually is.
+ */
+function currentRuntimeProvenance(env: NodeJS.ProcessEnv): DurableBunRuntime {
+  const recorded = recordedCurrentRuntime(env);
+  if (recorded) return recorded;
+  // No marker that describes this binary: report what is running. One resolution
+  // supplies both halves so the pair can never disagree.
+  const runtime = unmarkedDurableBunRuntime();
+  return samePath(runtime.path, process.execPath)
+    ? runtime
+    : { path: process.execPath, source: "process", overrideEnv: BUN_OVERRIDE_ENV };
+}
+
+function recordedCurrentRuntime(env: NodeJS.ProcessEnv): DurableBunRuntime | null {
+  const source = reportedBunRuntimeSource(env);
+  const path = env[BUN_RUNTIME_PATH_ENV]?.trim();
+  if (!source || !path || !samePath(path, process.execPath)) return null;
+  return { path, source, overrideEnv: BUN_OVERRIDE_ENV };
+}
+
+/**
+ * Same file, allowing for the aliases a path can pick up between launch and relaunch:
+ * symlinks/junctions, mapped drives, and Windows case differences. Falls back to a
+ * lexical comparison when a path cannot be resolved (it may be gone).
+ */
+function samePath(left: string, right: string): boolean {
+  const canonical = (value: string): string => {
+    let resolved = value;
+    try { resolved = realpathSync(value); } catch { /* keep the literal path */ }
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  };
+  return canonical(left) === canonical(right);
+}
+
+/**
+ * Absolute path to the bundled Bun binary, or null if the `bun` dependency is
+ * not installed/resolvable (or only the un-downloaded placeholder is present).
+ * The npm `bun` package ships the binary as `bin/bun.exe` on every platform;
+ * we also probe `bin/bun` for forward compatibility.
+ */
+export function bundledBunPath(): string | null {
+  try {
+    const bunDir = dirname(require.resolve("bun/package.json"));
+    for (const name of ["bun.exe", "bun"]) {
+      const p = join(bunDir, "bin", name);
+      if (isRealBunBinary(p)) return p;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function unmarkedDurableBunRuntime(): DurableBunRuntime {
+  const bundled = bundledBunPath();
+  if (bundled) return { path: bundled, source: "bundled", overrideEnv: BUN_OVERRIDE_ENV };
+  return { path: process.execPath, source: "process", overrideEnv: BUN_OVERRIDE_ENV };
+}
+
+export function durableBunRuntime(): DurableBunRuntime {
+  // A durable artifact must use the runtime selected BEFORE Bun auto-loaded a
+  // project dotenv. The Node launcher and owned service/shim launchers stamp the
+  // selected source/path pair; it is accepted only when it names this exact
+  // running executable. Re-reading OPENCODEX_BUN_PATH here would let a project
+  // `.env` persist an arbitrary executable into a shim or service.
+  return recordedCurrentRuntime(process.env) ?? unmarkedDurableBunRuntime();
+}
+
+/**
+ * Bun path to bake into durable artifacts (launchd/systemd/Task Scheduler and
+ * the Codex auto-start shim). Prefer the bundled binary — it lives under the
+ * npm global prefix and survives across `rmx update` — and fall back to the
+ * current runtime, which is Bun when launched normally.
+ */
+export function durableBunPath(): string {
+  return durableBunRuntime().path;
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Bun runtime stream-capability gate for eager SSE passthrough (#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. Windows no-rewrite traffic
+ * follows this runtime/config decision, preserving the explicit legacy-tee
+ * safety pin. Darwin no-rewrite traffic stays on tee
+ * for `auto` regardless of runtime capability and reaches eager relay only via
+ * explicit `streamMode: "eager-relay"` opt-in (see
+ * devlog/_fin/260731_macos_rss_retention/100_darwin_eager_optin.md).
+ *
+ * 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 runtime/config SSE client-path capability. `version`/`minFixed`
+ * are injectable for tests; `selectEagerPath` applies platform policy.
+ */
+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" };
+}
+
+/**
+ * Apply the two-platform eager-relay policy to the runtime/config capability.
+ * Windows preserves the decision for no-rewrite traffic. Darwin permits only
+ * explicit config opt-in; `auto` remains tee even on a future fixed runtime.
+ * Returns the normalized effective decision, or null when platform policy,
+ * Windows rewrite needs, or a Darwin non-config-eager mode selects tee.
+ */
+export function selectEagerPath(
+  platform: NodeJS.Platform,
+  needsClientRewrite: boolean,
+  mode: StreamMode,
+  version: string = Bun.version,
+  minFixed: string | null = MIN_FIXED_BUN_VERSION,
+): EagerRelayDecision | null {
+  if (platform !== "win32" && platform !== "darwin") {
+    return null;
+  }
+
+  const decision = decideEagerRelay(mode, version, minFixed);
+  if (platform === "win32") return needsClientRewrite ? null : decision;
+  return decision.reason === "config-eager" ? decision : null;
+}
+
+/**
+ * #864 transport gate: win32 traffic that needs a client payload rewrite must
+ * use the eager single reader with the rewrite applied inline, because the
+ * alternative tee()+JS-pull chain is the Bun#32111-unsafe path that loses the
+ * terminal SSE block on Windows. Independent of the version-based eager
+ * policy: the pull chain is unsafe on the AFFECTED runtimes by definition.
+ */
+export function isWin32EagerRewrite(
+  platform: NodeJS.Platform,
+  needsClientRewrite: boolean,
+): boolean {
+  return platform === "win32" && needsClientRewrite;
+}