gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

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

@@ -9,7 +9,7 @@ import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync,
 import { isAbsolute, join, sep as pathSep } from "node:path";
 import { homedir } from "node:os";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
-import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, } from "./gsd-db.js";
+import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, closeDatabase, openDatabase, getDbPath, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
@@ -45,6 +45,67 @@ const ROOT_STATE_FILES = [
     // Back-sync (worktree → main) must NEVER overwrite the project root's copy
     // because the project root is authoritative for preferences (#2684).
 ];
+/**
+ * Pop a stash entry by tracking the unique marker embedded in its message so
+ * concurrent stash operations against the same project root cannot cause us to
+ * pop the wrong entry.
+ *
+ * If `stashMarker` is null or no longer present in the stash list (e.g. a
+ * concurrent process popped/dropped it), leaves the stash list untouched and
+ * returns null.
+ *
+ * Throws on pop failure so callers can handle conflict cases the same way
+ * they would with the prior `git stash pop` form. When throwing after a
+ * targeted pop attempt, the error is annotated with the targeted stash ref.
+ *
+ * (Issue #4980 HIGH-6)
+ */
+function popStashByRef(basePath, stashMarker) {
+    let popArg = null;
+    if (stashMarker) {
+        try {
+            const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            }).trim().split("\n").filter(Boolean);
+            for (const entry of list) {
+                const [ref, subject] = entry.split("\0");
+                if (ref && subject?.includes(stashMarker)) {
+                    popArg = ref;
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            logWarning("worktree", `stash list lookup failed; leaving stash untouched: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!popArg) {
+        logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic pop");
+        return null;
+    }
+    try {
+        execFileSync("git", ["stash", "pop", popArg], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch (err) {
+        if (err && typeof err === "object") {
+            err.stashRef = popArg;
+        }
+        throw err;
+    }
+    return popArg;
+}
+function stashRefFromError(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const stashRef = err.stashRef;
+    return typeof stashRef === "string" && stashRef.length > 0 ? stashRef : null;
+}
 /**
  * Check if two filesystem paths resolve to the same real location.
  * Returns false if either path cannot be resolved (e.g. doesn't exist).
@@ -180,14 +241,6 @@ function clearProjectRootStateFiles(basePath, milestoneId) {
         }
     }
 }
-function isProjectGsdSymlink(basePath) {
-    try {
-        return lstatSyncFn(join(basePath, ".gsd")).isSymbolicLink();
-    }
-    catch {
-        return false;
-    }
-}
 // ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
 /** Patterns for machine-generated build artifacts that can be safely
  * auto-resolved by accepting --theirs during merge. These files are
@@ -836,6 +889,27 @@ export function enterBranchModeForMilestone(basePath, milestoneId) {
         const startPoint = integrationBranch ??
             validatedPrefBranch ??
             nativeDetectMainBranch(basePath);
+        // TOCTOU ancestry guard (Issue #4980 HIGH-3).
+        //
+        // The outer `branchExists` check at line 1012 is racy: a concurrent
+        // process (parallel-orchestrator worker, side-by-side `gsd` instance,
+        // or manual `git branch` invocation) may have created the branch with
+        // real commits between that check and this point. `nativeBranchForceReset`
+        // does `git branch -f`, which silently overwrites the branch ref —
+        // orphaning any commits not reachable from `startPoint`. Re-check
+        // immediately before the destructive call and refuse if the branch
+        // suddenly exists with non-ancestor commits.
+        //
+        // Note: under single-threaded execution this is rarely reached, but it
+        // is NOT dead code — it is the only barrier against a TOCTOU-induced
+        // commit loss in this code path.
+        const concurrentlyCreated = nativeBranchExists(basePath, branch);
+        if (concurrentlyCreated &&
+            !nativeIsAncestor(basePath, branch, startPoint)) {
+            throw new GSDError(GSD_GIT_ERROR, `Branch "${branch}" was created concurrently with commits not reachable from "${startPoint}". ` +
+                `Refusing to force-reset — would orphan prior work. ` +
+                `Resume the existing milestone or run \`git branch -D ${branch}\` to discard.`);
+        }
         // nativeBranchForceReset creates (or resets) branch at startPoint,
         // then checkout switches HEAD to it.
         nativeBranchForceReset(basePath, branch, startPoint);
@@ -1353,7 +1427,17 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     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)
+    //
+    // Refuse to proceed if the project root is in detached HEAD state. Silently
+    // running `nativeCheckoutBranch(mainBranch)` on a detached HEAD would
+    // abandon the user's deliberately-checked-out commit (mid-bisect, reviewing
+    // a tag, CI checkout-sha) without warning. (Issue #4980 HIGH-10)
     const currentBranchAtBase = nativeGetCurrentBranch(originalBasePath_);
+    if (!currentBranchAtBase || currentBranchAtBase.length === 0) {
+        process.chdir(previousCwd);
+        throw new GSDError(GSD_GIT_ERROR, `Project root is in detached HEAD state — cannot perform milestone merge. ` +
+            `Checkout an integration branch (e.g. \`git checkout ${mainBranch}\`) before resuming.`);
+    }
     if (currentBranchAtBase !== mainBranch) {
         nativeCheckoutBranch(originalBasePath_, mainBranch);
     }
@@ -1429,73 +1513,65 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             });
         }
     }
