@femtomc/mu-agent 26.2.85 → 26.2.86

package/README.md

@@ -48,6 +48,8 @@ Current stack:
 
 - `brandingExtension` — mu compact header/footer branding + default theme
 - `eventLogExtension` — event tail + watch widget
+- `planningUiExtension` — planning phase/checklist HUD widget (`/mu plan ...`)
+- `subagentsUiExtension` — tmux subagent monitor/spawner widget (`/mu subagents ...`)
 
 Default operator UI theme is `mu-gruvbox-dark`.
 
@@ -56,6 +58,8 @@ Default operator UI theme is `mu-gruvbox-dark`.
 - `/mu events [n]` / `/mu events tail [n]` — event log tail
 - `/mu events watch on|off` — toggle event watch widget
 - `/mu brand on|off|toggle` — enable/disable UI branding
+- `/mu plan on|off|status|phase|root|check|uncheck|toggle-step|reset` — planning HUD
+- `/mu subagents on|off|status|refresh|prefix|root|role|spawn` — tmux + issue queue monitor/spawner
 - `/mu help` — dispatcher catalog of registered `/mu` subcommands
 
 ## Tooling model (CLI-first)

package/dist/extensions/index.d.ts

@@ -2,6 +2,8 @@ export { brandingExtension } from "./branding.js";
 export { eventLogExtension } from "./event-log.js";
 export { muOperatorExtension } from "./mu-operator.js";
 export { muServeExtension } from "./mu-serve.js";
+export { planningUiExtension } from "./planning-ui.js";
+export { subagentsUiExtension } from "./subagents-ui.js";
 /**
  * Serve-mode extension — single facade that bundles all serve extensions.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQjD;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAA4C,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,sBAAsB,UAA+C,CAAC;AAEnF;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,MAAM,EAAO,CAAC;AAC3D,eAAO,MAAM,wBAAwB,EAAE,MAAM,EAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAQzD;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAA4C,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,sBAAsB,UAA+C,CAAC;AAEnF;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,MAAM,EAAO,CAAC;AAC3D,eAAO,MAAM,wBAAwB,EAAE,MAAM,EAAO,CAAC"}

package/dist/extensions/index.js

@@ -2,6 +2,8 @@ export { brandingExtension } from "./branding.js";
 export { eventLogExtension } from "./event-log.js";
 export { muOperatorExtension } from "./mu-operator.js";
 export { muServeExtension } from "./mu-serve.js";
+export { planningUiExtension } from "./planning-ui.js";
+export { subagentsUiExtension } from "./subagents-ui.js";
 const RUNTIME_EXTENSION = import.meta.url.endsWith(".ts") ? "ts" : "js";
 function resolveBundledExtensionPath(moduleBasename) {
     return new URL(`./${moduleBasename}.${RUNTIME_EXTENSION}`, import.meta.url).pathname;

package/dist/extensions/mu-operator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mu-operator.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-operator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAGnD;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"mu-operator.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-operator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMlE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAKnD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/extensions/mu-operator.js

@@ -6,8 +6,12 @@
  */
 import { brandingExtension } from "./branding.js";
 import { eventLogExtension } from "./event-log.js";
+import { planningUiExtension } from "./planning-ui.js";
+import { subagentsUiExtension } from "./subagents-ui.js";
 export function muOperatorExtension(pi) {
     brandingExtension(pi);
     eventLogExtension(pi);
+    planningUiExtension(pi);
+    subagentsUiExtension(pi);
 }
 export default muOperatorExtension;

package/dist/extensions/mu-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mu-serve.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-serve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,QAGhD;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"mu-serve.d.ts","sourceRoot":"","sources":["../../src/extensions/mu-serve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMlE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,QAKhD;AAED,eAAe,gBAAgB,CAAC"}

package/dist/extensions/mu-serve.js

@@ -6,8 +6,12 @@
  */
 import { brandingExtension } from "./branding.js";
 import { eventLogExtension } from "./event-log.js";
+import { planningUiExtension } from "./planning-ui.js";
+import { subagentsUiExtension } from "./subagents-ui.js";
 export function muServeExtension(pi) {
     brandingExtension(pi);
     eventLogExtension(pi);
+    planningUiExtension(pi);
+    subagentsUiExtension(pi);
 }
 export default muServeExtension;

package/dist/extensions/planning-ui.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function planningUiExtension(pi: ExtensionAPI): void;
+export default planningUiExtension;
+//# sourceMappingURL=planning-ui.d.ts.map

package/dist/extensions/planning-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/planning-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA4FpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAoHnD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/extensions/planning-ui.js

