@yansigit/opencodex 2.31.0

package/src/lib/bun-runtime.ts

@@ -0,0 +1,184 @@
+/**
+ * Bundled Bun runtime resolution.
+ *
+ * opencodex 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 `ocx 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 `ocx 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,130 @@
+/**
+ * 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). Bun 1.4.0 is the first RELEASED version proven
+ * to carry that fix, so `MIN_FIXED_BUN_VERSION` is "1.4.0": older runtimes stay
+ * "known-bad". 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.
+ * Bun 1.4.0 (npm stable, bundled by this package.json) carries the fix: PR
+ * #32120 merged 2026-06-21, well before the 1.4.0 cut, and the full suite ran
+ * green under the 1.4 line on every supported OS (devlog/260814_bun14-preview-dev).
+ */
+export const MIN_FIXED_BUN_VERSION: string | null = "1.4.0";
+
+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;
+}

package/src/lib/codex-restart-contract.ts

@@ -0,0 +1,120 @@
+/**
+ * Contract for the dashboard-driven Codex app-server restart (#1046 follow-up).
+ *
+ * Distinct from `system-restart-contract.ts`: that one restarts THIS proxy process
+ * and needs a pid-bound capability because it kills its own listener. This one asks
+ * matching Codex app-server children to exit so Codex rereads the catalog on next
+ * launch. It never touches the proxy and never spawns a replacement — whoever owns
+ * the app-server (the Codex app, an SSH bootstrap) relaunches it on next use.
+ *
+ * Scalar-only payload. A command line can contain a home directory and a username,
+ * and an OS error message often embeds a path, so neither crosses this boundary.
+ *
+ * Design and audit history: `devlog/_fin/260815_gui_codex_restart/`.
+ */
+
+export const CODEX_RESTART_METHOD = "POST";
+export const CODEX_RESTART_PATH = "/api/system/codex-restart";
+export const CODEX_APP_SERVER_STATE_PATH = "/api/system/codex-app-server";
+
+/** Mirrors CodexAppServerCatalogState so the GUI never imports runtime code. */
+export type CodexAppServerState = "fresh" | "stale" | "not_running" | "unknown";
+
+export type CodexRestartCode =
+  | "stopped"
+  | "nothing_running"
+  | "enumeration_unavailable"
+  | "partially_stopped";
+
+/** GET response: a cheap reading with no side effects. It never signals. */
+export interface CodexAppServerStateResponse {
+  state: CodexAppServerState;
+  runningCount: number;
+}
+
+/** POST response. All four arrays are pid lists — never command lines. */
+export interface CodexRestartResponse {
+  success: boolean;
+  /** Classifier reading taken BEFORE any signal, so the UI can explain why it acted. */
+  stateBefore: CodexAppServerState;
+  /** Whether a catalog or cache write happened during this request. */
+  synced: boolean;
+  requested: number[];
+  stopped: number[];
+  surviving: number[];
+  failed: number[];
+  code: CodexRestartCode;
+}
+
+const APP_SERVER_STATES: readonly string[] = ["fresh", "stale", "not_running", "unknown"];
+const RESTART_CODES: readonly string[] = [
+  "stopped",
+  "nothing_running",
+  "enumeration_unavailable",
+  "partially_stopped",
+];
+
+/**
+ * A pid is a positive safe integer. Accepting a float or a negative number would
+ * let a malformed body reach UI code that renders counts and indexes lengths.
+ */
+function isPidList(value: unknown): value is number[] {
+  return Array.isArray(value)
+    && value.every(entry => typeof entry === "number" && Number.isSafeInteger(entry) && entry > 0);
+}
+
+/**
+ * Runtime guard for GUI consumers: a 2xx body is not automatically this shape.
+ *
+ * Structure is not enough. A body can be structurally valid and still contradict
+ * itself — `code: "stopped"` alongside surviving pids, or `success: true` with a
+ * failure code — and a caller that trusts it reports a success that did not happen.
+ * A version-skewed or regressed proxy is exactly how that arrives, so the
+ * cross-field invariants are checked here rather than assumed.
+ */
+export function isCodexRestartResponse(value: unknown): value is CodexRestartResponse {
+  if (typeof value !== "object" || value === null) return false;
+  const view = value as Record<string, unknown>;
+  const structural = typeof view.success === "boolean"
+    && typeof view.synced === "boolean"
+    && typeof view.stateBefore === "string"
+    && APP_SERVER_STATES.includes(view.stateBefore)
+    && typeof view.code === "string"
+    && RESTART_CODES.includes(view.code)
+    && isPidList(view.requested)
+    && isPidList(view.stopped)
+    && isPidList(view.surviving)
+    && isPidList(view.failed);
+  if (!structural) return false;
+
+  const success = view.success as boolean;
+  const code = view.code as CodexRestartCode;
+  const surviving = view.surviving as number[];
+  const failed = view.failed as number[];
+  const stopped = view.stopped as number[];
+
+  // `success` and `code` must agree: only partially_stopped is an unsuccessful code.
+  if (success !== (code !== "partially_stopped")) return false;
+  // A clean outcome cannot leave anything behind.
+  if (success && (surviving.length > 0 || failed.length > 0)) return false;
+  // An unsuccessful outcome must name what survived.
+  if (!success && surviving.length === 0 && failed.length === 0) return false;
+  // Nothing can be reported stopped when the service says nothing was running.
+  if ((code === "nothing_running" || code === "enumeration_unavailable") && stopped.length > 0) {
+    return false;
+  }
+  return true;
+}
+
+export function isCodexAppServerStateResponse(
+  value: unknown,
+): value is CodexAppServerStateResponse {
+  if (typeof value !== "object" || value === null) return false;
+  const view = value as Record<string, unknown>;
+  return typeof view.state === "string"
+    && APP_SERVER_STATES.includes(view.state)
+    && typeof view.runningCount === "number"
+    && Number.isSafeInteger(view.runningCount)
+    && view.runningCount >= 0;
+}
+