feat(fleet): add durable tmux fleet poc

packages/mosaic/framework/defaults/TOOLS.md

@@ -5,10 +5,39 @@ Tool suites live at `~/.config/mosaic/tools/<suite>/`. This is the index only.
 read it (or the relevant service guide) when your task actually touches that service.
 Project-specific tooling belongs in the project's `AGENTS.md`, not here.
 
+## ⚡ Most-used fleet tools (reach for these FIRST — don't hand-roll)
+
+You are a Mosaic fleet agent. These cover the highest-frequency cross-agent and git-provider
+tasks — use them before improvising with raw `tmux send-keys`, raw `tea`/`gh`/`glab`, or `curl`.
+
+**1. Message another agent** → `tools/tmux/agent-send.sh` (NOT raw `tmux send-keys`):
+
+```bash
+tools/tmux/agent-send.sh -s <target-session> -m "message"   # or -f <file> to send a file's contents
+```
+
+The coordinator session is `mos-claude` — send status, findings, and questions there.
+
+**2. Issues / PRs / milestones** → `tools/git/*.sh` wrappers (before raw `tea`/`gh`/`glab`):
+
+```bash
+tools/git/pr-create.sh ...   tools/git/issue-create.sh ...   tools/git/pr-merge.sh ...
+tools/git/ci-queue-wait.sh --purpose push|merge   # REQUIRED before any push/merge
+```
+
+**GITEA_LOGIN gotcha** — the wrappers default to login `mosaicstack`; on a USC repo that fails with
+`gitea / Error: GetUserByName ... not found`. Pick the login from the repo's `origin` host first:
+
+| origin host           | login                                    |
+| --------------------- | ---------------------------------------- |
+| `git.uscllc.com`      | `export GITEA_LOGIN=usc`                 |
+| `git.mosaicstack.dev` | default `mosaicstack` (no export needed) |
+
 ## Suites (use wrappers first)
 
 | Suite      | Path                                             | Purpose                                                                  |
 | ---------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
+| tmux       | `tools/tmux/agent-send.sh`                       | inter-agent messaging (see "Most-used" above)                            |
 | git        | `tools/git/*.sh`                                 | issues, PRs, milestones, CI queue guard (platform-auto-detected)         |
 | woodpecker | `tools/woodpecker/*.sh`                          | CI pipelines (`-a mosaic`\|`usc`; match git remote host)                 |
 | portainer  | `tools/portainer/*.sh`                           | Docker Swarm stacks (status/redeploy/list)                               |

packages/mosaic/framework/runtime/pi/RUNTIME.md

@@ -29,7 +29,21 @@ Pi supports `--models` for Ctrl+P model cycling during a session. Use cheaper mo
 
 ### Skills
 
-Mosaic skills are loaded natively via Pi's `--skill` flag. Skills are discovered from:
+By default the launcher starts Pi with `--no-skills` to keep startup context small, then
+force-loads a small set of fleet-critical skills via explicit `--skill` flags (an explicit
+`--skill` overrides `--no-skills` for that path). The default forced set is `mosaic-tools`
+(the must-use `~/.config/mosaic/tools/` cheatsheet: inter-agent messaging + git wrappers).
+
+Tune skill loading with environment variables:
+
+- `MOSAIC_PI_FORCE_SKILLS` — colon-separated skill dir names to force-load (default: `mosaic-tools`;
+  set to an empty string to disable force-loading). Missing skills are skipped silently.
+- `MOSAIC_PI_SKILL_MODE=all` — link every skill found in `~/.config/mosaic/{skills,skills-local}/`
+  (full catalog; larger context).
+- `MOSAIC_PI_SKILL_MODE=discover` — let Pi discover skills natively (no `--no-skills`), still
+  force-loading the fleet set on top.
+
+Skills are discovered from:
 
 - `~/.config/mosaic/skills/` (Mosaic global skills)
 - `~/.pi/agent/skills/` (Pi global skills)

packages/mosaic/framework/systemd/user/README.md

@@ -0,0 +1,57 @@
+# Mosaic tmux Fleet PoC
+
+This directory contains the first durable tmux-backed fleet primitives for the
+Mosaic software-factory model.
+
+The lifecycle model follows the organization-neutral AI Guide playbook
+`mosaicstack/aiguide:playbooks/tmux-fleet.md` (commit `2a0b0b5`): a dedicated
+holder owns the tmux server/socket; agent units join it and stop only their own
+exact-match session.
+
+## Layout
+
+- `mosaic-tmux-holder.service` — user-mode holder that owns the named tmux server.
+- `mosaic-agent@.service` — user-mode template for one reusable agent session.
+- `test-fleet-units.sh` — validates unit syntax and required relationships.
+
+The agent template calls:
+
+```text
+~/.config/mosaic/tools/fleet/start-agent-session.sh <agent-name>
+```
+
+which starts or reuses a tmux session on `MOSAIC_TMUX_SOCKET`.
+
+## Local customization
+
+Per-agent overrides live outside the package in:
+
+```text
+~/.config/mosaic/fleet/agents/<agent>.env
+```
+
+Example:
+
+```dotenv
+MOSAIC_TMUX_SOCKET=mosaic-factory
+MOSAIC_AGENT_RUNTIME=claude
+MOSAIC_AGENT_WORKDIR=/home/jarvis/src/mosaic-stack
+# Optional escape hatch for PoC/canary agents:
+# MOSAIC_AGENT_COMMAND=mosaic yolo claude
+```
+
+## Manual canary sequence
+
+```bash
+mkdir -p ~/.config/systemd/user ~/.config/mosaic/tools/fleet ~/.config/mosaic/fleet/agents
+cp packages/mosaic/framework/systemd/user/mosaic-*.service ~/.config/systemd/user/
+cp packages/mosaic/framework/tools/fleet/start-agent-session.sh ~/.config/mosaic/tools/fleet/
+chmod +x ~/.config/mosaic/tools/fleet/start-agent-session.sh
+systemctl --user daemon-reload
+systemctl --user start mosaic-tmux-holder.service
+systemctl --user start mosaic-agent@canary.service
+tmux -L mosaic-factory ls
+```
+
+Do not use `tmux kill-server` without `-L mosaic-factory`; this pattern is meant
+to avoid disturbing the user's default tmux server.

packages/mosaic/framework/systemd/user/mosaic-agent@.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Mosaic tmux fleet agent %i
+Documentation=https://git.mosaicstack.dev/mosaicstack/stack
+Requires=mosaic-tmux-holder.service
+After=mosaic-tmux-holder.service
+PartOf=mosaic-tmux-holder.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+Environment=MOSAIC_AGENT_NAME=%i
+Environment=MOSAIC_AGENT_RUNTIME=pi
+Environment=MOSAIC_AGENT_WORKDIR=%h
+EnvironmentFile=-%h/.config/mosaic/fleet/agents/%i.env
+ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-agent-session.sh %i
+ExecStop=-/bin/bash -lc 'tmux -L "${MOSAIC_TMUX_SOCKET:-mosaic-factory}" kill-session -t "=%i"'
+
+[Install]
+WantedBy=default.target

packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=Mosaic tmux fleet holder
+Documentation=https://git.mosaicstack.dev/mosaicstack/stack
+After=default.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+Environment=MOSAIC_TMUX_HOLDER=_holder
+ExecStart=/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${MOSAIC_TMUX_HOLDER}:0.0" 2>/dev/null || tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$MOSAIC_TMUX_HOLDER" "while true; do sleep 3600; done"'
+ExecStop=-/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" kill-server'
+
+[Install]
+WantedBy=default.target

packages/mosaic/framework/systemd/user/test-fleet-units.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+HOLDER="$SCRIPT_DIR/mosaic-tmux-holder.service"
+AGENT="$SCRIPT_DIR/mosaic-agent@.service"
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+[ -f "$HOLDER" ] || fail "missing mosaic-tmux-holder.service"
+[ -f "$AGENT" ] || fail "missing mosaic-agent@.service"
+
+grep -qF 'ExecStart=' "$HOLDER" || fail "holder has no ExecStart"
+grep -qF 'tmux -L' "$HOLDER" || fail "holder does not use named tmux socket"
+grep -qF '_holder' "$HOLDER" || fail "holder session is not explicit"
+grep -qF 'Requires=mosaic-tmux-holder.service' "$AGENT" || fail "agent does not require holder"
+grep -qF 'start-agent-session.sh' "$AGENT" || fail "agent unit does not call start-agent-session.sh"
+grep -qF 'kill-session -t "=%i"' "$AGENT" || fail "agent stop does not exact-match its session"
+
+if command -v systemd-analyze >/dev/null 2>&1; then
+  systemd-analyze verify --user "$HOLDER" "$AGENT" >/tmp/mosaic-fleet-systemd-verify.log 2>&1 || {
+    cat /tmp/mosaic-fleet-systemd-verify.log >&2
+    fail "systemd-analyze verify failed"
+  }
+fi
+
+echo "ok - fleet systemd unit templates"

packages/mosaic/framework/templates/agent/AGENTS.md.template

@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
 
@@ -58,7 +58,7 @@ ${QUALITY_GATES}
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 
 ## Documentation Contract
@@ -88,7 +88,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 
 ## Container Release Strategy (When Applicable)
 
@@ -138,8 +138,8 @@ When completing an orchestrated task:
 ### Post-Coding Review
 After implementing changes, code review is REQUIRED for any source-code modification.
 For orchestrated tasks, the orchestrator will run:
-1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
 

packages/mosaic/framework/templates/agent/CLAUDE.md.template

@@ -135,7 +135,7 @@ ${QUALITY_GATES}
 ## Issue Tracking
 
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
 
@@ -147,9 +147,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -176,10 +176,10 @@ Run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.

packages/mosaic/framework/templates/agent/projects/django/AGENTS.md.template

@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
 
@@ -68,7 +68,7 @@ ruff check . && mypy . && pytest tests/
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 
 ## Documentation Contract
@@ -97,7 +97,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 
 
 ## Container Release Strategy (When Applicable)
@@ -139,8 +139,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
 ### Post-Coding Review
 After implementing changes, code review is REQUIRED for any source-code modification.
 For orchestrated tasks, the orchestrator will run:
-1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
 

packages/mosaic/framework/templates/agent/projects/django/CLAUDE.md.template

@@ -159,10 +159,10 @@ Run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
@@ -186,7 +186,7 @@ See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation delive
 ## Issue Tracking
 
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
 
@@ -198,9 +198,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.

packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/AGENTS.md.template

@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
 
@@ -72,7 +72,7 @@ pnpm typecheck && pnpm lint && pnpm test
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 
 ## Documentation Contract
@@ -101,7 +101,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 
 
 ## Container Release Strategy (When Applicable)
@@ -143,8 +143,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
 ### Post-Coding Review
 After implementing changes, code review is REQUIRED for any source-code modification.
 For orchestrated tasks, the orchestrator will run:
-1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
 

packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template

@@ -191,10 +191,10 @@ Run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
@@ -218,7 +218,7 @@ See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation delive
 ## Issue Tracking
 
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
 
@@ -230,9 +230,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.

packages/mosaic/framework/templates/agent/projects/python-fastapi/AGENTS.md.template

@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
 
@@ -58,7 +58,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 
 ## Documentation Contract
@@ -87,7 +87,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 
 ## Container Release Strategy (When Applicable)
 

packages/mosaic/framework/templates/agent/projects/python-fastapi/CLAUDE.md.template

@@ -135,7 +135,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 ## Issue Tracking
 
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
 
