gsd-pi 2.76.0 → 2.77.0

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

@@ -11,7 +11,7 @@ import { appendEvent } from "./workflow-events.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGates, updateTaskStatus, updateSliceStatus } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGates, updateTaskStatus, updateSliceStatus, insertSlice } from "./gsd-db.js";
 import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -220,12 +220,25 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
     // RESEARCH file. Without this, resolveExpectedArtifactPath returns null and
     // the retry/escalation machinery silently re-dispatches forever.
     //
+    // #4068: Also treat a PARALLEL-BLOCKER placeholder as a terminal completion
+    // so that timeout-recovery can write the blocker, have verifyExpectedArtifact
+    // return true, and let the dispatch loop advance past this unit.  Without
+    // this, the blocker is written but verification still returns false, the unit
+    // is never cleared from unitDispatchCount, and on the next iteration the
+    // dispatch rule (which correctly skips parallel-research when PARALLEL-BLOCKER
+    // exists) returns null — leaving the loop stuck re-deriving indefinitely.
+    //
     // NOTE: this predicate mirrors the dispatch rule at
     // auto-dispatch.ts parallel-research-slices — keep the two in sync.
     if (unitType === "research-slice" && unitId.endsWith("/parallel-research")) {
         const { milestone: mid } = parseUnitId(unitId);
         if (!mid)
             return false;
+        // #4068: PARALLEL-BLOCKER written by timeout-recovery is a terminal state.
+        const blockerPath = resolveExpectedArtifactPath(unitType, unitId, base);
+        if (blockerPath && existsSync(blockerPath)) {
+            return true;
+        }
         const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
         if (!roadmapFile || !existsSync(roadmapFile)) {
             logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap missing`);
@@ -497,6 +510,24 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
                 logWarning("recovery", `appendEvent failed for slice recovery: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
+        // Insert a placeholder complete slice so deriveState sees activeMilestoneSlices.length > 0
+        // and exits the pre-planning phase. Without this, activeMilestoneSlices stays empty
+        // after the blocker ROADMAP.md is written, causing deriveState to return phase:'pre-planning'
+        // indefinitely and re-dispatching plan-milestone in an infinite loop (#4378).
+        if (unitType === "plan-milestone" && mid) {
+            try {
+                insertSlice({ id: "S00-blocker", milestoneId: mid, title: "Blocker placeholder — planning failed", status: "complete", sequence: 0 });
+            }
+            catch (e) {
+                logWarning("recovery", `insertSlice placeholder failed for plan-milestone recovery: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            try {
+                appendEvent(base, { cmd: "plan-milestone", params: { milestoneId: mid }, ts, actor: "system", trigger_reason: "blocker-placeholder-recovery" });
+            }
+            catch (e) {
+                logWarning("recovery", `appendEvent failed for plan-milestone recovery: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
     }
     return diagnoseExpectedArtifact(unitType, unitId, base);
 }

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

@@ -30,8 +30,7 @@ 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 { hideFooter } from "./auto-dashboard.js";
+import { isDbAvailable, getMilestone, openDatabase, getDbStatus } from "./gsd-db.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync, } from "node:fs";
@@ -190,8 +189,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     //
     // Precedence:
     // 1) Explicit session override via /gsd model (this session)
-    // 2) GSD model preferences from PREFERENCES.md (validated against live auth)
-    // 3) Current session model from settings/session restore (if provider ready)
+    // 2) Current session model from settings/session restore (if provider ready)
+    // 3) GSD model preferences from PREFERENCES.md (validated against live auth)
     //
     // This preserves #3517 defaults while honoring explicit runtime model
     // selection for subsequent /gsd runs in the same session.
@@ -224,11 +223,14 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         }
     }
     const sessionModelReady = ctx.model && ctx.modelRegistry.isProviderRequestReady(ctx.model.provider);
+    const currentSessionModel = (sessionModelReady && ctx.model)
+        ? { provider: ctx.model.provider, id: ctx.model.id }
+        : null;
+    const startThinkingSnapshot = pi.getThinkingLevel();
     const startModelSnapshot = manualSessionOverride
+        ?? currentSessionModel
         ?? validatedPreferredModel
-        ?? (sessionModelReady && ctx.model
-            ? { provider: ctx.model.provider, id: ctx.model.id }
-            : null);
+        ?? null;
     try {
         // Validate GSD_PROJECT_ID early so the user gets immediate feedback
         const customProjectId = process.env.GSD_PROJECT_ID;
@@ -244,7 +246,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // the parent git root). See #2393 and related issue.
         const hasLocalGit = existsSync(join(base, ".git"));
         if (!hasLocalGit || isInheritedRepo(base)) {
-            const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
+            const mainBranch = loadEffectiveGSDPreferences(base)?.preferences?.git?.main_branch || "main";
             nativeInit(base, mainBranch);
         }
         // Migrate legacy in-project .gsd/ to external state directory.
@@ -260,7 +262,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // Ensure .gitignore has baseline patterns.
         // ensureGitignore checks for git-tracked .gsd/ files and skips the
         // ".gsd" pattern if the project intentionally tracks .gsd/ in git.
-        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+        const gitPrefs = loadEffectiveGSDPreferences(base)?.preferences?.git;
         const manageGitignore = gitPrefs?.manage_gitignore;
         ensureGitignore(base, { manageGitignore });
         if (manageGitignore !== false)
@@ -286,7 +288,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             prepareWorkflowMcpForProject(ctx, base);
         }
         // Initialize GitServiceImpl
-        s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences(base)?.preferences?.git ?? {});
         // ── Debug mode ──
         if (!isDebugEnabled() && process.env.GSD_DEBUG === "1") {
             enableDebug(base);
@@ -319,7 +321,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // was lost due to session ending between completion and teardown.
         // Must run after DB open and before worktree entry.
         try {
-            const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode());
+            const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode(base));
             for (const msg of auditResult.recovered) {
                 ctx.ui.notify(`Orphan audit: ${msg}`, "info");
             }
