gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.1b44e695b

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

@@ -10,7 +10,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import { isMilestoneComplete } from "./state.js";
-import { runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
+import { runVerificationGate, runVerificationGateForTargets, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
 import { runPostExecutionChecks } from "./post-execution-checks.js";
@@ -18,8 +18,69 @@ import { join } from "node:path";
 import { resolveUokFlags } from "./uok/flags.js";
 import { UokGateRunner } from "./uok/gate-runner.js";
 import { verificationRetryKey } from "./auto/verification-retry-policy.js";
-function isInfraVerificationFailure(stderr) {
-    return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(stderr);
+import { decideVerificationVerdict } from "./verification-verdict.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import { getSlice } from "./gsd-db.js";
+import { getLedger } from "./metrics.js";
+import { getUnitCostSpikeAction } from "./auto-budget.js";
+function getCurrentUnitCostStats(unitId) {
+    const ledger = getLedger();
+    if (!ledger || !Array.isArray(ledger.units) || ledger.units.length === 0) {
+        return { unitCostUsd: 0, rollingAvgUsd: 0 };
+    }
+    let unitCostUsd = 0;
+    let totalCost = 0;
+    let totalUnits = 0;
+    for (const unit of ledger.units) {
+        const cost = typeof unit?.cost === "number" ? unit.cost : 0;
+        if (!Number.isFinite(cost) || cost < 0)
+            continue;
+        totalCost += cost;
+        totalUnits++;
+        if (unit?.id === unitId)
+            unitCostUsd += cost;
+    }
+    return {
+        unitCostUsd,
+        rollingAvgUsd: totalUnits > 0 ? totalCost / totalUnits : 0,
+    };
+}
+function resolveVerificationTargets(basePath, prefs, task, slice) {
+    const registry = createRepositoryRegistryFromPreferences(basePath, prefs);
+    const explicitIds = task?.target_repositories?.length
+        ? task.target_repositories
+        : slice?.target_repositories?.length
+            ? slice.target_repositories
+            : null;
+    const requestedIds = explicitIds ?? ["project"];
+    const targets = [];
+    const seen = new Set();
+    for (const id of requestedIds) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const repo = registry.byId.get(id);
+        if (!repo) {
+            if (explicitIds) {
+                throw new Error(`unknown verification target repository: ${id}`);
+            }
+            continue;
+        }
+        targets.push({
+            id: repo.id,
+            cwd: repo.root,
+            // Top-level verification commands override per-repo defaults.
+            preferenceCommands: prefs?.verification_commands?.length
+                ? undefined
+                : repo.verification,
+        });
+    }
+    if (!explicitIds && targets.length === 0) {
+        const project = registry.byId.get("project");
+        if (project)
+            targets.push({ id: "project", cwd: project.root });
+    }
+    return targets;
 }
 /**
  * Post-unit guard for `validate-milestone` units (#4094).
@@ -67,12 +128,25 @@ async function runValidateMilestonePostCheck(vctx, pauseAuto) {
     const { milestone: mid } = parseUnitId(s.currentUnit.id);
     if (!mid)
         return "continue";
+    const setToolFailureRetry = (message) => {
+        const retryKey = verificationRetryKey(s.currentUnit.type, s.currentUnit.id);
+        const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1;
+        s.verificationRetryCount.set(retryKey, attempt);
+        s.pendingVerificationRetry = {
+            unitId: s.currentUnit.id,
+            failureContext: message,
+            attempt,
+        };
+        return "retry";
+    };
     const validationFile = resolveMilestoneFile(s.basePath, mid, "VALIDATION");
-    if (!validationFile)
-        return "continue";
+    if (!validationFile) {
+        return setToolFailureRetry("You must call gsd_validate_milestone to persist the validation results. No VALIDATION.md was created.");
+    }
     const validationContent = await loadFile(validationFile);
-    if (!validationContent)
-        return "continue";
+    if (!validationContent) {
+        return setToolFailureRetry("You must call gsd_validate_milestone to persist the validation results. VALIDATION.md exists but is empty.");
+    }
     const verdict = extractVerdict(validationContent);
     if (verdict !== "needs-remediation") {
         await persistMilestoneValidationGate("pass", "none", `milestone validation verdict is ${verdict}; no remediation loop risk`, "", mid);
@@ -128,7 +202,7 @@ async function countIncompleteSlices(basePath, milestoneId) {
 /**
  * Run the verification gate for the current execute-task unit.
  * Returns:
- * - "continue" — gate passed (or no checks configured), proceed normally
+ * - "continue" — host-owned verification passed, proceed normally
  * - "retry" — gate failed with retries remaining, s.pendingVerificationRetry set for loop re-iteration
  * - "pause" — gate failed with retries exhausted, pauseAuto already called
  */
@@ -150,17 +224,28 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
         // Read task plan verify field
         const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
         let taskPlanVerify;
+        let taskRow = null;
+        let sliceRow = null;
         if (mid && sid && tid) {
             if (isDbAvailable()) {
-                taskPlanVerify = getTask(mid, sid, tid)?.verify;
+                taskRow = getTask(mid, sid, tid);
+                sliceRow = getSlice(mid, sid);
+                taskPlanVerify = taskRow?.verify;
             }
             // When DB unavailable, taskPlanVerify stays undefined — gate runs without task-specific checks
         }
-        const result = runVerificationGate({
-            cwd: s.basePath,
-            preferenceCommands: prefs?.verification_commands,
-            taskPlanVerify,
-        });
+        const verificationTargets = resolveVerificationTargets(s.basePath, prefs, taskRow, sliceRow);
+        const result = verificationTargets.length <= 1
+            ? runVerificationGate({
+                cwd: verificationTargets[0]?.cwd ?? s.basePath,
+                preferenceCommands: prefs?.verification_commands ?? verificationTargets[0]?.preferenceCommands,
+                taskPlanVerify,
+            })
+            : runVerificationGateForTargets({
+                targets: verificationTargets,
+                preferenceCommands: prefs?.verification_commands,
+                taskPlanVerify,
+            });
         // Capture runtime errors
         const runtimeErrors = await captureRuntimeErrors();
         if (runtimeErrors.length > 0) {
@@ -178,6 +263,10 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 process.stderr.write(`  [${w.severity}] ${w.name}: ${w.title}\n`);
             }
         }
+        const verdict = decideVerificationVerdict(s.currentUnit.type, result);
+        if (!verdict.passed) {
+            result.passed = false;
+        }
         if (uokFlags.gates) {
             const gateRunner = new UokGateRunner();
             gateRunner.register({
@@ -190,10 +279,12 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                         : "verification",
                     rationale: result.passed
                         ? "verification checks passed"
-                        : "verification checks failed",
+                        : verdict.reason === "no-host-checks"
+                            ? "no runnable host-owned verification checks discovered"
+                            : "verification checks failed",
                     findings: result.passed
                         ? ""
-                        : formatFailureContext(result),
+                        : verdict.failureContext || formatFailureContext(result),
                 }),
             });
             await gateRunner.run("verification-gate", {
@@ -251,7 +342,11 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                     }
                     else {
                         const nextAttempt = attempt + 1;
-                        writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, nextAttempt, maxRetries);
+                        const includeRetryMetadata = !result.passed &&
+                            verdict.retryable &&
+                            autoFixEnabled &&
+                            nextAttempt <= maxRetries;
+                        writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, includeRetryMetadata ? nextAttempt : undefined, includeRetryMetadata ? maxRetries : undefined);
                     }
                 }
             }