@@ -146,9 +146,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -171,8 +171,8 @@ If you modify source code, independent code review is REQUIRED before completion
 Run independent reviews:
 
 ```bash
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.

packages/mosaic/framework/templates/agent/projects/python-library/AGENTS.md.template

@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
 
@@ -55,7 +55,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 
 ## Documentation Contract
@@ -84,7 +84,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 
 ## Container Release Strategy (When Applicable)
 

packages/mosaic/framework/templates/agent/projects/python-library/CLAUDE.md.template

@@ -125,7 +125,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 ## Issue Tracking
 
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
 
@@ -136,9 +136,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -161,8 +161,8 @@ If you modify source code, independent code review is REQUIRED before completion
 Run independent reviews:
 
 ```bash
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.

packages/mosaic/framework/templates/agent/projects/typescript/AGENTS.md.template

@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
 
@@ -56,7 +56,7 @@ ${QUALITY_GATES}
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 
 ## Documentation Contract
@@ -85,7 +85,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 
 ## Container Release Strategy (When Applicable)
 

packages/mosaic/framework/templates/agent/projects/typescript/CLAUDE.md.template

@@ -122,7 +122,7 @@ ${QUALITY_GATES}
 ## Issue Tracking
 
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
 
@@ -133,9 +133,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -159,10 +159,10 @@ Run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
+MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-mosaic-factory}
+MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
+MOSAIC_AGENT_WORKDIR=${MOSAIC_AGENT_WORKDIR:-$HOME}
+MOSAIC_AGENT_COMMAND=${MOSAIC_AGENT_COMMAND:-}
+
+if [ -z "$AGENT_NAME" ]; then
+  echo "ERROR: agent name argument or MOSAIC_AGENT_NAME is required" >&2
+  exit 64
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "ERROR: tmux is required" >&2
+  exit 69
+fi
+
+if tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
+  echo "Mosaic agent session already running: $AGENT_NAME on socket $MOSAIC_TMUX_SOCKET"
+  exit 0
+fi
+
+if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
+  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME"
+fi
+
+mkdir -p "$MOSAIC_AGENT_WORKDIR"
+exec tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" "$MOSAIC_AGENT_COMMAND"

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

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+START="$SCRIPT_DIR/start-agent-session.sh"
+SOCKET="mosaic-agent-test-$RANDOM-$$"
+AGENT="agent-$RANDOM"
+WORKDIR=$(mktemp -d)
+trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$WORKDIR"' EXIT
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+MOSAIC_TMUX_SOCKET="$SOCKET" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR" \
+MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
+  "$START" "$AGENT"
+
+tmux -L "$SOCKET" has-session -t "=$AGENT:0.0" || fail "agent session was not created"
+actual_dir=$(tmux -L "$SOCKET" display-message -p -t "=$AGENT:0.0" '#{pane_current_path}')
+[ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir"
+
+MOSAIC_TMUX_SOCKET="$SOCKET" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR" \
+MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
+  "$START" "$AGENT" >/tmp/mosaic-start-agent-idempotent.out
+
+grep -qF 'already running' /tmp/mosaic-start-agent-idempotent.out || fail "duplicate start was not idempotent"
+
+echo "ok - start-agent-session"

packages/mosaic/framework/tools/git/lane-brief.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# lane-brief.sh — live dispatch brief for a repo "lane" (milestone/label), straight
+# from current Gitea state. Defeats stale worker self-report: workers brief from
+# static notes and routinely report issues "todo" that are already CLOSED, forcing
+# the orchestrator to re-verify each one before dispatch. This returns the CURRENT
+# open set, classified for dispatch, in one call.
+#
+# Usage:
+#   lane-brief.sh -r <owner/repo> [-m <milestone>] [-l <label>] [-L <login>] [-n <limit>]
+#   lane-brief.sh -r usc/uconnect -m "M2M Part Search (0.0.45)"
+#   lane-brief.sh -r usc/uconnect -l domain/6-security
+#
+# Reliable signals (closed issues are excluded by definition — that's the point):
+#   - open-vs-closed : authoritative; this is the stale-intake failure mode.
+#   - PR-linkage     : an open PR referencing the issue = work underway.
+# Assignees/dependencies are intentionally NOT trusted as "available" signals —
+# fleets that track work-state out-of-band (tmux board, issue text) leave them
+# empty in Gitea. Output therefore partitions by PR presence and the OPEN-NO-PR set
+# is "dispatch candidates to cross-check against the live fleet", not a blind list.
+#
+# Login resolution order: -L flag > $GITEA_LOGIN > owner inference (usc->usc,
+# mosaicstack/mosaic->mosaicstack) > detect-platform.sh default-login fallback.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/detect-platform.sh"
+
+REPO="" MILESTONE="" LABEL="" LOGIN="" LIMIT=100
+while getopts "r:m:l:L:n:h" opt; do
+  case "$opt" in
+    r) REPO="$OPTARG" ;;
+    m) MILESTONE="$OPTARG" ;;
+    l) LABEL="$OPTARG" ;;
+    L) LOGIN="$OPTARG" ;;
+    n) LIMIT="$OPTARG" ;;
+    h) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "see -h" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$REPO" ]] || { echo "FATAL: -r <owner/repo> required" >&2; exit 2; }
+
+# Resolve login: explicit -L, then $GITEA_LOGIN, then owner inference, then the
+# shared default-login resolver. Owner inference comes before the shared fallback
+# because the latter is not owner-aware (picks the default tea login), which is
+# wrong for cross-instance lanes.
+if [[ -z "$LOGIN" ]]; then
+  if [[ -n "${GITEA_LOGIN:-}" ]]; then
+    LOGIN="$GITEA_LOGIN"
+  else
+    case "${REPO%%/*}" in
+      usc|USC) LOGIN=usc ;;
+      mosaicstack|mosaic) LOGIN=mosaicstack ;;
+      *) LOGIN="$(get_gitea_login_for_repo_override 2>/dev/null || true)" ;;
+    esac
+  fi
+fi
+[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 2; }
+
+command -v tea >/dev/null || { echo "FATAL: tea not found" >&2; exit 1; }
+command -v jq  >/dev/null || { echo "FATAL: jq not found" >&2; exit 1; }
+
+ISSUES_JSON="$(tea issues list --repo "$REPO" --login "$LOGIN" --state open --limit "$LIMIT" \
+  --fields index,title,assignees,milestone,labels --output json 2>/dev/null)" || {
+  echo "FATAL: tea issues list failed for $REPO (login=$LOGIN)" >&2; exit 1; }
+
+# Open PRs, to cross-ref which issues already have work in flight. An issue is
+# "work underway" if an open PR links to it. Two link signals are honored:
+#   (a) a closing keyword in the PR BODY — Gitea's auto-close set (close/closes/
+#       closed, fix/fixes/fixed, resolve/resolves/resolved), case-insensitive,
+#       directly preceding `#N`. This is the AUTHORITATIVE link Gitea itself uses
+#       to associate a PR with the issue it resolves; a body-only "Closes #546"
+#       is the common case and MUST count. The earlier version inspected only the
+#       PR index/title/head TSV (never the body or Gitea linkage), so a body-only
+#       reference was invisible and the linked OPEN issue was misclassified as a
+#       dispatch candidate — re-dispatchable in-flight work (the #546/#547 defect).
+#   (b) a bare #N in the PR title, or an issue number embedded in the head branch
+#       (feat/546-x, fix-546) — the weaker heuristic preserved from prior behavior.
+# Bare #N mentions in the BODY are deliberately NOT treated as links: PR bodies
+# routinely name unrelated issues in prose ("relevant to the #538 line of work"),
+# and counting those would wrongly mark live, dispatchable issues as in-flight.
+# Only the closing-keyword form is a commitment to resolve that issue. Requiring
+# `#` to directly follow the keyword also keeps cross-repo `owner/repo#N` forms
+# from leaking a foreign issue number into this per-repo lane (cross-repo lanes
+# are run per-repo). JSON (not TSV) is used so multi-line bodies parse cleanly.
+PRS_JSON="$(tea pulls list --repo "$REPO" --login "$LOGIN" --state open \
+  --fields index,title,head,body --output json 2>/dev/null || echo '[]')"
+[[ -n "$PRS_JSON" ]] || PRS_JSON='[]'
+
+# \b anchors the keyword to a word start so embedded substrings do not match
+# (e.g. "prefix #5", "disclosed #7" must NOT be read as "fix #5" / "closed #7").
+GITEA_CLOSE_KW='close[sd]?|fix(e[sd])?|resolve[sd]?'
+PR_BODY_REFS="$(printf '%s' "$PRS_JSON" | jq -r '.[] | .body // ""' 2>/dev/null \
+  | grep -oiE "\\b(${GITEA_CLOSE_KW})[[:space:]:]+#[0-9]+" | grep -oE '[0-9]+' || true)"
+PR_TITLE_HEAD_REFS="$(printf '%s' "$PRS_JSON" \
+  | jq -r '.[] | [ (.title // ""), (.head // "" | if type=="object" then (.ref // "") else . end) ] | join(" ")' 2>/dev/null \
+  | grep -oE '#[0-9]+|[/-][0-9]{3,}' | grep -oE '[0-9]+' || true)"
+PR_ISSUE_REFS="$(printf '%s\n%s\n' "$PR_BODY_REFS" "$PR_TITLE_HEAD_REFS" | grep -E '^[0-9]+$' | sort -u || true)"
+
+ts="$(date -u '+%Y-%m-%d %H:%MZ' 2>/dev/null || echo '?')"
+filt="$REPO"; [[ -n "$MILESTONE" ]] && filt="$filt · milestone:'$MILESTONE'"; [[ -n "$LABEL" ]] && filt="$filt · label:'$LABEL'"
+echo "LANE BRIEF — $filt · $ts (login=$LOGIN)"
+echo "(open issues only; closed are excluded by definition — that's the point)"
+echo
+
+# Label match is exact-token against tea's space-separated labels string (so -l
+# "security" does NOT match label "domain/6-security"). Caveat: label names that
+# themselves contain spaces aren't distinguishable in tea's string form.
+printf '%s' "$ISSUES_JSON" | jq -r --arg ms "$MILESTONE" --arg lb "$LABEL" --arg prs "$PR_ISSUE_REFS" '
+  ($prs | split("\n") | map(select(length>0))) as $prrefs
+  | map(
+      select( ($ms=="" or .milestone==$ms)
+          and ($lb=="" or ((.labels//"") | split(" ") | index($lb) != null)) )
+      | . + { assigned: ((.assignees//"")|length>0),
+              haspr: (.index as $ix | ($prrefs | index($ix)) != null) }
+    )
+  | (map(select(.haspr|not)))  as $candidates
+  | (map(select(.haspr)))      as $inflight
+  | "DISPATCH CANDIDATES (open · no open PR) — \($candidates|length)  [cross-check vs live fleet]:",
+    ( $candidates[] | "  #\(.index)  \(.title[0:90])\(if .assigned then "  (gitea-assignee set)" else "" end)" ),
+    "",
+    "WORK UNDERWAY (open · PR in flight) — \($inflight|length):",
+    ( $inflight[] | "  #\(.index)  \(.title[0:80])  [PR open]" )
+'
+echo
+echo "Closed issues are excluded — do NOT take a worker's self-reported 'todo' on faith."
+echo "Candidates = open + no PR; confirm against the live fleet before dispatch"
+echo "(fleets that don't self-assign in Gitea leave 'unassigned' meaningless)."

packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Regression harness for lane-brief.sh PR->issue linkage classification.
+#
+# Covers the #546/#547 defect: lane-brief.sh inspected only the PR index/title/head
+# fields and never the PR BODY, so an open PR whose body says "Closes #546" did not
+# mark issue #546 as work-underway — #546 was listed as a DISPATCH CANDIDATE and was
+# re-dispatchable in-flight work.
+#
+# Asserts:
+#   1. an open issue closed-keyword-linked from a PR BODY ("Closes #546") is
+#      classified WORK UNDERWAY, not a dispatch candidate.
+#   2. a BARE "#777" prose mention in a PR body does NOT classify #777 as
+#      work-underway (only Gitea closing keywords are a real link) — #777 stays a
+#      dispatch candidate.
+#   3. NON-VACUITY / RED-ON-REVERT: a copy of the script with the body-scan removed
+#      misclassifies #546 as a dispatch candidate — proving the body-scan is exactly
+#      what fixes the defect and that assertion 1 fails if the fix is reverted.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LANE_BRIEF="$SCRIPT_DIR/lane-brief.sh"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/lane-brief-pr-linkage}"
+BIN_DIR="$WORK_DIR/bin"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$BIN_DIR"
+
+# --- fake `tea`: serves a fixed open-issue set and one open PR. ----------------
+# PR #547 body uses a closing keyword for #546 ("Closes #546") and a BARE mention
+# of #777 ("the #777 line of work"). #777 must NOT be treated as linked.
+cat > "$BIN_DIR/tea" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+case "${1:-} ${2:-}" in
+  "issues list")
+    cat <<'JSON'
+[
+  {"index":"546","title":"lane-brief + ci-wait orchestration tooling","assignees":[],"milestone":null,"labels":""},
+  {"index":"777","title":"unrelated downstream item","assignees":[],"milestone":null,"labels":""},
+  {"index":"999","title":"item only named inside the word hotfix","assignees":[],"milestone":null,"labels":""}
+]
+JSON
+    ;;
+  "pulls list")
+    cat <<'JSON'
+[
+  {"index":"547","title":"feat(framework/tools): orchestration helpers","head":"feat/orchestration-tools-lane-brief-ci-wait","body":"Two additive orchestration tools.\n\nCloses #546.\n\nLogin resolution is relevant to the #777 line of work but does not touch it.\nThis shipped as a hotfix #999 earlier — that bare reference must not link it.\n\nFixes #546\n"}
+]
+JSON
+    ;;
+  *)
+    echo "fake-tea: unhandled: $*" >&2; exit 1 ;;
+esac
+SH
+chmod +x "$BIN_DIR/tea"
+
+run_brief() { # $1 = script path
+  PATH="$BIN_DIR:$PATH" "$1" -r mosaic/stack -L test-login 2>/dev/null
+}
+
+# Extract the issue numbers under a named section header until the next blank line.
+section_nums() { # $1 = output  $2 = header-prefix
+  printf '%s\n' "$1" | awk -v h="$2" '
+    index($0,h)==1 {grab=1; next}
+    grab && /^[[:space:]]*$/ {grab=0}
+    grab && match($0, /#[0-9]+/) { print substr($0, RSTART+1, RLENGTH-1) }
+  '
+}
+
+fail() { echo "FAIL: $1" >&2; exit 1; }
+contains() { printf '%s\n' "$1" | grep -qx "$2"; }
+
+# ---------------------------------------------------------------------------
+# Fixed (current) script behavior
+# ---------------------------------------------------------------------------
+OUT="$(run_brief "$LANE_BRIEF")"
+CAND="$(section_nums "$OUT" 'DISPATCH CANDIDATES')"
+UNDER="$(section_nums "$OUT" 'WORK UNDERWAY')"
+
+echo "--- lane-brief output (fixed) ---"; printf '%s\n' "$OUT"
+echo "--- candidates: [$(printf '%s' "$CAND" | tr '\n' ' ')] underway: [$(printf '%s' "$UNDER" | tr '\n' ' ')] ---"
+
+contains "$UNDER" 546 || fail "#546 (PR body 'Closes #546') should be WORK UNDERWAY"
+contains "$CAND" 546 && fail "#546 must NOT be a dispatch candidate (it has an open PR)"
+contains "$CAND" 777 || fail "#777 (only a bare prose mention) should remain a dispatch candidate"
+contains "$UNDER" 777 && fail "#777 must NOT be work-underway — bare body mentions are not links"
+contains "$CAND" 999 || fail "#999 ('hotfix #999' — keyword is a substring) should remain a candidate"
+contains "$UNDER" 999 && fail "#999 must NOT be work-underway — word-boundary must reject 'hotfix'"
+echo "PASS: body closing-keyword link classifies #546 underway; bare #777 / substring #999 stay candidates"
+
+# ---------------------------------------------------------------------------
+# NON-VACUITY: revert the body-scan and prove #546 regresses to a candidate.
+# ---------------------------------------------------------------------------
+REVERTED="$SCRIPT_DIR/.lane-brief.reverted.$$.sh"
+trap 'rm -f "$REVERTED"' EXIT
+# Drop the PR_BODY_REFS contribution from the union (simulates the pre-fix script
+# that only looked at index/title/head). Sibling `source detect-platform.sh` still
+# resolves because the copy lives in the same dir.
+# shellcheck disable=SC2016  # single-quoted on purpose: sed needs the literal $PR_BODY_REFS
+sed 's/"\$PR_BODY_REFS"/""/' "$LANE_BRIEF" > "$REVERTED"
+chmod +x "$REVERTED"
+grep -q 'PR_BODY_REFS' "$REVERTED" || fail "revert sed anchor not found — test is stale"
+
+ROUT="$(run_brief "$REVERTED")"
+RCAND="$(section_nums "$ROUT" 'DISPATCH CANDIDATES')"
+RUNDER="$(section_nums "$ROUT" 'WORK UNDERWAY')"
+echo "--- candidates(reverted): [$(printf '%s' "$RCAND" | tr '\n' ' ')] underway: [$(printf '%s' "$RUNDER" | tr '\n' ' ')] ---"
+
+contains "$RCAND" 546 || fail "non-vacuity broken: reverted script should misclassify #546 as a candidate"
+contains "$RUNDER" 546 && fail "non-vacuity broken: reverted script should NOT mark #546 underway"
+echo "PASS (RED-on-revert): without the body-scan, #546 regresses to a dispatch candidate"
+
+echo "ALL PASS: test-lane-brief-pr-linkage.sh"

packages/mosaic/framework/tools/tmux/README.md

@@ -31,9 +31,12 @@ Prepends the preamble automatically (auto-detecting your own `host:session`) and
 delivers reliably to local OR remote panes.
 
 ```bash
-# Local target (same host)
+# Local target (same host, default tmux server)
 agent-send.sh -s <dst_session> -m "message"
 
+# Local target on a Mosaic fleet socket
+agent-send.sh -L mosaic-factory -s '=coder0' -m "message"
+
 # Remote target (over ssh)
 agent-send.sh -H user@host -s <dst_session> -m "message"
 
@@ -42,10 +45,27 @@ agent-send.sh -H user@host -s <dst_session> -f msg.txt
 echo "msg" | agent-send.sh -s <dst_session>
 ```
 
-Key flags: `-s` dst session (required) · `-H` ssh target for remote · `-n` dst
+Key flags: `-L` named tmux socket · `-s` dst session (required) · `-H` ssh target for remote · `-n` dst
 hostname for the preamble (else auto-resolved) · `-m`/`-f`/stdin body · `-S`
 override source label · `-v` verbose · `-r N` Enter-flush attempts.
 
+For durable fleet use, prefer exact tmux targets such as `=coder0`. The helper
+normalizes exact session targets to pane-qualified targets internally so pane
+commands do not fall back to tmux's prefix matching behavior.
+
+## Named socket isolation
+
+Durable Mosaic fleets should use a dedicated tmux socket, for example:
+
+```bash
+tmux -L mosaic-factory ls
+agent-send.sh -L mosaic-factory -s '=coder0' -m "status?"
+send-message.sh -L mosaic-factory -t '=coder0' -m "raw pane message"
+```
+
+This keeps fleet operations away from the user's default tmux server. It is the
+safe rollout path on hosts that already have manual tmux sessions.
+
 ## Why a helper exists (the submission gotcha)
 
 Pasting into an interactive REPL via raw `tmux send-keys` is unreliable: a
@@ -67,6 +87,7 @@ message crosses the wire as base64 (`-b`) to avoid all shell-quoting hazards.
 
 - `agent-send.sh` — inter-agent wrapper (preamble + local/remote dispatch).
 - `send-message.sh` — low-level reliable single-pane submitter (`-b` base64 input).
+- `test-send-message-socket.sh` — smoke test for named-socket isolation.
 
 ## Distribution
 

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -23,12 +23,13 @@
 #   the remote host; only bash + tmux + base64 (standard).
 #
 # USAGE
-#   agent-send.sh -s <dst_session> -m "message"                 # local target
-#   agent-send.sh -H user@host -s <dst_session> -m "message"    # remote target
-#   agent-send.sh -H user@host -n <dst_hostname> -s <sess> -f msg.txt
-#   echo "msg" | agent-send.sh -H user@host -s <dst_session>
+#   agent-send.sh [-L socket] -s <dst_session> -m "message"                 # local target
+#   agent-send.sh [-L socket] -H user@host -s <dst_session> -m "message"    # remote target
+#   agent-send.sh [-L socket] -H user@host -n <dst_hostname> -s <sess> -f msg.txt
+#   echo "msg" | agent-send.sh [-L socket] -H user@host -s <dst_session>
 #
 # OPTIONS
+#   -L NAME         tmux socket name passed to `tmux -L NAME` on the target host
 #   -s DST_SESSION  target tmux session (or session:window.pane)   [required]
 #   -H SSH_TARGET   ssh target (user@host) for a remote pane; omit for local
 #   -n DST_HOST     hostname to show in the preamble for the target.
@@ -47,12 +48,13 @@ set -uo pipefail
 SELF_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 SENDER="$SELF_DIR/send-message.sh"
 
-DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""
+DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""; SOCKET_NAME=""
 SRC_LABEL=""; RETRIES=2; VERBOSE=0
 usage() { sed -n '2,44p' "$0"; exit "${1:-3}"; }
 
-while getopts "s:H:n:m:f:S:r:vh" o; do
+while getopts "L:s:H:n:m:f:S:r:vh" o; do
   case "$o" in
+    L) SOCKET_NAME=$OPTARG ;;
     s) DST_SESSION=$OPTARG ;; H) SSH_TARGET=$OPTARG ;; n) DST_HOST=$OPTARG ;;
     m) MSG=$OPTARG ;; f) FILE=$OPTARG ;; S) SRC_LABEL=$OPTARG ;;
     r) RETRIES=$OPTARG ;; v) VERBOSE=1 ;; h) usage 0 ;; *) usage 3 ;;
