gsd-pi 2.57.0 → 2.58.0-dev.778d6ac

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

@@ -11,6 +11,7 @@
  * Extracted from handleAgentEnd() in auto.ts.
  */
 import { deriveState } from "./state.js";
+import { logWarning, logError } from "./workflow-logger.js";
 import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { resolveSliceFile, resolveTaskFile, resolveMilestoneFile, resolveTasksDir, buildTaskFileName, } from "./paths.js";
@@ -319,18 +320,18 @@ export async function postUnitPreVerification(pctx, opts) {
                     ctx.ui.notify(`Triage: ${triageResult.quickTasks.length} quick-task${triageResult.quickTasks.length === 1 ? "" : "s"} queued for execution.`, "info");
                 }
                 for (const action of triageResult.actions) {
-                    process.stderr.write(`gsd-triage: ${action}\n`);
+                    logWarning("engine", `triage resolution: ${action}`);
                 }
             }
             catch (err) {
-                process.stderr.write(`gsd-triage: resolution execution failed: ${err.message}\n`);
+                logError("engine", "triage resolution failed", { error: err.message });
             }
         }
         // Rogue file detection — safety net for LLM bypassing completion tools (D003)
         try {
             const rogueFiles = detectRogueFileWrites(s.currentUnit.type, s.currentUnit.id, s.basePath);
             for (const rogue of rogueFiles) {
-                process.stderr.write(`gsd-rogue: detected rogue file write: ${rogue.path} (unit: ${rogue.unitId})\n`);
+                logWarning("engine", "rogue file write detected", { path: rogue.path, unitId: rogue.unitId });
                 ctx.ui.notify(`Rogue file write detected: ${rogue.path}`, "warning");
             }
         }