@@ -259,18 +354,6 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 logWarning("engine", `verification-evidence write error: ${evidenceErr.message}`);
             }
         }
-        const advisoryFailure = !result.passed &&
-            (result.discoverySource === "package-json" ||
-                result.checks.some((check) => isInfraVerificationFailure(check.stderr)));
-        if (advisoryFailure) {
-            s.verificationRetryCount.delete(retryKey);
-            s.verificationRetryFailureHashes.delete(retryKey);
-            s.pendingVerificationRetry = null;
-            ctx.ui.notify(result.discoverySource === "package-json"
-                ? "Verification failed in auto-discovered package.json checks — treating as advisory."
-                : "Verification failed due to infrastructure/runtime environment issues — treating as advisory.", "warning");
-            return "continue";
-        }
         // ── Post-execution checks (run after main verification passes for execute-task units) ──
         let postExecChecks;
         let postExecBlockingFailure = false;
@@ -280,8 +363,7 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
             const postEnabled = prefs?.enhanced_verification_post !== false; // default true
             if (enhancedEnabled && postEnabled && isDbAvailable()) {
                 try {
-                    // Get the completed task from DB
-                    const taskRow = getTask(mid, sid, tid);
+                    // Reuse the already-loaded task row for post-execution checks.
                     if (taskRow && taskRow.key_files && taskRow.key_files.length > 0) {
                         // Get all tasks in the slice
                         const allTasks = getSliceTasks(mid, sid);
@@ -430,6 +512,15 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
             s.pendingVerificationRetry = null;
             return "continue";
         }
+        else if (verdict.reason === "no-host-checks") {
+            s.verificationRetryCount.delete(retryKey);
+            s.verificationRetryFailureHashes.delete(retryKey);
+            s.pendingVerificationRetry = null;
+            ctx.ui.notify("Verification gate FAILED — no runnable host-owned verification checks were discovered. Pausing for human review.", "error");
+            process.stderr.write(`verification-gate: ${verdict.failureContext}\n`);
+            await pauseAuto(ctx, pi);
+            return "pause";
+        }
         else if (postExecBlockingFailure) {
             // Post-execution failures are cross-task consistency issues — retrying the same task won't fix them.
             // Skip retry and pause immediately for human review.
@@ -441,11 +532,31 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
             return "pause";
         }
         else if (autoFixEnabled && attempt + 1 <= maxRetries) {
+            const { unitCostUsd, rollingAvgUsd } = getCurrentUnitCostStats(s.currentUnit.id);
+            const perUnitCapUsd = typeof prefs?.per_unit_cost_cap_usd === "number" && Number.isFinite(prefs.per_unit_cost_cap_usd) && prefs.per_unit_cost_cap_usd > 0
+                ? prefs.per_unit_cost_cap_usd
+                : 5.0;
+            if (unitCostUsd >= perUnitCapUsd) {
+                s.verificationRetryCount.delete(retryKey);
+                s.verificationRetryFailureHashes.delete(retryKey);
+                s.pendingVerificationRetry = null;
+                ctx.ui.notify(`Unit ${s.currentUnit.id} hit per-unit cap $${perUnitCapUsd.toFixed(2)} — pausing auto-mode.`, "error");
+                await pauseAuto(ctx, pi);
+                return "pause";
+            }
+            if (getUnitCostSpikeAction(unitCostUsd, rollingAvgUsd, 3.0) === "pause") {
+                s.verificationRetryCount.delete(retryKey);
+                s.verificationRetryFailureHashes.delete(retryKey);
+                s.pendingVerificationRetry = null;
+                ctx.ui.notify(`Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) — pausing auto-mode.`, "error");
+                await pauseAuto(ctx, pi);
+                return "pause";
+            }
             const nextAttempt = attempt + 1;
             s.verificationRetryCount.set(retryKey, nextAttempt);
             s.pendingVerificationRetry = {
                 unitId: s.currentUnit.id,
-                failureContext: formatFailureContext(result),
+                failureContext: verdict.failureContext || formatFailureContext(result),
                 attempt: nextAttempt,
             };
             const failedCmds = result.checks
@@ -475,9 +586,10 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
         }
     }
     catch (err) {
-        // Gate errors are non-fatal
         logWarning("engine", `verification-gate error: ${err.message}`);
-        return "continue";
+        ctx.ui.notify(`Verification gate errored before producing an authoritative verdict: ${err.message}`, "error");
+        await pauseAuto(ctx, pi);
+        return "pause";
     }
 }
 /**

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

@@ -16,7 +16,7 @@ import { gsdRoot, resolveGsdPathContract } from "./paths.js";
 import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
-import { MergeConflictError, createDraftPR, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
+import { MergeConflictError, createDraftPR, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { buildPrEvidence } from "./pr-evidence.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -173,7 +173,18 @@ function gitPathspecForWorktreePath(basePath, targetPath) {
     let base = basePath;
     let target = targetPath;
     try {
-        base = realpathSync.native(basePath);
+        base = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        }).trim() || basePath;
+    }
+    catch {
+        /* keep original */
+        void base;
+    }
+    try {
+        base = realpathSync.native(base);
     }
     catch {
         /* keep original */
@@ -191,6 +202,9 @@ function gitPathspecForWorktreePath(basePath, targetPath) {
         return null;
     return rel.replaceAll("\\", "/");
 }
+export function _gitPathspecForWorktreePath(basePath, targetPath) {
+    return gitPathspecForWorktreePath(basePath, targetPath);
+}
 function gitRemoteExists(basePath, remote) {
     try {
         execFileSync("git", ["remote", "get-url", remote], {
@@ -204,6 +218,52 @@ function gitRemoteExists(basePath, remote) {
         return false;
     }
 }
+function findRegularMergeChangedPaths(basePath, milestoneBranch, mainBranch) {
+    const changedPaths = new Set();
+    let mergeLog = "";
+    try {
+        mergeLog = execFileSync("git", ["rev-list", "--merges", "--parents", mainBranch], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch (err) {
+        logWarning("worktree", `regular merge lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        return changedPaths;
+    }
+    for (const line of mergeLog.split("\n").filter(Boolean)) {
+        const [mergeCommit, firstParent, ...otherParents] = line.split(" ");
+        if (!mergeCommit || !firstParent || otherParents.length === 0)
+            continue;
+        const mergedMilestone = otherParents.some((parent) => {
+            try {
+                return nativeIsAncestor(basePath, milestoneBranch, parent);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!mergedMilestone)
+            continue;
+        try {
+            const output = execFileSync("git", ["diff", "--name-only", firstParent, mergeCommit], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            }).trim();
+            for (const path of output.split("\n").filter(Boolean)) {
+                if (!path.startsWith(".gsd/"))
+                    changedPaths.add(path);
+            }
+        }
+        catch (err) {
+            logWarning("worktree", `regular merge diff lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return changedPaths;
+    }
+    return changedPaths;
+}
 function clearProjectRootStateFiles(basePath, milestoneId) {
     const gsdDir = gsdRoot(basePath);
     // Phase C pt 2: auto.lock removed from this list — the file is gone
@@ -530,8 +590,9 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
     // If both resolve to the same directory (symlink), no sync needed
     if (isSamePath(mainGsd, wtGsd))
         return { synced };
-    if (!existsSync(mainGsd) || !existsSync(wtGsd))
+    if (!existsSync(mainGsd))
         return { synced };
+    mkdirSync(wtGsd, { recursive: true });
     // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE, etc.)
     for (const f of ROOT_STATE_FILES) {
         const src = join(mainGsd, f);
@@ -810,7 +871,63 @@ export function enterBranchModeForMilestone(basePath, milestoneId) {
             reused: true,
         });
     }
-    nativeCheckoutBranch(basePath, branch);
+    checkoutBranchWithStashGuard(basePath, branch, `enter-branch-mode:${milestoneId}`);
+}
+export function checkoutBranchWithStashGuard(basePath, branch, reason) {
+    let stashMarker = null;
+    let stashed = false;
+    const status = nativeWorkingTreeStatus(basePath).trim();
+    if (status.length > 0) {
+        stashMarker = `gsd-checkout-stash:${reason}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+        const stashListBefore = execFileSync("git", ["stash", "list"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: checkout stash [${stashMarker}]`], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        const stashListAfter = execFileSync("git", ["stash", "list"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        stashed = stashListAfter !== stashListBefore;
+    }
+    // Checkout and stash-restore are split so we can distinguish two failure
+    // modes: (a) checkout failed → HEAD did not move, restore stash and rethrow;
+    // (b) checkout succeeded but stash pop failed → HEAD moved to `branch` but
+    // the working-tree changes remain in the stash list. We surface a distinct
+    // error in case (b) so callers don't assume the branch switch was rolled back.
+    try {
+        nativeCheckoutBranch(basePath, branch);
+    }
+    catch (checkoutErr) {
+        if (stashed) {
+            try {
+                popStashByRef(basePath, stashMarker);
+            }
+            catch (restoreErr) {
+                logWarning("worktree", `git stash pop failed during checkout restore: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+            }
+        }
+        throw checkoutErr;
+    }
+    if (stashed) {
+        try {
+            popStashByRef(basePath, stashMarker);
+        }
+        catch (popErr) {
+            const msg = popErr instanceof Error ? popErr.message : String(popErr);
+            const wrapped = new Error(`checkout to '${branch}' succeeded but stash restore failed; working tree changes remain in the stash list. Original error: ${msg}`);
+            const ref = popErr?.stashRef;
+            if (ref)
+                wrapped.stashRef = ref;
+            throw wrapped;
+        }
+    }
 }
 // ─── Public API ────────────────────────────────────────────────────────────
 /**
@@ -1358,18 +1475,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // for any further cwd movement on the error path.
     const previousCwd = process.cwd();
     process.chdir(originalBasePath_);
-    // 4. Resolve integration branch — prefer milestone metadata, then preferences,
-    //    then auto-detect (origin/HEAD → main → master → current). Never hardcode
-    //    "main": repos using "master" or a custom default branch would fail at
-    //    checkout and leave the user with a broken merge state (#1668).
+    // 4. Resolve integration branch via shared resolver so stale/invalid
+    //    milestone metadata can recover to configured/detected fallbacks.
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-    const integrationBranch = readIntegrationBranch(originalBasePath_, milestoneId);
-    // Validate prefs.main_branch exists before using it — a stale preference
-    // (e.g. "master" when repo uses "main") causes merge failure (#3589).
-    const validatedPrefBranch = prefs.main_branch && nativeBranchExists(originalBasePath_, prefs.main_branch)
-        ? prefs.main_branch
-        : undefined;
-    const mainBranch = integrationBranch ?? validatedPrefBranch ?? nativeDetectMainBranch(originalBasePath_);
+    const branchResolution = resolveMilestoneIntegrationBranch(originalBasePath_, milestoneId, prefs);
+    const mainBranch = branchResolution.effectiveBranch ?? nativeDetectMainBranch(originalBasePath_);
     // Fail closed when the resolved integration branch is the milestone branch
     // itself (#5024). Stale or corrupt metadata (e.g. integrationBranch recorded
     // as "milestone/<MID>") would otherwise let the squash merge resolve to a
@@ -1380,9 +1490,8 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     if (normalizeLocalBranchRef(mainBranch) === milestoneBranch) {
         process.chdir(previousCwd);
         throw new GSDError(GSD_GIT_ERROR, `Resolved integration branch "${mainBranch}" is the same ref as milestone branch ` +
-            `"${milestoneBranch}" — refusing to self-merge. Integration branch metadata is invalid; ` +
-            `set a distinct main_branch in GSD preferences or repair the milestone integration record ` +
-            `before retrying milestone completion.`);
+            `"${milestoneBranch}" — refusing to self-merge. ${branchResolution.reason}. ` +
+            `Repair milestone integration metadata before retrying milestone completion.`);
     }
     // Remove transient project-root state files before any branch or merge
     // operation. Untracked milestone metadata can otherwise block squash merges.
@@ -1482,6 +1591,56 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             });
         }
     }
+    // Already regular-merged milestones can skip the squash path and proceed to cleanup (#5831).
+    if (nativeIsAncestor(originalBasePath_, milestoneBranch, mainBranch)) {
+        const codeChanges = nativeDiffNumstat(originalBasePath_, mainBranch, milestoneBranch).filter((entry) => !entry.path.startsWith(".gsd/"));
+        if (codeChanges.length > 0) {
+            const regularMergeChangedPaths = findRegularMergeChangedPaths(originalBasePath_, milestoneBranch, mainBranch);
+            const unanchoredCodeChanges = codeChanges.filter((entry) => regularMergeChangedPaths.has(entry.path));
+            if (unanchoredCodeChanges.length > 0) {
+                process.chdir(previousCwd);
+                throw new GSDError(GSD_GIT_ERROR, `Milestone branch "${milestoneBranch}" is reachable from "${mainBranch}" ` +
+                    `but has ${unanchoredCodeChanges.length} milestone-touched code file(s) not on current "${mainBranch}". ` +
+                    `Aborting worktree teardown to prevent data loss.`);
+            }
+        }
+        debugLog("mergeMilestoneToMain", {
+            action: "skip-squash-already-merged",
+            milestoneId,
+            milestoneBranch,
+            mainBranch,
+        });
+        try {
+            clearProjectRootStateFiles(originalBasePath_, milestoneId);
+        }
+        catch (err) {
+            logWarning("worktree", `clearProjectRootStateFiles failed during already-merged cleanup: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            removeWorktree(originalBasePath_, milestoneId, {
+                branch: milestoneBranch,
+                deleteBranch: false,
+            });
+        }
+        catch (err) {
+            logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            nativeBranchDelete(originalBasePath_, milestoneBranch);
+        }
+        catch (err) {
+            logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        setActiveWorkspace(null);
+        nudgeGitBranchCache(previousCwd);
+        try {
+            process.chdir(originalBasePath_);
+        }
+        catch (err) {
+            logWarning("worktree", `chdir to project root after already-merged cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
+    }
     // 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
@@ -1617,14 +1776,6 @@ 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
@@ -1633,6 +1784,14 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     removeMergeStateFiles(originalBasePath_, "pre-merge");
     // 8. Squash merge — auto-resolve .gsd/ state file conflicts (#530)
     const mergeResult = nativeMergeSquash(originalBasePath_, milestoneBranch);
+    if (needsDbCycle && dbPathToReopen) {
+        try {
+            openDatabase(dbPathToReopen);
+        }
+        catch (err) {
+            logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     if (!mergeResult.success) {
         // Dirty working tree — the merge was rejected before it started (e.g.
         // untracked .gsd/ files left by syncStateToProjectRoot).  Preserve the