gsd-pi 2.33.1-dev.ee47f1b → 2.34.0-dev.0150ae9

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

@@ -5,22 +5,39 @@
  * manual `/worktree` which uses `worktree/<name>` branches). This module
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
-import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync, readdirSync, cpSync, mkdirSync, lstatSync as lstatSyncFn } from "node:fs";
+import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
+import { copyWorktreeDb, reconcileWorktreeDb, isDbAvailable, } from "./gsd-db.js";
+import { atomicWriteSync } from "./atomic-write.js";
 import { execSync } from "node:child_process";
+import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
+import { gsdRoot } from "./paths.js";
 import { createWorktree, removeWorktree, worktreePath, } from "./worktree-manager.js";
-import { detectWorktreeName, nudgeGitBranchCache } from "./worktree.js";
-import { ensureGsdSymlink } from "./repo-identity.js";
-import { MergeConflictError, readIntegrationBranch, } from "./git-service.js";
+import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
+import { MergeConflictError, readIntegrationBranch } from "./git-service.js";
 import { parseRoadmap } from "./files.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { gsdRoot } from "./paths.js";
 import { nativeGetCurrentBranch, nativeWorkingTreeStatus, nativeAddAll, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchExists, } from "./native-git-bridge.js";
-import { getErrorMessage } from "./error-utils.js";
 // ─── Module State ──────────────────────────────────────────────────────────
 /** Original project root before chdir into auto-worktree. */
 let originalBase = null;
+function clearProjectRootStateFiles(basePath, milestoneId) {
+    const gsdDir = gsdRoot(basePath);
+    const transientFiles = [
+        join(gsdDir, "STATE.md"),
+        join(gsdDir, "auto.lock"),
+        join(gsdDir, "milestones", milestoneId, `${milestoneId}-META.json`),
+    ];
+    for (const file of transientFiles) {
+        try {
+            unlinkSync(file);
+        }
+        catch {
+            /* non-fatal — file may not exist */
+        }
+    }
+}
 // ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
 /**
  * Sync .gsd/ state from the main repo into the worktree.
@@ -53,7 +70,13 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
     if (!existsSync(mainGsd) || !existsSync(wtGsd))
         return { synced };
     // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE)
-    const rootFiles = ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md", "OVERRIDES.md"];
+    const rootFiles = [
+        "DECISIONS.md",
+        "REQUIREMENTS.md",
+        "PROJECT.md",
+        "KNOWLEDGE.md",
+        "OVERRIDES.md",
+    ];
     for (const f of rootFiles) {
         const src = join(mainGsd, f);
         const dst = join(wtGsd, f);
@@ -62,7 +85,9 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
                 cpSync(src, dst);
                 synced.push(f);
             }
-            catch { /* non-fatal */ }
+            catch {
+                /* non-fatal */
+            }
         }
     }
     // Sync milestones: copy entire milestone directories that are missing
@@ -71,9 +96,11 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
     if (existsSync(mainMilestonesDir)) {
         try {
             mkdirSync(wtMilestonesDir, { recursive: true });
-            const mainMilestones = readdirSync(mainMilestonesDir, { withFileTypes: true })
-                .filter(d => d.isDirectory() && /^M\d{3}/.test(d.name))
-                .map(d => d.name);
+            const mainMilestones = readdirSync(mainMilestonesDir, {
+                withFileTypes: true,
+            })
+                .filter((d) => d.isDirectory() && /^M\d{3}/.test(d.name))
+                .map((d) => d.name);
             for (const mid of mainMilestones) {
                 const srcDir = join(mainMilestonesDir, mid);
                 const dstDir = join(wtMilestonesDir, mid);
@@ -83,13 +110,15 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
                         cpSync(srcDir, dstDir, { recursive: true });
                         synced.push(`milestones/${mid}/`);
                     }
-                    catch { /* non-fatal */ }
+                    catch {
+                        /* non-fatal */
+                    }
                 }
                 else {
                     // Milestone directory exists but may be missing files (stale snapshot).
                     // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
                     try {
-                        const srcFiles = readdirSync(srcDir).filter(f => f.endsWith(".md") || f.endsWith(".json"));
+                        const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
                         for (const f of srcFiles) {
                             const srcFile = join(srcDir, f);
                             const dstFile = join(dstDir, f);
@@ -101,7 +130,9 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
                                         synced.push(`milestones/${mid}/${f}`);
                                     }
                                 }
-                                catch { /* non-fatal */ }
+                                catch {
+                                    /* non-fatal */
+                                }
                             }
                         }
                         // Sync slices directory if it exists in main but not in worktree
