@femtomc/mu-agent 26.2.103 → 26.2.105

package/README.md

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

package/dist/extensions/branding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branding.d.ts","sourceRoot":"","sources":["../../src/extensions/branding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAwEpF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,QAoOjD;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"branding.d.ts","sourceRoot":"","sources":["../../src/extensions/branding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAsGpF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,QAuPjD;AAED,eAAe,iBAAiB,CAAC"}

package/dist/extensions/branding.js

@@ -6,7 +6,10 @@
  * - Terminal title and working message branding
  * - Lightweight periodic status refresh (open/ready/control-plane)
  */
+import { readFileSync } from "node:fs";
 import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Image as TuiImage, detectCapabilities } from "@mariozechner/pi-tui";
 import { MU_DEFAULT_THEME_NAME, MU_VERSION } from "../ui_defaults.js";
 import { registerMuSubcommand } from "./mu-command-dispatcher.js";
 import { fetchMuStatus, muServerUrl } from "./shared.js";
@@ -17,6 +20,24 @@ const EMPTY_SNAPSHOT = {
     adapters: [],
     error: null,
 };
+const TUI_LOGO_MIME_TYPE = "image/png";
+const TUI_LOGO_FILENAME = "mu-tui-logo.png";
+const TUI_LOGO_MAX_WIDTH_CELLS = 16;
+function resolveTuiLogoPath() {
+    return fileURLToPath(new URL("../../assets/mu-tui-logo.png", import.meta.url));
+}
+function readTuiLogoBase64() {
+    try {
+        return readFileSync(resolveTuiLogoPath()).toString("base64");
+    }
+    catch {
+        return null;
+    }
+}
+const TUI_LOGO_BASE64 = readTuiLogoBase64();
+function canRenderTuiLogoImage() {
+    return TUI_LOGO_BASE64 !== null && detectCapabilities().images !== null;
+}
 const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
 function visibleWidth(text) {
     return text.replace(ANSI_RE, "").length;
@@ -38,6 +59,12 @@ function centerLine(text, width) {
     const pad = Math.floor((width - vw) / 2);
     return " ".repeat(pad) + text;
 }
+function centerLogoLines(lines, width) {
+    const targetLogoWidth = Math.max(1, Math.min(TUI_LOGO_MAX_WIDTH_CELLS, width - 2));
+    const pad = Math.max(0, Math.floor((width - targetLogoWidth) / 2));
+    const prefix = " ".repeat(pad);
+    return lines.map((line) => (line.length > 0 ? `${prefix}${line}` : line));
+}
 function routesFromStatus(adapters, routes) {
     if (routes && routes.length > 0)
         return routes;
@@ -85,24 +112,35 @@ export function brandingExtension(pi) {
         ctx.ui.setTitle(`mu · ${repoName}`);
         ctx.ui.setWorkingMessage("working…");
         ctx.ui.setWidget("mu-quick-actions", undefined);
-        ctx.ui.setHeader((_tui, theme) => ({
-            render(width) {
-                const cpPart = snapshot.error
-                    ? ""
-                    : snapshot.controlPlaneActive
-                        ? ` ${theme.fg("muted", "·")} ${theme.fg("success", `cp:${snapshot.adapters.join(",") || "on"}`)}`
-                        : "";
-                const line = [
-                    theme.fg("accent", theme.bold("μ")),
-                    theme.fg("muted", "·"),
-                    theme.fg("dim", `v${MU_VERSION}`),
-                    theme.fg("muted", "·"),
-                    theme.fg("dim", repoName),
-                ].join(" ") + cpPart;
-                return [centerLine(line, width)];
-            },
-            invalidate() { },
-        }));
+        ctx.ui.setHeader((_tui, theme) => {
+            const logoComponent = canRenderTuiLogoImage()
+                ? new TuiImage(TUI_LOGO_BASE64, TUI_LOGO_MIME_TYPE, { fallbackColor: (text) => theme.fg("dim", text) }, { maxWidthCells: TUI_LOGO_MAX_WIDTH_CELLS, filename: TUI_LOGO_FILENAME })
+                : null;
+            return {
+                render(width) {
+                    const cpPart = snapshot.error
+                        ? ""
+                        : snapshot.controlPlaneActive
+                            ? ` ${theme.fg("muted", "·")} ${theme.fg("success", `cp:${snapshot.adapters.join(",") || "on"}`)}`
+                            : "";
+                    const line = [
+                        theme.fg("accent", theme.bold("μ")),
+                        theme.fg("muted", "·"),
+                        theme.fg("dim", `v${MU_VERSION}`),
+                        theme.fg("muted", "·"),
+                        theme.fg("dim", repoName),
+                    ].join(" ") + cpPart;
+                    if (!logoComponent) {
+                        return [centerLine(line, width)];
+                    }
+                    const logoLines = centerLogoLines(logoComponent.render(width), width);
+                    return [...logoLines, centerLine(line, width)];
+                },
+                invalidate() {
+                    logoComponent?.invalidate();
+                },
+            };
+        });
         ctx.ui.setFooter((tui, theme, footerData) => {
             const requestRender = () => tui.requestRender();
             const unsubscribeBranch = footerData.onBranchChange(requestRender);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.2.103",
+  "version": "26.2.105",
   "description": "Shared operator runtime for mu assistant sessions and serve extensions.",
   "keywords": [
     "mu",
@@ -20,14 +20,16 @@
   },
   "files": [
     "dist/**",
+    "assets/**",
     "prompts/**",
     "themes/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.2.103",
+    "@femtomc/mu-core": "26.2.105",
     "@mariozechner/pi-agent-core": "^0.54.2",
     "@mariozechner/pi-ai": "^0.54.2",
     "@mariozechner/pi-coding-agent": "^0.54.2",
+    "@mariozechner/pi-tui": "^0.54.2",
     "zod": "^4.1.9"
   }
 }

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,8 @@ 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)
 - `subagents`
 - `heartbeats` (for short-cadence wake loops)
 

package/prompts/skills/heartbeats/SKILL.md

@@ -145,7 +145,8 @@ 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)
 - `subagents`
 
 For wall-clock scheduling semantics (`at`, `every`, `cron`), use `crons`.

package/prompts/skills/hud/SKILL.md

@@ -18,6 +18,7 @@ This skill is the canonical HUD reference for:
 - [Core contract](#core-contract)
 - [HudDoc shape](#huddoc-shape)
 - [Recommended turn loop](#recommended-turn-loop)
+- [Ownership and teardown protocol](#ownership-and-teardown-protocol)
 - [Planning and subagents profiles](#planning-and-subagents-profiles)
 - [Determinism and rendering limits](#determinism-and-rendering-limits)
 - [Evaluation scenarios](#evaluation-scenarios)
@@ -135,6 +136,38 @@ Example checklist doc:
 
 4. Keep response text and HUD state aligned (no contradictions).
 
+## 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`).
+   - 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 and subagents profiles
 
 Use profile-specific `hud_id` values:
@@ -168,4 +201,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/mu/SKILL.md

@@ -177,8 +177,11 @@ 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 `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 +204,10 @@ 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`**
+- 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)
+- [Control-flow overlays](#control-flow-overlays)
 - [Protocol primitives](#protocol-primitives)
 - [Required invariants](#required-invariants)
 - [Planning handoff contract](#planning-handoff-contract)
@@ -62,6 +65,20 @@ Node role rules:
    - Must include: `proto:hierarchical-work-v1`, `kind:ask`, `ctx:human`, `actor:user`
    - Must be non-executable (`node:agent` removed)
 
+## Control-flow overlays
+
+Control-flow is 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 (for example review gates, retry rounds,
+  escalation thresholds) with `flow:*` tags/metadata.
+- Compile control-flow policy decisions into existing primitives (`spawn`, `fork`,
+  `expand`, `ask`, `complete`, `serial`) instead of introducing ad-hoc mutations.
+
+Current compositional control-flow policy skill:
+- `control-flow` (for example `flow:review-gated-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,10 @@ 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.
+
 ## Core contract
 
 1. **Investigate first**
@@ -82,7 +89,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 +203,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
 

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,9 @@ 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)
 - [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 +38,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 +48,32 @@ 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.
+
 ## 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 +124,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.
 
@@ -132,7 +154,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 +169,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, 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. 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 +191,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, 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. 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 +216,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
 
@@ -216,6 +239,7 @@ Tool: `mu_hud`
 - 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.