gsd-pi 2.36.0 → 2.37.0-dev.68605cd

package/dist/resources/extensions/gsd/auto-loop.js

@@ -218,10 +218,24 @@ export async function autoLoop(ctx, pi, s, deps) {
         }
         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 ───────────────────────────────────────────
             // Resource version guard
@@ -258,6 +272,7 @@ export async function autoLoop(ctx, pi, s, deps) {
             }
             // 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", {
@@ -270,6 +285,7 @@ export async function autoLoop(ctx, pi, s, deps) {
             if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) {
                 ctx.ui.notify(`Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}: ${midTitle}.`, "info");
                 deps.sendDesktopNotification("GSD", `Milestone ${s.currentMilestoneId} complete!`, "success", "milestone");
+                deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}.`, "success");
                 const vizPrefs = deps.loadEffectiveGSDPreferences()?.preferences;
                 if (vizPrefs?.auto_visualize) {
                     ctx.ui.notify("Run /gsd visualize to see progress overview.", "info");
@@ -363,6 +379,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                         deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
                     }
                     deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
+                    deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, "All milestones complete.", "success");
                     await deps.stopAuto(ctx, pi, "All milestones complete");
                 }
                 else if (state.phase === "blocked") {
@@ -370,6 +387,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                     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) => m.id).join(", ");
@@ -415,6 +433,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                     deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
                 }
                 deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "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;
@@ -428,6 +447,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                 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;
             }
@@ -458,30 +478,35 @@ export async function autoLoop(ctx, pi, s, deps) {
                     if (budgetEnforcementAction === "pause") {
                         ctx.ui.notify(`${msg} Pausing auto-mode — /gsd auto to override and continue.`, "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;
                     ctx.ui.notify(`Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
                     deps.sendDesktopNotification("GSD", `Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning", "budget");
+                    deps.logCmuxEvent(prefs, `Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
                 }
                 else if (newBudgetAlertLevel === 80) {
                     s.lastBudgetAlertLevel =
                         newBudgetAlertLevel;
                     ctx.ui.notify(`Approaching budget ceiling — 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
                     deps.sendDesktopNotification("GSD", `Approaching budget ceiling — 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning", "budget");
+                    deps.logCmuxEvent(prefs, `Budget 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
                 }
                 else if (newBudgetAlertLevel === 75) {
                     s.lastBudgetAlertLevel =
                         newBudgetAlertLevel;
                     ctx.ui.notify(`Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "info");
                     deps.sendDesktopNotification("GSD", `Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "info", "budget");
+                    deps.logCmuxEvent(prefs, `Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "progress");
                 }
                 else if (budgetAlertLevel === 0) {
                     s.lastBudgetAlertLevel = 0;

package/dist/resources/extensions/gsd/auto.js

@@ -18,7 +18,7 @@ import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic, } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive, } from "./crash-recovery.js";
-import { acquireSessionLock, validateSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
+import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { clearUnitRuntimeRecord, readUnitRuntimeRecord, writeUnitRuntimeRecord, } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
 import { sendDesktopNotification } from "./notifications.js";
@@ -50,6 +50,7 @@ import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } 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";
 import { runPostUnitVerification } from "./auto-verification.js";
@@ -208,6 +209,29 @@ export function stopAutoRemote(projectRoot) {
         return { found: false, error: err.message };
     }
 }
+/**
+ * Check if a remote auto-mode session is running (from a different process).
+ * Reads the crash lock, checks PID liveness, and returns session details.
+ * Used by the guard in commands.ts to prevent bare /gsd, /gsd next, and
+ * /gsd auto from stealing the session lock.
+ */
+export function checkRemoteAutoSession(projectRoot) {
+    const lock = readCrashLock(projectRoot);
+    if (!lock)
+        return { running: false };
+    if (!isLockProcessAlive(lock)) {
+        // Stale lock from a dead process — not a live remote session
+        return { running: false };
+    }
+    return {
+        running: true,
+        pid: lock.pid,
+        unitType: lock.unitType,
+        unitId: lock.unitId,
+        startedAt: lock.startedAt,
+        completedUnits: lock.completedUnits,
+    };
+}
 export function isStepMode() {
     return s.stepMode;
 }
@@ -242,13 +266,28 @@ function buildSnapshotOpts(unitType, unitId) {
         ...(runtime?.continueHereFired ? { continueHereFired: true } : {}),
     };
 }