@@ -0,0 +1,179 @@
+import { registerMuSubcommand } from "./mu-command-dispatcher.js";
+const DEFAULT_STEPS = [
+    "Investigate relevant code/docs/state",
+    "Create root issue + decomposed child issues",
+    "Present plan with IDs, ordering, risks",
+    "Refine with user feedback until approved",
+];
+function createDefaultState() {
+    return {
+        enabled: false,
+        phase: "investigating",
+        rootIssueId: null,
+        steps: DEFAULT_STEPS.map((label) => ({ label, done: false })),
+    };
+}
+function summarizePhase(phase) {
+    switch (phase) {
+        case "investigating":
+            return "investigating";
+        case "drafting":
+            return "drafting";
+        case "reviewing":
+            return "reviewing";
+        case "approved":
+            return "approved";
+    }
+}
+function renderPlanningUi(ctx, state) {
+    if (!ctx.hasUI) {
+        return;
+    }
+    if (!state.enabled) {
+        ctx.ui.setStatus("mu-planning", undefined);
+        ctx.ui.setWidget("mu-planning", undefined);
+        return;
+    }
+    const done = state.steps.filter((step) => step.done).length;
+    const total = state.steps.length;
+    const phase = summarizePhase(state.phase);
+    const rootSuffix = state.rootIssueId ? ` root:${state.rootIssueId}` : "";
+    ctx.ui.setStatus("mu-planning", ctx.ui.theme.fg("dim", `planning ${done}/${total} · ${phase}${rootSuffix}`));
+    const lines = [
+        ctx.ui.theme.fg("accent", `Planning (${phase})`),
+        state.rootIssueId
+            ? ctx.ui.theme.fg("dim", `  root issue: ${state.rootIssueId}`)
+            : ctx.ui.theme.fg("dim", "  root issue: (unset)"),
+        ...state.steps.map((step, index) => {
+            const mark = step.done ? ctx.ui.theme.fg("success", "☑") : ctx.ui.theme.fg("muted", "☐");
+            return `${mark} ${index + 1}. ${step.label}`;
+        }),
+    ];
+    ctx.ui.setWidget("mu-planning", lines, { placement: "belowEditor" });
+}
+function planningUsageText() {
+    return [
+        "Usage:",
+        "  /mu plan on|off|toggle|status|reset",
+        "  /mu plan phase <investigating|drafting|reviewing|approved>",
+        "  /mu plan root <issue-id|clear>",
+        "  /mu plan check <n> | /mu plan uncheck <n> | /mu plan toggle-step <n>",
+    ].join("\n");
+}
+function parsePlanningPhase(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === "investigating" || value === "drafting" || value === "reviewing" || value === "approved") {
+        return value;
+    }
+    return null;
+}
+export function planningUiExtension(pi) {
+    let state = createDefaultState();
+    const notify = (ctx, message, level = "info") => {
+        ctx.ui.notify(`${message}\n\n${planningUsageText()}`, level);
+    };
+    const refresh = (ctx) => {
+        renderPlanningUi(ctx, state);
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        refresh(ctx);
+    });
+    pi.on("session_switch", async (_event, ctx) => {
+        refresh(ctx);
+    });
+    registerMuSubcommand(pi, {
+        subcommand: "plan",
+        summary: "Planning HUD: phase + checklist widget for planning workflows",
+        usage: "/mu plan on|off|toggle|status|phase|root|check|uncheck|toggle-step|reset",
+        handler: async (args, ctx) => {
+            const tokens = args
+                .trim()
+                .split(/\s+/)
+                .filter((token) => token.length > 0);
+            if (tokens.length === 0 || tokens[0] === "status") {
+                const done = state.steps.filter((step) => step.done).length;
+                const root = state.rootIssueId ?? "(unset)";
+                ctx.ui.notify(`Planning HUD: ${state.enabled ? "enabled" : "disabled"}\nphase: ${state.phase}\nroot: ${root}\nsteps: ${done}/${state.steps.length}`, "info");
+                refresh(ctx);
+                return;
+            }
+            switch (tokens[0]) {
+                case "on":
+                    state.enabled = true;
+                    refresh(ctx);
+                    ctx.ui.notify("Planning HUD enabled.", "info");
+                    return;
+                case "off":
+                    state.enabled = false;
+                    refresh(ctx);
+                    ctx.ui.notify("Planning HUD disabled.", "info");
+                    return;
+                case "toggle":
+                    state.enabled = !state.enabled;
+                    refresh(ctx);
+                    ctx.ui.notify(`Planning HUD ${state.enabled ? "enabled" : "disabled"}.`, "info");
+                    return;
+                case "reset":
+                    state = createDefaultState();
+                    refresh(ctx);
+                    ctx.ui.notify("Planning HUD state reset.", "info");
+                    return;
+                case "phase": {
+                    const phase = parsePlanningPhase(tokens[1] ?? "");
+                    if (!phase) {
+                        notify(ctx, "Invalid phase.", "error");
+                        return;
+                    }
+                    state.phase = phase;
+                    state.enabled = true;
+                    refresh(ctx);
+                    ctx.ui.notify(`Planning phase set to ${phase}.`, "info");
+                    return;
+                }
+                case "root": {
+                    const value = (tokens[1] ?? "").trim();
+                    if (!value) {
+                        notify(ctx, "Missing root issue id.", "error");
+                        return;
+                    }
+                    state.rootIssueId = value.toLowerCase() === "clear" ? null : value;
+                    state.enabled = true;
+                    refresh(ctx);
+                    ctx.ui.notify(`Planning root set to ${state.rootIssueId ?? "(unset)"}.`, "info");
+                    return;
+                }
+                case "check":
+                case "uncheck":
+                case "toggle-step": {
+                    const indexRaw = tokens[1] ?? "";
+                    const parsed = Number.parseInt(indexRaw, 10);
+                    if (!Number.isFinite(parsed)) {
+                        notify(ctx, "Step index must be a number.", "error");
+                        return;
+                    }
+                    if (parsed < 1 || parsed > state.steps.length) {
+                        notify(ctx, `Step index out of range (1-${state.steps.length}).`, "error");
+                        return;
+                    }
+                    const index = parsed - 1;
+                    if (tokens[0] === "check") {
+                        state.steps[index].done = true;
+                    }
+                    else if (tokens[0] === "uncheck") {
+                        state.steps[index].done = false;
+                    }
+                    else {
+                        state.steps[index].done = !state.steps[index].done;
+                    }
+                    state.enabled = true;
+                    refresh(ctx);
+                    ctx.ui.notify(`Planning step ${index + 1} updated.`, "info");
+                    return;
+                }
+                default:
+                    notify(ctx, `Unknown plan command: ${tokens[0]}`, "error");
+            }
+        },
+    });
+}
+export default planningUiExtension;