@@ -70,8 +72,12 @@ fi
 
 # Source label: this agent's host:session (auto-detected, overridable).
 if [ -z "$SRC_LABEL" ]; then
+  tmux_cmd=(tmux)
+  if [ -n "$SOCKET_NAME" ]; then
+    tmux_cmd+=(-L "$SOCKET_NAME")
+  fi
   src_host=$(hostname -s 2>/dev/null || echo "?")
-  src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
+  src_sess=$("${tmux_cmd[@]}" display-message -p '#S' 2>/dev/null || echo "?")
   SRC_LABEL="${src_host}:${src_sess}"
 fi
 
@@ -89,12 +95,16 @@ FULL="${PREAMBLE} ${MSG}"
 B64=$(printf '%s' "$FULL" | base64 -w0)
 
 vflag=""; [ "$VERBOSE" = 1 ] && vflag="-v"
+socket_args=()
+if [ -n "$SOCKET_NAME" ]; then
+  socket_args=(-L "$SOCKET_NAME")
+fi
 
 if [ -z "$SSH_TARGET" ]; then
   # Local pane: call the canonical sender directly.
-  exec "$SENDER" -t "$DST_SESSION" -b "$B64" -r "$RETRIES" $vflag
+  exec "$SENDER" "${socket_args[@]}" -t "$DST_SESSION" -b "$B64" -r "$RETRIES" $vflag
 else
   # Remote pane: ship the sender over ssh and run it local to the target.
   ssh -o ConnectTimeout=10 "$SSH_TARGET" \
