@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -54,14 +54,14 @@ const DEFAULT_STALE_DAYS = 14;
  * @param basePath — the main project root (not the worktree path)
  * @param wt — worktree info from listWorktrees()
  * @param staleDays — days without commits to consider stale (default: 14)
+ * @param mainBranch — pre-detected main branch for batched health checks
  */
 export function getWorktreeHealth(
   basePath: string,
   wt: WorktreeInfo,
   staleDays = DEFAULT_STALE_DAYS,
+  mainBranch = nativeDetectMainBranch(basePath),
 ): WorktreeHealthStatus {
-  const mainBranch = nativeDetectMainBranch(basePath);
-
   // Merge status: is the worktree branch fully contained in main?
   let mergedIntoMain = false;
   try {
@@ -131,7 +131,10 @@ export function getAllWorktreeHealth(
   staleDays = DEFAULT_STALE_DAYS,
 ): WorktreeHealthStatus[] {
   const worktrees = listWorktrees(basePath);
-  return worktrees.map(wt => getWorktreeHealth(basePath, wt, staleDays));
+  if (worktrees.length === 0) return [];
+
+  const mainBranch = nativeDetectMainBranch(basePath);
+  return worktrees.map(wt => getWorktreeHealth(basePath, wt, staleDays, mainBranch));
 }
 
 /**

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

@@ -21,6 +21,8 @@ import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 
+import type { PreflightResult, PostflightResult } from "./clean-root-preflight.js";
+
 import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning } from "./workflow-logger.js";
@@ -153,11 +155,11 @@ export interface WorktreeLifecycleDeps {
   /**
    * Milestone Merge Transaction Module runner.
    *
-   * The field name is preserved for existing test fixtures, but production
-   * wiring now supplies the named transaction wrapper rather than the raw
-   * squash-merge primitive directly.
+   * The field name describes the lifecycle seam; production wiring supplies
+   * the named transaction wrapper rather than the raw legacy
+   * auto-worktree primitive directly.
    */
-  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
+  mergeMilestone: MilestoneMergeTransactionRunner;
 
   // ADR-016 phase 2 / C1 + C2 + C3 + C4 inlined the following fields as
   // direct imports — leaf primitives that did not vary across callers:
@@ -238,7 +240,106 @@ export interface StrandedMilestoneAdoptionOptions {
 
 export type ExitResult =
   | { ok: true; merged: boolean; codeFilesChanged: boolean }
-  | { ok: false; reason: "merge-conflict" | "teardown-failed"; cause?: unknown };
+  | {
+      ok: false;
+      reason:
+        | "merge-conflict"
+        | "teardown-failed"
+        | "preflight-dirty-overlap"
+        | "preflight-unmerged-conflicts"
+        | "merge-failed"
+        | "postflight-stash-restore-failed";
+      cause?: unknown;
+      postflight?: PostflightResult;
+    };
+
+export interface GuardedMilestoneMergeDeps {
+  preflightCleanRoot: (
+    basePath: string,
+    milestoneId: string,
+    notify: NotifyCtx["notify"],
+  ) => PreflightResult;
+  postflightPopStash: (
+    basePath: string,
+    milestoneId: string,
+    stashMarker: string | undefined,
+    notify: NotifyCtx["notify"],
+  ) => PostflightResult;
+}
+
+/**
+ * Optional `exitMilestone(..., { merge: true, guardedMerge })` contract for callers
+ * that need root-clean preflight and postflight stash restoration around the
+ * lifecycle-owned merge attempt. `projectRoot` is the workspace root whose
+ * user changes are protected by the supplied guard functions.
+ */
+export interface GuardedMilestoneMergeOptions extends GuardedMilestoneMergeDeps {
+  projectRoot: string;
+}
+
+type GuardedMilestoneMergeResult = ExitResult;
+
+function preflightBlockedMergeReason(
+  blockedReason: PreflightResult["blockedReason"],
+): Extract<ExitResult, { ok: false }>["reason"] {
+  if (blockedReason?.startsWith("unmerged-conflicts")) {
+    return "preflight-unmerged-conflicts";
+  }
+  return "preflight-dirty-overlap";
+}
+
+/**
+ * Run a milestone merge behind the Worktree Lifecycle seam with the root-clean
+ * stash guard that protects user changes around merge.
+ *
+ * The helper owns the invariant ordering (preflight -> merge callback ->
+ * postflight on every attempted merge path) and returns the same typed result
+ * shape as `exitMilestone`. Auto closeout remains responsible for translating
+ * that result into loop policy (pause vs. stop, visible transcript
+ * preservation, projection rebuild).
+ */
+function runGuardedMilestoneMerge(request: {
+  merge: () => ExitResult;
+  guard: GuardedMilestoneMergeOptions;
+  milestoneId: string;
+  notify: NotifyCtx["notify"];
+}): GuardedMilestoneMergeResult {
+  const { merge, guard, milestoneId, notify } = request;
+  const preflight = guard.preflightCleanRoot(guard.projectRoot, milestoneId, notify);
+  if (preflight.blocked) {
+    return {
+      ok: false,
+      reason: preflightBlockedMergeReason(preflight.blockedReason),
+    };
+  }
+
+  let mergeError: unknown = null;
+  const exitResult = merge();
+  if (!exitResult.ok) {
+    mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+  }
+
+  let postflight: PostflightResult | undefined;
+  if (preflight.stashPushed) {
+    postflight = guard.postflightPopStash(
+      guard.projectRoot,
+      milestoneId,
+      preflight.stashMarker,
+      notify,
+    );
+  }
+
+  if (mergeError instanceof MergeConflictError) {
+    return { ok: false, reason: "merge-conflict", cause: mergeError, postflight };
+  }
+  if (mergeError) {
+    return { ok: false, reason: "merge-failed", cause: mergeError, postflight };
+  }
+  if (postflight?.needsManualRecovery) {
+    return { ok: false, reason: "postflight-stash-restore-failed", postflight };
+  }
+  return exitResult;
+}
 
 /**
  * Session-less merge entry context. Per ADR-016 phase 2 / A1 (#5616), the
@@ -1046,7 +1147,7 @@ function _mergeWorktreeModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       originalBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1213,7 +1314,7 @@ function _mergeBranchModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       worktreeBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1444,18 +1545,41 @@ export class WorktreeLifecycle {
    * With `opts.merge === false`, runs auto-commit and teardown without
    * merging to main.
    *
+   * When `opts.guardedMerge` is present with `opts.merge === true`, the
+   * lifecycle verb also owns the root-clean guard around the merge: preflight
+   * runs before the inner merge, postflight stash restore runs after every
+   * attempted merge path, and guard failures are returned as typed
+   * `ExitResult` reasons.
+   *
    * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
    * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
-   * giving callers a typed branch for the expected failure path.
-   * Unexpected failures (filesystem, git permissions, etc.) are wrapped
-   * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
+   * giving callers a typed branch for the expected failure path. Guarded merge
+   * failures surface as `preflight-dirty-overlap`,
+   * `preflight-unmerged-conflicts`, `merge-failed`, or
+   * `postflight-stash-restore-failed`. Unexpected failures (filesystem, git
+   * permissions, etc.) are wrapped as
+   * `{ ok: false, reason: "teardown-failed", cause }` so callers always
    * receive a discriminated union — no exceptions for any expected outcome.
    */
   exitMilestone(
     milestoneId: string,
-    opts: { merge: boolean; preserveBranch?: boolean; preserveWorktree?: boolean },
+    opts: {
+      merge: boolean;
+      preserveBranch?: boolean;
+      preserveWorktree?: boolean;
+      guardedMerge?: GuardedMilestoneMergeOptions;
+    },
     ctx: NotifyCtx,
   ): ExitResult {
+    if (opts.merge && opts.guardedMerge) {
+      return runGuardedMilestoneMerge({
+        merge: () => this.exitMilestone(milestoneId, { merge: true }, ctx),
+        guard: opts.guardedMerge,
+        milestoneId,
+        notify: ctx.notify,
+      });
+    }
+
     if (opts.merge) {
       try {
         const merged = this._mergeAndExit(milestoneId, ctx);

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

@@ -19,7 +19,7 @@
  *   4. remove()  — git worktree remove + branch cleanup
  */
 
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
@@ -37,6 +37,7 @@ import {
   nativeGetCurrentBranch,
   nativeIsAncestor,
   nativeLogOneline,
+  nativeMergeAbort,
   nativeMergeSquash,
   nativeWorktreeAdd,
   nativeWorktreeList,
@@ -87,6 +88,34 @@ function deleteBranchIfPresent(basePath: string, branch: string, warningPrefix:
   }
 }
 
+function cleanupFailedSquashMergeState(basePath: string): void {
+  try {
+    nativeMergeAbort(basePath);
+  } catch (e) {
+    // Squash conflicts may not create MERGE_HEAD; this is expected.
+    logWarning("worktree", `merge abort skipped: ${(e as Error).message}`);
+  }
+  try {
+    execFileSync("git", ["reset", "--merge"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (e) {
+    logWarning("worktree", `failed squash merge reset failed: ${(e as Error).message}`);
+  }
+
+  const gitDir = resolveGitDir(basePath);
+  for (const marker of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
+    try {
+      const markerPath = join(gitDir, marker);
+      if (existsSync(markerPath)) unlinkSync(markerPath);
+    } catch (e) {
+      logWarning("worktree", `failed squash merge marker cleanup failed (${marker}): ${(e as Error).message}`);
+    }
+  }
+}
+
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 
 function normalizePathForComparison(path: string): string {
@@ -198,6 +227,113 @@ function isRegisteredGitWorktreeAtPath(basePath: string, wtPath: string): boolea
   }
 }
 
+function inspectUncommittedWorktreeState(wtPath: string): { dirty: boolean; status: string } {
+  try {
+    const status = execFileSync(
+      "git",
+      ["status", "--porcelain=v1", "--untracked-files=all"],
+      { cwd: wtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trimEnd();
+    return { dirty: status.length > 0, status };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logWarning(
+      "worktree",
+      `dirty worktree inspection failed for ${wtPath}: ${message}`,
+    );
+    // Fail closed: unknown state must quarantine rather than force-remove.
+    return { dirty: true, status: `git status failed: ${message}` };
+  }
+}
+
+function timestampForPath(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function uniqueQuarantinePath(basePath: string, name: string): string {
+  const root = join(basePath, ".gsd", "quarantine", "worktrees");
+  const baseName = `${name}-${timestampForPath()}`;
+  let candidate = join(root, baseName);
+  let suffix = 2;
+  while (existsSync(candidate)) {
+    candidate = join(root, `${baseName}-${suffix}`);
+    suffix++;
+  }
+  return candidate;
+}
+
+function quarantineDirtyWorktree(
+  basePath: string,
+  name: string,
+  branch: string,
+  wtPath: string,
+  status: string,
+): string | null {
+  const quarantinePath = uniqueQuarantinePath(basePath, name);
+  mkdirSync(join(basePath, ".gsd", "quarantine", "worktrees"), { recursive: true });
+
+  let moved = false;
+  try {
+    renameSync(wtPath, quarantinePath);
+    moved = true;
+  } catch (renameErr) {
+    logWarning(
+      "worktree",
+      `dirty worktree rename quarantine failed for ${name}: ${renameErr instanceof Error ? renameErr.message : String(renameErr)}; trying copy snapshot`,
+    );
+    try {
+      cpSync(wtPath, quarantinePath, { recursive: true, force: false, errorOnExist: true });
+    } catch (copyErr) {
+      logWarning(
+        "reconcile",
+        `Dirty worktree quarantine failed; preserving original worktree ${wtPath}: ${copyErr instanceof Error ? copyErr.message : String(copyErr)}`,
+        { worktree: name, path: wtPath },
+      );
+      return null;
+    }
+  }
+
+  try {
+    const gitFile = join(quarantinePath, ".git");
+    if (existsSync(gitFile) && lstatSync(gitFile).isFile()) {
+      unlinkSync(gitFile);
+    }
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `failed to remove quarantined worktree git pointer: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  try {
+    writeFileSync(
+      join(quarantinePath, ".gsd-quarantine.json"),
+      JSON.stringify({
+        kind: "dirty-worktree",
+        worktree: name,
+        branch,
+        originalPath: wtPath,
+        moved,
+        quarantinedAt: new Date().toISOString(),
+        status,
+      }, null, 2) + "\n",
+      "utf-8",
+    );
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `failed to write worktree quarantine metadata: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  logWarning(
+    "reconcile",
+    `Quarantined dirty worktree ${name} at ${quarantinePath} before removal. Branch ${branch} was preserved.`,
+    { worktree: name, path: quarantinePath, branch },
+  );
+  return quarantinePath;
+}
+
 /** True when `wtPath` has a git worktree checkout marker (`.git` file with gitdir pointer). */
 export function isLiveGitWorktreeCheckout(wtPath: string): boolean {
   const gitPath = join(wtPath, ".git");
@@ -287,7 +423,7 @@ export function pruneEphemeralGhostWorktreeDirectories(basePath: string): string
   return removed;
 }
 
-function removeStaleWorktreeDirectory(wtPath: string, name: string): void {
+export function removeStaleWorktreeDirectory(wtPath: string, name: string): void {
   logWarning(
     "reconcile",
     `Removing stale worktree directory (not registered with git): ${wtPath}`,
@@ -701,12 +837,13 @@ export function removeWorktree(
   basePath: string,
   name: string,
   opts: { deleteBranch?: boolean; force?: boolean; branch?: string } = {},
-): void {
+): boolean {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   let wtPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
   const { deleteBranch = true, force = true } = opts;
+  let deleteBranchAfterRemoval = deleteBranch;
 
   // Resolve the ACTUAL worktree path from git's worktree list.
   // The computed path may differ when .gsd/ is (or was) a symlink to an
@@ -759,10 +896,10 @@ export function removeWorktree(
 
   if (!existsSync(wtPath)) {
     nativeWorktreePrune(basePath);
-    if (deleteBranch) {
+    if (deleteBranchAfterRemoval) {
       deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
     }
-    return;
+    return true;
   }
 
   // Submodule safety (#2337): detect submodules with uncommitted changes
@@ -844,6 +981,35 @@ export function removeWorktree(
     }
   }
 
+  // Dirty-worktree quarantine (#2365): once submodule (#2337) and nested-.git
+  // (#2616) rescue have run — they commit/clean the tree first — quarantine any
+  // uncommitted state that remains instead of force-deleting it. Gate on a live
+  // git checkout so a stale local directory left behind by state-sync (which
+  // has no `.git` file and is not a registered worktree) is removed normally
+  // rather than quarantined; otherwise its branch would never be deleted and
+  // the worktree would never be unregistered (#1852).
+  if (force && resolvedPathSafe && isLiveGitWorktreeCheckout(resolvedWtPath)) {
+    const dirtyState = inspectUncommittedWorktreeState(resolvedWtPath);
+    if (dirtyState.dirty) {
+      const quarantinePath = quarantineDirtyWorktree(
+        basePath,
+        name,
+        branch,
+        resolvedWtPath,
+        dirtyState.status,
+      );
+      if (!quarantinePath) {
+        return false;
+      }
+
+      deleteBranchAfterRemoval = false;
+      if (!existsSync(resolvedWtPath)) {
+        nativeWorktreePrune(basePath);
+        return true;
+      }
+    }
+  }
+
   // Remove worktree — only use force/rmSync when the path is safely contained
   if (resolvedPathSafe) {
     // Remove worktree: try non-force first when submodules have changes,
@@ -894,9 +1060,10 @@ export function removeWorktree(
   // Prune stale entries so git knows the worktree is gone
   nativeWorktreePrune(basePath);
 
-  if (deleteBranch) {
+  if (deleteBranchAfterRemoval) {
     deleteBranchIfPresent(basePath, branch, "final branch delete failed");
   }
+  return true;
 }
 
 /**
@@ -964,11 +1131,11 @@ function parseDiffNameStatus(entries: { status: string; path: string }[]): Workt
  * Diff the .gsd/ directory between the worktree branch and main branch.
  * Returns a summary of added, modified, and removed GSD artifacts.
  */
-export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSummary {
+export function diffWorktreeGSD(basePath: string, name: string, mainBranchOverride?: string): WorktreeDiffSummary {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const entries = nativeDiffNameStatus(basePath, mainBranch, branch, ".gsd/", true);
 
@@ -981,11 +1148,16 @@ export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSum
  * on main when the merge is applied. If both branches have identical
  * content, this correctly returns an empty diff.
  */
-export function diffWorktreeAll(basePath: string, name: string, branchOverride?: string): WorktreeDiffSummary {
+export function diffWorktreeAll(
+  basePath: string,
+  name: string,
+  branchOverride?: string,
+  mainBranchOverride?: string,
+): WorktreeDiffSummary {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = branchOverride ?? worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
 
@@ -996,11 +1168,16 @@ export function diffWorktreeAll(basePath: string, name: string, branchOverride?:
  * Get per-file line addition/deletion stats for what will change on main.
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
-export function diffWorktreeNumstat(basePath: string, name: string, branchOverride?: string): FileLineStat[] {
+export function diffWorktreeNumstat(
+  basePath: string,
+  name: string,
+  branchOverride?: string,
+  mainBranchOverride?: string,
+): FileLineStat[] {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = branchOverride ?? worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
 
@@ -1016,11 +1193,11 @@ export function diffWorktreeNumstat(basePath: string, name: string, branchOverri
  * Get the full diff content for .gsd/ between the worktree branch and main.
  * Returns the raw unified diff for LLM consumption.
  */
-export function getWorktreeGSDDiff(basePath: string, name: string): string {
+export function getWorktreeGSDDiff(basePath: string, name: string, mainBranchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   return nativeDiffContent(basePath, mainBranch, branch, ".gsd/", undefined, true);
 }
@@ -1029,11 +1206,11 @@ export function getWorktreeGSDDiff(basePath: string, name: string): string {
  * Get the full diff content for non-.gsd/ files between the worktree branch and main.
  * Returns the raw unified diff for LLM consumption.
  */
-export function getWorktreeCodeDiff(basePath: string, name: string): string {
+export function getWorktreeCodeDiff(basePath: string, name: string, mainBranchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   return nativeDiffContent(basePath, mainBranch, branch, undefined, ".gsd/", true);
 }
@@ -1041,11 +1218,11 @@ export function getWorktreeCodeDiff(basePath: string, name: string): string {
 /**
  * Get commit log for the worktree branch since it diverged from main.
  */
-export function getWorktreeLog(basePath: string, name: string): string {
+export function getWorktreeLog(basePath: string, name: string, mainBranchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const entries = nativeLogOneline(basePath, mainBranch, branch);
 
@@ -1057,11 +1234,17 @@ export function getWorktreeLog(basePath: string, name: string): string {
  * Must be called from the main working tree (not the worktree itself).
  * Returns the merge commit message.
  */
-export function mergeWorktreeToMain(basePath: string, name: string, commitMessage: string, branchOverride?: string): string {
+export function mergeWorktreeToMain(
+  basePath: string,
+  name: string,
+  commitMessage: string,
+  branchOverride?: string,
+  mainBranchOverride?: string,
+): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = branchOverride ?? worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
   const current = nativeGetCurrentBranch(basePath);
 
   if (current !== mainBranch) {
@@ -1070,6 +1253,17 @@ export function mergeWorktreeToMain(basePath: string, name: string, commitMessag
 
   const result = nativeMergeSquash(basePath, branch);
   if (!result.success) {
+    const dirtyWorkingTree = result.conflicts.includes("__dirty_working_tree__");
+    if (!dirtyWorkingTree) {
+      cleanupFailedSquashMergeState(basePath);
+    }
+    if (!dirtyWorkingTree && branch.startsWith("milestone/")) {
+      try {
+        removeWorktree(basePath, name, { branch, deleteBranch: true, force: true });
+      } catch (e) {
+        logWarning("worktree", `failed milestone branch cleanup after squash merge failure: ${(e as Error).message}`);
+      }
+    }
     throw new GSDError(GSD_MERGE_CONFLICT, `Merge conflicts detected in: ${result.conflicts.join(", ")}`);
   }