mosaicstack/stack
1
0
Fork 0
Code Issues 26 Pull Requests 2 Actions Packages Projects Releases 14 Wiki Activity

docs: plan durable tmux fleet install #557

Merged
jason.woltje merged 2 commits from plan/tmux-fleet-durable-install into main 2026-06-20 16:19:20 +00:00
Conversation 3 Commits 2 Files Changed 11 +1058 -23
jason.woltje commented 2026-06-19 20:10:53 +00:00
Owner
Copy Link

Summary

  • add implementation plan for durable tmux fleet holder-service rollout
  • define generic Mosaic install/customization path instead of hardcoding USC roster
  • capture current-server evidence and safe named-socket rollout strategy
  • split follow-up work into tmux tool hardening, systemd primitives, roster/CLI, and docs

Key decisions

  • use holder-owned tmux server with per-agent systemd units
  • default to a separate named tmux socket to avoid disturbing existing sessions
  • expose mosaic fleet and mosaic agent abstractions so Matrix can replace tmux later
  • keep USC-style agent roster as an example profile, not a default

Validation

  • plan written under scratchpads/
  • current server discovery performed: tmux 3.4, user systemd active, existing default tmux sessions present, installed Mosaic 0.0.31
## Summary - add implementation plan for durable tmux fleet holder-service rollout - define generic Mosaic install/customization path instead of hardcoding USC roster - capture current-server evidence and safe named-socket rollout strategy - split follow-up work into tmux tool hardening, systemd primitives, roster/CLI, and docs ## Key decisions - use holder-owned tmux server with per-agent systemd units - default to a separate named tmux socket to avoid disturbing existing sessions - expose `mosaic fleet` and `mosaic agent` abstractions so Matrix can replace tmux later - keep USC-style agent roster as an example profile, not a default ## Validation - plan written under `scratchpads/` - current server discovery performed: tmux 3.4, user systemd active, existing default tmux sessions present, installed Mosaic 0.0.31
jason.woltje added 1 commit 2026-06-19 20:10:54 +00:00
docs: plan durable tmux fleet install
Some checks failed
ci/woodpecker/push/ci Pipeline was canceled
Details
ci/woodpecker/pr/ci Pipeline was canceled
Details
250d3da12d
jason.woltje added 1 commit 2026-06-19 20:23:26 +00:00
feat(fleet): add durable tmux fleet poc
Some checks failed
ci/woodpecker/push/ci Pipeline was canceled
Details
ci/woodpecker/pr/ci Pipeline was canceled
Details
b464c39fc7
jason.woltje commented 2026-06-19 20:23:54 +00:00
Author
Owner
Copy Link

PoC implementation pushed in b464c39.

Added:

  • named-socket support for framework/tools/tmux/send-message.sh and agent-send.sh via -L <socket>
  • exact target normalization for =session → =session:0.0 on pane operations
  • named-socket isolation smoke test: framework/tools/tmux/test-send-message-socket.sh
  • fleet launcher: framework/tools/fleet/start-agent-session.sh
  • fleet launcher test: framework/tools/fleet/test-start-agent-session.sh
  • user systemd templates:
    • framework/systemd/user/mosaic-tmux-holder.service
    • framework/systemd/user/mosaic-agent@.service
  • systemd template validation: framework/systemd/user/test-fleet-units.sh
  • PoC install/canary notes: framework/systemd/user/README.md

Validation run locally:

bash -n packages/mosaic/framework/tools/tmux/send-message.sh \
  packages/mosaic/framework/tools/tmux/agent-send.sh \
  packages/mosaic/framework/tools/tmux/test-send-message-socket.sh \
  packages/mosaic/framework/tools/fleet/start-agent-session.sh \
  packages/mosaic/framework/tools/fleet/test-start-agent-session.sh \
  packages/mosaic/framework/systemd/user/test-fleet-units.sh

packages/mosaic/framework/tools/tmux/test-send-message-socket.sh
# ok - named tmux socket send tools

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
# ok - start-agent-session

