fix(doctor): address runtime provenance review

Author: luvs01

docs-site/src/content/docs/troubleshooting/windows-memory.md

@@ -36,8 +36,13 @@ runtime the leak itself remains an upstream problem:
   Windows working-set/RSS counters can under-report committed external
   retention.
 - **`ocx doctor`** — a "Memory / runtime" section shows the *service*
-  process's Bun version, RSS, external/ArrayBuffers counters, JS-heap context,
-  and stream-mode decision. On the bundled Bun 1.3.14 runtime, `heapUsed` /
+  process's Bun version/revision, launcher-reported runtime source, RSS,
+  external/ArrayBuffers counters, JS-heap context, and stream-mode decision.
+  Source is allowlisted as `override`, `bundled`, or `process`; an older service
+  or invalid/missing marker is shown as unknown instead of being guessed from
+  the current shell. An active override remains unvalidated and keeps the
+  conservative runtime gate, but doctor no longer repeats the already-completed
+  `OPENCODEX_BUN_PATH` setup step. On the bundled Bun 1.3.14 runtime, `heapUsed` /
   `jscHeap` alone are not a leak discriminator; compare observed memory with
   `responseState` and repeated samples before assigning an app-level leak.
 - **`GET /api/system/memory`** — the same data over the authenticated

src/cli/doctor.ts

