@femtomc/mu-agent 26.2.107 → 26.2.108

package/prompts/skills/core/SKILL.md

@@ -10,14 +10,14 @@ Use this meta-skill when the user asks for general `mu` operation guidance and y
 ## Subskills
 
 - `mu` — default CLI-first operating workflow (inspect, mutate, verify, handoff).
-- `memory` — historical context retrieval, timeline reconstruction, and memory-index maintenance.
+- `memory` — prior-context retrieval, timeline reconstruction, and memory-index maintenance.
 - `tmux` — persistent terminal/session substrate for bounded command execution and fan-out.
 - `code-mode` — tmux-backed REPL loops for iterative execution and context compression.
 
 ## Selection guide
 
 1. Start with `mu` for most day-to-day operator work.
-2. Add `memory` when historical context or timeline anchors are required.
+2. Add `memory` when prior context or timeline anchors are required.
 3. Add `tmux` when durable shell state or parallel worker shells are needed.
 4. Add `code-mode` when solving by live execution is cheaper than chat-only reasoning.
 

package/prompts/skills/core/memory/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: memory
-description: "Runs cross-store memory retrieval and index maintenance workflows with bounded filters and timeline anchors. Use when querying historical context or repairing memory index health."
+description: "Runs cross-store memory retrieval and index maintenance workflows with bounded filters and timeline anchors. Use when querying prior context or repairing memory index health."
 ---
 
 # memory
 
-Use this skill when the user asks for historical context lookup, timeline reconstruction,
+Use this skill when the user asks for prior-context lookup, timeline reconstruction,
 or memory index diagnostics.
 
 ## Contents

package/prompts/skills/core/mu/SKILL.md

@@ -197,7 +197,15 @@ One-shot prompt (no durable session):
 mu exec --message "<task>" --json
 ```
 
-In attached terminal operator chat, `/mu` helpers are available (`/mu events`, `/mu hud ...`, `/mu help`).
+In attached terminal operator chat, `/mu` helpers are available (`/mu events`, `/mu ui status`, `/mu ui snapshot compact`, `/mu help`).
+
+Canonical visibility checks while running orchestrated work:
+
+```bash
+/mu ui status
+/mu ui snapshot compact
+/mu ui snapshot multiline
+```
 
 ## Durable automation handoff
 
@@ -209,10 +217,13 @@ 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 `protocol` 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 `execution` for durable execution supervision.
+then `protocol` 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 `execution` for durable execution supervision.
+Keep operator↔human communication mu_ui-first across these skills:
+- one non-interactive status doc per active profile (`metadata.profile.variant: "status"`)
+- separate interactive prompt docs for decisions (`metadata.command_text` actions)
+- explicit `mu_ui remove` teardown for resolved prompts and completed passes
 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`.
@@ -234,9 +245,9 @@ For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
 
 ## Escalation map
 
-- Historical context retrieval and index maintenance: **`memory`**
+- Prior-context retrieval and index maintenance: **`memory`**
 - Planning/decomposition and DAG review: **`planning`**
-- HUD contract/state updates across surfaces: **`hud`**
+- mu_ui-first status/prompt communication patterns for DAG work: **`planning`**, **`execution`**, **`control-flow`**, **`model-routing`**
 - Shared DAG semantics for planning + execution: **`protocol`**
 - Loop/termination policy overlays (review gates, retries, escalation): **`control-flow`**
 - Per-issue model/provider/thinking selection overlays: **`model-routing`**

package/prompts/skills/subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagents
-description: "Meta-skill for protocol-driven planning and execution. Routes to planning, protocol, execution, control-flow, model-routing, and hud."
+description: "Meta-skill for protocol-driven planning and execution. Routes to planning, protocol, execution, control-flow, and model-routing with mu_ui-first communication."
 ---
 
 # subagents
@@ -14,21 +14,105 @@ Use this meta-skill when work should run through the full multi-agent DAG stack.
 - `execution` — durable orchestration/supervision loop over the DAG.
 - `control-flow` — loop/termination overlays (`flow:*`) on top of protocol primitives.
 - `model-routing` — provider/model/thinking overlays (`route:*`) from live harness capabilities.
-- `hud` — canonical HUD ownership/update/teardown contract.
 
-## Hard-cutover naming
+## Naming conventions
 
 - Use `protocol` (not `orchestration`).
-- Use `execution` (not the old execution leaf named `subagents`).
+- Use `execution` for execution/supervision workflows.
 
 ## Recommended bundles
 