packages/mosaic/framework/systemd/user/test-fleet-units.sh
# ok - fleet systemd unit templates

npm pack --dry-run --json
# confirmed new framework/tools/fleet, framework/tools/tmux, and framework/systemd/user files are included in package

Note: pnpm --filter @mosaicstack/mosaic test could not run in this checkout because node_modules/vitest are not installed locally. Shell/systemd/package checks passed.

PoC implementation pushed in `b464c39`. Added: - named-socket support for `framework/tools/tmux/send-message.sh` and `agent-send.sh` via `-L <socket>` - exact target normalization for `=session` → `=session:0.0` on pane operations - named-socket isolation smoke test: `framework/tools/tmux/test-send-message-socket.sh` - fleet launcher: `framework/tools/fleet/start-agent-session.sh` - fleet launcher test: `framework/tools/fleet/test-start-agent-session.sh` - user systemd templates: - `framework/systemd/user/mosaic-tmux-holder.service` - `framework/systemd/user/mosaic-agent@.service` - systemd template validation: `framework/systemd/user/test-fleet-units.sh` - PoC install/canary notes: `framework/systemd/user/README.md` Validation run locally: ```bash bash -n packages/mosaic/framework/tools/tmux/send-message.sh \ packages/mosaic/framework/tools/tmux/agent-send.sh \ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh \ packages/mosaic/framework/tools/fleet/start-agent-session.sh \ packages/mosaic/framework/tools/fleet/test-start-agent-session.sh \ packages/mosaic/framework/systemd/user/test-fleet-units.sh packages/mosaic/framework/tools/tmux/test-send-message-socket.sh # ok - named tmux socket send tools packages/mosaic/framework/tools/fleet/test-start-agent-session.sh # ok - start-agent-session packages/mosaic/framework/systemd/user/test-fleet-units.sh # ok - fleet systemd unit templates npm pack --dry-run --json # confirmed new framework/tools/fleet, framework/tools/tmux, and framework/systemd/user files are included in package ``` Note: `pnpm --filter @mosaicstack/mosaic test` could not run in this checkout because `node_modules`/`vitest` are not installed locally. Shell/systemd/package checks passed.
jason.woltje force-pushed plan/tmux-fleet-durable-install from b464c39fc7 to 28a669a89c 2026-06-19 20:41:41 +00:00 Compare
jason.woltje commented 2026-06-19 20:48:29 +00:00
Author
Owner
Copy Link

Update: amended PoC commit to 28a669a after local Prettier check caught the scratchpad table formatting that failed CI format on superseded pipeline 1230.

Additional validation:

npx --yes prettier@3 --check \
  scratchpads/2026-06-19-tmux-fleet-durable-install-plan.md \
  packages/mosaic/framework/tools/tmux/README.md \
  packages/mosaic/framework/systemd/user/README.md
# All matched files use Prettier code style!

Fresh CI after force-with-lease push:

As of last poll both are still running at install/ci-postgres. No new failure observed yet.

Update: amended PoC commit to `28a669a` after local Prettier check caught the scratchpad table formatting that failed CI format on superseded pipeline `1230`. Additional validation: ```bash npx --yes prettier@3 --check \ scratchpads/2026-06-19-tmux-fleet-durable-install-plan.md \ packages/mosaic/framework/tools/tmux/README.md \ packages/mosaic/framework/systemd/user/README.md # All matched files use Prettier code style! ``` Fresh CI after force-with-lease push: - push: https://ci.mosaicstack.dev/repos/47/pipeline/1231/1 - PR: https://ci.mosaicstack.dev/repos/47/pipeline/1232/1 As of last poll both are still running at install/ci-postgres. No new failure observed yet.
jason.woltje force-pushed plan/tmux-fleet-durable-install from 28a669a89c to 757f5e6998 2026-06-19 20:50:45 +00:00 Compare
jason.woltje commented 2026-06-19 20:51:13 +00:00
Author
Owner
Copy Link

