fix(server): run the background service through a Homebrew Node path that survives upgrades

[Mnigos]

t3 service install / service update record process.execPath as the service's Node. Node reports the realpath, so a Homebrew install becomes /opt/homebrew/Cellar/node/<version>/bin/node, a path that brew upgrade node deletes. The running service survives on the old inode, but the next launchd or systemd start fails even though node still works through the Homebrew prefix. The launcher also spawns managed runtimes through process.execPath, so a live handoff after a keg removal breaks the same way.

Following the triage on #11054:

• The service plan now prefers the formula's opt link (<prefix>/opt/<formula>/bin/node) whenever execPath sits in a Homebrew keg and that link exists. It stays absolute, follows the current keg across upgrades, and covers versioned formulae such as node@22 and Linuxbrew prefixes. Any other execPath is used as before. The same path goes into the unit's PATH entry and into the runtime validation run.
• The launcher spawns runtimes through the Node path it was started with (process.argv0) when that is absolute, and falls back to process.execPath otherwise.

homebrewOwnershipFromCommandPath from provider maintenance already parses keg layouts, so the keg detection is shared.

Verification

• bootService.test.ts: keg to opt-link mapping (plain, versioned and Linuxbrew formulae, non-keg paths), and a macOS install that writes the keg path while the opt link is missing and the opt link once it exists, with no Cellar left in the plist.
• serviceLauncher.test.ts: absolute argv0 wins, a bare node falls back to execPath.
• vp test run on both files (43 tests), server typecheck and lint on the touched files are clean.

Fixes #11054. Implemented with Claude Code (Claude Fable 5.1).

Summary by CodeRabbit

• Bug Fixes
  • Improved service reliability after Node.js updates by using stable Homebrew Node paths.
  • Ensured launched runtimes continue using the configured service path instead of an outdated resolved path.
  • Improved macOS launch-agent setup when stable Node paths are available.

[macroscopeapp]

Approvability

Verdict: Approved at c5768fd

Macroscope's review found this PR approvable — This is a narrow, well-tested compatibility fix that preserves existing behavior outside Homebrew keg installations while making service and child-process Node paths survive upgrades. It introduces no schema, security-sensitive, deployment, product-default, or static-analysis configuration changes.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: b8f3dde4-f364-4481-b4de-46f6e62d9fea

📥 Commits

Reviewing files that changed from the base of the PR and between d29c56a and c5768fd.

📒 Files selected for processing (4)

• apps/server/src/cloud/bootService.test.ts
• apps/server/src/cloud/bootService.ts
• apps/server/src/serviceLauncher.test.ts
• apps/server/src/serviceLauncher.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The boot service now resolves Homebrew Node executables to stable opt paths when available. The service launcher preserves an absolute startup path when spawning managed runtimes. Tests cover path resolution, launchd installation, and runtime spawning.

Changes

Homebrew Node path durability

Layer / File(s)	Summary
Durable Homebrew path resolution apps/server/src/cloud/bootService.ts, apps/server/src/cloud/bootService.test.ts	durableHomebrewNodePath maps Homebrew Cellar executables to stable opt paths. Tests cover macOS, Linuxbrew, and non-Homebrew paths.
Service path integration apps/server/src/cloud/bootService.ts, apps/server/src/cloud/bootService.test.ts	The boot service uses an existing durable path for launchd PATH, ExecStart, and pinned-runtime validation. Installation tests cover the opt link transition.
Managed runtime launch path apps/server/src/serviceLauncher.ts, apps/server/src/serviceLauncher.test.ts	launcherNodePath preserves an absolute argv0, and #startChild uses it when spawning managed runtimes. Tests cover absolute and relative paths.

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

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Homebrew
  participant BootService
  participant LaunchAgent
  participant ServiceLauncher
  participant ManagedRuntime
  Homebrew->>BootService: provide host.execPath
  BootService->>Homebrew: resolve stable opt path
  Homebrew-->>BootService: return existing durable nodePath
  BootService->>LaunchAgent: write nodePath to service definition
  LaunchAgent->>ServiceLauncher: start with absolute node path
  ServiceLauncher->>ManagedRuntime: spawn using launcherNodePath()

Loading

Suggested reviewers: t3dotgg, juliusmarminge

Merge Risk: ⚪ Minimal · up to c5768

The service now survives Homebrew Node upgrades by preferring stable opt links while retaining safe fallbacks, and managed runtimes preserve a durable startup path. The covered fallback and upgrade scenarios show no current merge-blocking risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: using an upgrade-stable Homebrew Node path for the background service.
Description check	✅ Passed	The description explains the problem, implementation, verification, and linked issue. It does not use the template headings or checklist, but it provides the required information and remains focused.
Linked Issues check	✅ Passed	The changes address issue #11054 by using the Homebrew opt link for service definitions, preserving launchability after keg upgrades, and using the launcher’s absolute argv0 for managed-runtime handof…
Out of Scope Changes check	✅ Passed	The changes are limited to Homebrew Node path resolution, service configuration, launcher spawning, and related tests. No unrelated code changes are identified.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[Mnigos]

Note

🤖 Claude Fable 5.1 on behalf of Mnigos

Closing: since #11510 the background service runs the self-contained t3 executable from the release archive, so the host Node path this PR pinned is no longer used.