From e1b90ed6960994b3cd3522a96026fdc8b6316624 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sun, 11 Oct 2026 15:46:52 -0500 Subject: [PATCH] docs(plans): bus host explicit Claude Code binary brief (Q18) Mos withdrew decision 89's package upgrade: Jason's Claude Code is the native ~/.local/bin/claude (2.1.296), not /usr/bin/claude 2.1.259. The unit will carry MOSAIC_CLAUDE_BIN and the adapter and manifest version check will use it. Co-Authored-By: Claude Opus 5.5 --- docs/plans/2026-10-11_bus-claude-binary.md | 85 ++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/plans/2026-10-11_bus-claude-binary.md diff --git a/docs/plans/2026-10-11_bus-claude-binary.md b/docs/plans/2026-10-11_bus-claude-binary.md new file mode 100644 index 000000000..d494ede2b --- /dev/null +++ b/docs/plans/2026-10-11_bus-claude-binary.md @@ -0,0 +1,85 @@ +# 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 + +`mosaic-bus@.service` 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.