Skip to content

fix(doctor): report Bun runtime provenance - #861

Open
luvs01 wants to merge 3 commits into
lidge-jun:devfrom
luvs01:fix/848-bun-runtime-provenance
Open

fix(doctor): report Bun runtime provenance#861
luvs01 wants to merge 3 commits into
lidge-jun:devfrom
luvs01:fix/848-bun-runtime-provenance

Conversation

@luvs01

@luvs01 luvs01 commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Fixes #848

Summary

  • propagate a single allowlisted override | bundled | process Bun runtime provenance marker through the npm Node launcher, Windows Task Scheduler, native Windows WinSW, launchd, and systemd launch paths
  • preserve missing provenance as unknown for legacy services and payloads instead of inferring it from the current shell
  • surface the recorded provenance alongside the existing Bun version and revision in management diagnostics
  • keep bunRevision informational and leave the conservative eager-relay capability policy unchanged for canary and otherwise unknown builds
  • retain the bundled-runtime remediation while avoiding the circular “set OPENCODEX_BUN_PATH” instruction when an explicit override is already active
  • document the provenance trust boundary and backward-compatibility behavior

Compatibility and safety

  • persisted provenance accepts only the three documented scalar values
  • legacy artifacts without the field remain supported and are reported as unknown
  • no runtime path or arbitrary environment content is added to durable service metadata
  • this PR changes diagnostics only; it does not automatically trust or enable eager relay for a canary

Validation

  • focused launcher, service, watchdog, runtime, management, and doctor tests: 149 passed, 0 failed on bundled Bun 1.3.14
  • the same 149 tests passed on Bun 1.4.0-canary.1
  • TypeScript typecheck passed on both runtimes
  • privacy scan passed on both runtimes
  • Codex Security diff scan completed with no reportable findings

This incorporates the maintainer-requested corrections from the latest issue comment and is based on current dev.

Summary by CodeRabbit

  • New Features
    • Service diagnostics now show the Bun revision and runtime source: override, bundled, or process.
    • System memory information includes validated Bun runtime provenance when available.
    • Managed services, command shims, and the Windows tray now preserve Bun runtime source details.
  • Bug Fixes
    • Improved diagnostics for legacy runtime data and Windows runtime compatibility scenarios.
    • Invalid or missing runtime source information is safely omitted rather than inferred.
  • Documentation
    • Updated troubleshooting and API documentation to explain Bun runtime provenance.

@github-actions github-actions Bot added the bug Something isn't working label Aug 1, 2026
@coderabbitai

coderabbitai Bot commented Aug 1, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6f7d5a31-79c1-4b71-ac3d-1029661b47d5

📥 Commits

Reviewing files that changed from the base of the PR and between 32bd685 and f6d7d1c.

📒 Files selected for processing (1)
  • tests/codex-shim.test.ts

📝 Walkthrough

Walkthrough

Changes

Bun runtime selection now returns provenance labels. Launchers, services, shims, and the Windows tray pass those labels through OCX_BUN_RUNTIME_SOURCE. The memory API and ocx doctor display validated provenance and Bun revision data. Windows diagnostics distinguish active overrides from legacy payloads.

Bun runtime provenance

Layer / File(s) Summary
Runtime source contract and launcher propagation
src/lib/bun-runtime.ts, bin/ocx.mjs, tests/ocx-launcher-source.test.ts
Bun resolution returns the executable path and source. The launcher passes the source to Bun.
Service runtime environment propagation
src/service.ts, src/lib/winsw.ts, tests/service.test.ts, tests/winsw.test.ts
launchd, Windows, systemd, and WinSW service definitions embed the durable Bun runtime source.
Shim and tray runtime propagation
src/codex/shim.ts, src/tray/windows.ts, tests/codex-shim.test.ts, tests/windows-tray-runtime-source.test.ts
Platform shims and detached Windows tray hosts preserve runtime-source metadata.
Memory API and doctor diagnostics
src/server/management/system-routes.ts, src/cli/doctor.ts, tests/doctor.test.ts, tests/memory-watchdog.test.ts, structure/05_gui-and-management-api.md, docs-site/src/content/docs/troubleshooting/windows-memory.md
The memory endpoint returns validated provenance. Doctor displays the source and revision and changes Windows auto-known-bad guidance for active overrides and legacy payloads.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Launcher
  participant DurableRuntime
  participant ServiceOrShim
  participant BunProcess
  participant MemoryAPI
  participant Doctor
  Launcher->>DurableRuntime: resolve path and runtime source
  DurableRuntime-->>ServiceOrShim: return durable runtime metadata
  ServiceOrShim->>BunProcess: set OCX_BUN_RUNTIME_SOURCE
  BunProcess->>MemoryAPI: report bunRevision and runtime source
  MemoryAPI->>Doctor: return validated diagnostics
  Doctor->>Doctor: render source-aware guidance
Loading

Possibly related PRs

Suggested reviewers: ingwannu, lidge-jun, wibias

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: reporting Bun runtime provenance in doctor diagnostics.
Linked Issues check ✅ Passed The changes satisfy #848 by distinguishing bundled and active override runtimes, preserving conservative policy, reporting bunRevision, and adding regression coverage.
Out of Scope Changes check ✅ Passed The launcher, service, shim, tray, documentation, and test changes directly support runtime provenance propagation and #848 diagnostics.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
src/lib/winsw.ts (1)