@@ -372,7 +373,18 @@ export async function postUnitPreVerification(pctx, opts) {
             // When artifact verification fails for a unit type that has a known expected
             // artifact, return "retry" so the caller re-dispatches with failure context
             // instead of blindly re-dispatching the same unit (#1571).
-            if (!triggerArtifactVerified) {
+            //
+            // HOWEVER, if the DB is unavailable (db_unavailable), the artifact was never
+            // written because the completion tool failed at the infra level. Retrying
+            // can never succeed and produces a costly re-dispatch loop (#2517).
+            if (!triggerArtifactVerified && !isDbAvailable()) {
+                // DB infra failure — do NOT retry; the completion tool returned
+                // db_unavailable so the artifact was never written. Retrying would
+                // produce an infinite re-dispatch loop (#2517).
+                debugLog("postUnit", { phase: "artifact-verify-skip-db-unavailable", unitType: s.currentUnit.type, unitId: s.currentUnit.id });
+                ctx.ui.notify(`Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} but DB is unavailable — skipping retry to avoid loop (#2517)`, "error");
+            }
+            else if (!triggerArtifactVerified) {
                 const hasExpectedArtifact = resolveExpectedArtifactPath(s.currentUnit.type, s.currentUnit.id, s.basePath) !== null;
                 if (hasExpectedArtifact) {
                     const retryKey = `${s.currentUnit.type}:${s.currentUnit.id}`;

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

@@ -1403,7 +1403,7 @@ export async function buildRunUatPrompt(mid, sliceId, uatPath, uatContent, base)
     if (projectInline)
         inlined.push(projectInline);
     const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
-    const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "UAT"));
+    const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
     const uatType = getUatType(uatContent);
     return loadPrompt("run-uat", {
         workingDirectory: base,

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

@@ -11,6 +11,7 @@ import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
 import { isDbAvailable, getTask, getSlice, getSliceTasks, updateTaskStatus } from "./gsd-db.js";
 import { isValidationTerminal } from "./state.js";
+import { getErrorMessage } from "./error-utils.js";
 import { nativeConflictFiles, nativeCommit, nativeCheckoutTheirs, nativeAddPaths, nativeMergeAbort, nativeResetHard, } from "./native-git-bridge.js";
 import { resolveSlicePath, resolveSliceFile, resolveTasksDir, resolveTaskFiles, relMilestoneFile, relSliceFile, buildSliceFileName, resolveMilestoneFile, clearPathCache, resolveGsdRootFile, } from "./paths.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, } from "node:fs";
@@ -425,12 +426,19 @@ export function reconcileMergeState(basePath, ctx) {
     if (conflictedFiles.length === 0) {
         // All conflicts resolved — finalize the merge/squash commit
         try {
-            nativeCommit(basePath, ""); // --no-edit equivalent: use empty message placeholder
-            const mode = hasMergeHead ? "merge" : "squash commit";
-            ctx.ui.notify(`Finalized leftover ${mode} from prior session.`, "info");
+            const commitSha = nativeCommit(basePath, ""); // --no-edit equivalent: use empty message placeholder
+            if (commitSha) {
+                const mode = hasMergeHead ? "merge" : "squash commit";
+                ctx.ui.notify(`Finalized leftover ${mode} from prior session.`, "info");
+            }
+            else {
+                ctx.ui.notify("No new commit needed for leftover merge/squash state — already committed.", "info");
+            }
         }
-        catch {
-            // Commit may already exist; non-fatal
+        catch (err) {
+            const errorMessage = getErrorMessage(err);
+            ctx.ui.notify(`Failed to finalize leftover merge/squash commit: ${errorMessage}`, "error");
+            return false;
         }
     }
     else {

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

@@ -30,15 +30,14 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone, openDatabase } from "./gsd-db.js";
+import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { hideFooter } from "./auto-dashboard.js";
-import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { parseUnitId } from "./unit-id.js";
-import { setLogBasePath } from "./workflow-logger.js";
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from "node:fs";
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
+import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
 /**
  * Bootstrap a fresh auto-mode session. Handles everything from git init
  * through secrets collection, returning when ready for the first
@@ -47,23 +46,33 @@ import { sep as pathSep } from "node:path";
  * Returns false if the bootstrap aborted (e.g., guided flow returned,
  * concurrent session detected). Returns true when ready to dispatch.
  */
-/** Guard: tracks consecutive bootstrap attempts that found phase === "complete".
- *  Prevents the recursive dialog loop described in #1348 where
- *  bootstrapAutoSession → showSmartEntry → checkAutoStartAfterDiscuss → startAuto
- *  cycles indefinitely when the discuss workflow doesn't produce a milestone. */
-let _consecutiveCompleteBootstraps = 0;
-const MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS = 2;
+/**
+ * Open the project-root DB before the first deriveState call (#2841).
+ * When auto-mode starts cold (no prior DB handle), state derivation that
+ * touches DB-backed helpers (queue-order, task status) silently falls back
+ * to markdown-only data, producing stale or incomplete state.  Opening the
+ * DB first ensures deriveState sees the full picture on its very first run.
+ */
 async function openProjectDbIfPresent(basePath) {
     const gsdDbPath = resolveProjectRootDbPath(basePath);
-    if (!existsSync(gsdDbPath) || isDbAvailable())
+    if (!existsSync(gsdDbPath))
+        return;
+    if (isDbAvailable())
         return;
     try {
+        const { openDatabase } = await import("./gsd-db.js");
         openDatabase(gsdDbPath);
     }
-    catch (err) {
-        process.stderr.write(`gsd-db: failed to open existing database: ${err.message}\n`);
+    catch {
+        /* non-fatal — DB lifecycle block below will retry */
     }
 }
+/** Guard: tracks consecutive bootstrap attempts that found phase === "complete".
+ *  Prevents the recursive dialog loop described in #1348 where
+ *  bootstrapAutoSession → showSmartEntry → checkAutoStartAfterDiscuss → startAuto
+ *  cycles indefinitely when the discuss workflow doesn't produce a milestone. */
+let _consecutiveCompleteBootstraps = 0;
+const MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS = 2;
 export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, deps) {
     const { shouldUseWorktreeIsolation, registerSigtermHandler, lockBase, buildResolver, } = deps;
     const lockResult = acquireSessionLock(base);
@@ -120,10 +129,13 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         ensureGitignore(base, { manageGitignore });
         if (manageGitignore !== false)
             untrackRuntimeFiles(base);
-        // Bootstrap .gsd/ if it doesn't exist
+        // Bootstrap milestones/ if it doesn't exist.
+        // Check milestones/ directly — ensureGsdSymlink above already created .gsd/,
+        // so checking .gsd/ existence would be dead code (#2942).
         const gsdDir = join(base, ".gsd");
-        if (!existsSync(gsdDir)) {
-            mkdirSync(join(gsdDir, "milestones"), { recursive: true });
+        const milestonesPath = join(gsdDir, "milestones");
+        if (!existsSync(milestonesPath)) {
+            mkdirSync(milestonesPath, { recursive: true });
             try {
                 nativeAddAll(base);
                 nativeCommit(base, "chore: init gsd");
@@ -178,13 +190,13 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             });
             ctx.ui.notify(`Debug logging enabled → ${getDebugLogPath()}`, "info");
         }
-        // Open the project DB before the first derive so resume uses DB truth
-        // immediately on cold starts instead of falling back to markdown (#2841).
-        await openProjectDbIfPresent(base);
         // Invalidate caches before initial state derivation
         invalidateAllCaches();
         // Clean stale runtime unit files for completed milestones (#887)
         cleanStaleRuntimeUnits(gsdRoot(base), (mid) => !!resolveMilestoneFile(base, mid, "SUMMARY"));
+        // Open the project-root DB before deriveState so DB-backed state
+        // derivation (queue-order, task status) works on a cold start (#2841).
+        await openProjectDbIfPresent(base);
         let state = await deriveState(base);
         // Stale worktree state recovery (#654)
         if (state.activeMilestone &&
@@ -336,7 +348,6 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         s.verbose = verboseMode;
         s.cmdCtx = ctx;
         s.basePath = base;
-        setLogBasePath(base);
         s.unitDispatchCount.clear();
         s.unitRecoveryCount.clear();
         s.lastBudgetAlertLevel = 0;
@@ -392,14 +403,15 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // ── DB lifecycle ──
-        const gsdDbPath = resolveProjectRootDbPath(s.basePath);
+        const gsdDbPath = join(s.basePath, ".gsd", "gsd.db");
         const gsdDirPath = join(s.basePath, ".gsd");
         if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
             const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));
             const hasRequirements = existsSync(join(gsdDirPath, "REQUIREMENTS.md"));
             const hasMilestones = existsSync(join(gsdDirPath, "milestones"));
             try {
-                openDatabase(gsdDbPath);
+                const { openDatabase: openDb } = await import("./gsd-db.js");
+                openDb(gsdDbPath);
                 if (hasDecisions || hasRequirements || hasMilestones) {
                     const { migrateFromMarkdown } = await import("./md-importer.js");
                     migrateFromMarkdown(s.basePath);
@@ -411,7 +423,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         }
         if (existsSync(gsdDbPath) && !isDbAvailable()) {
             try {
-                openDatabase(gsdDbPath);
+                const { openDatabase: openDb } = await import("./gsd-db.js");
+                openDb(gsdDbPath);
             }
             catch (err) {
                 process.stderr.write(`gsd-db: failed to open existing database: ${err.message}\n`);

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

@@ -5,7 +5,7 @@
  * manual `/worktree` which uses `worktree/<name>` branches). This module
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
-import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
+import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, statSync, lstatSync as lstatSyncFn, } from "node:fs";
 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";
@@ -20,7 +20,7 @@ import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } fr
 import { debugLog } from "./debug-logger.js";
 import { logWarning } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, } from "./native-git-bridge.js";
+import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, } from "./native-git-bridge.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
 const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
@@ -39,6 +39,7 @@ const ROOT_STATE_FILES = [
     "QUEUE.md",
     "completed-units.json",
     "metrics.json",
+    "mcp.json",
     // NOTE: project preferences are intentionally NOT in ROOT_STATE_FILES.
     // Forward-sync (main → worktree) is handled explicitly in syncGsdStateToWorktree().
     // Back-sync (worktree → main) must NEVER overwrite the project root's copy
@@ -56,6 +57,65 @@ function isSamePath(a, b) {
         return false;
     }
 }
+// ─── ASSESSMENT Force-Sync Helper (#2821) ─────────────────────────────────
+/** Regex matching YAML frontmatter `verdict:` field. */
+const VERDICT_RE = /verdict:\s*[\w-]+/i;
+/**
+ * Walk a milestone directory and force-overwrite ASSESSMENT files in the
+ * destination when the source copy contains a `verdict:` field.
+ *
+ * This is the targeted fix for the UAT stuck-loop (#2821): the main
+ * safeCopyRecursive uses force:false to protect worktree-authoritative
+ * files (#1886), but ASSESSMENT files written by run-uat must be
+ * forward-synced when the project root has a verdict. Without this,
+ * the worktree retains a stale FAIL or missing ASSESSMENT and
+ * checkNeedsRunUat re-dispatches run-uat indefinitely.
+ *
+ * Only overwrites when the source has a verdict — never clobbers a
+ * worktree ASSESSMENT with a verdictless project-root copy.
+ */
+function forceOverwriteAssessmentsWithVerdict(srcMilestoneDir, dstMilestoneDir) {
+    if (!existsSync(srcMilestoneDir))
+        return;
+    // Walk slices/<SID>/ looking for *-ASSESSMENT.md files
+    const slicesDir = join(srcMilestoneDir, "slices");
+    if (!existsSync(slicesDir))
+        return;
+    try {
+        for (const sliceEntry of readdirSync(slicesDir, { withFileTypes: true })) {
+            if (!sliceEntry.isDirectory())
+                continue;
+            const srcSliceDir = join(slicesDir, sliceEntry.name);
+            const dstSliceDir = join(dstMilestoneDir, "slices", sliceEntry.name);
+            try {
+                for (const fileEntry of readdirSync(srcSliceDir, { withFileTypes: true })) {
+                    if (!fileEntry.isFile())
+                        continue;
+                    if (!fileEntry.name.endsWith("-ASSESSMENT.md"))
+                        continue;
+                    const srcFile = join(srcSliceDir, fileEntry.name);
+                    try {
+                        const srcContent = readFileSync(srcFile, "utf-8");
+                        if (!VERDICT_RE.test(srcContent))
+                            continue; // no verdict in source — skip
+                        // Source has a verdict — force-copy into worktree
+                        mkdirSync(dstSliceDir, { recursive: true });
+                        safeCopy(srcFile, join(dstSliceDir, fileEntry.name), { force: true });
+                    }
+                    catch {
+                        /* non-fatal per file */
+                    }
+                }
+            }
+            catch {
+                /* non-fatal per slice */
+            }
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}
 // ─── Module State ──────────────────────────────────────────────────────────
 /** Original project root before chdir into auto-worktree. */
 let originalBase = null;
@@ -147,16 +207,31 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
     // by validate-milestone) get clobbered by stale project root copies,
     // causing an infinite re-validation loop (#1886).
     safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId), { force: false });
+    // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
+    // The additive-only copy above preserves worktree-authoritative files, but
+    // ASSESSMENT files are special: after run-uat writes a verdict and post-unit
+    // syncs it to the project root, the worktree may retain a stale copy (e.g.
+    // verdict:fail while the project root has verdict:pass from a retry). On
+    // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT
+    // persists, checkNeedsRunUat finds no passing verdict → re-dispatches
+    // run-uat indefinitely (stuck-loop ×9).
+    forceOverwriteAssessmentsWithVerdict(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId));
     // Forward-sync completed-units.json from project root to worktree.
     // Project root is authoritative for completion state after crash recovery;
     // without this, the worktree re-dispatches already-completed units (#1886).
     safeCopy(join(prGsd, "completed-units.json"), join(wtGsd, "completed-units.json"), { force: true });
-    // Delete worktree gsd.db so it rebuilds from the freshly synced files.
-    // Stale DB rows are the root cause of the infinite skip loop (#853).
+    // Delete worktree gsd.db ONLY if it is empty (0 bytes).
+    // An empty DB is stale/corrupt and should be rebuilt (#853).
+    // A non-empty DB was populated by gsd-migrate on respawn and must be
+    // preserved — deleting it truncates the file to 0 bytes when
+    // openDatabase re-creates it, causing "no such table" failures (#2815).
     try {
         const wtDb = join(wtGsd, "gsd.db");
         if (existsSync(wtDb)) {
-            unlinkSync(wtDb);
+            const size = statSync(wtDb).size;
+            if (size === 0) {
+                unlinkSync(wtDb);
+            }
         }
     }
     catch {
@@ -855,6 +930,7 @@ function copyPlanningArtifacts(srcBase, wtPath) {
         "STATE.md",
         "KNOWLEDGE.md",
         "OVERRIDES.md",
+        "mcp.json",
     ]) {
         safeCopy(join(srcGsd, file), join(dstGsd, file), { force: true });
     }
@@ -1060,12 +1136,17 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     const milestoneBranch = autoWorktreeBranch(milestoneId);
     // 1. Auto-commit dirty state in worktree before leaving
     autoCommitDirtyState(worktreeCwd);
-    // Reconcile worktree DB into main DB before leaving worktree context
+    // Reconcile worktree DB into main DB before leaving worktree context.
+    // Skip when both paths resolve to the same physical file (shared WAL /
+    // symlink layout) — ATTACHing a WAL-mode file to itself corrupts the
+    // database (#2823).
     if (isDbAvailable()) {
         try {
             const worktreeDbPath = join(worktreeCwd, ".gsd", "gsd.db");
             const mainDbPath = join(originalBasePath_, ".gsd", "gsd.db");
-            reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+            if (!isSamePath(worktreeDbPath, mainDbPath)) {
+                reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+            }
         }
         catch {
             /* non-fatal */
@@ -1190,7 +1271,17 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             encoding: "utf-8",
         }).trim();
         if (status) {
-            execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId}`], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+            // Use --include-untracked to stash untracked files that would block
+            // the squash merge, but EXCLUDE .gsd/milestones/ (#2505).
+            // --include-untracked without exclusion sweeps queued milestone
+            // CONTEXT files into the stash. If stash pop later fails, those files
+            // are permanently trapped in the stash entry and lost on the next
+            // stash push or drop.
+            execFileSync("git", [
+                "stash", "push", "--include-untracked",
+                "-m", `gsd: pre-merge stash for ${milestoneId}`,
+                "--", ":(exclude).gsd/milestones",
+            ], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
             stashed = true;
         }
     }
@@ -1198,6 +1289,69 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         // Stash failure is non-fatal — proceed without stash and let the merge
         // report the dirty tree if it fails.
     }
+    // 7a. Shelter queued milestone directories before the squash merge (#2505).
+    // The milestone branch may contain copies of queued milestone dirs (via
+    // copyPlanningArtifacts), so `git merge --squash` rejects when those same
+    // files exist as untracked in the working tree. Temporarily move them to
+    // a backup location, then restore after the merge+commit.
+    const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
+    const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
+    const shelteredDirs = [];
+    // Helper: restore sheltered milestone directories (#2505).
+    // Called on both success and error paths to ensure queued CONTEXT files
+    // are never permanently lost.
+    const restoreShelter = () => {
+        if (shelteredDirs.length === 0)
+            return;
+        for (const dirName of shelteredDirs) {
+            try {
+                mkdirSync(milestonesDir, { recursive: true });
+                cpSync(join(shelterDir, dirName), join(milestonesDir, dirName), { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            rmSync(shelterDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    };
+    try {
+        if (existsSync(milestonesDir)) {
+            const entries = readdirSync(milestonesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                // Only shelter directories that do NOT belong to the milestone being merged
+                if (entry.name === milestoneId)
+                    continue;
+                const srcDir = join(milestonesDir, entry.name);
+                const dstDir = join(shelterDir, entry.name);
+                try {
+                    mkdirSync(shelterDir, { recursive: true });
+                    cpSync(srcDir, dstDir, { recursive: true, force: true });
+                    rmSync(srcDir, { recursive: true, force: true });
+                    shelteredDirs.push(entry.name);
+                }
+                catch {
+                    // Non-fatal — if shelter fails, the merge may still succeed
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal — proceed with merge; untracked files may block it
+    }
+    // 7c. Clean stale MERGE_HEAD before the squash merge (#2912).
+    // The native (libgit2) merge path or a prior interrupted merge may leave
+    // MERGE_HEAD in the git dir. `git merge --squash` refuses to run when
+    // MERGE_HEAD exists, so remove it preemptively.
+    try {
+        const gitDirPre = resolveGitDir(originalBasePath_);
+        const mergeHeadPre = join(gitDirPre, "MERGE_HEAD");
+        if (existsSync(mergeHeadPre))
+            unlinkSync(mergeHeadPre);
+    }
+    catch { /* best-effort */ }
     // 8. Squash merge — auto-resolve .gsd/ state file conflicts (#530)
     const mergeResult = nativeMergeSquash(originalBasePath_, milestoneBranch);
     if (!mergeResult.success) {
@@ -1205,6 +1359,17 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         // untracked .gsd/ files left by syncStateToProjectRoot).  Preserve the
         // milestone branch so commits are not lost.
         if (mergeResult.conflicts.includes("__dirty_working_tree__")) {
+            // Defensively clean merge state — the native path may leave MERGE_HEAD
+            // even when the merge is rejected (#2912).
+            try {
+                const gitDir_ = resolveGitDir(originalBasePath_);
+                for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+                    const p = join(gitDir_, f);
+                    if (existsSync(p))
+                        unlinkSync(p);
+                }
+            }
+            catch { /* best-effort */ }
             // Pop stash before throwing so local work is not lost.
             if (stashed) {
                 try {
@@ -1216,6 +1381,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 }
                 catch { /* stash pop conflict is non-fatal */ }
             }
+            restoreShelter();
             // Restore cwd so the caller is not stranded on the integration branch
             process.chdir(previousCwd);
             // Surface the actual dirty filenames from git stderr instead of
@@ -1253,6 +1419,22 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             }
             // If there are still real code conflicts, escalate
             if (codeConflicts.length > 0) {
+                // Abort merge state so MERGE_HEAD is not left on disk (#2912).
+                // libgit2's merge creates MERGE_HEAD even for squash merges; if left
+                // dangling, subsequent merges fail and doctor reports corrupt state.
+                try {
+                    nativeMergeAbort(originalBasePath_);
+                }
+                catch { /* best-effort */ }
+                try {
+                    const gitDir_ = resolveGitDir(originalBasePath_);
+                    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+                        const p = join(gitDir_, f);
+                        if (existsSync(p))
+                            unlinkSync(p);
+                    }
+                }
+                catch { /* best-effort */ }
                 // Pop stash before throwing so local work is not lost (#2151).
                 if (stashed) {
                     try {
@@ -1264,6 +1446,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                     }
                     catch { /* stash pop conflict is non-fatal */ }
                 }
+                restoreShelter();
                 throw new MergeConflictError(codeConflicts, "squash", milestoneBranch, mainBranch);
             }
         }
@@ -1272,15 +1455,19 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // 9. Commit (handle nothing-to-commit gracefully)
     const commitResult = nativeCommit(originalBasePath_, commitMessage);
     const nothingToCommit = commitResult === null;
-    // 9a. Clean up SQUASH_MSG left by git merge --squash (#1853).
+    // 9a. Clean up merge state files left by git merge --squash (#1853, #2912).
     // git only removes SQUASH_MSG when the commit reads it directly (plain
     // `git commit`).  nativeCommit uses `-F -` (stdin) or libgit2, neither
-    // of which trigger git's SQUASH_MSG cleanup.  If left on disk, doctor
-    // reports `corrupt_merge_state` on every subsequent run.
+    // of which trigger git's SQUASH_MSG cleanup.  MERGE_HEAD is created by
+    // libgit2's merge even in squash mode and is not removed by nativeCommit.
+    // If left on disk, doctor reports `corrupt_merge_state` on every subsequent run.
     try {
-        const squashMsgPath = join(resolveGitDir(originalBasePath_), "SQUASH_MSG");
-        if (existsSync(squashMsgPath))
-            unlinkSync(squashMsgPath);
+        const gitDir_ = resolveGitDir(originalBasePath_);
+        for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+            const p = join(gitDir_, f);
+            if (existsSync(p))
+                unlinkSync(p);
+        }
     }
     catch { /* best-effort */ }
     // 9a-ii. Restore stashed files now that the merge+commit is complete (#2151).
@@ -1340,6 +1527,8 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             }
         }
     }
+    // 9a-iii. Restore sheltered queued milestone directories (#2505).
+    restoreShelter();
     // 9b. Safety check (#1792): if nothing was committed, verify the milestone
     // work is already on the integration branch before allowing teardown.
     // Compare only non-.gsd/ paths — .gsd/ state files diverge normally and

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

@@ -774,6 +774,10 @@ function buildLoopDeps() {
     };
 }
 export async function startAuto(ctx, pi, base, verboseMode, options) {
+    if (s.active) {
+        debugLog("startAuto", { phase: "already-active", skipping: true });
+        return;
+    }
     const requestedStepMode = options?.step ?? false;
     // Escape stale worktree cwd from a previous milestone (#608).
     base = escapeStaleWorktree(base);

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -48,6 +48,30 @@ export async function handleAgentEnd(pi, event, ctx) {
         return;
     const lastMsg = event.messages[event.messages.length - 1];
     if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
+        // Empty content with aborted stopReason is a non-fatal agent stop (the LLM
+        // chose to end without producing output). Only pause on genuine fatal aborts
+        // that carry error context — e.g. errorMessage field or non-empty content
+        // indicating a mid-stream failure. (#2695)
+        const content = "content" in lastMsg ? lastMsg.content : undefined;
+        const hasEmptyContent = Array.isArray(content) && content.length === 0;
+        const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
+        if (hasEmptyContent && !hasErrorMessage) {
+            // Non-fatal: treat as a normal agent end so the loop can continue
+            // instead of entering a stuck re-dispatch cycle.
+            try {
+                resetRetryState(retryState);
+                resolveAgentEnd(event);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                ctx.ui.notify(`Auto-mode error after empty-content abort: ${message}. Stopping auto-mode.`, "error");
+                try {
+                    await pauseAuto(ctx, pi);
+                }
+                catch { /* best-effort */ }
+            }
+            return;
+        }
         await pauseAuto(ctx, pi);
         return;
     }
@@ -57,6 +81,14 @@ export async function handleAgentEnd(pi, event, ctx) {
         const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
         // ── 1. Classify ──────────────────────────────────────────────────────
         const cls = classifyError(errorMsg, explicitRetryAfterMs);
+        // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli)
+        // which use per-user quotas with shorter windows (#2922).
+        if (cls.kind === "rate-limit") {
+            const currentProvider = ctx.model?.provider;
+            if (currentProvider === "openai-codex" || currentProvider === "google-gemini-cli") {
+                cls.retryAfterMs = Math.min(cls.retryAfterMs, 30_000);
+            }
+        }
         // ── 2. Decide & Act ──────────────────────────────────────────────────
         // --- Network errors: same-model retry with backoff ---
         if (cls.kind === "network") {