clarify active Bun runtime diagnostics

Author: luvs01

src/cli/doctor.ts

@@ -523,6 +523,8 @@ export async function probeWham(fetchImpl: typeof fetch = fetch): Promise<WhamPr
 export type ServiceMemoryData = {
   pid: number;
   bunVersion: string;
+  bunRevision?: string;
+  bunRuntimeSource?: "override" | "bundled" | "process" | null;
   platform: string;
   rss: number;
   heapUsed: number;
@@ -579,6 +581,10 @@ export async function fetchServiceMemory(
       data: {
         pid: body.pid,
         bunVersion: body.bunVersion,
+        bunRevision: typeof body.bunRevision === "string" ? body.bunRevision : undefined,
+        bunRuntimeSource: body.bunRuntimeSource === "override" || body.bunRuntimeSource === "bundled" || body.bunRuntimeSource === "process"
+          ? body.bunRuntimeSource
+          : null,
         platform: typeof body.platform === "string" ? body.platform : "unknown",
         rss: body.rss,
         heapUsed: typeof body.heapUsed === "number" ? body.heapUsed : 0,
@@ -625,7 +631,14 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
     return lines;
   }
   const d = report.data;
-  lines.push(`  ok     service pid ${d.pid}: Bun ${d.bunVersion} on ${d.platform}`);
+  const sourceLabel = d.bunRuntimeSource === "override"
+    ? "OPENCODEX_BUN_PATH override"
+    : d.bunRuntimeSource;
+  const identityDetails = [
+    d.bunRevision ? `revision=${d.bunRevision}` : null,
+    sourceLabel ? `source=${sourceLabel}` : null,
+  ].filter((value): value is string => Boolean(value)).join(", ");
+  lines.push(`  ok     service pid ${d.pid}: Bun ${d.bunVersion} on ${d.platform}${identityDetails ? ` (${identityDetails})` : ""}`);
   const observed = observedMemory(d);
   const observedBytes = d.observedBytes ?? d.watchdog?.observedBytes ?? observed.bytes;
   const observedMetric = d.observedMetric ?? d.watchdog?.observedMetric ?? observed.metric;
@@ -652,12 +665,15 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
   } else {
     lines.push("  !!     high RSS, indeterminate split — capture two doctor runs over time to see the trend");
   }
-  // Version-claiming (never binary-claiming): the endpoint cannot distinguish
-  // the bundled binary from an OPENCODEX_BUN_PATH override of the same version.
   if (d.platform === "win32" && d.eagerRelay?.reason === "auto-known-bad") {
-    lines.push(`         service is running Bun ${d.bunVersion} on Windows — a version affected by the upstream Bun memory issue.`);
-    lines.push("         Options: wait for a bundled runtime update, or set OPENCODEX_BUN_PATH to a runtime you trust (unvalidated — own risk),");
-    lines.push("         or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+    if (d.bunRuntimeSource === "override") {
+      lines.push(`         OPENCODEX_BUN_PATH is already active for Bun ${d.bunVersion}; automatic eager relay has not validated this runtime revision.`);
+      lines.push("         Keep streamMode \"auto\" for the conservative path, or explicitly opt into \"eager-relay\" at your own risk; see docs.");
+    } else {
+      lines.push(`         service is running Bun ${d.bunVersion} on Windows — a version affected by the upstream Bun memory issue.`);
+      lines.push("         Options: wait for a bundled runtime update, or set OPENCODEX_BUN_PATH to a runtime you trust (unvalidated — own risk),");
+      lines.push("         or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+    }
   }
   return lines;
 }

src/lib/bun-runtime.ts

@@ -19,10 +19,12 @@ export { isRealBunBinary };
 const require = createRequire(import.meta.url);
 
 const BUN_OVERRIDE_ENV = "OPENCODEX_BUN_PATH";
+export const BUN_RUNTIME_SOURCE_ENV = "OCX_BUN_RUNTIME_SOURCE";
+export type BunRuntimeSource = "override" | "bundled" | "process";
 
 export type DurableBunRuntime = {
   path: string;
-  source: "override" | "bundled" | "process";
+  source: BunRuntimeSource;
   overrideEnv: typeof BUN_OVERRIDE_ENV;
 };
 
@@ -60,6 +62,18 @@ export function durableBunRuntime(): DurableBunRuntime {
   return { path: process.execPath, source: "process", overrideEnv: BUN_OVERRIDE_ENV };
 }
 
+/**
+ * Runtime origin reported by the running proxy. Durable launchers bake the
+ * source selected at install time so a later shell environment cannot
+ * misidentify an already-installed service. Direct starts fall back to the
+ * same resolver that selected their Bun executable.
+ */
+export function effectiveBunRuntimeSource(): BunRuntimeSource {
+  const baked = process.env[BUN_RUNTIME_SOURCE_ENV]?.trim();
+  if (baked === "override" || baked === "bundled" || baked === "process") return baked;
+  return durableBunRuntime().source;
+}
+
 /**
  * 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

src/server/management/system-routes.ts

@@ -20,6 +20,7 @@
  * dashboard drain-and-restart confirm UX — never request bodies or IDs.
  */
 import { selectEagerPath } from "../../lib/bun-stream-caps";
+import { effectiveBunRuntimeSource } from "../../lib/bun-runtime";
 import { getActiveTurnCount, isDraining } from "../lifecycle";
 import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
 import { responseStateMetrics } from "../../responses/state";
@@ -75,6 +76,7 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       pid: process.pid,
       bunVersion: Bun.version,
       bunRevision: Bun.revision,
+      bunRuntimeSource: effectiveBunRuntimeSource(),
       platform: process.platform,
       uptimeSeconds: process.uptime(),
       rss: usage.rss,

src/service.ts

@@ -15,7 +15,7 @@ import { loadConfig } from "./config";
 import { restoreNativeCodex } from "./codex/inject";
 import { stripGrokConfig } from "./grok/inject";
 import { isWslRuntime } from "./codex/home";
-import { durableBunPath, durableBunRuntime } from "./lib/bun-runtime";
+import { BUN_RUNTIME_SOURCE_ENV, durableBunPath, durableBunRuntime } from "./lib/bun-runtime";
 import { isProcessAlive, stopProxy } from "./lib/process-control";
 import { serviceApiTokenFilePath } from "./lib/service-secrets";
 import { randomUUID } from "node:crypto";
@@ -269,12 +269,14 @@ function writeServiceApiTokenFile(): string | null {
 
 export function buildPlist(): string {
   const { bun, cli } = cliEntry();
+  const bunRuntime = durableBunRuntime();
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = process.env.CODEX_HOME?.trim();
   const opencodexHome = process.env.OPENCODEX_HOME?.trim();
   const envLines = [
     `    <key>OCX_SERVICE</key><string>1</string>`,
+    `    <key>${BUN_RUNTIME_SOURCE_ENV}</key><string>${bunRuntime.source}</string>`,
     `    <key>PATH</key><string>${plistString(path)}</string>`,
     codexHome ? `    <key>CODEX_HOME</key><string>${plistString(codexHome)}</string>` : null,
     opencodexHome ? `    <key>OPENCODEX_HOME</key><string>${plistString(opencodexHome)}</string>` : null,
@@ -1032,6 +1034,7 @@ export function buildWindowsServiceScript(entry = cliEntry(), port = resolveServ
     // it to UTF-8 is safe (no leak into user shells) and lets cmd parse UTF-8 remnants.
     "chcp 65001 >nul",
     windowsBatchSet("OCX_SERVICE", "1"),
+    windowsBatchSet(BUN_RUNTIME_SOURCE_ENV, bunRuntime.source),
     windowsBatchSet("PATH", path, "pathList"),
     windowsBatchSet("CODEX_HOME", process.env.CODEX_HOME?.trim(), "path"),
     windowsBatchSet("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim(), "path"),
@@ -1571,12 +1574,14 @@ function unitPath(): string {
 
 export function buildUnit(): string {
   const { bun, cli } = cliEntry();
+  const bunRuntime = durableBunRuntime();
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = systemdEnvironmentAssignment("CODEX_HOME", process.env.CODEX_HOME?.trim());
   const opencodexHome = systemdEnvironmentAssignment("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim());
   const envLines = [
     systemdEnvironmentAssignment("OCX_SERVICE", "1"),
+    systemdEnvironmentAssignment(BUN_RUNTIME_SOURCE_ENV, bunRuntime.source),
     systemdEnvironmentAssignment("PATH", path),
     codexHome,
     opencodexHome,
@@ -2163,4 +2168,3 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       process.exit(1);
   }
 }
-

structure/05_gui-and-management-api.md

@@ -78,7 +78,7 @@ this document owns is which module holds which area and what invariant that area
 | V2 / Multi-agent mode | `GET/PUT /api/v2` — reports/sets the codex `multi_agent_v2` feature flag, the 3-state `multiAgentMode` override (`v1`/`default`/`v2`), and the logical maximum thread count. Selecting `v2` enables the native flag and migrates `[agents] max_threads` to the v2 key; selecting `v1` disables it and migrates the same value back. `default` leaves the native flag unchanged. PUT accepts `enabled`, `multiAgentMode`, and/or the compatibility-named `maxConcurrentThreadsPerSession`; contradictory mode/flag pairs are rejected before writes. Every transition is rollback-safe and resyncs the catalog. |
 | Logs & Debug | One sidebar entry (`/#logs`) with two tabs. Logs tab: request/runtime logs for local diagnosis. Debug tab (`/#logs/debug`; legacy `/#debug` deep links redirect there): provider + usage toggles, refresh/follow log viewer. `GET/PUT /api/debug`; `GET /api/debug/logs` and `GET /api/debug/usage-logs` (monotonic `after` cursor, legacy `since` accepted). CLI: `ocx debug provider|usage …` (both streams via running proxy API). |
 | Usage | `GET /api/usage` aggregate read-only summary derived from `~/.opencodex/usage.jsonl`; measured / reported / unreported / unsupported / estimated counts, daily zero-filled grid, model and provider breakdowns. Never exposes prompts. |
-| System | `POST /api/system/restart` restarts the proxy in place. `GET /api/system/memory` — service-process runtime/memory identity (pid, Bun version/revision, platform, RSS/heap/external/ArrayBuffers scalars, observed memory = max(RSS, external, ArrayBuffers), `bun:jsc` heap context, streamMode + eager-relay gate decision, watchdog snapshot sliced to the last 60 samples). Scalar-only payload; rides the standard management auth gate and must never move to unauthenticated `/healthz`. Consumed by `ocx doctor`'s Memory/runtime section and the dashboard Memory observability card. |
+| System | `POST /api/system/restart` restarts the proxy in place. `GET /api/system/memory` — service-process runtime/memory identity (pid, Bun version/revision/runtime source, platform, RSS/heap/external/ArrayBuffers scalars, observed memory = max(RSS, external, ArrayBuffers), `bun:jsc` heap context, streamMode + eager-relay gate decision, watchdog snapshot sliced to the last 60 samples). Scalar-only payload; rides the standard management auth gate and must never move to unauthenticated `/healthz`. Consumed by `ocx doctor`'s Memory/runtime section and the dashboard Memory observability card. |
 | Stop | `POST /api/stop` — restore native Codex, stop any installed service, and exit the proxy. |
 | Diagnostics/sync | `src/server/management/config-routes.ts` — `GET /api/diagnostics/project-config` reports project-level Codex config that bypasses managed routing; `POST /api/sync` re-runs catalog/config sync. The diagnostic reports the bypass; it does not rewrite the project file. |
 | Sidecar/shadow-call settings | `src/server/management/config-routes.ts` — `GET/PUT /api/sidecar-settings` and `GET/PUT /api/shadow-call-settings`. PUT accepts model and backend plus optional `webSearch.reasoning` and `vision.maxDescriptionsPerTurn`; the read and PUT-response payload reports model, backend, and the vision per-turn limit. Credentials live in the provider and OAuth stores instead. Both shadow-call responses also report the resolved `sourceModels` — the prefixes the runtime actually intercepts (`src/lib/shadow-call.ts`, default `gpt-5.4-mini` + `gpt-5.6-luna`), so no client hard-codes a helper slug that a Codex release can invalidate. |

tests/doctor.test.ts

@@ -326,6 +326,8 @@ describe("service memory section (#314 WP4)", () => {
   const baseData: ServiceMemoryData = {
     pid: 4242,
     bunVersion: "1.3.14",
+    bunRevision: "1.3.14+0d9b296a",
+    bunRuntimeSource: "bundled",
     platform: "win32",
     rss: 5 * 1024 ** 3,
     heapUsed: 200 * 1024 ** 2,
@@ -401,11 +403,28 @@ describe("service memory section (#314 WP4)", () => {
     expect(lines.some(l => l.includes("looks normal"))).toBe(false);
   });
 
-  test("guidance gating: win32 + auto-known-bad prints version-claiming guidance", () => {
+  test("guidance gating: bundled win32 + auto-known-bad offers an override", () => {
     const lines = formatServiceMemoryLines({ status: "ok", data: baseData });
+    expect(lines.some(l => l.includes("source=bundled"))).toBe(true);
     expect(lines.some(l => l.includes("OPENCODEX_BUN_PATH"))).toBe(true);
-    // Version-claiming, never binary-claiming.
-    expect(lines.join("\n")).not.toContain("bundled binary");
+  });
+
+  test("guidance gating: active override reports revision without repeating setup advice", () => {
+    const lines = formatServiceMemoryLines({
+      status: "ok",
+      data: {
+        ...baseData,
+        bunVersion: "1.4.0",
+        bunRevision: "1.4.0-canary.1+5f65d3785",
+        bunRuntimeSource: "override",
+      },
+    });
+    const text = lines.join("\n");
+    expect(text).toContain("revision=1.4.0-canary.1+5f65d3785");
+    expect(text).toContain("source=OPENCODEX_BUN_PATH override");
+    expect(text).toContain("OPENCODEX_BUN_PATH is already active");
+    expect(text).not.toContain("set OPENCODEX_BUN_PATH");
+    expect(text).not.toContain("a version affected by the upstream Bun memory issue");
   });
 
   test("guidance gating: darwin auto-off or fixed Windows runtime prints no override guidance", () => {

tests/memory-watchdog.test.ts

@@ -175,7 +175,7 @@ describe("GET /api/system/memory", () => {
     expect(res).not.toBeNull();
     expect(res!.status).toBe(200);
 	    const body = await res!.json() as {
-	      pid: number; bunVersion: string; platform: string; rss: number;
+	      pid: number; bunVersion: string; bunRevision: string; bunRuntimeSource: string; platform: string; rss: number;
 	      heapUsed: number; external: number; arrayBuffers: number; observedBytes: number; observedMetric: string;
 	      jscHeap: { heapSize: number } | null;
 	      responseState: { count: number; totalBytes: number; largestBytes: number; oldestAgeMs: number };
@@ -189,6 +189,8 @@ describe("GET /api/system/memory", () => {
 	    };
     expect(body.pid).toBe(process.pid);
     expect(body.bunVersion).toBe(Bun.version);
+	    expect(body.bunRevision).toBe(Bun.revision);
+	    expect(["override", "bundled", "process"]).toContain(body.bunRuntimeSource);
 	    expect(body.rss).toBeGreaterThan(0);
 	    expect(body.heapUsed).toBeGreaterThan(0);
 	    expect(body.external).toBeGreaterThanOrEqual(0);

tests/service.test.ts

@@ -79,6 +79,13 @@ describe("service listen-port bake", () => {
     expect(buildPlist()).toContain("start --port 13337");
     expect(buildUnit()).toContain("start --port 13337");
   });
+
+  test("durable service artifacts bake the selected Bun runtime source", () => {
+    const script = buildWindowsServiceScript({ bun: "C:\\OpenCodex\\bun.exe", cli: "C:\\OpenCodex\\cli.ts" });
+    expect(script).toMatch(/set "OCX_BUN_RUNTIME_SOURCE=(override|bundled|process)"/);
+    expect(buildPlist()).toMatch(/<key>OCX_BUN_RUNTIME_SOURCE<\/key><string>(override|bundled|process)<\/string>/);
+    expect(buildUnit()).toMatch(/Environment="OCX_BUN_RUNTIME_SOURCE=(override|bundled|process)"/);
+  });
 });
 
 describe("systemd service unit", () => {