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 <[email protected]>

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
+
+`[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.