Module toolchain_path 

GUI-launch PATH enrichment.

When AgentMux launches from Finder / Dock / a mounted DMG as a .app, it inherits launchd’s stripped PATH (/usr/bin:/bin:/usr/sbin:/sbin). nvm- and Homebrew-installed node / npm / git live in the user’s login-shell PATH, which a GUI launch never sees — so the CLI installer (Command::new("npm")) dies with npm: command not found, and spawned agent CLIs can’t find their interpreter either.

resolve_login_path reconstructs a usable PATH from the user’s login shell ($SHELL -lic 'printf … "$PATH"', with a hard timeout) unioned with well-known toolchain directories. It is purely additive — inherited system directories are never dropped — and a no-op on Windows (whose GUI apps inherit a usable PATH).

See docs/specs/SPEC_TOOLCHAIN_MANAGER_2026-06-15.md §3.

Structs

EnrichOutcome

What enrich_current_process_path_cached did.

EnrichedPath

The enriched PATH plus a record of how it was derived.

Enums

PathSource

How the effective PATH was produced — surfaced in logs and (later) the Toolchain modal so PATH problems are diagnosable rather than mysterious.

Functions

enrich_current_process_path

Enrich the current process’ PATH in place, but only when it looks like the stripped launchd default. Idempotent and cheap when the PATH is already healthy (no shell spawn). Returns the source used. Intended for the srv’s direct-launch fallback; the host enriches the srv’s PATH unconditionally when it spawns it (it knows it is the GUI entry point).

enrich_current_process_path_cached

Like enrich_current_process_path, but reuses the login-shell PATH captured by an earlier launch when nothing it depends on has changed: the shell, the inherited PATH, and the size and mtime of every shell startup file and /etc/paths{,.d}. On a hit no shell is spawned, which takes the 1-2 s an interactive login shell costs (oh-my-zsh, conda, nvm) off the boot path. A miss spawns the shell as before and writes the cache.

looks_like_launchd_default

True when the current PATH is the stripped launchd default (every entry is one of /usr/bin, /bin, /usr/sbin, /sbin) — i.e. a GUI launch that never saw the user’s shell. Used by the srv to decide whether the cheap guard should pay for a login-shell spawn on a direct launch.

refresh_login_path_cache

Re-run the login shell and rewrite the cache that enrich_current_process_path_cached read. inherited is the PATH the process started with (before enrichment), so the fingerprint matches the next launch’s. Returns the freshly captured enriched PATH when it differs from current_enriched, None when nothing changed or the shell couldn’t be read. Never touches this process’ environment.

resolve_login_path

Build a usable PATH for spawning the toolchain (node/npm/git/docker and the provider CLIs). Additive over the inherited PATH; never removes an inherited entry. On Windows this returns the inherited PATH unchanged.