@@ -112,13 +143,17 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
                                 cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
                                 synced.push(`milestones/${mid}/slices/`);
                             }
-                            catch { /* non-fatal */ }
+                            catch {
+                                /* non-fatal */
+                            }
                         }
                         else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
                             // Both exist — sync missing slice directories
-                            const srcSlices = readdirSync(srcSlicesDir, { withFileTypes: true })
-                                .filter(d => d.isDirectory())
-                                .map(d => d.name);
+                            const srcSlices = readdirSync(srcSlicesDir, {
+                                withFileTypes: true,
+                            })
+                                .filter((d) => d.isDirectory())
+                                .map((d) => d.name);
                             for (const sid of srcSlices) {
                                 const srcSlice = join(srcSlicesDir, sid);
                                 const dstSlice = join(dstSlicesDir, sid);
@@ -127,16 +162,22 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
                                         cpSync(srcSlice, dstSlice, { recursive: true });
                                         synced.push(`milestones/${mid}/slices/${sid}/`);
                                     }
-                                    catch { /* non-fatal */ }
+                                    catch {
+                                        /* non-fatal */
+                                    }
                                 }
                             }
                         }
                     }
-                    catch { /* non-fatal */ }
+                    catch {
+                        /* non-fatal */
+                    }
                 }
             }
         }
-        catch { /* non-fatal */ }
+        catch {
+            /* non-fatal */
+        }
     }
     return { synced };
 }
@@ -177,24 +218,32 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
                     cpSync(src, dst, { force: true });
                     synced.push(`milestones/${milestoneId}/${entry.name}`);
                 }
-                catch { /* non-fatal */ }
+                catch {
+                    /* non-fatal */
+                }
             }
         }
     }
-    catch { /* non-fatal */ }
+    catch {
+        /* non-fatal */
+    }
     // Sync slice-level files (summaries, UATs)
     const wtSlicesDir = join(wtMilestoneDir, "slices");
     const mainSlicesDir = join(mainMilestoneDir, "slices");
     if (existsSync(wtSlicesDir)) {
         try {
-            for (const sliceEntry of readdirSync(wtSlicesDir, { withFileTypes: true })) {
+            for (const sliceEntry of readdirSync(wtSlicesDir, {
+                withFileTypes: true,
+            })) {
                 if (!sliceEntry.isDirectory())
                     continue;
                 const sid = sliceEntry.name;
                 const wtSliceDir = join(wtSlicesDir, sid);
                 const mainSliceDir = join(mainSlicesDir, sid);
                 mkdirSync(mainSliceDir, { recursive: true });
-                for (const fileEntry of readdirSync(wtSliceDir, { withFileTypes: true })) {
+                for (const fileEntry of readdirSync(wtSliceDir, {
+                    withFileTypes: true,
+                })) {
                     if (fileEntry.isFile() && fileEntry.name.endsWith(".md")) {
                         const src = join(wtSliceDir, fileEntry.name);
                         const dst = join(mainSliceDir, fileEntry.name);
@@ -202,12 +251,16 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
                             cpSync(src, dst, { force: true });
                             synced.push(`milestones/${milestoneId}/slices/${sid}/${fileEntry.name}`);
                         }
-                        catch { /* non-fatal */ }
+                        catch {
+                            /* non-fatal */
+                        }
                     }
                 }
             }
         }
-        catch { /* non-fatal */ }
+        catch {
+            /* non-fatal */
+        }
     }
     return { synced };
 }
