fix(launcher): fall back to a validated PATH Bun and warn on lifecycle version skew

bin/ocx.mjs

@@ -34,6 +34,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isRealBunBinary } from "../src/lib/bun-binary-validator.mjs";
+import { findDesktopCli, findPathBun } from "../src/lib/bun-path-runtime.mjs";
 import { npmInvocation } from "../src/update/npm-invocation.mjs";
 import { pnpmInvocationForPath, resolvePnpmCommands } from "../src/update/pnpm-invocation.mjs";
 import { detectInstallOwnershipFromPath } from "../src/update/install-detection.mjs";
@@ -95,6 +96,15 @@ function currentPackageVersion() {
   }
 }
 
+function pinnedBunVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    return typeof pkg.dependencies?.bun === "string" ? pkg.dependencies.bun : "";
+  } catch {
+    return "";
+  }
+}
+
 function updateTag(currentVersion) {
   // Allowlist the tag: the value is argv-controlled and (on Windows) flows into a
   // shell-joined spawnSync — never forward arbitrary strings.
@@ -884,6 +894,8 @@ const BUN_OVERRIDE_ENV = "OPENCODEX_BUN_PATH";
 // imported; tests/cli/ocx-launcher-source.test.ts pins the two together.
 const BUN_RUNTIME_SOURCE_ENV = "OCX_BUN_RUNTIME_SOURCE";
 const BUN_RUNTIME_PATH_ENV = "OCX_BUN_RUNTIME_PATH";
+/** Total budget for validating a PATH Bun fallback (both probes together). */
+const PATH_BUN_PROBE_BUDGET_MS = 5_000;
 
 function findBunBinary(bunDir) {
   // The bundled `bun` package ships the binary as bin/bun.exe on every platform;
@@ -899,14 +911,16 @@ function fail(msg) {
   const reinstall = installMethod === "pnpm"
     ? "pnpm add -g --allow-build=bun @bitkyc08/opencodex"
     : "npm install -g --allow-scripts=bun @bitkyc08/opencodex";
+  const desktopCli = findDesktopCli();
   console.error(
     `opencodex: ${msg}\n` +
       "The bundled Bun runtime could not be prepared. This usually means the\n" +
       "install skipped lifecycle scripts (for example npm blocked bun's postinstall\n" +
       "or pnpm did not approve bun's build) or optional dependencies. Reinstall with:\n" +
       `  ${reinstall}\n` +
       "(use sudo if the original install used sudo; without --ignore-scripts\n" +
-      "and without --omit=optional / optional=false)"
+      "and without --omit=optional / optional=false)" +
+      (desktopCli ? `\nAn installed Desktop CLI is available: "${desktopCli}"` : "")
   );
   process.exit(1);
 }
@@ -923,25 +937,32 @@ function resolveBun({ allowInstall = true } = {}) {
     );
   }
 
-  let bunDir;
+  let bunDir = null;
   try {
     bunDir = bunBinDir();
-  } catch {
-    fail("the `bun` dependency is not installed.");
-  }
+  } catch { /* Missing dependency can still fall back to a validated PATH Bun. */ }
 
-  let bin = findBunBinary(bunDir);
+  let bin = bunDir ? findBunBinary(bunDir) : null;
   if (bin) return { path: bin, source: "bundled" };
 
   // Lazy fallback: --ignore-scripts (or a failed postinstall) leaves the
   // ~450-byte placeholder stub. Run the bun package's own installer once.
-  const installJs = join(bunDir, "install.js");
-  if (allowInstall && existsSync(installJs)) {
+  const installJs = bunDir ? join(bunDir, "install.js") : null;
+  if (allowInstall && installJs && existsSync(installJs)) {
     const r = spawnSync(process.execPath, [installJs], { stdio: "inherit" });
     if (r.status === 0) bin = findBunBinary(bunDir);
   }
-  if (!bin) fail("Bun binary missing after install attempt.");
-  return { path: bin, source: "bundled" };
+  if (bin) return { path: bin, source: "bundled" };
+
+  // Reached only when the bundled runtime is unusable. The two probes start the candidate Bun
+  // cold, and on Windows a first run of a copied bun.exe is often held by an on-access scan for
+  // well over a second, so the total budget is generous rather than interactive-tight.
+  const pathBun = findPathBun({ pinnedVersion: pinnedBunVersion(), deadlineMs: PATH_BUN_PROBE_BUDGET_MS });
+  if (pathBun) {
+    console.error(`opencodex: using PATH Bun ${pathBun.version}.`);
+    return { path: pathBun.path, source: "process" };
+  }
+  fail(bunDir ? "Bun binary missing after install attempt." : "the `bun` dependency is not installed.");
 }
 
 // `ocx update --help` prints usage and exits WITHOUT side effects. The Node launcher