-- Planning bundle: `planning` + `protocol` + `hud`
-- Execution bundle: `execution` + `protocol` + `hud`
+- Planning bundle: `planning` + `protocol`
+- Execution bundle: `execution` + `protocol`
 - Policy overlays: add `control-flow` and/or `model-routing` as needed
 
+## Canonical mu_ui communication pattern
+
+Use `mu_ui` as the shared operator↔human surface during planning/execution passes.
+
+```bash
+/mu ui status
+/mu ui snapshot compact
+/mu ui snapshot multiline
+```
+
+Status doc example (`ui:subagents`):
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:subagents",
+    "title": "Subagents execution status",
+    "summary": "ready=2 · active=1 · blocked=0",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "queue",
+        "title": "Queue",
+        "rows": [
+          { "key": "ready", "value": "2" },
+          { "key": "active", "value": "1" },
+          { "key": "blocked", "value": "0" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "subagents-status", "version": 3 },
+    "updated_at_ms": 1772060000000,
+    "metadata": {
+      "profile": {
+        "id": "subagents",
+        "variant": "status",
+        "snapshot": {
+          "compact": "ready=2 · active=1 · blocked=0",
+          "multiline": "ready: 2\nactive: 1\nblocked: 0"
+        }
+      }
+    }
+  }
+}
+```
+
+Interactive prompt example (`ui:subagents:handoff`):
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:subagents:handoff",
+    "title": "Execution handoff decision",
+    "components": [
+      { "kind": "text", "id": "question", "text": "Close root now?", "metadata": {} }
+    ],
+    "actions": [
+      {
+        "id": "close-root",
+        "label": "Close root",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer close-root" }
+      }
+    ],
+    "revision": { "id": "subagents-handoff", "version": 1 },
+    "updated_at_ms": 1772060005000,
+    "metadata": { "profile": { "id": "subagents-handoff", "variant": "interactive" } }
+  }
+}
+```
+
+Teardown/handoff uses explicit removes:
+
+```json
+{"action":"remove","ui_id":"ui:subagents:handoff"}
+{"action":"remove","ui_id":"ui:subagents"}
+```
+
 ## Common patterns
 
-- **End-to-End Orchestration**: Route to `planning` to get a structured issue DAG, present the plan in the `hud` to the user, then route to `execution` to drive the workers until the DAG is complete.
+- **End-to-End Orchestration**: Route to `planning` to get a structured issue DAG, publish plan state in `ui:planning` (status) plus `ui:planning:approval` (interactive prompt) when needed, then route to `execution` to drive workers until DAG completion.
 - **DAG Recovery / Unblocking**: If a DAG stalls, route to `protocol` to inspect `mu issues ready` constraints, followed by a bounded `execution` pass to claim and manually unblock the stalled task.
-- **Differentiated Model Provisioning**: If different nodes need different abilities (e.g. specialized docs vs. complex refactoring), add `model-routing` to set `route:model-routing-v1` policies per issue. The `execution` worker shell will then automatically spin up the required model profiles based on those policies.
+- **Differentiated Model Provisioning**: If different nodes need different abilities (for example specialized docs vs. complex refactoring), add `model-routing` to set `route:model-routing-v1` policies per issue. The `execution` worker shell will then launch the required model profiles based on those policies.

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

@@ -17,7 +17,7 @@ shared protocol.
 - [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)