-      "bash -s -- -t '$DST_SESSION' -b '$B64' -r '$RETRIES' $vflag" < "$SENDER"
+      "bash -s -- ${socket_args[*]@Q} -t '$DST_SESSION' -b '$B64' -r '$RETRIES' $vflag" < "$SENDER"
 fi

packages/mosaic/framework/tools/tmux/send-message.sh

@@ -13,12 +13,13 @@
 #   no-op in Claude Code, so the double-Enter is safe.
 #
 # USAGE
-#   send-message.sh -t <target> -m "message"
-#   send-message.sh -t <target> -f <file>
-#   echo "message" | send-message.sh -t <target>
-#   ssh host bash -s -- -t <target> -b "$(base64 -w0 <<<msg)" < send-message.sh
+#   send-message.sh [-L socket_name] -t <target> -m "message"
+#   send-message.sh [-L socket_name] -t <target> -f <file>
+#   echo "message" | send-message.sh [-L socket_name] -t <target>
+#   ssh host bash -s -- -L socket -t <target> -b "$(base64 -w0 <<<msg)" < send-message.sh
 #
 # OPTIONS
+#   -L NAME     tmux socket name passed to `tmux -L NAME` (optional)
 #   -t TARGET   tmux target: session, or session:window.pane  [required]
 #   -m MESSAGE  message text (single- or multi-line)
 #   -f FILE     read message from FILE instead of -m
@@ -34,11 +35,12 @@
 #   3  usage error
 set -uo pipefail
 
-TARGET=""; MSG=""; FILE=""; B64=""; RETRIES=2; VERBOSE=0
+SOCKET_NAME=""; TARGET=""; MSG=""; FILE=""; B64=""; RETRIES=2; VERBOSE=0
 usage() { sed -n '2,34p' "$0"; exit "${1:-3}"; }
 
-while getopts "t:m:f:b:r:vh" o; do
+while getopts "L:t:m:f:b:r:vh" o; do
   case "$o" in
+    L) SOCKET_NAME=$OPTARG ;;
     t) TARGET=$OPTARG ;; m) MSG=$OPTARG ;; f) FILE=$OPTARG ;; b) B64=$OPTARG ;;
     r) RETRIES=$OPTARG ;; v) VERBOSE=1 ;; h) usage 0 ;; *) usage 3 ;;
   esac
@@ -51,8 +53,21 @@ elif [ -z "$MSG" ] && [ ! -t 0 ]; then MSG=$(cat)
 fi
 [ -n "$MSG" ] || { echo "ERROR: empty message (use -m, -f, or stdin)" >&2; exit 3; }
 
+tmux_cmd=(tmux)
+if [ -n "$SOCKET_NAME" ]; then
+  tmux_cmd+=(-L "$SOCKET_NAME")
+fi
+
+# tmux accepts `=session` for some commands, but pane-level commands such as
+# capture-pane require a pane-qualified target. Keep exact-session addressing
+# convenient while avoiding accidental prefix matches.
+EFFECTIVE_TARGET=$TARGET
+if [[ "$TARGET" == =* && "$TARGET" != *:* ]]; then
+  EFFECTIVE_TARGET="${TARGET}:0.0"
+fi
+
 # Target must resolve to a live pane.
-if ! tmux list-panes -t "$TARGET" >/dev/null 2>&1; then
+if ! "${tmux_cmd[@]}" list-panes -t "$EFFECTIVE_TARGET" >/dev/null 2>&1; then
   echo "ERROR: tmux target not found: $TARGET" >&2; exit 1
 fi
 