package/dist/extensions/subagents-ui.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function subagentsUiExtension(pi: ExtensionAPI): void;
+export default subagentsUiExtension;
+//# sourceMappingURL=subagents-ui.d.ts.map

package/dist/extensions/subagents-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/subagents-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAuapF,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,QAmRpD;AAED,eAAe,oBAAoB,CAAC"}

package/dist/extensions/subagents-ui.js

@@ -0,0 +1,602 @@
+import { registerMuSubcommand } from "./mu-command-dispatcher.js";
+const DEFAULT_PREFIX = "mu-sub-";
+const DEFAULT_ROLE_TAG = "role:worker";
+const ISSUE_LIST_LIMIT = 40;
+const MU_CLI_TIMEOUT_MS = 12_000;
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function spawnRunId(now = new Date()) {
+    return now.toISOString().replaceAll(/[-:TZ.]/g, "").slice(0, 14);
+}
+function issueHasSession(sessions, issueId) {
+    return sessions.some((session) => session === issueId ||
+        session.endsWith(`-${issueId}`) ||
+        session.includes(`-${issueId}-`) ||
+        session.includes(`_${issueId}`));
+}
+function buildSubagentPrompt(issue) {
+    return [
+        `Work issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
+        `First run: mu issues claim ${issue.id}.`,
+        `Keep forum updates in topic issue:${issue.id}.`,
+        "When done, close with an explicit outcome and summary.",
+    ].join(" ");
+}
+async function spawnIssueTmuxSession(opts) {
+    const shellCommand = `cd ${shellQuote(opts.cwd)} && mu exec ${shellQuote(buildSubagentPrompt(opts.issue))} ; rc=$?; echo __MU_DONE__:$rc`;
+    let proc = null;
+    try {
+        proc = Bun.spawn({
+            cmd: ["tmux", "new-session", "-d", "-s", opts.sessionName, shellCommand],
+            stdin: "ignore",
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `failed to launch tmux session: ${message}` };
+    }
+    const [exitCode, stderr] = await Promise.all([proc.exited, readableText(proc.stderr)]);
+    if (exitCode !== 0) {
+        const detail = stderr.trim();
+        return { ok: false, error: detail.length > 0 ? detail : `tmux exited ${exitCode}` };
+    }
+    return { ok: true, error: null };
+}
+function readableText(stream) {
+    if (stream && typeof stream === "object" && "getReader" in stream) {
+        return new Response(stream).text().catch(() => "");
+    }
+    return Promise.resolve("");
+}
+function createDefaultState() {
+    return {
+        enabled: false,
+        prefix: DEFAULT_PREFIX,
+        sessions: [],
+        sessionError: null,
+        issueRootId: null,
+        issueRoleTag: DEFAULT_ROLE_TAG,
+        readyIssues: [],
+        activeIssues: [],
+        issueError: null,
+        lastUpdatedMs: null,
+    };
+}
+function truncateOneLine(input, maxLen = 68) {
+    const compact = input.replace(/\s+/g, " ").trim();
+    if (compact.length <= maxLen) {
+        return compact;
+    }
+    return `${compact.slice(0, Math.max(0, maxLen - 1))}…`;
+}
+function summarizeFailure(label, outcome) {
+    if (outcome.error) {
+        return `${label}: ${outcome.error}`;
+    }
+    if (outcome.timedOut) {
+        return `${label}: timed out after ${MU_CLI_TIMEOUT_MS}ms`;
+    }
+    const stderr = outcome.stderr.trim();
+    if (stderr.length > 0) {
+        return `${label}: ${stderr}`;
+    }
+    const stdout = outcome.stdout.trim();
+    if (stdout.length > 0) {
+        return `${label}: ${truncateOneLine(stdout, 120)}`;
+    }
+    return `${label}: exit ${outcome.exitCode}`;
+}
+function normalizeIssueDigest(row) {
+    if (!row || typeof row !== "object") {
+        return null;
+    }
+    const value = row;
+    const id = typeof value.id === "string" ? value.id.trim() : "";
+    const title = typeof value.title === "string" ? value.title : "";
+    const status = value.status;
+    const priorityRaw = value.priority;
+    const tagsRaw = value.tags;
+    if (!id || !title) {
+        return null;
+    }
+    if (status !== "open" && status !== "in_progress" && status !== "closed") {
+        return null;
+    }
+    const priority = typeof priorityRaw === "number" && Number.isFinite(priorityRaw) ? Math.trunc(priorityRaw) : 3;
+    const tags = Array.isArray(tagsRaw) ? tagsRaw.filter((tag) => typeof tag === "string") : [];
+    return {
+        id,
+        title,
+        status,
+        priority,
+        tags,
+    };
+}
+function parseIssueArray(label, jsonText) {
+    const trimmed = jsonText.trim();
+    if (trimmed.length === 0) {
+        return { issues: [], error: null };
+    }
+    let parsed = null;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { issues: [], error: `${label}: invalid JSON output from mu issues command` };
+    }
+    if (!Array.isArray(parsed)) {
+        return { issues: [], error: `${label}: expected JSON array output from mu issues command` };
+    }
+    const issues = parsed.map(normalizeIssueDigest).filter((issue) => issue !== null);
+    issues.sort((left, right) => {
+        if (left.priority !== right.priority) {
+            return left.priority - right.priority;
+        }
+        return left.id.localeCompare(right.id);
+    });
+    return { issues, error: null };
+}
+async function runMuCli(args) {
+    let proc = null;
+    try {
+        proc = Bun.spawn({
+            cmd: ["mu", ...args],
+            stdin: "ignore",
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "",
+            timedOut: false,
+            error: `failed to launch mu CLI (${message})`,
+        };
+    }
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        proc?.kill();
+    }, MU_CLI_TIMEOUT_MS);
+    const [exitCode, stdout, stderr] = await Promise.all([proc.exited, readableText(proc.stdout), readableText(proc.stderr)]);
+    clearTimeout(timeout);
+    return {
+        exitCode,
+        stdout,
+        stderr,
+        timedOut,
+        error: null,
+    };
+}
+async function listTmuxSessions(prefix) {
+    let proc = null;
+    try {
+        proc = Bun.spawn({
+            cmd: ["tmux", "ls"],
+            stdin: "ignore",
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { sessions: [], error: `failed to launch tmux: ${message}` };
+    }
+    const [exitCode, stdout, stderr] = await Promise.all([proc.exited, readableText(proc.stdout), readableText(proc.stderr)]);
+    const stderrTrimmed = stderr.trim();
+    if (exitCode !== 0) {
+        const lowered = stderrTrimmed.toLowerCase();
+        if (lowered.includes("no server running") || lowered.includes("failed to connect to server")) {
+            return { sessions: [], error: null };
+        }
+        const detail = stderrTrimmed.length > 0 ? stderrTrimmed : `tmux exited ${exitCode}`;
+        return { sessions: [], error: detail };
+    }
+    const sessions = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const colon = line.indexOf(":");
+        return colon >= 0 ? line.slice(0, colon).trim() : line;
+    })
+        .filter((name) => name.length > 0)
+        .filter((name) => (prefix.length > 0 ? name.startsWith(prefix) : true))
+        .sort((left, right) => left.localeCompare(right));
+    return { sessions, error: null };
+}
+async function listIssueSlices(rootId, roleTag) {
+    const readyArgs = ["issues", "ready", "--json", "--limit", String(ISSUE_LIST_LIMIT)];
+    const activeArgs = ["issues", "list", "--status", "in_progress", "--json", "--limit", String(ISSUE_LIST_LIMIT)];
+    if (rootId) {
+        readyArgs.push("--root", rootId);
+        activeArgs.push("--root", rootId);
+    }
+    if (roleTag) {
+        readyArgs.push("--tag", roleTag);
+        activeArgs.push("--tag", roleTag);
+    }
+    const [readyOutcome, activeOutcome] = await Promise.all([runMuCli(readyArgs), runMuCli(activeArgs)]);
+    if (readyOutcome.exitCode !== 0 || readyOutcome.error || readyOutcome.timedOut) {
+        return {
+            ready: [],
+            active: [],
+            error: summarizeFailure("ready", readyOutcome),
+        };
+    }
+    if (activeOutcome.exitCode !== 0 || activeOutcome.error || activeOutcome.timedOut) {
+        return {
+            ready: [],
+            active: [],
+            error: summarizeFailure("in-progress", activeOutcome),
+        };
+    }
+    const readyParsed = parseIssueArray("ready", readyOutcome.stdout);
+    if (readyParsed.error) {
+        return { ready: [], active: [], error: readyParsed.error };
+    }
+    const activeParsed = parseIssueArray("in-progress", activeOutcome.stdout);
+    if (activeParsed.error) {
+        return { ready: [], active: [], error: activeParsed.error };
+    }
+    return {
+        ready: readyParsed.issues,
+        active: activeParsed.issues,
+        error: null,
+    };
+}
+function formatIssueLine(ctx, issue) {
+    const id = ctx.ui.theme.fg("dim", issue.id);
+    const priority = ctx.ui.theme.fg("muted", `p${issue.priority}`);
+    return `  ${ctx.ui.theme.fg("success", "•")} ${id} ${priority} ${truncateOneLine(issue.title)}`;
+}
+function renderSubagentsUi(ctx, state) {
+    if (!ctx.hasUI) {
+        return;
+    }
+    if (!state.enabled) {
+        ctx.ui.setStatus("mu-subagents", undefined);
+        ctx.ui.setWidget("mu-subagents", undefined);
+        return;
+    }
+    const issueScope = state.issueRootId ? `root ${state.issueRootId}` : "all roots";
+    const roleScope = state.issueRoleTag ? state.issueRoleTag : "(all roles)";
+    const issueStatus = `${state.readyIssues.length} ready / ${state.activeIssues.length} active`;
+    if (state.sessionError || state.issueError) {
+        ctx.ui.setStatus("mu-subagents", ctx.ui.theme.fg("warning", `subagents ${state.sessions.length} · issues ${issueStatus} · degraded`));
+    }
+    else {
+        ctx.ui.setStatus("mu-subagents", ctx.ui.theme.fg("dim", `subagents ${state.sessions.length} · issues ${issueStatus} · ${issueScope}`));
+    }
+    const lines = [
+        ctx.ui.theme.fg("accent", "Subagents monitor"),
+        ctx.ui.theme.fg("dim", `  tmux prefix: ${state.prefix || "(all sessions)"}`),
+        ctx.ui.theme.fg("dim", `  issue scope: ${issueScope} · tag ${roleScope}`),
+    ];
+    if (state.sessionError) {
+        lines.push(ctx.ui.theme.fg("warning", `  tmux error: ${state.sessionError}`));
+    }
+    else if (state.sessions.length === 0) {
+        lines.push(ctx.ui.theme.fg("muted", "  tmux: (no matching sessions)"));
+    }
+    else {
+        for (const name of state.sessions.slice(0, 8)) {
+            lines.push(`  ${ctx.ui.theme.fg("success", "●")} ${name}`);
+        }
+        if (state.sessions.length > 8) {
+            lines.push(ctx.ui.theme.fg("muted", `  ... +${state.sessions.length - 8} more tmux sessions`));
+        }
+    }
+    if (state.issueError) {
+        lines.push(ctx.ui.theme.fg("warning", `  issue error: ${state.issueError}`));
+    }
+    else {
+        lines.push(ctx.ui.theme.fg("accent", "Ready issues"));
+        if (state.readyIssues.length === 0) {
+            lines.push(ctx.ui.theme.fg("muted", "  (no ready issues)"));
+        }
+        else {
+            for (const issue of state.readyIssues.slice(0, 6)) {
+                lines.push(formatIssueLine(ctx, issue));
+            }
+            if (state.readyIssues.length > 6) {
+                lines.push(ctx.ui.theme.fg("muted", `  ... +${state.readyIssues.length - 6} more ready issues`));
+            }
+        }
+        lines.push(ctx.ui.theme.fg("accent", "Active issues"));
+        if (state.activeIssues.length === 0) {
+            lines.push(ctx.ui.theme.fg("muted", "  (no in-progress issues)"));
+        }
+        else {
+            for (const issue of state.activeIssues.slice(0, 6)) {
+                lines.push(formatIssueLine(ctx, issue));
+            }
+            if (state.activeIssues.length > 6) {
+                lines.push(ctx.ui.theme.fg("muted", `  ... +${state.activeIssues.length - 6} more active issues`));
+            }
+        }
+    }
+    ctx.ui.setWidget("mu-subagents", lines, { placement: "belowEditor" });
+}
+function subagentsUsageText() {
+    return [
+        "Usage:",
+        "  /mu subagents on|off|toggle|status|refresh",
+        "  /mu subagents prefix <text|clear>",
+        "  /mu subagents root <issue-id|clear>",
+        "  /mu subagents role <tag|clear>",
+        "  /mu subagents spawn [N|all]",
+    ].join("\n");
+}
+function normalizeRoleTag(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "clear") {
+        return null;
+    }
+    if (trimmed === "worker" || trimmed === "orchestrator") {
+        return `role:${trimmed}`;
+    }
+    return trimmed;
+}
+export function subagentsUiExtension(pi) {
+    let activeCtx = null;
+    let pollTimer = null;
+    let state = createDefaultState();
+    const refresh = async (ctx) => {
+        if (!state.enabled) {
+            renderSubagentsUi(ctx, state);
+            return;
+        }
+        const [tmux, issues] = await Promise.all([
+            listTmuxSessions(state.prefix),
+            listIssueSlices(state.issueRootId, state.issueRoleTag),
+        ]);
+        state.sessions = tmux.sessions;
+        state.sessionError = tmux.error;
+        state.readyIssues = issues.ready;
+        state.activeIssues = issues.active;
+        state.issueError = issues.error;
+        state.lastUpdatedMs = Date.now();
+        renderSubagentsUi(ctx, state);
+    };
+    const stopPolling = () => {
+        if (!pollTimer) {
+            return;
+        }
+        clearInterval(pollTimer);
+        pollTimer = null;
+    };
+    const ensurePolling = () => {
+        if (pollTimer) {
+            return;
+        }
+        pollTimer = setInterval(() => {
+            if (!activeCtx) {
+                return;
+            }
+            void refresh(activeCtx);
+        }, 8_000);
+    };
+    const notify = (ctx, message, level = "info") => {
+        ctx.ui.notify(`${message}\n\n${subagentsUsageText()}`, level);
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        activeCtx = ctx;
+        if (state.enabled) {
+            ensurePolling();
+        }
+        await refresh(ctx);
+    });
+    pi.on("session_switch", async (_event, ctx) => {
+        activeCtx = ctx;
+        if (state.enabled) {
+            ensurePolling();
+        }
+        await refresh(ctx);
+    });
+    pi.on("session_shutdown", async () => {
+        stopPolling();
+        activeCtx = null;
+    });
+    registerMuSubcommand(pi, {
+        subcommand: "subagents",
+        summary: "Monitor tmux subagent sessions + issue queue, and spawn ready issue sessions",
+        usage: "/mu subagents on|off|toggle|status|refresh|prefix|root|role|spawn",
+        handler: async (args, ctx) => {
+            activeCtx = ctx;
+            const tokens = args
+                .trim()
+                .split(/\s+/)
+                .filter((token) => token.length > 0);
+            if (tokens.length === 0 || tokens[0] === "status") {
+                const when = state.lastUpdatedMs == null ? "never" : new Date(state.lastUpdatedMs).toLocaleTimeString();
+                const status = state.enabled ? "enabled" : "disabled";
+                const issueScope = state.issueRootId ?? "(all roots)";
+                const issueRole = state.issueRoleTag ?? "(all roles)";
+                const issueError = state.issueError ? `\nissue_error: ${state.issueError}` : "";
+                const tmuxError = state.sessionError ? `\ntmux_error: ${state.sessionError}` : "";
+                ctx.ui.notify([
+                    `Subagents monitor ${status}`,
+                    `prefix: ${state.prefix || "(all sessions)"}`,
+                    `issue_root: ${issueScope}`,
+                    `issue_role: ${issueRole}`,
+                    `sessions: ${state.sessions.length}`,
+                    `ready_issues: ${state.readyIssues.length}`,
+                    `active_issues: ${state.activeIssues.length}`,
+                    `last refresh: ${when}`,
+                ].join("\n") + issueError + tmuxError, state.issueError || state.sessionError ? "warning" : "info");
+                renderSubagentsUi(ctx, state);
+                return;
+            }
+            switch (tokens[0]) {
+                case "on":
+                    state.enabled = true;
+                    ensurePolling();
+                    await refresh(ctx);
+                    ctx.ui.notify("Subagents monitor enabled.", "info");
+                    return;
+                case "off":
+                    state.enabled = false;
+                    stopPolling();
+                    renderSubagentsUi(ctx, state);
+                    ctx.ui.notify("Subagents monitor disabled.", "info");
+                    return;
+                case "toggle":
+                    state.enabled = !state.enabled;
+                    if (state.enabled) {
+                        ensurePolling();
+                        await refresh(ctx);
+                    }
+                    else {
+                        stopPolling();
+                        renderSubagentsUi(ctx, state);
+                    }
+                    ctx.ui.notify(`Subagents monitor ${state.enabled ? "enabled" : "disabled"}.`, "info");
+                    return;
+                case "refresh": {
+                    await refresh(ctx);
+                    ctx.ui.notify("Subagents monitor refreshed.", "info");
+                    return;
+                }
+                case "prefix": {
+                    const value = tokens.slice(1).join(" ").trim();
+                    if (!value) {
+                        notify(ctx, "Missing prefix value.", "error");
+                        return;
+                    }
+                    state.prefix = value.toLowerCase() === "clear" ? "" : value;
+                    state.enabled = true;
+                    ensurePolling();
+                    await refresh(ctx);
+                    ctx.ui.notify(`Subagents prefix set to ${state.prefix || "(all sessions)"}.`, "info");
+                    return;
+                }
+                case "root": {
+                    const value = tokens.slice(1).join(" ").trim();
+                    if (!value) {
+                        notify(ctx, "Missing root issue id.", "error");
+                        return;
+                    }
+                    state.issueRootId = value.toLowerCase() === "clear" ? null : value;
+                    state.enabled = true;
+                    ensurePolling();
+                    await refresh(ctx);
+                    ctx.ui.notify(`Subagents root set to ${state.issueRootId ?? "(all roots)"}.`, "info");
+                    return;
+                }
+                case "role": {
+                    const value = tokens.slice(1).join(" ").trim();
+                    if (!value) {
+                        notify(ctx, "Missing role/tag value.", "error");
+                        return;
+                    }
+                    state.issueRoleTag = normalizeRoleTag(value);
+                    state.enabled = true;
+                    ensurePolling();
+                    await refresh(ctx);
+                    ctx.ui.notify(`Subagents issue tag filter set to ${state.issueRoleTag ?? "(all roles)"}.`, "info");
+                    return;
+                }
+                case "spawn": {
+                    if (!state.issueRootId) {
+                        notify(ctx, "Set a root first (`/mu subagents root <root-id>`) before spawning.", "error");
+                        return;
+                    }
+                    let spawnLimit = null;
+                    const limitToken = tokens[1]?.trim();
+                    if (limitToken && limitToken.toLowerCase() !== "all") {
+                        const parsed = Number.parseInt(limitToken, 10);
+                        if (!Number.isFinite(parsed) || parsed < 1 || parsed > ISSUE_LIST_LIMIT) {
+                            notify(ctx, `Spawn count must be 1-${ISSUE_LIST_LIMIT} or 'all'.`, "error");
+                            return;
+                        }
+                        spawnLimit = parsed;
+                    }
+                    const issueSlices = await listIssueSlices(state.issueRootId, state.issueRoleTag);
+                    state.readyIssues = issueSlices.ready;
+                    state.activeIssues = issueSlices.active;
+                    state.issueError = issueSlices.error;
+                    if (issueSlices.error) {
+                        state.enabled = true;
+                        ensurePolling();
+                        renderSubagentsUi(ctx, state);
+                        notify(ctx, `Cannot spawn: ${issueSlices.error}`, "error");
+                        return;
+                    }
+                    const candidates = spawnLimit == null ? issueSlices.ready : issueSlices.ready.slice(0, spawnLimit);
+                    if (candidates.length === 0) {
+                        state.enabled = true;
+                        ensurePolling();
+                        await refresh(ctx);
+                        ctx.ui.notify("No ready issues to spawn for current root/tag filter.", "info");
+                        return;
+                    }
+                    const spawnPrefix = state.prefix.length > 0 ? state.prefix : DEFAULT_PREFIX;
+                    const tmux = await listTmuxSessions(spawnPrefix);
+                    if (tmux.error) {
+                        state.sessionError = tmux.error;
+                        state.enabled = true;
+                        ensurePolling();
+                        renderSubagentsUi(ctx, state);
+                        notify(ctx, `Cannot spawn: ${tmux.error}`, "error");
+                        return;
+                    }
+                    const existingSessions = [...tmux.sessions];
+                    const runId = spawnRunId();
+                    const launched = [];
+                    const skipped = [];
+                    const failed = [];
+                    for (const issue of candidates) {
+                        if (issueHasSession(existingSessions, issue.id)) {
+                            skipped.push(`${issue.id} (session exists)`);
+                            continue;
+                        }
+                        let sessionName = `${spawnPrefix}${runId}-${issue.id}`;
+                        if (existingSessions.includes(sessionName)) {
+                            let suffix = 1;
+                            while (existingSessions.includes(`${sessionName}-${suffix}`)) {
+                                suffix += 1;
+                            }
+                            sessionName = `${sessionName}-${suffix}`;
+                        }
+                        const spawned = await spawnIssueTmuxSession({
+                            cwd: ctx.cwd,
+                            sessionName,
+                            issue,
+                        });
+                        if (spawned.ok) {
+                            existingSessions.push(sessionName);
+                            launched.push(`${issue.id} -> ${sessionName}`);
+                        }
+                        else {
+                            failed.push(`${issue.id} (${spawned.error ?? "unknown error"})`);
+                        }
+                    }
+                    state.enabled = true;
+                    ensurePolling();
+                    await refresh(ctx);
+                    const summary = [
+                        `Spawned ${launched.length}/${candidates.length} ready issue sessions.`,
+                        launched.length > 0 ? `launched: ${launched.join(", ")}` : "launched: (none)",
+                        `skipped: ${skipped.length}`,
+                        `failed: ${failed.length}`,
+                    ];
+                    if (failed.length > 0) {
+                        summary.push(`failures: ${failed.join("; ")}`);
+                    }
+                    ctx.ui.notify(summary.join("\n"), failed.length > 0 ? "warning" : "info");
+                    return;
+                }
+                default:
+                    notify(ctx, `Unknown subagents command: ${tokens[0]}`, "error");
+            }
+        },
+    });
+}
+export default subagentsUiExtension;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.2.85",
+  "version": "26.2.86",
   "description": "Shared agent runtime for mu assistant sessions, orchestration roles, and serve extensions.",
   "keywords": [
     "mu",
@@ -24,7 +24,7 @@
     "themes/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.2.85",
+    "@femtomc/mu-core": "26.2.86",
     "@mariozechner/pi-agent-core": "^0.53.0",
     "@mariozechner/pi-ai": "^0.53.0",
     "@mariozechner/pi-coding-agent": "^0.53.0",

package/prompts/skills/planning/SKILL.md

@@ -38,6 +38,13 @@ mu forum read user:context --limit 50 --pretty
 mu memory search --query "<topic>" --limit 30
 ```
 
+Optional planning HUD (interactive operator session):
+
+```text
+/mu plan on
+/mu plan phase investigating
+```
+
 Also inspect repo files directly (read/bash) for implementation constraints.
 
 ### B) Draft DAG in mu-issue
@@ -71,6 +78,15 @@ mu issues ready --root <root-id> --pretty
 - Re-run `mu issues ready --root <root-id> --pretty`.
 - Present a concise diff of what changed and why.
 
+Optional HUD updates during the loop:
+
+```text
+/mu plan root <root-id>
+/mu plan phase drafting
+/mu plan check 1
+/mu plan phase reviewing
+```
+
 ## Quality bar
 
 - Every issue should be actionable and testable.

package/prompts/skills/subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagents
-description: Break a task into independent parts and dispatch mu subagents in tmux sessions.
+description: Break work into issue-tracked shards and dispatch mu subagents in tmux sessions.
 ---
 
 # Subagents
@@ -15,55 +15,103 @@ Use this skill when work can be split into independent shards and run concurrent
 
 ## Workflow
 
-1. Decompose into 2–4 independent subtasks with explicit deliverables.
-2. Launch one detached tmux session per subtask.
-3. Run a `mu` invocation in each session.
-4. Monitor each pane, then reconcile outputs into one final synthesis.
+1. Create a root issue and decompose into 2–4 actionable child issues in `mu issues`.
+2. Ensure each child has clear acceptance criteria and dependency edges.
+3. Launch one detached tmux session per ready child issue.
+4. Monitor both tmux sessions and issue queue state, then reconcile outputs.
 
 ## Launch pattern
 
+Issue-first decomposition (required before dispatch):
+
+```bash
+# Root issue
+mu issues create "Root: <goal>" --tag node:root --role orchestrator
+
+# Child issues (repeat as needed)
+mu issues create "<child-1 deliverable>" --parent <root-id> --role worker --priority 2
+mu issues create "<child-2 deliverable>" --parent <root-id> --role worker --priority 2
+
+# Optional ordering constraints
+mu issues dep <child-1> blocks <child-2>
+
+# Verify queue before fan-out
+mu issues ready --root <root-id> --tag role:worker --pretty
+```
+
+Dispatch one tmux subagent per ready issue id:
+
 ```bash
 run_id="$(date +%Y%m%d-%H%M%S)"
 
 # Optional: keep one shared server alive for all shards
 mu serve --port 3000
 
-# In another terminal, dispatch shards
-for shard in 1 2 3; do
-  session="mu-sub-${run_id}-${shard}"
+for issue_id in <issue-a> <issue-b> <issue-c>; do
+  session="mu-sub-${run_id}-${issue_id}"
   tmux new-session -d -s "$session" \
-    "cd '$PWD' && mu run 'SUBTASK_PROMPT_${shard}' ; rc=\$?; echo __MU_DONE__:\$rc"
+    "cd '$PWD' && mu exec 'Work issue ${issue_id}. First: mu issues claim ${issue_id}. Keep forum updates on issue:${issue_id}. Close when complete.' ; rc=\$?; echo __MU_DONE__:\$rc"
 done
 ```
 
-If you need non-interactive queueing, use `mu runs start ...` in tmux windows instead of `mu run ...`.
+Use `mu exec` for lightweight one-shot subagent work.
+If you need queued orchestration runs, use `mu runs start ...` / `mu run ...` instead.
 
 ## Monitoring
 
 ```bash
 tmux ls | rg '^mu-sub-'
-tmux capture-pane -pt mu-sub-<run-id>-1 -S -200
-tmux attach -t mu-sub-<run-id>-1
+tmux capture-pane -pt mu-sub-<run-id>-<issue-id> -S -200
+tmux attach -t mu-sub-<run-id>-<issue-id>
+
+# Issue queue visibility (same root used for dispatch)
+mu issues ready --root <root-id> --tag role:worker --pretty
+mu issues list --root <root-id> --status in_progress --tag role:worker --pretty
 ```
 
+Optional live monitor widget (interactive operator session):
+
+```text
+/mu subagents on
+/mu subagents prefix mu-sub-
+/mu subagents root <root-id>
+/mu subagents role role:worker
+/mu subagents refresh
+/mu subagents spawn 3
+```
+
+The widget picks up tracker decomposition by reading `mu issues ready` and
+`mu issues list --status in_progress`.
+Use `spawn` to launch tmux sessions directly from the ready queue for the
+current root/tag filter.
+
 ## Handoffs and follow-up turns
 
-When a subagent session already exists, ask direct follow-ups in that same session:
+With `mu exec`, follow up by issuing another `mu exec` command in the same tmux pane
+(scoped to the same issue id):
+
+```bash
+mu exec "Continue issue <issue-id>. Address feedback: ..."
+```
+
+If you intentionally use long-lived terminal operator sessions (`mu run`/`mu serve`),
+you can hand off with `mu turn`:
 
 ```bash
 mu session list --json --pretty
 mu turn --session-kind operator --session-id <session-id> --body "Follow-up question"
 ```
 
-Use `--session-kind operator` for terminal/tmux subagent sessions.
+Use `--session-kind operator` for terminal/tmux sessions.
 If omitted, `mu turn` defaults to control-plane operator sessions (`cp_operator`).
 
 ## Reconciliation checklist
 
-- Collect outputs from each shard.
-- Identify conflicts or overlaps.
+- Collect outputs from each issue-owned shard.
+- Confirm each claimed issue is closed with an explicit outcome.
+- Identify conflicts or overlaps across child issues.
 - Produce one merged plan/result with explicit decisions.
-- Record any follow-up tasks in `mu issues` / `mu forum`.
+- Record follow-up tasks in `mu issues` / `mu forum`.
 
 ## Safety rules