77-99: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Resolve the Bun runtime once for WinSW XML generation. buildWinswXml() emits entry.bun but writes OCX_BUN_RUNTIME_SOURCE from a separate durableBunRuntime() call (src/lib/winsw.ts:76-77,99). defaultWinswEntry() also resolves the runtime independently through durableBunPath() (src/lib/winsw.ts:375-376). If the entries differ, WinSW launches one Bun executable while the service reports another runtime source, which can produce incorrect ocx doctor guidance. Pass one resolved DurableBunRuntime object through entry construction and XML generation.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/winsw.ts` around lines 77 - 99, Update buildWinswXml(),
defaultWinswEntry(), and their call path to resolve durableBunRuntime() once and
pass the same DurableBunRuntime object through entry construction and XML
generation. Use that shared object for both entry.bun and the
OCX_BUN_RUNTIME_SOURCE environment value, replacing independent durableBunPath()
and durableBunRuntime() resolutions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/lib/winsw.ts`:
- Around line 77-99: Update buildWinswXml(), defaultWinswEntry(), and their call
path to resolve durableBunRuntime() once and pass the same DurableBunRuntime
object through entry construction and XML generation. Use that shared object for
both entry.bun and the OCX_BUN_RUNTIME_SOURCE environment value, replacing
independent durableBunPath() and durableBunRuntime() resolutions.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f87a7015-0728-44c9-b890-60dcbae648a0

📥 Commits

Reviewing files that changed from the base of the PR and between aae9426 and 3bf4c76.

📒 Files selected for processing (12)
  • bin/ocx.mjs
  • src/cli/doctor.ts
  • src/lib/bun-runtime.ts
  • src/lib/winsw.ts
  • src/server/management/system-routes.ts
  • src/service.ts
  • structure/05_gui-and-management-api.md
  • tests/doctor.test.ts
  • tests/memory-watchdog.test.ts
  • tests/ocx-launcher-source.test.ts
  • tests/service.test.ts
  • tests/winsw.test.ts

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3bf4c76281

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/lib/bun-runtime.ts
Comment thread structure/05_gui-and-management-api.md
Comment thread src/cli/doctor.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
tests/codex-shim.test.ts (1)

61-72: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add explicit override and bundled provenance cases.

These assertions verify only the default "process" value. A builder that ignores a supplied non-default bunRuntimeSource would still pass.

Call each Unix, CMD, and PowerShell builder with explicit "override" and "bundled" values. Assert the generated environment assignment for each platform syntax.

As per path instructions, “A behavior change in src/ should come with a focused regression test near the existing tests for that subsystem.” The PR objectives also require bundled and override regression coverage.

Also applies to: 183-183

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/codex-shim.test.ts` around lines 61 - 72, Extend the existing Unix,
Windows CMD, and PowerShell shim tests for their respective builder functions to
call explicit "override" and "bundled" bunRuntimeSource values, asserting each
generated script contains the platform-appropriate OCX_BUN_RUNTIME_SOURCE
assignment. Keep the existing default "process" assertions and place focused
coverage alongside the current codex shim tests.

Source: Path instructions

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@tests/codex-shim.test.ts`:
- Around line 61-72: Extend the existing Unix, Windows CMD, and PowerShell shim
tests for their respective builder functions to call explicit "override" and
"bundled" bunRuntimeSource values, asserting each generated script contains the
platform-appropriate OCX_BUN_RUNTIME_SOURCE assignment. Keep the existing
default "process" assertions and place focused coverage alongside the current
codex shim tests.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cb3c37b0-030f-4181-9e77-df72e8ead7ee

📥 Commits

Reviewing files that changed from the base of the PR and between 3bf4c76 and 32bd685.

📒 Files selected for processing (9)
  • docs-site/src/content/docs/troubleshooting/windows-memory.md
  • src/cli/doctor.ts
  • src/codex/shim.ts
  • src/lib/winsw.ts
  • src/tray/windows.ts
  • tests/codex-shim.test.ts
  • tests/doctor.test.ts
  • tests/windows-tray-runtime-source.test.ts
  • tests/winsw.test.ts

luvs01 commented Aug 1, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up review fixes are in 32bd685.

  • Propagated Bun runtime provenance through generated Codex shims and the Windows tray.
  • Resolved the WinSW executable and provenance from one durableBunRuntime() result.
  • Preserved eager-relay guidance for active overrides.
  • Added public Windows runtime-source documentation.

Local validation: 177 focused tests on Bun 1.4.0-canary.1 and bundled Bun 1.3.14, typecheck and privacy checks on both runtimes, plus a successful frozen docs install and production build.

luvs01 commented Aug 1, 2026

Copy link
Copy Markdown
Contributor Author

The follow-up test request is addressed in f6d7d1cf. Unix, Windows CMD, and PowerShell shim builders are now exercised with explicit override and bundled runtime sources, while the existing default process coverage remains intact.

Validation: tests/codex-shim.test.ts passes 34/34 on Bun 1.4.0-canary.1 and bundled Bun 1.3.14, and root typecheck passes.

luvs01 commented Aug 1, 2026

Copy link
Copy Markdown
Contributor Author

CI note for head f6d7d1cf: the macOS full-test job did not report a test assertion failure. After the suite reached its final test groups, Bun 1.3.14 crashed with a segmentation fault (Trace/BPT trap, exit 133) and emitted this runtime report: https://bun.report/1.3.14/Mt10d9b296izBukooC_upjokD27h3e+hr0iB+g30iB2ztjiBu21nnB__A2DR

The focused shim suite remains green on both Bun 1.4.0-canary.1 and bundled Bun 1.3.14 (34/34 on each), and typecheck passes. This appears to be a Bun runtime failure rather than a PR assertion regression; a repository maintainer can rerun the failed macOS job if desired.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant