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

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";
@@ -242,13 +243,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 +272,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 +331,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 +474,8 @@ function buildLoopDeps() {
         pauseAuto,
         clearUnitTimeout,
         updateProgressWidget,
+        syncCmuxSidebar,
+        logCmuxEvent,
         // State and cache
         invalidateAllCaches,
         deriveState,
@@ -466,7 +487,7 @@ function buildLoopDeps() {
         // Resource version guard
         checkResourcesStale,
         // Session lock
-        validateSessionLock,
+        validateSessionLock: getSessionLockStatus,
         updateSessionLock,
         handleLostSessionLock,
         // Milestone transition
@@ -605,6 +626,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 +656,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 +670,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

@@ -37,6 +37,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. */
 export function projectRoot() {
     const cwd = process.cwd();
@@ -89,7 +90,7 @@ function notifyRemoteAutoActive(ctx, basePath) {
 }
 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 +99,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 +133,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 +185,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 +463,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 +491,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");
@@ -900,6 +949,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",

package/dist/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/dist/resources/extensions/gsd/git-service.js

@@ -349,10 +349,18 @@ 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.
         // Native path uses libgit2 (single call), fallback spawns multiple git processes.

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

@@ -1,6 +1,7 @@
 // GSD Extension — Session History View
 // Human-readable display of past auto-mode unit executions.
-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, } from "./metrics.js";
 /**
  * Show recent unit execution history with cost, tokens, and duration.

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

@@ -46,6 +46,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.
 // Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
@@ -532,6 +533,10 @@ export default function (pi) {
         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/dist/resources/extensions/gsd/metrics.js

@@ -17,8 +17,10 @@ import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
-// Re-export from shared — canonical implementation lives in format-utils.
-export { formatTokenCount } from "../shared/mod.js";
+// Re-export from shared — import directly from format-utils to avoid pulling
+// in the full barrel (mod.js → ui.js → @gsd/pi-tui) which breaks when loaded
+// outside jiti's alias resolution (e.g. dynamic import in auto-loop reports).
+export { formatTokenCount } from "../shared/format-utils.js";
 export function classifyUnitPhase(unitType) {
     switch (unitType) {
         case "research-milestone":

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

@@ -2,13 +2,22 @@
 // Cross-platform desktop notifications for auto-mode events.
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
  */
 export function sendDesktopNotification(title, message, level = "info", kind = "complete") {
-    if (!shouldSendDesktopNotification(kind))
+    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);
         if (!command)

package/dist/resources/extensions/gsd/preferences-types.js

@@ -47,6 +47,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "budget_enforcement",
     "context_pause_threshold",
     "notifications",
+    "cmux",
     "remote_questions",
     "git",
     "post_unit_hooks",
@@ -63,6 +64,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "search_provider",
     "compression_strategy",
     "context_selection",
+    "widget_mode",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -225,6 +225,35 @@ export function validatePreferences(preferences) {
             errors.push("notifications must be an object");
         }
     }
+    // ─── Cmux ───────────────────────────────────────────────────────────────
+    if (preferences.cmux !== undefined) {
+        if (preferences.cmux && typeof preferences.cmux === "object") {
+            const cmux = preferences.cmux;
+            const validatedCmux = {};
+            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") {