multi-agent-mux/.agents/reports/canary-projects-multi-agent-mux-planner-claude/report-skill-optimization-plan.md

📑 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:

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.