gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.04f5ccf82

package/src/resources/extensions/gsd/auto-verification.ts

@@ -20,6 +20,7 @@ import { parseUnitId } from "./unit-id.js";
 import { isDbAvailable, getTask, getSliceTasks, getMilestoneSlices } from "./gsd-db.js";
 import type { TaskRow } from "./db-task-slice-rows.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import type { GSDPreferences } from "./preferences-types.js";
 import { extractVerdict } from "./verdict-parser.js";
 import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
@@ -27,10 +28,12 @@ import { parseRoadmap } from "./parsers-legacy.js";
 import { isMilestoneComplete } from "./state.js";
 import {
   runVerificationGate,
+  runVerificationGateForTargets,
   formatFailureContext,
   captureRuntimeErrors,
   runDependencyAudit,
 } from "./verification-gate.js";
+import type { VerificationTarget } from "./verification-gate.js";
 import { writeVerificationJSON, type PostExecutionCheckJSON, type EvidenceJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
 import { runPostExecutionChecks, type PostExecutionResult } from "./post-execution-checks.js";
@@ -40,6 +43,12 @@ 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";
+import { decideVerificationVerdict } from "./verification-verdict.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import type { SliceRow } from "./db-task-slice-rows.js";
+import { getSlice } from "./gsd-db.js";
+import { getLedger } from "./metrics.js";
+import { getUnitCostSpikeAction } from "./auto-budget.js";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -49,10 +58,69 @@ export interface VerificationContext {
 
 export type VerificationResult = "continue" | "retry" | "pause";
 
-function isInfraVerificationFailure(stderr: string): boolean {
-  return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(
-    stderr,
-  );
+function getCurrentUnitCostStats(unitId: string): { unitCostUsd: number; rollingAvgUsd: number } {
+  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: string,
+  prefs: GSDPreferences | undefined,
+  task: TaskRow | null,
+  slice: SliceRow | null,
+): VerificationTarget[] {
+  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: VerificationTarget[] = [];
+  const seen = new Set<string>();
+  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;
 }
 
 /**
@@ -110,11 +178,31 @@ async function runValidateMilestonePostCheck(
   const { milestone: mid } = parseUnitId(s.currentUnit.id);
   if (!mid) return "continue";
 
+  const setToolFailureRetry = (message: string): VerificationResult => {
+    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") {
@@ -196,7 +284,7 @@ async function countIncompleteSlices(basePath: string, milestoneId: string): Pro
 /**
  * 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
  */
@@ -226,18 +314,29 @@ export async function runPostUnitVerification(
     // Read task plan verify field
     const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
     let taskPlanVerify: string | undefined;
+    let taskRow: TaskRow | null = null;
+    let sliceRow: SliceRow | null = 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();
@@ -260,6 +359,11 @@ export async function runPostUnitVerification(
       }
     }
 
+    const verdict = decideVerificationVerdict(s.currentUnit.type, result);
+    if (!verdict.passed) {
+      result.passed = false;
+    }
+
     if (uokFlags.gates) {
       const gateRunner = new UokGateRunner();
       gateRunner.register({
@@ -272,10 +376,12 @@ export async function runPostUnitVerification(
             : "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),
         }),
       });
 
@@ -343,13 +449,18 @@ export async function runPostUnitVerification(
             writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id);
           } else {
             const nextAttempt = attempt + 1;
+            const includeRetryMetadata =
+              !result.passed &&
+              verdict.retryable &&
+              autoFixEnabled &&
+              nextAttempt <= maxRetries;
             writeVerificationJSON(
               result,
               tasksDir,
               tid,
               s.currentUnit.id,
-              nextAttempt,
-              maxRetries,
+              includeRetryMetadata ? nextAttempt : undefined,
+              includeRetryMetadata ? maxRetries : undefined,
             );
           }
         }
@@ -358,26 +469,6 @@ export async function runPostUnitVerification(
       }
     }
 
-    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: PostExecutionCheckJSON[] | undefined;
     let postExecBlockingFailure = false;
@@ -389,8 +480,7 @@ export async function runPostUnitVerification(
 
       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);
@@ -572,6 +662,17 @@ export async function runPostUnitVerification(
       s.verificationRetryFailureHashes.delete(retryKey);
       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.
@@ -585,11 +686,38 @@ export async function runPostUnitVerification(
       await pauseAuto(ctx, pi);
       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
@@ -623,9 +751,13 @@ export async function runPostUnitVerification(
       return "pause";
     }
   } catch (err) {
-    // Gate errors are non-fatal
     logWarning("engine", `verification-gate error: ${(err as Error).message}`);
-    return "continue";
+    ctx.ui.notify(
+      `Verification gate errored before producing an authoritative verdict: ${(err as Error).message}`,
+      "error",
+    );
+    await pauseAuto(ctx, pi);
+    return "pause";
   }
 }
 

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -52,7 +52,7 @@ import {
   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";
@@ -252,7 +252,17 @@ function gitPathspecForWorktreePath(basePath: string, targetPath: string): strin
   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 */
     void base;
@@ -269,6 +279,10 @@ function gitPathspecForWorktreePath(basePath: string, targetPath: string): strin
   return rel.replaceAll("\\", "/");
 }
 
+export function _gitPathspecForWorktreePath(basePath: string, targetPath: string): string | null {
+  return gitPathspecForWorktreePath(basePath, targetPath);
+}
+
 function gitRemoteExists(basePath: string, remote: string): boolean {
   try {
     execFileSync("git", ["remote", "get-url", remote], {
@@ -282,6 +296,50 @@ function gitRemoteExists(basePath: string, remote: string): boolean {
   }
 }
 
+function findRegularMergeChangedPaths(basePath: string, milestoneBranch: string, mainBranch: string): Set<string> {
+  const changedPaths = new Set<string>();
+  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: string, milestoneId: string): void {
   const gsdDir = gsdRoot(basePath);
   // Phase C pt 2: auto.lock removed from this list — the file is gone
@@ -643,7 +701,8 @@ export function syncGsdStateToWorktree(
   // If both resolve to the same directory (symlink), no sync needed
   if (isSamePath(mainGsd, wtGsd)) return { synced };
 
-  if (!existsSync(mainGsd) || !existsSync(wtGsd)) return { synced };
+  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) {
@@ -949,7 +1008,73 @@ export function enterBranchModeForMilestone(
     });
   }
 
-  nativeCheckoutBranch(basePath, branch);
+  checkoutBranchWithStashGuard(basePath, branch, `enter-branch-mode:${milestoneId}`);
+}
+
+export function checkoutBranchWithStashGuard(
+  basePath: string,
+  branch: string,
+  reason: string,
+): void {
+  let stashMarker: string | null = 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 as { stashRef?: string } | null)?.stashRef;
+      if (ref) (wrapped as { stashRef?: string }).stashRef = ref;
+      throw wrapped;
+    }
+  }
 }
 
 // ─── Public API ────────────────────────────────────────────────────────────
@@ -1596,22 +1721,11 @@ export function mergeMilestoneToMain(
   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
@@ -1625,9 +1739,8 @@ export function mergeMilestoneToMain(
     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.`,
     );
   }
 
@@ -1739,6 +1852,66 @@ export function mergeMilestoneToMain(
     }
   }
 
+  // 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
@@ -1874,14 +2047,6 @@ export function mergeMilestoneToMain(
     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
@@ -1891,6 +2056,13 @@ export function mergeMilestoneToMain(
 
   // 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.