devlog/_plan/261009_L1-desktop-cli/019_wp2_done.md

@@ -0,0 +1,15 @@
+# 019 — wp2 done (PR A #6802)
+
+**Conclusion.** The CLI now recognizes a Desktop-supervised runtime without an ownership claim and stops recommending a
+competing service. PR #6802 (head 1718fcad8b, rebased on dev fd2032050a) carries evidence, projection, GUI and docs.
+
+**Evidence.** 332 focused tests pass (receipt), typecheck/lint/GUI tsc/build/ratchet/structure/privacy/docs build pass;
+live read-only check on the reporting Mac matches the expected output; independent review PASS after two fix rounds
+(found: live wording without liveness, stale supervision across login probe, override pid binding, untranslated
+guidance, ownership race after the final probe, custom-local precedence).
+
+**What did not improve / risks.** Windows still reports `unsupported`. The fix reaches users whose CLI is updated; the
+2.81.0 runtime's own startup probe still lacks the field until the Desktop app updates (the override covers updated CLIs).
+Hosted CI was pending at D.
+
+**Next.** wp5 command guards stacked on this branch (020 + 003); then wp3 launcher from dev.

devlog/_plan/261009_L1-desktop-cli/021_wp5_execution_packets.md

@@ -0,0 +1,47 @@
+# 021 — wp5 execution packets (cycle plan, PR B stacked on #6802)
+
+**Continuity.** wp2 D (019): "evidence + projection shipped as #6802; next wp5 command guards stacked on that branch,
+then wp3 launcher from dev." Kept. Re-verification: `git diff c15037b324 fd2032050a` touches none of bin/, src/service,
+src/update, src/cli/{index,dispatch,update-restart}.ts, so 020 anchors still hold. Branch
+`codex/desktop-sidecar-command-guards` cut from #6802's head in the same lane worktree (the session's source binding).
+
+Contract: 003 + 020 including r2–r5 (later wins). Blocking rule everywhere: `createSupervisionLatch()` from
+`src/service/desktop-supervision.mjs` — blocked on `desktop` or `unknown && desktopSeen`, cleared only by `none`.
+`desktopServiceRefusal` (020) therefore takes the latch verdict, not just `kind === "desktop"`.
+
+| Worker | Write scope | Notes |
+|---|---|---|
+| G1 service | NEW `src/service/desktop-command-guard.ts`; MODIFY `src/service/cli.ts`, `src/service/orchestration.ts`, `src/service/repair.ts`; tests `tests/service/service-ownership-handover.test.ts` | refuse install/repair/start/restart before any mutation incl. Windows staging; one latch per command |
+| G2 updater | MODIFY `src/update/runtime-ownership.mjs` + `.d.mts`, `bin/ocx.mjs`, `src/update/index.ts`, `src/update/restart-ownership.ts`; tests `tests/update/update-desktop-owner.test.ts`, `tests/update/update-restart-lease.test.ts`, `tests/cli/cli-update-restart.test.ts`, `tests/cli/ocx-launcher-source.test.ts`, `tests/cli/ocx-launcher-runtime.test.ts` | planner `supervision` input; initial + **pre-stop** (index.ts stop block, bin/ocx.mjs stop) + recovery + refresh through one latch; Node proof per 020 r5 |
+| G3 CLI wording | NEW `src/cli/desktop-runtime-guidance.ts`; MODIFY `src/cli/index.ts` (net ≤ 0 lines preferred, max +5), `src/cli/dispatch.ts`, `src/cli/update-restart.ts`; tests `tests/cli/cli-stop-json.test.ts`, `tests/cli/cli-restart-health.test.ts` | type-only import from G1's module; stop notice suppressed under --json, wording "may" |
+| G4 docs | `structure/desktop-shell.md`, `structure/ops/service-and-sidecars.md`, docs-site desktop guide en + ko | guard paragraph + bypass ledger summary (020 r4 F7), user section from 020 (~:766/:782) |
+
+Verifier (main, after integration): the union of the worker test files plus wp2's nine files (regression),
+`bun run typecheck`, `bun scripts/file-size-ratchet.ts`, `bun run structure:check`, `bun run privacy:scan`,
+docs-site build, Node import proof `node bin/ocx.mjs update --help`, and a read-only live check: lane CLI
+`service install` must refuse on the reporting Mac **without mutating anything** — run it only with
+`--dry-run` if the command supports one; otherwise do not run it live (unit tests carry the proof).
+
+
+Reflection (Kant): MISALIGNED → folded: G4 also owns `structure/runtime.md` (cap 600, replace only) and
+`structure/cli-management.md` (020:684, :737); main's verifier adds `tests/cli/cli-dispatch.test.ts`,
+`tests/cli/system-restart-client.test.ts`, `tests/cli/system-restart-client-package-tree.test.ts` (020:850).
+
+Audit (reviewer 01a11e4b): GO-WITH-FIXES (blockers=2), folded:
+1. `SupervisionInspector = (deps?: Parameters<typeof inspectDesktopSupervision>[0]) => DesktopSupervision` (G1).
+   Restart fallback (G3) keeps the restart target pid and calls `inspect({ targetPid })`; an unrelated Desktop pid never
+   blocks the target's recovery. Tests: unrelated pid → allowed; target-bound `unknown`+`desktopSeen:true` → blocked.
+2. Pre-stop targets (G2): Bun updater uses `targetPid: runtimeTrusted ? livePid : undefined` (src/update/index.ts:522-530);
+   the Node launcher passes no `targetPid` and relies on the inspector's own pid-file/runtime-port correlation
+   (bin/ocx.mjs:409). Missing target → inspector correlation only; mismatch → `unknown` (latch keeps a prior block).
+3. Every `unknown` fixture carries `desktopSeen` explicitly (false for pass-through, true for refusal cases).
+Live check: `service` has no `--dry-run` (src/service/cli.ts:169-186) → no live service command is run.
+
+
+Combined-tree check (030 r4 / 031): scratch branch `codex/l1-combined-check` = PR B head 6653faf382 merged with PR C
+head (launcher). Conflict only in `tests/cli/ocx-launcher-runtime.test.ts` (both PRs append a describe block at the end
+of the file; resolution keeps both blocks) and in this plan unit (now synced identically to both branches). Result:
+typecheck pass; 326 pass / 2 skip / 0 fail across launcher runtime/source, bun-runtime, update-desktop-owner,
+version-skew, dispatch, help-recovery; ratchet and structure pass; `node bin/ocx.mjs update --help` exit 0. Whichever of
+PR B / PR C merges second needs that one test-file conflict resolved the same way.
+

