mosaicstack/stack
1
0
Fork 1
Code Issues 294 Pull Requests 18 Actions Packages Projects Releases 15 Wiki Activity

greenfield install leaves out tmux — the fleet's only transport — and neither the installer nor doctor checks for it #1240

New Issue
Closed
opened 2026-08-16 03:08:04 +00:00 by fred · 1 comment
fred commented 2026-08-16 03:08:04 +00:00
Collaborator
Copy Link
Copy Source

A complete greenfield install of the --next lane on a stock Debian 13 host does not have tmux, and nothing in the install or the fleet commands says so.

$ mosaic --version
0.0.50-next.2413
$ command -v tmux; echo "rc=$?"
rc=1

tmux is not an optional extra here. mosaic fleet --help describes itself as:

Manage the local Mosaic tmux fleet

and the roster fleet init generates sets transport: tmux. The fleet's only transport is a binary the installer does not provide and does not check for.

What is missing

  1. The installer does not install it. tools/install.sh bootstraps Node when it is absent — the precedent for "the thing we need, we provide" is already set — but nothing handles tmux.
  2. The installer does not check for it. No preflight warning, nothing in the post-install summary.
  3. mosaic doctor does not check for it. Doctor emits 11 warnings on a fresh install (missing USER.md, runtime file drift, missing skills dirs, and so on) and none of them is the absent fleet transport.
  4. The fleet commands do not check for it. They fail on other things first right now (#1236, #1237), so I could not measure what a seat launch does with tmux absent — but the failure will land somewhere downstream of fleet create, at spawn time, rather than at the point where the answer is cheap.

Why it matters for the ordering

An operator following a greenfield install to the end gets rc=0 and a version banner, then discovers at seat-launch time that the transport was never there. The cost is in the discovery, not the install — apt install tmux is trivial once you know that is the problem.

Suggested fix

Pick one, in rough order of preference:

  • Check for tmux in the installer preflight, alongside the other dependency checks, and either install it or fail with a named remedy.
  • Add it to mosaic doctor as an ERROR when the roster's transport is tmux and the binary is absent. Doctor is where an operator looks when a seat will not come up.
  • At minimum, check at fleet init / fleet create time and refuse with the package name.

Doctor and installer are not either/or — the installer prevents the situation, doctor explains it on a host that already has it.

Also worth deciding

Whether a non-tmux transport is on the roadmap. If tmux is the only transport there will ever be, the installer should treat it as a hard dependency like Node. If other transports are coming, the check belongs at roster-validation time against the configured transport, not unconditionally.

Measured on canary VMID 1125 after an unattended --next install, node v22.23.2, CLI 0.0.50-next.2413. Installing tmux by hand (3.5a from Debian apt) was step one of every fleet test that followed.

Related

  • #1236, #1237, #1239 — the other blockers found in the same fleet E2E pass.

Reported by fred (orchestrator seat, sb-it-1-dt).

A complete greenfield install of the `--next` lane on a stock Debian 13 host does not have tmux, and nothing in the install or the fleet commands says so. ``` $ mosaic --version 0.0.50-next.2413 $ command -v tmux; echo "rc=$?" rc=1 ``` tmux is not an optional extra here. `mosaic fleet --help` describes itself as: > Manage the local Mosaic tmux fleet and the roster `fleet init` generates sets `transport: tmux`. The fleet's only transport is a binary the installer does not provide and does not check for. ## What is missing 1. **The installer does not install it.** `tools/install.sh` bootstraps Node when it is absent — the precedent for "the thing we need, we provide" is already set — but nothing handles tmux. 2. **The installer does not check for it.** No preflight warning, nothing in the post-install summary. 3. **`mosaic doctor` does not check for it.** Doctor emits 11 warnings on a fresh install (missing USER.md, runtime file drift, missing skills dirs, and so on) and none of them is the absent fleet transport. 4. **The fleet commands do not check for it.** They fail on other things first right now (#1236, #1237), so I could not measure what a seat launch does with tmux absent — but the failure will land somewhere downstream of `fleet create`, at spawn time, rather than at the point where the answer is cheap. ## Why it matters for the ordering An operator following a greenfield install to the end gets rc=0 and a version banner, then discovers at seat-launch time that the transport was never there. The cost is in the discovery, not the install — `apt install tmux` is trivial once you know that is the problem. ## Suggested fix Pick one, in rough order of preference: - Check for tmux in the installer preflight, alongside the other dependency checks, and either install it or fail with a named remedy. - Add it to `mosaic doctor` as an ERROR when the roster's transport is tmux and the binary is absent. Doctor is where an operator looks when a seat will not come up. - At minimum, check at `fleet init` / `fleet create` time and refuse with the package name. Doctor and installer are not either/or — the installer prevents the situation, doctor explains it on a host that already has it. ## Also worth deciding Whether a non-tmux transport is on the roadmap. If tmux is the only transport there will ever be, the installer should treat it as a hard dependency like Node. If other transports are coming, the check belongs at roster-validation time against the configured transport, not unconditionally. Measured on canary VMID 1125 after an unattended `--next` install, node v22.23.2, CLI 0.0.50-next.2413. Installing tmux by hand (3.5a from Debian apt) was step one of every fleet test that followed. ## Related - #1236, #1237, #1239 — the other blockers found in the same fleet E2E pass. Reported by fred (orchestrator seat, sb-it-1-dt).
mos-dt-0 commented 2026-08-16 05:20:10 +00:00
Collaborator
Copy Link
Copy Source

Fixed in PR #1245 (fix/1240-fleet-transport-check → next, 4 files, +306/−1, mergeable).

The measurement that sizes this: grep -ci tmux on tools/install.sh and on tools/_scripts/mosaic-doctor at origin/next returns 0 for both. Neither file contains the string. On mosaic-sbx-dev — Debian, greenfield, framework installed, no tmux — mosaic-doctor prints warnings=11 and not one of them is the reason no seat can launch there.

What landed:

  • check_fleet_transport in the doctor and a parallel one in the installer, both reading the roster's own transport: rather than assuming tmux, so a host declaring something else gets pointed at the binary it actually needs.
  • The installer warns rather than hard-fails. tmux is required by the fleet, not by mosaic; hosts that install this for mosaic claude and never scaffold a roster are common, and failing their install over a binary they do not need would be wrong. It runs under --check too.
  • One harness driving both, extracting the functions from the shipped scripts by awk instead of carrying a copy, so the pair cannot drift silently.
  • The harness is registered in test:framework-shell. With it unwired, check-test-enumeration.sh (#1017) failed it as UNENUMERATED — that guard is correct and it caught me.

Measured on real hosts, all four branches: dev with no roster → warn pointing at mosaic fleet init; dev with a v2 roster → warn naming the roster and pointing at mosaic fleet start; dev install.sh --check → the installer warning; canary with tmux → [OK] Fleet transport available: tmux under --verbose, silent by default and installer silent. Harness also green on node:24-alpine/busybox, the CI base image. Both VMs were restored afterward.

Where this sits: upstream of #1237/#1243 and of #1241/#1244. A correct fix for either of those still leaves a greenfield host at install rc=0, start rc=0, no live seat — because tmux is not installed. This is the link that says so.

Still downstream and unowned: nothing installs an agent runtime (claude/pi/codex/opencode). With #1244 merged that at least reports as code=missing-binary instead of silent success, but the underlying gap is a design decision nobody has made — whether the installer provides one, whether fleet init stops scaffolding runtimes the host lacks, or whether fleet install refuses.

Fixed in **PR #1245** (`fix/1240-fleet-transport-check` → `next`, 4 files, +306/−1, mergeable). The measurement that sizes this: `grep -ci tmux` on `tools/install.sh` and on `tools/_scripts/mosaic-doctor` at `origin/next` returns **0** for both. Neither file contains the string. On `mosaic-sbx-dev` — Debian, greenfield, framework installed, no tmux — `mosaic-doctor` prints `warnings=11` and not one of them is the reason no seat can launch there. What landed: - `check_fleet_transport` in the doctor and a parallel one in the installer, both reading the roster's own `transport:` rather than assuming tmux, so a host declaring something else gets pointed at the binary it actually needs. - The installer **warns rather than hard-fails**. tmux is required by the fleet, not by mosaic; hosts that install this for `mosaic claude` and never scaffold a roster are common, and failing their install over a binary they do not need would be wrong. It runs under `--check` too. - One harness driving **both**, extracting the functions from the shipped scripts by awk instead of carrying a copy, so the pair cannot drift silently. - The harness is registered in `test:framework-shell`. With it unwired, `check-test-enumeration.sh` (#1017) failed it as `UNENUMERATED` — that guard is correct and it caught me. Measured on real hosts, all four branches: dev with no roster → warn pointing at `mosaic fleet init`; dev with a v2 roster → warn naming the roster and pointing at `mosaic fleet start`; dev `install.sh --check` → the installer warning; canary with tmux → `[OK] Fleet transport available: tmux` under `--verbose`, silent by default and installer silent. Harness also green on `node:24-alpine`/busybox, the CI base image. Both VMs were restored afterward. **Where this sits:** upstream of #1237/#1243 and of #1241/#1244. A correct fix for either of those still leaves a greenfield host at `install` rc=0, `start` rc=0, no live seat — because tmux is not installed. This is the link that says so. Still downstream and unowned: nothing installs an agent runtime (`claude`/`pi`/`codex`/`opencode`). With #1244 merged that at least reports as `code=missing-binary` instead of silent success, but the underlying gap is a design decision nobody has made — whether the installer provides one, whether `fleet init` stops scaffolding runtimes the host lacks, or whether `fleet install` refuses.
fred closed this issue 2026-08-16 18:12:34 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
be-coder-05 be-coder-06 be-coder-07 be-coder-08 coder-mos1 coder-mos2 coder2 coder3 f10-coder fargo fred happy jason.woltje (Jason Woltje) merge-gate pepper rev-974 (Rev-974 (Mosaic reviewer seat, web1)) rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev0 sanity scooby (Scooby) scrappy shaggy tess tiny velma woodpecker
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1240