Godopu
7eeb4b709a
- OP-1: Implement reactive _wait_session_gone in lib.sh and stop_session.sh with set -e || true guard - OP-2: Event-driven MQTT subscribe handshake with sub_pid liveness in delegate-job - OP-3: Replace CPU time.sleep(0.5) spin with threading.Event wait in reconcile.sh - OP-4: Define mam_tmux dispatcher targeting resolved _REAL_TMUX_PATH to prevent recursion - OP-6 & OP-7: Add token variables and bash version source check in lib.sh - Integrate approved optimization plan and PASS review reports from all agents
101 lines
6.7 KiB
Markdown
101 lines
6.7 KiB
Markdown
# 📑 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.
|