@femtomc/mu-agent 26.2.87 → 26.2.89

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

@@ -1 +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;AA+fpF,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,QAwWpD;AAED,eAAe,oBAAoB,CAAC"}
+{"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;AA2uBpF,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,QAwmBpD;AAED,eAAe,oBAAoB,CAAC"}

package/dist/extensions/subagents-ui.js

@@ -1,30 +1,62 @@
 import { registerMuSubcommand } from "./mu-command-dispatcher.js";
 const DEFAULT_PREFIX = "mu-sub-";
 const DEFAULT_ROLE_TAG = "role:worker";
+const DEFAULT_SPAWN_MODE = "worker";
 const ISSUE_LIST_LIMIT = 40;
 const MU_CLI_TIMEOUT_MS = 12_000;
+const DEFAULT_REFRESH_INTERVAL_MS = 8_000;
+const MIN_REFRESH_SECONDS = 2;
+const MAX_REFRESH_SECONDS = 120;
+const DEFAULT_STALE_AFTER_MS = 60_000;
+const MIN_STALE_SECONDS = 10;
+const MAX_STALE_SECONDS = 3_600;
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\"'\"'")}'`;
 }
 function spawnRunId(now = new Date()) {
-    return now.toISOString().replaceAll(/[-:TZ.]/g, "").slice(0, 14);
+    return now
+        .toISOString()
+        .replaceAll(/[-:TZ.]/g, "")
+        .slice(0, 14);
+}
+function sessionMatchesIssue(sessionName, issueId) {
+    return (sessionName === issueId ||
+        sessionName.endsWith(`-${issueId}`) ||
+        sessionName.includes(`-${issueId}-`) ||
+        sessionName.includes(`_${issueId}`));
 }
 function issueHasSession(sessions, issueId) {
-    return sessions.some((session) => session === issueId ||
-        session.endsWith(`-${issueId}`) ||
-        session.includes(`-${issueId}-`) ||
-        session.includes(`_${issueId}`));
+    return sessions.some((sessionName) => sessionMatchesIssue(sessionName, 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(" ");
+function buildSubagentPrompt(issue, mode) {
+    switch (mode) {
+        case "worker":
+            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(" ");
+        case "reviewer":
+            return [
+                `Review issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
+                `First run: mu issues claim ${issue.id}.`,
+                "Validate acceptance criteria with concrete checks and evidence.",
+                "Post PASS/FAIL verdict, blockers, and required fixes in topic issue:<id>.",
+                "Close the issue with explicit outcome and review summary.",
+            ].join(" ");
+        case "researcher":
+            return [
+                `Research issue ${issue.id} (${truncateOneLine(issue.title, 80)}).`,
+                `First run: mu issues claim ${issue.id}.`,
+                "Collect concrete evidence and options; call out uncertainty explicitly.",
+                `Keep findings in topic issue:${issue.id}.`,
+                "Close the issue with a concise recommendation and rationale.",
+            ].join(" ");
+    }
 }
 async function spawnIssueTmuxSession(opts) {
-    const shellCommand = `cd ${shellQuote(opts.cwd)} && mu exec ${shellQuote(buildSubagentPrompt(opts.issue))} ; rc=$?; echo __MU_DONE__:$rc`;
+    const shellCommand = `cd ${shellQuote(opts.cwd)} && mu exec ${shellQuote(buildSubagentPrompt(opts.issue, opts.mode))} ; rc=$?; echo __MU_DONE__:$rc`;
     let proc = null;
     try {
         proc = Bun.spawn({
@@ -63,6 +95,10 @@ function createDefaultState() {
         activeIssues: [],
         issueError: null,
         lastUpdatedMs: null,
+        refreshIntervalMs: DEFAULT_REFRESH_INTERVAL_MS,
+        staleAfterMs: DEFAULT_STALE_AFTER_MS,
+        spawnPaused: false,
+        spawnMode: DEFAULT_SPAWN_MODE,
     };
 }
 function truncateOneLine(input, maxLen = 68) {
@@ -164,7 +200,11 @@ async function runMuCli(args) {
         timedOut = true;
         proc?.kill();
     }, MU_CLI_TIMEOUT_MS);
-    const [exitCode, stdout, stderr] = await Promise.all([proc.exited, readableText(proc.stdout), readableText(proc.stderr)]);
+    const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        readableText(proc.stdout),
+        readableText(proc.stderr),
+    ]);
     clearTimeout(timeout);
     return {
         exitCode,
@@ -188,7 +228,11 @@ async function listTmuxSessions(prefix) {
         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 [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();
@@ -283,6 +327,107 @@ function formatRefreshAge(lastUpdatedMs) {
     const hours = Math.floor(mins / 60);
     return `${hours}h ago`;
 }
+function isRefreshStale(lastUpdatedMs, staleAfterMs) {
+    if (lastUpdatedMs == null) {
+        return false;
+    }
+    return Date.now() - lastUpdatedMs > staleAfterMs;
+}
+function computeQueueDrift(sessions, activeIssues) {
+    const activeWithoutSessionIds = activeIssues
+        .filter((issue) => !issueHasSession(sessions, issue.id))
+        .map((issue) => issue.id);
+    const orphanSessions = sessions.filter((sessionName) => !activeIssues.some((issue) => sessionMatchesIssue(sessionName, issue.id)));
+    return {
+        activeWithoutSessionIds,
+        orphanSessions,
+    };
+}
+function normalizeRoleTag(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "clear") {
+        return null;
+    }
+    if (trimmed === "worker" || trimmed === "orchestrator" || trimmed === "reviewer" || trimmed === "researcher") {
+        return `role:${trimmed}`;
+    }
+    return trimmed;
+}
+function parseSpawnMode(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === "worker" || value === "reviewer" || value === "researcher") {
+        return value;
+    }
+    return null;
+}
+function parseOnOff(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (value === "on" || value === "yes" || value === "true" || value === "1") {
+        return true;
+    }
+    if (value === "off" || value === "no" || value === "false" || value === "0") {
+        return false;
+    }
+    return null;
+}
+function parseSnapshotFormat(raw) {
+    const value = (raw ?? "compact").trim().toLowerCase();
+    return value === "multiline" ? "multiline" : "compact";
+}
+function parseSecondsBounded(secondsRaw, minSeconds, maxSeconds, field) {
+    if (typeof secondsRaw !== "number" || !Number.isFinite(secondsRaw)) {
+        return { ok: false, error: `${field} must be a number.` };
+    }
+    const rounded = Math.round(secondsRaw);
+    if (rounded < minSeconds || rounded > maxSeconds) {
+        return { ok: false, error: `${field} must be ${minSeconds}-${maxSeconds} seconds.` };
+    }
+    return { ok: true, ms: rounded * 1_000 };
+}
+function subagentsSnapshot(state, format) {
+    const issueScope = state.issueRootId ?? "(all roots)";
+    const roleScope = state.issueRoleTag ?? "(all roles)";
+    const drift = computeQueueDrift(state.sessions, state.activeIssues);
+    const refreshStale = isRefreshStale(state.lastUpdatedMs, state.staleAfterMs);
+    const staleCount = drift.activeWithoutSessionIds.length + drift.orphanSessions.length;
+    const health = state.issueError || state.sessionError || refreshStale || staleCount > 0 ? "degraded" : "healthy";
+    const refreshAge = formatRefreshAge(state.lastUpdatedMs);
+    const paused = state.spawnPaused ? "yes" : "no";
+    const refreshSeconds = Math.round(state.refreshIntervalMs / 1_000);
+    const staleAfterSeconds = Math.round(state.staleAfterMs / 1_000);
+    if (format === "multiline") {
+        return [
+            "Subagents HUD snapshot",
+            `health: ${health}`,
+            `prefix: ${state.prefix || "(all sessions)"}`,
+            `issue_root: ${issueScope}`,
+            `issue_role: ${roleScope}`,
+            `spawn_mode: ${state.spawnMode}`,
+            `spawn_paused: ${paused}`,
+            `queues: ${state.readyIssues.length} ready / ${state.activeIssues.length} active`,
+            `sessions: ${state.sessions.length}`,
+            `drift_active_without_session: ${drift.activeWithoutSessionIds.length}`,
+            `drift_orphan_sessions: ${drift.orphanSessions.length}`,
+            `refresh_age: ${refreshAge}`,
+            `refresh_stale: ${refreshStale ? "yes" : "no"}`,
+            `refresh_seconds: ${refreshSeconds}`,
+            `stale_after_seconds: ${staleAfterSeconds}`,
+        ].join("\n");
+    }
+    return [
+        "HUD(subagents)",
+        `health=${health}`,
+        `root=${issueScope}`,
+        `role=${roleScope}`,
+        `mode=${state.spawnMode}`,
+        `paused=${paused}`,
+        `ready=${state.readyIssues.length}`,
+        `active=${state.activeIssues.length}`,
+        `sessions=${state.sessions.length}`,
+        `drift=${staleCount}`,
+        `refresh=${refreshAge}`,
+    ].join(" · ");
+}
 function renderSubagentsUi(ctx, state) {
     if (!ctx.hasUI) {
         return;
@@ -294,15 +439,24 @@ function renderSubagentsUi(ctx, state) {
     }
     const issueScope = state.issueRootId ? `root:${state.issueRootId}` : "all-roots";
     const roleScope = state.issueRoleTag ? state.issueRoleTag : "(all roles)";
-    const hasError = Boolean(state.sessionError || state.issueError);
+    const refreshStale = isRefreshStale(state.lastUpdatedMs, state.staleAfterMs);
+    const drift = computeQueueDrift(state.sessions, state.activeIssues);
+    const staleCount = drift.activeWithoutSessionIds.length + drift.orphanSessions.length;
+    const hasError = Boolean(state.sessionError || state.issueError || refreshStale || staleCount > 0);
     const healthColor = hasError ? "warning" : "success";
     const healthLabel = hasError ? "degraded" : "healthy";
     const queueTotal = state.readyIssues.length + state.activeIssues.length;
     const queueBar = queueMeter(state.activeIssues.length, Math.max(1, queueTotal), 10);
     const refreshAge = formatRefreshAge(state.lastUpdatedMs);
+    const pausedLabel = state.spawnPaused ? "yes" : "no";
+    const pausedColor = state.spawnPaused ? "warning" : "dim";
+    const refreshSeconds = Math.round(state.refreshIntervalMs / 1_000);
+    const staleAfterSeconds = Math.round(state.staleAfterMs / 1_000);
     ctx.ui.setStatus("mu-subagents", [
         ctx.ui.theme.fg("dim", "subagents"),
         ctx.ui.theme.fg(healthColor, healthLabel),
+        ctx.ui.theme.fg("dim", `${state.spawnMode}`),
+        ctx.ui.theme.fg(pausedColor, `paused:${pausedLabel}`),
         ctx.ui.theme.fg("dim", `${state.sessions.length} tmux`),
         ctx.ui.theme.fg("dim", `${state.readyIssues.length} ready/${state.activeIssues.length} active`),
         ctx.ui.theme.fg("muted", issueScope),
@@ -312,8 +466,11 @@ function renderSubagentsUi(ctx, state) {
         `  ${ctx.ui.theme.fg("muted", "health:")} ${ctx.ui.theme.fg(healthColor, healthLabel)}`,
         `  ${ctx.ui.theme.fg("muted", "scope:")} ${ctx.ui.theme.fg("dim", `${issueScope} · ${roleScope}`)}`,
         `  ${ctx.ui.theme.fg("muted", "tmux prefix:")} ${ctx.ui.theme.fg("dim", state.prefix || "(all sessions)")}`,
+        `  ${ctx.ui.theme.fg("muted", "spawn mode:")} ${ctx.ui.theme.fg("accent", state.spawnMode)}`,
+        `  ${ctx.ui.theme.fg("muted", "spawn paused:")} ${ctx.ui.theme.fg(pausedColor, pausedLabel)}`,
+        `  ${ctx.ui.theme.fg("muted", "refresh:")} ${ctx.ui.theme.fg("dim", `${refreshSeconds}s`)} ${ctx.ui.theme.fg("muted", "| stale after:")} ${ctx.ui.theme.fg("dim", `${staleAfterSeconds}s`)}`,
         `  ${ctx.ui.theme.fg("muted", "queues:")} ${ctx.ui.theme.fg("accent", `${state.readyIssues.length} ready`)} ${ctx.ui.theme.fg("muted", "| ")} ${ctx.ui.theme.fg("warning", `${state.activeIssues.length} active`)} ${ctx.ui.theme.fg("dim", queueBar)}`,
-        `  ${ctx.ui.theme.fg("muted", "last refresh:")} ${ctx.ui.theme.fg("dim", refreshAge)}`,
+        `  ${ctx.ui.theme.fg("muted", "last refresh:")} ${ctx.ui.theme.fg(refreshStale ? "warning" : "dim", refreshAge)}`,
         `  ${ctx.ui.theme.fg("dim", "────────────────────────────")}`,
         ctx.ui.theme.fg("accent", `tmux sessions (${state.sessions.length})`),
     ];
@@ -361,40 +518,55 @@ function renderSubagentsUi(ctx, state) {
             }
         }
     }
+    if (refreshStale) {
+        lines.push(ctx.ui.theme.fg("warning", `refresh warning: last successful refresh is stale (>${staleAfterSeconds}s)`));
+    }
+    if (drift.activeWithoutSessionIds.length > 0) {
+        lines.push(ctx.ui.theme.fg("warning", `drift warning: active issues without tmux sessions (${drift.activeWithoutSessionIds.length})`));
+        lines.push(ctx.ui.theme.fg("warning", `  missing sessions for: ${drift.activeWithoutSessionIds.slice(0, 8).join(", ")}${drift.activeWithoutSessionIds.length > 8 ? " ..." : ""}`));
+    }
+    if (drift.orphanSessions.length > 0) {
+        lines.push(ctx.ui.theme.fg("warning", `drift warning: tmux sessions without active issues (${drift.orphanSessions.length})`));
+        lines.push(ctx.ui.theme.fg("warning", `  orphan sessions: ${drift.orphanSessions.slice(0, 8).join(", ")}${drift.orphanSessions.length > 8 ? " ..." : ""}`));
+    }
     ctx.ui.setWidget("mu-subagents", lines, { placement: "belowEditor" });
 }
 function subagentsUsageText() {
     return [
         "Usage:",
-        "  /mu subagents on|off|toggle|status|refresh",
+        "  /mu subagents on|off|toggle|status|refresh|snapshot",
         "  /mu subagents prefix <text|clear>",
         "  /mu subagents root <issue-id|clear>",
         "  /mu subagents role <tag|clear>",
+        "  /mu subagents mode <worker|reviewer|researcher>",
+        "  /mu subagents refresh-interval <seconds>",
+        "  /mu subagents stale-after <seconds>",
+        "  /mu subagents pause <on|off>",
         "  /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;
-}
 function subagentsDetails(state) {
+    const drift = computeQueueDrift(state.sessions, state.activeIssues);
     return {
         enabled: state.enabled,
         prefix: state.prefix,
         issue_root_id: state.issueRootId,
         issue_role_tag: state.issueRoleTag,
+        spawn_mode: state.spawnMode,
+        spawn_paused: state.spawnPaused,
+        refresh_seconds: Math.round(state.refreshIntervalMs / 1_000),
+        stale_after_seconds: Math.round(state.staleAfterMs / 1_000),
         sessions: [...state.sessions],
         ready_issue_ids: state.readyIssues.map((issue) => issue.id),
         active_issue_ids: state.activeIssues.map((issue) => issue.id),
+        active_without_session_ids: drift.activeWithoutSessionIds,
+        orphan_sessions: drift.orphanSessions,
+        refresh_stale: isRefreshStale(state.lastUpdatedMs, state.staleAfterMs),
         issue_error: state.issueError,
         session_error: state.sessionError,
         last_updated_ms: state.lastUpdatedMs,
+        snapshot_compact: subagentsSnapshot(state, "compact"),
+        snapshot_multiline: subagentsSnapshot(state, "multiline"),
     };
 }
 function subagentsToolError(message, state) {
@@ -410,7 +582,7 @@ function subagentsToolError(message, state) {
 export function subagentsUiExtension(pi) {
     let activeCtx = null;
     let pollTimer = null;
-    let state = createDefaultState();
+    const state = createDefaultState();
     const refresh = async (ctx) => {
         if (!state.enabled) {
             renderSubagentsUi(ctx, state);
@@ -444,7 +616,14 @@ export function subagentsUiExtension(pi) {
                 return;
             }
             void refresh(activeCtx);
-        }, 8_000);
+        }, state.refreshIntervalMs);
+    };
+    const restartPolling = () => {
+        if (!state.enabled) {
+            return;
+        }
+        stopPolling();
+        ensurePolling();
     };
     const notify = (ctx, message, level = "info") => {
         ctx.ui.notify(`${message}\n\n${subagentsUsageText()}`, level);
@@ -454,20 +633,40 @@ export function subagentsUiExtension(pi) {
         const status = state.enabled ? "enabled" : "disabled";
         const issueScope = state.issueRootId ?? "(all roots)";
         const issueRole = state.issueRoleTag ?? "(all roles)";
+        const drift = computeQueueDrift(state.sessions, state.activeIssues);
+        const refreshStale = isRefreshStale(state.lastUpdatedMs, state.staleAfterMs);
         const issueError = state.issueError ? `\nissue_error: ${state.issueError}` : "";
         const tmuxError = state.sessionError ? `\ntmux_error: ${state.sessionError}` : "";
+        const driftInfo = drift.activeWithoutSessionIds.length > 0 || drift.orphanSessions.length > 0
+            ? `\ndrift_active_without_session: ${drift.activeWithoutSessionIds.length}\ndrift_orphan_sessions: ${drift.orphanSessions.length}`
+            : "";
+        const staleInfo = refreshStale ? "\nrefresh_stale: yes" : "\nrefresh_stale: no";
         return {
-            level: state.issueError || state.sessionError ? "warning" : "info",
+            level: state.issueError ||
+                state.sessionError ||
+                refreshStale ||
+                drift.activeWithoutSessionIds.length > 0 ||
+                drift.orphanSessions.length > 0
+                ? "warning"
+                : "info",
             text: [
                 `Subagents monitor ${status}`,
                 `prefix: ${state.prefix || "(all sessions)"}`,
                 `issue_root: ${issueScope}`,
                 `issue_role: ${issueRole}`,
+                `spawn_mode: ${state.spawnMode}`,
+                `spawn_paused: ${state.spawnPaused ? "yes" : "no"}`,
+                `refresh_seconds: ${Math.round(state.refreshIntervalMs / 1_000)}`,
+                `stale_after_seconds: ${Math.round(state.staleAfterMs / 1_000)}`,
                 `sessions: ${state.sessions.length}`,
                 `ready_issues: ${state.readyIssues.length}`,
                 `active_issues: ${state.activeIssues.length}`,
                 `last refresh: ${when}`,
-            ].join("\n") + issueError + tmuxError,
+            ].join("\n") +
+                issueError +
+                tmuxError +
+                driftInfo +
+                staleInfo,
         };
     };
     const applySubagentsAction = async (params, ctx) => {
@@ -476,6 +675,10 @@ export function subagentsUiExtension(pi) {
                 const summary = statusSummary();
                 return { ok: true, message: summary.text, level: summary.level };
             }
+            case "snapshot": {
+                const format = parseSnapshotFormat(params.snapshot_format);
+                return { ok: true, message: subagentsSnapshot(state, format), level: "info" };
+            }
             case "on":
                 state.enabled = true;
                 ensurePolling();
@@ -531,9 +734,160 @@ export function subagentsUiExtension(pi) {
                 state.enabled = true;
                 ensurePolling();
                 await refresh(ctx);
-                return { ok: true, message: `Subagents issue tag filter set to ${state.issueRoleTag ?? "(all roles)"}.`, level: "info" };
+                return {
+                    ok: true,
+                    message: `Subagents issue tag filter set to ${state.issueRoleTag ?? "(all roles)"}.`,
+                    level: "info",
+                };
+            }
+            case "set_mode": {
+                const modeRaw = params.spawn_mode?.trim() ?? "";
+                const mode = parseSpawnMode(modeRaw);
+                if (!mode) {
+                    return { ok: false, message: "Invalid spawn mode.", level: "error" };
+                }
+                state.spawnMode = mode;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return { ok: true, message: `Subagents spawn mode set to ${mode}.`, level: "info" };
+            }
+            case "set_refresh_interval": {
+                const parsed = parseSecondsBounded(params.refresh_seconds, MIN_REFRESH_SECONDS, MAX_REFRESH_SECONDS, "refresh_seconds");
+                if (!parsed.ok) {
+                    return { ok: false, message: parsed.error, level: "error" };
+                }
+                state.refreshIntervalMs = parsed.ms;
+                state.enabled = true;
+                restartPolling();
+                await refresh(ctx);
+                return {
+                    ok: true,
+                    message: `Subagents refresh interval set to ${Math.round(state.refreshIntervalMs / 1_000)}s.`,
+                    level: "info",
+                };
+            }
+            case "set_stale_after": {
+                const parsed = parseSecondsBounded(params.stale_after_seconds, MIN_STALE_SECONDS, MAX_STALE_SECONDS, "stale_after_seconds");
+                if (!parsed.ok) {
+                    return { ok: false, message: parsed.error, level: "error" };
+                }
+                state.staleAfterMs = parsed.ms;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return {
+                    ok: true,
+                    message: `Subagents stale threshold set to ${Math.round(state.staleAfterMs / 1_000)}s.`,
+                    level: "info",
+                };
+            }
+            case "set_spawn_paused": {
+                if (typeof params.spawn_paused !== "boolean") {
+                    return { ok: false, message: "spawn_paused must be a boolean.", level: "error" };
+                }
+                state.spawnPaused = params.spawn_paused;
+                state.enabled = true;
+                ensurePolling();
+                await refresh(ctx);
+                return {
+                    ok: true,
+                    message: `Subagents spawn pause set to ${state.spawnPaused ? "on" : "off"}.`,
+                    level: "info",
+                };
+            }
+            case "update": {
+                const changed = [];
+                let refreshIntervalChanged = false;
+                if (params.prefix !== undefined) {
+                    if (typeof params.prefix !== "string") {
+                        return { ok: false, message: "prefix must be a string.", level: "error" };
+                    }
+                    const trimmed = params.prefix.trim();
+                    if (trimmed.length === 0) {
+                        return { ok: false, message: "prefix must not be empty.", level: "error" };
+                    }
+                    state.prefix = trimmed.toLowerCase() === "clear" ? "" : trimmed;
+                    changed.push("prefix");
+                }
+                if (params.root_issue_id !== undefined) {
+                    if (typeof params.root_issue_id !== "string") {
+                        return { ok: false, message: "root_issue_id must be a string.", level: "error" };
+                    }
+                    const trimmed = params.root_issue_id.trim();
+                    if (trimmed.length === 0) {
+                        return { ok: false, message: "root_issue_id must not be empty.", level: "error" };
+                    }
+                    state.issueRootId = trimmed.toLowerCase() === "clear" ? null : trimmed;
+                    changed.push("root_issue_id");
+                }
+                if (params.role_tag !== undefined) {
+                    if (typeof params.role_tag !== "string") {
+                        return { ok: false, message: "role_tag must be a string.", level: "error" };
+                    }
+                    const trimmed = params.role_tag.trim();
+                    if (trimmed.length === 0) {
+                        return { ok: false, message: "role_tag must not be empty.", level: "error" };
+                    }
+                    state.issueRoleTag = normalizeRoleTag(trimmed);
+                    changed.push("role_tag");
+                }
+                if (params.spawn_mode !== undefined) {
+                    if (typeof params.spawn_mode !== "string") {
+                        return { ok: false, message: "spawn_mode must be a string.", level: "error" };
+                    }
+                    const mode = parseSpawnMode(params.spawn_mode);
+                    if (!mode) {
+                        return { ok: false, message: "Invalid spawn mode.", level: "error" };
+                    }
+                    state.spawnMode = mode;
+                    changed.push("spawn_mode");
+                }
+                if (params.refresh_seconds !== undefined) {
+                    const parsed = parseSecondsBounded(params.refresh_seconds, MIN_REFRESH_SECONDS, MAX_REFRESH_SECONDS, "refresh_seconds");
+                    if (!parsed.ok) {
+                        return { ok: false, message: parsed.error, level: "error" };
+                    }
+                    state.refreshIntervalMs = parsed.ms;
+                    refreshIntervalChanged = true;
+                    changed.push("refresh_seconds");
+                }
+                if (params.stale_after_seconds !== undefined) {
+                    const parsed = parseSecondsBounded(params.stale_after_seconds, MIN_STALE_SECONDS, MAX_STALE_SECONDS, "stale_after_seconds");
+                    if (!parsed.ok) {
+                        return { ok: false, message: parsed.error, level: "error" };
+                    }
+                    state.staleAfterMs = parsed.ms;
+                    changed.push("stale_after_seconds");
+                }
+                if (params.spawn_paused !== undefined) {
+                    if (typeof params.spawn_paused !== "boolean") {
+                        return { ok: false, message: "spawn_paused must be a boolean.", level: "error" };
+                    }
+                    state.spawnPaused = params.spawn_paused;
+                    changed.push("spawn_paused");
+                }
+                if (changed.length === 0) {
+                    return { ok: false, message: "No update fields provided.", level: "error" };
+                }
+                state.enabled = true;
+                if (refreshIntervalChanged) {
+                    restartPolling();
+                }
+                else {
+                    ensurePolling();
+                }
+                await refresh(ctx);
+                return { ok: true, message: `Subagents monitor updated (${changed.join(", ")}).`, level: "info" };
             }
             case "spawn": {
+                if (state.spawnPaused) {
+                    return {
+                        ok: false,
+                        message: "Spawn is paused. Use set_spawn_paused=false before spawning.",
+                        level: "error",
+                    };
+                }
                 if (!state.issueRootId) {
                     return {
                         ok: false,
@@ -598,6 +952,7 @@ export function subagentsUiExtension(pi) {
                         cwd: ctx.cwd,
                         sessionName,
                         issue,
+                        mode: state.spawnMode,
                     });
                     if (spawned.ok) {
                         existingSessions.push(sessionName);
@@ -611,7 +966,7 @@ export function subagentsUiExtension(pi) {
                 ensurePolling();
                 await refresh(ctx);
                 const summary = [
-                    `Spawned ${launched.length}/${candidates.length} ready issue sessions.`,
+                    `Spawned ${launched.length}/${candidates.length} ready issue sessions (mode=${state.spawnMode}).`,
                     launched.length > 0 ? `launched: ${launched.join(", ")}` : "launched: (none)",
                     `skipped: ${skipped.length}`,
                     `failed: ${failed.length}`,
@@ -644,7 +999,7 @@ export function subagentsUiExtension(pi) {
     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",
+        usage: "/mu subagents on|off|toggle|status|refresh|snapshot|prefix|root|role|mode|refresh-interval|stale-after|pause|spawn",
         handler: async (args, ctx) => {
             activeCtx = ctx;
             const tokens = args
@@ -657,6 +1012,9 @@ export function subagentsUiExtension(pi) {
                 case "status":
                     params = { action: "status" };
                     break;
+                case "snapshot":
+                    params = { action: "snapshot", snapshot_format: tokens[1] };
+                    break;
                 case "on":
                     params = { action: "on" };
                     break;
@@ -678,6 +1036,20 @@ export function subagentsUiExtension(pi) {
                 case "role":
                     params = { action: "set_role", role_tag: tokens.slice(1).join(" ") };
                     break;
+                case "mode":
+                    params = { action: "set_mode", spawn_mode: tokens[1] };
+                    break;
+                case "refresh-interval":
+                    params = { action: "set_refresh_interval", refresh_seconds: Number.parseFloat(tokens[1] ?? "") };
+                    break;
+                case "stale-after":
+                    params = { action: "set_stale_after", stale_after_seconds: Number.parseFloat(tokens[1] ?? "") };
+                    break;
+                case "pause": {
+                    const parsed = parseOnOff(tokens[1]);
+                    params = { action: "set_spawn_paused", spawn_paused: parsed ?? undefined };
+                    break;
+                }
                 case "spawn":
                     params = {
                         action: "spawn",
@@ -706,19 +1078,43 @@ export function subagentsUiExtension(pi) {
     pi.registerTool({
         name: "mu_subagents_hud",
         label: "mu subagents HUD",
-        description: "Control or inspect subagents HUD state, including tmux scope, issue queue filters, and ready-queue spawning.",
+        description: "Control or inspect subagents HUD state, including tmux scope, queue filters, spawn profile, and health policies.",
         parameters: {
             type: "object",
             properties: {
                 action: {
                     type: "string",
-                    enum: ["status", "on", "off", "toggle", "refresh", "set_prefix", "set_root", "set_role", "spawn"],
+                    enum: [
+                        "status",
+                        "snapshot",
+                        "on",
+                        "off",
+                        "toggle",
+                        "refresh",
+                        "set_prefix",
+                        "set_root",
+                        "set_role",
+                        "set_mode",
+                        "set_refresh_interval",
+                        "set_stale_after",
+                        "set_spawn_paused",
+                        "update",
+                        "spawn",
+                    ],
                 },
                 prefix: { type: "string" },
                 root_issue_id: { type: "string" },
                 role_tag: { type: "string" },
+                spawn_mode: { type: "string", enum: ["worker", "reviewer", "researcher"] },
+                refresh_seconds: { type: "number", minimum: MIN_REFRESH_SECONDS, maximum: MAX_REFRESH_SECONDS },
+                stale_after_seconds: { type: "number", minimum: MIN_STALE_SECONDS, maximum: MAX_STALE_SECONDS },
+                spawn_paused: { type: "boolean" },
+                snapshot_format: { type: "string", enum: ["compact", "multiline"] },
                 count: {
-                    anyOf: [{ type: "integer", minimum: 1, maximum: ISSUE_LIST_LIMIT }, { type: "string", enum: ["all"] }],
+                    anyOf: [
+                        { type: "integer", minimum: 1, maximum: ISSUE_LIST_LIMIT },
+                        { type: "string", enum: ["all"] },
+                    ],
                 },
             },
             required: ["action"],