fix(ops): generated systemd/launchd units bake a PATH so bridges find user tools

[schubydoo]

Summary

clauster install-service <kind> generated units that set only CLAUSTER_CONFIG, never a PATH. Under systemd a service inherits a minimal default PATH (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin) — it does not source the operator's login shell. Clauster propagates its own environment to every spawned bridge via procutil.child_env(), so every claude bridge inherited that minimal PATH and couldn't resolve user-local tools (uv in ~/.local/bin, nvm node/npx, cargo, Go tools). The bridge still ran, but an agent inside it couldn't invoke uv/ruff/pytest/node — a confusing, hard-to-diagnose gap.

Change

• render_service_unit() now bakes a PATH into the systemd unit (Environment=PATH=…) and the launchd plist (a PATH key in EnvironmentVariables): the run-as user's ~/.local/bin first, then the standard system bin dirs.
• New _home_for_user() / _service_path() helpers. systemd's %h specifier resolves to /root for a system unit regardless of User=, so it can't reach the operator's home — the home is resolved at render time via the passwd db, falling back to a platform-aware /home (or /Users on macOS) when the user isn't present on the rendering host yet.
• Each renderer carries a comment pointing operators at claude.path_append / claude.env (from feat(config): allow extending the bridge subprocess PATH/env via clauster.yml #504) for shell-managed toolchains (nvm/pyenv/cargo/go) that a static dir can't cover.
• windows/nssm left as-is — the minimal-PATH problem is POSIX-specific; acceptance covers systemd + launchd.

Tests

• Assert the PATH provision + the operator-knob comment in the rendered systemd and launchd units.
• Cover both _home_for_user branches: passwd-db hit (resolves the real home) and the lookup-miss fallback (Linux /home, macOS /Users).

Reviewed against the project's safety invariants with clauster-reviewer: no injection regression (the user value already lands raw on the User= directive; launchd is XML-escaped), launchd plist stays valid XML, PATH is purely additive.

Closes #590

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR fixes a real operational gap: clauster install-service generated units with no PATH, so every bridge the service spawned inherited systemd's minimal default and couldn't find user-local tools (uv, ruff, pytest, etc.) even though they work fine in an interactive shell. The fix bakes a proper PATH into both the systemd Environment= directive (double-quoted to handle spaces in home dirs) and the launchd EnvironmentVariables dict, resolved from the run-as user's passwd-db entry at render time.

• Two new helpers — _home_for_user() and _service_path() — do the home resolution with a clean platform-aware fallback for users not yet present on the rendering host.
• Tests cover: passwd-db hit, lookup-miss fallback (Linux/macOS), space-in-home quoting, and presence of the operator comment pointing at claude.path_append/claude.env.
• Docs updated in both configuration.md and installation.md to explain the static-vs-shell-managed toolchain boundary.

Confidence Score: 5/5

Safe to merge — the change is purely additive, writing an extra ENV directive into generated unit files, with no effect on already-deployed units.

The home-dir resolution has a well-tested fallback path, the systemd value is correctly double-quoted, the launchd value goes through XML escaping, and new tests cover all four branches. No existing behaviour is removed or altered.

No files require special attention.

Important Files Changed

Filename	Overview
src/clauster/ops.py	Adds _home_for_user, _service_path, and wires baked PATH into both systemd and launchd renderers; systemd value is double-quoted, launchd value is XML-escaped — both are correct.
tests/test_ops.py	Four new test cases cover the passwd hit, platform-aware fallback (pinned via monkeypatch), and space-in-home quoting; all assertions are substring-based so they survive varying CI host home directories.
docs/installation.md	Adds the baked PATH line to the example systemd unit and an explanatory callout note directing operators to claude.path_append for shell-managed toolchains.
docs/configuration.md	Refines the path_append documentation to reflect that ~/.local/bin is now baked in by the generated unit, so path_append is for shell-managed runtimes only.
.changeset/590-install-service-unit-path.md	Patch-level changeset entry correctly describing the fix.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["clauster install-service"] --> B["render_service_unit(kind, user)"]
    B --> C["_service_path(user)"]
    C --> D["_home_for_user(user)"]
    D --> E{user provided?}
    E -- yes --> F["pwd.getpwnam(user).pw_dir"]
    F -- success --> G["real home dir"]
    F -- "KeyError / OSError" --> H{sys.platform?}
    H -- darwin --> I["/Users/user"]
    H -- other --> J["/home/user"]
    E -- no --> K["os.path.expanduser ~"]
    G & I & J & K --> L["home/.local/bin + system dirs"]
    L --> M{kind?}
    M -- systemd --> N["Environment=PATH=... double-quoted"]
    M -- launchd --> O["xml-escaped PATH in EnvironmentVariables"]
    N --> P["Bridges inherit PATH via child_env"]
    O --> P

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["clauster install-service"] --> B["render_service_unit(kind, user)"]
    B --> C["_service_path(user)"]
    C --> D["_home_for_user(user)"]
    D --> E{user provided?}
    E -- yes --> F["pwd.getpwnam(user).pw_dir"]
    F -- success --> G["real home dir"]
    F -- "KeyError / OSError" --> H{sys.platform?}
    H -- darwin --> I["/Users/user"]
    H -- other --> J["/home/user"]
    E -- no --> K["os.path.expanduser ~"]
    G & I & J & K --> L["home/.local/bin + system dirs"]
    L --> M{kind?}
    M -- systemd --> N["Environment=PATH=... double-quoted"]
    M -- launchd --> O["xml-escaped PATH in EnvironmentVariables"]
    N --> P["Bridges inherit PATH via child_env"]
    O --> P

Loading

_{Reviews (4): Last reviewed commit: "docs: document the baked unit PATH and r..." | Re-trigger Greptile}