stack/agents/sage/work/queue-68/build.md

Row 68 (#1561): the bus host runs an explicit Claude Code binary, round 1

Sage, 2026-10-11. Brief: docs/plans/2026-10-11_bus-claude-binary.md, "Bus host runs an explicit Claude Code binary" (e1b90ed6). Mos's Q18 ask: the bus finds /usr/bin/claude 2.1.259 (pacman claude-code), which refuses claude-opus-5-5. Jason runs the native ~/.local/bin/claude (2.1.296). Filbert and Dewey review. Sage commits after the gate; nothing is committed, staged or pushed yet.

Base a86de1f1. build.patch applies there with git apply --index; candidate-manifest.sha256 pins all 13 files after the patch.

Design

The binary is named, not found. MOSAIC_CLAUDE_BIN is an absolute path:

1. The unit sets it. scripts/bus-service.sh render|install --claude PATH; without --claude, command -v claude in the installing shell. The path is kept as given, not resolved: ~/.local/bin/claude is a symlink the native installer moves to each new version, so the unit follows updates without a reinstall.
2. ENV_ALLOW passes it to the session. It's a path, not a credential.
3. adapters/claude/adapter.sh runs $MOSAIC_CLAUDE_BIN when it is set and nonempty, else claude as before.
4. claudeVersion, which fills the manifest's claudeVersion, asks the same binary, so the manifest records what actually ran.

Rejected: prepending ~/.local/bin to the unit's PATH. Every binary there (pip and npm installs, personal scripts) would then shadow the system's, for the host and for every session. Also rejected: a field in the business file or system config. Which binary runs is a property of the host install, like node's directory, which the unit already carries.

Refusals

Where	Input	Result
bus-service.sh	--claude relative	exit 1, "must be absolute", nothing written
bus-service.sh	not an executable file, or missing	exit 1, "not an executable file"
bus-service.sh	a character outside A-Za-z0-9/._+- (%, space, ...)	exit 1, "cannot carry". systemd expands % and splits Environment= on spaces.
bus-service.sh	no --claude and no claude on PATH	exit 0; the unit gets # MOSAIC_CLAUDE_BIN unset: ... and stderr says so. A pi-only host installs as before.
bus-service.sh	uninstall --claude, render --dir	exit 4
adapter	MOSAIC_CLAUDE_BIN relative	exit 2 before claude runs
adapter	not an executable file, or missing	exit 2 before claude runs
adapter	unset or empty	claude from PATH, as today

install now renders into a variable before mktemp, so a refused pin leaves no temp file in the unit directory. Calling render inside || { ... } would have switched set -e off in the function and written a unit with an empty line. claude_line failing is handled with an explicit || exit 1.

install prints claude: <path> (<--version>) or the unset line. status adds -p Environment to its systemctl show, which shows PATH and the pin. The unit holds no secret.

Files

• packages/cli/systemd/mosaic-bus.service.in: a comment and an @CLAUDE_ENV@ line after Environment=PATH=. The header names "the claude line below" rather than the token, because header tokens render into the comment (as @REPO@ and @PATH@ already do) and the claude substitution only matches its own line.
• scripts/bus-service.sh: claude_line, --claude for render and install, the install print, status shows Environment, usage.
• adapters/claude/adapter.sh: the CLAUDE variable and its checks.
• packages/seat/src/session.mjs: MOSAIC_CLAUDE_BIN in ENV_ALLOW.
• packages/cli/src/launcher.mjs: claudeVersion asks env.MOSAIC_CLAUDE_BIN || "claude".
• Docs: packages/cli/README.md ("Unit" and the manifest note), adapters/README.md (adapter list and variable table), packages/seat/README.md (sessionEnv), docs/TOOLS.md (usage line and one paragraph). The brief didn't list docs/TOOLS.md. I added it because its usage line would otherwise be wrong, and it is my file.
• Tests:
  • host.test.mjs, new test "bus-service.sh pins the claude binary...":
    • the pin found on PATH, from --claude, and through a symlink kept unresolved
    • five refusals with exit 1 and empty stdout
    • install printing the pin and the stand-in's version
    • a refused install writing nothing
    • uninstall --claude and render --dir exiting 4
    • no claude anywhere: PATH is a directory holding only node, dirname and sed, and the unit gets the comment line
  • The existing render test also asserts no @CLAUDE_ENV@.
  • launcher.test.mjs: claudeVersion with the pin, from PATH, and with none (null).
  • session.test.mjs: sessionEnv passes MOSAIC_CLAUDE_BIN.
  • claude-session.test.mjs, new test:
    • the pin wins over a claude on PATH
    • unset or empty uses PATH
    • relative, missing and non-executable pins exit 2 without running anything

Each new test fails against base: unpinned claudeVersion returns the PATH stand-in's 1.0.0, the base adapter runs the PATH stand-in, base sessionEnv drops the variable, and base render rejects --claude with exit 4.

Gate (my run on the candidate)

Suite	Result
packages/cli	85/0
packages/seat	27/0
packages/harness	57/0, nothing skipped. The live claude tests ran against the 2.1.296 on my PATH.
scripts/test-*.sh	all nine exit 0: auth 15, conductor 17, config 24, discord 66, extension-package 18, foundation 44, queue 27, release 14, task 98 (Docker on)

Logs: /tmp/sage-r68-out/ (not kept).

After landing (not in the candidate)

1. scripts/bus-service.sh install from my shell, which resolves /home/jwoltje/.local/bin/claude. install prints the pin and its version.
2. The opus probe: the adapter's flags with MOSAIC_CLAUDE_BIN and PATH taken from the installed unit, as decision 89's probe did.
3. Report the path and version to Mos.

The running host (MainPID 1242258) keeps its old environment until it restarts. That restart is the Q18 --pm start, which waits for Mos's watched window. Nothing here restarts it.

Questions for reviewers

• Is keeping the symlink, not its target, right? The other choice pins an exact version and needs a reinstall per update. I chose to follow updates because that's what Jason's own sessions do.
• With no claude found, install succeeds with a comment rather than refusing, because a pi-only business needs no claude. Is that the right default, or should install refuse unless the business's roles are all pi?