gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.eaa4973bc

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -46,6 +46,7 @@ import { resolveUokFlags } from "./uok/flags.js";
 import { UokGateRunner } from "./uok/gate-runner.js";
 import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
+import { detectAbandonMilestone } from "./abandon-detect.js";
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
@@ -472,6 +473,36 @@ export async function postUnitPreVerification(pctx, opts) {
         // Rewrite-docs completion
         if (s.currentUnit.type === "rewrite-docs") {
             await runSafely("postUnit", "rewrite-docs-resolve", async () => {
+                // Detect abandon/descope overrides BEFORE resolving them (#3490).
+                // If an override is about abandoning the milestone, park it so the
+                // state engine skips it. Without this, rewrite-docs only edits
+                // markdown but the DB still has the milestone as active.
+                try {
+                    const { loadActiveOverrides } = await import("./files.js");
+                    const overrides = await loadActiveOverrides(s.basePath);
+                    const decision = detectAbandonMilestone(overrides, s.currentMilestoneId);
+                    if (decision.shouldPark && s.currentMilestoneId) {
+                        const { parkMilestone } = await import("./milestone-actions.js");
+                        const parked = parkMilestone(s.basePath, s.currentMilestoneId, decision.reason);
+                        if (parked) {
+                            ctx.ui.notify(`Milestone ${s.currentMilestoneId} parked: "${decision.reason}"`, "info");
+                        }
+                        else {
+                            // Park refused: milestone directory missing, milestone already
+                            // completed (SUMMARY present), or PARKED.md already exists.
+                            // resolveAllOverrides below will still consume the override —
+                            // surface this loudly so the user notices state drift rather
+                            // than silently losing the abandon directive.
+                            const msg = `Abandon detected for ${s.currentMilestoneId} but park refused (milestone is completed, already parked, or missing). Override will be resolved anyway — verify state is correct.`;
+                            logError("engine", msg);
+                            ctx.ui.notify(msg, "warning");
+                        }
+                    }
+                }
+                catch (err) {
+                    logError("engine", `abandon-detect failed: ${err.message}`);
+                    ctx.ui.notify(`Abandon detection failed — check logs. Overrides will still be resolved.`, "warning");
+                }
                 await resolveAllOverrides(s.basePath);
                 // Reset both disk and in-memory counters. Disk counter is authoritative
                 // (survives restarts); in-memory is kept in sync for the current session.

package/dist/resources/extensions/gsd/auto-timeout-recovery.js

@@ -6,8 +6,14 @@
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord, formatExecuteTaskRecoveryStatus, inspectExecuteTaskDurability, } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, writeBlockerPlaceholder, } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
-import { resolveAgentEnd } from "./auto-loop.js";
+import { bumpAndResolveSynthetic } from "./auto/resolve.js";
 export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rctx) {
+    // Note on turn epoch: the bump is intentionally NOT unconditional at
+    // function entry. Two branches below (the "steering retry" paths) keep
+    // the same LLM turn alive and let it try again — they must NOT bump,
+    // otherwise the retry's legitimate writes get marked stale and drop.
+    // Each advance branch calls `bumpAndResolveSynthetic` to bump+resolve
+    // atomically. Search for that helper to find all supersede sites.
     const { basePath, verbose, currentUnitStartedAt, unitRecoveryCount } = rctx;
     const runtime = readUnitRuntimeRecord(basePath, unitType, unitId);
     const recoveryAttempts = runtime?.recoveryAttempts ?? 0;
@@ -36,7 +42,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
             });
             ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} already completed on disk. Continuing auto-mode. (attempt ${attemptNumber})`, "info");
             unitRecoveryCount.delete(recoveryKey);
-            resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+            bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
             return "recovered";
         }
         if (recoveryAttempts < maxRecoveryAttempts) {
@@ -90,7 +96,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
             });
             ctx.ui.notify(`${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts (${diagnostic}). Blocker artifacts written. Advancing pipeline. (attempt ${attemptNumber})`, "warning");
             unitRecoveryCount.delete(recoveryKey);
-            resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+            bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
             return "recovered";
         }
         // Fallback: couldn't write skip artifacts — pause as before.
@@ -115,7 +121,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         });
         ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} artifact already exists on disk. Advancing. (attempt ${attemptNumber})`, "info");
         unitRecoveryCount.delete(recoveryKey);