@@ -62,18 +77,18 @@ snippet=$(printf '%s' "$MSG" | tr '\n' ' ' | tr -s ' ' | sed 's/[^[:print:]]//g'
 
 # 1) Paste the body as a bracketed paste so multi-line content does not submit
 #    line-by-line. load-buffer/paste-buffer is far safer than `send-keys -l`.
-printf '%s' "$MSG" | tmux load-buffer -b __mosaic_send -
+printf '%s' "$MSG" | "${tmux_cmd[@]}" load-buffer -b __mosaic_send -
 # -p = bracketed paste when the client supports it; fall back if not.
-tmux paste-buffer -d -p -b __mosaic_send -t "$TARGET" 2>/dev/null \
-  || tmux paste-buffer -d -b __mosaic_send -t "$TARGET"
+"${tmux_cmd[@]}" paste-buffer -d -p -b __mosaic_send -t "$EFFECTIVE_TARGET" 2>/dev/null \
+  || "${tmux_cmd[@]}" paste-buffer -d -b __mosaic_send -t "$EFFECTIVE_TARGET"
 sleep 0.5
 
 # 2) Submit, then verify; flush with another Enter if it is still a draft.
 status="sent"
 for attempt in $(seq 1 $((RETRIES + 1))); do
-  tmux send-keys -t "$TARGET" Enter
+  "${tmux_cmd[@]}" send-keys -t "$EFFECTIVE_TARGET" Enter
   sleep 1.2
-  pane=$(tmux capture-pane -t "$TARGET" -p 2>/dev/null)
+  pane=$("${tmux_cmd[@]}" capture-pane -t "$EFFECTIVE_TARGET" -p 2>/dev/null)
 
   if printf '%s' "$pane" | grep -qF "$QUEUED_RE"; then
     status="queued"; break

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+SEND_MESSAGE="$SCRIPT_DIR/send-message.sh"
+AGENT_SEND="$SCRIPT_DIR/agent-send.sh"
+SOCKET="mosaic-test-$RANDOM-$$"
+TARGET="target-$RANDOM"
+DEFAULT_TARGET="default-target-$RANDOM"
+TMPDIR=$(mktemp -d)
+trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; tmux kill-session -t "$DEFAULT_TARGET" >/dev/null 2>&1 || true; rm -rf "$TMPDIR"' EXIT
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+require_tmux() {
+  command -v tmux >/dev/null 2>&1 || fail "tmux is required"
+}
+
+capture_named() {
+  tmux -L "$SOCKET" capture-pane -t "=$TARGET:0.0" -p
+}
+
+capture_default() {
+  tmux capture-pane -t "=$DEFAULT_TARGET:0.0" -p
+}
+
+require_tmux
+
+tmux -L "$SOCKET" new-session -d -s "$TARGET" -c "$TMPDIR" 'bash --noprofile --norc -i'
+tmux new-session -d -s "$DEFAULT_TARGET" -c "$TMPDIR" 'bash --noprofile --norc -i'
+
+"$SEND_MESSAGE" -L "$SOCKET" -t "=$TARGET" -m "named socket hello" >/tmp/send-message-named.out
+sleep 0.2
+capture_named | grep -qF "named socket hello" || fail "send-message.sh did not deliver to named socket"
+if capture_default | grep -qF "named socket hello"; then
+  fail "send-message.sh leaked named-socket message to default tmux server"
+fi
+
+"$AGENT_SEND" -L "$SOCKET" -S "tester:source" -s "=$TARGET" -m "agent socket hello" >/tmp/agent-send-named.out
+sleep 0.2
+capture_named | grep -qF "[tester:source ->" || fail "agent-send.sh did not include preamble"
+capture_named | grep -qF "agent socket hello" || fail "agent-send.sh did not deliver to named socket"
+if capture_default | grep -qF "agent socket hello"; then
+  fail "agent-send.sh leaked named-socket message to default tmux server"
+fi
+
+echo "ok - named tmux socket send tools"

packages/mosaic/framework/tools/woodpecker/README.md

@@ -27,10 +27,11 @@ A Woodpecker API token is required. To configure:
 ## Scripts
 
 | Script                | Purpose                                      |
-| --------------------- | ------------------------------------------- |
+| --------------------- | -------------------------------------------- |
 | `pipeline-list.sh`    | List recent pipelines for a repo             |
 | `pipeline-status.sh`  | Get status of a specific or latest pipeline  |
 | `pipeline-trigger.sh` | Trigger a new pipeline build                 |
+| `ci-wait.sh`          | Block until pipeline(s) reach terminal state |
 
 ## Common Options
 
@@ -55,4 +56,7 @@ A Woodpecker API token is required. To configure:
 
 # Trigger a build on a specific branch
 ~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh -b feature/my-branch
+
+# Block until one or more pipelines finish (event-driven CI wait)
+~/.config/mosaic/tools/woodpecker/ci-wait.sh -r usc/uconnect -n 3917 -n 3918
 ```

packages/mosaic/framework/tools/woodpecker/ci-wait.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# ci-wait.sh — block until one or more Woodpecker pipelines reach terminal state.
+#
+# Problem it solves: orchestrators hand-author a `while true; curl .../repos/1/pipelines/$n
+# ...; sleep` loop for every CI wait. Those loops HARDCODE Woodpecker repo id 1 (only
+# correct for whichever repo happens to be id 1), re-implement URL building with raw
+# curl, and tend to get armed as tight <300s ScheduleWakeup polls (each poll = a full
+# wake+reload+recheck cycle). This encapsulates the loop once, on top of the existing
+# `pipeline-status.sh` wrapper (which resolves repo->id correctly and is instance-aware),
+# so a CI wait becomes a one-liner.
+#
+# Intended use: as the COMMAND of a Monitor / event-driven re-invoke (primary), paired
+# with a single long (>=1500s) timed fallback — NOT as a tight standalone poll.
+#
+# Usage:
+#   ci-wait.sh -r <owner/repo> -n <num> [-n <num> ...] [-a <instance>] [-i <interval>] [-t <timeout>]
+#   ci-wait.sh -r usc/uconnect -n 3917 -n 3918              # wait for both, infer instance
+#   ci-wait.sh -r usc/uconnect -n 3922 -a usc -i 30 -t 2400
+#
+# Instance is inferred from the owner (usc->usc, mosaicstack/mosaic->mosaic) unless -a given.
+# Exit: 0 = all pipelines terminal AND all 'success'; 1 = >=1 terminal non-success;
+#       2 = usage/precondition error; 3 = timeout before all terminal.
+set -euo pipefail
+
+# Resolve pipeline-status.sh as a sibling, matching how the woodpecker tools source
+# _lib.sh — works under the installed runtime AND an in-repo checkout, no MOSAIC_HOME dep.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PS="$SCRIPT_DIR/pipeline-status.sh"
+
+REPO="" INSTANCE="" INTERVAL=30 TIMEOUT=3600
+NUMS=()
+while getopts "r:n:a:i:t:h" opt; do
+  case "$opt" in
+    r) REPO="$OPTARG" ;;
+    n) NUMS+=("$OPTARG") ;;
+    a) INSTANCE="$OPTARG" ;;
+    i) INTERVAL="$OPTARG" ;;
+    t) TIMEOUT="$OPTARG" ;;
+    h) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "see -h" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$REPO" ]] || { echo "FATAL: -r <owner/repo> required" >&2; exit 2; }
+[[ ${#NUMS[@]} -gt 0 ]] || { echo "FATAL: at least one -n <pipeline-number> required" >&2; exit 2; }
+[[ -x "$PS" ]] || { echo "FATAL: pipeline-status.sh not found/executable at $PS" >&2; exit 2; }
+
+# Infer Woodpecker instance from owner unless overridden (matches the git-wrapper convention).
+if [[ -z "$INSTANCE" ]]; then
+  case "${REPO%%/*}" in
+    usc|USC) INSTANCE=usc ;;
+    mosaicstack|mosaic) INSTANCE=mosaic ;;
+    *) echo "FATAL: cannot infer Woodpecker instance for owner '${REPO%%/*}' — pass -a <instance>" >&2; exit 2 ;;
+  esac
+fi
+
+command -v jq >/dev/null || { echo "FATAL: jq not found" >&2; exit 2; }
+
+TERMINAL_RE='^(success|failure|error|killed|declined|blocked)$'
+declare -A STATE=()        # num -> terminal status, once reached
+start=$(date +%s 2>/dev/null || echo 0)
+
+echo "ci-wait: $REPO pipelines [${NUMS[*]}] (instance=$INSTANCE, every ${INTERVAL}s, timeout ${TIMEOUT}s)"
+while true; do
+  for n in "${NUMS[@]}"; do
+    [[ -n "${STATE[$n]:-}" ]] && continue
+    s=$("$PS" -r "$REPO" -n "$n" -a "$INSTANCE" -f json 2>/dev/null | jq -r '.status // empty' 2>/dev/null || true)
+    if [[ "$s" =~ $TERMINAL_RE ]]; then
+      STATE[$n]="$s"
+      echo "  pipeline $n TERMINAL: $s"
+    fi
+  done
+  # all terminal?
+  if [[ ${#STATE[@]} -eq ${#NUMS[@]} ]]; then
+    bad=0
+    for n in "${NUMS[@]}"; do [[ "${STATE[$n]}" == "success" ]] || bad=1; done
+    if [[ $bad -eq 0 ]]; then echo "ci-wait: ALL SUCCESS"; exit 0; fi
+    echo "ci-wait: all terminal, NOT all success — $(for n in "${NUMS[@]}"; do printf '%s=%s ' "$n" "${STATE[$n]}"; done)"
+    exit 1
+  fi
+  now=$(date +%s 2>/dev/null || echo 0)
+  if [[ "$start" != 0 && $((now - start)) -ge $TIMEOUT ]]; then
+    echo "ci-wait: TIMEOUT after ${TIMEOUT}s — pending: $(for n in "${NUMS[@]}"; do [[ -z "${STATE[$n]:-}" ]] && printf '%s ' "$n"; done)"
+    exit 3
+  fi
+  sleep "$INTERVAL"
+done

packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Regression harness for ci-wait.sh terminal-state aggregation and exit codes.
+#
+# ci-wait.sh wraps pipeline-status.sh and blocks until every requested pipeline
+# reaches a terminal Woodpecker state, then maps the aggregate to an exit code.
+# That contract is what callers arm a Monitor/timed-fallback around, so it must be
+# exact. This harness drives ci-wait.sh against a stub pipeline-status.sh whose
+# per-pipeline status is fixture-controlled, and asserts the full exit matrix:
+#
+#   0 = every pipeline terminal AND all 'success'
+#   1 = every pipeline terminal, at least one non-success
+#   2 = usage/precondition error (missing -n)
+#   3 = timeout before all pipelines terminal
+#
+# Non-vacuity: each case pins a DISTINCT exit code to a distinct fixture, so a
+# regression in success-aggregation (case 0 vs 1), terminal detection (case 3),
+# or arg validation (case 2) flips exactly one assertion RED.
+
+set -euo pipefail
+
+CIW_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/ci-wait.sh"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-wait-exit-matrix}"
+TOOL_DIR="$WORK_DIR/tool"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$TOOL_DIR"
+
+# ci-wait.sh resolves pipeline-status.sh as a sibling ($SCRIPT_DIR/pipeline-status.sh),
+# so we run a COPY of ci-wait.sh next to a stub sibling we control.
+cp "$CIW_SRC" "$TOOL_DIR/ci-wait.sh"
+chmod +x "$TOOL_DIR/ci-wait.sh"
+
+# Stub pipeline-status.sh: emits {"status":"<s>"} where <s> comes from env
+# CIW_STATUS_<num> (default "running" = non-terminal, drives the timeout path).
+cat > "$TOOL_DIR/pipeline-status.sh" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+num=""
+while getopts "r:n:a:f:" opt; do case "$opt" in n) num="$OPTARG" ;; *) : ;; esac; done
+var="CIW_STATUS_${num}"
+printf '{"status":"%s"}\n' "${!var:-running}"
+SH
+chmod +x "$TOOL_DIR/pipeline-status.sh"
+
+CIW="$TOOL_DIR/ci-wait.sh"
+
+run_expect() { # $1 = expected exit  $2 = label ; rest = args
+  local want="$1" label="$2"; shift 2
+  local rc=0
+  "$CIW" "$@" >/dev/null 2>&1 || rc=$?
+  if [[ "$rc" -ne "$want" ]]; then
+    echo "FAIL [$label]: expected exit $want, got $rc" >&2; exit 1
+  fi
+  echo "PASS [$label]: exit $rc"
+}
+
+# 0 — both pipelines terminal + success
+CIW_STATUS_100=success CIW_STATUS_101=success \
+  run_expect 0 "all-success" -r mosaic/stack -n 100 -n 101 -a mosaic -i 1 -t 30
+
+# 1 — both terminal, one failure
+CIW_STATUS_100=success CIW_STATUS_101=failure \
+  run_expect 1 "terminal-not-success" -r mosaic/stack -n 100 -n 101 -a mosaic -i 1 -t 30
+
+# 1 — other terminal non-success states still map to 1 (error/killed)
+CIW_STATUS_100=error CIW_STATUS_101=killed \
+  run_expect 1 "terminal-error-killed" -r mosaic/stack -n 100 -n 101 -a mosaic -i 1 -t 30
+
+# 3 — a pipeline never reaches terminal state before timeout
+CIW_STATUS_100=success CIW_STATUS_101=running \
+  run_expect 3 "timeout-pending" -r mosaic/stack -n 100 -n 101 -a mosaic -i 1 -t 0
+
+# 2 — usage error: no -n
+run_expect 2 "usage-missing-n" -r mosaic/stack -a mosaic
+
+echo "ALL PASS: test-ci-wait-exit-matrix.sh"

packages/mosaic/src/commands/launch.spec.ts

@@ -1,6 +1,15 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
 import { Command } from 'commander';
-import { buildPiSkillArgs, registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  buildPiSkillArgs,
+  enumerateSkillDirs,
+  piForceSkillNames,
+  registerRuntimeLaunchers,
+  type RuntimeLaunchHandler,
+} from './launch.js';
 
 /**
  * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
@@ -23,6 +32,7 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
 }
 
 const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
+const fakeForced = ['--skill', '/skills/mosaic-tools'];
 
 // `process.exit` returns `never`, so vi.spyOn demands a replacement with the
 // same signature. We throw from the mock to short-circuit into test-land.
@@ -66,16 +76,42 @@ describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
 });
 
 describe('buildPiSkillArgs', () => {
-  it('defaults to disabling Pi skill discovery to keep startup context small', () => {
-    expect(buildPiSkillArgs([], {}, fakeSkills)).toEqual(['--no-skills']);
+  it('disables auto-discovery but force-loads fleet-critical skills by default', () => {
+    expect(buildPiSkillArgs([], {}, fakeSkills, fakeForced)).toEqual([
+      '--no-skills',
+      '--skill',
+      '/skills/mosaic-tools',
+    ]);
   });
 
-  it('keeps explicit user skills while disabling automatic discovery', () => {
-    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills)).toEqual(['--no-skills']);
+  it('ignores _runtimeArgs (user --skill flags reach Pi via the launch handler, not here)', () => {
+    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills, fakeForced)).toEqual([
+      '--no-skills',
+      '--skill',
+      '/skills/mosaic-tools',
+    ]);
   });
 
-  it('supports legacy all-skills mode without double-loading settings skills', () => {
-    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills)).toEqual([
+  it('emits only --no-skills when no forced skills are present on disk', () => {
+    expect(buildPiSkillArgs([], {}, fakeSkills, [])).toEqual(['--no-skills']);
+  });
+
+  it('all-skills mode merges the forced set in without duplicating discovered skills', () => {
+    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills, fakeForced)).toEqual([
+      '--no-skills',
+      '--skill',
+      '/skills/test-driven-development',
+      '--skill',
+      '/skills/pdf',
+      '--skill',
+      '/skills/mosaic-tools',
+    ]);
+  });
+
+  it('all-skills mode does not double-load a forced skill already discovered', () => {
+    expect(
+      buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills, ['--skill', '/skills/pdf']),
+    ).toEqual([
       '--no-skills',
       '--skill',
       '/skills/test-driven-development',
@@ -84,8 +120,117 @@ describe('buildPiSkillArgs', () => {
     ]);
   });
 
-  it('supports native Pi discovery when explicitly requested', () => {
-    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills)).toEqual([]);
+  it('force-loads fleet skills under native Pi discovery when not already discoverable', () => {
+    // Empty native set => Pi would not find mosaic-tools on its own, so force it.
+    expect(
+      buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills, fakeForced, new Set()),
+    ).toEqual(['--skill', '/skills/mosaic-tools']);
+  });
+
+  it('discover mode drops a forced skill Pi already discovers natively (no double-load)', () => {
+    // mosaic-tools is reachable from a Pi native root, so native discovery
+    // covers it — forcing it again would register the same skill twice.
+    expect(
+      buildPiSkillArgs(
+        [],
+        { MOSAIC_PI_SKILL_MODE: 'discover' },
+        fakeSkills,
+        fakeForced,
+        new Set(['/skills/mosaic-tools']),
+      ),
+    ).toEqual([]);
+  });
+
+  it('discover mode keeps a forced skill that no native root provides', () => {
+    expect(
+      buildPiSkillArgs(
+        [],
+        { MOSAIC_PI_SKILL_MODE: 'discover' },
+        fakeSkills,
+        fakeForced,
+        new Set(['/skills/some-other-skill']),
+      ),
+    ).toEqual(['--skill', '/skills/mosaic-tools']);
+  });
+
+  it('discover mode collapses a forced skill listed twice to a single --skill', () => {
+    // Mirror 'all' mode: intra-forced-set duplicates (same realpath) dedup.
+    expect(
+      buildPiSkillArgs(
+        [],
+        { MOSAIC_PI_SKILL_MODE: 'discover' },
+        fakeSkills,
+        ['--skill', '/skills/mosaic-tools', '--skill', '/skills/mosaic-tools'],
+        new Set(),
+      ),
+    ).toEqual(['--skill', '/skills/mosaic-tools']);
+  });
+});
+
+describe('enumerateSkillDirs (real FS)', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'mosaic-skills-'));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  function makeSkill(parent: string, name: string): string {
+    const dir = join(parent, name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'SKILL.md'), `# ${name}\n`);
+    return dir;
+  }
+
+  it('accepts a symlinked skill dir (regression: synced fleet skills are symlinks)', () => {
+    // Real skill lives under `canonical/`; the scanned root only has a symlink to it.
+    const canonical = makeSkill(join(root, 'canonical'), 'mosaic-tools');
+    const scanned = join(root, 'scanned');
+    mkdirSync(scanned, { recursive: true });
+    symlinkSync(canonical, join(scanned, 'mosaic-tools'), 'dir');
+
+    expect(enumerateSkillDirs([scanned])).toEqual(['--skill', join(scanned, 'mosaic-tools')]);
+  });
+
+  it('dedups by real path when the same skill is reachable from two roots', () => {
+    // Root A holds the real dir; root B symlinks to it — one --skill, not two.
+    const rootA = join(root, 'a');
+    const rootB = join(root, 'b');
+    const real = makeSkill(rootA, 'mosaic-tools');
+    mkdirSync(rootB, { recursive: true });
+    symlinkSync(real, join(rootB, 'mosaic-tools'), 'dir');
+
+    expect(enumerateSkillDirs([rootA, rootB])).toEqual(['--skill', real]);
+  });
+
+  it('skips directories without a SKILL.md and missing roots', () => {
+    mkdirSync(join(root, 'present', 'not-a-skill'), { recursive: true });
+    makeSkill(join(root, 'present'), 'real-skill');
+
+    expect(enumerateSkillDirs([join(root, 'present'), join(root, 'does-not-exist')])).toEqual([
+      '--skill',
+      join(root, 'present', 'real-skill'),
+    ]);
+  });
+});
+
+describe('piForceSkillNames', () => {
+  it('defaults to mosaic-tools when MOSAIC_PI_FORCE_SKILLS is unset', () => {
+    expect(piForceSkillNames({})).toEqual(['mosaic-tools']);
+  });
+
+  it('treats an empty string as "disable force-loading" (distinct from unset)', () => {
+    expect(piForceSkillNames({ MOSAIC_PI_FORCE_SKILLS: '' })).toEqual([]);
+  });
+
+  it('parses a colon list, trimming blanks and whitespace', () => {
+    expect(piForceSkillNames({ MOSAIC_PI_FORCE_SKILLS: 'mosaic-tools: mosaic-gitea ::' })).toEqual([
+      'mosaic-tools',
+      'mosaic-gitea',
+    ]);
   });
 });
 

packages/mosaic/src/commands/launch.ts

@@ -6,7 +6,15 @@
  */
 
 import { execFileSync, execSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+} from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -428,25 +436,74 @@ function ensureRuntimeConfig(runtime: RuntimeName, destPath: string): void {
 
 // ─── Pi skill/extension discovery ────────────────────────────────────────────
 
-function discoverPiSkills(): string[] {
+/** Resolve a skill dir to its canonical real path so symlinked duplicates
+ * (e.g. ~/.pi/agent/skills/X -> ~/.config/mosaic/skills/X) collapse to one key.
+ * Falls back to the literal path if it can't be resolved (e.g. broken link). */
+function skillRealPath(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+/** Skill roots Pi auto-discovers natively (no `--skill` needed): its global
+ * skills dir and the project-local one relative to the launch cwd. */
+function piNativeSkillRoots(cwd: string = process.cwd()): string[] {
+  return [join(homedir(), '.pi', 'agent', 'skills'), join(cwd, '.pi', 'skills')];
+}
+
+/** Enumerate skill dirs under a set of roots, deduped by real path. A directory
+ * counts as a skill when it (or its symlink target) contains a SKILL.md.
+ * Exported for tests (real-FS coverage of symlink acceptance + realpath dedup). */
+export function enumerateSkillDirs(roots: string[]): string[] {
+  const seen = new Set<string>();
   const args: string[] = [];
-  for (const skillsRoot of [join(MOSAIC_HOME, 'skills'), join(MOSAIC_HOME, 'skills-local')]) {
+  for (const skillsRoot of roots) {
     if (!existsSync(skillsRoot)) continue;
     try {
       for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
+        // Synced fleet skills land as symlinks, so accept both dirs and links.
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
         const skillDir = join(skillsRoot, entry.name);
-        if (existsSync(join(skillDir, 'SKILL.md'))) {
+        if (!existsSync(join(skillDir, 'SKILL.md'))) continue;
+        const key = skillRealPath(skillDir);
+        if (seen.has(key)) continue;
+        seen.add(key);
         args.push('--skill', skillDir);
       }
-      }
     } catch {
-      // skip
+      // skip unreadable roots
     }
   }
   return args;
 }
 
+/** Every skill dir Pi would link under `MOSAIC_PI_SKILL_MODE=all`: the Mosaic
+ * global/local catalog plus Pi's own native roots. `--no-skills` suppresses
+ * native auto-discovery, so 'all' must re-add the native roots explicitly or
+ * they would be silently dropped. Deduped by real path. */
+function discoverPiSkills(cwd: string = process.cwd()): string[] {
+  return enumerateSkillDirs([
+    join(MOSAIC_HOME, 'skills'),
+    join(MOSAIC_HOME, 'skills-local'),
+    ...piNativeSkillRoots(cwd),
+  ]);
+}
+
+/** Real paths of skills Pi will auto-discover from its native roots. Used to
+ * drop redundant force-loads in 'discover' mode (which keeps native discovery
+ * on) so the same skill is not registered twice. */
+function piNativeSkillRealPaths(cwd: string = process.cwd()): Set<string> {
+  const args = enumerateSkillDirs(piNativeSkillRoots(cwd));
+  const set = new Set<string>();
+  for (let i = 1; i < args.length; i += 2) {
+    const dir = args[i];
+    if (dir !== undefined) set.add(skillRealPath(dir));
+  }
+  return set;
+}
+
 type PiSkillMode = 'none' | 'all' | 'discover';
 
 function normalizePiSkillMode(env: NodeJS.ProcessEnv): PiSkillMode {
@@ -455,22 +512,96 @@ function normalizePiSkillMode(env: NodeJS.ProcessEnv): PiSkillMode {
   return 'none';
 }
 
+/**
+ * Fleet-critical Pi skills that are force-loaded on every Pi launch regardless
+ * of MOSAIC_PI_SKILL_MODE. They cover the highest-frequency cross-agent and
+ * git-provider operations where Pi workers historically improvised raw CLIs
+ * (raw `tmux send-keys`, raw `tea`/`gh`/`glab`) instead of the maintained
+ * `~/.config/mosaic/tools/` wrappers.
+ *
+ * An explicit `--skill <dir>` overrides `--no-skills` for that path, so forcing
+ * a single targeted skill surfaces the must-use toolkit without loading the full
+ * ~100-skill catalog (context bloat). Missing skills are skipped silently, so
+ * this is a no-op until the named skill is synced into ~/.config/mosaic/skills/.
+ *
+ * Override with MOSAIC_PI_FORCE_SKILLS (colon-separated skill dir names; set to
+ * an empty string to disable force-loading entirely).
+ */
+const DEFAULT_PI_FORCE_SKILLS = ['mosaic-tools'];
+
+export function piForceSkillNames(env: NodeJS.ProcessEnv): string[] {
+  const override = env['MOSAIC_PI_FORCE_SKILLS'];
+  if (override === undefined) return DEFAULT_PI_FORCE_SKILLS;
+  return override
+    .split(':')
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
+function forcedPiSkillArgs(env: NodeJS.ProcessEnv = process.env): string[] {
+  const args: string[] = [];
+  for (const name of piForceSkillNames(env)) {
+    const skillDir = join(MOSAIC_HOME, 'skills', name);
+    if (existsSync(join(skillDir, 'SKILL.md'))) {
+      args.push('--skill', skillDir);
+    }
+  }
+  return args;
+}
+
+/** Concatenate `--skill <dir>` arg groups, dropping any skill already seen.
+ * Dedup is by real path, so a forced skill and the same skill reached via a
+ * different (e.g. symlinked) directory collapse to a single `--skill`. */
+function mergeSkillArgs(...groups: string[][]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const group of groups) {
+    for (let i = 0; i < group.length; i += 2) {
+      const dir = group[i + 1];
+      if (group[i] !== '--skill' || dir === undefined) continue;
+      const key = skillRealPath(dir);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push('--skill', dir);
+    }
+  }
+  return out;
+}
+
 export function buildPiSkillArgs(
   _runtimeArgs: string[],
   env: NodeJS.ProcessEnv = process.env,
   discoveredSkillArgs: string[] = discoverPiSkills(),
+  forcedSkillArgs: string[] = forcedPiSkillArgs(env),
+  nativeSkillRealPaths: Set<string> = piNativeSkillRealPaths(),
 ): string[] {
   const mode = normalizePiSkillMode(env);
 
   if (mode === 'discover') {
-    return [];
+    // Native Pi discovery stays on, so only force-load fleet skills it will NOT
+    // already find under its native roots — otherwise the same skill is
+    // registered twice (once natively, once via --skill). mergeSkillArgs first
+    // collapses any intra-forced-set realpath duplicates, mirroring 'all' mode.
+    const deduped = mergeSkillArgs(forcedSkillArgs);
+    const out: string[] = [];
+    for (let i = 0; i < deduped.length; i += 2) {
+      const dir = deduped[i + 1];
+      if (deduped[i] !== '--skill' || dir === undefined) continue;
+      if (nativeSkillRealPaths.has(skillRealPath(dir))) continue;
+      out.push('--skill', dir);
+    }
+    return out;
   }
 
   if (mode === 'all') {
-    return ['--no-skills', ...discoveredSkillArgs];
+    // 'all' links the full catalog; merge in the forced set so fleet-critical
+    // skills are guaranteed present even if they live only under skills-local/.
+    // discoverPiSkills already covers Pi's native roots, which `--no-skills`
+    // would otherwise suppress.
+    return ['--no-skills', ...mergeSkillArgs(discoveredSkillArgs, forcedSkillArgs)];
   }
 
-  return ['--no-skills'];
+  return ['--no-skills', ...forcedSkillArgs];
 }
 
 function discoverPiExtension(): string[] {

scratchpads/2026-06-19-tmux-fleet-durable-install-plan.md

@@ -0,0 +1,755 @@
+# Durable tmux Fleet Installation Plan
+
+> **For Mosaic/Hermes:** This is an implementation plan for making the tmux-backed Mosaic software-factory fleet durable on this server and reusable in generic Mosaic Stack installs. Keep local USC/Mosaic defaults in profiles; keep framework behavior customizable.
+
+**Goal:** Add a supported Mosaic tmux-fleet installation path: holder-owned tmux server, per-agent reusable sessions, reliable send/reset/status tools, local roster customization, and a documented cutover for this server.
+
+**Architecture:** Mosaic should ship generic tmux fleet primitives in the framework, then layer local rosters through configuration. The holder service owns the tmux socket; each agent service joins the holder-owned server and runs `mosaic yolo <runtime>`. The orchestrator addresses agents through `mosaic agent ...` abstractions so tmux can later be replaced by Matrix-backed agent comms without changing mission flow.
+
+**Reference:** AI Guide `playbooks/tmux-fleet.md` at commit `2a0b0b5` documents the organization-neutral holder-service pattern, exact-match `=<name>` stop targets, and coupled-server cutover/verification sequence. The Stack implementation should treat that as the lifecycle model and keep concrete Mosaic unit/tooling details here.
+
+**Tech Stack:** Bash, tmux, user systemd units, Mosaic CLI/framework installer, JSON/YAML roster config, existing `packages/mosaic/framework/tools/tmux/{agent-send.sh,send-message.sh}`.
+
+---
+
+## Current evidence from this server
+
+Checked 2026-06-19:
+
+- Host: `W-jarvis`
+- User: `jarvis`
+- tmux: `/usr/bin/tmux`, version `3.4`
+- user systemd: active
+- existing tmux sessions: `ai-bma-0`, `dyor-1`, `melaniewoltje-3`, `sage-2`
+- existing Mosaic runtime: `/home/jarvis/.npm-global/bin/mosaic`, version `0.0.31`
+- installed `~/.config/mosaic/tools/tmux` was not present even though the stack repo contains `packages/mosaic/framework/tools/tmux/`
+
+Implication: do not kill the current tmux server casually. This server has active ad-hoc/service sessions. The durable fleet cutover must be planned, with either a separate socket first or a scheduled fleet recycle.
+
+## Design decisions
+
+### 1. Generic framework, local profile
+
+The Mosaic framework should ship:
+
+- systemd unit templates;
+- tmux fleet CLI wrappers;
+- roster schema and examples;
+- install/enable/status/reset commands;
+- docs and verification scripts.
+
+Local environments should provide:
+
+- agent names;
+- runtime per slot (`claude`, `pi`, `codex`, etc.);
+- default role class;
+- launch directory;
+- optional kickstart prompt;
+- model/provider hints;
+- transport selection (`tmux` now, `matrix` later).
+
+Do not bake the USC roster into generic install code. Ship it as an example profile.
+
+### 2. Durable sessions, disposable task context
+
+Session names are durable operational addresses. Task persona is disposable. Reusable worker slots should be reset with `/clear` or `/new` and then receive a fresh task kickstart.
+
+Persistent/semi-persistent personas:
+
+- lead orchestrator;
+- final/adversarial reviewer;
+- architecture/enhancement lane.
+
+Disposable slots:
+
+- implementers;
+- ordinary reviewers;
+- security reviewers unless actively holding a security mission.
+
+### 3. Transport abstraction now
+
+Add commands around tmux instead of calling tmux directly from orchestration:
+
+```bash
+mosaic agent send <agent> --message "..."
+mosaic agent status [--json]
+mosaic agent reset <agent> [--clear|--new]
+mosaic agent roster [--json]
+mosaic fleet install|start|stop|restart|status|verify
+```
+
+Today these call tmux/systemd. Later the same command surface can target Matrix or per-agent gateways.
+
+### 4. Avoid shared-server ownership bug
+
+Use the AI Guide holder pattern:
+
+```text
+mosaic-tmux-holder.service owns the tmux server/socket
+mosaic-agent@<name>.service joins the existing holder-owned socket
+ExecStop kills only session =<name>
+```
+
+Use exact tmux targets: `=<session>`.
+
+### 5. Prefer separate named socket for Mosaic factory
+
+To avoid disturbing existing tmux work, the default fleet should use a named socket such as:
+
+```text
+$XDG_RUNTIME_DIR/mosaic-factory.tmux
+```
+
+or tmux socket name:
+
+```bash
+tmux -L mosaic-factory ...
+```
+
+This avoids collision with ordinary `tmux ls` sessions. The send tools need socket support.
+
+---
+
+## Target USC-style roster example
+
+Ship as example only, not default:
+
+```yaml
+version: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-factory
+  holder_session: _holder
+  working_directory: ~/src
+agents:
+  - name: mos-claude
+    runtime: claude
+    class: orchestrator
+    model_hint: Claude Opus
+    persistent_persona: true
+  - name: coder0
+    runtime: claude
+    class: implementer
+    model_hint: Claude Opus
+    reset_between_tasks: true
+  - name: coder1
+    runtime: claude
+    class: implementer
+    model_hint: Claude Opus
+    reset_between_tasks: true
+  - name: coder2
+    runtime: pi
+    class: implementer
+    model_hint: Pi GPT-5.5
+    reset_between_tasks: true
+  - name: coder3
+    runtime: pi
+    class: implementer
+    model_hint: Pi GPT-5.5
+    reset_between_tasks: true
+  - name: coder4
+    runtime: claude
+    class: implementer
+    model_hint: Claude Opus
+    reset_between_tasks: true
+  - name: coder5
+    runtime: claude
+    class: implementer
+    model_hint: Claude Opus
+    reset_between_tasks: true
+  - name: enhance
+    runtime: claude
+    class: enhancer
+    model_hint: Claude Opus
+    persistent_persona: semi
+  - name: rev0
+    runtime: pi
+    class: reviewer
+    model_hint: Pi GPT-5.5
+    reset_between_tasks: true
+  - name: rev1
+    runtime: pi
+    class: reviewer
+    model_hint: Pi GPT-5.5
+    reset_between_tasks: true
+  - name: secrev0
+    runtime: pi
+    class: security_reviewer
+    model_hint: Pi GPT-5.5
+    reset_between_tasks: true
+  - name: secrev1
+    runtime: pi
+    class: security_reviewer
+    model_hint: Pi GPT-5.5
+    reset_between_tasks: true
+  - name: ultron
+    runtime: pi
+    class: final_reviewer
+    model_hint: Pi GPT-5.5
+    persistent_persona: semi
+```
+
+---
+
+## Phase 0 — Confirm install surfaces
+
+### Task 0.1: Inspect installer copy behavior
+
+**Objective:** Confirm how framework files under `packages/mosaic/framework/` become installed under `~/.config/mosaic/`.
+
+**Files:**
+
+- Read: `tools/install.sh`
+- Read: `packages/mosaic/framework/install.sh`
+- Read: `packages/mosaic/src/runtime/install-manifest.ts`
+
+**Steps:**
+
+1. Verify `packages/mosaic/framework/install.sh` rsyncs `tools/tmux`.
+2. Verify whether npm-packaged installs include `framework/tools/tmux`.
+3. Confirm whether installed hosts should run `mosaic update`, `bash tools/install.sh`, or `packages/mosaic/framework/install.sh` to receive new tmux tools.
+4. Record exact propagation command in docs.
+
+**Verification:**
+
+```bash
+bash packages/mosaic/framework/install.sh --help || true
+npm pack --dry-run --json | jq '.[0].files[].path' | grep 'framework/tools/tmux'
+```
+
+Expected: tmux tools are included in installable package or packaging fix is identified.
+
+### Task 0.2: Inspect current yolo launch semantics
+
+**Objective:** Confirm `mosaic yolo claude` and `mosaic yolo pi` accept optional initial prompt text and behave well under systemd/tmux.
+
+**Files:**
+
+- Read: `packages/mosaic/src/**`
+- Read: `packages/mosaic/framework/runtime/claude/RUNTIME.md`
+- Read: `packages/mosaic/framework/runtime/pi/RUNTIME.md`
+
+**Verification commands:**
+
+```bash
+mosaic yolo claude --help
+mosaic yolo pi --help
+```
+
+Expected: a systemd `ExecStart` can launch the runtime either with no prompt or with a kickstart prompt file/string.
+
+---
+
+## Phase 1 — Framework tmux primitives
+
+### Task 1.1: Add socket support to send tools
+
+**Objective:** Allow `agent-send.sh` and `send-message.sh` to target a named Mosaic tmux socket without affecting default tmux sessions.
+
+**Files:**
+
+- Modify: `packages/mosaic/framework/tools/tmux/send-message.sh`
+- Modify: `packages/mosaic/framework/tools/tmux/agent-send.sh`
+- Modify: `packages/mosaic/framework/tools/tmux/README.md`
+- Test: `packages/mosaic/framework/tools/tmux/test-send-message.sh` (new)
+
+**Design:**
+
+Add optional flags:
+
+```bash
+-L SOCKET_NAME      # tmux -L socket name
+-SOCKET PATH        # optional later if needed; avoid conflict with existing -S source label in agent-send
+```
+
+Because `agent-send.sh` already uses `-S` for source label, prefer `-L` for socket name and `-T` or `--socket-path` only if long-option parsing is added.
+
+**Implementation notes:**
+
+- Build a tmux command array:
+
+```bash
+tmux_cmd=(tmux)
+if [ -n "$SOCKET_NAME" ]; then tmux_cmd+=( -L "$SOCKET_NAME" ); fi
+```
+
+- Replace raw `tmux ...` calls with `"${tmux_cmd[@]}" ...`.
+- Pass `-L` through remote ssh invocation.
+- Include socket name in verbose output.
+
+**Verification:**
+
+```bash
+tmux -L mosaic-test new-session -d -s target 'cat'
+packages/mosaic/framework/tools/tmux/send-message.sh -L mosaic-test -t target -m 'hello'
+tmux -L mosaic-test capture-pane -t target -p | grep hello
+tmux -L mosaic-test kill-server
+```
+
+Expected: message lands in the named socket session; default `tmux ls` is untouched.
+
+### Task 1.2: Add exact target validation helper
+
+**Objective:** Prevent accidental prefix targeting in all tmux fleet operations.
+
+**Files:**
+
+- Create: `packages/mosaic/framework/tools/tmux/_lib.sh`
+- Modify: `send-message.sh`
+- Modify: `agent-send.sh`
+
+**Behavior:**
+
+- For session-only agent names, normalize target to `=<name>` before kill/status/reset operations.
+- For explicit pane targets like `session:window.pane`, allow as advanced path but document the risk.
+
+**Verification:**
+
+Create sessions `agent` and `agent0`; verify killing/resetting `agent` does not affect `agent0`.
+
+---
+
+## Phase 2 — systemd unit templates
+
+### Task 2.1: Add holder service template
+
+**Objective:** Ship a user systemd unit template that owns the Mosaic factory tmux server.
+
+**Files:**
+
+- Create: `packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service`
+- Create: `packages/mosaic/framework/tools/fleet/install-user-units.sh`
+
+**Unit shape:**
+
+```ini
+[Unit]
+Description=Mosaic tmux fleet holder
+Documentation=https://git.mosaicstack.dev/mosaicstack/aiguide
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+ExecStart=/usr/bin/tmux -L ${MOSAIC_TMUX_SOCKET} new-session -d -s _holder 'while true; do sleep 3600; done'
+ExecStop=-/usr/bin/tmux -L ${MOSAIC_TMUX_SOCKET} kill-server
+
+[Install]
+WantedBy=default.target
+```
+
+**Important:** systemd environment expansion in `ExecStart` is limited. Verify syntax; if `%E`/environment expansion is awkward, generate concrete units from config instead of relying on dynamic expansion.
+
+**Verification:**
+
+```bash
+systemd-analyze --user verify ~/.config/systemd/user/mosaic-tmux-holder.service
+systemctl --user daemon-reload
+systemctl --user start mosaic-tmux-holder.service
+tmux -L mosaic-factory ls | grep _holder
+```
+
+### Task 2.2: Add agent service template
+
+**Objective:** Ship a user systemd template that starts one configured agent slot.
+
+**Files:**
+
+- Create: `packages/mosaic/framework/systemd/user/mosaic-agent@.service`
+- Modify: `packages/mosaic/framework/tools/fleet/install-user-units.sh`
+
+**Unit shape:**
+
+```ini
+[Unit]
+Description=Mosaic agent session %i
+Requires=mosaic-tmux-holder.service
+After=mosaic-tmux-holder.service
+PartOf=mosaic-tmux-holder.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+WorkingDirectory=%h/src
+Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+ExecStart=/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "%i" "mosaic yolo $(mosaic fleet runtime %i)"'
+ExecStop=-/usr/bin/tmux -L mosaic-factory kill-session -t '=%i'
+
+[Install]
+WantedBy=default.target
+```
+
+**Design warning:** command substitution in unit files can become brittle. Prefer a generated per-agent EnvironmentFile:
+
+```text
+~/.config/mosaic/fleet/agents/coder0.env
+```
+
+with:
+
+```bash
+MOSAIC_AGENT_NAME=coder0
+MOSAIC_AGENT_RUNTIME=claude
+MOSAIC_AGENT_WORKDIR=/home/jarvis/src
+MOSAIC_TMUX_SOCKET=mosaic-factory
+```
+
+Then `ExecStart` calls a wrapper:
+
+```bash
+~/.config/mosaic/tools/fleet/start-agent-session.sh
+```
+
+**Verification:**
+
+```bash
+systemd-analyze --user verify ~/.config/systemd/user/mosaic-agent@.service
+systemctl --user start mosaic-agent@coder0.service
+tmux -L mosaic-factory has-session -t '=coder0'
+systemctl --user restart mosaic-agent@coder0.service
+```
+
+Expected: holder server PID remains unchanged; only `coder0` session recycles.
+
+### Task 2.3: Add start-agent wrapper
+
+**Objective:** Keep systemd units simple by moving config lookup and launch command construction into a script.
+
+**Files:**
+
+- Create: `packages/mosaic/framework/tools/fleet/start-agent-session.sh`
+
+**Behavior:**
+
+Inputs:
+
+```bash
+start-agent-session.sh <agent-name>
+```
+
+Reads:
+
+```text
+$MOSAIC_HOME/fleet/agents/<agent-name>.env
+```
+
+Starts:
+
+```bash
+tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$MOSAIC_AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" "mosaic yolo $MOSAIC_AGENT_RUNTIME"
+```
+
+Guardrails:
+
+- fail if runtime is empty;
+- fail if workdir does not exist;
+- no duplicate sessions unless `--replace` is passed;
+- exact session names only.
+
+---
+
+## Phase 3 — roster config and CLI wrappers
+
+### Task 3.1: Add fleet config schema and examples
+
+**Objective:** Define customizable install-time roster without hardcoding USC.
+
+**Files:**
+
+- Create: `packages/mosaic/framework/fleet/roster.schema.json`
+- Create: `packages/mosaic/framework/fleet/examples/minimal.yaml`
+- Create: `packages/mosaic/framework/fleet/examples/usc-software-factory.yaml`
+- Create: `packages/mosaic/framework/fleet/README.md`
+
+**Schema concepts:**
+
+- `transport`: `tmux` now; `matrix` later.
+- `tmux.socket_name`
+- `tmux.holder_session`
+- `defaults.working_directory`
+- `agents[].name`
+- `agents[].runtime`
+- `agents[].class`
+- `agents[].model_hint`
+- `agents[].persistent_persona`
+- `agents[].reset_between_tasks`
+- `agents[].kickstart_template`
+
+**Verification:**
+
+Use `jq` for JSON examples or add a small Python/YAML validator if YAML is chosen. If no YAML parser is guaranteed, store examples as JSON or support both with Python stdlib JSON first.
+
+### Task 3.2: Add `mosaic fleet` commands
+
+**Objective:** Provide operator-safe commands for install/status/start/stop/restart/verify.
+
+**Files:**
+
+- Modify: `packages/mosaic/src/cli.ts` or the current commander entrypoint.
+- Create scripts under: `packages/mosaic/framework/tools/fleet/`
+
+**Commands:**
+
+```bash
+mosaic fleet init --profile minimal|usc --write
+mosaic fleet install-systemd
+mosaic fleet start [agent]
+mosaic fleet stop [agent]
+mosaic fleet restart [agent]
+mosaic fleet status --json
+mosaic fleet verify
+```
+
+**Implementation path:**
+
+Start by wrapping framework shell scripts from the TypeScript CLI. Do not overbuild a TypeScript service manager in the first pass.
+
+### Task 3.3: Add `mosaic agent` commands
+
+**Objective:** Provide transport-stable per-agent operations.
+
+**Files:**
+
+- Modify: Mosaic CLI entrypoint.
+- Create: `packages/mosaic/framework/tools/agent/` or reuse `tools/tmux` + `tools/fleet`.
+
+**Commands:**
+
+```bash
+mosaic agent roster [--json]
+mosaic agent status [agent] [--json]
+mosaic agent send <agent> --message "..."
+mosaic agent reset <agent> --clear|--new
+mosaic agent tail <agent> [-n 80]
+```
+
+**Reset behavior:**
+
+For tmux transport, `reset --clear` sends `/clear` then Enter through `send-message.sh`.
+
+For Claude/Pi differences, keep reset command configurable per runtime:
+
+```yaml
+runtimes:
+  claude:
+    reset_command: /clear
+  pi:
+    reset_command: /new
+```
+
+If a runtime does not support a known reset command, restart the service and send a fresh kickstart.
+
+---
+
+## Phase 4 — this-server rollout strategy
+
+### Task 4.1: Install on separate socket first
+
+**Objective:** Prove the holder pattern without disturbing existing sessions.
+
+**Commands after implementation lands locally:**
+
+```bash
+mosaic fleet init --profile minimal --write
+mosaic fleet install-systemd
+systemctl --user daemon-reload
+systemctl --user start mosaic-tmux-holder.service
+mosaic fleet verify
+```
+
+Expected:
+
+- `tmux -L mosaic-factory ls` shows `_holder`.
+- normal `tmux ls` still shows existing sessions unchanged.
+
+### Task 4.2: Start one canary agent
+
+**Objective:** Validate single-agent start/restart isolation.
+
+Use a harmless canary first, not the full fleet.
+
+Example roster addition:
+
+```yaml
+- name: canary-pi
+  runtime: pi
+  class: canary
+  working_directory: /home/jarvis/src
+```
+
+Commands:
+
+```bash
+systemctl --user start mosaic-agent@canary-pi.service
+SRV=$(tmux -L mosaic-factory display-message -p '#{pid}')
+systemctl --user restart mosaic-agent@canary-pi.service
+test "$SRV" = "$(tmux -L mosaic-factory display-message -p '#{pid}')"
+tmux -L mosaic-factory ls
+```
+
+Expected: holder PID unchanged; `_holder` remains; `canary-pi` recreated.
+
+### Task 4.3: Configure local Mosaic factory roster
+
+**Objective:** Create the actual local roster for this server after canary passes.
+
+Do not assume USC exact roster is desired here. Create a local profile such as:
+
+```text
+~/.config/mosaic/fleet/roster.yaml
+```
+
+Initial local recommendation:
+
+- `mos-claude` orchestrator
+- `coder0` / `coder1` implementers
+- `rev0` reviewer
+- `secrev0` security reviewer
+- `ultron` final/adversarial reviewer
+
+Scale to full USC-style pool only after resource/budget behavior is understood.
+
+### Task 4.4: Cut over existing ad-hoc tmux sessions only if desired
+
+**Objective:** Avoid data loss.
+
+Existing sessions on this server are not on the proposed `mosaic-factory` socket. They can remain untouched. If we later want them under Mosaic fleet control:
+
+1. list sessions;
+2. capture logs/handoffs;
+3. stop old processes intentionally;
+4. recreate as configured `mosaic-agent@...` services;
+5. verify comms and state.
+
+Do not run `tmux kill-server` on the default socket unless Jason explicitly approves that outage.
+
+---
+
+## Phase 5 — docs and AI Guide backfill
+
+### Task 5.1: Stack docs
+
+**Objective:** Document install and customization for Mosaic Stack users.
+
+**Files:**
+
+- Create: `docs/fleet/tmux-fleet.md` or `packages/mosaic/framework/tools/fleet/README.md`
+- Modify: top-level `README.md` if appropriate.
+
+Must cover:
+
+- what problem holder service solves;
+- install commands;
+- customization file;
+- example rosters;
+- reset/reuse lifecycle;
+- exact-target safety;
+- separate socket default;
+- Matrix migration path.
+
+### Task 5.2: AI Guide docs
+
+**Objective:** Keep generic guidance in AI Guide and implementation details in Stack.
+
+**Files in `mosaicstack/aiguide`:**
+
+- Update: `playbooks/tmux-fleet.md` with named socket, roster/profile, and resettable-slot pattern.
+- Add or update: `reference/agent-role-matrix.md` if PR #5 lands.
+
+Do not put Mosaic install commands as the only path in AI Guide. Present them as one implementation profile.
+
+---
+
+## Phase 6 — Matrix migration seam
+
+### Task 6.1: Add transport enum but implement tmux only
+
+**Objective:** Avoid hardcoding tmux into orchestration semantics.
+
+Roster:
+
+```yaml
+transport: tmux
+```
+
+Future:
+
+```yaml
+transport: matrix
+matrix:
+  homeserver: https://matrix.example
+  room_prefix: mosaic-factory
+```
+
+### Task 6.2: Define transport interface docs
+
+**Objective:** Make Matrix plugin work a transport swap, not a rewrite.
+
+Minimum operations:
+
+```text
+send(agent, message)
+reset(agent, mode)
+status(agent)
+tail(agent)
+listAgents()
+```
+
+Any tmux-specific concept must stay below this line.
+
+---
+
+## Acceptance criteria
+
+The implementation is complete when:
+
+- `mosaic fleet init` can write a minimal roster.
+- `mosaic fleet install-systemd` installs holder and agent units without hand editing.
+- `mosaic fleet start` starts the holder and configured agents on a named tmux socket.
+- Restarting one `mosaic-agent@name.service` does not change holder server PID or kill sibling sessions.
+- `mosaic agent send` can deliver a message to a named agent with a self-identifying preamble.
+- `mosaic agent reset` can clear/new a reusable slot and send a fresh kickstart.
+- `mosaic fleet verify` proves holder ownership, exact-target safety, and per-agent restart isolation.
+- Existing default tmux sessions on this server are not disturbed by default install.
+- Docs explain generic customization and include USC-style roster only as an example.
+- AI Guide remains generic; Mosaic Stack docs carry the concrete install path.
+
+## Risks and mitigations
+
+| Risk                                                | Mitigation                                                                        |
+| --------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Killing existing tmux sessions                      | Use named `mosaic-factory` socket; no default `tmux kill-server`.                 |
+| systemd unit quoting/env expansion bugs             | Move logic into shell wrappers; verify with `systemd-analyze --user verify`.      |
+| Runtime reset command mismatch                      | Make reset command runtime-configurable; fallback to service restart + kickstart. |
+| Tool install drift                                  | Ensure npm package includes framework tmux/fleet tools; add packaging test.       |
+| Mosaic-specific assumptions leak into generic guide | Keep USC roster as example profile; AI Guide documents pattern/options.           |
+| Matrix migration blocked by tmux coupling           | Add `mosaic agent` abstraction now; keep tmux details below transport layer.      |
+
+## Suggested first PR split
+
+1. **PR A — tmux tool hardening**
+   - socket support;
+   - exact target helpers;
+   - tests/docs.
+
+2. **PR B — fleet systemd primitives**
+   - holder unit;
+   - agent unit;
+   - start-agent wrapper;
+   - install-user-units script;
+   - verify script.
+
+3. **PR C — roster and CLI**
+   - roster schema/examples;
+   - `mosaic fleet ...` commands;
+   - `mosaic agent ...` commands.
+
+4. **PR D — local rollout and docs**
+   - local roster for this server;
+   - run canary;
+   - document verification evidence;
+   - update AI Guide with generic lessons.
+
+## Immediate next action
+
+Implement PR A first. It is low-risk, improves existing tools, and is required for a safe named-socket rollout on this server.