-function handleLostSessionLock(ctx) {
-    debugLog("session-lock-lost", { lockBase: lockBase() });
+function handleLostSessionLock(ctx, lockStatus) {
+    debugLog("session-lock-lost", {
+        lockBase: lockBase(),
+        reason: lockStatus?.failureReason,
+        existingPid: lockStatus?.existingPid,
+        expectedPid: lockStatus?.expectedPid,
+    });
     s.active = false;
     s.paused = false;
     clearUnitTimeout();
     deregisterSigtermHandler();
-    ctx?.ui.notify("Session lock lost — another GSD process appears to have taken over. Stopping gracefully.", "error");
+    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(message, "error");
     ctx?.ui.setStatus("gsd-auto", undefined);
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
@@ -256,6 +295,7 @@ function handleLostSessionLock(ctx) {
 export async function stopAuto(ctx, pi, reason) {
     if (!s.active && !s.paused)
         return;
+    const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
     const reasonSuffix = reason ? ` — ${reason}` : "";
     clearUnitTimeout();
     if (lockBase())
@@ -314,6 +354,8 @@ export async function stopAuto(ctx, pi, reason) {
             });
         }
     }
+    clearCmuxSidebar(loadedPreferences);
+    logCmuxEvent(loadedPreferences, `Auto-mode stopped${reasonSuffix || ""}.`, reason?.startsWith("Blocked:") ? "warning" : "info");
     if (isDebugEnabled()) {
         const logPath = writeDebugSummary();
         if (logPath) {
@@ -455,6 +497,8 @@ function buildLoopDeps() {
         pauseAuto,
         clearUnitTimeout,
         updateProgressWidget,
+        syncCmuxSidebar,
+        logCmuxEvent,
         // State and cache
         invalidateAllCaches,
         deriveState,
@@ -466,7 +510,7 @@ function buildLoopDeps() {
         // Resource version guard
         checkResourcesStale,
         // Session lock
-        validateSessionLock,
+        validateSessionLock: getSessionLockStatus,
         updateSessionLock,
         handleLostSessionLock,
         // Milestone transition
@@ -605,6 +649,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         restoreHookState(s.basePath);
         try {
             await rebuildState(s.basePath);
+            syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
         }
         catch (e) {
             debugLog("resume-rebuild-state-failed", {
@@ -634,6 +679,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         }
         updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
         writeLock(lockBase(), "resuming", 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;
     }
@@ -647,6 +693,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     const ready = await bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, bootstrapDeps);
     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/dist/resources/extensions/gsd/commands-cmux.js

@@ -0,0 +1,120 @@
+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) {
+    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, updater) {
+    const path = getProjectGSDPreferencesPath();
+    await ensurePreferencesFile(path, ctx, "project");
+    const existing = loadProjectGSDPreferences();
+    const prefs = 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() {
+    const loaded = loadEffectiveGSDPreferences();
+    const detected = detectCmuxEnvironment();
+    const resolved = resolveCmuxConfig(loaded?.preferences);
+    const capabilities = new CmuxClient(resolved).getCapabilities();
+    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) {
+    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, ctx) {
+    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 ?? {}),
+            };
+            prefs.cmux.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 ?? {}), 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];
+        const enabled = parts[1] === "on";
+        if (enabled && !ensureCmuxAvailableForEnable(ctx))
+            return;
+        await writeProjectCmuxPreferences(ctx, (prefs) => {
+            const next = { ...(prefs.cmux ?? {}) };
+            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/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -626,7 +626,7 @@ export function serializePreferencesToFrontmatter(prefs) {
         "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/dist/resources/extensions/gsd/commands.js

@@ -12,7 +12,7 @@ import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
 import { showQueue, showDiscuss, showHeadlessMilestoneCreation } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, stopAutoRemote } from "./auto.js";
+import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, stopAutoRemote, checkRemoteAutoSession } from "./auto.js";
 import { dispatchDirectPhase } from "./auto-direct-dispatch.js";
 import { resolveProjectRoot } from "./worktree.js";
 import { assertSafeDirectory } from "./validate-directory.js";
@@ -36,7 +36,8 @@ import { computeProgressScore, formatProgressLine } from "./progress-score.js";
 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";
+import { showNextAction } from "../shared/mod.js";
 /** Resolve the effective project root, accounting for worktree paths. */
 export function projectRoot() {
     const cwd = process.cwd();
@@ -56,40 +57,85 @@ export function projectRoot() {
     return root;
 }
 /**
- * Check if another process holds the auto-mode session lock.
- * Returns the lock data if a remote session is alive, null otherwise.
+ * Guard against starting auto-mode when a remote session is already running.
+ * Returns true if the caller should proceed with startAuto, false if handled.
  */
-function getRemoteAutoSession(basePath) {
-    const lockData = readSessionLockData(basePath);
-    if (!lockData)
-        return null;
-    if (lockData.pid === process.pid)
-        return null;
-    if (!isSessionLockProcessAlive(lockData))
-        return null;
-    return { pid: lockData.pid };
-}
-/**
- * Show a steering menu when auto-mode is running in another process.
- * Returns true if a remote session was detected (caller should return early).
- */
-function notifyRemoteAutoActive(ctx, basePath) {
-    const remote = getRemoteAutoSession(basePath);
-    if (!remote)
+async function guardRemoteSession(ctx, pi) {
+    // Local session already active — proceed (startAuto handles re-entrant calls)
+    if (isAutoActive() || isAutoPaused())
+        return true;
+    const remote = checkRemoteAutoSession(projectRoot());
+    if (!remote.running || !remote.pid)
+        return true;
+    const unitLabel = remote.unitType && remote.unitId
+        ? `${remote.unitType} (${remote.unitId})`
+        : "unknown unit";
+    const unitsMsg = remote.completedUnits != null
+        ? `${remote.completedUnits} units completed`
+        : "";
+    const choice = await showNextAction(ctx, {
+        title: `Auto-mode is running in another terminal (PID ${remote.pid})`,
+        summary: [
+            `Currently executing: ${unitLabel}`,
+            ...(unitsMsg ? [unitsMsg] : []),
+            ...(remote.startedAt ? [`Started: ${remote.startedAt}`] : []),
+        ],
+        actions: [
+            {
+                id: "status",
+                label: "View status",
+                description: "Show the current GSD progress dashboard.",
+                recommended: true,
+            },
+            {
+                id: "steer",
+                label: "Steer the session",
+                description: "Use /gsd steer <instruction> to redirect the running session.",
+            },
+            {
+                id: "stop",
+                label: "Stop remote session",
+                description: `Send SIGTERM to PID ${remote.pid} to stop it gracefully.`,
+            },
+            {
+                id: "force",
+                label: "Force start (steal lock)",
+                description: "Start a new session, terminating the existing one.",
+            },
+        ],
+        notYetMessage: "Run /gsd when ready.",
+    });
+    if (choice === "status") {
+        await handleStatus(ctx);
         return false;
-    ctx.ui.notify(`Auto-mode is running in another process (PID ${remote.pid}).\n` +
-        `Use these commands to interact with it:\n` +
-        `  /gsd status   — check progress\n` +
-        `  /gsd discuss  — discuss architecture decisions\n` +
-        `  /gsd queue    — queue the next milestone\n` +
-        `  /gsd steer    — apply an override to active work\n` +
-        `  /gsd capture  — fire-and-forget thought\n` +
-        `  /gsd stop     — stop auto-mode`, "warning");
-    return true;
+    }
+    if (choice === "steer") {
+        ctx.ui.notify("Use /gsd steer <instruction> to redirect the running auto-mode session.\n" +
+            "Example: /gsd steer Use Postgres instead of SQLite", "info");
+        return false;
+    }
+    if (choice === "stop") {
+        const result = stopAutoRemote(projectRoot());
+        if (result.found) {
+            ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+        }
+        else if (result.error) {
+            ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+        }
+        else {
+            ctx.ui.notify("Remote session is no longer running.", "info");
+        }
+        return false;
+    }
+    if (choice === "force") {
+        return true; // Proceed — startAuto will steal the lock
+    }
+    // "not_yet" or escape
+    return false;
 }
 export function registerGSDCommand(pi) {
     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) => {
             const subcommands = [
                 { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -98,6 +144,7 @@ export function registerGSDCommand(pi) {
                 { 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" },
@@ -131,6 +178,7 @@ export function registerGSDCommand(pi) {
                 { 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" },
@@ -182,6 +230,36 @@ export function registerGSDCommand(pi) {
                     .filter((s) => s.cmd.startsWith(subPrefix))
                     .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 = [
@@ -430,6 +508,18 @@ export async function handleGSDCommand(args, ctx, pi) {
         await handleStatus(ctx);
         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;
@@ -446,6 +536,10 @@ export async function handleGSDCommand(args, ctx, pi) {
         await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
         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");
@@ -493,12 +587,12 @@ export async function handleGSDCommand(args, ctx, pi) {
             await handleDryRun(ctx, projectRoot());
             return;
         }
-        if (notifyRemoteAutoActive(ctx, projectRoot()))
-            return;
         const verboseMode = trimmed.includes("--verbose");
         const debugMode = trimmed.includes("--debug");
         if (debugMode)
             enableDebug(projectRoot());
+        if (!(await guardRemoteSession(ctx, pi)))
+            return;
         await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
         return;
     }
@@ -507,6 +601,8 @@ export async function handleGSDCommand(args, ctx, pi) {
         const debugMode = trimmed.includes("--debug");
         if (debugMode)
             enableDebug(projectRoot());
+        if (!(await guardRemoteSession(ctx, pi)))
+            return;
         await startAuto(ctx, pi, projectRoot(), verboseMode);
         return;
     }
@@ -850,7 +946,7 @@ Examples:
         return;
     }
     if (trimmed === "") {
-        if (notifyRemoteAutoActive(ctx, projectRoot()))
+        if (!(await guardRemoteSession(ctx, pi)))
             return;
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
         return;
@@ -900,6 +996,7 @@ function showHelp(ctx) {
         "  /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",