USC tmux-fleet context reconciled against the Stack PoC.

Verified AI Guide source:

  • mosaicstack/aiguide:playbooks/tmux-fleet.md
  • commit 2a0b0b5

Alignment changes in current Stack head 757f5e6:

  • added explicit references to the AI Guide playbook in the Stack implementation plan and systemd README
  • changed mosaic-agent@.service ExecStop to the playbook's exact session target form: kill-session -t "=%i"
  • added a regression check so the unit template must keep exact-match per-agent stop behavior

Re-run local validation after alignment:

bash -n packages/mosaic/framework/systemd/user/test-fleet-units.sh \
  packages/mosaic/framework/tools/fleet/start-agent-session.sh \
  packages/mosaic/framework/tools/fleet/test-start-agent-session.sh \
  packages/mosaic/framework/tools/tmux/send-message.sh \
  packages/mosaic/framework/tools/tmux/agent-send.sh \
  packages/mosaic/framework/tools/tmux/test-send-message-socket.sh

packages/mosaic/framework/systemd/user/test-fleet-units.sh
# ok - fleet systemd unit templates

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
# ok - start-agent-session

packages/mosaic/framework/tools/tmux/test-send-message-socket.sh
# ok - named tmux socket send tools

npx --yes prettier@3 --check \
  scratchpads/2026-06-19-tmux-fleet-durable-install-plan.md \
  packages/mosaic/framework/systemd/user/README.md \
  packages/mosaic/framework/tools/tmux/README.md
# All matched files use Prettier code style!

Fresh CI after this force-with-lease push:

Scope note: agreed with USC split. framework/tools/tmux remains the inter-agent messaging layer; fleet ownership/lifecycle primitives are under framework/systemd/user and framework/tools/fleet, not mixed into tmux comms.

USC tmux-fleet context reconciled against the Stack PoC. Verified AI Guide source: - `mosaicstack/aiguide:playbooks/tmux-fleet.md` - commit `2a0b0b5` Alignment changes in current Stack head `757f5e6`: - added explicit references to the AI Guide playbook in the Stack implementation plan and systemd README - changed `mosaic-agent@.service` `ExecStop` to the playbook's exact session target form: `kill-session -t "=%i"` - added a regression check so the unit template must keep exact-match per-agent stop behavior Re-run local validation after alignment: ```bash bash -n packages/mosaic/framework/systemd/user/test-fleet-units.sh \ packages/mosaic/framework/tools/fleet/start-agent-session.sh \ packages/mosaic/framework/tools/fleet/test-start-agent-session.sh \ packages/mosaic/framework/tools/tmux/send-message.sh \ packages/mosaic/framework/tools/tmux/agent-send.sh \ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh packages/mosaic/framework/systemd/user/test-fleet-units.sh # ok - fleet systemd unit templates packages/mosaic/framework/tools/fleet/test-start-agent-session.sh # ok - start-agent-session packages/mosaic/framework/tools/tmux/test-send-message-socket.sh # ok - named tmux socket send tools npx --yes prettier@3 --check \ scratchpads/2026-06-19-tmux-fleet-durable-install-plan.md \ packages/mosaic/framework/systemd/user/README.md \ packages/mosaic/framework/tools/tmux/README.md # All matched files use Prettier code style! ``` Fresh CI after this force-with-lease push: - push: https://ci.mosaicstack.dev/repos/47/pipeline/1233/1 - PR: https://ci.mosaicstack.dev/repos/47/pipeline/1234/1 Scope note: agreed with USC split. `framework/tools/tmux` remains the inter-agent messaging layer; fleet ownership/lifecycle primitives are under `framework/systemd/user` and `framework/tools/fleet`, not mixed into tmux comms.
jason.woltje merged commit 45e2c2aad8 into main 2026-06-20 16:19:20 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#557
Delete Branch "plan/tmux-fleet-durable-install"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?