MUX - pi coordinator pattern (pimux runtime)

Use this when the task is too large for one uninterrupted context window and you need mux wave semantics with tmux-backed long-lived execution.

Binding activation

If the user explicitly invokes mux / ac-workflow-mux, or embeds this skill text as the runtime for the task, treat this document as a binding runtime contract, not as optional guidance, commentary, or a planning reference.

Absolute compliance rule

For explicit mux-family triggers in pi, the current session is a pimux-only control plane.

• FIRST after spawn: do not poll pimux or use Bash sleep/wait loops; wait for delivered child bridge activity.
• The authoritative pimux extension applies a fail-closed parent control-plane lock for explicit mux-family wrappers.
• Before the first child exists, the parent must not call Read, Bash, Edit, Write, NotebookEdit, Grep, Glob, web_search, subagent, or any other non-pimux tool for substantive repo work.
• Do not do substantive repo or domain work in the parent session.
• Do not use parent-side repo discovery, file inspection, implementation planning, or direct edits before spawn.
• The first real move is to spawn the authoritative pimux child coordinator.
• The first observable parent tool call must be pimux spawn.
• If you have not spawned that child yet, you are not allowed to analyze, compare, implement, or answer the task from the parent.
• If the parent performs substantive repo inspection or any forbidden tool call before spawn, stop immediately, acknowledge a protocol violation, discard any parent-side conclusions, and restart from pimux spawn.

Parent tool surface

While this skill is active, the parent session is runtime-locked to pimux, AskUserQuestion, and say only:

• before the first child exists: pimux spawn only
• AskUserQuestion is allowed only for explicit user clarification that blocks spawn
• after spawn: notify-first, not poll-first; wait for delivered child bridge activity instead of inspecting live state
• do not poll pimux or use Bash sleep/wait loops; if you are about to inspect routine progress, stop and wait for delivered child activity instead
• happy path after spawn forbids status, capture, tree, list, and open; those are recovery-only tools for explicit live inspection, suspected stall/protocol violation/failure, or the inactivity watchdog
• after a child progress report arrives, use at most one send_message when the child needs input; then wait for closeout or another child report
• terminal settlement re-arms exactly one final pimux status verification before advancing
• say is allowed only for short user-attention prompts

The parent does not use repo Read, Bash, Edit, Write, NotebookEdit, Grep, Glob, web_search, or local helper orchestration for the substantive task.

Mandatory first actions

1. Build a short handoff from the user request only.
2. pimux spawn the bounded mux coordinator before any substantive analysis or implementation.
3. Pass the raw objective, constraints, and any explicit file paths from the user into that child.
4. Let the child read mux foundation assets and repo context.

Semantics to preserve

The migration is runtime/orchestration adaptation only. Preserve mux semantics:

• strict control-plane vs data-plane discipline
• declared dispatch before worker execution
• report/signal/summary evidence gates for advancement
• strict ADVANCE | BLOCK | RECOVER routing
• no manual fallback outside protocol

Child coordinator contract

The authoritative pimux child owns the substantive mux run:

• child reads ../../assets/mux/protocol/foundation.md and ../../assets/mux/protocol/subagent.md
• child initializes strict session state with ../../assets/mux/tools/session.py --strict-runtime --session-key <key>
• child declares worker dispatch payloads before execution
• child requires report + signal + summary evidence for advancement
• child keeps one worker layer (coordinator -> subagent) inside the child
• child keeps workers data-plane only; no pimux / report_parent from helpers

Parent/session contract

• Parent -> child messaging: pimux send_message
• Child -> parent reporting: pimux report_parent
• success settles only after terminal closeout + child exit
• if child outcomes are intentionally non-success, propagate matching terminal kind (question / blocker / failure)
• for a child that must ask and continue in the same session, use report_parent(progress, requiresResponse=true); question is terminal waiting-on-parent settlement

Completion

Complete only when the authoritative child settles and exits with protocol-valid reporting. Do not treat interim captures, local notes, or helper output as completion.