pitchfork boot enable writes version-specific binary paths; brew/mise upgrades break the launchd registration

[sahidvelji]

Sharing a paper cut from setting up pitchfork on macOS, where the resulting registration is fragile across package-manager upgrades.

pitchfork boot enable generates ~/Library/LaunchAgents/pitchfork.plist with the resolved binary path:

<string>/opt/homebrew/Cellar/pitchfork/2.14.0/bin/pitchfork</string>

That path is version-specific. The next brew upgrade pitchfork installs (e.g.) 2.15.0 at a new Cellar path; brew cleanup eventually removes 2.14.0/. After that, launchd tries to spawn the missing binary and the supervisor enters the launchd penalty box with EX_CONFIG (78). Symptoms include:

• launchctl kickstart -k gui/$UID/pitchfork hangs indefinitely
• pitchfork list returns "supervisor not running" (despite RunAtLoad=true)
• pitchfork logs pitchfork is empty (the supervisor never gets to log anything)
• launchctl print gui/$UID/pitchfork shows last exit code = 78: EX_CONFIG and the old Cellar path in arguments, even after the plist file on disk has been updated

To recover I had to walk through:

launchctl bootout gui/$UID/pitchfork
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/pitchfork.plist

…after manually rewriting the plist (or running pitchfork boot disable && pitchfork boot enable).

A second compounding factor I hit: pitchfork boot disable && pitchfork boot enable rewrites the plist file on disk but does not refresh launchd's in-memory cached args. Even after a successful disable+enable, launchd kept trying to launch the old Cellar path until I manually bootout+bootstrap. From a user's perspective, the recommended disable && enable recovery doesn't actually recover.

What works in each ecosystem

Brew has a stable indirection: /opt/homebrew/bin/pitchfork is a symlink that brew rewrites on upgrade. If the plist pointed at the symlink, brew upgrade would never invalidate the launchd registration.

Mise has ~/.local/share/mise/installs/pitchfork/<version>/pitchfork (version-specific) and ~/.local/share/mise/shims/pitchfork as a "stable" path. But the shim is a shell script that calls mise exec, which needs MISE_* env and full PATH that launchd's minimal startup environment doesn't provide. So the shim doesn't actually work as a launchd target.

Possible directions

1. pitchfork boot enable should prefer a stable path when one is available. On macOS, check whether which pitchfork returns a path under /opt/homebrew/bin/ or /usr/local/bin/; if so, write that. Otherwise fall back to the current resolved-path behavior.
2. pitchfork boot enable (and boot disable) should also do launchctl bootout + bootstrap so the on-disk plist change actually propagates to launchd.
3. Document the upgrade dance. If neither of the above makes sense, the boot enable docs could note that brew upgrade pitchfork (or any version bump that changes the install path) requires regenerating the plist + bouncing launchd.

#1 + #2 together would mean brew users never have to think about this again — brew upgrade pitchfork && launchctl kickstart -k gui/$UID/pitchfork would suffice. Mise users would still need to regenerate manually because there's no stable path that works under launchd.

[Guria]

Good catch — reproducing this on Linux/systemd too, and I think it's broader than the macOS/launchd framing suggests.

Repro (Linux, mise, systemd user unit, pitchfork 2.19.0):

pitchfork boot enable writes a unit that pins the fully-resolved, version-specific path:

# ~/.config/systemd/user/pitchfork.service
[Service]
ExecStart=/home/exedev/.local/share/mise/installs/aqua-jdx-pitchfork/2.19.0/pitchfork supervisor run --boot

mise puts the install dir on PATH via its latest symlink (…/aqua-jdx-pitchfork/latest/pitchfork → …/2.19.0/pitchfork). After an upgrade latest repoints to the new version, but the unit keeps ExecStart on the old path — so the supervisor silently boots the previous version, and once that old install is pruned the unit dangles. Same shape as the brew/Cellar case, no launchd involved.

Root cause is in src/env.rs:

pub static PITCHFORK_BIN: Lazy<PathBuf> = Lazy::new(|| {
    current_exe().and_then(|p| p.canonicalize()) …
});

fed to auto_launcher as app_path in src/boot_manager.rs.

One nuance worth flagging before a fix is chosen: on Linux current_exe() reads /proc/self/exe, which the kernel already resolves to the real file — so the explicit .canonicalize() is redundant there, and simply removing it will not un-pin the path on Linux. On macOS the resolution path differs, so the two platforms aren't symmetric: "remove .canonicalize()" is not a complete fix.

Per-platform refresh (verified on systemd): boot disable deletes the unit file entirely, and boot enable regenerates it fresh from the current PITCHFORK_BIN — so on systemd your disable && enable dance does refresh the path (no launchd-style sticky arg cache). The trap on Linux is different from macOS: a bare boot enable on an already-enabled system is a true no-op — BootEnable::run in src/cli/boot.rs early-returns "already enabled" without re-checking or rewriting the pinned path (confirmed: identical file sha256 + mtime before/after). So the user gets "already enabled" while the unit silently points at a stale or deleted binary. You have to know to run the disable/enable dance; nothing in the output hints at it.

On the mise-shim point: that concern is real on macOS, but on Linux with the versioned install on PATH (not the shim) the failure is the clean versioned-path case above, not the shim-needs-env case — so a stable symlink would work there.

Of the three directions, a detect-and-re-register variant of your option 2 looks lowest-risk cross-platform: when already enabled, compare the registered ExecStart against the current PITCHFORK_BIN and re-register on mismatch, with the bootout/bootstrap step gated to macOS. Happy to open a PR once a direction's agreed.

[gaojunran]

sorry that I missed this discussion. it's a real ux gap and I think we should check whether bin path are the same each time sup start (not the time you run boot enable, or you need to remember to do it every time) I'll impl it!