@femtomc/mu-agent 26.2.104 → 26.2.106

package/README.md

@@ -28,7 +28,11 @@ into `~/.mu/skills/` (or `$MU_HOME/skills/`) by the CLI store-initialization pat
 - `memory`
 - `planning`
 - `hud`
-- `hierarchical-work-protocol`
+- `orchestration`
+- `control-flow`
+- `model-routing`
+- `code-mode`
+- `tmux`
 - `subagents`
 - `heartbeats`
 - `crons`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.2.104",
+  "version": "26.2.106",
   "description": "Shared operator runtime for mu assistant sessions and serve extensions.",
   "keywords": [
     "mu",
@@ -25,7 +25,7 @@
     "themes/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.2.104",
+    "@femtomc/mu-core": "26.2.106",
     "@mariozechner/pi-agent-core": "^0.54.2",
     "@mariozechner/pi-ai": "^0.54.2",
     "@mariozechner/pi-coding-agent": "^0.54.2",

package/prompts/skills/code-mode/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: code-mode
+description: "Runs lightweight tmux-backed REPL workflows so agents can execute code and engineer context without bloating prompt history."
+---
+
+# code-mode
+
+Use this skill when a task is better solved by iterative code execution in a live
+REPL than by stuffing intermediate data into chat context.
+
+The core idea is intentionally simple: `tmux` provides a persistent runtime shell,
+and the agent drives it with `bash`.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [tmux skill dependency](#tmux-skill-dependency)
+- [Minimal tmux execution loop](#minimal-tmux-execution-loop)
+- [Context engineering contract](#context-engineering-contract)
+- [Language-specific quick starts](#language-specific-quick-starts)
+- [Integration with other mu skills](#integration-with-other-mu-skills)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+1. **Use persistent runtime state, not prompt state**
+   - Keep working data in REPL variables, files, and process memory.
+   - Only return compact summaries/artifacts to chat.
+
+2. **One session per task scope**
+   - Reuse the same tmux session while solving one problem.
+   - Use distinct session names for unrelated tasks to avoid state bleed.
+
+3. **Bounded command passes**
+   - Send one coherent code block per pass.
+   - Capture output, summarize, decide next pass.
+
+4. **On-demand discovery**
+   - Ask runtime for definitions/help only when needed (`help(...)`, `dir(...)`,
+     `.help`, etc.) instead of loading everything up front.
+
+5. **No extra harness required**
+   - Trusted local workflows can stay minimal: `tmux` + `bash` + REPL.
+
+## tmux skill dependency
+
+Before mutating tmux session state, load **`tmux`** and follow its canonical
+session lifecycle and bounded pass protocol.
+
+- Treat `tmux` as source-of-truth for create/reuse, capture, fan-out, and teardown.
+- This `code-mode` skill defines REPL/context-engineering behavior only.
+
+## Minimal tmux execution loop
+
+Follow the `Bounded execution protocol` in the `tmux` skill to create
+sessions, run commands with a completion marker, and capture output.
+
+Example session creation for a REPL:
+
+```bash
+session="mu-code-py"
+tmux has-session -t "$session" 2>/dev/null || tmux new-session -d -s "$session" "python3 -q"
+```
+
+Then send your REPL commands and the marker, according to the `tmux` skill.
+Teardown the session when finished.
+
+## Context engineering contract
+
+Use the runtime to compress context before speaking:
+
+1. Load raw data into files/variables.
+2. Execute code that filters, slices, or aggregates.
+3. Persist useful artifacts (`summary.json`, `notes.md`, `results.csv`).
+4. Report only:
+   - key findings,
+   - confidence/limits,
+   - artifact paths and next action.
+
+Practical rules:
+
+- Prefer computed summaries over pasted raw logs.
+- Keep long transcripts in files; cite paths.
+- Recompute when uncertain instead of guessing from stale text.
+
+## Language-specific quick starts
+
+Python:
+
+```bash
+tmux new-session -d -s mu-code-py "python3 -q"
+```
+
+Node:
+
+```bash
+tmux new-session -d -s mu-code-node "node"
+```
+
+SQLite:
+
+```bash
+tmux new-session -d -s mu-code-sql "sqlite3 data.db"
+```
+
+Shell-only REPL (for pipelines/tools):
+
+```bash
+tmux new-session -d -s mu-code-sh "bash --noprofile --norc -i"
+```
+
+## Integration with other mu skills
+
+- Use with `planning` when a plan step needs exploratory coding.
+- Use with `orchestration`/`subagents` by assigning one tmux session per worker.
+- Use with `control-flow` for explicit retry/termination policy around code passes.
+- Use with `heartbeats`/`crons` when bounded code passes should run on schedule.
+
+## Evaluation scenarios
+
+1. **Exploratory data pass**
+   - Setup: large raw text/log corpus.
+   - Expected: agent uses REPL transforms to produce concise findings + artifact path,
+     without dumping full corpus into chat.
+
+2. **Multi-pass debugging**
+   - Setup: bug reproduction requires iterative commands.
+   - Expected: same tmux session is reused across passes; state continuity reduces
+     repeated setup and prompt churn.
+
+3. **Language swap with same control pattern**
+   - Setup: compare Python and Node approaches.
+   - Expected: same tmux send/capture loop works across both REPLs with only session
+     bootstrap command changed.

package/prompts/skills/control-flow/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: control-flow
+description: "Defines compositional control-flow policies for orchestration DAGs (for example review-gated retry loops) using protocol-preserving transitions."
+---
+
+# control-flow
+
+Use this skill when work needs explicit loop/termination policy on top of the
+shared orchestration protocol.
+
+## Contents
+
+- [Purpose](#purpose)
+- [Required dependencies](#required-dependencies)
+- [Core contract](#core-contract)
+- [Review-gated policy (`flow:review-gated-v1`)](#review-gated-policy-flowreview-gated-v1)
+- [Transition table](#transition-table)
+- [Planning handoff contract](#planning-handoff-contract)
+- [Subagents/heartbeat execution contract](#subagentsheartbeat-execution-contract)
+- [HUD visibility and teardown](#hud-visibility-and-teardown)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Purpose
+
+Control-flow policies are overlays. They do not replace orchestration protocol
+semantics; they guide which protocol primitive to apply next.
+
+Examples:
+- review-gated retries
+- bounded retry + human escalation
+- checkpoint/approval gates
+
+## Required dependencies
+
+Load these skills before applying control-flow policies:
+
+- `orchestration` (protocol primitives/invariants)
+- `subagents` (durable execution runtime)
+- `heartbeats` and/or `crons` (scheduler clock)
+- `hud` (required visibility/handoff surface)
+
+## Core contract
+
+1. **Overlay, don’t fork protocol**
+   - Keep `hierarchical-work.protocol/v1` + `proto:hierarchical-work-v1`.
+   - Do not invent new protocol IDs for policy variants.
+
+2. **Policy metadata lives in `flow:*`**
+   - Keep policy tags/metadata orthogonal to `kind:*` and `ctx:*`.
+
+3. **Transitions compile to protocol primitives**
+   - Use only `spawn|fork|expand|ask|complete|serial` plus normal issue lifecycle
+     commands (`claim/open/close/dep`).
+
+4. **Bounded pass per tick**
+   - One control-flow transition decision and one bounded mutation bundle per
+     heartbeat pass; verify then exit.
+
+## Review-gated policy (`flow:review-gated-v1`)
+
+### Tag vocabulary
+
+- `flow:review-gated-v1` — subtree uses review-gated policy
+- `flow:attempt` — implementation attempt node
+- `flow:review` — review gate node
+
+Optional metadata in issue body/forum packet:
+- `max_review_rounds=<N>` (default recommended: 3)
+
+### Required shape per round
+
+For round `k` under policy scope:
+
+- `attempt_k` (executable; usually `kind:spawn` or `kind:fork`)
+- `review_k` (executable; usually `kind:fork`, `ctx:inherit`)
+- edge: `attempt_k blocks review_k`
+
+### Critical invariant
+
+When review fails, **do not leave the review node closed as `needs_work`**.
+That keeps the DAG non-final forever.
+
+Instead:
+1. record verdict in forum (`VERDICT: needs_work`)
+2. spawn `attempt_{k+1}` + `review_{k+1}`
+3. add `attempt_{k+1} blocks review_{k+1}`
+4. close `review_k` with `outcome=expanded`
+
+This preserves full audit history while keeping finalization reachable.
+
+## Transition table
+
+Given current round `(attempt_k, review_k)`:
+
+1. **attempt not finished**
+   - action: continue attempt execution (normal worker loop)
+
+2. **attempt finished, review pending**
+   - action: run review_k
+
+3. **review verdict = pass**
+   - action: `complete(review_k)` with `success`
+   - if subtree validates final, disable supervising heartbeat
+
+4. **review verdict = needs_work, rounds < max**
+   - action: apply fail->expand transition (spawn next round + close review_k as `expanded`)
+
+5. **review verdict = needs_work, rounds >= max**
+   - action: create `kind:ask` escalation node (`ctx:human`, `actor:user`)
+   - downstream work blocks on that ask node
+
+## Planning handoff contract
+
+When planning a review-gated subtree:
+
+1. Tag policy scope root (or selected goal node) with `flow:review-gated-v1`.
+2. Create round-1 pair (`flow:attempt`, `flow:review`) + dependency edge.
+3. Encode acceptance criteria for attempt + review explicitly.
+4. Record max rounds policy in body/forum packet.
+
+## Subagents/heartbeat execution contract
+
+Per orchestrator tick:
+
+1. `read_tree` + ready-set + round-state inspection.
+2. Select one transition from the table above.
+3. Apply one bounded transition bundle.
+4. Verify with:
+   - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
+   - `mu issues validate <root-id>`
+5. Post one concise ORCH_PASS update.
+6. If final: disable heartbeat program.
+
+Reusable bounded heartbeat prompt fragment:
+
+```text
+Use skills orchestration, control-flow, subagents, and hud.
+For root <root-id>, enforce flow:review-gated-v1 with spawn-per-attempt rounds.
+Run exactly one bounded control-flow transition pass, verify DAG state,
+post one ORCH_PASS, and stop. If validate is final, disable the supervising
+heartbeat and report completion.
+```
+
+## HUD visibility and teardown
+
+HUD usage is not optional for active control-flow execution.
+
+- If subagents HUD is already active, publish control-flow state in that HUD doc
+  (for example policy mode, round counters, escalation state).
+- If running control-flow standalone, own a dedicated `hud_id:"control-flow"` doc.
+- Update HUD state each bounded pass before reporting ORCH_PASS output.
+
+- Follow the HUD ownership and teardown protocol from the `hud` skill when completing or handing off.
+
+## Evaluation scenarios
+
+1. **Single-pass review success**
+   - attempt_1 succeeds, review_1 succeeds, subtree validates final, heartbeat disables.
+
+2. **One failed review then success**
+   - review_1 fails -> expand to round 2; review_2 succeeds -> final.
+
+3. **Max-round escalation**
+   - repeated failed reviews hit `max_review_rounds`; ask node created and execution blocks awaiting human input.

package/prompts/skills/crons/SKILL.md

@@ -152,7 +152,9 @@ post concise summary, then exit.
 
 For DAG execution workloads, combine with:
 - `planning`
-- `hierarchical-work-protocol`
+- `orchestration`
+- `control-flow` (when explicit loop/termination policy is required)
+- `model-routing` (when per-issue model/provider/thinking policy is required)
 - `subagents`
 - `heartbeats` (for short-cadence wake loops)
 

package/prompts/skills/heartbeats/SKILL.md

@@ -145,7 +145,9 @@ packet mechanics, raw issue-ID lists). Include them only when diagnosing a block
 
 For hierarchical DAG execution, pair this skill with:
 - `planning`
-- `hierarchical-work-protocol`
+- `orchestration`
+- `control-flow` (when explicit loop/termination policy is required)
+- `model-routing` (when per-issue model/provider/thinking policy is required)
 - `subagents`
 
 For wall-clock scheduling semantics (`at`, `every`, `cron`), use `crons`.

package/prompts/skills/hud/SKILL.md

@@ -18,7 +18,8 @@ This skill is the canonical HUD reference for:
 - [Core contract](#core-contract)
 - [HudDoc shape](#huddoc-shape)
 - [Recommended turn loop](#recommended-turn-loop)
-- [Planning and subagents profiles](#planning-and-subagents-profiles)
+- [Ownership and teardown protocol](#ownership-and-teardown-protocol)
+- [Planning, subagents, and model-routing profiles](#planning-subagents-and-model-routing-profiles)
 - [Determinism and rendering limits](#determinism-and-rendering-limits)
 - [Evaluation scenarios](#evaluation-scenarios)
 
@@ -135,12 +136,45 @@ Example checklist doc:
 
 4. Keep response text and HUD state aligned (no contradictions).
 
-## Planning and subagents profiles
+## Ownership and teardown protocol
+
+HUD-using skills should treat HUD state as owned, explicit, and non-optional when
+that skill declares HUD-required behavior.
+
+1. **Own explicit `hud_id` values**
+   - Each active skill owns one canonical doc id (for example `planning`,
+     `subagents`, `control-flow`, `model-routing`).
+   - Prefer `remove <hud_id>` over `clear` to avoid deleting other skills’ docs.
+
+2. **Teardown is mandatory at skill end**
+   - When a HUD-owning skill completes, remove its doc(s).
+   - If no other HUD-owning skill is active next, turn HUD off.
+
+3. **Teardown during HUD-to-HUD handoff**
+   - Remove current skill doc(s), keep HUD enabled, then let next skill set its doc.
+   - Never leave stale docs from prior skills during handoff.
+
+Example teardown/handoff calls:
+
+```json
+{"action":"remove","hud_id":"planning"}
+{"action":"set","doc":{"v":1,"hud_id":"subagents","title":"Subagents HUD","snapshot_compact":"HUD(subagents)","updated_at_ms":1771853115001}}
+```
+
+Example full teardown (no next HUD skill):
+
+```json
+{"action":"remove","hud_id":"subagents"}
+{"action":"off"}
+```
+
+## Planning, subagents, and model-routing profiles
 
 Use profile-specific `hud_id` values:
 
 - planning profile: `hud_id: "planning"`
 - subagents profile: `hud_id: "subagents"`
+- model-routing profile: `hud_id: "model-routing"`
 
 Treat these as conventions layered on top of this generic contract.
 
@@ -168,4 +202,4 @@ If behavior is unclear, inspect implementation/tests before guessing:
    - Expected: `subagents` doc updates queue/activity/chips after each bounded pass.
 
 3. **HUD reset handoff**
-   - Expected: after phase completion, HUD is cleared or removed by `hud_id`, and status reflects no stale docs.
+   - Expected: after phase completion, owned HUD docs are removed; HUD is turned off when no next HUD skill is active, or ownership cleanly hands off to the next skill with no stale docs.

package/prompts/skills/model-routing/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: model-routing
+description: "Adds a model-selection overlay for issue DAG execution, recommending provider/model/thinking per issue from live harness capabilities."
+---
+
+# model-routing
+
+Use this skill when execution should choose different models for different issue
+kinds (for example code vs docs), while preserving orchestration protocol
+semantics.
+
+## Contents
+
+- [Purpose](#purpose)
+- [Required dependencies](#required-dependencies)
+- [Core contract](#core-contract)
+- [Overlay identity (`route:model-routing-v1`)](#overlay-identity-routemodel-routing-v1)
+- [Tag vocabulary](#tag-vocabulary)
+- [Recommendation packet contract](#recommendation-packet-contract)
+- [Selection algorithm (deterministic)](#selection-algorithm-deterministic)
+- [Transition table](#transition-table)
+- [Planning handoff contract](#planning-handoff-contract)
+- [Subagents/heartbeat execution contract](#subagentsheartbeat-execution-contract)
+- [Failure + fallback policy](#failure--fallback-policy)
+- [HUD visibility and teardown](#hud-visibility-and-teardown)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Purpose
+
+Model-routing policies are overlays. They do not replace `orchestration`
+protocol semantics.
+
+Examples:
+- use a strong coding model for implementation leaves
+- use a stronger writing model for docs/synthesis leaves
+- choose lower-cost fast models for routine triage
+- escalate to deeper thinking for high-risk or complex nodes
+
+## Required dependencies
+
+Load these skills before applying model-routing policies:
+
+- `orchestration` (protocol primitives/invariants)
+- `subagents` (durable execution runtime)
+- `heartbeats` and/or `crons` (scheduler clock)
+- `hud` (required visibility/handoff surface)
+- `control-flow` (optional; when loop/termination overlays are also active)
+
+## Core contract
+
+1. **Overlay, don’t fork protocol**
+   - Keep `hierarchical-work.protocol/v1` + `proto:hierarchical-work-v1`.
+   - Do not redefine `kind:*`, `ctx:*`, issue lifecycle semantics, or DAG validity.
+
+2. **Harness is source-of-truth**
+   - Drive recommendations from `mu control harness --json`.
+   - Only consider authenticated providers unless policy explicitly allows otherwise.
+
+3. **Recommend, then apply**
+   - Route decisions are explicit artifacts (forum packets + optional tags),
+     not hidden implicit behavior.
+
+4. **Non-blocking by default**
+   - Routing failure should degrade safely (fallback model / default model)
+     unless a hard requirement cannot be met.
+
+5. **Bounded pass per tick**
+   - One routing decision and one bounded mutation/action bundle per heartbeat pass.
+
+6. **Per-issue/session overrides preferred**
+   - Use `mu exec --provider/--model/--thinking` or `mu turn ...` overrides.
+   - Avoid changing workspace-global operator defaults for per-issue routing.
+
+## Overlay identity (`route:model-routing-v1`)
+
+- Tag scope root (or selected subtree root) with: `route:model-routing-v1`
+- Routing metadata remains orthogonal to `kind:*`, `ctx:*`, and `flow:*`.
+
+## Tag vocabulary
+
+Recommended routing tags (policy metadata):
+
+- Scope:
+  - `route:model-routing-v1`
+- Task family:
+  - `route:task:code`
+  - `route:task:docs`
+  - `route:task:research`
+  - `route:task:ops`
+  - `route:task:review`
+  - `route:task:synth`
+  - `route:task:general`
+- Depth intent:
+  - `route:depth:fast`
+  - `route:depth:balanced`
+  - `route:depth:deep`
+- Budget intent:
+  - `route:budget:low`
+  - `route:budget:balanced`
+  - `route:budget:premium`
+- Hard modality requirement:
+  - `route:modality:image` (omit for text-only)
+- Pin indicator:
+  - `route:pin` (exact provider/model comes from packet metadata)
+
+Notes:
+- Keep tags concise and stable.
+- Put detailed routing config in forum packets (not in tag strings).
+
+## Recommendation packet contract
+
+Post one `ROUTE_RECOMMENDATION` packet to `issue:<issue-id>` before launching work
+with a selected model.
+
+Suggested packet shape (JSON block inside forum message):
+
+```text
+ROUTE_RECOMMENDATION:
+{
+  "version": "route:model-routing-v1",
+  "issue_id": "<issue-id>",
+  "harness_fingerprint": "<sha256>",
+  "selected": {
+    "provider": "<provider>",
+    "model": "<model>",
+    "thinking": "<thinking-level>"
+  },
+  "alternates": [
+    { "provider": "<provider>", "model": "<model>", "thinking": "<thinking-level>" }
+  ],
+  "constraints": {
+    "task": "code|docs|research|ops|review|synth|general",
+    "depth": "fast|balanced|deep",
+    "budget": "low|balanced|premium",
+    "modality": "text|image",
+    "min_context_window": 0
+  },
+  "rationale": [
+    "provider authenticated",
+    "supports required thinking level",
+    "meets context/modality constraints",
+    "best score under budget/depth policy"
+  ],
+  "created_at_ms": 0
+}
+```
+
+Optional root-level packet for custom preferences:
+
+```text
+ROUTE_POLICY:
+{
+  "version": "route:model-routing-v1",
+  "task_preferences": {
+    "code": [
+      { "provider": "openai-codex", "model": "gpt-5.3-codex", "thinking": "xhigh" }
+    ],
+    "docs": [
+      { "provider": "openrouter", "model": "google/gemini-3.1-pro-preview", "thinking": "high" }
+    ]
+  }
+}
+```
+
+If a preference entry is unavailable under current harness/auth state, skip it and
+continue deterministic fallback selection.
+
+## Selection algorithm (deterministic)
+
+### Inputs
+
+- Issue tags (`route:task:*`, `route:depth:*`, `route:budget:*`, `route:modality:image`, `route:pin`)
+- Optional `ROUTE_POLICY` and per-issue constraints from forum/body
+- Live harness snapshot (`mu control harness --json`)
+
+### Step 1: gather live capabilities
+
+```bash
+mu control harness --json --pretty
+```
+
+### Step 2: build candidate set
+
+1. Start from authenticated providers only.
+2. Flatten model entries across providers.
+3. Filter by hard requirements:
+   - required modality (`text` and optional `image`)
+   - minimum context window (if specified)
+   - pin requirement (`route:pin`) if specified
+4. Resolve target thinking from depth intent:
+   - `fast` -> `minimal`
+   - `balanced` -> `medium`
+   - `deep` -> `xhigh` if available, else `high`
+5. Clamp chosen thinking to model-supported `thinking_levels`.
+
+### Step 3: score candidates
+
+Use deterministic score components (example):
+
+- Hard-fit gates (must pass): auth, modality, context, thinking compatibility
+- Soft score:
+  - task preference match (`ROUTE_POLICY`/task family)
+  - reasoning/xhigh capability vs depth
+  - context headroom
+  - budget penalty from per-token cost
+
+Tie-breaker: lower estimated cost, then lexicographic `provider/model`.
+
+### Step 4: select + alternates
+
+- pick top candidate as `selected`
+- keep next N as `alternates` (recommended N=2)
+- post `ROUTE_RECOMMENDATION` packet
+
+### Step 5: apply selection
+
+For one-shot execution:
+
+```bash
+mu exec --provider <provider> --model <model> --thinking <thinking> \
+  "Use skills subagents, orchestration, model-routing, and hud. Work issue <issue-id>."
+```
+
+For existing session turn:
+
+```bash
+mu turn --session-kind cp_operator --session-id <session-id> \
+  --provider <provider> --model <model> --thinking <thinking> \
+  --body "Continue issue <issue-id> with current routing selection."
+```
+
+## Transition table
+
+Given an executable issue under `route:model-routing-v1`:
+
+1. **No routing decision yet**
+   - action: compute recommendation + post `ROUTE_RECOMMENDATION` packet
+
+2. **Routing decision exists and still valid**
+   - action: execute issue using selected provider/model/thinking
+
+3. **Selected route fails at launch/runtime**
+   - action: choose next alternate, post `ROUTE_FALLBACK`, retry bounded once
+
+4. **All alternates exhausted**
+   - action: degrade to harness default model, post `ROUTE_DEGRADED`
+
+5. **Hard requirement unmet (no valid candidates)**
+   - action: create `kind:ask` node (`ctx:human`, `actor:user`) requesting
+     provider auth/config change or constraint relaxation
+
+## Planning handoff contract
+
+When planning a routed subtree:
+
+1. Tag policy scope with `route:model-routing-v1`.
+2. Tag executable nodes with task/depth/budget intent.
+3. Record any hard constraints (modality/context) in issue body or forum packet.
+4. Optionally add root `ROUTE_POLICY` preferences.
+5. Ensure DAG remains valid under `orchestration` invariants:
+   - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
+   - `mu issues validate <root-id>`
+
+## Subagents/heartbeat execution contract
+
+Per orchestrator tick:
+
+1. Read tree + ready set + latest route packet on target issue.
+2. Read harness snapshot once per pass.
+3. Select one routing transition from the table above.
+4. Apply one bounded mutation bundle (recommend/fallback/ask/execute-start).
+5. Verify with:
+   - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
+   - `mu issues validate <root-id>`
+6. Update HUD state.
+7. Post one concise `ORCH_PASS` status update.
+8. If root is final, disable supervising heartbeat.
+
+Reusable heartbeat prompt fragment:
+
+```text
+Use skills orchestration, model-routing, subagents, and hud.
+For root <root-id>, enforce route:model-routing-v1.
+Run exactly one bounded routing/orchestration transition pass: compute or validate
+one issue's model recommendation from live `mu control harness` capabilities,
+apply one action, verify DAG state, post one ORCH_PASS, then stop.
+If validate is final, disable the supervising heartbeat and report completion.
+```
+
+## Failure + fallback policy
+
+1. **Provider/model unavailable or auth drift**
+   - post `ROUTE_FALLBACK`
+   - move to next alternate
+
+2. **Thinking level unsupported for selected model**
+   - clamp to nearest supported lower level
+   - post rationale in fallback packet
+
+3. **No candidates satisfy hard constraints**
+   - create `kind:ask` escalation with clear options:
+     - authenticate provider X
+     - relax modality/context/depth constraint
+     - approve default-model execution
+
+4. **Auditability requirement**
+   - every route change emits forum packet (`ROUTE_RECOMMENDATION`,
+     `ROUTE_FALLBACK`, `ROUTE_DEGRADED`)
+
+## HUD visibility and teardown
+
+HUD usage is not optional for active model-routing execution.
+
+- If subagents HUD is active, publish routing state there (selected model,
+  alternates remaining, last fallback reason).
+- If running model-routing standalone, own `hud_id:"model-routing"`.
+- Update HUD each bounded pass before ORCH_PASS output.
+- Follow `hud` skill ownership/teardown protocol on completion or handoff.
+
+## Evaluation scenarios
+
+1. **Coding leaf selects deep coding model**
+   - Setup: `route:task:code`, `route:depth:deep`, authenticated coding provider.
+   - Expected: recommendation picks a deep reasoning coding model and starts work.
+
+2. **Docs leaf prefers writing model**
+   - Setup: `route:task:docs` with root `ROUTE_POLICY` preference for docs.
+   - Expected: recommendation uses preferred docs model when available, otherwise fallback.
+
+3. **Auth/provider drift fallback**
+   - Setup: selected provider becomes unauthenticated mid-run.
+   - Expected: `ROUTE_FALLBACK` packet and alternate selection in next bounded pass.
+
+4. **Hard requirement escalation**
+   - Setup: issue requires image input but no authenticated image-capable models.
+   - Expected: `kind:ask` node created; downstream remains blocked until user action.

package/prompts/skills/mu/SKILL.md

@@ -177,8 +177,12 @@ mu cron --help
 ```
 
 When work is multi-step and issue-graph driven, use `planning` to shape the DAG,
-then `hud` for canonical HUD behavior, then `hierarchical-work-protocol` to keep DAG
-semantics consistent, then `subagents` for durable execution.
+then `hud` for canonical HUD behavior, then `orchestration` to keep DAG
+semantics consistent, then `control-flow` for explicit loop/termination policy,
+then `model-routing` for per-issue provider/model/thinking selection overlays,
+then `subagents` for durable execution.
+For REPL-driven exploration and context compression, use `code-mode`.
+For persistent terminal sessions and worker fan-out mechanics, use `tmux`.
 For recurring bounded automation loops, use `heartbeats`.
 For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
 
@@ -201,7 +205,11 @@ For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
 - Historical context retrieval and index maintenance: **`memory`**
 - Planning/decomposition and DAG review: **`planning`**
 - HUD contract/state updates across surfaces: **`hud`**
-- Shared DAG semantics for planning + execution: **`hierarchical-work-protocol`**
+- Shared DAG semantics for planning + execution: **`orchestration`**
+- Loop/termination policy overlays (review gates, retries, escalation): **`control-flow`**
+- Per-issue model/provider/thinking selection overlays: **`model-routing`**
+- Live REPL execution and context engineering via tmux: **`code-mode`**
+- Persistent tmux session management + worker fan-out primitives: **`tmux`**
 - Durable multi-agent orchestration: **`subagents`**
 - Recurring bounded automation scheduling: **`heartbeats`**
 - Wall-clock scheduling workflows: **`crons`**

package/prompts/skills/{hierarchical-work-protocol → orchestration}/SKILL.md

@@ -1,16 +1,19 @@
 ---
-name: hierarchical-work-protocol
-description: "Defines the shared hierarchical planning/work issue-DAG protocol used by planning and subagents. Use when creating, validating, or executing protocol-driven DAG work."
+name: orchestration
+description: "Defines the shared planning/execution orchestration protocol for issue-DAG work. Use when creating, validating, or executing protocol-driven DAG work."
 ---
 
-# hierarchical-work-protocol
+# orchestration
 
 Use this skill when work should flow through one shared protocol from planning to execution.
 
+This skill supersedes the previous `hierarchical-work-protocol` skill name.
+
 ## Contents
 
 - [Protocol identity](#protocol-identity)
 - [Canonical tags and node roles](#canonical-tags-and-node-roles)
+- [Policy overlays](#policy-overlays)
 - [Protocol primitives](#protocol-primitives)
 - [Required invariants](#required-invariants)
 - [Planning handoff contract](#planning-handoff-contract)
@@ -62,6 +65,25 @@ Node role rules:
    - Must include: `proto:hierarchical-work-v1`, `kind:ask`, `ctx:human`, `actor:user`
    - Must be non-executable (`node:agent` removed)
 
+## Policy overlays
+
+Policy overlays are layered on top of this protocol and should not redefine
+protocol primitives or `kind:*` semantics.
+
+- Keep orchestration protocol tags/kinds as source-of-truth for structure.
+- Represent policy-specific behavior with overlay tags/metadata:
+  - loop/termination policy (for example review gates, retry rounds,
+    escalation thresholds): `flow:*`
+  - per-issue model/provider/thinking routing policy: `route:*`
+- Compile overlay decisions into existing primitives (`spawn`, `fork`, `expand`,
+  `ask`, `complete`, `serial`) and per-turn/per-session model overrides
+  (`mu exec` / `mu turn` with `--provider --model --thinking`) instead of
+  introducing ad-hoc mutations.
+
+Current compositional overlay skills:
+- `control-flow` (for example `flow:review-gated-v1` behavior)
+- `model-routing` (for example `route:model-routing-v1` behavior)
+
 ## Protocol primitives
 
 ### `read_tree`

package/prompts/skills/planning/SKILL.md

@@ -21,11 +21,13 @@ Use this skill when the user asks for planning, decomposition, or a staged execu
 ## Planning HUD is required
 
 For this skill, the planning HUD is the primary status/communication surface.
+HUD usage is not optional for planning turns.
 
 - Keep HUD state in sync with real planning progress.
 - Update HUD before and after each major planning turn.
 - Use `waiting_on_user`, `next_action`, and `blocker` to communicate exactly what the user needs to do.
 - Include a HUD snapshot in user-facing planning updates.
+- Teardown/handoff HUD state explicitly when planning ends or transitions to another HUD-owning skill.
 
 Default per-turn HUD loop:
 
@@ -33,6 +35,7 @@ Default per-turn HUD loop:
 2. Keep checklist progress and root issue linkage synchronized with the live issue DAG.
 3. Emit `snapshot` (`compact` or `multiline`) and reflect it in your response.
 
+
 ## HUD skill dependency
 
 Before emitting or mutating planning HUD state, load **`hud`** and follow its canonical contract.
@@ -43,7 +46,7 @@ Before emitting or mutating planning HUD state, load **`hud`** and follow its ca
 ## Shared protocol dependency
 
 This skill plans DAGs for execution by `subagents`, so planning must follow the
-shared protocol in **`hierarchical-work-protocol`**.
+shared protocol in **`orchestration`**.
 
 Before creating or reshaping DAG nodes, load that skill and use its canonical:
 
@@ -54,6 +57,15 @@ Before creating or reshaping DAG nodes, load that skill and use its canonical:
 
 Do not invent alternate protocol names or tag schemas.
 
+If the user asks for explicit loop/termination behavior (for example review-gated
+retry rounds), load **`control-flow`** and encode policy via `flow:*` overlays
+without changing orchestration protocol semantics.
+
+If the user asks for per-issue model/provider/thinking recommendations based on
+live harness capabilities, load **`model-routing`** and encode policy via
+`route:*` overlays plus route packets (for example `ROUTE_POLICY`) without
+changing orchestration protocol semantics.
+
 ## Core contract
 
 1. **Investigate first**
@@ -64,6 +76,7 @@ Do not invent alternate protocol names or tag schemas.
    - Create root and child issues that comply with `hierarchical-work.protocol/v1`.
    - Encode dependencies so the DAG reflects execution order and synth fan-in.
    - Add clear titles, scope, acceptance criteria, and protocol tags.
+   - When model specialization is required, attach explicit `route:*` intent tags/constraints to executable nodes.
 
 3. **Drive communication through the planning HUD**
    - Load `hud` and use its canonical `mu_hud`/`HudDoc` contract.
@@ -82,7 +95,10 @@ Do not invent alternate protocol names or tag schemas.
    - Do not begin broad execution until the user signals satisfaction.
 
 6. **After user approval, ask user about next steps**
-   - On user acceptance of the plan, turn the planning HUD off.
+   - On user acceptance of the plan, teardown planning HUD ownership.
+   - If handing off to another HUD-owning skill (for example `subagents`), remove
+     `hud_id:"planning"` and keep HUD on for the next skill.
+   - If no next HUD-owning skill starts immediately, remove planning doc and turn HUD off.
    - Read the `subagents` skill and offer to supervise subagents to execute the plan.
 
 ## Suggested workflow
@@ -193,6 +209,7 @@ Required HUD updates during the loop:
 - Re-emit the `planning` HUD doc with current `phase`, checklist progress, `waiting_on_user`, `next_action`, and `blocker` after each meaningful planning step.
 - Use `{"action":"snapshot","snapshot_format":"compact"}` for concise user-facing HUD lines.
 - Keep `updated_at_ms` monotonic across updates so latest doc wins deterministically.
+- On plan completion/handoff, remove `hud_id:"planning"` and apply handoff/off semantics from the `hud` skill.
 
 ## Effective HUD usage heuristics
 
@@ -223,4 +240,5 @@ Required HUD updates during the loop:
 - Keep tasks small enough to complete in one focused pass.
 - Explicitly call out uncertain assumptions for user confirmation.
 - Prefer reversible plans and incremental checkpoints.
+- If `model-routing` is in scope, route intent/constraints are explicit and non-conflicting.
 - HUD state must be fresh, accurate, and aligned with user-visible status updates.

package/prompts/skills/setup-discord/SKILL.md

@@ -9,6 +9,13 @@ Use this skill when the user asks to set up Discord messaging for `mu`.
 
 Goal: get Discord `/mu` ingress working with minimal user effort outside the terminal.
 
+## Contents
+
+- [Required user-provided inputs](#required-user-provided-inputs)
+- [Agent-first workflow](#agent-first-workflow)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Notes and caveats](#notes-and-caveats)
+
 ## Required user-provided inputs
 
 - Public webhook base URL reachable by Discord (for example `https://mu.example.com`)

package/prompts/skills/setup-neovim/SKILL.md

@@ -9,6 +9,13 @@ Use this skill when the user asks to set up the Neovim messaging channel (`mu.nv
 
 Goal: get `:Mu ...` working against `mu` control-plane with minimal user-side editor actions.
 
+## Contents
+
+- [Required user-provided inputs](#required-user-provided-inputs)
+- [Agent-first workflow](#agent-first-workflow)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Safety and UX requirements](#safety-and-ux-requirements)
+
 ## Required user-provided inputs
 
 - Confirmation that `mu.nvim` is installed (or permission for the agent to provide install snippet)

package/prompts/skills/subagents/SKILL.md

@@ -9,7 +9,10 @@ description: "Orchestrates issue-driven subagent execution with heartbeat superv
 
 - [Purpose (what this skill is for)](#purpose-what-this-skill-is-for)
 - [Shared protocol dependency](#shared-protocol-dependency)
+- [Control-flow dependency](#control-flow-dependency)
+- [Model-routing dependency](#model-routing-dependency)
 - [HUD skill dependency](#hud-skill-dependency)
+- [tmux skill dependency](#tmux-skill-dependency)
 - [When to use](#when-to-use)
 - [Success condition](#success-condition)
 - [Dispatch modes](#dispatch-modes)
@@ -36,7 +39,7 @@ Source of truth remains in `mu issues` + `mu forum`.
 
 ## Shared protocol dependency
 
-This skill executes DAG work defined by **`hierarchical-work-protocol`**.
+This skill executes DAG work defined by **`orchestration`**.
 
 Before orchestration begins, load that skill and enforce:
 
@@ -46,13 +49,45 @@ Before orchestration begins, load that skill and enforce:
 
 Do not run subagent orchestration against alternate protocol tags.
 
+## Control-flow dependency
+
+When a subtree declares explicit loop/termination policy (for example
+`flow:review-gated-v1`), load **`control-flow`** and apply policy transitions as
+an overlay on orchestration primitives.
+
+- Keep DAG structure protocol-valid (`orchestration` remains source-of-truth).
+- Compile control-flow decisions into protocol primitives (`spawn`, `expand`,
+  `ask`, `complete`, `serial`), not ad-hoc mutations.
+
+## Model-routing dependency
+
+When a subtree declares per-issue model/provider/thinking policy (for example
+`route:model-routing-v1`), load **`model-routing`** and apply routing transitions
+as an overlay on orchestration primitives.
+
+- Keep DAG structure protocol-valid (`orchestration` remains source-of-truth).
+- Drive recommendations from live harness capabilities (`mu control harness --json`).
+- Apply route selections with per-turn/per-session overrides (`mu exec`/`mu turn`
+  `--provider --model --thinking`) instead of mutating workspace-global defaults.
+- Emit auditable route packets (`ROUTE_RECOMMENDATION`, `ROUTE_FALLBACK`,
+  `ROUTE_DEGRADED`) in forum topics.
+
 ## HUD skill dependency
 
 Before emitting or mutating subagent HUD state, load **`hud`** and follow its canonical contract.
+HUD usage is not optional for this skill.
 
 - Treat `hud` as source-of-truth for generic `mu_hud` actions, `HudDoc` shape, and rendering constraints.
 - This subagents skill defines orchestration-specific conventions only (for example `hud_id: "subagents"`, queue/activity semantics).
 
+## tmux skill dependency
+
+Before spawning/inspecting worker sessions, load **`tmux`** and follow its
+canonical session lifecycle and bounded send/capture protocol.
+
+- Treat `tmux` as source-of-truth for session ownership, completion markers, and teardown.
+- This subagents skill defines orchestration semantics and queue policy.
+
 ## When to use
 
 - Work is represented as issue-scoped deliverables with explicit outcomes.
@@ -103,14 +138,15 @@ mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
 mu forum read issue:<root-id> --limit 20 --pretty
 ```
 
-2. Choose exactly one action/primitive from `hierarchical-work-protocol`.
+2. Choose exactly one action/primitive from `orchestration`.
 3. Apply it.
 4. Verify (`get`, `children`, `ready`, `validate`).
-5. Post a human-facing `ORCH_PASS` update to forum:
+5. Update `hud_id:"subagents"` (required) and emit a compact snapshot.
+6. Post a human-facing `ORCH_PASS` update to forum:
    - start with a short title that captures status in plain language
    - follow with one concise paragraph covering: project objective context, milestone moved this pass, impact, overall progress, and next high-level step
    - include queue/worker/drift internals only when diagnosing blocker/anomaly.
-6. Exit tick.
+7. Exit tick.
 
 Stop automation when `mu issues validate <root-id>` returns final.
 
@@ -120,6 +156,7 @@ For claimed issue `<issue-id>` under `<root-id>`:
 
 1. Run `read_tree`.
 2. Choose one primitive:
+   - route policy present and no valid route decision -> apply one `model-routing` transition
    - missing input -> `ask`
    - needs decomposition -> `expand`
    - directly solvable -> `complete`
@@ -132,7 +169,7 @@ Repeat bounded passes until issue closes.
 ## Bootstrap and queue targeting
 
 If root DAG does not yet exist, create it using the
-`hierarchical-work-protocol` bootstrap template first.
+`orchestration` bootstrap template first.
 
 During orchestration, always scope queue reads with protocol tag:
 
@@ -147,9 +184,9 @@ mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
 ```bash
 mu heartbeats create \
   --title "hierarchical-work-v1 <root-id>" \
-  --reason hierarchical_work_protocol_v1 \
+  --reason orchestration_v1 \
   --every-ms 15000 \
-  --prompt "Use skills subagents, hud, and hierarchical-work-protocol for root <root-id>. Run exactly one bounded orchestration pass: inspect the proto:hierarchical-work-v1 queue, perform exactly one corrective orchestration action (including in_progress-without-worker drift recovery) or claim/work-start one ready issue, then verify state. Report human-facing progress as a titled status note plus one concise paragraph that explains project context, milestone moved, impact, overall progress, and next high-level step; avoid low-level orchestration internals unless diagnosing a blocker/anomaly. Post a matching ORCH_PASS update to issue:<root-id>. Stop when 'mu issues validate <root-id>' is final."
+  --prompt "Use skills subagents, orchestration, control-flow, model-routing, and hud for root <root-id>. Run exactly one bounded orchestration pass: inspect the proto:hierarchical-work-v1 queue, perform exactly one corrective orchestration action (including in_progress-without-worker drift recovery) or claim/work-start one ready issue, then verify state. If flow:* policy tags are present, apply one control-flow transition from the control-flow skill in this pass. If route:* policy tags are present, apply one model-routing transition from the model-routing skill in this pass using live `mu control harness` capabilities and per-turn provider/model/thinking overrides. Report human-facing progress as a titled status note plus one concise paragraph that explains project context, milestone moved, impact, overall progress, and next high-level step; avoid low-level orchestration internals unless diagnosing a blocker/anomaly. Post a matching ORCH_PASS update to issue:<root-id>. Stop when 'mu issues validate <root-id>' is final."
 ```
 
 Reusable status-voice add-on for heartbeat prompts (copy/paste):
@@ -169,13 +206,13 @@ run_id="$(date +%Y%m%d-%H%M%S)"
 for issue_id in $(mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --json | jq -r '.[].id' | head -n 3); do
   session="mu-sub-${run_id}-${issue_id}"
   tmux new-session -d -s "$session" \
-    "cd '$PWD' && mu exec 'Use skills subagents, hud, and hierarchical-work-protocol. Work issue ${issue_id} using hierarchical-work.protocol/v1. Claim first, then run one full control loop.' ; rc=\$?; echo __MU_DONE__:\$rc"
+    "cd '$PWD' && mu exec 'Use skills subagents, orchestration, control-flow, model-routing, and hud. Work issue ${issue_id} using hierarchical-work.protocol/v1. If flow:* policy tags are present, apply the control-flow overlay before selecting the next primitive. If route:* policy tags are present, apply the model-routing overlay using live harness capabilities before selecting the next primitive. Claim first, then run one full control loop.' ; rc=\$?; echo __MU_DONE__:\$rc"
 done
 ```
 
 ## Subagents HUD
 
-Use HUD for user visibility. Truth still lives in issues/forum.
+HUD usage is required for this skill. Truth still lives in issues/forum.
 
 ```text
 /mu hud on
@@ -194,7 +231,8 @@ Tool: `mu_hud`
   - actions: refresh/spawn command hooks (if desired)
   - metadata: include `style_preset:"subagents"` for consistent renderer emphasis
 - Example update:
-  - `{"action":"set","doc":{"v":1,"hud_id":"subagents","title":"Subagents HUD","scope":"mu-root-123","chips":[{"key":"health","label":"healthy","tone":"success"},{"key":"mode","label":"mode:operator","tone":"dim"},{"key":"paused","label":"paused:no","tone":"dim"}],"sections":[{"kind":"kv","title":"Queue","items":[{"key":"ready","label":"Ready","value":"3"},{"key":"active","label":"Active","value":"2"},{"key":"sessions","label":"Sessions","value":"2"}]},{"kind":"activity","title":"Activity","lines":["Spawned worker for mu-abc123","Posted ORCH_PASS update"]}],"actions":[{"id":"refresh","label":"Refresh","command_text":"/mu hud snapshot","kind":"secondary"}],"snapshot_compact":"HUD(subagents) · healthy · mode=operator · ready=3 · active=2","updated_at_ms":1771853115000,"metadata":{"style_preset":"subagents","spawn_mode":"operator","spawn_paused":false}}}`
+  - `{"action":"set", "doc": {"hud_id":"subagents", ...}}` (see `hud` skill for exact shape)
+- Follow the HUD ownership and teardown protocol from `hud` skill for completion and handoff.
 
 ## Evaluation scenarios
 
@@ -210,12 +248,17 @@ Tool: `mu_hud`
    - Setup: worker encounters missing critical input.
    - Expected: skill applies protocol `ask` semantics, creates a human-input node, and downstream work remains blocked until the answer issue closes.
 
+4. **Model-routing overlay with fallback**
+   - Setup: ready issue tagged `route:model-routing-v1` and selected model fails at launch.
+   - Expected: one bounded pass emits `ROUTE_FALLBACK`, selects alternate/provider fallback deterministically, and continues execution without violating DAG protocol rules.
+
 ## Reconciliation
 
 - Run `mu issues validate <root-id>` before declaring completion.
 - Merge synth-node outputs into one final user-facing result.
 - Convert unresolved gaps into new child issues tagged `proto:hierarchical-work-v1`.
 - Tear down temporary tmux sessions.
+- Tear down/handoff `hud_id:"subagents"` ownership following the `hud` skill protocol.
 
 ## Safety
 

package/prompts/skills/tmux/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: tmux
+description: "Provides canonical tmux session patterns for persistent REPLs, bounded command execution, and parallel worker fan-out."
+---
+
+# tmux
+
+Use this skill when other workflows need durable shell state, long-lived REPLs,
+or parallel worker sessions.
+
+This is a transport/runtime primitive skill. It does not define task semantics;
+it defines how to run sessions reliably.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [Session lifecycle primitives](#session-lifecycle-primitives)
+- [Bounded execution protocol](#bounded-execution-protocol)
+- [Parallel fan-out pattern](#parallel-fan-out-pattern)
+- [Teardown and diagnostics](#teardown-and-diagnostics)
+- [Integration map](#integration-map)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+1. **One logical task scope per session**
+   - Reuse a session for one task/thread.
+   - Use distinct names for unrelated tasks.
+
+2. **Create-or-reuse, do not assume**
+   - Always check `tmux has-session` before creating.
+
+3. **Bound command passes**
+   - Send one coherent pass, capture output, then decide the next pass.
+   - Use completion markers when possible.
+
+4. **Prefer explicit ownership**
+   - Track which sessions this run created.
+   - Tear down owned sessions at completion/handoff.
+
+5. **Keep it simple**
+   - `tmux` is a substrate; avoid extra protocol complexity unless the task requires it.
+
+## Session lifecycle primitives
+
+List and inspect:
+
+```bash
+tmux list-sessions
+```
+
+Create or reuse a shell session:
+
+```bash
+session="mu-shell-main"
+tmux has-session -t "$session" 2>/dev/null || tmux new-session -d -s "$session" "bash --noprofile --norc -i"
+```
+
+Attach for manual inspection:
+
+```bash
+tmux attach -t "$session"
+```
+
+## Bounded execution protocol
+
+Send one command pass and wait for a marker:
+
+```bash
+session="mu-shell-main"
+token="__MU_DONE_$(date +%s%N)__"
+
+tmux send-keys -t "$session" "echo start && pwd && ls" C-m
+tmux send-keys -t "$session" "echo $token" C-m
+
+for _ in $(seq 1 80); do
+  out="$(tmux capture-pane -pt "$session" -S -200)"
+  echo "$out" | grep -q "$token" && break
+  sleep 0.05
+done
+
+printf "%s\n" "$out"
+```
+
+Use this same pattern for REPL sessions (`python3 -q`, `node`, `sqlite3`, etc.).
+
+## Parallel fan-out pattern
+
+Spawn one session per independent unit of work:
+
+```bash
+run_id="$(date +%Y%m%d-%H%M%S)"
+for work_id in a b c; do
+  session="mu-worker-${run_id}-${work_id}"
+  tmux new-session -d -s "$session" "bash -lc 'echo START:${work_id}; sleep 1; echo DONE:${work_id}'"
+done
+```
+
+Inspect recent output from all workers:
+
+```bash
+for s in $(tmux list-sessions -F '#S' | grep '^mu-worker-'); do
+  echo "=== $s ==="
+  tmux capture-pane -pt "$s" -S -60 | tail -n 20
+done
+```
+
+## Teardown and diagnostics
+
+Kill one session:
+
+```bash
+tmux kill-session -t "$session"
+```
+
+Kill owned worker set by prefix:
+
+```bash
+for s in $(tmux list-sessions -F '#S' | grep '^mu-worker-20260224-'); do
+  tmux kill-session -t "$s"
+done
+```
+
+Quick diagnostics checklist:
+
+1. `tmux list-sessions` (does session exist?)
+2. `tmux capture-pane -pt <session> -S -200` (what actually happened?)
+3. check marker presence / timeout behavior
+4. recreate session if shell state is irrecoverably bad
+
+## Integration map
+
+- `code-mode`: tmux-backed REPL persistence and context engineering loops
+- `subagents`: tmux fan-out for parallel worker execution
+- `heartbeats` / `crons`: schedule bounded passes that dispatch into tmux workers
+
+## Evaluation scenarios
+
+1. **Persistent REPL continuity**
+   - Setup: run multi-pass Python debugging task.
+   - Expected: same session reused; state persists across passes.
+
+2. **Bounded pass completion**
+   - Setup: command that emits long output.
+   - Expected: completion marker reliably terminates capture loop.
+
+3. **Parallel worker fan-out**
+   - Setup: three independent work items.
+   - Expected: one session per item, inspectable output, clean teardown.