devlog/_plan/261009_L1-desktop-cli/030_launcher_bun_fallback.md

@@ -1127,3 +1127,12 @@ Open product/design question: none within accepted wp3 scope. Recorded implement
   Verify on the combined tree before the last push of the later PR.
 - **F6:** add `tests/ci-workflows/bun-runtime.test.ts` to the focused verifier command.
 
+
+
+## r6 amendment (hosted CI, 2026-10-09)
+
+Production budget raised from 750 ms to `PATH_BUN_PROBE_BUDGET_MS = 5_000` in `bin/ocx.mjs`. Windows CI run
+37894746375 (`windows 9/9`) rejected a valid PATH Bun: the two cold probes of a freshly copied `bun.exe` exceeded 750 ms
+under on-access scanning. The fallback runs only when the bundled runtime is unusable, so a larger bound costs nothing
+on the normal path; it stays a total bound shared by both probes.
+

devlog/_plan/261009_L1-desktop-cli/031_wp3_execution_packets.md

@@ -0,0 +1,32 @@
+# 031 — wp3 execution packets (cycle plan, PR C → dev)
+
+**Continuity.** wp2 D (019) said "wp5 guards next, then wp3". The goalplan cursor selected wp3 first (registration
+order; both are ready), and the two are independent, so wp3 runs now on `codex/ocx-launcher-bun-fallback` from dev
+fd2032050a; wp5's packets (021) and branch stay ready. 030 anchors were written against c15037b324; dev's move to
+fd2032050a did not touch bin/, src/lib, src/cli/root.ts or src/cli/version-skew.ts, so they hold.
+
+Contract: 030 incl. r2/r4 (later wins) + 003. PR A (#6802) already added the "Using the ocx CLI with the desktop app"
+section to the docs-site desktop guide, so this PR does not touch that page (040's doc item is satisfied there).
+
+| Worker | Write scope | Notes |
+|---|---|---|
+| K1 launcher | NEW `src/lib/bun-path-runtime.mjs` + `.d.mts`; MODIFY `bin/ocx.mjs`; tests `tests/cli/ocx-launcher-runtime.test.ts`, `tests/cli/ocx-launcher-source.test.ts`, `tests/ci-workflows/bun-runtime.test.ts` | order override → bundled → installer recovery → validated PATH; identity `-e` probe; POSIX writable rejection; same major, minor ≥ pinned; macOS Desktop CLI pointer in `fail`; source assertion scoped to `resolveBun`/`fail` |
+| K2 skew notice | NEW `src/cli/version-skew-notice.ts`; MODIFY `src/cli/root.ts`; tests `tests/cli/cli-version-skew.test.ts` | lifecycle commands only, 200 ms, neutral text, never changes exit code, skip --json/--help |
+| K3 docs | `structure/runtime.md` (net 0, cap 600), `structure/ops/docs-and-release.md`, `structure/ops/service-and-sidecars.md` (launcher paragraph ~:139 only), docs-site install troubleshooting page(s) named in 030 §"MODIFY public installation troubleshooting" (en + ko; other locales must not contradict) | PR A edits other paragraphs of service-and-sidecars.md/runtime.md; touch only the launcher text |
+
+Verifier (main): `bun test tests/cli/ocx-launcher-runtime.test.ts tests/cli/ocx-launcher-source.test.ts tests/ci-workflows/bun-runtime.test.ts tests/cli/cli-version-skew.test.ts tests/cli/cli-head.test.ts` (isolated
+`OPENCODEX_HOME`), `bun run typecheck`, ratchet, structure:check, privacy:scan, docs-site build, and a real Node
+reproduction of the reported failure: a temp copy of the package without `node_modules/bun` launched with
+`node bin/ocx.mjs --version` and a PATH containing the user's Bun → succeeds with the fallback notice (read-only; no
+proxy start).
+
+
+Reflection (Pascal): MISALIGNED → folded: main's verifier also runs `tests/cli/cli-help-recovery.test.ts`,
+`tests/cli/cli-ready.test.ts`, `tests/cli/cli-ready-subprocess.test.ts`, `tests/cli/cli-resolve.test.ts`,
+`tests/cli/cli-resolve-subprocess.test.ts` (030:1076). Combined-tree check (030 r4): main merges PR B's and PR C's
+branches into a scratch branch before the later PR's last push and runs ocx-launcher-source + ocx-launcher-runtime there.
+
+Audit (reviewer 01a11e4b): GO-WITH-FIXES (blockers=1), folded: the Node reproduction runs with a child-only
+environment — `BUN_RUNTIME_TRANSPILER_CACHE_PATH=0`, `OPENCODEX_HOME`/`CODEX_HOME`/`HOME`-derived caches pointed at the
+temp fixture, `OPENCODEX_BUN_PATH` unset, PATH = the user's Bun directory plus system dirs (child only), and the temp
+package copy keeps every installed dependency except `node_modules/bun` so nothing installs during the run.

devlog/_plan/261009_L1-desktop-cli/039_wp3_done.md

@@ -0,0 +1,13 @@
+# 039 — wp3 done (PR C #6807)
+
+**Conclusion.** The package launcher no longer hard-fails when the bundled Bun is missing and a valid Bun is on PATH;
+lifecycle commands warn once on CLI/proxy version skew. PR #6807 (head 73f166f08a, from dev fd2032050a).
+
+**Evidence.** 318 focused tests pass (receipt); real Node reproduction of the report succeeds on PATH Bun 1.4.0; review
+PASS first round.
+
+**Did not improve / risks.** Node 18 and native Windows are left to CI. The PATH check is policy, not authentication.
+The npm/pnpm/mise update path (handled in Node before Bun) has no skew notice. The plan unit is duplicated in #6802 and
+#6807 with identical content (merges cleanly in either order).
+
+**Next.** wp5 command guards on `codex/desktop-sidecar-command-guards` (stacked on #6802), then wp4 closeout.

devlog/_plan/261009_L1-desktop-cli/040_path_cli_decision_closeout.md

@@ -38,3 +38,17 @@ updater.
 3. Final report: PR links, head SHAs, CI runs, open decisions (Windows evidence, GUI wording for unowned supervision,
    PATH installer follow-up), user-environment suggestions (remove stale `~/.opencodex/service-state.json` via
    `ocx service uninstall` from a working CLI, re-enable Start at Login, repoint `~/.bun/bin/ocx`) — suggestions only.
+
+## Outcome (wp4, 2026-10-09)
+
+Decision unchanged: no Desktop PATH installer in this lane. What users get instead:
+
+- #6802: `ocx status`/`doctor`/`resolve` from an updated CLI name OpenCodex Desktop as the live supervisor and stop
+  recommending `ocx service install`; the docs-site desktop guide (en/ko) gained "Using the ocx CLI with the desktop
+  app" with the bundled CLI path per platform.
+- #6807: when the package launcher cannot run, its failure text names `/Applications/OpenCodex.app/Contents/MacOS/ocx`
+  (or the `~/Applications` copy) when installed; a usable PATH Bun now runs the CLI instead of failing.
+- PR B (wp5): command guards so an updated CLI refuses to compete with the Desktop runtime.
+
+Follow-up (separate unit, not opened by this lane): the native "Install ocx command" design above. The coordinator
+thread took it on as `codex/desktop-owned-path-cli`; this lane does not touch that scope.

devlog/_plan/261009_L1-desktop-cli/041_wp4_cycle_plan.md

@@ -0,0 +1,32 @@
+# 041 — wp4 cycle plan (decision record + CI closeout for PR A and PR C)
+
+**Continuity.** wp3 D (039): "next wp5 guards, then wp4 closeout". The goalplan cursor selects wp4 before wp5
+(registration order; wp4 depends only on wp2/wp3). This cycle therefore covers the parts of wp4 that do not need
+PR B: the Desktop PATH CLI decision record and exact-head CI for #6802 and #6807. PR B's CI and the final lane report
+belong to the wp5 cycle that follows; criterion c-5 is met only after all three PRs are green.
+
+Deliverables (B):
+1. Finalize `040_path_cli_decision_closeout.md` with the outcome: decision unchanged (no Desktop PATH installer in this
+   lane), evidence that PR A covers the CLI section of the desktop guide and PR C names the Desktop CLI in launcher
+   failures; follow-up design kept as written.
+2. CI: rerun only failed jobs of #6802 run 37873621613 (`macos 1/2` timed out in a `tests/ci-workflows` batch whose
+   12 files all pass alone; no changed module is in that batch). If the rerun fails again in the same place, compare
+   with dev's run; a real regression goes back to a fix in wp5's branch base (PR A).
+3. Watch #6807 CI at its current head.
+
+Check (C): both PRs' required checks green at their exact heads (`gh pr checks`), recorded with run ids.
+Out of scope: merging, other lanes, PR B.
+
+
+Audit (reviewer 01a11e4b): GO-WITH-FIXES (blockers=1), folded:
+- Review evidence is recorded here for A and C: #6802 independent review PASS (round 3, reviewer 01a11e61, head
+  e866bf0815 → rebased 1718fcad8b, content-identical); #6807 independent review PASS (reviewer 01a11e61, head 73f166f08a).
+  PR B's review and the three-PR reconciliation transfer to wp5's C/D.
+- 039 now exists on this branch too (copied from the launcher branch; identical content).
+- The macos 1/2 failure is retried as a whole failed job after the run completes; a repeat in the same batch is
+  treated as real and investigated, not retried again.
+
+Check amendment (at B): run 37873621613 still had 10 queued/running jobs (Windows runner backlog), so its failed job
+cannot be retried yet and #6807's CI is pending. This cycle's C therefore checks the decision record (privacy and
+structure gates over the changed docs) and records the CI snapshot; the green-at-exact-head requirement for all three
+PRs is verified in wp5's C/D before c-5 is met. Nothing about c-5 is weakened.