-    // 7. Stash any pre-existing dirty files so the squash merge is not
-    //    blocked by unrelated local changes (#2151).  clearProjectRootStateFiles
-    //    only removes untracked .gsd/ files; tracked dirty files elsewhere (e.g.
-    //    .planning/work-state.json with stash conflict markers) are invisible to
-    //    that cleanup but will cause `git merge --squash` to reject.
-    let stashed = false;
-    try {
-        const status = execFileSync("git", ["status", "--porcelain"], {
-            cwd: originalBasePath_,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        }).trim();
-        if (status) {
-            // Use --include-untracked to stash untracked files that would block
-            // the squash merge, but EXCLUDE .gsd/milestones/ (#2505).
-            // --include-untracked without exclusion sweeps queued milestone
-            // CONTEXT files into the stash. If stash pop later fails, those files
-            // are permanently trapped in the stash entry and lost on the next
-            // stash push or drop.
-            //
-            // When `.gsd` itself is a symlink, Git rejects pathspecs below it
-            // ("beyond a symbolic link"). In that layout, exclude the whole symlink
-            // and keep stashing real project files that could block the merge.
-            const stashPathspecs = isProjectGsdSymlink(originalBasePath_)
-                ? [".", ":(exclude).gsd"]
-                : [":(exclude).gsd/milestones"];
-            execFileSync("git", [
-                "stash", "push", "--include-untracked",
-                "-m", `gsd: pre-merge stash for ${milestoneId}`,
-                "--", ...stashPathspecs,
-            ], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
-            stashed = true;
-        }
-    }
-    catch (err) {
-        // Stash failure is non-fatal — proceed without stash and let the merge
-        // report the dirty tree if it fails.
-        logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    // 7a. Shelter queued milestone directories before the squash merge (#2505).
+    // 7. Shelter queued milestone directories before the squash merge (#2505).
     // The milestone branch may contain copies of queued milestone dirs (via
     // copyPlanningArtifacts), so `git merge --squash` rejects when those same
     // files exist as untracked in the working tree. Temporarily move them to
     // a backup location, then restore after the merge+commit.
+    //
+    // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
+    // does not sweep queued CONTEXT files into the stash. If stash pop later
+    // fails, files trapped inside the stash are permanently lost (#2505).
     const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
     const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
     const shelteredDirs = [];
+    let shelterRestored = false;
     // Helper: restore sheltered milestone directories (#2505).
     // Called on both success and error paths to ensure queued CONTEXT files
-    // are never permanently lost.
+    // are never permanently lost. Idempotent — the error path may fire after
+    // the success path has already restored and removed the shelter dir; a
+    // second call is a no-op instead of logging a misleading "shelter restore
+    // failed: ENOENT" error for shelter sources that were cleaned up legitimately.
     const restoreShelter = () => {
+        if (shelterRestored)
+            return;
+        shelterRestored = true;
         if (shelteredDirs.length === 0)
             return;
+        let restoreFailed = false;
         for (const dirName of shelteredDirs) {
+            const src = join(shelterDir, dirName);
+            // If the shelter source is missing the restore cannot proceed for this
+            // entry. Distinguish "legitimately missing" (shelter dir removed by a
+            // prior successful restore or never copied) from a surprising ENOENT
+            // inside an otherwise-populated shelter.
+            if (!existsSync(src)) {
+                logWarning("worktree", `shelter source missing for ${dirName}; skipping restore (shelter already cleaned or entry never staged)`);
+                continue;
+            }
             try {
                 mkdirSync(milestonesDir, { recursive: true });
-                cpSync(join(shelterDir, dirName), join(milestonesDir, dirName), { recursive: true, force: true });
+                cpSync(src, join(milestonesDir, dirName), { recursive: true, force: true });
             }
             catch (err) { /* best-effort */
-                logError("worktree", `shelter restore failed: ${err instanceof Error ? err.message : String(err)}`);
+                restoreFailed = true;
+                logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        try {
-            rmSync(shelterDir, { recursive: true, force: true });
+        // Preserve the shelter if any per-entry restore failed — it is the only
+        // surviving copy of the queued milestone dirs (sources were deleted during
+        // shelter). Deleting it here would permanently lose those files (#2505).
+        if (restoreFailed) {
+            logWarning("worktree", `shelter retained at ${shelterDir} — manual recovery required for unrestored entries`);
+            return;
         }
-        catch (err) { /* best-effort */
-            logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        if (existsSync(shelterDir)) {
+            try {
+                rmSync(shelterDir, { recursive: true, force: true });
+            }
+            catch (err) { /* best-effort */
+                logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     };
     try {
@@ -1526,6 +1602,60 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         // Non-fatal — proceed with merge; untracked files may block it
         logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    // 7a. Stash pre-existing dirty files so the squash merge is not blocked by
+    //     unrelated local changes (#2151). Includes untracked files to handle
+    //     locally-added files that conflict with tracked files on the milestone
+    //     branch. Passing NO pathspec lets git skip gitignored paths silently;
+    //     adding an explicit pathspec trips a `git add`-style fatal on ignored
+    //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
+    //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
+    //     in step 7 above, so they won't be swept into the stash.
+    // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
+    // sidecars while the connection is open. `git stash --include-untracked`
+    // walks those files and fails with EBUSY (#4704). Close the DB before
+    // stashing so Windows releases the handles; reopen after. No-op on
+    // POSIX, where advisory locks don't block git.
+    const needsDbCycle = process.platform === "win32" && isDbAvailable();
+    const dbPathToReopen = needsDbCycle ? getDbPath() : null;
+    if (needsDbCycle) {
+        try {
+            closeDatabase();
+        }
+        catch (err) {
+            logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    let stashed = false;
+    // Embed a unique marker in the stash message so subsequent pop/drop targets
+    // the entry we created, not whatever happens to be at stash@{0} (concurrent
+    // milestone merges share the project-root stash list and can shift positions).
+    // (Issue #4980 HIGH-6)
+    let stashMarker = null;
+    try {
+        const status = execFileSync("git", ["status", "--porcelain"], {
+            cwd: originalBasePath_,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+        if (status) {
+            stashMarker = `gsd-pre-merge:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+            execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId} [${stashMarker}]`], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+            stashed = true;
+        }
+    }
+    catch (err) {
+        // Stash failure is non-fatal — proceed without stash and let the merge
+        // report the dirty tree if it fails.
+        logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    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
@@ -1565,11 +1695,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             // Pop stash before throwing so local work is not lost.
             if (stashed) {
                 try {
-                    execFileSync("git", ["stash", "pop"], {
-                        cwd: originalBasePath_,
-                        stdio: ["ignore", "pipe", "pipe"],
-                        encoding: "utf-8",
-                    });
+                    popStashByRef(originalBasePath_, stashMarker);
                 }
                 catch (err) { /* stash pop conflict is non-fatal */
                     logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1637,11 +1763,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 // Pop stash before throwing so local work is not lost (#2151).
                 if (stashed) {
                     try {
-                        execFileSync("git", ["stash", "pop"], {
-                            cwd: originalBasePath_,
-                            stdio: ["ignore", "pipe", "pipe"],
-                            encoding: "utf-8",
-                        });
+                        popStashByRef(originalBasePath_, stashMarker);
                     }
                     catch (err) { /* stash pop conflict is non-fatal */
                         logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1684,14 +1806,12 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // or the commit content.  Conflict on pop is non-fatal — the stash entry is
     // preserved and the user can resolve manually with `git stash pop`.
     if (stashed) {
+        let stashRefForDrop = null;
         try {
-            execFileSync("git", ["stash", "pop"], {
-                cwd: originalBasePath_,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-            });
+            stashRefForDrop = popStashByRef(originalBasePath_, stashMarker);
         }
         catch (e) {
+            stashRefForDrop = stashRefFromError(e);
             logWarning("worktree", `git stash pop failed, attempting conflict resolution: ${e.message}`);
             // Stash pop after squash merge can conflict on .gsd/ state files that
             // diverged between branches.  Left unresolved, these UU entries block
@@ -1719,25 +1839,33 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                     }
                 }
             }
-            if (nonGsdUU.length === 0) {
+            if (gsdUU.length > 0 && nonGsdUU.length === 0) {
                 // All conflicts were .gsd/ files — safe to drop the stash
-                try {
-                    execFileSync("git", ["stash", "drop"], {
-                        cwd: originalBasePath_,
-                        stdio: ["ignore", "pipe", "pipe"],
-                        encoding: "utf-8",
-                    });
+                if (stashRefForDrop) {
+                    try {
+                        execFileSync("git", ["stash", "drop", stashRefForDrop], {
+                            cwd: originalBasePath_,
+                            stdio: ["ignore", "pipe", "pipe"],
+                            encoding: "utf-8",
+                        });
+                    }
+                    catch (err) { /* stash may already be consumed */
+                        logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
-                catch (err) { /* stash may already be consumed */
-                    logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+                else {
+                    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
                 }
             }
-            else {
+            else if (nonGsdUU.length > 0) {
                 // Non-.gsd conflicts remain — leave stash for manual resolution
                 logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
                     files: nonGsdUU.join(", "),
                 });
             }
+            else {
+                logWarning("worktree", "git stash pop failed without resolvable conflict files; leaving stash for manual recovery");
+            }
         }
     }
     // 9a-iii. Restore sheltered queued milestone directories (#2505).
@@ -1761,16 +1889,32 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // When a milestone only produced .gsd/ metadata (summaries, roadmaps) but no
     // real code, the user sees "milestone complete" but nothing changed in their
     // codebase. Surface this so the caller can warn the user.
+    //
+    // Bug #4385 fix: use `git diff-tree --root` instead of `git diff HEAD~1 HEAD`.
+    // `HEAD~1` does not exist on initial commits and is unreliable on shallow clones
+    // and merge commits. `diff-tree --root` handles all three cases correctly.
+    // The empty-tree hash (4b825dc…) is the universal fallback for refs that don't exist.
+    const GIT_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
     let codeFilesChanged = false;
     if (!nothingToCommit) {
         try {
-            const mergedFiles = nativeDiffNumstat(originalBasePath_, "HEAD~1", "HEAD");
-            codeFilesChanged = mergedFiles.some((entry) => !entry.path.startsWith(".gsd/"));
+            const diffTreeOutput = execFileSync("git", ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+            const mergedFiles = diffTreeOutput ? diffTreeOutput.split("\n").filter(Boolean) : [];
+            codeFilesChanged = mergedFiles.some((f) => !f.startsWith(".gsd/"));
         }
         catch (e) {
-            // If HEAD~1 doesn't exist (first commit), assume code was changed
-            logWarning("worktree", `diff numstat failed (assuming code changed): ${e.message}`);
-            codeFilesChanged = true;
+            // diff-tree failed (e.g. unborn HEAD in a brand-new repo) — fall back to
+            // comparing against the empty tree so initial-commit repos still report changes.
+            try {
+                const fallbackOutput = execFileSync("git", ["diff", "--name-only", GIT_EMPTY_TREE, "HEAD"], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+                const fallbackFiles = fallbackOutput ? fallbackOutput.split("\n").filter(Boolean) : [];
+                codeFilesChanged = fallbackFiles.some((f) => !f.startsWith(".gsd/"));
+            }
+            catch {
+                // Truly unable to determine — assume code was changed to avoid silent data loss
+                logWarning("worktree", `diff-tree and empty-tree fallback both failed (assuming code changed): ${e.message}`);
+                codeFilesChanged = true;
+            }
         }
     }
     // 10. Auto-push if enabled