# 📑 Multi-Agent Mux (MAM) Skill Optimization Plan

Based on the joint code audits conducted by **Reviewer Cline** and **Creator Claude**, this plan identifies the structural inefficiencies, duplicate code paths, and latent portability risks in the MAM skills library (`.agents/skills/`), and provides a phased execution blueprint for refactoring and optimization.

---

## 📊 Summary of Optimization Focus Areas

The audit of all 8 shell entry points (~3,422 lines) revealed three key areas where the skills codebase can be significantly optimized:
1. **Sleeps to Handshakes (Timing Bets)**: Replacing fixed timing loops with event-driven or reactive waits (e.g., reactive tmux stop, MQTT suback event check).
2. **Structural Consolidation (DRY principle)**: Reducing code duplication across scripts, such as 7 identical copies of the SQLite/YAML loader block and 4 copies of tmux server resolution.
3. **Portability & Observability**: Guarding against zsh path resolution anomalies when sourcing `lib.sh`, and eliminating silent failures inside monitor loops.

---

## 🛠️ Detailed Optimization Items

### 1. Inefficient Polling & Sleep Reductions

#### 🚀 OP-1: Reactive Tmux Graceful Stopping (`stop_session.sh`)
*   **Location**: `stop_session.sh:193,200`
*   **Defect**: Graceful stopping uses fixed sleeps (`sleep 3` after sending exitkey, `sleep 5` after kill-session). Every stop operation incurs an unconditional 3–8 s delay, even if the agent session exits in milliseconds.
*   **Optimization**: Implement `_wait_session_gone` helper in `lib.sh` that polls `tmux has-session` at a high frequency (e.g., every 250 ms) up to a deadline.
*   **Outcome**: Reduces average session stop time from **8 s to <0.3 s** under ordinary circumstances.

#### 🚀 OP-2: MQTT Subscriber Event-Driven Handshake (`delegate-job`)
*   **Location**: `multi-agent-mux-delegate-job:119,205`
*   **Defect**: Sponsoring a subscriber runs in the background, followed by a blind `sleep 1` to win the race against the agent's startup event publish. If HiveMQ CONNACK/SUBACK is slow, the start event is lost; if fast, 1 s is wasted.
*   **Optimization**: Modify `job_subscriber.py` to write a sentinel line (e.g. `SUBSCRIBED <topic>`) to its log file on a successful SUBSCRIBE callback. Replace `sleep 1` in the wrapper with a fast-poll loop matching this sentinel.
*   **Outcome**: Eliminates event-loss race conditions over WAN brokers, while dropping the startup delay to the physical minimum.

#### 🚀 OP-3: Main Event Loop Pacing (`reconcile.sh`)
*   **Location**: `reconcile.sh:243-256` (MQTT client wait)
*   **Defect**: The foreground loop spins on a CPU-wake polling model `while True: time.sleep(0.5)` just to compare time differentials for deadlines, bypassing python's event capabilities.
*   **Optimization**: Use a `threading.Event()` wait state (`stop.wait(timeout=next_deadline - now)`) to suspend the main thread until a true timeout occurs or an interrupt event fires.
*   **Outcome**: Zero-CPU footprint while idling.

---

### 2. Code Duplication & Modularization (DRY)

#### 🚀 OP-4: Unify Divergent Tmux Server Resolvers
*   **Location**: `lib.sh:1043-1046`, `create_session.sh:212`, `delegate-job:347`
*   **Defect**: String resolution for tmux servers (`local_tmux="tmux -L $TMUX_SERVER_NAME"`) is duplicated 4 times, leading to potential word-splitting hazards (shellcheck SC2086).
*   **Optimization**: Extract a single, canonical `mam_tmux()` dispatch function into `lib.sh` that safely handles server arguments and exports them cleanly.

#### 🚀 OP-5: Single-Source the YAML / SQLite Load Boilerplate (7× Duplicate)
*   **Location**: `lib.sh` (3 sites), `stop_session.sh:87`, `status.sh:42`, `update_yaml_resumed.sh:66`, `reconcile.sh:298`
*   **Defect**: The ~20 lines of Python heredoc code that dynamically queries merged YAML and SQLite state is copy-pasted in 7 separate files, each with slightly drifted error policies.
*   **Optimization**: Implement `load_state_json` in `lib.sh` which executes the Python boilerplate exactly once and emits the state to stdout as a JSON document. Script files can then parse this single JSON document.

#### 🚀 OP-6: Consolidate TUI Ready / Dialog Tokens
*   **Location**: `lib.sh:1058` and `lib.sh:1205`
*   **Defect**: Regular expressions for Claude ready-states and trust dialog tokens are duplicated. Updates to one block (e.g. for new Claude versions) can lead to drift and prompt-lock bugs.
*   **Optimization**: Declare central constants (`_MAM_DIALOG_TOKENS`, `_MAM_READY_TOKENS_CLAUDE`) at the top of `lib.sh` and refer to them.

---

### 3. Portability & Robustness

#### 🚀 OP-7: Guard against Non-Bash Sourced Environments
*   **Location**: `lib.sh:17` and all 8 script headers
*   **Defect**: If a user runs a zsh session and types `source .agents/skills/lib.sh`, `${BASH_SOURCE[0]}` resolves to empty, leading to silent path resolution failure.
*   **Optimization**: Add a zsh-aware fallback detection block for the parent script path (`ZSH_VERSION` check) or print an explicit exit message warning users not to source from a foreign shell.

#### 🚀 OP-8: Make Degraded Mode Failures Observable (`reconcile.sh`)
*   **Location**: `reconcile.sh:269`
*   **Defect**: Fallback polling mode (`bash reconcile.sh --once --emit-diff >/dev/null 2>&1 || true`) discards stderr and exit codes. If database locks or SQLite faults occur, the monitor stays silently broken.
*   **Optimization**: Capture stdout/stderr of the one-off run. Log errors and exit the loop for supervisor restart if 5 consecutive runs fail.

---

## 📅 Actionable Optimization Roadmap

We recommend executing these optimizations in three sequential phases:

```mermaid
gantt
    title MAM Skill Optimization Roadmap
    dateFormat  YYYY-MM-DD
    section Phase 1 (Latency)
    OP-1 (Reactive Tmux Stop)     :active, p1, 2026-07-12, 1d
    OP-2 (MQTT Subscribe Handshake):active, p2, after p1, 2d
    OP-3 (Event Loop CPU Wait)    :p3, after p2, 1d
    section Phase 2 (DRY & Consolidate)
    OP-4 (Tmux Dispatcher)        :p4, 2026-07-15, 1d
    OP-5 (JSON Loader Helper)     :p5, after p4, 2d
    OP-6 (Ready Token Constants)  :p6, after p5, 1d
    section Phase 3 (Portability & Safety)
    OP-7 (zsh Source Guard)       :p7, 2026-07-19, 1d
    OP-8 (Reconcile Observability) :p8, after p7, 1d
```

---

## 📋 Definition of Done (DoD) for Optimizations
1. **Shell Linting**: `bash -n <script>` passes; zero new `shellcheck` warnings.
2. **Functional verification**: All tests in the prompt-lock test suite (T-A through T-E) pass on an isolated scratch server (`-L sks-test`).
3. **Drift-Free**: `reconcile.sh` correctly resolves running tmux sessions after code unification.
4. **Interactive testing**: Graceful stop runs successfully and reports exit time under 1 s.