@@ -337,7 +339,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         let state = await deriveState(base);
         // Stale worktree state recovery (#654)
         if (state.activeMilestone &&
-            shouldUseWorktreeIsolation() &&
+            shouldUseWorktreeIsolation(base) &&
             !detectWorktreeName(base)) {
             const wtPath = getAutoWorktreePath(base, state.activeMilestone.id);
             if (wtPath) {
@@ -352,7 +354,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         let hasSurvivorBranch = false;
         if (state.activeMilestone &&
             (state.phase === "pre-planning" || state.phase === "complete") &&
-            getIsolationMode() !== "none" &&
+            getIsolationMode(base) !== "none" &&
             !detectWorktreeName(base) &&
             !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)) {
             const milestoneBranch = `milestone/${state.activeMilestone.id}`;
@@ -413,29 +415,15 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 }
                 const { showSmartEntry } = await import("./guided-flow.js");
                 await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
-                invalidateAllCaches();
-                const postState = await deriveState(base);
-                if (postState.activeMilestone &&
-                    postState.phase !== "complete" &&
-                    postState.phase !== "pre-planning") {
-                    s.consecutiveCompleteBootstraps = 0; // Successfully advanced past "complete"
-                    state = postState;
-                }
-                else if (postState.activeMilestone &&
-                    postState.phase === "pre-planning") {
-                    const contextFile = resolveMilestoneFile(base, postState.activeMilestone.id, "CONTEXT");
-                    const hasContext = !!(contextFile && (await loadFile(contextFile)));
-                    if (hasContext) {
-                        state = postState;
-                    }
-                    else {
-                        ctx.ui.notify("Discussion completed but no milestone context was written. Run /gsd to try the discussion again, or /gsd auto after creating the milestone manually.", "warning");
-                        return releaseLockAndReturn();
-                    }
-                }
-                else {
-                    return releaseLockAndReturn();
-                }
+                // showSmartEntry dispatches via pi.sendMessage() which is fire-and-forget:
+                // it queues the message and returns immediately, before the LLM turn runs.
+                // Checking postState here would always see the pre-dispatch state, causing
+                // the premature "Discussion completed but..." warning (#3420).
+                //
+                // checkAutoStartAfterDiscuss (in guided-flow.ts) already handles re-entering
+                // auto-mode by calling startAutoDetached after the discussion completes.
+                // Release the lock and let the async dispatch proceed.
+                return releaseLockAndReturn();
             }
             // Active milestone exists but has no roadmap
             if (state.phase === "pre-planning") {
@@ -445,15 +433,16 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 if (!hasContext) {
                     const { showSmartEntry } = await import("./guided-flow.js");
                     await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
-                    invalidateAllCaches();
-                    const postState = await deriveState(base);
-                    if (postState.activeMilestone && postState.phase !== "pre-planning") {
-                        state = postState;
-                    }
-                    else {
-                        ctx.ui.notify("Discussion completed but milestone context is still missing. Run /gsd to try again.", "warning");
-                        return releaseLockAndReturn();
-                    }
+                    // showSmartEntry dispatches via pi.sendMessage() which is fire-and-forget:
+                    // it queues the message and returns immediately, before the LLM turn runs.
+                    // Checking postState here fires before the LLM has had a turn, so the
+                    // pre-planning phase would still appear unchanged and a premature warning
+                    // would be emitted (#3420).
+                    //
+                    // checkAutoStartAfterDiscuss (in guided-flow.ts) already handles re-entering
+                    // auto-mode by calling startAutoDetached after the discussion completes.
+                    // Release the lock and let the async dispatch proceed.
+                    return releaseLockAndReturn();
                 }
             }
             // Active milestone has CONTEXT-DRAFT but no full context — needs discussion