+- [mu_ui visibility and handoff](#mu_ui-visibility-and-handoff)
 - [Evaluation scenarios](#evaluation-scenarios)
 
 ## Purpose
@@ -37,7 +37,7 @@ Load these skills before applying control-flow policies:
 - `protocol` (protocol primitives/invariants)
 - `execution` (durable execution runtime)
 - `heartbeats` and/or `crons` (scheduler clock)
-- `hud` (required visibility/handoff surface)
+- `mu` (for `/mu ui` inspection commands and communication checks)
 
 ## Core contract
 
@@ -128,29 +128,134 @@ Per orchestrator tick:
 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.
+5. Upsert control-flow visibility via `mu_ui` (`ui_id:"ui:subagents"` when orchestration is shared, or `ui_id:"ui:control-flow"` when standalone).
+6. Post one concise ORCH_PASS update.
+7. If final: disable heartbeat program.
 
 Reusable bounded heartbeat prompt fragment:
 
 ```text
-Use skills subagents, protocol, execution, control-flow, and hud.
+Use skills subagents, protocol, execution, control-flow, and mu.
 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,
+Run exactly one bounded control-flow transition pass, keep control-flow visibility
+current via mu_ui (`ui:subagents` or `ui:control-flow`), verify DAG state,
 post one ORCH_PASS, and stop. If validate is final, disable the supervising
 heartbeat and report completion.
 ```
 
-## HUD visibility and teardown
+## mu_ui visibility and handoff
+
+Use `mu_ui` as the primary communication surface for active control-flow
+execution.
+
+- Publish control-flow status in one status-profile doc:
+  - shared orchestration: `ui_id:"ui:subagents"`
+  - standalone control-flow loop: `ui_id:"ui:control-flow"`
+- Set profile metadata for deterministic snapshots:
+  - `metadata.profile.id: "subagents"` or `"control-flow"`
+  - `metadata.profile.variant: "status"`
+  - `metadata.profile.snapshot.compact|multiline`
+- Keep status docs non-interactive (`actions: []`).
+- For user decisions (for example max-round escalation), publish a separate
+  interactive prompt doc (for example `ui_id:"ui:control-flow:escalation"`).
+- Update status docs each bounded pass before posting `ORCH_PASS`.
+- On completion or handoff, remove control-flow-owned docs with explicit
+  `mu_ui remove` actions. Prefer `remove` over `clear`.
+
+### Canonical status doc (`ui:control-flow`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:control-flow",
+    "title": "Control-flow status",
+    "summary": "policy=review-gated · round=2/3 · state=review_pending",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "policy",
+        "title": "Review gate",
+        "rows": [
+          { "key": "policy", "value": "flow:review-gated-v1" },
+          { "key": "round", "value": "2/3" },
+          { "key": "attempt", "value": "mu-attempt-2" },
+          { "key": "review", "value": "mu-review-2" },
+          { "key": "next", "value": "Run review_2" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "control-flow-status", "version": 5 },
+    "updated_at_ms": 1772067720000,
+    "metadata": {
+      "profile": {
+        "id": "control-flow",
+        "variant": "status",
+        "snapshot": {
+          "compact": "round=2/3 · state=review_pending",
+          "multiline": "policy: review-gated\nround: 2/3\nstate: review_pending\nnext: run review_2"
+        }
+      }
+    }
+  }
+}
+```
 
-HUD usage is not optional for active control-flow execution.
+### Canonical escalation prompt (`ui:control-flow:escalation`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:control-flow:escalation",
+    "title": "Review rounds exhausted",
+    "summary": "Need user decision after max failed review rounds.",
+    "components": [
+      {
+        "kind": "text",
+        "id": "question",
+        "text": "Max review rounds were reached. Should execution open another attempt or stop for manual intervention?",
+        "metadata": {}
+      }
+    ],
+    "actions": [
+      {
+        "id": "open-extra-round",
+        "label": "Open one extra round",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer open-extra-round" }
+      },
+      {
+        "id": "stop-and-handoff",
+        "label": "Stop and hand off",
+        "kind": "secondary",
+        "payload": {},
+        "metadata": { "command_text": "/answer stop-and-handoff" }
+      }
+    ],
+    "revision": { "id": "control-flow-escalation", "version": 1 },
+    "updated_at_ms": 1772067730000,
+    "metadata": {
+      "profile": {
+        "id": "control-flow-escalation",
+        "variant": "interactive"
+      }
+    }
+  }
+}
+```
 
-- 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.
+### Teardown / handoff
 
-- Follow the HUD ownership and teardown protocol from the `hud` skill when completing or handing off.
+```json
+{"action":"remove","ui_id":"ui:control-flow:escalation"}
+{"action":"remove","ui_id":"ui:control-flow"}
+```
 
 ## Evaluation scenarios
 

package/prompts/skills/subagents/execution/SKILL.md

@@ -12,7 +12,7 @@ This skill is execution-supervision focused:
 
 - `mu heartbeats` / `mu cron` = orchestrator wake cadence
 - `tmux` + `mu exec` = parallel worker execution
-- subagents HUD = operator observability/control board
+- `mu_ui` status + prompt docs = operator↔human communication surface
 
 Source of truth remains in `mu issues` + `mu forum`.
 
@@ -22,7 +22,7 @@ Source of truth remains in `mu issues` + `mu forum`.
 - [Control-flow dependency](#control-flow-dependency)
 - [Model-routing dependency](#model-routing-dependency)
 - [Model quality defaults for orchestration](#model-quality-defaults-for-orchestration)
-- [HUD skill dependency](#hud-skill-dependency)
+- [mu_ui communication dependency](#mu_ui-communication-dependency)
 - [tmux skill dependency](#tmux-skill-dependency)
 - [When to use](#when-to-use)
 - [Success condition](#success-condition)
@@ -30,7 +30,7 @@ Source of truth remains in `mu issues` + `mu forum`.
 - [Orchestration loops](#orchestration-loops)
 - [Bootstrap and queue targeting](#bootstrap-and-queue-targeting)
 - [Dispatch templates](#dispatch-templates)
-- [Execution HUD (subagents profile)](#execution-hud-subagents-profile)
+- [Execution UI (subagents profile)](#execution-ui-subagents-profile)
 - [Evaluation scenarios](#evaluation-scenarios)
 - [Reconciliation](#reconciliation)
 - [Safety](#safety)
@@ -92,13 +92,20 @@ Operational rules:
 5. Helper shell workflows must fail fast with actionable usage text whenever
    required provider/model/thinking args are missing.
 
-## HUD skill dependency
+## mu_ui communication dependency
 
-Before emitting or mutating subagent HUD state, load **`hud`** and follow its canonical contract.
-HUD usage is not optional for this skill.
+Before publishing execution visibility or user prompts, use **`mu_ui`** as the
+primary communication surface.
 
-- Treat `hud` as source-of-truth for generic `mu_hud` actions, `HudDoc` shape, and rendering constraints.
-- This execution skill defines orchestration-specific conventions only (for example `hud_id: "subagents"`, queue/activity semantics).
+- Use one status doc at `ui_id:"ui:subagents"` for queue/worker visibility.
+- Encode status profile metadata with:
+  - `metadata.profile.id: "subagents"`
+  - `metadata.profile.variant: "status"`
+  - `metadata.profile.snapshot.compact|multiline` for deterministic snapshots.
+- Keep status docs non-interactive (`actions: []`); publish user prompts in a
+  separate interactive `ui_id` (for example `ui:subagents:handoff`).
+- Use `/mu ui status` and `/mu ui snapshot [compact|multiline]` to verify live
+  communication state during orchestration passes.
 
 ## tmux skill dependency
 
@@ -161,7 +168,8 @@ mu forum read issue:<root-id> --limit 20 --pretty
 2. Choose exactly one action/primitive from `protocol`.
 3. Apply it.
 4. Verify (`get`, `children`, `ready`, `validate`).
-5. Update `hud_id:"subagents"` (required) and emit a compact snapshot.
+5. Upsert `ui_id:"ui:subagents"` via `mu_ui` (required) and keep the status
+   snapshot current.
 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
@@ -210,7 +218,7 @@ thinking="${4:-}"
 if [ -z "$root_id" ] || [ -z "$provider" ] || [ -z "$model" ] || [ -z "$thinking" ]; then
   cat >&2 <<'USAGE'
 usage: ./orch-heartbeat.sh <root-id> <provider> <model> <thinking>
-example: ./orch-heartbeat.sh mu-4be265df openai-codex gpt-5.3-codex xhigh
+example: ./orch-heartbeat.sh mu-root-1234 openai-codex gpt-5.3-codex xhigh
 USAGE
   exit 64
 fi
@@ -219,7 +227,7 @@ mu heartbeats create \
   --title "hierarchical-work-v1 ${root_id}" \
   --reason orchestration_v1 \
   --every-ms 15000 \
-  --prompt "Use skills subagents, protocol, execution, 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. If route:* policy tags are absent, use the high-quality orchestration profile (openai-codex / gpt-5.3-codex / xhigh) for any execution launch in this pass. Any execution launch in this pass must pass explicit overrides: --provider ${provider} --model ${model} --thinking ${thinking}; if this tuple cannot be used, stop and post BLOCKED with remediation options. 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, protocol, execution, control-flow, model-routing, and mu 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. Maintain operator↔human communication via mu_ui in this pass: keep ui:subagents updated as a status-profile doc (metadata.profile.id=subagents, metadata.profile.variant=status) and, when user input is required, publish a separate interactive ui_id doc with action metadata.command_text. 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. If route:* policy tags are absent, use the high-quality orchestration profile (openai-codex / gpt-5.3-codex / xhigh) for any execution launch in this pass. Any execution launch in this pass must pass explicit overrides: --provider ${provider} --model ${model} --thinking ${thinking}; if this tuple cannot be used, stop and post BLOCKED with remediation options. 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):
@@ -244,7 +252,7 @@ limit="${5:-3}"
 if [ -z "$root_id" ] || [ -z "$provider" ] || [ -z "$model" ] || [ -z "$thinking" ]; then
   cat >&2 <<'USAGE'
 usage: ./orch-fanout.sh <root-id> <provider> <model> <thinking> [limit]
-example: ./orch-fanout.sh mu-4be265df openai-codex gpt-5.3-codex xhigh 3
+example: ./orch-fanout.sh mu-root-1234 openai-codex gpt-5.3-codex xhigh 3
 USAGE
   exit 64
 fi
@@ -253,33 +261,137 @@ 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 "$limit"); do
   session="mu-sub-${run_id}-${issue_id}"
   tmux new-session -d -s "$session" \
-    "cd '$PWD' && mu exec --provider '$provider' --model '$model' --thinking '$thinking' 'Use skills subagents, protocol, execution, 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"
+    "cd '$PWD' && mu exec --provider '$provider' --model '$model' --thinking '$thinking' 'Use skills subagents, protocol, execution, control-flow, model-routing, and mu. Work issue ${issue_id} using hierarchical-work.protocol/v1. Keep ui:subagents current via mu_ui status-profile updates and publish separate interactive ui_id docs for user decisions. 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
 ```
 
-## Execution HUD (subagents profile)
+## Execution UI (subagents profile)
 
-HUD usage is required for this skill. Truth still lives in issues/forum.
+Use `mu_ui` for active execution communication. Truth still lives in issues/forum.
 
 ```text
-/mu hud on
-/mu hud status
-/mu hud snapshot
+/mu ui status
+/mu ui snapshot compact
+/mu ui snapshot multiline
 ```
 
-Tool: `mu_hud`
+### Canonical status update (`ui:subagents`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:subagents",
+    "title": "Subagents execution status",
+    "summary": "workers=2 · ready=3 · blocked=1",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "queue",
+        "title": "Queue",
+        "rows": [
+          { "key": "ready", "value": "3" },
+          { "key": "active", "value": "2" },
+          { "key": "blocked", "value": "1" },
+          { "key": "next", "value": "Validate final synth issue" }
+        ],
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "activity",
+        "title": "Recent activity",
+        "items": [
+          { "id": "a1", "label": "Renderer work completed", "detail": "channel render updates merged" },
+          { "id": "a2", "label": "Docs pass in progress", "detail": "execution docs update running" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "subagents-status", "version": 12 },
+    "updated_at_ms": 1772067300000,
+    "metadata": {
+      "profile": {
+        "id": "subagents",
+        "variant": "status",
+        "snapshot": {
+          "compact": "workers=2 · ready=3 · blocked=1",
+          "multiline": "workers: 2\nready: 3\nblocked: 1\nnext: validate synth issue"
+        }
+      }
+    }
+  }
+}
+```
+
+### Canonical user prompt (`ui:subagents:handoff`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:subagents:handoff",
+    "title": "Execution handoff decision",
+    "summary": "Need user confirmation before final close.",
+    "components": [
+      {
+        "kind": "text",
+        "id": "question",
+        "text": "Should execution close the root now or open a follow-up issue?",
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "options",
+        "title": "Choices",
+        "items": [
+          { "id": "opt-close", "label": "Close root now" },
+          { "id": "opt-followup", "label": "Create follow-up issue first" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [
+      {
+        "id": "close-root",
+        "label": "Close root",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer close-root" }
+      },
+      {
+        "id": "create-followup",
+        "label": "Create follow-up",
+        "kind": "secondary",
+        "payload": { "title": "Document remaining follow-up gaps" },
+        "metadata": { "command_text": "/answer followup {{title}}" }
+      }
+    ],
+    "revision": { "id": "subagents-handoff", "version": 1 },
+    "updated_at_ms": 1772067310000,
+    "metadata": {
+      "profile": {
+        "id": "subagents-handoff",
+        "variant": "interactive"
+      }
+    }
+  }
+}
+```
 
-- Canonical contract: see skill `hud`
-- Actions: `status`, `snapshot`, `on`, `off`, `toggle`, `set`, `update`, `replace`, `remove`, `clear`
-- Subagents convention: maintain a HUD doc with `hud_id: "subagents"`
-- Suggested subagents doc structure:
-  - chips: health, mode, paused
-  - sections: queue counts + recent activity lines
-  - actions: refresh/spawn command hooks (if desired)
-  - metadata: include `style_preset:"subagents"` for consistent renderer emphasis
-- Example update:
-  - `{"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.
+### Teardown / handoff semantics
+
+- Remove execution-owned interactive docs when the question is resolved.
+- Remove or replace `ui:subagents` when execution completes or hands off.
+- Prefer `remove` over `clear` so other skills keep their docs intact.
+
+```json
+{"action":"remove","ui_id":"ui:subagents:handoff"}
+{"action":"remove","ui_id":"ui:subagents"}
+```
 
 ## Evaluation scenarios
 
@@ -305,7 +417,8 @@ 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.
+- Tear down/handoff execution-owned `ui_id`s (at minimum `ui:subagents`) with
+  explicit `mu_ui remove` actions.
 
 ## Safety