fix: runner PATH for Homebrew tools

[Peyton-Spencer]

Summary

Fixes MacRunner-launched GitHub Actions runners missing Homebrew tools such as npm when the MacRunner app is launched by LaunchServices or as a login item.

Root Cause

The MacRunner GUI process inherits launchd's limited PATH, e.g. /usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin. That environment is then passed into runner startup/configuration, and the Actions runner snapshots it into .path. On Apple Silicon Macs, Homebrew installs Node/npm under /opt/homebrew/bin, so actions that shell out to npm fail even though npm is available in the user's interactive shell.

Changes

• Add RunnerEnvironment to normalize runner PATH values with standard Homebrew locations.
• Use the normalized environment when configuring and launching non-isolated runners.
• Refresh the runner .path snapshot on start so existing runners recover after restart.
• Add unit coverage for PATH normalization, headless GUI stripping, GUI preservation, and .path writing.

Verification

• git diff --check
• swiftc -typecheck -target arm64-apple-macosx15.0 Sources/Services/RunnerEnvironment.swift
• swift test was attempted, but the current checkout fails on pre-existing issues unrelated to this change: SwiftUI #Preview macro plugin missing for MenuBarView.swift and Swift 6 actor-send errors in RunnerManager.swift container service calls.

Summary by CodeRabbit

• New Features

  • Improved process execution environment configuration with enhanced PATH normalization and deduplication
  • Better support for CI and headless execution modes with proper handling of GUI-related environment variables
  • Refined environment setup for runner processes ensuring consistent and optimized execution

• Tests

  • Added comprehensive test coverage for environment configuration, PATH management, and headless mode scenarios

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 79de00ae-e319-4e9f-9d9a-67639d5a3ba8

📥 Commits

Reviewing files that changed from the base of the PR and between fd47690 and c8bbcb5.

📒 Files selected for processing (4)

• Sources/Services/ProcessManager.swift
• Sources/Services/RunnerEnvironment.swift
• Sources/Services/RunnerInstaller.swift
• Tests/MacRunnerTests/MacRunnerTests.swift

---

📝 Walkthrough

Walkthrough

Introduces RunnerEnvironment, a new Swift enum in Sources/Services/ that centralizes PATH normalization (Homebrew-first deduplication), headless/GUI environment sanitization, and atomic .path snapshot file writes. ProcessManager.startProcess and RunnerInstaller.configureRunner are updated to use these utilities for .none/.container isolation, and four XCTest cases verify the new behavior.

Changes

RunnerEnvironment utility and integration

Layer / File(s)	Summary
RunnerEnvironment core: constants, env builder, PATH normalizer, snapshot writer Sources/Services/RunnerEnvironment.swift	Defines RunnerEnvironment enum with preferred PATH directories, a fallback PATH, environment(from:enableGUI:) that normalizes PATH and conditionally strips GUI-related vars while setting CI/HEADLESS, normalizedPath(_:) for dedup-ordered PATH construction, and writePathSnapshot(in:environment:) for atomic UTF-8 .path file writes.
ProcessManager and RunnerInstaller wiring Sources/Services/ProcessManager.swift, Sources/Services/RunnerInstaller.swift	ProcessManager.startProcess replaces 13 lines of inline env mutation with RunnerEnvironment.environment(enableGUI:) + writePathSnapshot. RunnerInstaller.configureRunner assigns the sanitized environment before running config.sh and calls writePathSnapshot after successful configuration for .none/.container isolation.
XCTest coverage Tests/MacRunnerTests/MacRunnerTests.swift	Adds four test cases covering normalizedPath Homebrew prepending and deduplication, headless env variable removal and flag setting, GUI-enabled variable preservation, and writePathSnapshot file content verification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• omniaura/mac-runner#13: Modifies RunnerInstaller.configureRunner to handle .container alongside .none, the same branch this PR extends with RunnerEnvironment env setup and PATH snapshot writing.
• omniaura/mac-runner#14: Touches ProcessManager.startProcess process environment configuration for .none/.container, directly overlapping with this PR's replacement of that inline logic.
• omniaura/mac-runner#28: Changes headless/GUI environment handling in ProcessManager.startProcess by removing GUI vars and setting CI/HEADLESS, which this PR reimplements via RunnerEnvironment.

Poem

🐇 Hoppity-hop through the PATH I go,
Deduplicating entries, high and low,
Homebrew first, then the rest in line,
.path snapshot written, atomic and fine.
No GUI vars shall clutter my run—
CI=true, HEADLESS=true, the work is done! 🥕

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-runner-homebrew-path

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🎉 This PR is included in version 1.17.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