@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

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

@@ -0,0 +1,168 @@
+// gsd-pi — Pre-merge stash handling for auto-worktree merge closeout.
+//
+// Owns the local-work protection around milestone merge: stash before merge,
+// DB handle cycling for Windows, restoring on merge failures, and post-commit
+// stash-pop conflict recovery.
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { closeWorkflowDatabase, getWorkflowDatabasePath, openWorkflowDatabasePath, } from "./db-workspace.js";
+import { nativeAddPaths, nativeConflictFiles, nativeLsFiles, nativeRmForce, } from "./native-git-bridge.js";
+import { gsdJsonlFilesWithConflictMarkers, hasConflictMarkers, popStashByRef, stashAlreadyExistsFilesFromError, stashRefFromError, } from "./worktree-git-recovery.js";
+import { logWarning } from "./workflow-logger.js";
+export function createPreMergeStash(basePath, milestoneId, cycleDbHandles) {
+    let stashed = false;
+    let marker = null;
+    const dbPathToReopen = cycleDbHandles ? getWorkflowDatabasePath() : null;
+    return {
+        stash() {
+            closeDbBeforeStashIfNeeded(cycleDbHandles);
+            try {
+                const status = execFileSync("git", ["status", "--porcelain"], {
+                    cwd: basePath,
+                    stdio: ["ignore", "pipe", "pipe"],
+                    encoding: "utf-8",
+                }).trim();
+                if (!status)
+                    return;
+                marker = createStashMarker(milestoneId);
+                execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId} [${marker}]`], { cwd: basePath, 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)}`);
+            }
+        },
+        reopenDbAfterMerge() {
+            if (!cycleDbHandles || !dbPathToReopen)
+                return;
+            try {
+                openWorkflowDatabasePath(dbPathToReopen);
+            }
+            catch (err) {
+                logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+        restoreForMergeFailure() {
+            if (!stashed)
+                return;
+            try {
+                popStashByRef(basePath, marker);
+            }
+            catch (err) {
+                logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+        restoreAfterCommit() {
+            if (!stashed)
+                return;
+            restoreStashAfterCommit(basePath, marker);
+        },
+    };
+}
+function closeDbBeforeStashIfNeeded(cycleDbHandles) {
+    if (!cycleDbHandles)
+        return;
+    try {
+        closeWorkflowDatabase();
+    }
+    catch (err) {
+        logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function createStashMarker(milestoneId) {
+    return `gsd-pre-merge:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+}
+function restoreStashAfterCommit(basePath, marker) {
+    let stashRefForDrop = null;
+    try {
+        stashRefForDrop = popStashByRef(basePath, marker);
+    }
+    catch (e) {
+        stashRefForDrop = stashRefFromError(e);
+        logWarning("worktree", `git stash pop failed, attempting conflict resolution: ${e.message}`);
+        resolveStashPopConflict(basePath, e, stashRefForDrop);
+    }
+}
+function resolveStashPopConflict(basePath, error, stashRefForDrop) {
+    const uu = nativeConflictFiles(basePath);
+    const gsdUU = uu.filter((f) => f.startsWith(".gsd/"));
+    const nonGsdUU = uu.filter((f) => !f.startsWith(".gsd/"));
+    const stashPopMessage = error instanceof Error ? error.message : String(error);
+    const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+    const gsdContentConflicts = [];
+    const alreadyExists = stashAlreadyExistsFilesFromError(error);
+    if (isUntrackedRestoreFailure) {
+        gsdContentConflicts.push(...gsdJsonlFilesWithConflictMarkers(basePath));
+    }
+    const gsdConflictFiles = [...new Set([...gsdUU, ...gsdContentConflicts])];
+    resolveGsdConflictFiles(basePath, gsdConflictFiles);
+    if (gsdConflictFiles.length > 0 && nonGsdUU.length === 0) {
+        dropStashIfNoNonGsdConflictsRemain(basePath, stashRefForDrop);
+        return;
+    }
+    if (gsdUU.length === 0 && nonGsdUU.length === 0 && alreadyExists.length > 0) {
+        dropRecordedStash(basePath, stashRefForDrop);
+        return;
+    }
+    if (nonGsdUU.length > 0) {
+        logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
+            files: nonGsdUU.join(", "),
+        });
+        return;
+    }
+    logWarning("worktree", "git stash pop failed without resolvable conflict files; leaving stash for manual recovery");
+}
+function resolveGsdConflictFiles(basePath, conflictFiles) {
+    for (const file of conflictFiles) {
+        try {
+            // Accept the committed (HEAD) version of the state file.
+            execFileSync("git", ["checkout", "HEAD", "--", file], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            });
+            nativeAddPaths(basePath, [file]);
+        }
+        catch (err) {
+            // Last resort: remove the conflicted state file.
+            logWarning("worktree", `checkout HEAD failed for ${file}, removing: ${err.message}`);
+            nativeRmForce(basePath, [file]);
+        }
+    }
+}
+function dropStashIfNoNonGsdConflictsRemain(basePath, stashRefForDrop) {
+    const remainingUnmerged = nativeConflictFiles(basePath);
+    const nonGsdUnmerged = remainingUnmerged.filter((f) => !f.startsWith(".gsd/"));
+    const markerCandidates = Array.from(new Set([
+        ...nonGsdUnmerged,
+        ...nativeLsFiles(basePath, "."),
+    ])).filter((f) => !f.startsWith(".gsd/"));
+    const nonGsdMarkerConflicts = markerCandidates.filter((f) => hasConflictMarkers(join(basePath, f)));
+    const hasRemainingNonGsdConflicts = nonGsdUnmerged.length > 0 || nonGsdMarkerConflicts.length > 0;
+    if (hasRemainingNonGsdConflicts) {
+        const files = Array.from(new Set([...nonGsdUnmerged, ...nonGsdMarkerConflicts]));
+        logWarning("reconcile", "Leaving stash because non-.gsd conflicts remain after auto-resolution", {
+            files: files.join(", "),
+        });
+        return;
+    }
+    dropRecordedStash(basePath, stashRefForDrop);
+}
+function dropRecordedStash(basePath, stashRefForDrop) {
+    if (!stashRefForDrop) {
+        logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
+        return;
+    }
+    try {
+        execFileSync("git", ["stash", "drop", stashRefForDrop], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch (err) {
+        logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

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

@@ -0,0 +1,302 @@
+// gsd-pi — Auto-worktree merge module.
+//
+// Owns milestone merge/closeout for auto-worktrees: dirty-state capture, DB
+// reconciliation, integration-branch merge, stash/shelter recovery, publication,
+// and safe teardown.
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
+import { MergeConflictError, RUNTIME_EXCLUSION_PATHS, } from "./git-service.js";
+import { getMilestone, isDbAvailable, } from "./gsd-db.js";
+import { nativeAddAllWithExclusions, nativeCommit, nativeConflictFiles, nativeGetCurrentBranch, nativeMergeRegular, nativeMergeSquash, nativeWorkingTreeStatus, } from "./native-git-bridge.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { publishMilestone } from "./publication.js";
+import { autoWorktreeBranch, } from "./auto-worktree-branch-lifecycle.js";
+import { createMilestoneDirectoryShelter } from "./auto-worktree-milestone-shelter.js";
+import { getActiveWorkspace } from "./auto-worktree-session-registry.js";
+import { assertNoUnanchoredCodeChangesAfterEmptyMerge, detectMergedCodeFilesChanged, } from "./auto-worktree-merge-code-changes.js";
+import { reconcileMilestoneBranchHead } from "./auto-worktree-merge-branch-head.js";
+import { finalizeAlreadyMergedMilestoneIfReachable } from "./auto-worktree-merge-already-merged.js";
+import { cleanupMergedMilestoneWorktree } from "./auto-worktree-merge-cleanup.js";
+import { assertMilestoneDbReadyForMerge } from "./auto-worktree-merge-db-ready.js";
+import { prepareIntegrationBranchForMilestoneMerge } from "./auto-worktree-merge-integration-branch.js";
+import { buildMilestoneMergeMessage } from "./auto-worktree-merge-message.js";
+import { assertMilestoneWorktreeCleanBeforeTeardown } from "./auto-worktree-merge-pre-teardown.js";
+import { createPreMergeStash } from "./auto-worktree-merge-stash.js";
+import { cleanupConflictState, removeMergeStateFiles, } from "./worktree-git-recovery.js";
+import { logWarning } from "./workflow-logger.js";
+export { _setRestoreEntryFnForTests } from "./auto-worktree-milestone-shelter.js";
+// ─── Merge Milestone -> Main ───────────────────────────────────────────────
+/**
+ * Auto-commit any dirty (uncommitted) state in the given directory.
+ * Returns true if a commit was made, false if working tree was clean.
+ */
+function autoCommitDirtyState(cwd) {
+    try {
+        const status = nativeWorkingTreeStatus(cwd);
+        if (!status)
+            return false;
+        nativeAddAllWithExclusions(cwd, RUNTIME_EXCLUSION_PATHS);
+        const result = nativeCommit(cwd, "chore: auto-commit before milestone merge");
+        return result !== null;
+    }
+    catch (e) {
+        debugLog("autoCommitDirtyState", { error: String(e) });
+        throw new GSDError(GSD_GIT_ERROR, `Failed to auto-commit dirty worktree state before milestone merge: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * Squash-merge the milestone branch into main with a rich commit message
+ * listing all completed slices, then tear down the worktree.
+ *
+ * Sequence:
+ *  1. Auto-commit dirty worktree state
+ *  2. chdir to originalBasePath
+ *  3. git checkout main
+ *  4. git merge --squash milestone/<MID>
+ *  5. git commit with rich message
+ *  6. Auto-push if enabled
+ *  7. Delete milestone branch
+ *  8. Remove worktree directory
+ *  9. Clear originalBase
+ *
+ * On merge conflict: throws MergeConflictError.
+ * On "nothing to commit" after squash: safe only if milestone work is already
+ * on the integration branch.  Throws if unanchored code changes would be lost.
+ *
+ * @internal **Do not call directly.** This is the inner squash-merge primitive
+ * for the Worktree Lifecycle Module (ADR-016 phase 2 / A3, issue #5619).
+ * Production callers must go through `WorktreeLifecycle.mergeMilestoneStandalone`
+ * or `WorktreeLifecycle.exitMilestone({ merge: true })`. The export keyword
+ * is preserved for legacy tests and the default transaction adapter; production
+ * wiring depends on `createDefaultMilestoneMergeTransaction()` instead.
+ */
+export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapContent) {
+    const worktreeCwd = process.cwd();
+    const milestoneBranch = autoWorktreeBranch(milestoneId);
+    // 1. Auto-commit dirty state before leaving.
+    //    Guard: when we entered through an auto-worktree (originalBase is set),
+    //    only auto-commit when cwd is on the milestone branch. In parallel mode,
+    //    cwd may be on the integration branch after a prior merge's
+    //    MergeConflictError left cwd unrestored. Auto-committing on the
+    //    integration branch captures dirty files from OTHER milestones under a
+    //    misleading commit message, contaminating the main branch (#2929).
+    //
+    //    When activeWorkspace is null (branch mode, no worktree), autoCommitDirtyState
+    //    runs unconditionally — the caller is responsible for cwd placement.
+    {
+        let shouldAutoCommit = true;
+        if (getActiveWorkspace() !== null) {
+            try {
+                const currentBranch = nativeGetCurrentBranch(worktreeCwd);
+                shouldAutoCommit = currentBranch === milestoneBranch;
+            }
+            catch {
+                // If we can't determine the branch, skip the auto-commit to be safe
+                shouldAutoCommit = false;
+            }
+        }
+        if (shouldAutoCommit) {
+            autoCommitDirtyState(worktreeCwd);
+        }
+    }
+    // Reconcile DB state and prove closeout before leaving worktree context.
+    assertMilestoneDbReadyForMerge({
+        milestoneId,
+        projectRoot: originalBasePath_,
+        worktreeCwd,
+    });
+    // 2. Build completed-slice summaries and rich commit message.
+    const { commitMessage, milestoneTitle, sliceSummaries } = buildMilestoneMergeMessage({
+        milestoneId,
+        milestoneBranch,
+        roadmapContent,
+    });
+    // 3. chdir to original base
+    // Note: previousCwd captures the cwd at this point — i.e. the worktree cwd
+    // entering the function. Subsequent throws restore to previousCwd, leaving
+    // the caller in worktree-cwd; callers (worktree-resolver) are responsible
+    // for any further cwd movement on the error path.
+    const previousCwd = process.cwd();
+    process.chdir(originalBasePath_);
+    // 4/5. Resolve and prepare the integration branch. The integration-branch
+    //      module owns stale metadata fallback, self-merge fail-closed behavior,
+    //      detached HEAD protection, transient state cleanup, and checkout.
+    const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+    const { mainBranch } = prepareIntegrationBranchForMilestoneMerge({
+        milestoneBranch,
+        milestoneId,
+        prefs,
+        previousCwd,
+        projectRoot: originalBasePath_,
+    });
+    // 6b. Reconcile worktree HEAD with milestone branch ref (#1846).
+    //     The branch-head module owns the data-loss guard: fast-forward stale
+    //     branch refs to detached worktree commits, and fail loudly on divergence.
+    reconcileMilestoneBranchHead({
+        projectRoot: originalBasePath_,
+        worktreeCwd,
+        milestoneBranch,
+        previousCwd,
+    });
+    // Already regular-merged milestones can skip the squash path and proceed to cleanup (#5831).
+    const alreadyMerged = finalizeAlreadyMergedMilestoneIfReachable({
+        projectRoot: originalBasePath_,
+        milestoneId,
+        milestoneBranch,
+        mainBranch,
+        previousCwd,
+        commitMessage,
+    });
+    if (alreadyMerged)
+        return alreadyMerged;
+    // 7. Shelter queued milestone directories before the squash merge (#2505).
+    // MUST run before the pre-merge stash so queued CONTEXT files are not swept
+    // into a stash that may later fail to pop and strand user work.
+    const milestoneDirectoryShelter = createMilestoneDirectoryShelter(originalBasePath_, milestoneId, getMilestone(milestoneId)?.title);
+    // 7a. Stash pre-existing dirty files so the squash merge is not blocked by
+    //     unrelated local changes (#2151). The stash module also owns Windows DB
+    //     handle cycling and later stash-pop conflict recovery.
+    const preMergeStash = createPreMergeStash(originalBasePath_, milestoneId, process.platform === "win32" && isDbAvailable());
+    preMergeStash.stash();
+    // 7b. Clean up stale merge state before attempting the merge (#2912).
+    // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path,
+    // or interrupted operation) causes git merge to refuse with
+    // "fatal: You have not concluded your merge (MERGE_HEAD exists)".
+    // Defensively remove merge artifacts before starting.
+    removeMergeStateFiles(originalBasePath_, "pre-merge");
+    // 8. Merge — respect merge_strategy preference (#549).
+    // "squash" (default): stages changes without a merge commit; caller commits.
+    // "merge": --no-ff --no-commit so caller can supply the commit message while
+    // git records a real merge commit (MERGE_HEAD present when nativeCommit runs).
+    const effectiveStrategy = prefs.merge_strategy === "merge" ? "merge" : "squash";
+    const mergeResult = effectiveStrategy === "merge"
+        ? nativeMergeRegular(originalBasePath_, milestoneBranch)
+        : nativeMergeSquash(originalBasePath_, milestoneBranch);
+    preMergeStash.reopenDbAfterMerge();
+    if (!mergeResult.success) {
+        // Dirty working tree — the merge was rejected before it started (e.g.
+        // untracked .gsd/ files left by syncStateToProjectRoot).  Preserve the
+        // milestone branch so commits are not lost.
+        if (mergeResult.conflicts.includes("__dirty_working_tree__")) {
+            // Defensively clean merge state — the native path may leave MERGE_HEAD
+            // even when the merge is rejected (#2912).
+            removeMergeStateFiles(originalBasePath_, "dirty-tree rejection");
+            // Pop stash before throwing so local work is not lost.
+            preMergeStash.restoreForMergeFailure();
+            milestoneDirectoryShelter.restore();
+            // Restore cwd so the caller is not stranded on the integration branch
+            process.chdir(previousCwd);
+            // Surface the actual dirty filenames from git stderr instead of
+            // generically blaming .gsd/ (#2151).
+            const fileList = mergeResult.dirtyFiles?.length
+                ? `Dirty files:\n${mergeResult.dirtyFiles.map((f) => `  ${f}`).join("\n")}`
+                : `Check \`git status\` in the project root for details.`;
+            throw new GSDError(GSD_GIT_ERROR, `${effectiveStrategy === "merge" ? "Merge" : "Squash merge"} of ${milestoneBranch} rejected: working tree has dirty or untracked files ` +
+                `that conflict with the merge. ${fileList}`);
+        }
+        // Check for conflicts — use merge result first, fall back to nativeConflictFiles
+        const conflictedFiles = mergeResult.conflicts.length > 0
+            ? mergeResult.conflicts
+            : nativeConflictFiles(originalBasePath_);
+        if (conflictedFiles.length > 0) {
+            // Separate auto-resolvable conflicts (GSD state files + build artifacts)
+            // from real code conflicts. GSD state files diverge between branches
+            // during normal operation. Build artifacts are machine-generated and
+            // regenerable. Both are safe to accept from the milestone branch.
+            const { resolved: autoResolved, remaining: codeConflicts } = autoResolveSafeConflictPaths(originalBasePath_, conflictedFiles);
+            if (autoResolved.length > 0) {
+                logWarning("worktree", `auto-resolved safe merge conflicts: ${autoResolved.join(", ")}`);
+            }
+            // If there are still real code conflicts, escalate
+            if (codeConflicts.length > 0) {
+                cleanupConflictState(originalBasePath_);
+                // Pop stash before throwing so local work is not lost (#2151).
+                preMergeStash.restoreForMergeFailure();
+                milestoneDirectoryShelter.restore();
+                // Restore cwd so the caller is not stranded on the integration branch.
+                // Without this, the next mergeMilestoneToMain call in a parallel merge
+                // sequence uses process.cwd() (now the project root) as worktreeCwd,
+                // causing autoCommitDirtyState to commit unrelated milestone files to
+                // the integration branch (#2929).
+                process.chdir(previousCwd);
+                throw new MergeConflictError(codeConflicts, effectiveStrategy, milestoneBranch, mainBranch);
+            }
+        }
+        // No conflicts detected — possibly "already up to date", fall through to commit
+    }
+    // 9. Commit (handle nothing-to-commit gracefully)
+    const commitResult = nativeCommit(originalBasePath_, commitMessage);
+    const nothingToCommit = commitResult === null;
+    // 9a. Clean up merge state files left by git merge --squash (#1853, #2912).
+    // git only removes SQUASH_MSG when the commit reads it directly (plain
+    // `git commit`).  nativeCommit uses `-F -` (stdin) or libgit2, neither
+    // of which trigger git's SQUASH_MSG cleanup.  MERGE_HEAD is created by
+    // libgit2's merge even in squash mode and is not removed by nativeCommit.
+    // If left on disk, doctor reports `corrupt_merge_state` on every subsequent run.
+    removeMergeStateFiles(originalBasePath_, "post-commit");
+    // 9a-ii. Restore stashed files now that the merge+commit is complete (#2151).
+    preMergeStash.restoreAfterCommit();
+    // 9a-iii. Restore sheltered queued milestone directories (#2505).
+    milestoneDirectoryShelter.restore();
+    // 9b. Safety check (#1792): if nothing was committed, verify the milestone
+    // work is already on the integration branch before allowing teardown.
+    try {
+        assertNoUnanchoredCodeChangesAfterEmptyMerge(originalBasePath_, mainBranch, milestoneBranch, effectiveStrategy, nothingToCommit);
+    }
+    catch (err) {
+        process.chdir(previousCwd);
+        throw err;
+    }
+    // 9c. Detect whether any non-.gsd/ code files were actually merged (#1906).
+    const codeFilesChanged = detectMergedCodeFilesChanged(originalBasePath_, nothingToCommit);
+    const finalizeMilestoneCleanup = () => {
+        cleanupMergedMilestoneWorktree({
+            projectRoot: originalBasePath_,
+            milestoneId,
+            milestoneBranch,
+            previousCwd,
+            chdirWarningContext: "after merge",
+        });
+    };
+    let shouldCleanup = false;
+    try {
+        // 10/9b. Publication (auto-push / draft PR) — Publication module seam (ADR-034).
+        const publication = publishMilestone({
+            basePath: originalBasePath_,
+            milestoneId,
+            milestoneTitle,
+            integrationBranch: mainBranch,
+            milestoneBranch,
+            sliceSummaries,
+            nothingToCommit,
+            prefs: {
+                autoPush: prefs.auto_push === true,
+                autoPr: prefs.auto_pr === true,
+                remote: prefs.remote,
+                prTargetBranch: prefs.pr_target_branch,
+            },
+        });
+        const { pushed, prCreated } = publication;
+        // 11. Guard removed — step 9b (#1792) now handles this with a smarter check:
+        //     throws only when the milestone has unanchored code changes, passes
+        //     through when the code is genuinely already on the integration branch.
+        // 11a. Pre-teardown safety net (#1853): preserve the milestone branch if
+        // the source worktree still has uncommitted changes after the merge commit.
+        assertMilestoneWorktreeCleanBeforeTeardown({
+            milestoneBranch,
+            previousCwd,
+            worktreeCwd,
+        });
+        shouldCleanup = true;
+        return { commitMessage, pushed, prCreated, codeFilesChanged };
+    }
+    finally {
+        if (shouldCleanup) {
+            finalizeMilestoneCleanup();
+        }
+        else {
+            logWarning("worktree", `Skipping worktree cleanup for ${milestoneBranch}; merge did not reach safe-cleanup point and milestone work is preserved for manual recovery.`);
+        }
+    }
+}

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

@@ -0,0 +1,119 @@
+// gsd-pi — Milestone directory shelter for auto-worktree merge closeout.
+//
+// Owns the #2505 queued-milestone directory protection step that runs before
+// merge stash handling. This keeps queued CONTEXT files out of the stash and
+// restores them after merge closeout without hiding restore failures.
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { canonicalPhaseDirName, gsdRoot, milestonesDir, resolveMilestonePath, } from "./paths.js";
+import { logError, logWarning } from "./workflow-logger.js";
+/**
+ * Optional override for the shelter restore copy step (milestone merge #2505).
+ * Production leaves this null so restore uses the real cpSync; tests inject a
+ * throwing function to deterministically exercise the best-effort failure path
+ * and the shelter-retention guarantee.
+ * @internal
+ */
+let restoreEntryFn = null;
+/** @internal */
+export function _setRestoreEntryFnForTests(fn) {
+    restoreEntryFn = fn;
+    return () => { restoreEntryFn = null; };
+}
+export function createMilestoneDirectoryShelter(originalBasePath, milestoneId, milestoneTitle) {
+    const planningDir = milestonesDir(originalBasePath);
+    const shelterDir = join(gsdRoot(originalBasePath), ".milestone-shelter");
+    const shelteredDirs = [];
+    const mergeDirNames = milestoneDirectoryNames(originalBasePath, milestoneId, milestoneTitle);
+    let restored = false;
+    try {
+        if (existsSync(planningDir)) {
+            const entries = readdirSync(planningDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (mergeDirNames.has(entry.name))
+                    continue;
+                shelterMilestoneDirectory(planningDir, shelterDir, entry.name, shelteredDirs);
+            }
+        }
+    }
+    catch (err) {
+        // Non-fatal — proceed with merge; untracked files may block it.
+        logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            restoreShelteredDirectories(planningDir, shelterDir, shelteredDirs);
+        },
+    };
+}
+function milestoneDirectoryNames(originalBasePath, milestoneId, milestoneTitle) {
+    const mergeDirNames = new Set([milestoneId]);
+    const resolvedMergeDir = resolveMilestonePath(originalBasePath, milestoneId);
+    if (resolvedMergeDir) {
+        mergeDirNames.add(basename(resolvedMergeDir));
+    }
+    else {
+        mergeDirNames.add(canonicalPhaseDirName(milestoneId, milestoneTitle));
+    }
+    return mergeDirNames;
+}
+function shelterMilestoneDirectory(planningDir, shelterDir, dirName, shelteredDirs) {
+    const srcDir = join(planningDir, dirName);
+    const dstDir = join(shelterDir, dirName);
+    try {
+        mkdirSync(shelterDir, { recursive: true });
+        cpSync(srcDir, dstDir, { recursive: true, force: true });
+        rmSync(srcDir, { recursive: true, force: true });
+        shelteredDirs.push(dirName);
+    }
+    catch (err) {
+        // Non-fatal — if shelter fails, the merge may still succeed.
+        logWarning("worktree", `milestone shelter failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function restoreShelteredDirectories(planningDir, shelterDir, shelteredDirs) {
+    if (shelteredDirs.length === 0)
+        return;
+    let restoreFailed = false;
+    for (const dirName of shelteredDirs) {
+        const src = join(shelterDir, dirName);
+        if (!existsSync(src)) {
+            logWarning("worktree", `shelter source missing for ${dirName}; skipping restore (shelter already cleaned or entry never staged)`);
+            continue;
+        }
+        try {
+            mkdirSync(planningDir, { recursive: true });
+            const dest = join(planningDir, dirName);
+            if (restoreEntryFn) {
+                restoreEntryFn(src, dest);
+            }
+            else {
+                cpSync(src, dest, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            restoreFailed = true;
+            logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 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;
+    }
+    if (existsSync(shelterDir)) {
+        try {
+            rmSync(shelterDir, { recursive: true, force: true });
+        }
+        catch (err) {
+            logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+// gsd-pi — Auto-worktree path resolution seam.
+//
+// Keeps callers that only resolve existing auto-worktree paths on the focused
+// entry/path module instead of the legacy auto-worktree compatibility barrel.
+export { getAutoWorktreePath } from "./auto-worktree-entry.js";

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

@@ -0,0 +1,5 @@
+// gsd-pi — Narrow auto-worktree path utility seam.
+//
+// Keeps path comparison, pathspec, and expected-warning callers off the legacy
+// auto-worktree compatibility barrel while extraction continues.
+export { _gitPathspecForWorktreePath, _isExpectedWorktreeUnlinkError, _isSamePath, } from "./auto-worktree-cleanup.js";

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

@@ -0,0 +1,41 @@
+// gsd-pi — Auto-worktree resource version module.
+//
+// Owns managed-resource freshness checks for long-running auto sessions.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdHome } from "./gsd-home.js";
+import { logWarning } from "./workflow-logger.js";
+/**
+ * Read the resource version (semver) from the managed-resources manifest.
+ * Uses gsdVersion instead of syncedAt so that launching a second session
+ * doesn't falsely trigger staleness (#804).
+ */
+export function readResourceVersion() {
+    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
+    const manifestPath = join(agentDir, "managed-resources.json");
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return typeof manifest?.gsdVersion === "string"
+            ? manifest.gsdVersion
+            : null;
+    }
+    catch (e) {
+        logWarning("worktree", `readResourceVersion failed: ${e.message}`);
+        return null;
+    }
+}
+/**
+ * Check if managed resources have been updated since session start.
+ * Returns a warning message if stale, null otherwise.
+ */
+export function checkResourcesStale(versionOnStart) {
+    if (versionOnStart === null)
+        return null;
+    const current = readResourceVersion();
+    if (current === null)
+        return null;
+    if (current !== versionOnStart) {
+        return "GSD resources were updated since this session started. Restart gsd to load the new code.";
+    }
+    return null;
+}