@@ -673,6 +673,7 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
     if (d.bunRuntimeSource === "override") {
       lines.push("         OPENCODEX_BUN_PATH is already active, but this runtime remains unvalidated for automatic eager relay.");
       lines.push("         The conservative auto-known-bad decision remains in effect; bunRevision is informational only.");
+      lines.push("         You can still opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
       return lines;
     }
     if (d.bunRuntimeSource === undefined) {

src/codex/shim.ts

@@ -19,7 +19,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { getConfigDir } from "../config";
-import { durableBunPath } from "../lib/bun-runtime";
+import { BUN_RUNTIME_SOURCE_ENV, durableBunRuntime, type BunRuntimeSource } from "../lib/bun-runtime";
 import { isProcessAlive } from "../lib/process-control";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
@@ -120,11 +120,16 @@ export type CodexShimAutoRestoreResult =
   | { status: "ineligible" | "deferred"; message?: string }
   | { status: "restored"; message: string };
 
-function cliEntry(): { bun: string; cli: string } {
-  // Bundled Bun path (survives `ocx update`); all three shim builders
-  // (Unix / Windows cmd / Windows PowerShell) receive it via this entry.
+function cliEntry(): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string } {
+  // Resolve the durable path and its diagnostic provenance together; all three shim
+  // builders (Unix / Windows cmd / Windows PowerShell) receive the same pair.
   // This module lives in src/codex/, the CLI entry in src/cli/index.ts.
-  return { bun: durableBunPath(), cli: join(import.meta.dir, "..", "cli", "index.ts") };
+  const bunRuntime = durableBunRuntime();
+  return {
+    bun: bunRuntime.path,
+    bunRuntimeSource: bunRuntime.source,
+    cli: join(import.meta.dir, "..", "cli", "index.ts"),
+  };
 }
 
 function commandNames(name: string): string[] {
@@ -366,11 +371,19 @@ function shQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
-export function buildUnixCodexShim(realCodexPath: string, bunPath: string, cliPath: string, tokenFile = serviceApiTokenFilePath()): string {
+export function buildUnixCodexShim(
+  realCodexPath: string,
+  bunPath: string,
+  cliPath: string,
+  tokenFile = serviceApiTokenFilePath(),
+  bunRuntimeSource: BunRuntimeSource = "process",
+): string {
   const internalCommands = CODEX_INTERNAL_COMMANDS.join("|");
   const valueOptions = CODEX_GLOBAL_OPTIONS_WITH_VALUE.join("|");
   return `#!/usr/bin/env sh
 # ${SHIM_MARKER}
+${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)}
+export ${BUN_RUNTIME_SOURCE_ENV}
 if [ -z "$OPENCODEX_API_AUTH_TOKEN" ] && [ -f ${shQuote(tokenFile)} ]; then
   OPENCODEX_API_AUTH_TOKEN="$(cat ${shQuote(tokenFile)})"
   export OPENCODEX_API_AUTH_TOKEN
@@ -431,14 +444,20 @@ function windowsBatchSet(name: string, value: string): string {
   return `set "${name}=${windowsEnvIndirectBatchValue(value, windowsBatchValue)}"`;
 }
 
-export function buildWindowsCodexShim(realCodexPath: string, bunPath: string, cliPath: string): string {
+export function buildWindowsCodexShim(
+  realCodexPath: string,
+  bunPath: string,
+  cliPath: string,
+  bunRuntimeSource: BunRuntimeSource = "process",
+): string {
   const internalCommandChecks = CODEX_INTERNAL_COMMANDS.map(command => `if /I "%~1"=="${command}" goto run_codex`).join("\r\n");
   const valueOptionChecks = CODEX_GLOBAL_OPTIONS_WITH_VALUE.map(option => `if /I "%~1"=="${option}" goto skip_option_value`).join("\r\n");
   return `@echo off\r
 rem ${SHIM_MARKER}\r
 ${windowsBatchSet("OCX_REAL_CODEX", realCodexPath)}\r
 ${windowsBatchSet("OCX_BUN", bunPath)}\r
 ${windowsBatchSet("OCX_CLI", cliPath)}\r
+${windowsBatchSet(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource)}\r
 ${windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath())}\r
 if "%OPENCODEX_API_AUTH_TOKEN%"=="" if exist "%OCX_API_TOKEN_FILE%" set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"\r
 if not "%OCX_SHIM_BYPASS%"=="" goto run_codex\r
@@ -472,12 +491,18 @@ function psString(value: string): string {
   return `'${value.replace(/'/g, "''")}'`;
 }
 
-export function buildWindowsPowerShellCodexShim(realCodexPath: string, bunPath: string, cliPath: string): string {
+export function buildWindowsPowerShellCodexShim(
+  realCodexPath: string,
+  bunPath: string,
+  cliPath: string,
+  bunRuntimeSource: BunRuntimeSource = "process",
+): string {
   const internalCommands = CODEX_INTERNAL_COMMANDS.map(command => psString(command)).join(", ");
   const valueOptions = CODEX_GLOBAL_OPTIONS_WITH_VALUE.map(option => psString(option)).join(", ");
   const tokenFile = serviceApiTokenFilePath();
   return `#!/usr/bin/env pwsh
 # ${SHIM_MARKER}
+$env:${BUN_RUNTIME_SOURCE_ENV} = ${psString(bunRuntimeSource)}
 if (-not $env:OPENCODEX_API_AUTH_TOKEN -and (Test-Path -LiteralPath ${psString(tokenFile)})) {
   $env:OPENCODEX_API_AUTH_TOKEN = (Get-Content -Raw -LiteralPath ${psString(tokenFile)}).Trim()
 }
@@ -601,25 +626,35 @@ function gitBashPath(path: string): string {
 }
 
 function writeShim(wrapperPath: string, realCodexPath: string): void {
-  const { bun, cli } = cliEntry();
+  const { bun, bunRuntimeSource, cli } = cliEntry();
   if (process.platform === "win32") {
     const lower = wrapperPath.toLowerCase();
     if (lower.endsWith(".ps1")) {
       // UTF-8 BOM: Windows PowerShell 5.1 decodes BOM-less .ps1 files in the ANSI
       // codepage, which mangles non-ASCII paths embedded in the shim.
-      writeFileSync(wrapperPath, `\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli)}`, "utf8");
+      writeFileSync(wrapperPath, `\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli, bunRuntimeSource)}`, "utf8");
     } else if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
-      writeFileSync(wrapperPath, buildWindowsCodexShim(realCodexPath, bun, cli), "utf8");
+      writeFileSync(wrapperPath, buildWindowsCodexShim(realCodexPath, bun, cli, bunRuntimeSource), "utf8");
     } else {
       // Extensionless Git-Bash sh launcher: sh shim with forward-slash paths.
       writeFileSync(
         wrapperPath,
-        buildUnixCodexShim(gitBashPath(realCodexPath), gitBashPath(bun), gitBashPath(cli), gitBashPath(serviceApiTokenFilePath())),
+        buildUnixCodexShim(
+          gitBashPath(realCodexPath),
+          gitBashPath(bun),
+          gitBashPath(cli),
+          gitBashPath(serviceApiTokenFilePath()),
+          bunRuntimeSource,
+        ),
         "utf8",
       );
     }
   } else {
-    writeFileSync(wrapperPath, buildUnixCodexShim(realCodexPath, bun, cli), "utf8");
+    writeFileSync(
+      wrapperPath,
+      buildUnixCodexShim(realCodexPath, bun, cli, serviceApiTokenFilePath(), bunRuntimeSource),
+      "utf8",
+    );
     chmodSync(wrapperPath, 0o755);
   }
 }

src/lib/winsw.ts

@@ -20,7 +20,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandUserPath, getConfigDir, loadConfig } from "../config";
 import { recordOwnedConfigPath } from "./config-ownership";
-import { BUN_RUNTIME_SOURCE_ENV, durableBunPath, durableBunRuntime } from "./bun-runtime";
+import { BUN_RUNTIME_SOURCE_ENV, durableBunRuntime, type BunRuntimeSource } from "./bun-runtime";
 import { serviceApiTokenFilePath } from "./service-secrets";
 
 export const WINSW_VERSION = "2.12.0";
@@ -64,6 +64,7 @@ function currentCodexHomeAbsolute(): string {
 
 export interface WinswEntry {
   bun: string;
+  bunRuntimeSource: BunRuntimeSource;
   cli: string;
 }
 
@@ -74,7 +75,6 @@ export interface WinswEntry {
  * user's interactive PATH, which provider subprocesses may need.
  */
 export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = process.env, port?: number): string {
-  const bunRuntime = durableBunRuntime();
   const domain = env.USERDOMAIN?.trim() || ".";
   const user = env.USERNAME?.trim() || "";
   const listenPort = (() => {
@@ -96,7 +96,7 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
   const aclTimeout = env.OPENCODEX_ACL_TIMEOUT_MS?.trim();
   const envLines = [
     `  <env name="OCX_SERVICE" value="1"/>`,
-    `  <env name="${BUN_RUNTIME_SOURCE_ENV}" value="${bunRuntime.source}"/>`,
+    `  <env name="${BUN_RUNTIME_SOURCE_ENV}" value="${entry.bunRuntimeSource}"/>`,
     `  <env name="OCX_API_TOKEN_FILE" value="${xmlEscape(serviceApiTokenFilePath())}"/>`,
     `  <env name="PATH" value="${xmlEscape(env.PATH ?? "")}"/>`,
     env.CODEX_HOME?.trim() ? `  <env name="CODEX_HOME" value="${xmlEscape(currentCodexHomeAbsolute())}"/>` : null,
@@ -373,5 +373,10 @@ export function winswStatusSummary(): string {
 
 /** Default entry mirrors the Task Scheduler baking: durable Bun + cli.ts. */
 export function defaultWinswEntry(cliDir: string): WinswEntry {
-  return { bun: durableBunPath(), cli: join(cliDir, "cli", "index.ts") };
+  const bunRuntime = durableBunRuntime();
+  return {
+    bun: bunRuntime.path,
+    bunRuntimeSource: bunRuntime.source,
+    cli: join(cliDir, "cli", "index.ts"),
+  };
 }

src/tray/windows.ts

@@ -4,7 +4,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync,
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
-import { durableBunPath } from "../lib/bun-runtime";
+import { BUN_RUNTIME_SOURCE_ENV, durableBunRuntime, type BunRuntimeSource } from "../lib/bun-runtime";
 import { forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 
@@ -20,6 +20,7 @@ const TRAY_ICON_FILES = [
 
 export interface WindowsTrayEntry {
   bun: string;
+  bunRuntimeSource?: BunRuntimeSource;
   cli: string;
   script: string;
   codexHome: string;
@@ -81,8 +82,10 @@ function currentCodexHome(): string {
 }
 
 function currentEntry(): WindowsTrayEntry {
+  const bunRuntime = durableBunRuntime();
   return {
-    bun: durableBunPath(),
+    bun: bunRuntime.path,
+    bunRuntimeSource: bunRuntime.source,
     cli: join(import.meta.dir, "..", "cli", "index.ts"),
     script: installedTrayScriptPath(),
     codexHome: currentCodexHome(),
@@ -522,9 +525,27 @@ function parseTrayHostEntry(): WindowsTrayEntry {
     if (typeof value[key] !== "string") throw new Error(`Invalid tray host field: ${key}`);
     safePath(value[key]);
   }
+  if (
+    value.bunRuntimeSource !== undefined
+    && value.bunRuntimeSource !== "override"
+    && value.bunRuntimeSource !== "bundled"
+    && value.bunRuntimeSource !== "process"
+  ) {
+    throw new Error("Invalid tray host field: bunRuntimeSource");
+  }
   return value as WindowsTrayEntry;
 }
 
+export function windowsTrayHostEnvironment(
+  entry: Pick<WindowsTrayEntry, "bunRuntimeSource">,
+  env: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const childEnv = { ...env };
+  if (entry.bunRuntimeSource) childEnv[BUN_RUNTIME_SOURCE_ENV] = entry.bunRuntimeSource;
+  else delete childEnv[BUN_RUNTIME_SOURCE_ENV];
+  return childEnv;
+}
+
 /** Detached Bun host keeps the attached WinForms PowerShell process alive. */
 export async function runWindowsTrayHost(): Promise<void> {
   assertWindows();
@@ -535,7 +556,7 @@ export async function runWindowsTrayHost(): Promise<void> {
   const child = spawn(windowsPowerShellPath(), windowsTrayProcessArgs(entry, "Run", process.pid), {
     stdio: "ignore",
     windowsHide: true,
-    env: process.env,
+    env: windowsTrayHostEnvironment(entry),
   });
   await new Promise<void>((resolvePromise, rejectPromise) => {
     child.once("error", rejectPromise);

tests/codex-shim.test.ts

@@ -58,6 +58,7 @@ describe("Codex autostart shim", () => {
     expect(script).not.toContain("sync-cache");
     expect(script).toContain("exec '/usr/local/bin/codex-real' \"$@\"");
     expect(script).toContain("OPENCODEX_API_AUTH_TOKEN");
+    expect(script).toContain("OCX_BUN_RUNTIME_SOURCE='process'");
   });
 
   test("builds a Windows shim that starts ocx before running Codex", () => {
@@ -68,6 +69,7 @@ describe("Codex autostart shim", () => {
     expect(script).not.toContain("sync-cache");
     expect(script).toContain('set "OCX_REAL_CODEX=C:\\Tools\\codex-real.exe"');
     expect(script).toContain('set "OCX_API_TOKEN_FILE=');
+    expect(script).toContain('set "OCX_BUN_RUNTIME_SOURCE=process"');
     expect(script).toContain('set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"');
     expect(script).toContain('"%OCX_REAL_CODEX%" %*');
   });
@@ -115,15 +117,16 @@ describe("Codex autostart shim", () => {
   test("PowerShell shim is written with a UTF-8 BOM (Windows PowerShell 5.1 decodes BOM-less ps1 as ANSI)", async () => {
     const source = readFileSync(join(import.meta.dir, "..", "src", "codex", "shim.ts"), "utf8");
 
-    expect(source).toContain("`\\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli)}`");
+    expect(source).toContain("`\\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli, bunRuntimeSource)}`");
   });
 
   test("Windows target discovery includes the extensionless Git-Bash launcher and writeShim emits a forward-slash sh shim for it", () => {
     const source = readFileSync(join(import.meta.dir, "..", "src", "codex", "shim.ts"), "utf8");
 
     expect(source).toContain('const gitBashLauncher = join(dir, "codex");');
     expect(source).toContain("for (const path of [cmd, ps1, gitBashLauncher])");
-    expect(source).toContain("buildUnixCodexShim(gitBashPath(realCodexPath), gitBashPath(bun), gitBashPath(cli), gitBashPath(serviceApiTokenFilePath()))");
+    expect(source).toContain("gitBashPath(serviceApiTokenFilePath()),");
+    expect(source).toContain("bunRuntimeSource,");
   });
 
   test("Unix shim accepts an injected token-file path (Git-Bash shims need forward slashes everywhere)", () => {
@@ -177,6 +180,7 @@ describe("Codex autostart shim", () => {
     expect(script).toContain("OCX_SHIM_BYPASS");
     expect(script).toContain("Test-Path -LiteralPath");
     expect(script).toContain("OPENCODEX_API_AUTH_TOKEN");
+    expect(script).toContain("$env:OCX_BUN_RUNTIME_SOURCE = 'process'");
     expect(script).toContain("& 'C:\\codex-real.ps1' @args");
   });
 

tests/doctor.test.ts

@@ -430,6 +430,7 @@ describe("service memory section (#314 WP4)", () => {
     expect(text).toContain("OPENCODEX_BUN_PATH is already active");
     expect(text).not.toContain("set OPENCODEX_BUN_PATH");
     expect(text).toContain("auto-known-bad");
+    expect(text).toContain('streamMode "eager-relay"');
   });
 
   test("legacy payload keeps runtime source unknown without circular override advice", async () => {

tests/windows-tray-runtime-source.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { windowsTrayHostEnvironment } from "../src/tray/windows";
+
+test("Windows tray forwards the recorded Bun source and leaves legacy entries unknown", () => {
+  expect(windowsTrayHostEnvironment(
+    { bunRuntimeSource: "override" },
+    { OCX_BUN_RUNTIME_SOURCE: "bundled", KEEP: "yes" },
+  )).toEqual({ OCX_BUN_RUNTIME_SOURCE: "override", KEEP: "yes" });
+
+  expect(windowsTrayHostEnvironment(
+    {},
+    { OCX_BUN_RUNTIME_SOURCE: "bundled", KEEP: "yes" },
+  )).toEqual({ KEEP: "yes" });
+});
+
+test("Windows tray resolves its durable Bun path and source as one entry", () => {
+  const source = readFileSync(join(import.meta.dir, "..", "src", "tray", "windows.ts"), "utf8");
+  expect(source).toContain("const bunRuntime = durableBunRuntime();");
+  expect(source).toContain("bun: bunRuntime.path");
+  expect(source).toContain("bunRuntimeSource: bunRuntime.source");
+});

tests/winsw.test.ts

@@ -7,7 +7,11 @@ import { mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-const entry = { bun: "C:\\OpenCodex\\bun.exe", cli: "C:\\Open Codex\\cli & co\\index.ts" };
+const entry = {
+  bun: "C:\\OpenCodex\\bun.exe",
+  bunRuntimeSource: "override" as const,
+  cli: "C:\\Open Codex\\cli & co\\index.ts",
+};
 
 function winswEnvValue(xml: string, name: string): string | null {
   const match = xml.match(new RegExp(`<env name="${name}" value="([^"]*)"/>`));
@@ -39,7 +43,7 @@ describe("winsw xml", () => {
     const xml = buildWinswXml(entry, env);
 
     expect(xml).toContain('<env name="OCX_SERVICE" value="1"/>');
-    expect(xml).toMatch(/<env name="OCX_BUN_RUNTIME_SOURCE" value="(override|bundled|process)"\/>/);
+    expect(xml).toContain('<env name="OCX_BUN_RUNTIME_SOURCE" value="override"/>');
     expect(xml).toContain('<env name="OCX_API_TOKEN_FILE"');
     expect(xml).toContain('<env name="PATH" value="C:\\bin;C:\\tools &amp; more"/>');
     expect(winswEnvValue(xml, "OPENCODEX_HOME")).toBe(getConfigDir());