gsd-pi 2.36.0-dev.f887f4e → 2.37.0-dev.3186675

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

@@ -15,6 +15,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import type { AutoSession } from "./auto/session.js";
 import { NEW_SESSION_TIMEOUT_MS } from "./auto/session.js";
 import type { GSDPreferences } from "./preferences.js";
+import type { SessionLockStatus } from "./session-lock.js";
 import type { GSDState } from "./types.js";
 import type { CloseoutOptions } from "./auto-unit-closeout.js";
 import type { PostUnitContext } from "./auto-post-unit.js";
@@ -25,6 +26,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 +278,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;
@@ -300,7 +308,7 @@ export interface LoopDeps {
   checkResourcesStale: (version: string | null) => string | null;
 
   // Session lock
-  validateSessionLock: (basePath: string) => boolean;
+  validateSessionLock: (basePath: string) => SessionLockStatus;
   updateSessionLock: (
     basePath: string,
     unitType: string,
@@ -308,7 +316,10 @@ export interface LoopDeps {
     completedUnits: number,
     sessionFile?: string,
   ) => void;
-  handleLostSessionLock: (ctx?: ExtensionContext) => void;
+  handleLostSessionLock: (
+    ctx?: ExtensionContext,
+    lockStatus?: SessionLockStatus,
+  ) => void;
 
   // Milestone transition functions
   sendDesktopNotification: (
@@ -552,10 +563,24 @@ export async function autoLoop(
     try {
       // ── Blanket try/catch: one bad iteration must not kill the session
 
-      if (deps.lockBase() && !deps.validateSessionLock(deps.lockBase())) {
-        deps.handleLostSessionLock(ctx);
-        debugLog("autoLoop", { phase: "exit", reason: "session-lock-lost" });
-        break;
+      const sessionLockBase = deps.lockBase();
+      if (sessionLockBase) {
+        const lockStatus = deps.validateSessionLock(sessionLockBase);
+        if (!lockStatus.valid) {
+          debugLog("autoLoop", {
+            phase: "session-lock-invalid",
+            reason: lockStatus.failureReason ?? "unknown",
+            existingPid: lockStatus.existingPid,
+            expectedPid: lockStatus.expectedPid,
+          });
+          deps.handleLostSessionLock(ctx, lockStatus);
+          debugLog("autoLoop", {
+            phase: "exit",
+            reason: "session-lock-lost",
+            detail: lockStatus.failureReason ?? "unknown",
+          });
+          break;
+        }
       }
 
       // ── Phase 1: Pre-dispatch ───────────────────────────────────────────
@@ -609,6 +634,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 +656,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 +798,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 +887,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 +913,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 +957,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 +978,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 +996,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 +1014,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

@@ -47,10 +47,11 @@ import {
 } from "./crash-recovery.js";
 import {
   acquireSessionLock,
-  validateSessionLock,
+  getSessionLockStatus,
   releaseSessionLock,
   updateSessionLock,
 } from "./session-lock.js";
+import type { SessionLockStatus } from "./session-lock.js";
 import {
   clearUnitRuntimeRecord,
   inspectExecuteTaskDurability,
@@ -184,6 +185,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";
@@ -460,14 +462,33 @@ function buildSnapshotOpts(
   };
 }
 
-function handleLostSessionLock(ctx?: ExtensionContext): void {
-  debugLog("session-lock-lost", { lockBase: lockBase() });
+function handleLostSessionLock(
+  ctx?: ExtensionContext,
+  lockStatus?: SessionLockStatus,
+): void {
+  debugLog("session-lock-lost", {
+    lockBase: lockBase(),
+    reason: lockStatus?.failureReason,
+    existingPid: lockStatus?.existingPid,
+    expectedPid: lockStatus?.expectedPid,
+  });
   s.active = false;
   s.paused = false;
   clearUnitTimeout();
   deregisterSigtermHandler();
+  clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
+  const message =
+    lockStatus?.failureReason === "pid-mismatch"
+      ? lockStatus.existingPid
+        ? `Session lock moved to PID ${lockStatus.existingPid} — another GSD process appears to have taken over. Stopping gracefully.`
+        : "Session lock moved to a different process — another GSD process appears to have taken over. Stopping gracefully."
+      : lockStatus?.failureReason === "missing-metadata"
+        ? "Session lock metadata disappeared, so ownership could not be confirmed. Stopping gracefully."
+        : lockStatus?.failureReason === "compromised"
+          ? "Session lock was compromised or invalidated during heartbeat checks; takeover was not confirmed. Stopping gracefully."
+          : "Session lock lost. Stopping gracefully.";
   ctx?.ui.notify(
-    "Session lock lost — another GSD process appears to have taken over. Stopping gracefully.",
+    message,
     "error",
   );
   ctx?.ui.setStatus("gsd-auto", undefined);
@@ -481,6 +502,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 +565,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 +737,8 @@ function buildLoopDeps(): LoopDeps {
     pauseAuto,
     clearUnitTimeout,
     updateProgressWidget,
+    syncCmuxSidebar,
+    logCmuxEvent,
 
     // State and cache
     invalidateAllCaches,
@@ -724,7 +755,7 @@ function buildLoopDeps(): LoopDeps {
     checkResourcesStale,
 
     // Session lock
-    validateSessionLock,
+    validateSessionLock: getSessionLockStatus,
     updateSessionLock,
     handleLostSessionLock,
 
@@ -890,6 +921,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 +973,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 +998,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/git-service.ts

@@ -479,9 +479,20 @@ export class GitServiceImpl {
 
     const wtName = detectWorktreeName(this.basePath);
     if (wtName) {
+      // Auto-mode worktrees use milestone/<MID> branches (wtName = milestone ID)
+      const milestoneBranch = `milestone/${wtName}`;
+      const currentBranch = nativeGetCurrentBranch(this.basePath);
+
+      // If we're on a milestone/<MID> branch, use it (auto-mode case)
+      if (currentBranch.startsWith("milestone/")) {
+        return currentBranch;
+      }
+
+      // Otherwise check for manual worktree branch (worktree/<name>)
       const wtBranch = `worktree/${wtName}`;
       if (nativeBranchExists(this.basePath, wtBranch)) return wtBranch;
-      return nativeGetCurrentBranch(this.basePath);
+
+      return currentBranch;
     }
 
     // Repo-level default detection: origin/HEAD → main → master → current branch.

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

@@ -2,7 +2,8 @@
 // Human-readable display of past auto-mode unit executions.
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { formatDuration, padRight, truncateWithEllipsis } from "../shared/format-utils.js";
+import { formatDuration, truncateWithEllipsis } from "../shared/format-utils.js";
+import { padRight } from "../shared/layout-utils.js";
 import {
   getLedger, getProjectTotals, formatCost, formatTokenCount,
   aggregateBySlice, aggregateByPhase, aggregateByModel, loadLedgerFromDisk,

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();