@@ -506,13 +495,14 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         s.pendingQuickTasks = [];
         s.currentUnit = null;
         s.currentMilestoneId = state.activeMilestone?.id ?? null;
-        s.originalModelId = ctx.model?.id ?? null;
-        s.originalModelProvider = ctx.model?.provider ?? null;
+        s.originalModelId = startModelSnapshot?.id ?? ctx.model?.id ?? null;
+        s.originalModelProvider = startModelSnapshot?.provider ?? ctx.model?.provider ?? null;
+        s.originalThinkingLevel = startThinkingSnapshot ?? null;
         // Register SIGTERM handler
         registerSigtermHandler(base);
         // Capture integration branch
         if (s.currentMilestoneId) {
-            if (getIsolationMode() !== "none") {
+            if (getIsolationMode(base) !== "none") {
                 captureIntegrationBranch(base, s.currentMilestoneId);
             }
             setActiveMilestoneId(base, s.currentMilestoneId);
@@ -520,7 +510,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // Guard against stale milestone branch when isolation:none (#3613).
         // A prior session with isolation:branch/worktree may have left HEAD on
         // milestone/<MID>. Auto-checkout back to the integration branch.
-        if (getIsolationMode() === "none" && nativeIsRepo(base)) {
+        if (getIsolationMode(base) === "none" && nativeIsRepo(base)) {
             try {
                 const currentBranch = nativeGetCurrentBranch(base);
                 if (currentBranch.startsWith("milestone/")) {
@@ -548,7 +538,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             return symlinkRe.test(p);
         };
         if (s.currentMilestoneId &&
-            getIsolationMode() !== "none" &&
+            getIsolationMode(base) !== "none" &&
             !detectWorktreeName(base) &&
             !isUnderGsdWorktrees(base)) {
             buildResolver().enterMilestone(s.currentMilestoneId, {
@@ -593,8 +583,21 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // call returns "db_unavailable", triggering artifact-retry which
         // re-dispatches the same task — producing an infinite loop (#2419).
         if (existsSync(gsdDbPath) && !isDbAvailable()) {
-            ctx.ui.notify("SQLite database exists but failed to open. Auto-mode cannot proceed without a working database provider. " +
-                "Check for corrupt gsd.db or missing native SQLite bindings.", "error");
+            const dbStatus = getDbStatus();
+            const phaseHint = dbStatus.lastPhase === "open"
+                ? "The database file could not be opened"
+                : dbStatus.lastPhase === "initSchema"
+                    ? "The database schema could not be initialized"
+                    : dbStatus.lastPhase === "vacuum-recovery"
+                        ? "Corruption recovery (VACUUM) failed"
+                        : dbStatus.attempted
+                            ? "The database could not be opened (phase unknown)"
+                            : "The database provider could not be loaded";
+            const errorDetail = dbStatus.lastError ? ` (${dbStatus.lastError.message})` : "";
+            const providerHint = dbStatus.provider
+                ? ` Provider: ${dbStatus.provider}.`
+                : " No SQLite provider available — check Node >= 22 or install better-sqlite3.";
+            ctx.ui.notify(`SQLite database exists but failed to open: ${gsdDbPath}. ${phaseHint}${errorDetail}.${providerHint}`, "error");
             return releaseLockAndReturn();
         }
         // Initialize metrics
@@ -608,6 +611,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 id: startModelSnapshot.id,
             };
         }
+        s.autoModeStartThinkingLevel = startThinkingSnapshot ?? null;
         s.manualSessionModelOverride = manualSessionOverride ?? null;
         // Apply worker model override from parallel orchestrator (#worker-model).
         // GSD_WORKER_MODEL is injected by the coordinator when parallel.worker_model
@@ -628,13 +632,10 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // Snapshot installed skills
-        if (resolveSkillDiscoveryMode() !== "off") {
+        if (resolveSkillDiscoveryMode(base) !== "off") {
             snapshotSkills();
         }
         ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
-        ctx.ui.setFooter(hideFooter);
-        // Hide gsd-health during AUTO — gsd-progress is the single source of truth
-        // for last-commit / cost / health signal while auto is running.
         ctx.ui.setWidget("gsd-health", undefined);
         const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
         const pendingCount = (state.registry ?? []).filter((m) => m.status !== "complete" && m.status !== "parked").length;
@@ -656,7 +657,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // FlatRateContext used by selectAndApplyModel so user-declared
         // flat-rate providers and externalCli auto-detection are respected.
         const { isFlatRateProvider, buildFlatRateContext } = await import("./auto-model-selection.js");
-        const bannerPrefs = loadEffectiveGSDPreferences()?.preferences;
+        const bannerPrefs = loadEffectiveGSDPreferences(base)?.preferences;
         const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
         const effectivelyEnabled = routingConfig.enabled
             && (routingConfig.allow_flat_rate_providers

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

@@ -396,6 +396,39 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
         if (postExecBlockingFailure) {
             result.passed = false;
         }
+        // Emit Layer 2 verify_result event with the final, post-exec verdict so hooks
+        // see the authoritative pass/fail and the complete set of failures.
+        try {
+            const { emitVerifyResult } = await import("./hook-emitter.js");
+            const checkFailures = result.checks
+                .filter((c) => c.exitCode !== 0)
+                .map((c) => ({
+                kind: "gate",
+                message: `${c.command} exited ${c.exitCode}${c.stderr ? `: ${c.stderr.slice(0, 200)}` : ""}`,
+            }));
+            const runtimeFailures = (result.runtimeErrors ?? [])
+                .filter((e) => e.blocking)
+                .map((e) => ({
+                kind: "other",
+                message: `[${e.source}] ${e.message.slice(0, 200)}`,
+            }));
+            const postExecFailures = (postExecChecks ?? [])
+                .filter((c) => !c.passed)
+                .map((c) => ({
+                kind: "other",
+                message: `[${c.category}] ${c.target}: ${c.message}`,
+            }));
+            await emitVerifyResult({
+                passed: result.passed,
+                failures: [...checkFailures, ...runtimeFailures, ...postExecFailures],
+                unitType: s.currentUnit.type,
+                unitId: s.currentUnit.id,
+                cwd: s.basePath,
+            });
+        }
+        catch (hookErr) {
+            logWarning("engine", `verify_result hook emission failed: ${hookErr.message}`);
+        }
         // ── Auto-fix retry logic ──
         if (result.passed) {
             s.verificationRetryCount.delete(s.currentUnit.id);

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

@@ -180,14 +180,6 @@ function clearProjectRootStateFiles(basePath, milestoneId) {
         }
     }
 }
-function isProjectGsdSymlink(basePath) {
-    try {
-        return lstatSyncFn(join(basePath, ".gsd")).isSymbolicLink();
-    }
-    catch {
-        return false;
-    }
-}
 // ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
 /** Patterns for machine-generated build artifacts that can be safely
  * auto-resolved by accepting --theirs during merge. These files are
@@ -1429,50 +1421,15 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             });
         }
     }
-    // 7. Stash any pre-existing dirty files so the squash merge is not
-    //    blocked by unrelated local changes (#2151).  clearProjectRootStateFiles
-    //    only removes untracked .gsd/ files; tracked dirty files elsewhere (e.g.
-    //    .planning/work-state.json with stash conflict markers) are invisible to
-    //    that cleanup but will cause `git merge --squash` to reject.
-    let stashed = false;
-    try {
-        const status = execFileSync("git", ["status", "--porcelain"], {
-            cwd: originalBasePath_,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        }).trim();
-        if (status) {
-            // 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.
-            //
-            // When `.gsd` itself is a symlink, Git rejects pathspecs below it
-            // ("beyond a symbolic link"). In that layout, exclude the whole symlink
-            // and keep stashing real project files that could block the merge.
-            const stashPathspecs = isProjectGsdSymlink(originalBasePath_)
-                ? [".", ":(exclude).gsd"]
-                : [":(exclude).gsd/milestones"];
-            execFileSync("git", [
-                "stash", "push", "--include-untracked",
-                "-m", `gsd: pre-merge stash for ${milestoneId}`,
-                "--", ...stashPathspecs,
-            ], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
-            stashed = true;
-        }
-    }
-    catch (err) {
-        // Stash failure is non-fatal — proceed without stash and let the merge
-        // report the dirty tree if it fails.
-        logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    // 7a. Shelter queued milestone directories before the squash merge (#2505).
+    // 7. 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.
+    //
+    // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
+    // does not sweep queued CONTEXT files into the stash. If stash pop later
+    // fails, files trapped inside the stash are permanently lost (#2505).
     const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
     const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
     const shelteredDirs = [];
@@ -1526,6 +1483,31 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         // Non-fatal — proceed with merge; untracked files may block it
         logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    // 7a. Stash pre-existing dirty files so the squash merge is not blocked by
+    //     unrelated local changes (#2151). Includes untracked files to handle
+    //     locally-added files that conflict with tracked files on the milestone
+    //     branch. Passing NO pathspec lets git skip gitignored paths silently;
+    //     adding an explicit pathspec trips a `git add`-style fatal on ignored
+    //     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.
+    let stashed = false;
+    try {
+        const status = execFileSync("git", ["status", "--porcelain"], {
+            cwd: originalBasePath_,
+            stdio: ["ignore", "pipe", "pipe"],
+            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" });
+            stashed = true;
+        }
+    }
+    catch (err) {
+        // Stash failure is non-fatal — proceed without stash and let the merge
+        // report the dirty tree if it fails.
+        logWarning("worktree", `git stash 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
@@ -1761,16 +1743,32 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // When a milestone only produced .gsd/ metadata (summaries, roadmaps) but no
     // real code, the user sees "milestone complete" but nothing changed in their
     // codebase. Surface this so the caller can warn the user.
+    //
+    // Bug #4385 fix: use `git diff-tree --root` instead of `git diff HEAD~1 HEAD`.
+    // `HEAD~1` does not exist on initial commits and is unreliable on shallow clones
+    // and merge commits. `diff-tree --root` handles all three cases correctly.
+    // The empty-tree hash (4b825dc…) is the universal fallback for refs that don't exist.
+    const GIT_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
     let codeFilesChanged = false;
     if (!nothingToCommit) {
         try {
-            const mergedFiles = nativeDiffNumstat(originalBasePath_, "HEAD~1", "HEAD");
-            codeFilesChanged = mergedFiles.some((entry) => !entry.path.startsWith(".gsd/"));
+            const diffTreeOutput = execFileSync("git", ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+            const mergedFiles = diffTreeOutput ? diffTreeOutput.split("\n").filter(Boolean) : [];
+            codeFilesChanged = mergedFiles.some((f) => !f.startsWith(".gsd/"));
         }
         catch (e) {
-            // If HEAD~1 doesn't exist (first commit), assume code was changed
-            logWarning("worktree", `diff numstat failed (assuming code changed): ${e.message}`);
-            codeFilesChanged = true;
+            // diff-tree failed (e.g. unborn HEAD in a brand-new repo) — fall back to
+            // comparing against the empty tree so initial-commit repos still report changes.
+            try {
+                const fallbackOutput = execFileSync("git", ["diff", "--name-only", GIT_EMPTY_TREE, "HEAD"], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+                const fallbackFiles = fallbackOutput ? fallbackOutput.split("\n").filter(Boolean) : [];
+                codeFilesChanged = fallbackFiles.some((f) => !f.startsWith(".gsd/"));
+            }
+            catch {
+                // Truly unable to determine — assume code was changed to avoid silent data loss
+                logWarning("worktree", `diff-tree and empty-tree fallback both failed (assuming code changed): ${e.message}`);
+                codeFilesChanged = true;
+            }
         }
     }
     // 10. Auto-push if enabled