stack/docs/plans/2026-10-11_bus-claude-binary.md

Bus host: an explicit Claude Code binary (2026-10-11)

Status: written by Sage, lead, for Mos's Q18 ask (measured 20:42-20:43Z). It follows docs/plans/BRIEF-TEMPLATE.md and amends lead decision 89, whose remedy (a package upgrade by Jason) Mos withdrew. One row.

Bus host runs an explicit Claude Code binary

Problem

[email protected] sets Environment=PATH=/usr/local/bin:/usr/bin:/bin plus node's directory (scripts/bus-service.sh render). Claude Code sessions and the manifest's claude --version find claude on that PATH, which on Jason's host is /usr/bin/claude 2.1.259 from the pacman package claude-code. Jason doesn't use that build: his Claude Code is the native install, ~/.local/bin/claude, a symlink into ~/.local/share/claude/versions/ (2.1.296 on 2026-10-11), in both distroboxes and in the host's T3 sessions (Mos, 20:42Z). 2.1.259 refuses claude-opus-5-5 ("version 2.1.280 or newer is required"); 2.1.296 runs it with the adapter's full flag set (decision 89). So a managed Claude Code session under the unit can't run the model the business file names.

Putting ~/.local/bin on the unit's PATH would fix it, but every binary there would then shadow the system's for the host and every session. The binary should be named, not found.

Owner and reviewer

Owner: Sage. Reviewers: Filbert and Dewey.

Files owned

• packages/cli/systemd/mosaic-bus.service.in, scripts/bus-service.sh
• packages/cli/src/launcher.mjs (claudeVersion only)
• packages/seat/src/session.mjs (ENV_ALLOW only)
• adapters/claude/adapter.sh, adapters/README.md
• packages/cli/README.md, packages/seat/README.md
• packages/cli/tests/host.test.mjs, packages/cli/tests/launcher.test.mjs, packages/seat/tests/session.test.mjs, packages/harness/tests/claude-session.test.mjs

What ships

• MOSAIC_CLAUDE_BIN, an absolute path to the claude the host runs.
  • The adapter runs ${MOSAIC_CLAUDE_BIN:-claude}. If the variable is set but isn't an absolute path to an executable file, it exits 2 before anything runs.
  • claudeVersion (the manifest's claudeVersion) asks the same binary.
  • ENV_ALLOW passes it to sessions. It is a path, not a credential.
  • Unset, everything behaves as today: claude from PATH.
• The unit sets it. render and install take --claude PATH; without it, they use command -v claude from the installing shell. The path is kept as given, not resolved, so the native install's symlink follows its updates. It must be absolute, an executable file, and only [A-Za-z0-9/._+-] (systemd expands % and splits on spaces); anything else refuses with exit 1. With no claude found, the unit gets a comment line instead of the variable and render says so on stderr, so a pi-only host installs as before.
• install prints the pinned path and its --version. status prints the unit's MOSAIC_CLAUDE_BIN.
• Tests:
  • render with --claude, with claude found on PATH, with none, and the refusals (relative, not executable, % or a space);
  • sessionEnv passes MOSAIC_CLAUDE_BIN;
  • the adapter runs MOSAIC_CLAUDE_BIN over a claude on PATH, and exits 2 for a relative or missing one;
  • claudeVersion asks MOSAIC_CLAUDE_BIN.
• Docs: the cli README "Unit" section and the manifest note, the adapters README variable table, the seat README sessionEnv line.

Out of scope

The pacman package stays installed and untouched (no sudo). The model routing table, thinking and the recorded provider stay row 65's. No business-file or system-config field: the binary is a property of the host install, like node's directory, so the unit carries it.

Gate

Filbert and Dewey approve on the row's issue naming the candidate manifest. The cli, seat and harness node suites and every scripts/test-*.sh green on Sage's gate rerun. After landing, Sage reinstalls the unit through scripts/bus-service.sh install, runs the opus probe with the unit's environment, and reports the path and version to Mos. The running host keeps its environment until the Q18 --pm restart.