-        resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+        bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
         return "recovered";
     }
     if (recoveryAttempts < maxRecoveryAttempts) {
@@ -180,7 +186,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         });
         ctx.ui.notify(`${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts. Blocker placeholder written to ${placeholder}. Advancing pipeline. (attempt ${attemptNumber})`, "warning");
         unitRecoveryCount.delete(recoveryKey);
-        resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+        bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
         return "recovered";
     }
     // Fallback: couldn't resolve artifact path — pause as before.

package/dist/resources/extensions/gsd/auto-unit-closeout.js

@@ -20,9 +20,18 @@ export async function closeoutUnit(ctx, basePath, unitType, unitId, startedAt, o
             const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import('./memory-extractor.js');
             const llmCallFn = buildMemoryLLMCall(ctx);
             if (llmCallFn) {
-                extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn).catch((err) => {
+                // Awaited: a fire-and-forget here lets memory-extractor writes land in
+                // .gsd/ after closeoutUnit returns but before the milestone merge
+                // runs, which made the working tree appear dirty to `git merge
+                // --squash` (root cause class of #4704). Completion latency is now
+                // bounded by the extractor's LLM call, which is the acceptable price
+                // for not racing the merge boundary.
+                try {
+                    await extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn);
+                }
+                catch (err) {
                     logWarning("engine", `memory extraction failed for ${unitType}/${unitId}: ${err.message}`);
-                });
+                }
             }
         }
         catch (err) { /* non-fatal */

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

@@ -9,7 +9,7 @@ import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync,
 import { isAbsolute, join, sep as pathSep } from "node:path";
 import { homedir } from "node:os";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
-import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, } from "./gsd-db.js";
+import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, closeDatabase, openDatabase, getDbPath, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
@@ -1433,26 +1433,53 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
     const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
     const shelteredDirs = [];
+    let shelterRestored = false;
     // Helper: restore sheltered milestone directories (#2505).
     // Called on both success and error paths to ensure queued CONTEXT files