@@ -247,7 +300,7 @@ export function runWorktreePostCreateHook(sourceDir, worktreeDir, hookPath) {
         return null;
     }
     catch (err) {
-        const msg = getErrorMessage(err);
+        const msg = err instanceof Error ? err.message : String(err);
         return `Worktree post-create hook failed: ${msg}`;
     }
 }
@@ -263,6 +316,96 @@ export function autoWorktreeBranch(milestoneId) {
  * Atomic: chdir + originalBase update happen in the same try block
  * to prevent split-brain.
  */
+/**
+ * Forward-merge plan checkbox state from the project root into a freshly
+ * re-attached worktree (#778).
+ *
+ * When auto-mode stops via crash (not graceful stop), the milestone branch
+ * HEAD may be behind the filesystem state at the project root because
+ * syncStateToProjectRoot() runs after every task completion but the final
+ * git commit may not have happened before the crash. On restart the worktree
+ * is re-attached to the branch HEAD, which has [ ] for the crashed task,
+ * causing verifyExpectedArtifact() to fail and triggering an infinite
+ * dispatch/skip loop.
+ *
+ * Fix: after re-attaching, read every *.md plan file in the milestone
+ * directory at the project root and apply any [x] checkbox states that are
+ * ahead of the worktree version (forward-only: never downgrade [x] → [ ]).
+ *
+ * This is safe because syncStateToProjectRoot() is the authoritative source
+ * of post-task state at the project root — it writes the same [x] the LLM
+ * produced, then the auto-commit follows. If the commit never happened, the
+ * filesystem copy is still valid and correct.
+ */
+function reconcilePlanCheckboxes(projectRoot, wtPath, milestoneId) {
+    const srcMilestone = join(projectRoot, ".gsd", "milestones", milestoneId);
+    const dstMilestone = join(wtPath, ".gsd", "milestones", milestoneId);
+    if (!existsSync(srcMilestone) || !existsSync(dstMilestone))
+        return;
+    // Walk all markdown files in the milestone directory (plans, summaries, etc.)
+    function walkMd(dir) {
+        const results = [];
+        try {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    results.push(...walkMd(full));
+                }
+                else if (entry.isFile() && entry.name.endsWith(".md")) {
+                    results.push(full);
+                }
+            }
+        }
+        catch {
+            /* non-fatal */
+        }
+        return results;
+    }
+    for (const srcFile of walkMd(srcMilestone)) {
+        const rel = srcFile.slice(srcMilestone.length);
+        const dstFile = dstMilestone + rel;
+        if (!existsSync(dstFile))
+            continue; // only reconcile existing files
+        let srcContent;
+        let dstContent;
+        try {
+            srcContent = readFileSync(srcFile, "utf-8");
+            dstContent = readFileSync(dstFile, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (srcContent === dstContent)
+            continue;
+        // Extract all checked task IDs from the source (project root)
+        // Pattern: - [x] **T<id>: or - [x] **S<id>: (case-insensitive x)
+        const checkedRe = /^- \[[xX]\] \*\*([TS]\d+):/gm;
+        const srcChecked = new Set();
+        for (const m of srcContent.matchAll(checkedRe))
+            srcChecked.add(m[1]);
+        if (srcChecked.size === 0)
+            continue;
+        // Forward-apply: replace [ ] → [x] for any IDs that are checked in src
+        let updated = dstContent;
+        let changed = false;
+        for (const id of srcChecked) {
+            const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const uncheckedRe = new RegExp(`^(- )\\[ \\]( \\*\\*${escapedId}:)`, "gm");
+            if (uncheckedRe.test(updated)) {
+                updated = updated.replace(new RegExp(`^(- )\\[ \\]( \\*\\*${escapedId}:)`, "gm"), "$1[x]$2");
+                changed = true;
+            }
+        }
+        if (changed) {
+            try {
+                atomicWriteSync(dstFile, updated, "utf-8");
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+    }
+}
 export function createAutoWorktree(basePath, milestoneId) {
     const branch = autoWorktreeBranch(milestoneId);
     // Check if the milestone branch already exists — it survives auto-mode
@@ -273,20 +416,46 @@ export function createAutoWorktree(basePath, milestoneId) {
     let info;
     if (branchExists) {
         // Re-attach worktree to the existing milestone branch (preserving commits)
-        info = createWorktree(basePath, milestoneId, { branch, reuseExistingBranch: true });
+        info = createWorktree(basePath, milestoneId, {
+            branch,
+            reuseExistingBranch: true,
+        });
     }
     else {
         // Fresh start — create branch from integration branch
         const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
-        info = createWorktree(basePath, milestoneId, { branch, startPoint: integrationBranch });
-    }
-    // Ensure worktree shares external state via symlink
-    ensureGsdSymlink(info.path);
-    // Sync .gsd/ state from main repo into the worktree (#1311).
-    // Even with the symlink, the worktree may have stale git-tracked files
-    // if .gsd/ is not gitignored. And on fresh create, the milestone files
-    // created on main since the branch point won't be in the worktree.
-    syncGsdStateToWorktree(basePath, info.path);
+        info = createWorktree(basePath, milestoneId, {
+            branch,
+            startPoint: integrationBranch,
+        });
+    }
+    // Copy .gsd/ planning artifacts from the source repo into the new worktree.
+    // Worktrees are fresh git checkouts — untracked files don't carry over.
+    // Planning artifacts may be untracked if the project's .gitignore had a
+    // blanket .gsd/ rule (pre-v2.14.0). Without this copy, auto-mode loops
+    // on plan-slice because the plan file doesn't exist in the worktree.
+    //
+    // IMPORTANT: Skip when re-attaching to an existing branch (#759).
+    // The branch checkout already has committed artifacts with correct state
+    // (e.g. [x] for completed slices). Copying from the project root would
+    // overwrite them with stale data ([ ] checkboxes) because the root is
+    // not always fully synced.
+    if (!branchExists) {
+        copyPlanningArtifacts(basePath, info.path);
+    }
+    else {
+        // Re-attaching to an existing branch: forward-merge any plan checkpoint
+        // state from the project root into the worktree (#778).
+        //
+        // If auto-mode stopped via crash, the milestone branch HEAD may lag behind
+        // the project root filesystem because syncStateToProjectRoot() ran after
+        // task completion but the auto-commit never fired. On restart the worktree
+        // is re-created from the branch HEAD (which has [ ] for the crashed task),
+        // causing verifyExpectedArtifact() to return false → stale-key eviction →
+        // infinite dispatch/skip loop. Reconciling here ensures the worktree sees
+        // the same [x] state that syncStateToProjectRoot() wrote to the root.
+        reconcilePlanCheckboxes(basePath, info.path, milestoneId);
+    }
     // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets
     const hookError = runWorktreePostCreateHook(basePath, info.path);
     if (hookError) {
@@ -301,11 +470,52 @@ export function createAutoWorktree(basePath, milestoneId) {
     catch (err) {
         // If chdir fails, the worktree was created but we couldn't enter it.
         // Don't store originalBase -- caller can retry or clean up.
-        throw new GSDError(GSD_IO_ERROR, `Auto-worktree created at ${info.path} but chdir failed: ${getErrorMessage(err)}`);
+        throw new GSDError(GSD_IO_ERROR, `Auto-worktree created at ${info.path} but chdir failed: ${err instanceof Error ? err.message : String(err)}`);
     }
     nudgeGitBranchCache(previousCwd);
     return info.path;
 }
+/**
+ * Copy .gsd/ planning artifacts from source repo to a new worktree.
+ * Copies milestones/, DECISIONS.md, REQUIREMENTS.md, PROJECT.md, QUEUE.md,
+ * STATE.md, KNOWLEDGE.md, and OVERRIDES.md.
+ * Skips runtime files (auto.lock, metrics.json, etc.) and the worktrees/ dir.
+ * Best-effort — failures are non-fatal since auto-mode can recreate artifacts.
+ */
+function copyPlanningArtifacts(srcBase, wtPath) {
+    const srcGsd = join(srcBase, ".gsd");
+    const dstGsd = join(wtPath, ".gsd");
+    if (!existsSync(srcGsd))
+        return;
+    // Copy milestones/ directory (planning files, roadmaps, plans, research)
+    safeCopyRecursive(join(srcGsd, "milestones"), join(dstGsd, "milestones"), {
+        force: true,
+        filter: (src) => !src.endsWith("-META.json"),
+    });
+    // Copy top-level planning files
+    for (const file of [
+        "DECISIONS.md",
+        "REQUIREMENTS.md",
+        "PROJECT.md",
+        "QUEUE.md",
+        "STATE.md",
+        "KNOWLEDGE.md",
+        "OVERRIDES.md",
+    ]) {
+        safeCopy(join(srcGsd, file), join(dstGsd, file), { force: true });
+    }
+    // Copy gsd.db if present in source
+    const srcDb = join(srcGsd, "gsd.db");
+    const destDb = join(dstGsd, "gsd.db");
+    if (existsSync(srcDb)) {
+        try {
+            copyWorktreeDb(srcDb, destDb);
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+}
 /**
  * Teardown an auto-worktree: chdir back to original base, then remove
  * the worktree and its branch.
@@ -319,50 +529,28 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
         originalBase = null;
     }
     catch (err) {
-        throw new GSDError(GSD_IO_ERROR, `Failed to chdir back to ${originalBasePath} during teardown: ${getErrorMessage(err)}`);
+        throw new GSDError(GSD_IO_ERROR, `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`);
     }
     nudgeGitBranchCache(previousCwd);
-    removeWorktree(originalBasePath, milestoneId, { branch, deleteBranch: !preserveBranch });
+    removeWorktree(originalBasePath, milestoneId, {
+        branch,
+        deleteBranch: !preserveBranch,
+    });
 }
 /**
  * Detect if the process is currently inside an auto-worktree.
  * Checks both module state and git branch prefix.
  */
 export function isInAutoWorktree(basePath) {
-    const cwd = process.cwd();
-    // Primary check: use originalBase if available (fast path)
-    if (originalBase) {
-        const resolvedBase = existsSync(basePath) ? realpathSync(basePath) : basePath;
-        const wtDir = join(gsdRoot(resolvedBase), "worktrees");
-        if (!cwd.startsWith(wtDir))
-            return false;
-        const branch = nativeGetCurrentBranch(cwd);
-        return branch.startsWith("milestone/");
-    }
-    // Fallback: infer worktree status structurally when originalBase is null
-    // (happens after session restart where module-level state is lost, #1120).
-    // Check if cwd is inside a .gsd/worktrees/ directory and has a .git file
-    // (worktree marker) pointing to the main repo.
-    const worktreeMarker = join(cwd, ".git");
-    if (!existsSync(worktreeMarker))
+    if (!originalBase)
         return false;
-    try {
-        const stat = statSync(worktreeMarker);
-        if (stat.isDirectory())
-            return false; // Main repo has .git dir, not file
-        // Worktrees have a .git file with "gitdir: ..." pointing to the main repo
-        const gitContent = readFileSync(worktreeMarker, "utf-8").trim();
-        if (!gitContent.startsWith("gitdir:"))
-            return false;
-        // Verify we're inside a GSD-managed worktree
-        if (!detectWorktreeName(cwd))
-            return false;
-        const branch = nativeGetCurrentBranch(cwd);
-        return branch.startsWith("milestone/");
-    }
-    catch {
+    const cwd = process.cwd();
+    const resolvedBase = existsSync(basePath) ? realpathSync(basePath) : basePath;
+    const wtDir = join(resolvedBase, ".gsd", "worktrees");
+    if (!cwd.startsWith(wtDir))
         return false;
-    }
+    const branch = nativeGetCurrentBranch(cwd);
+    return branch.startsWith("milestone/");
 }
 /**
  * Get the filesystem path for an auto-worktree, or null if it doesn't exist
@@ -418,23 +606,13 @@ export function enterAutoWorktree(basePath, milestoneId) {
             throw err;
         throw new GSDError(GSD_IO_ERROR, `Auto-worktree path ${p} exists but .git is unreadable`);
     }
-    // Ensure worktree shares external state via symlink (#1311).
-    // On resume (enterAutoWorktree), the symlink may be missing if it was
-    // created before ensureGsdSymlink existed, or the .gsd/ directory may be
-    // a stale git-tracked copy instead of a symlink. Refreshing here ensures
-    // the worktree sees the same milestone state as the main repo.
-    ensureGsdSymlink(p);
-    // Sync .gsd/ state from main repo into worktree (#1311).
-    // Covers the case where .gsd/ is a real directory (not symlinked) and
-    // milestones were created on main after the worktree was last used.
-    syncGsdStateToWorktree(basePath, p);
     const previousCwd = process.cwd();
     try {
         process.chdir(p);
         originalBase = basePath;
     }
     catch (err) {
-        throw new GSDError(GSD_IO_ERROR, `Failed to enter auto-worktree at ${p}: ${getErrorMessage(err)}`);
+        throw new GSDError(GSD_IO_ERROR, `Failed to enter auto-worktree at ${p}: ${err instanceof Error ? err.message : String(err)}`);
     }
     nudgeGitBranchCache(previousCwd);
     return p;
@@ -450,8 +628,10 @@ export function getActiveAutoWorktreeContext() {
     if (!originalBase)
         return null;
     const cwd = process.cwd();
-    const resolvedBase = existsSync(originalBase) ? realpathSync(originalBase) : originalBase;
-    const wtDir = join(gsdRoot(resolvedBase), "worktrees");
+    const resolvedBase = existsSync(originalBase)
+        ? realpathSync(originalBase)
+        : originalBase;
+    const wtDir = join(resolvedBase, ".gsd", "worktrees");
     if (!cwd.startsWith(wtDir))
         return null;
     const worktreeName = detectWorktreeName(cwd);
@@ -507,54 +687,34 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     const milestoneBranch = autoWorktreeBranch(milestoneId);
     // 1. Auto-commit dirty state in worktree before leaving
     autoCommitDirtyState(worktreeCwd);
+    // Reconcile worktree DB into main DB before leaving worktree context
+    if (isDbAvailable()) {
+        try {
+            const worktreeDbPath = join(worktreeCwd, ".gsd", "gsd.db");
+            const mainDbPath = join(originalBasePath_, ".gsd", "gsd.db");
+            reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
     // 2. Parse roadmap for slice listing
     const roadmap = parseRoadmap(roadmapContent);
-    const completedSlices = roadmap.slices.filter(s => s.done);
+    const completedSlices = roadmap.slices.filter((s) => s.done);
     // 3. chdir to original base
     const previousCwd = process.cwd();
     process.chdir(originalBasePath_);
-    // 3a. Auto-commit any dirty state in the project root. Without this, the
-    // squash merge can fail with "Your local changes would be overwritten" (#1127).
-    autoCommitDirtyState(originalBasePath_);
-    // 3b. Remove untracked .gsd/ runtime files that syncStateToProjectRoot copied.
-    // Only clean specific runtime files — NEVER touch milestones/, decisions, or
-    // other planning artifacts that represent user work (#1250).
-    const runtimeFilesToClean = ["STATE.md", "completed-units.json", "auto.lock", "gsd.db"];
-    for (const f of runtimeFilesToClean) {
-        const p = join(originalBasePath_, ".gsd", f);
-        try {
-            if (existsSync(p))
-                unlinkSync(p);
-        }
-        catch { /* non-fatal */ }
-    }
-    try {
-        const runtimeDir = join(originalBasePath_, ".gsd", "runtime");
-        if (existsSync(runtimeDir))
-            rmSync(runtimeDir, { recursive: true, force: true });
-    }
-    catch { /* non-fatal */ }
     // 4. Resolve integration branch — prefer milestone metadata, fall back to preferences / "main"
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
     const integrationBranch = readIntegrationBranch(originalBasePath_, milestoneId);
     const mainBranch = integrationBranch ?? prefs.main_branch ?? "main";
+    // Remove transient project-root state files before any branch or merge
+    // operation. Untracked milestone metadata can otherwise block squash merges.
+    clearProjectRootStateFiles(originalBasePath_, milestoneId);
     // 5. Checkout integration branch (skip if already current — avoids git error
     //    when main is already checked out in the project-root worktree, #757)
     const currentBranchAtBase = nativeGetCurrentBranch(originalBasePath_);
     if (currentBranchAtBase !== mainBranch) {
-        // Remove untracked .gsd/ state files that may conflict with the branch
-        // being checked out. These are regenerated by doctor/rebuildState and
-        // are not meaningful in the main working tree — the worktree had the
-        // real state. Without this, `git checkout main` fails with
-        // "Your local changes would be overwritten" (#827).
-        const gsdStateFiles = ["STATE.md", "completed-units.json", "auto.lock"];
-        for (const f of gsdStateFiles) {
-            const p = join(gsdRoot(originalBasePath_), f);
-            try {
-                unlinkSync(p);
-            }
-            catch { /* non-fatal — file may not exist */ }
-        }
         nativeCheckoutBranch(originalBasePath_, mainBranch);
     }
     // 6. Build rich commit message
@@ -562,7 +722,9 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     const subject = `feat(${milestoneId}): ${milestoneTitle}`;
     let body = "";
     if (completedSlices.length > 0) {
-        const sliceLines = completedSlices.map(s => `- ${s.id}: ${s.title}`).join("\n");
+        const sliceLines = completedSlices
+            .map((s) => `- ${s.id}: ${s.title}`)
+            .join("\n");
         body = `\n\nCompleted slices:\n${sliceLines}\n\nBranch: ${milestoneBranch}`;
     }
     const commitMessage = subject + body;
@@ -575,11 +737,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             : nativeConflictFiles(originalBasePath_);
         if (conflictedFiles.length > 0) {
             // Separate .gsd/ state file conflicts from real code conflicts.
-            // GSD state files (STATE.md, completed-units.json, auto.lock, etc.)
+            // GSD state files (STATE.md, auto.lock, etc.)
             // diverge between branches during normal operation — always prefer the
             // milestone branch version since it has the latest execution state.
-            const gsdConflicts = conflictedFiles.filter(f => f.startsWith(".gsd/"));
-            const codeConflicts = conflictedFiles.filter(f => !f.startsWith(".gsd/"));
+            const gsdConflicts = conflictedFiles.filter((f) => f.startsWith(".gsd/"));
+            const codeConflicts = conflictedFiles.filter((f) => !f.startsWith(".gsd/"));
             // Auto-resolve .gsd/ conflicts by accepting the milestone branch version
             if (gsdConflicts.length > 0) {
                 for (const gsdFile of gsdConflicts) {
@@ -646,7 +808,10 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     }
     // 10. Remove worktree directory first (must happen before branch deletion)
     try {
-        removeWorktree(originalBasePath_, milestoneId, { branch: null, deleteBranch: false });
+        removeWorktree(originalBasePath_, milestoneId, {
+            branch: null,
+            deleteBranch: false,
+        });
     }
     catch {
         // Best-effort -- worktree dir may already be gone