gsd-pi 2.36.0-dev.f887f4e → 2.37.0

package/src/resources/extensions/gsd/auto-loop.ts

@@ -25,6 +25,7 @@ import type {
 import type { DispatchAction } from "./auto-dispatch.js";
 import type { WorktreeResolver } from "./worktree-resolver.js";
 import { debugLog } from "./debug-logger.js";
+import type { CmuxLogLevel } from "../cmux/index.js";
 
 /**
  * Maximum total loop iterations before forced stop. Prevents runaway loops
@@ -276,6 +277,12 @@ export interface LoopDeps {
     unitId: string,
     state: GSDState,
   ) => void;
+  syncCmuxSidebar: (preferences: GSDPreferences | undefined, state: GSDState) => void;
+  logCmuxEvent: (
+    preferences: GSDPreferences | undefined,
+    message: string,
+    level?: CmuxLogLevel,
+  ) => void;
 
   // State and cache functions
   invalidateAllCaches: () => void;
@@ -609,6 +616,7 @@ export async function autoLoop(
 
       // Derive state
       let state = await deps.deriveState(s.basePath);
+      deps.syncCmuxSidebar(deps.loadEffectiveGSDPreferences()?.preferences, state);
       let mid = state.activeMilestone?.id;
       let midTitle = state.activeMilestone?.title;
       debugLog("autoLoop", {
@@ -630,6 +638,11 @@ export async function autoLoop(
           "success",
           "milestone",
         );
+        deps.logCmuxEvent(
+          deps.loadEffectiveGSDPreferences()?.preferences,
+          `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}.`,
+          "success",
+        );
 
         const vizPrefs = deps.loadEffectiveGSDPreferences()?.preferences;
         if (vizPrefs?.auto_visualize) {
@@ -767,12 +780,18 @@ export async function autoLoop(
             "success",
             "milestone",
           );
+          deps.logCmuxEvent(
+            deps.loadEffectiveGSDPreferences()?.preferences,
+            "All milestones complete.",
+            "success",
+          );
           await deps.stopAuto(ctx, pi, "All milestones complete");
         } else if (state.phase === "blocked") {
           const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
           await deps.stopAuto(ctx, pi, blockerMsg);
           ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
           deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+          deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, blockerMsg, "error");
         } else {
           const ids = incomplete.map((m: { id: string }) => m.id).join(", ");
           const diag = `basePath=${s.basePath}, milestones=[${state.registry.map((m: { id: string; status: string }) => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
@@ -850,6 +869,11 @@ export async function autoLoop(
           "success",
           "milestone",
         );
+        deps.logCmuxEvent(
+          deps.loadEffectiveGSDPreferences()?.preferences,
+          `Milestone ${mid} complete.`,
+          "success",
+        );
         await deps.stopAuto(ctx, pi, `Milestone ${mid} complete`);
         debugLog("autoLoop", { phase: "exit", reason: "milestone-complete" });
         break;
@@ -871,6 +895,7 @@ export async function autoLoop(
         await deps.stopAuto(ctx, pi, blockerMsg);
         ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
         deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+        deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, blockerMsg, "error");
         debugLog("autoLoop", { phase: "exit", reason: "blocked" });
         break;
       }
@@ -914,12 +939,14 @@ export async function autoLoop(
               "warning",
             );
             deps.sendDesktopNotification("GSD", msg, "warning", "budget");
+            deps.logCmuxEvent(prefs, msg, "warning");
             await deps.pauseAuto(ctx, pi);
             debugLog("autoLoop", { phase: "exit", reason: "budget-pause" });
             break;
           }
           ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
           deps.sendDesktopNotification("GSD", msg, "warning", "budget");
+          deps.logCmuxEvent(prefs, msg, "warning");
         } else if (newBudgetAlertLevel === 90) {
           s.lastBudgetAlertLevel =
             newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
@@ -933,6 +960,11 @@ export async function autoLoop(
             "warning",
             "budget",
           );
+          deps.logCmuxEvent(
+            prefs,
+            `Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`,
+            "warning",
+          );
         } else if (newBudgetAlertLevel === 80) {
           s.lastBudgetAlertLevel =
             newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
@@ -946,6 +978,11 @@ export async function autoLoop(
             "warning",
             "budget",
           );
+          deps.logCmuxEvent(
+            prefs,
+            `Budget 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`,
+            "warning",
+          );
         } else if (newBudgetAlertLevel === 75) {
           s.lastBudgetAlertLevel =
             newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
@@ -959,6 +996,11 @@ export async function autoLoop(
             "info",
             "budget",
           );
+          deps.logCmuxEvent(
+            prefs,
+            `Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`,
+            "progress",
+          );
         } else if (budgetAlertLevel === 0) {
           s.lastBudgetAlertLevel = 0;
         }

package/src/resources/extensions/gsd/auto.ts

@@ -184,6 +184,7 @@ import {
 } from "./auto-supervisor.js";
 import { isDbAvailable } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
+import { clearCmuxSidebar, logCmuxEvent, syncCmuxSidebar } from "../cmux/index.js";
 
 // ── Extracted modules ──────────────────────────────────────────────────────
 import { startUnitSupervision } from "./auto-timers.js";
@@ -466,6 +467,7 @@ function handleLostSessionLock(ctx?: ExtensionContext): void {
   s.paused = false;
   clearUnitTimeout();
   deregisterSigtermHandler();
+  clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
   ctx?.ui.notify(
     "Session lock lost — another GSD process appears to have taken over. Stopping gracefully.",
     "error",
@@ -481,6 +483,7 @@ export async function stopAuto(
   reason?: string,
 ): Promise<void> {
   if (!s.active && !s.paused) return;
+  const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
   const reasonSuffix = reason ? ` — ${reason}` : "";
   clearUnitTimeout();
   if (lockBase()) clearLock(lockBase());
@@ -543,6 +546,13 @@ export async function stopAuto(
     }
   }
 
+  clearCmuxSidebar(loadedPreferences);
+  logCmuxEvent(
+    loadedPreferences,
+    `Auto-mode stopped${reasonSuffix || ""}.`,
+    reason?.startsWith("Blocked:") ? "warning" : "info",
+  );
+
   if (isDebugEnabled()) {
     const logPath = writeDebugSummary();
     if (logPath) {
@@ -708,6 +718,8 @@ function buildLoopDeps(): LoopDeps {
     pauseAuto,
     clearUnitTimeout,
     updateProgressWidget,
+    syncCmuxSidebar,
+    logCmuxEvent,
 
     // State and cache
     invalidateAllCaches,
@@ -890,6 +902,7 @@ export async function startAuto(
     restoreHookState(s.basePath);
     try {
       await rebuildState(s.basePath);
+      syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
     } catch (e) {
       debugLog("resume-rebuild-state-failed", {
         error: e instanceof Error ? e.message : String(e),
@@ -941,6 +954,7 @@ export async function startAuto(
       s.currentMilestoneId ?? "unknown",
       s.completedUnits.length,
     );
+    logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
 
     await autoLoop(ctx, pi, s, buildLoopDeps());
     return;
@@ -965,6 +979,13 @@ export async function startAuto(
   );
   if (!ready) return;
 
+  try {
+    syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
+  } catch {
+    // Best-effort only — sidebar sync must never block auto-mode startup
+  }
+  logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
+
   // Dispatch the first unit
   await autoLoop(ctx, pi, s, buildLoopDeps());
 }

package/src/resources/extensions/gsd/commands-cmux.ts

@@ -0,0 +1,143 @@
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { clearCmuxSidebar, CmuxClient, detectCmuxEnvironment, resolveCmuxConfig } from "../cmux/index.js";
+import { saveFile } from "./files.js";
+import {
+  getProjectGSDPreferencesPath,
+  loadEffectiveGSDPreferences,
+  loadProjectGSDPreferences,
+} from "./preferences.js";
+import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+
+function extractBodyAfterFrontmatter(content: string): string | null {
+  const start = content.startsWith("---\n") ? 4 : content.startsWith("---\r\n") ? 5 : -1;
+  if (start === -1) return null;
+  const closingIdx = content.indexOf("\n---", start);
+  if (closingIdx === -1) return null;
+  const after = content.slice(closingIdx + 4);
+  return after.trim() ? after : null;
+}
+
+async function writeProjectCmuxPreferences(
+  ctx: ExtensionCommandContext,
+  updater: (prefs: Record<string, unknown>) => void,
+): Promise<void> {
+  const path = getProjectGSDPreferencesPath();
+  await ensurePreferencesFile(path, ctx, "project");
+
+  const existing = loadProjectGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : { version: 1 };
+  updater(prefs);
+  prefs.version = prefs.version || 1;
+
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  if (existsSync(path)) {
+    const preserved = extractBodyAfterFrontmatter(readFileSync(path, "utf-8"));
+    if (preserved) body = preserved;
+  }
+
+  await saveFile(path, `---\n${frontmatter}---${body}`);
+  await ctx.waitForIdle();
+  await ctx.reload();
+}
+
+function formatCmuxStatus(): string {
+  const loaded = loadEffectiveGSDPreferences();
+  const detected = detectCmuxEnvironment();
+  const resolved = resolveCmuxConfig(loaded?.preferences);
+  const capabilities = new CmuxClient(resolved).getCapabilities() as Record<string, unknown> | null;
+  const accessMode = typeof capabilities?.mode === "string"
+    ? capabilities.mode
+    : typeof capabilities?.access_mode === "string"
+      ? capabilities.access_mode
+      : "unknown";
+  const methods = Array.isArray(capabilities?.methods) ? capabilities.methods.length : 0;
+
+  return [
+    "cmux status",
+    "",
+    `Detected: ${detected.available ? "yes" : "no"}`,
+    `Enabled: ${resolved.enabled ? "yes" : "no"}`,
+    `CLI available: ${detected.cliAvailable ? "yes" : "no"}`,
+    `Socket: ${detected.socketPath}`,
+    `Workspace: ${detected.workspaceId ?? "(none)"}`,
+    `Surface: ${detected.surfaceId ?? "(none)"}`,
+    `Features: notifications=${resolved.notifications ? "on" : "off"}, sidebar=${resolved.sidebar ? "on" : "off"}, splits=${resolved.splits ? "on" : "off"}, browser=${resolved.browser ? "on" : "off"}`,
+    `Capabilities: access=${accessMode}, methods=${methods}`,
+  ].join("\n");
+}
+
+function ensureCmuxAvailableForEnable(ctx: ExtensionCommandContext): boolean {
+  const detected = detectCmuxEnvironment();
+  if (detected.available) return true;
+  ctx.ui.notify(
+    "cmux not detected. Install it from https://cmux.com and run gsd inside a cmux terminal.",
+    "warning",
+  );
+  return false;
+}
+
+export async function handleCmux(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const trimmed = args.trim();
+  if (!trimmed || trimmed === "status") {
+    ctx.ui.notify(formatCmuxStatus(), "info");
+    return;
+  }
+
+  if (trimmed === "on") {
+    if (!ensureCmuxAvailableForEnable(ctx)) return;
+    await writeProjectCmuxPreferences(ctx, (prefs) => {
+      prefs.cmux = {
+        enabled: true,
+        notifications: true,
+        sidebar: true,
+        splits: false,
+        browser: false,
+        ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}),
+      };
+      (prefs.cmux as Record<string, unknown>).enabled = true;
+    });
+    ctx.ui.notify("cmux integration enabled in project preferences.", "info");
+    return;
+  }
+
+  if (trimmed === "off") {
+    const effective = loadEffectiveGSDPreferences()?.preferences;
+    await writeProjectCmuxPreferences(ctx, (prefs) => {
+      prefs.cmux = { ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}), enabled: false };
+    });
+    clearCmuxSidebar(effective);
+    ctx.ui.notify("cmux integration disabled in project preferences.", "info");
+    return;
+  }
+
+  const parts = trimmed.split(/\s+/);
+  if (parts.length === 2 && ["notifications", "sidebar", "splits", "browser"].includes(parts[0]) && ["on", "off"].includes(parts[1])) {
+    const feature = parts[0] as "notifications" | "sidebar" | "splits" | "browser";
+    const enabled = parts[1] === "on";
+    if (enabled && !ensureCmuxAvailableForEnable(ctx)) return;
+
+    await writeProjectCmuxPreferences(ctx, (prefs) => {
+      const next = { ...((prefs.cmux as Record<string, unknown> | undefined) ?? {}) };
+      next[feature] = enabled;
+      if (enabled) next.enabled = true;
+      prefs.cmux = next;
+    });
+
+    if (!enabled && feature === "sidebar") {
+      clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
+    }
+
+    const note = feature === "browser" && enabled
+      ? " Browser surfaces are still a follow-up path."
+      : "";
+    ctx.ui.notify(`cmux ${feature} ${enabled ? "enabled" : "disabled"}.${note}`, "info");
+    return;
+  }
+
+  ctx.ui.notify(
+    "Usage: /gsd cmux <status|on|off|notifications on|notifications off|sidebar on|sidebar off|splits on|splits off|browser on|browser off>",
+    "info",
+  );
+}

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -740,7 +740,7 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "skill_rules", "custom_instructions", "models", "skill_discovery",
     "skill_staleness_days", "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
-    "notifications", "remote_questions", "git",
+    "notifications", "cmux", "remote_questions", "git",
     "post_unit_hooks", "pre_dispatch_hooks",
     "dynamic_routing", "token_profile", "phases", "parallel",
     "auto_visualize", "auto_report",

package/src/resources/extensions/gsd/commands.ts

@@ -49,6 +49,7 @@ import { runEnvironmentChecks } from "./doctor-environment.js";
 import { handleLogs } from "./commands-logs.js";
 import { handleStart, handleTemplates, getTemplateCompletions } from "./commands-workflow-templates.js";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
+import { handleCmux } from "./commands-cmux.js";
 
 
 /** Resolve the effective project root, accounting for worktree paths. */
@@ -105,7 +106,7 @@ function notifyRemoteAutoActive(ctx: ExtensionCommandContext, basePath: string):
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|update",
+    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|update",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -114,6 +115,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "stop", desc: "Stop auto mode gracefully" },
         { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
         { cmd: "status", desc: "Progress dashboard" },
+        { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
         { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
         { cmd: "queue", desc: "Queue and reorder future milestones" },
         { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
@@ -147,6 +149,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
         { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
         { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge)" },
+        { cmd: "cmux", desc: "Manage cmux integration (status, sidebar, notifications, splits)" },
         { cmd: "park", desc: "Park a milestone — skip without deleting" },
         { cmd: "unpark", desc: "Reactivate a parked milestone" },
         { cmd: "update", desc: "Update GSD to the latest version" },
@@ -203,6 +206,38 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((s) => ({ value: `parallel ${s.cmd}`, label: s.cmd, description: s.desc }));
       }
 
+      if (parts[0] === "cmux") {
+        if (parts.length <= 2) {
+          const subPrefix = parts[1] ?? "";
+          const subs = [
+            { cmd: "status", desc: "Show cmux detection, prefs, and capabilities" },
+            { cmd: "on", desc: "Enable cmux integration" },
+            { cmd: "off", desc: "Disable cmux integration" },
+            { cmd: "notifications", desc: "Toggle cmux desktop notifications" },
+            { cmd: "sidebar", desc: "Toggle cmux sidebar metadata" },
+            { cmd: "splits", desc: "Toggle cmux visual subagent splits" },
+            { cmd: "browser", desc: "Toggle future browser integration flag" },
+          ];
+          return subs
+            .filter((s) => s.cmd.startsWith(subPrefix))
+            .map((s) => ({ value: `cmux ${s.cmd}`, label: s.cmd, description: s.desc }));
+        }
+
+        if (parts.length <= 3 && ["notifications", "sidebar", "splits", "browser"].includes(parts[1])) {
+          const togglePrefix = parts[2] ?? "";
+          return [
+            { cmd: "on", desc: "Enable this cmux area" },
+            { cmd: "off", desc: "Disable this cmux area" },
+          ]
+            .filter((item) => item.cmd.startsWith(togglePrefix))
+            .map((item) => ({
+              value: `cmux ${parts[1]} ${item.cmd}`,
+              label: item.cmd,
+              description: item.desc,
+            }));
+        }
+      }
+
       if (parts[0] === "setup" && parts.length <= 2) {
         const subPrefix = parts[1] ?? "";
         const subs = [
@@ -474,6 +509,18 @@ export async function handleGSDCommand(
     return;
   }
 
+  if (trimmed === "widget" || trimmed.startsWith("widget ")) {
+    const { cycleWidgetMode, setWidgetMode, getWidgetMode } = await import("./auto-dashboard.js");
+    const arg = trimmed.replace(/^widget\s*/, "").trim();
+    if (arg === "full" || arg === "small" || arg === "min" || arg === "off") {
+      setWidgetMode(arg);
+    } else {
+      cycleWidgetMode();
+    }
+    ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info");
+    return;
+  }
+
   if (trimmed === "visualize") {
     await handleVisualize(ctx);
     return;
@@ -493,6 +540,11 @@ export async function handleGSDCommand(
     return;
   }
 
+  if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
+    await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
+    return;
+  }
+
       if (trimmed === "init") {
         const { detectProjectState } = await import("./detection.js");
         const { showProjectInit, handleReinit } = await import("./init-wizard.js");
@@ -996,6 +1048,7 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
     "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
     "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
+    "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
     "  /gsd config         Set API keys for external tools",
     "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
     "  /gsd hooks          Show post-unit hook configuration",

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -173,6 +173,13 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `on_milestone`: boolean — notify when a milestone finishes. Default: `true`.
   - `on_attention`: boolean — notify when manual attention is needed. Default: `true`.
 
+- `cmux`: configures cmux terminal integration when GSD is running inside a cmux workspace. Keys:
+  - `enabled`: boolean — master toggle for cmux integration. Default: `false`.
+  - `notifications`: boolean — route desktop notifications through cmux. Default: `true` when enabled.
+  - `sidebar`: boolean — publish status, progress, and log metadata to the cmux sidebar. Default: `true` when enabled.
+  - `splits`: boolean — run supported subagent work in visible cmux splits. Default: `false`.
+  - `browser`: boolean — reserve the future browser integration flag. Default: `false`.
+
 - `dynamic_routing`: configures the dynamic model router that adjusts model selection based on task complexity. Keys:
   - `enabled`: boolean — enable dynamic routing. Default: `false`.
   - `tier_models`: object — model overrides per complexity tier. Keys: `light`, `standard`, `heavy`. Values are model ID strings.
@@ -477,6 +484,24 @@ Disables per-unit completion notifications (noisy in long runs) while keeping er
 
 ---
 
+## cmux Example
+
+```yaml
+---
+version: 1
+cmux:
+  enabled: true
+  notifications: true
+  sidebar: true
+  splits: true
+  browser: false
+---
+```
+
+Enables cmux-aware notifications, sidebar metadata, and visible subagent splits when GSD is running inside a cmux terminal.
+
+---
+
 ## Post-Unit Hooks Example
 
 ```yaml

package/src/resources/extensions/gsd/index.ts

@@ -65,6 +65,7 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
+import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js";
 
 // ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
 // agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
@@ -623,6 +624,13 @@ export default function (pi: ExtensionAPI) {
     const stopContextTimer = debugTime("context-inject");
     const systemContent = loadPrompt("system");
     const loadedPreferences = loadEffectiveGSDPreferences();
+    if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+      markCmuxPromptShown();
+      ctx.ui.notify(
+        "cmux detected. Run /gsd cmux on to enable sidebar metadata, notifications, and visual subagent splits for this project.",
+        "info",
+      );
+    }
     let preferenceBlock = "";
     if (loadedPreferences) {
       const cwd = process.cwd();

package/src/resources/extensions/gsd/notifications.ts

@@ -4,6 +4,7 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
 export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";
@@ -23,7 +24,15 @@ export function sendDesktopNotification(
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
 ): void {
-  if (!shouldSendDesktopNotification(kind)) return;
+  const loaded = loadEffectiveGSDPreferences()?.preferences;
+  if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
+
+  const cmux = resolveCmuxConfig(loaded);
+  if (cmux.notifications) {
+    const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+    if (delivered) return;
+    emitOsc777Notification(title, message);
+  }
 
   try {
     const command = buildDesktopNotificationCommand(process.platform, title, message, level);

package/src/resources/extensions/gsd/preferences-types.ts

@@ -68,6 +68,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "budget_enforcement",
   "context_pause_threshold",
   "notifications",
+  "cmux",
   "remote_questions",
   "git",
   "post_unit_hooks",
@@ -84,6 +85,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "search_provider",
   "compression_strategy",
   "context_selection",
+  "widget_mode",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -164,6 +166,14 @@ export interface RemoteQuestionsConfig {
   poll_interval_seconds?: number;  // clamped to 2-30
 }
 
+export interface CmuxPreferences {
+  enabled?: boolean;
+  notifications?: boolean;
+  sidebar?: boolean;
+  splits?: boolean;
+  browser?: boolean;
+}
+
 export interface GSDPreferences {
   version?: number;
   mode?: WorkflowMode;
@@ -182,6 +192,7 @@ export interface GSDPreferences {
   budget_enforcement?: BudgetEnforcementMode;
   context_pause_threshold?: number;
   notifications?: NotificationPreferences;
+  cmux?: CmuxPreferences;
   remote_questions?: RemoteQuestionsConfig;
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
@@ -202,6 +213,8 @@ export interface GSDPreferences {
   compression_strategy?: CompressionStrategy;
   /** Context selection mode for file inlining. "full" inlines entire files, "smart" uses semantic chunking. Default derived from token profile. */
   context_selection?: ContextSelectionMode;
+  /** Default widget display mode for auto-mode dashboard. "full" | "small" | "min" | "off". Default: "full". */
+  widget_mode?: "full" | "small" | "min" | "off";
 }
 
 export interface LoadedGSDPreferences {

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -242,6 +242,32 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Cmux ───────────────────────────────────────────────────────────────
+  if (preferences.cmux !== undefined) {
+    if (preferences.cmux && typeof preferences.cmux === "object") {
+      const cmux = preferences.cmux as Record<string, unknown>;
+      const validatedCmux: NonNullable<GSDPreferences["cmux"]> = {};
+      if (cmux.enabled !== undefined) validatedCmux.enabled = !!cmux.enabled;
+      if (cmux.notifications !== undefined) validatedCmux.notifications = !!cmux.notifications;
+      if (cmux.sidebar !== undefined) validatedCmux.sidebar = !!cmux.sidebar;
+      if (cmux.splits !== undefined) validatedCmux.splits = !!cmux.splits;
+      if (cmux.browser !== undefined) validatedCmux.browser = !!cmux.browser;
+
+      const knownCmuxKeys = new Set(["enabled", "notifications", "sidebar", "splits", "browser"]);
+      for (const key of Object.keys(cmux)) {
+        if (!knownCmuxKeys.has(key)) {
+          warnings.push(`unknown cmux key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validatedCmux).length > 0) {
+        validated.cmux = validatedCmux;
+      }
+    } else {
+      errors.push("cmux must be an object");
+    }
+  }
+
   // ─── Remote Questions ───────────────────────────────────────────────
   if (preferences.remote_questions !== undefined) {
     if (preferences.remote_questions && typeof preferences.remote_questions === "object") {

package/src/resources/extensions/gsd/preferences.ts

@@ -45,6 +45,7 @@ export type {
   SkillDiscoveryMode,
   AutoSupervisorConfig,
   RemoteQuestionsConfig,
+  CmuxPreferences,
   GSDPreferences,
   LoadedGSDPreferences,
   SkillResolution,
@@ -241,6 +242,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     notifications: (base.notifications || override.notifications)
       ? { ...(base.notifications ?? {}), ...(override.notifications ?? {}) }
       : undefined,
+    cmux: (base.cmux || override.cmux)
+      ? { ...(base.cmux ?? {}), ...(override.cmux ?? {}) }
+      : undefined,
     remote_questions: override.remote_questions
       ? { ...(base.remote_questions ?? {}), ...override.remote_questions }
       : base.remote_questions,

package/src/resources/extensions/gsd/prompts/research-milestone.md

@@ -25,9 +25,10 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content
-6. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
-7. Write `{{outputPath}}`
+5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
+6. Use the **Research** output template from the inlined context above — include only sections that have real content
+7. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
+8. Write `{{outputPath}}`
 
 ## Strategic Questions to Answer