-    // are never permanently lost.
+    // are never permanently lost. Idempotent — the error path may fire after
+    // the success path has already restored and removed the shelter dir; a
+    // second call is a no-op instead of logging a misleading "shelter restore
+    // failed: ENOENT" error for shelter sources that were cleaned up legitimately.
     const restoreShelter = () => {
+        if (shelterRestored)
+            return;
+        shelterRestored = true;
         if (shelteredDirs.length === 0)
             return;
+        let restoreFailed = false;
         for (const dirName of shelteredDirs) {
+            const src = join(shelterDir, dirName);
+            // If the shelter source is missing the restore cannot proceed for this
+            // entry. Distinguish "legitimately missing" (shelter dir removed by a
+            // prior successful restore or never copied) from a surprising ENOENT
+            // inside an otherwise-populated shelter.
+            if (!existsSync(src)) {
+                logWarning("worktree", `shelter source missing for ${dirName}; skipping restore (shelter already cleaned or entry never staged)`);
+                continue;
+            }
             try {
                 mkdirSync(milestonesDir, { recursive: true });
-                cpSync(join(shelterDir, dirName), join(milestonesDir, dirName), { recursive: true, force: true });
+                cpSync(src, join(milestonesDir, dirName), { recursive: true, force: true });
             }
             catch (err) { /* best-effort */
-                logError("worktree", `shelter restore failed: ${err instanceof Error ? err.message : String(err)}`);
+                restoreFailed = true;
+                logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        try {
-            rmSync(shelterDir, { recursive: true, force: true });
+        // Preserve the shelter if any per-entry restore failed — it is the only
+        // surviving copy of the queued milestone dirs (sources were deleted during
+        // shelter). Deleting it here would permanently lose those files (#2505).
+        if (restoreFailed) {
+            logWarning("worktree", `shelter retained at ${shelterDir} — manual recovery required for unrestored entries`);
+            return;
         }
-        catch (err) { /* best-effort */
-            logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        if (existsSync(shelterDir)) {
+            try {
+                rmSync(shelterDir, { recursive: true, force: true });
+            }
+            catch (err) { /* best-effort */
+                logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     };
     try {
@@ -1491,6 +1518,21 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
     //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
     //     in step 7 above, so they won't be swept into the stash.
+    // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
+    // sidecars while the connection is open. `git stash --include-untracked`
+    // walks those files and fails with EBUSY (#4704). Close the DB before
+    // stashing so Windows releases the handles; reopen after. No-op on
+    // POSIX, where advisory locks don't block git.
+    const needsDbCycle = process.platform === "win32" && isDbAvailable();
+    const dbPathToReopen = needsDbCycle ? getDbPath() : null;
+    if (needsDbCycle) {
+        try {
+            closeDatabase();
+        }
+        catch (err) {
+            logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     let stashed = false;
     try {
         const status = execFileSync("git", ["status", "--porcelain"], {
@@ -1508,6 +1550,14 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         // report the dirty tree if it fails.
         logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    if (needsDbCycle && dbPathToReopen) {
+        try {
+            openDatabase(dbPathToReopen);
+        }
+        catch (err) {
+            logWarning("worktree", `post-stash db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // 7b. Clean up stale merge state before attempting squash merge (#2912).
     // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path,
     // or interrupted operation) causes `git merge --squash` to refuse with

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

@@ -60,7 +60,14 @@ import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
-import { clearCmuxSidebar, logCmuxEvent, syncCmuxSidebar } from "../cmux/index.js";
+import { CMUX_CHANNELS } from "../shared/cmux-events.js";
+function makeCmuxEmitters(pi) {
+    return {
+        syncCmuxSidebar: (preferences, state) => pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences, state }),
+        logCmuxEvent: (preferences, message, level) => pi.events.emit(CMUX_CHANNELS.LOG, { preferences, message, level: level ?? "info" }),
+        clearCmuxSidebar: (preferences) => pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "clear", preferences }),
+    };
+}
 // ── Extracted modules ──────────────────────────────────────────────────────
 import { startUnitSupervision } from "./auto-timers.js";
 import { runPostUnitVerification } from "./auto-verification.js";
@@ -267,6 +274,10 @@ export function getAutoDashboardData() {
 export function isAutoActive() {
     return s.active;
 }
+/** Test-only seam for validating auto-mode guards (#4704). Do not use in production code. */
+export function _setAutoActiveForTest(active) {
+    s.active = active;
+}
 export function isAutoPaused() {
     return s.paused;
 }
@@ -446,7 +457,6 @@ function handleLostSessionLock(ctx, lockStatus) {
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
     deregisterSigtermHandler();
-    clearCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences);
     const base = lockBase();
     const lockFilePath = base ? join(gsdRoot(base), "auto.lock") : "unknown";
     const recoverySuggestion = "\nTo recover, run: gsd doctor --fix";
@@ -674,8 +684,12 @@ export async function stopAuto(ctx, pi, reason) {
         }
         // ── Step 9: Cmux sidebar / event log ──
         try {
-            clearCmuxSidebar(loadedPreferences);
-            logCmuxEvent(loadedPreferences, `Auto-mode stopped${reasonSuffix || ""}.`, reason?.startsWith("Blocked:") ? "warning" : "info");
+            pi?.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "clear", preferences: loadedPreferences });
+            pi?.events.emit(CMUX_CHANNELS.LOG, {
+                preferences: loadedPreferences,
+                message: `Auto-mode stopped${reasonSuffix || ""}.`,
+                level: reason?.startsWith("Blocked:") ? "warning" : "info",
+            });
         }
         catch (e) {
             debugLog("stop-cleanup-cmux", { error: e instanceof Error ? e.message : String(e) });
@@ -892,11 +906,12 @@ function buildResolver() {
  * Build the LoopDeps object from auto.ts private scope.
  * This bundles all private functions that autoLoop needs without exporting them.
  */
-function buildLoopDeps() {
+function buildLoopDeps(pi) {
     // Initialize the unified rule registry with converted dispatch rules.
     // Must happen before LoopDeps is assembled so facade functions
     // (resolveDispatch, runPreDispatchHooks, etc.) delegate to the registry.
     initRegistry(convertDispatchRules(DISPATCH_RULES));
+    const cmux = makeCmuxEmitters(pi);
     return {
         lockBase,
         buildSnapshotOpts,
@@ -904,8 +919,11 @@ function buildLoopDeps() {
         pauseAuto,
         clearUnitTimeout,
         updateProgressWidget,
-        syncCmuxSidebar,
-        logCmuxEvent,
+        ...cmux,
+        handleLostSessionLock: (ctx, lockStatus) => {
+            cmux.clearCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences);
+            handleLostSessionLock(ctx, lockStatus);
+        },
         // State and cache
         invalidateAllCaches,
         deriveState,
@@ -920,7 +938,6 @@ function buildLoopDeps() {
         // Session lock
         validateSessionLock: getSessionLockStatus,
         updateSessionLock,
-        handleLostSessionLock,
         // Milestone transition
         sendDesktopNotification,
         setActiveMilestoneId,
@@ -1236,7 +1253,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         await openProjectDbIfPresent(s.basePath);
         try {
             await rebuildState(s.basePath);
-            syncCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, await deriveState(s.basePath));
+            pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, state: await deriveState(s.basePath) });
         }
         catch (e) {
             debugLog("resume-rebuild-state-failed", {
@@ -1266,14 +1283,14 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         }
         updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
-        logCmuxEvent(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
+        pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
         captureProjectRootEnv(s.originalBasePath || s.basePath);
         startAutoCommandPolling(s.basePath);
         await runAutoLoopWithUok({
             ctx,
             pi,
             s,
-            deps: buildLoopDeps(),
+            deps: buildLoopDeps(pi),
             runKernelLoop: runUokKernelLoop,
             runLegacyLoop: runLegacyAutoLoop,
         });
@@ -1292,20 +1309,20 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         return;
     captureProjectRootEnv(s.originalBasePath || s.basePath);
     try {
-        syncCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, await deriveState(s.basePath));
+        pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, state: await deriveState(s.basePath) });
     }
     catch (err) {
         // Best-effort only — sidebar sync must never block auto-mode startup
         logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
-    logCmuxEvent(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
+    pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: requestedStepMode ? "Step-mode started." : "Auto-mode started.", level: "progress" });
     startAutoCommandPolling(s.basePath);
     // Dispatch the first unit
     await runAutoLoopWithUok({
         ctx,
         pi,
         s,
-        deps: buildLoopDeps(),
+        deps: buildLoopDeps(pi),
         runKernelLoop: runUokKernelLoop,
         runLegacyLoop: runLegacyAutoLoop,
     });

package/dist/resources/extensions/gsd/bootstrap/provider-error-resume.js

@@ -3,6 +3,8 @@ import { resetTransientRetryState } from "./agent-end-recovery.js";
 import { resetSessionTimeoutState } from "../auto/phases.js";
 const defaultDeps = {
     getSnapshot: () => getAutoDashboardData(),
+    resetTransientRetryState,
+    resetSessionTimeoutState,
     startAuto,
 };
 export async function resumeAutoAfterProviderDelay(pi, ctx, deps = defaultDeps) {
@@ -18,8 +20,8 @@ export async function resumeAutoAfterProviderDelay(pi, ctx, deps = defaultDeps)
     // Reset retry counters before restarting — without this, counters
     // accumulate across pause/resume cycles and permanently lock out
     // auto-resume after their respective MAX thresholds.
-    resetTransientRetryState();
-    resetSessionTimeoutState();
+    deps.resetTransientRetryState();
+    deps.resetSessionTimeoutState();
     await deps.startAuto(ctx, pi, snapshot.basePath, false, { step: snapshot.stepMode });
     return "resumed";
 }

package/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -12,6 +12,13 @@ import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning } from "../workflow-logger.js";
+// Static import so cmux event listeners are registered synchronously during
+// extension bootstrap. Prior implementation used `void import().then()` which
+// queued listener registration as a microtask — any CMUX_CHANNELS emit fired
+// in the same event loop turn as registration (e.g. from a provider-error
+// session hook calling startAuto) would be silently dropped because Node's
+// EventEmitter does not buffer events for late subscribers.
+import { initCmuxEventListeners } from "../../cmux/index.js";
 export { writeCrashLog } from "./crash-log.js";
 export function handleRecoverableExtensionProcessError(err) {
     if (err.code === "EPIPE") {
@@ -89,6 +96,10 @@ export function registerGsdExtension(pi) {
         ["memory-tools", () => registerMemoryTools(pi)],
         ["exec-tools", () => registerExecTools(pi)],
         ["shortcuts", () => registerShortcuts(pi)],
+        // cmux is a library (no pi), so gsd sets up the event listeners on its
+        // behalf using the shared event channel contract. Registration is
+        // synchronous — see the import comment above for the rationale.
+        ["cmux-events", () => initCmuxEventListeners(pi.events)],
         ["hooks", () => registerHooks(pi, ecosystemHandlers)],
         ["ecosystem", () => {
                 void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -16,7 +16,6 @@ import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-comma
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
-import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 /**
@@ -87,13 +86,19 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         shortcutShell: formatShortcut("Ctrl+Alt+B"),
     });
     let loadedPreferences = loadEffectiveGSDPreferences();
-    if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-        markCmuxPromptShown();
-        if (autoEnableCmuxPreferences()) {
-            loadedPreferences = loadEffectiveGSDPreferences();
-            ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+    try {
+        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
+        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+            markCmuxPromptShown();
+            if (autoEnableCmuxPreferences()) {
+                loadedPreferences = loadEffectiveGSDPreferences();
+                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+            }
         }
     }
+    catch (e) {
+        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+    }
     let preferenceBlock = "";
     if (loadedPreferences) {
         const cwd = process.cwd();

package/dist/resources/extensions/gsd/commands/handlers/workflow.js

@@ -17,6 +17,22 @@ import { validateDefinition } from "../../definition-loader.js";
 import { formatPluginInfo, listPluginsFormatted, resolvePlugin, } from "../../workflow-plugins.js";
 import { dispatchOneshot } from "../../workflow-dispatch.js";
 import { fetchWorkflowSource, globalInstallDir, inferPluginName, installPlugin, previewContent, projectInstallDir, resolveSourceUrl, uninstallPlugin, validateFetchedContent, } from "../../workflow-install.js";
+/**
+ * Refuses interactive commands that mutate durable .gsd/ planning state while
+ * auto-mode holds the worktree. Returns true if the command was blocked and
+ * the caller should return immediately; false if it is safe to proceed.
+ *
+ * Auto-mode's squash merge performs a pre-merge dirty-tree check; concurrent
+ * writes by interactive commands between that check and the merge itself
+ * cause __dirty_working_tree__ failures (#4704).
+ */
+function requireNotAutoActive(commandName, ctx) {
+    if (!isAutoActive())
+        return false;
+    ctx.ui.notify(`${commandName} cannot run while auto-mode is active.\n` +
+        `Stop auto-mode first with /gsd stop, then run ${commandName}.`, "error");
+    return true;
+}
 // ─── Custom Workflow Subcommands ─────────────────────────────────────────
 const RESERVED_SUBCOMMANDS = new Set([
     "new", "run", "list", "validate", "pause", "resume",
@@ -394,12 +410,16 @@ async function handleCustomWorkflow(sub, ctx, pi) {
 export async function handleWorkflowCommand(trimmed, ctx, pi) {
     // ── /gsd do — natural language routing (must be early to route to other commands) ──
     if (trimmed === "do" || trimmed.startsWith("do ")) {
+        if (requireNotAutoActive("/gsd do", ctx))
+            return true;
         const { handleDo } = await import("../../commands-do.js");
         await handleDo(trimmed.replace(/^do\s*/, "").trim(), ctx, pi);
         return true;
     }
     // ── Backlog management ──
     if (trimmed === "backlog" || trimmed.startsWith("backlog ")) {
+        if (requireNotAutoActive("/gsd backlog", ctx))
+            return true;
         const { handleBacklog } = await import("../../commands-backlog.js");
         await handleBacklog(trimmed.replace(/^backlog\s*/, "").trim(), ctx, pi);
         return true;
@@ -410,23 +430,26 @@ export async function handleWorkflowCommand(trimmed, ctx, pi) {
         return handleCustomWorkflow(sub, ctx, pi);
     }
     if (trimmed === "queue") {
+        if (requireNotAutoActive("/gsd queue", ctx))
+            return true;
         await showQueue(ctx, pi, projectRoot());
         return true;
     }
     if (trimmed === "discuss") {
+        if (requireNotAutoActive("/gsd discuss", ctx))
+            return true;
         await showDiscuss(ctx, pi, projectRoot());
         return true;
     }
     if (trimmed === "quick" || trimmed.startsWith("quick ")) {
-        if (isAutoActive()) {
-            ctx.ui.notify("/gsd quick cannot run while auto-mode is active.\n" +
-                "Stop auto-mode first with /gsd stop, then run /gsd quick.", "error");
+        if (requireNotAutoActive("/gsd quick", ctx))
             return true;
-        }
         await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
         return true;
     }
     if (trimmed === "new-milestone") {
+        if (requireNotAutoActive("/gsd new-milestone", ctx))
+            return true;
         const basePath = projectRoot();
         const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
         if (existsSync(headlessContextPath)) {
@@ -452,6 +475,8 @@ export async function handleWorkflowCommand(trimmed, ctx, pi) {
         return true;
     }
     if (trimmed === "park" || trimmed.startsWith("park ")) {
+        if (requireNotAutoActive("/gsd park", ctx))
+            return true;
         const basePath = projectRoot();
         const arg = trimmed.replace(/^park\s*/, "").trim();
         let targetId = arg;
@@ -474,6 +499,8 @@ export async function handleWorkflowCommand(trimmed, ctx, pi) {
         return true;
     }
     if (trimmed === "unpark" || trimmed.startsWith("unpark ")) {
+        if (requireNotAutoActive("/gsd unpark", ctx))
+            return true;
         const basePath = projectRoot();
         const arg = trimmed.replace(/^unpark\s*/, "").trim();
         let targetId = arg;

package/dist/resources/extensions/gsd/commands-cmux.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, writeFileSync } 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";
@@ -63,7 +62,8 @@ async function writeProjectCmuxPreferences(ctx, updater) {
 function resolveProjectPreferencesWritePath() {
     return loadProjectGSDPreferences()?.path ?? getProjectGSDPreferencesPath();
 }
-function formatCmuxStatus() {
+async function formatCmuxStatus() {
+    const { CmuxClient, detectCmuxEnvironment, resolveCmuxConfig } = await import("../cmux/index.js");
     const loaded = loadEffectiveGSDPreferences();
     const detected = detectCmuxEnvironment();
     const resolved = resolveCmuxConfig(loaded?.preferences);
@@ -87,7 +87,8 @@ function formatCmuxStatus() {
         `Capabilities: access=${accessMode}, methods=${methods}`,
     ].join("\n");
 }
-function ensureCmuxAvailableForEnable(ctx) {
+async function ensureCmuxAvailableForEnable(ctx) {
+    const { detectCmuxEnvironment } = await import("../cmux/index.js");
     const detected = detectCmuxEnvironment();
     if (detected.available)
         return true;
@@ -97,11 +98,11 @@ function ensureCmuxAvailableForEnable(ctx) {
 export async function handleCmux(args, ctx) {
     const trimmed = args.trim();
     if (!trimmed || trimmed === "status") {
-        ctx.ui.notify(formatCmuxStatus(), "info");
+        ctx.ui.notify(await formatCmuxStatus(), "info");
         return;
     }
     if (trimmed === "on") {
-        if (!ensureCmuxAvailableForEnable(ctx))
+        if (!await ensureCmuxAvailableForEnable(ctx))
             return;
         await writeProjectCmuxPreferences(ctx, (prefs) => {
             prefs.cmux = {
@@ -122,6 +123,7 @@ export async function handleCmux(args, ctx) {
         await writeProjectCmuxPreferences(ctx, (prefs) => {
             prefs.cmux = { ...(prefs.cmux ?? {}), enabled: false };
         });
+        const { clearCmuxSidebar } = await import("../cmux/index.js");
         clearCmuxSidebar(effective);
         ctx.ui.notify("cmux integration disabled in project preferences.", "info");
         return;
@@ -130,7 +132,7 @@ export async function handleCmux(args, ctx) {
     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))
+        if (enabled && !await ensureCmuxAvailableForEnable(ctx))
             return;
         await writeProjectCmuxPreferences(ctx, (prefs) => {
             const next = { ...(prefs.cmux ?? {}) };
@@ -140,6 +142,7 @@ export async function handleCmux(args, ctx) {
             prefs.cmux = next;
         });
         if (!enabled && feature === "sidebar") {
+            const { clearCmuxSidebar } = await import("../cmux/index.js");
             clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
         }
         const note = feature === "browser" && enabled