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

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

@@ -1,2048 +1,22 @@
 // Project/App: gsd-pi
-// File Purpose: Auto-mode worktree lifecycle, merge, and cleanup management.
-/**
- * GSD Auto-Worktree -- lifecycle management for auto-mode worktrees.
- *
- * Auto-mode creates worktrees with `milestone/<MID>` branches (distinct from
- * manual `/worktree` which uses `worktree/<name>` branches). This module
- * manages create, enter, detect, and teardown for auto-mode worktrees.
- */
-import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative } from "node:path";
-import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
-import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, getSliceTasks, } from "./gsd-db.js";
-import { closeWorkflowDatabase, getWorkflowDatabasePath, openWorkflowDatabasePath, } from "./db-workspace.js";
-import { execFileSync } from "node:child_process";
-import { canonicalPhaseDirName, gsdRoot, milestonesDir, resolveGsdPathContract, resolveMilestonePath, } from "./paths.js";
-import { createWorktree, removeWorktree, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
-import { worktreePathFor } from "./worktree-placement.js";
-import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
-import { isGsdWorktreePath, projectRootFromWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
-import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
-import { MergeConflictError, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
-import { publishMilestone } from "./publication.js";
-import { debugLog } from "./debug-logger.js";
-import { logWarning, logError } from "./workflow-logger.js";
-import { checkoutBranchWithStashGuard, cleanupConflictState, gsdJsonlFilesWithConflictMarkers, hasConflictMarkers, popStashByRef, removeMergeStateFiles, stashAlreadyExistsFilesFromError, stashRefFromError, } from "./worktree-git-recovery.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { MILESTONE_ID_RE } from "./milestone-ids.js";
-import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
-import { classifyProject } from "./detection.js";
-import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeMergeRegular, nativeConflictFiles, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeWorktreeList, nativeLsFiles, } from "./native-git-bridge.js";
-import { CLOSEOUT_CONSISTENCY_BLOCKED_REASON, } from "./closeout-consistency-gate.js";
-import { formatCloseoutProofBlock, proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
-import { gsdHome } from "./gsd-home.js";
-import { createWorkspace } from "./workspace.js";
-import { WorktreeStateProjection } from "./worktree-state-projection.js";
-const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
-const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
-const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
-    "workflow-preferences-WORKFLOW-PREFS.json",
-    "discuss-project-PROJECT.json",
-    "discuss-requirements-REQUIREMENTS.json",
-    "research-decision-RESEARCH-DECISION.json",
-    "research-project-RESEARCH-PROJECT.json",
-]);
-// ─── Shared Constants & Helpers ─────────────────────────────────────────────
-/**
- * Root-level .gsd/ projections copied from project root into worktrees for
- * compatibility. Project root remains the canonical state/projection root.
- */
-const ROOT_STATE_FILES = [
-    "DECISIONS.md",
-    "REQUIREMENTS.md",
-    "PROJECT.md",
-    "KNOWLEDGE.md",
-    "OVERRIDES.md",
-    "QUEUE.md",
-    "completed-units.json",
-    "metrics.json",
-    "mcp.json",
-    // NOTE: project preferences are intentionally NOT in ROOT_STATE_FILES.
-    // Forward-sync (main → worktree) is handled explicitly in syncGsdStateToWorktree().
-    // Back-sync (worktree → main) must NEVER overwrite the project root's copy
-    // because the project root is authoritative for preferences (#2684).
-];
-/**
- * Check if two filesystem paths resolve to the same real location.
- * Returns false if either path cannot be resolved (e.g. doesn't exist).
- */
-function isSamePath(a, b) {
-    try {
-        return realpathSync(a) === realpathSync(b);
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return false;
-        logWarning("worktree", `isSamePath failed: ${e.message}`);
-        return false;
-    }
-}
-export function _isSamePath(a, b) {
-    return isSamePath(a, b);
-}
-export function _resolveAutoWorktreeStartPoint(integrationBranch, gitMainBranch, branchExists) {
-    if (integrationBranch)
-        return integrationBranch;
-    return gitMainBranch &&
-        typeof gitMainBranch === "string" &&
-        gitMainBranch.length > 0 &&
-        branchExists(gitMainBranch)
-        ? gitMainBranch
-        : undefined;
-}
-function importUntrackedProjectRootContentIntoEmptyWorktree(projectRoot, worktreeRoot, milestoneId) {
-    const worktreeClassification = classifyProject(worktreeRoot);
-    if (worktreeClassification.kind !== "greenfield")
-        return 0;
-    const projectRootClassification = classifyProject(projectRoot);
-    if (projectRootClassification.kind === "greenfield" ||
-        projectRootClassification.kind === "invalid-repo" ||
-        projectRootClassification.untrackedFiles.length === 0) {
-        return 0;
-    }
-    let copied = 0;
-    for (const relPath of projectRootClassification.untrackedFiles) {
-        const src = join(projectRoot, relPath);
-        if (!existsSync(src))
-            continue;
-        const dst = join(worktreeRoot, relPath);
-        if (existsSync(dst))
-            continue;
-        mkdirSync(dirname(dst), { recursive: true });
-        cpSync(src, dst, { recursive: true, force: false });
-        copied++;
-    }
-    if (copied > 0) {
-        debugLog("createAutoWorktree", {
-            phase: "import-untracked-project-content",
-            milestoneId,
-            copied,
-        });
-    }
-    return copied;
-}
-export function _shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath, pathExists = existsSync, samePath = isSamePath) {
-    return pathExists(worktreeDbPath) && !samePath(worktreeDbPath, mainDbPath);
-}
-export function _isExpectedWorktreeUnlinkError(code) {
-    return code === "ENOENT" || code === "EISDIR";
-}
-function stripGsdDisplayPrefix(value, id) {
-    const raw = String(value ?? "").trim();
-    if (!raw)
-        return undefined;
-    const lower = raw.toLowerCase();
-    const idLower = id.toLowerCase();
-    if (lower.startsWith(`${idLower}:`))
-        return raw.slice(id.length + 1).trim() || undefined;
-    return raw;
-}
-// ─── Module State ──────────────────────────────────────────────────────────
-/** Active workspace registry — replaces the legacy `originalBase` singleton. */
-let activeWorkspace = null;
-/**
- * Optional override for the shelter restore copy step (milestone merge #2505).
- * Production leaves this null so restoreShelter uses the real cpSync; tests
- * inject a throwing function to deterministically exercise the best-effort
- * failure path (auto-worktree.ts:1809) and the shelter-retention guarantee,
- * which is otherwise unreachable because shelter and restore run synchronously
- * in one mergeMilestoneToMain call (the filesystem cannot change between them).
- * @internal
- */
-let _restoreEntryFn = null;
-function setActiveWorkspace(ws) {
-    activeWorkspace = ws;
-}
-function getActiveWorkspace() {
-    return activeWorkspace;
-}
-function gitPathspecForWorktreePath(basePath, targetPath) {
-    let base = basePath;
-    let target = targetPath;
-    try {
-        base = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "ignore"],
-            encoding: "utf-8",
-        }).trim() || basePath;
-    }
-    catch {
-        /* keep original */
-        void base;
-    }
-    try {
-        base = realpathSync.native(base);
-    }
-    catch {
-        /* keep original */
-        void base;
-    }
-    try {
-        target = realpathSync.native(targetPath);
-    }
-    catch {
-        /* keep original */
-        void target;
-    }
-    const rel = relative(base, target);
-    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
-        return null;
-    return rel.replaceAll("\\", "/");
-}
-export function _gitPathspecForWorktreePath(basePath, targetPath) {
-    return gitPathspecForWorktreePath(basePath, targetPath);
-}
-function findRegularMergeChangedPaths(basePath, milestoneBranch, mainBranch) {
-    const changedPaths = new Set();
-    let mergeLog = "";
-    try {
-        mergeLog = execFileSync("git", ["rev-list", "--merges", "--parents", mainBranch], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        }).trim();
-    }
-    catch (err) {
-        logWarning("worktree", `regular merge lookup failed: ${err instanceof Error ? err.message : String(err)}`);
-        return changedPaths;
-    }
-    for (const line of mergeLog.split("\n").filter(Boolean)) {
-        const [mergeCommit, firstParent, ...otherParents] = line.split(" ");
-        if (!mergeCommit || !firstParent || otherParents.length === 0)
-            continue;
-        const mergedMilestone = otherParents.some((parent) => {
-            try {
-                return nativeIsAncestor(basePath, milestoneBranch, parent);
-            }
-            catch {
-                return false;
-            }
-        });
-        if (!mergedMilestone)
-            continue;
-        try {
-            const output = execFileSync("git", ["diff", "--name-only", firstParent, mergeCommit], {
-                cwd: basePath,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-            }).trim();
-            for (const path of output.split("\n").filter(Boolean)) {
-                if (!path.startsWith(".gsd/"))
-                    changedPaths.add(path);
-            }
-        }
-        catch (err) {
-            logWarning("worktree", `regular merge diff lookup failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        return changedPaths;
-    }
-    return changedPaths;
-}
-function clearProjectRootStateFiles(basePath, milestoneId) {
-    const gsdDir = gsdRoot(basePath);
-    // Phase C pt 2: auto.lock removed from this list — the file is gone
-    // (migrated to the workers + unit_dispatches + runtime_kv tables). The
-    // remaining transient files (STATE.md, {MID}-META.json) are still
-    // worth removing on teardown.
-    const transientFiles = [
-        join(gsdDir, "STATE.md"),
-        join(gsdDir, "milestones", milestoneId, `${milestoneId}-META.json`),
-    ];
-    for (const file of transientFiles) {
-        try {
-            unlinkSync(file);
-        }
-        catch (err) {
-            // ENOENT is expected — file may not exist (#3597)
-            if (err.code !== "ENOENT") {
-                logWarning("worktree", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    // Clean up legacy synced milestone directories and runtime/units.
-    // Older versions copied these into the project root during execution.
-    // If they remain as untracked files when we attempt
-    // `git merge --squash`, git rejects the merge with "local changes would
-    // be overwritten", causing silent data loss (#1738).
-    const syncedDirs = [
-        join(gsdDir, "milestones", milestoneId),
-        join(gsdDir, "runtime", "units"),
-    ];
-    for (const dir of syncedDirs) {
-        try {
-            if (existsSync(dir)) {
-                const pathspec = gitPathspecForWorktreePath(basePath, dir);
-                if (!pathspec)
-                    continue;
-                // Only remove files that are untracked by git — tracked files are
-                // managed by the branch checkout and should not be deleted.
-                const untrackedOutput = execFileSync("git", ["ls-files", "--others", "--exclude-standard", pathspec], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
-                if (untrackedOutput) {
-                    for (const f of untrackedOutput.split("\n").filter(Boolean)) {
-                        try {
-                            unlinkSync(join(basePath, f));
-                        }
-                        catch (err) {
-                            // ENOENT/EISDIR are expected for already-removed or directory entries (#3597)
-                            const code = err.code;
-                            if (!_isExpectedWorktreeUnlinkError(code)) {
-                                logWarning("worktree", `untracked file unlink failed: ${err instanceof Error ? err.message : String(err)}`);
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        catch (err) {
-            /* non-fatal — git command may fail if not in repo */
-            logWarning("worktree", `untracked file cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-}
-// ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
-/** Patterns for machine-generated build artifacts that can be safely
- * auto-resolved by accepting --theirs during merge. These files are
- * regenerable and never contain meaningful manual edits. */
-export const SAFE_AUTO_RESOLVE_PATTERNS = [
-    /\.tsbuildinfo$/,
-    /\.pyc$/,
-    /\/__pycache__\//,
-    /\.DS_Store$/,
-    /\.map$/,
-    // Regenerable dependency lockfiles. These are fully derivable from their
-    // manifests by the package manager, so accepting the merge side during
-    // auto-resolve clears the conflict markers without losing meaningful edits —
-    // and stops auto-mode from hard-pausing on a lockfile conflict (issue #828).
-    /(?:^|\/)pnpm-lock\.yaml$/,
-    /(?:^|\/)package-lock\.json$/,
-    /(?:^|\/)npm-shrinkwrap\.json$/,
-    /(?:^|\/)yarn\.lock$/,
-    /(?:^|\/)bun\.lockb?$/,
-    /(?:^|\/)Cargo\.lock$/,
-    /(?:^|\/)composer\.lock$/,
-    /(?:^|\/)Gemfile\.lock$/,
-    /(?:^|\/)Pipfile\.lock$/,
-    /(?:^|\/)poetry\.lock$/,
-];
-/** Returns true if the file path is safe to auto-resolve during merge.
- * Covers `.gsd/` state files, common build artifacts, and regenerable
- * dependency lockfiles. */
-export const isSafeToAutoResolve = (filePath) => filePath.startsWith(".gsd/") ||
-    SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
-// ─── Dispatch-Level Sync (project root ↔ worktree) ──────────────────────────
-/**
- * Sync milestone artifacts from project root INTO worktree before deriveState.
- * Covers the case where the LLM wrote artifacts to the main repo filesystem
- * (e.g. via absolute paths) but the worktree has stale data. Also deletes
- * gsd.db in the worktree so it rebuilds from fresh disk state (#853).
- * Non-fatal — sync failure should never block dispatch.
- */
-/**
- * Path-string entry point to WorktreeStateProjection.projectRootToWorktree.
- * Production code goes through the Module class; this delegator survives so
- * the projection-invariant tests (#1886, #2184, #2478, #2821) can exercise
- * the bodies with raw paths.
- */
-export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneId) {
-    new WorktreeStateProjection().projectRootToWorktreePaths(projectRoot, worktreePath_, milestoneId);
-}
-/**
- * Path-string entry point to WorktreeStateProjection.projectWorktreeToRoot.
- * Production code goes through the Module class; this delegator survives so
- * the projection-invariant tests can exercise the body with raw paths.
- */
-export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId) {
-    new WorktreeStateProjection().projectWorktreeToRootPaths(worktreePath_, projectRoot, milestoneId);
-}
-// ─── Resource Staleness ───────────────────────────────────────────────────
-/**
- * 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;
-}
-// ─── Stale Worktree Escape ────────────────────────────────────────────────
-/**
- * Detect and escape a stale worktree cwd (#608).
- *
- * After milestone completion + merge, the worktree directory is removed but
- * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
- * When a new session starts, `process.cwd()` is passed as `base` to startAuto
- * and all subsequent writes land in the wrong directory. This function detects
- * that scenario and chdir back to the project root.
- *
- * Returns the corrected base path.
- */
-export function escapeStaleWorktree(base) {
-    const projectRoot = projectRootFromWorktreePath(base);
-    if (projectRoot === null)
-        return base;
-    // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
-    // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
-    // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
-    // resolved through the symlink. Returning ~ would be catastrophic (#1676).
-    const candidateGsd = normalizeWorktreePathForCompare(join(projectRoot, ".gsd"));
-    const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
-    if (candidateGsd === gsdHomeNorm || candidateGsd.startsWith(gsdHomeNorm + "/")) {
-        // Don't chdir to home — return base unchanged.
-        // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
-        // and will be called by the caller (startAuto → projectRoot()).
-        return base;
-    }
-    try {
-        process.chdir(projectRoot);
-    }
-    catch (e) {
-        // If chdir fails, return the original — caller will handle errors downstream
-        logWarning("worktree", `escapeStaleWorktree chdir failed: ${e.message}`);
-        return base;
-    }
-    return projectRoot;
-}
-/**
- * Clean stale runtime unit files for completed milestones.
- *
- * After restart, stale runtime/units/*.json from prior milestones can
- * cause deriveState to resume the wrong milestone (#887). Removes files
- * for milestones that have a SUMMARY (fully complete).
- */
-export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
-    const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
-    if (!existsSync(runtimeUnitsDir))
-        return 0;
-    let cleaned = 0;
-    try {
-        for (const file of readdirSync(runtimeUnitsDir)) {
-            if (!file.endsWith(".json"))
-                continue;
-            if (LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES.has(file)) {
-                try {
-                    unlinkSync(join(runtimeUnitsDir, file));
-                    cleaned++;
-                }
-                catch (err) {
-                    /* non-fatal */
-                    logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
-                }
-                continue;
-            }
-            const staleDiscussMatch = file.match(/^discuss-milestone-(.+)\.json$/);
-            if (staleDiscussMatch && !MILESTONE_ID_RE.test(staleDiscussMatch[1])) {
-                try {
-                    unlinkSync(join(runtimeUnitsDir, file));
-                    cleaned++;
-                }
-                catch (err) {
-                    /* non-fatal */
-                    logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
-                }
-                continue;
-            }
-            const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
-            if (!midMatch)
-                continue;
-            if (hasMilestoneSummary(midMatch[1])) {
-                try {
-                    unlinkSync(join(runtimeUnitsDir, file));
-                    cleaned++;
-                }
-                catch (err) {
-                    /* non-fatal */
-                    logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-        }
-    }
-    catch (err) {
-        /* non-fatal */
-        logWarning("worktree", `stale runtime unit cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    return cleaned;
-}
-// ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
-/**
- * Scope-typed variant of syncGsdStateToWorktree.
- *
- * Takes an explicit (rootScope, worktreeScope) pair. Note: milestoneId is not
- * used by syncGsdStateToWorktree — this variant only requires workspace
- * identity. Asserts both scopes belong to the same workspace identity to
- * prevent silent mismatch bugs.
- */
-export function syncGsdStateToWorktreeByScope(rootScope, worktreeScope) {
-    if (rootScope.workspace.identityKey !== worktreeScope.workspace.identityKey) {
-        throw new Error(`syncGsdStateToWorktreeByScope: scope identity mismatch — ` +
-            `rootScope.identityKey="${rootScope.workspace.identityKey}" ` +
-            `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}"`);
-    }
-    const mainBasePath = rootScope.workspace.projectRoot;
-    const worktreePath_ = worktreeScope.workspace.worktreeRoot ?? worktreeScope.workspace.projectRoot;
-    return syncGsdStateToWorktree(mainBasePath, worktreePath_);
-}
-/**
- * Sync .gsd/ state from the main repo into the worktree.
- *
- * When .gsd/ is a symlink to the external state directory, both the main
- * repo and worktree share the same directory — no sync needed.
- *
- * When .gsd/ is a real directory (e.g., git-tracked or manage_gitignore:false),
- * the worktree has its own copy that may be stale. This function copies
- * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
- * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
- *
- * Only adds missing content — never overwrites existing files in the worktree.
- * Worktree files are compatibility projections; DB/project root remains
- * authoritative for runtime state.
- * @deprecated Use syncGsdStateToWorktreeByScope instead.
- * TODO(C-future): remove once all callers migrated.
- */
-export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
-    const contract = resolveGsdPathContract(worktreePath_, mainBasePath);
-    const mainGsd = contract.projectGsd;
-    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
-    const synced = [];
-    // If both resolve to the same directory (symlink), no sync needed
-    if (isSamePath(mainGsd, wtGsd))
-        return { synced };
-    if (!existsSync(mainGsd))
-        return { synced };
-    mkdirSync(wtGsd, { recursive: true });
-    // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE, etc.)
-    for (const f of ROOT_STATE_FILES) {
-        const src = join(mainGsd, f);
-        const dst = join(wtGsd, f);
-        if (existsSync(src) && !existsSync(dst)) {
-            try {
-                cpSync(src, dst);
-                synced.push(f);
-            }
-            catch (err) {
-                /* non-fatal */
-                logWarning("worktree", `file copy failed (${f}): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    // Forward-sync project preferences from project root to worktree (additive only).
-    // Prefer the canonical uppercase file name, but keep the legacy lowercase
-    // fallback so older repos still work on case-sensitive filesystems.
-    {
-        const worktreeHasPreferences = existsSync(join(wtGsd, PROJECT_PREFERENCES_FILE))
-            || existsSync(join(wtGsd, LEGACY_PROJECT_PREFERENCES_FILE));
-        if (!worktreeHasPreferences) {
-            for (const file of [PROJECT_PREFERENCES_FILE, LEGACY_PROJECT_PREFERENCES_FILE]) {
-                const src = join(mainGsd, file);
-                const dst = join(wtGsd, file);
-                if (existsSync(src)) {
-                    try {
-                        cpSync(src, dst);
-                        synced.push(file);
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `preferences copy failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                    break;
-                }
-            }
-        }
-    }
-    // Sync milestone/phase trees: copy entire directories that are missing.
-    // Support both flat-phase (phases/) and legacy (milestones/) layouts.
-    for (const layoutSegment of ["phases", "milestones"]) {
-        const mainMilestonesDir = join(mainGsd, layoutSegment);
-        const wtMilestonesDir = join(wtGsd, layoutSegment);
-        if (existsSync(mainMilestonesDir)) {
-            try {
-                mkdirSync(wtMilestonesDir, { recursive: true });
-                const mainMilestones = readdirSync(mainMilestonesDir, {
-                    withFileTypes: true,
-                })
-                    .filter((d) => d.isDirectory())
-                    .map((d) => d.name);
-                for (const mid of mainMilestones) {
-                    const srcDir = join(mainMilestonesDir, mid);
-                    const dstDir = join(wtMilestonesDir, mid);
-                    if (!existsSync(dstDir)) {
-                        // Entire milestone missing from worktree — copy it
-                        try {
-                            cpSync(srcDir, dstDir, { recursive: true });
-                            synced.push(`milestones/${mid}/`);
-                        }
-                        catch (err) {
-                            /* non-fatal */
-                            logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-                        }
-                    }
-                    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"));
-                            for (const f of srcFiles) {
-                                const srcFile = join(srcDir, f);
-                                const dstFile = join(dstDir, f);
-                                if (!existsSync(dstFile)) {
-                                    try {
-                                        const srcStat = lstatSyncFn(srcFile);
-                                        if (srcStat.isFile()) {
-                                            cpSync(srcFile, dstFile);
-                                            synced.push(`milestones/${mid}/${f}`);
-                                        }
-                                    }
-                                    catch (err) {
-                                        /* non-fatal */
-                                        logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
-                                    }
-                                }
-                            }
-                            // Sync slices directory if it exists in main but not in worktree
-                            const srcSlicesDir = join(srcDir, "slices");
-                            const dstSlicesDir = join(dstDir, "slices");
-                            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
-                                try {
-                                    cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
-                                    synced.push(`milestones/${mid}/slices/`);
-                                }
-                                catch (err) {
-                                    /* non-fatal */
-                                    logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-                                }
-                            }
-                            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);
-                                for (const sid of srcSlices) {
-                                    const srcSlice = join(srcSlicesDir, sid);
-                                    const dstSlice = join(dstSlicesDir, sid);
-                                    if (!existsSync(dstSlice)) {
-                                        try {
-                                            cpSync(srcSlice, dstSlice, { recursive: true });
-                                            synced.push(`milestones/${mid}/slices/${sid}/`);
-                                        }
-                                        catch (err) {
-                                            /* non-fatal */
-                                            logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        catch (err) {
-                            /* non-fatal */
-                            logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
-                        }
-                    }
-                }
-            }
-            catch (err) {
-                /* non-fatal */
-                logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    return { synced };
-}
-/**
- * Sync compatibility artifacts from worktree back to the main external state
- * directory. Canonical workflow state lives in the project DB; worktree .gsd
- * content is legacy projection/diagnostic data only.
- *
- * Syncs:
- *   1. Legacy worktree DBs are reconciled into the canonical project DB.
- *   2. Runtime diagnostic files may be copied for operator visibility.
- *
- * Markdown milestone directories are projections and are not copied from
- * worktrees into the project root. Current workflow state must arrive through
- * the shared project DB or the pre-upgrade DB reconciliation path above.
- */
-export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
-    return new WorktreeStateProjection().finalizeProjectionForMergePaths(mainBasePath, worktreePath, milestoneId);
-}
+// File Purpose: Compatibility barrel for auto-mode worktree modules.
+/**
+ * GSD Auto-Worktree compatibility barrel.
+ *
+ * New code should import from the focused modules (`auto-worktree-creation`,
+ * `auto-worktree-teardown`, `auto-worktree-sync`, `auto-worktree-merge`, etc.).
+ * This file preserves the historical interface while the module extraction
+ * completes.
+ */
+export { autoWorktreeBranch, enterBranchModeForMilestone, fastForwardReusedMilestoneBranchIfSafe, _isBranchCheckedOutElsewhere, _resolveAutoWorktreeStartPoint, } from "./auto-worktree-branch-lifecycle.js";
+export { _gitPathspecForWorktreePath, _isExpectedWorktreeUnlinkError, _isSamePath, _shouldReconcileWorktreeDb, } from "./auto-worktree-cleanup.js";
+export { isSafeToAutoResolve, SAFE_AUTO_RESOLVE_PATTERNS, } from "./auto-worktree-conflict-auto-resolve.js";
+export { createAutoWorktree } from "./auto-worktree-creation.js";
+export { enterAutoWorktree, getAutoWorktreePath, isInAutoWorktree, } from "./auto-worktree-entry.js";
+export { mergeMilestoneToMain, _setRestoreEntryFnForTests, } from "./auto-worktree-merge.js";
+export { checkResourcesStale, readResourceVersion, } from "./auto-worktree-resource-version.js";
+export { cleanStaleRuntimeUnits, escapeStaleWorktree, } from "./auto-worktree-runtime-cleanup.js";
+export { getActiveAutoWorktreeContext, getAutoWorktreeOriginalBase, _resetAutoWorktreeOriginalBaseForTests, } from "./auto-worktree-session-registry.js";
+export { syncGsdStateToWorktree, syncGsdStateToWorktreeByScope, syncProjectRootToWorktree, syncStateToProjectRoot, syncWorktreeStateBack, } from "./auto-worktree-sync.js";
+export { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 export { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
-// ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
-/** Returns the git branch name for a milestone worktree (`milestone/<MID>`). */
-export function autoWorktreeBranch(milestoneId) {
-    return `milestone/${milestoneId}`;
-}
-function normalizeLocalBranchRef(branch) {
-    return branch.startsWith("refs/heads/")
-        ? branch.slice("refs/heads/".length)
-        : branch;
-}
-// ─── Branch-mode Entry ─────────────────────────────────────────────────────
-/**
- * Enter branch isolation mode for a milestone.
- *
- * Creates `milestone/<MID>` from the integration branch (if it doesn't
- * exist yet) and checks out to it.  No worktree directory is created — the
- * project root is the working copy; only HEAD changes.
- *
- * Uses the same 3-tier integration-branch fallback as createAutoWorktree:
- *   1. META.json recorded integration branch
- *   2. git.main_branch preference
- *   3. nativeDetectMainBranch (origin/HEAD auto-detection)
- */
-export function enterBranchModeForMilestone(basePath, milestoneId) {
-    const branch = autoWorktreeBranch(milestoneId);
-    const branchExists = nativeBranchExists(basePath, branch);
-    if (!branchExists) {
-        // Create the milestone branch from the integration branch start-point.
-        const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
-        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-        const startPoint = _resolveAutoWorktreeStartPoint(integrationBranch, gitPrefs?.main_branch, (branchName) => nativeBranchExists(basePath, branchName)) ??
-            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);
-        debugLog("auto-worktree", {
-            action: "enterBranchMode",
-            milestoneId,
-            branch,
-            startPoint,
-            created: true,
-        });
-    }
-    else {
-        debugLog("auto-worktree", {
-            action: "enterBranchMode",
-            milestoneId,
-            branch,
-            reused: true,
-        });
-    }
-    checkoutBranchWithStashGuard(basePath, branch, `enter-branch-mode:${milestoneId}`);
-}
-// ─── Public API ────────────────────────────────────────────────────────────
-/**
- * Create a new auto-worktree for a milestone, chdir into it, and store
- * the original base path for later teardown.
- *
- * 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).
- *
- * Phase C: deleted. Writers in workflow-projections.ts, triage-resolution.ts,
- * rule-registry.ts, and auto-post-unit.ts now route through
- * s.canonicalProjectRoot, so non-symlinked worktrees no longer need a local
- * .gsd/ projection — the project-root .gsd/ is the only authoritative source
- * for both reads and writes. copyPlanningArtifacts and reconcilePlanCheckboxes
- * (both formerly here) became dead.
- */
-/**
- * True when `branch` is checked out in any worktree listed by
- * `git worktree list --porcelain`. Used to gate ref updates that would
- * otherwise leave a concurrent worktree's HEAD inconsistent with its
- * index/working tree (Codex peer-review of #5538-followup).
- *
- * Best-effort: a `nativeWorktreeList` failure returns true so we err on
- * the side of NOT moving the ref. Better to skip a fast-forward than to
- * silently corrupt another worktree.
- */
-export function _isBranchCheckedOutElsewhere(basePath, branch) {
-    try {
-        const entries = nativeWorktreeList(basePath);
-        return entries.some((entry) => entry.branch === branch);
-    }
-    catch {
-        return true;
-    }
-}
-/**
- * Resolve the integration branch using the same 3-tier fallback as the
- * fresh-create path: META.json → git.main_branch preference → detected
- * main branch. Returns null when no usable target exists.
- */
-function _resolveIntegrationBranchForReuse(basePath, milestoneId) {
-    const fromMeta = readIntegrationBranch(basePath, milestoneId);
-    if (fromMeta)
-        return fromMeta;
-    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    const fromPref = gitPrefs?.main_branch &&
-        typeof gitPrefs.main_branch === "string" &&
-        gitPrefs.main_branch.length > 0 &&
-        nativeBranchExists(basePath, gitPrefs.main_branch)
-        ? gitPrefs.main_branch
-        : null;
-    if (fromPref)
-        return fromPref;
-    try {
-        return nativeDetectMainBranch(basePath);
-    }
-    catch {
-        return null;
-    }
-}
-function safeCwd(fallback) {
-    try {
-        return process.cwd();
-    }
-    catch {
-        return fallback;
-    }
-}
-/**
- * When reusing an existing milestone branch, fast-forward it onto the
- * integration branch when that's safe (branch is a strict ancestor of
- * integration — no commits would be lost). Skips when the branch has its
- * own commits ahead of integration, when the integration branch can't be
- * resolved, or when any git operation fails — the merge gate at milestone
- * completion will surface real divergence as a conflict.
- *
- * The previous behavior re-attached the worktree to whatever stale tip
- * the branch held, which caused new milestone work to fork from a base
- * missing prior milestones' merges (#5538-followup).
- */
-export function fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch) {
-    try {
-        const integrationBranch = _resolveIntegrationBranchForReuse(basePath, milestoneId);
-        if (!integrationBranch || integrationBranch === branch)
-            return;
-        if (!nativeBranchExists(basePath, integrationBranch))
-            return;
-        // Pure fast-forward only: branch must be a strict ancestor of integration.
-        // If the branch has its own commits ahead, leave it alone.
-        if (!nativeIsAncestor(basePath, branch, integrationBranch)) {
-            debugLog("createAutoWorktree", {
-                phase: "skip-ff-branch-not-ancestor",
-                milestoneId,
-                branch,
-                integration: integrationBranch,
-            });
-            return;
-        }
-        // Codex peer-review: `nativeUpdateRef` succeeds even when the branch is
-        // currently checked out in another worktree, leaving that worktree's HEAD
-        // inconsistent with its index/work tree. Skip the fast-forward if any
-        // listed worktree has this branch checked out — the merge gate at
-        // milestone-completion will surface stale-base divergence as a conflict
-        // instead of silently corrupting the other worktree's state.
-        if (_isBranchCheckedOutElsewhere(basePath, branch)) {
-            debugLog("createAutoWorktree", {
-                phase: "skip-ff-branch-checked-out-elsewhere",
-                milestoneId,
-                branch,
-            });
-            return;
-        }
-        nativeUpdateRef(basePath, `refs/heads/${branch}`, integrationBranch);
-        debugLog("createAutoWorktree", {
-            phase: "fast-forward-reused-branch",
-            milestoneId,
-            branch,
-            integration: integrationBranch,
-        });
-    }
-    catch (err) {
-        debugLog("createAutoWorktree", {
-            phase: "fast-forward-reused-branch-failed",
-            milestoneId,
-            branch,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}
-export function createAutoWorktree(basePath, milestoneId) {
-    basePath = resolveWorktreeProjectRoot(basePath);
-    // Check if repo has commits — git worktree requires a valid HEAD
-    try {
-        execFileSync("git", ["rev-parse", "--verify", "HEAD"], { cwd: basePath, stdio: "pipe" });
-    }
-    catch {
-        throw new GSDError(GSD_GIT_ERROR, `Cannot create worktree: repository has no commits yet. Worktree isolation requires at least one commit.`);
-    }
-    const branch = autoWorktreeBranch(milestoneId);
-    // Check if the milestone branch already exists — it survives auto-mode
-    // stop/pause and contains committed work from prior sessions. If it exists,
-    // re-attach the worktree to it WITHOUT resetting. Only create a fresh branch
-    // from the integration branch when no prior work exists.
-    const branchExists = nativeBranchExists(basePath, branch);
-    let info;
-    if (branchExists) {
-        // #5538-followup: fast-forward the reused branch onto the integration
-        // branch when safe so the next milestone forks from up-to-date code.
-        // Without this, a milestone that was created before another milestone
-        // merged into main would carry a stale base into its worktree.
-        fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch);
-        // Re-attach worktree to the existing milestone branch (preserving commits)
-        info = createWorktree(basePath, milestoneId, {
-            branch,
-            reuseExistingBranch: true,
-        });
-    }
-    else {
-        // Fresh start — create branch from integration branch.
-        // Use the same 3-tier fallback as mergeMilestoneToMain (#3461):
-        //   1. META.json integration branch (explicit per-milestone override)
-        //   2. git.main_branch preference (user's configured working branch)
-        //   3. nativeDetectMainBranch (origin/HEAD auto-detection)
-        // Without tier 2, projects with main_branch=dev but origin/HEAD→master
-        // would fork worktrees from the wrong (stale) branch.
-        const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
-        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-        const startPoint = _resolveAutoWorktreeStartPoint(integrationBranch, gitPrefs?.main_branch, (branchName) => nativeBranchExists(basePath, branchName));
-        info = createWorktree(basePath, milestoneId, {
-            branch,
-            startPoint,
-        });
-    }
-    // Phase C: copyPlanningArtifacts and reconcilePlanCheckboxes were
-    // deleted. Both addressed the same problem (worktree-local .gsd/
-    // projection lagging behind project-root state) by maintaining a stale
-    // copy. Now that auto-mode writers in workflow-projections.ts,
-    // triage-resolution.ts, rule-registry.ts, and auto-post-unit.ts route
-    // through s.canonicalProjectRoot, the worktree never needs a local
-    // .gsd/ — both reads and writes converge on the project-root .gsd/.
-    // The original concerns (#759, #778) no longer apply because there is
-    // no second copy to drift.
-    importUntrackedProjectRootContentIntoEmptyWorktree(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) {
-        // Non-fatal — log but don't prevent worktree usage
-        logWarning("reconcile", hookError, { worktree: info.name });
-    }
-    const previousCwd = process.cwd();
-    try {
-        process.chdir(info.path);
-        setActiveWorkspace(createWorkspace(basePath));
-    }
-    catch (err) {
-        // If chdir fails, the worktree was created but we couldn't enter it.
-        // Don't set activeWorkspace -- caller can retry or clean up.
-        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;
-}
-// Phase C: copyPlanningArtifacts removed. Planning artifacts now live
-// only at the project root .gsd/; auto-mode writers (workflow-projections,
-// triage-resolution, rule-registry, regenerateIfMissing,
-// resolveHookArtifactPath) all route through s.canonicalProjectRoot.
-// Worktrees are pure git checkouts — they no longer maintain a parallel
-// .gsd/ projection. The gsd.db has always lived at the project root via
-// the shared-WAL R012 contract; that is unchanged.
-/**
- * Teardown an auto-worktree: chdir back to original base, then remove
- * the worktree and its branch.
- */
-export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
-    originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
-    const branch = autoWorktreeBranch(milestoneId);
-    const { preserveBranch = false, preserveWorktree = false } = opts;
-    const previousCwd = safeCwd(originalBasePath);
-    // Wrap the entire teardown body in a single try/finally so activeWorkspace
-    // is ALWAYS cleared — even if process.chdir throws (e.g. originalBasePath
-    // was deleted before teardown ran). Previously the finally only covered
-    // removeWorktree, leaving the registry stale on a chdir failure (H3 fix).
-    try {
-        try {
-            process.chdir(originalBasePath);
-        }
-        catch (err) {
-            throw new GSDError(GSD_IO_ERROR, `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        // Mirror cleanup steps from mergeMilestoneToMain abort path:
-        // 1. Remove transient state files (STATE.md, auto.lock, {MID}-META.json).
-        //    Non-fatal — must not block teardown.
-        try {
-            clearProjectRootStateFiles(originalBasePath, milestoneId);
-        }
-        catch (err) {
-            logWarning("worktree", `clearProjectRootStateFiles failed during teardown: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        // 2. Reconcile worktree-local gsd.db into project root DB if both exist.
-        //    Non-fatal — handles legacy worktrees that have a local copy.
-        if (isDbAvailable()) {
-            try {
-                const contract = resolveGsdPathContract(previousCwd, originalBasePath);
-                const worktreeDbPath = join(contract.worktreeGsd ?? join(previousCwd, ".gsd"), "gsd.db");
-                const mainDbPath = contract.projectDb;
-                if (_shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
-                    reconcileWorktreeDb(mainDbPath, worktreeDbPath);
-                }
-            }
-            catch (err) {
-                /* non-fatal */
-                logError("worktree", `DB reconciliation failed during teardown: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-        nudgeGitBranchCache(previousCwd);
-        // 3. Remove the worktree unless this exit path explicitly preserves it
-        //    (slice-parallel dispatch stops the parent loop but keeps the parent
-        //    milestone worktree for restart/re-entry).
-        if (!preserveWorktree) {
-            removeWorktree(originalBasePath, milestoneId, {
-                branch,
-                deleteBranch: !preserveBranch,
-            });
-        }
-        // Verify cleanup succeeded — warn if the worktree directory is still on disk.
-        // On Windows, bash-based cleanup can silently fail when paths contain
-        // backslashes (#1436), leaving ~1 GB+ orphaned directories.
-        const wtDir = worktreePath(originalBasePath, milestoneId);
-        if (!preserveWorktree && existsSync(wtDir)) {
-            logWarning("reconcile", `Worktree directory still exists after teardown: ${wtDir}. ` +
-                `This is likely an orphaned directory consuming disk space. ` +
-                `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`, { worktree: milestoneId });
-            // Attempt a direct filesystem removal as a fallback — but ONLY if the
-            // path is safely inside .gsd/worktrees/ to prevent #2365 data loss.
-            if (isInsideWorktreesDir(originalBasePath, wtDir)) {
-                try {
-                    rmSync(wtDir, { recursive: true, force: true });
-                }
-                catch (err) {
-                    // Non-fatal — the warning above tells the user how to clean up
-                    logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            else {
-                console.error(`[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`);
-            }
-        }
-    }
-    finally {
-        // Clear module state unconditionally — regardless of which step above
-        // failed. A stale activeWorkspace causes getActiveAutoWorktreeContext()
-        // to return wrong data for subsequent operations.
-        setActiveWorkspace(null);
-    }
-}
-/**
- * Detect if the process is currently inside an auto-worktree.
- * Uses the current directory structure plus git branch prefix so detection
- * still works after process restart when module state has been reset.
- */
-export function isInAutoWorktree(basePath) {
-    const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
-    if (!isGsdWorktreePath(targetPath))
-        return false;
-    const storedBase = getAutoWorktreeOriginalBase();
-    const projectRoot = resolveWorktreeProjectRoot(basePath, storedBase);
-    const targetProjectRoot = resolveWorktreeProjectRoot(targetPath, storedBase);
-    if (normalizeWorktreePathForCompare(projectRoot) !==
-        normalizeWorktreePathForCompare(targetProjectRoot)) {
-        return false;
-    }
-    try {
-        const branch = nativeGetCurrentBranch(targetPath);
-        return branch.startsWith("milestone/");
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Get the filesystem path for an auto-worktree, or null if it doesn't exist
- * or is not a valid git worktree.
- *
- * Validates that the path is a real git worktree (has a .git file with a
- * gitdir: pointer) rather than just a stray directory. This prevents
- * mis-detection of leftover directories as active worktrees (#695).
- */
-export function getAutoWorktreePath(basePath, milestoneId) {
-    basePath = resolveWorktreeProjectRoot(basePath);
-    // basePath is already the resolved project root — go straight to placement
-    // instead of worktreePath(), which would re-resolve the root.
-    const p = worktreePathFor(basePath, milestoneId);
-    if (!existsSync(p))
-        return null;
-    // Validate this is a real git worktree, not a stray directory.
-    // A git worktree has a .git *file* (not directory) containing "gitdir: <path>".
-    const gitPath = join(p, ".git");
-    if (!existsSync(gitPath))
-        return null;
-    try {
-        const content = readFileSync(gitPath, "utf8").trim();
-        if (!content.startsWith("gitdir: "))
-            return null;
-    }
-    catch (e) {
-        logWarning("worktree", `getAutoWorktreePath .git read failed: ${e.message}`);
-        return null;
-    }
-    return p;
-}
-/**
- * Enter an existing auto-worktree (chdir into it, store originalBase).
- * Use for resume -- the worktree already exists from a prior create.
- *
- * Atomic: chdir + originalBase update in same try block.
- */
-export function enterAutoWorktree(basePath, milestoneId) {
-    basePath = resolveWorktreeProjectRoot(basePath);
-    const p = worktreePath(basePath, milestoneId);
-    if (!existsSync(p)) {
-        throw new GSDError(GSD_IO_ERROR, `Auto-worktree for ${milestoneId} does not exist at ${p}`);
-    }
-    // Validate this is a real git worktree, not a stray directory (#695)
-    const gitPath = join(p, ".git");
-    if (!existsSync(gitPath)) {
-        throw new GSDError(GSD_GIT_ERROR, `Auto-worktree path ${p} exists but is not a git worktree (no .git)`);
-    }
-    try {
-        const content = readFileSync(gitPath, "utf8").trim();
-        if (!content.startsWith("gitdir: ")) {
-            throw new GSDError(GSD_GIT_ERROR, `Auto-worktree path ${p} has a .git but it is not a worktree gitdir pointer`);
-        }
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("worktree"))
-            throw err;
-        throw new GSDError(GSD_IO_ERROR, `Auto-worktree path ${p} exists but .git is unreadable`);
-    }
-    const previousCwd = process.cwd();
-    try {
-        process.chdir(p);
-        setActiveWorkspace(createWorkspace(basePath));
-    }
-    catch (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;
-}
-/**
- * Get the original project root stored when entering an auto-worktree.
- * Returns null if not currently in an auto-worktree.
- */
-export function getAutoWorktreeOriginalBase() {
-    return getActiveWorkspace()?.projectRoot ?? null;
-}
-/**
- * Test-only — resets the module-level `activeWorkspace` registry between
- * runs. Production code never clears the registry directly; tests call this
- * in `beforeEach`/`afterEach` to isolate registry-mutating cases. Renaming
- * the underscore-prefixed `_*ForTest` exports it joins (slice 7 / step G of
- * ADR-016) was deliberate: those wrapped real production helpers and lost
- * the suffix; this one stays as the only legitimate test-scaffolding export
- * because it has no production caller.
- */
-export function _resetAutoWorktreeOriginalBaseForTests() {
-    setActiveWorkspace(null);
-}
-/**
- * Inject an override for the shelter restore copy step, returning a function
- * that restores the default (real cpSync) behavior. Used by tests to
- * deterministically exercise the best-effort restore-failure path
- * (auto-worktree.ts:1809) and the #2505 shelter-retention guarantee — which is
- * otherwise unreachable because shelter + restore run synchronously in one
- * mergeMilestoneToMain call. No production caller.
- * @internal
- */
-export function _setRestoreEntryFnForTests(fn) {
-    _restoreEntryFn = fn;
-    return () => { _restoreEntryFn = null; };
-}
-export function getActiveAutoWorktreeContext() {
-    const ws = getActiveWorkspace();
-    if (!ws)
-        return null;
-    const originalBase = ws.projectRoot;
-    const cwd = process.cwd();
-    if (!isGsdWorktreePath(cwd))
-        return null;
-    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
-    if (normalizeWorktreePathForCompare(cwdProjectRoot) !==
-        normalizeWorktreePathForCompare(originalBase)) {
-        return null;
-    }
-    const worktreeName = detectWorktreeName(cwd);
-    if (!worktreeName)
-        return null;
-    const branch = nativeGetCurrentBranch(cwd);
-    if (!branch.startsWith("milestone/"))
-        return null;
-    return {
-        originalBase,
-        worktreeName,
-        branch,
-    };
-}
-// ─── 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 only so `auto.ts:buildWorktreeLifecycleDeps()` can wire this
- * function through the Module's deps seam — that is the construction of the
- * seam, not a bypass.
- */
-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 worktree DB into main DB before leaving worktree context.
-    // Skip when both paths resolve to the same physical file (shared WAL /
-    // symlink layout) — ATTACHing a WAL-mode file to itself corrupts the
-    // database (#2823).
-    if (isDbAvailable()) {
-        const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
-        const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
-        const mainDbPath = contract.projectDb;
-        try {
-            const activeDbPath = getWorkflowDatabasePath();
-            if (activeDbPath && _shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
-                closeWorkflowDatabase();
-                if (!openWorkflowDatabasePath(mainDbPath)) {
-                    throw new Error(`cannot open project DB at ${mainDbPath}`);
-                }
-            }
-            if (_shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
-                reconcileWorktreeDb(mainDbPath, worktreeDbPath);
-            }
-        }
-        catch (err) {
-            const message = `DB reconciliation failed before milestone ${milestoneId} merge: ${err instanceof Error ? err.message : String(err)}`;
-            logError("worktree", message);
-            throw new GSDError(GSD_GIT_ERROR, `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`);
-        }
-        const closeoutProof = proveMilestoneCloseout(milestoneId);
-        if (!closeoutProof.ok) {
-            throw new GSDError(GSD_GIT_ERROR, formatCloseoutProofBlock(closeoutProof));
-        }
-    }
-    // 2. Get completed slices for commit message
-    let completedSlices = [];
-    if (isDbAvailable()) {
-        completedSlices = getMilestoneSlices(milestoneId)
-            .filter(s => s.status === "complete")
-            .map(s => ({
-            id: s.id,
-            title: stripGsdDisplayPrefix(s.title, s.id) ?? s.id,
-            tasks: getSliceTasks(milestoneId, s.id)
-                .filter((task) => task.status === "complete")
-                .map((task) => ({
-                id: task.id,
-                title: stripGsdDisplayPrefix(task.title, task.id) ?? task.id,
-            })),
-        }));
-    }
-    // Fallback: parse roadmap content when DB is unavailable
-    if (completedSlices.length === 0 && roadmapContent) {
-        const sliceRe = /- \[x\] \*\*(\w+):\s*(.+?)\*\*/gi;
-        let m;
-        while ((m = sliceRe.exec(roadmapContent)) !== null) {
-            completedSlices.push({ id: m[1], title: m[2], tasks: [] });
-        }
-    }
-    // 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. Resolve integration branch via shared resolver so stale/invalid
-    //    milestone metadata can recover to configured/detected fallbacks.
-    const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-    const branchResolution = resolveMilestoneIntegrationBranch(originalBasePath_, milestoneId, prefs);
-    const mainBranch = branchResolution.effectiveBranch ?? nativeDetectMainBranch(originalBasePath_);
-    // Fail closed when the resolved integration branch is the milestone branch
-    // itself (#5024). Stale or corrupt metadata (e.g. integrationBranch recorded
-    // as "milestone/<MID>") would otherwise let the squash merge resolve to a
-    // self-merge: nothing-to-commit + empty self-diff in the post-merge safety
-    // check (#1792) collapse to a false success, and the worktree-resolver
-    // emits worktree-merged for work that never landed on a distinct
-    // integration branch.
-    if (normalizeLocalBranchRef(mainBranch) === milestoneBranch) {
-        process.chdir(previousCwd);
-        throw new GSDError(GSD_GIT_ERROR, `Resolved integration branch "${mainBranch}" is the same ref as milestone branch ` +
-            `"${milestoneBranch}" — refusing to self-merge. ${branchResolution.reason}. ` +
-            `Repair milestone integration metadata before retrying milestone completion.`);
-    }
-    // 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)
-    //
-    // 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);
-    }
-    // 6. Build rich commit message
-    const dbMilestone = getMilestone(milestoneId);
-    let milestoneTitle = stripGsdDisplayPrefix(dbMilestone?.title, milestoneId) ?? "";
-    // Fallback: parse title from roadmap content header (e.g. "# M020: Backend foundation")
-    if (!milestoneTitle && roadmapContent) {
-        const titleMatch = roadmapContent.match(new RegExp(`^#\\s+${milestoneId}:\\s*(.+)`, "m"));
-        if (titleMatch)
-            milestoneTitle = titleMatch[1].trim();
-    }
-    milestoneTitle = milestoneTitle || milestoneId;
-    const subject = `feat: ${milestoneTitle}`;
-    const milestoneContext = milestoneTitle === milestoneId
-        ? `Milestone: ${milestoneId}`
-        : `Milestone: ${milestoneId} - ${milestoneTitle}`;
-    let body = "";
-    if (completedSlices.length > 0) {
-        const sliceLines = completedSlices
-            .map((s) => `- ${s.id}: ${s.title}`)
-            .join("\n");
-        const taskLines = completedSlices
-            .flatMap((s) => s.tasks.map((task) => `- ${s.id}/${task.id}: ${task.title}`))
-            .join("\n");
-        const taskBlock = taskLines ? `\n\nCompleted tasks:\n${taskLines}` : "";
-        body = `\n\nCompleted slices:\n${sliceLines}${taskBlock}\n\n${milestoneContext}\nGSD-Milestone: ${milestoneId}\nBranch: ${milestoneBranch}`;
-    }
-    else {
-        body = `\n\n${milestoneContext}\nGSD-Milestone: ${milestoneId}\nBranch: ${milestoneBranch}`;
-    }
-    const commitMessage = subject + body;
-    // 6b. Reconcile worktree HEAD with milestone branch ref (#1846).
-    //     When the worktree HEAD detaches and advances past the named branch,
-    //     the branch ref becomes stale. Squash-merging the stale ref silently
-    //     orphans all commits between the branch ref and the actual worktree HEAD.
-    //     Fix: fast-forward the branch ref to the worktree HEAD before merging.
-    //     Only applies when merging from an actual worktree (worktreeCwd differs
-    //     from originalBasePath_).
-    if (worktreeCwd !== originalBasePath_) {
-        try {
-            const worktreeHead = execFileSync("git", ["rev-parse", "HEAD"], {
-                cwd: worktreeCwd,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-            }).trim();
-            const branchHead = execFileSync("git", ["rev-parse", milestoneBranch], {
-                cwd: originalBasePath_,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-            }).trim();
-            if (worktreeHead && branchHead && worktreeHead !== branchHead) {
-                if (nativeIsAncestor(originalBasePath_, branchHead, worktreeHead)) {
-                    // Worktree HEAD is strictly ahead — fast-forward the branch ref
-                    nativeUpdateRef(originalBasePath_, `refs/heads/${milestoneBranch}`, worktreeHead);
-                    debugLog("mergeMilestoneToMain", {
-                        action: "fast-forward-branch-ref",
-                        milestoneBranch,
-                        oldRef: branchHead.slice(0, 8),
-                        newRef: worktreeHead.slice(0, 8),
-                    });
-                }
-                else {
-                    // Diverged — fail loudly rather than silently losing commits
-                    process.chdir(previousCwd);
-                    throw new GSDError(GSD_GIT_ERROR, `Worktree HEAD (${worktreeHead.slice(0, 8)}) diverged from ` +
-                        `${milestoneBranch} (${branchHead.slice(0, 8)}). ` +
-                        `Manual reconciliation required before merge.`);
-                }
-            }
-        }
-        catch (err) {
-            // Re-throw GSDError (divergence); swallow rev-parse failures
-            // (e.g. worktree dir already removed by external cleanup)
-            if (err instanceof GSDError)
-                throw err;
-            debugLog("mergeMilestoneToMain", {
-                action: "reconcile-skipped",
-                reason: String(err),
-            });
-        }
-    }
-    // Already regular-merged milestones can skip the squash path and proceed to cleanup (#5831).
-    if (nativeIsAncestor(originalBasePath_, milestoneBranch, mainBranch)) {
-        const codeChanges = nativeDiffNumstat(originalBasePath_, mainBranch, milestoneBranch).filter((entry) => !entry.path.startsWith(".gsd/"));
-        if (codeChanges.length > 0) {
-            const regularMergeChangedPaths = findRegularMergeChangedPaths(originalBasePath_, milestoneBranch, mainBranch);
-            const unanchoredCodeChanges = codeChanges.filter((entry) => regularMergeChangedPaths.has(entry.path));
-            if (unanchoredCodeChanges.length > 0) {
-                process.chdir(previousCwd);
-                throw new GSDError(GSD_GIT_ERROR, `Milestone branch "${milestoneBranch}" is reachable from "${mainBranch}" ` +
-                    `but has ${unanchoredCodeChanges.length} milestone-touched code file(s) not on current "${mainBranch}". ` +
-                    `Aborting worktree teardown to prevent data loss.`);
-            }
-        }
-        debugLog("mergeMilestoneToMain", {
-            action: "skip-squash-already-merged",
-            milestoneId,
-            milestoneBranch,
-            mainBranch,
-        });
-        try {
-            clearProjectRootStateFiles(originalBasePath_, milestoneId);
-        }
-        catch (err) {
-            logWarning("worktree", `clearProjectRootStateFiles failed during already-merged cleanup: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        try {
-            removeWorktree(originalBasePath_, milestoneId, {
-                branch: milestoneBranch,
-                deleteBranch: false,
-            });
-        }
-        catch (err) {
-            logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        try {
-            nativeBranchDelete(originalBasePath_, milestoneBranch);
-        }
-        catch (err) {
-            logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        setActiveWorkspace(null);
-        nudgeGitBranchCache(previousCwd);
-        try {
-            process.chdir(originalBasePath_);
-        }
-        catch (err) {
-            logWarning("worktree", `chdir to project root after already-merged cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
-    }
-    // 7. Shelter queued milestone directories before the squash merge (#2505).
-    // The milestone branch may contain copies of queued milestone dirs (via
-    // copyPlanningArtifacts), so `git merge --squash` rejects when those same
-    // 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 planningDir = milestonesDir(originalBasePath_);
-    const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
-    const shelteredDirs = [];
-    let shelterRestored = false;
-    const mergeDirNames = new Set([milestoneId]);
-    const resolvedMergeDir = resolveMilestonePath(originalBasePath_, milestoneId);
-    if (resolvedMergeDir) {
-        mergeDirNames.add(basename(resolvedMergeDir));
-    }
-    else {
-        mergeDirNames.add(canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
-    }
-    // Helper: restore sheltered milestone directories (#2505).
-    // Called on both success and error paths to ensure queued CONTEXT files
-    // 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(planningDir, { recursive: true });
-                // Test seam: when _restoreEntryFn is injected, route the copy through it
-                // so the best-effort failure path (and shelter-retention guarantee) can
-                // be exercised deterministically. Production leaves it null → real cpSync.
-                const dest = join(planningDir, dirName);
-                if (_restoreEntryFn) {
-                    _restoreEntryFn(src, dest);
-                }
-                else {
-                    cpSync(src, dest, { recursive: true, force: true });
-                }
-            }
-            catch (err) { /* best-effort */
-                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) { /* best-effort */
-                logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    };
-    try {
-        if (existsSync(planningDir)) {
-            const entries = readdirSync(planningDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                // Only shelter directories that do NOT belong to the milestone being merged
-                if (mergeDirNames.has(entry.name))
-                    continue;
-                const srcDir = join(planningDir, entry.name);
-                const dstDir = join(shelterDir, entry.name);
-                try {
-                    mkdirSync(shelterDir, { recursive: true });
-                    cpSync(srcDir, dstDir, { recursive: true, force: true });
-                    rmSync(srcDir, { recursive: true, force: true });
-                    shelteredDirs.push(entry.name);
-                }
-                catch (err) {
-                    // Non-fatal — if shelter fails, the merge may still succeed
-                    logWarning("worktree", `milestone shelter failed (${entry.name}): ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-        }
-    }
-    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)}`);
-    }
-    // 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/phases/*` (or legacy 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 ? getWorkflowDatabasePath() : null;
-    if (needsDbCycle) {
-        try {
-            closeWorkflowDatabase();
-        }
-        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)}`);
-    }
-    // 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);
-    if (needsDbCycle && dbPathToReopen) {
-        try {
-            openWorkflowDatabasePath(dbPathToReopen);
-        }
-        catch (err) {
-            logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    if (!mergeResult.success) {
-        // Dirty working tree — the merge was rejected before it started (e.g.
-        // 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.
-            if (stashed) {
-                try {
-                    popStashByRef(originalBasePath_, stashMarker);
-                }
-                catch (err) { /* stash pop conflict is non-fatal */
-                    logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            restoreShelter();
-            // 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).
-                if (stashed) {
-                    try {
-                        popStashByRef(originalBasePath_, stashMarker);
-                    }
-                    catch (err) { /* stash pop conflict is non-fatal */
-                        logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-                restoreShelter();
-                // 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).
-    // Pop after commit so stashed changes do not interfere with the squash merge
-    // 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 {
-            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
-            // every subsequent merge.  Auto-resolve them the same way we handle
-            // .gsd/ conflicts during the merge itself: accept HEAD (the just-committed
-            // version) and drop the now-applied stash.
-            const uu = nativeConflictFiles(originalBasePath_);
-            const gsdUU = uu.filter((f) => f.startsWith(".gsd/"));
-            const nonGsdUU = uu.filter((f) => !f.startsWith(".gsd/"));
-            const stashPopMessage = e instanceof Error ? e.message : String(e);
-            const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
-            const gsdContentConflicts = [];
-            const alreadyExists = stashAlreadyExistsFilesFromError(e);
-            // Untracked-file restore failures can leave marker conflicts in tracked
-            // .gsd JSONL files without producing `U` status entries.
-            if (isUntrackedRestoreFailure) {
-                gsdContentConflicts.push(...gsdJsonlFilesWithConflictMarkers(originalBasePath_));
-            }
-            const gsdConflictFiles = [...new Set([...gsdUU, ...gsdContentConflicts])];
-            if (gsdConflictFiles.length > 0) {
-                for (const f of gsdConflictFiles) {
-                    try {
-                        // Accept the committed (HEAD) version of the state file
-                        execFileSync("git", ["checkout", "HEAD", "--", f], {
-                            cwd: originalBasePath_,
-                            stdio: ["ignore", "pipe", "pipe"],
-                            encoding: "utf-8",
-                        });
-                        nativeAddPaths(originalBasePath_, [f]);
-                    }
-                    catch (e) {
-                        // Last resort: remove the conflicted state file
-                        logWarning("worktree", `checkout HEAD failed for ${f}, removing: ${e.message}`);
-                        nativeRmForce(originalBasePath_, [f]);
-                    }
-                }
-            }
-            if (gsdConflictFiles.length > 0 && nonGsdUU.length === 0) {
-                // All detected conflicts were .gsd/ files. Before dropping, verify no
-                // unresolved non-.gsd conflict markers or unmerged entries remain.
-                const remainingUnmerged = nativeConflictFiles(originalBasePath_);
-                const nonGsdUnmerged = remainingUnmerged.filter((f) => !f.startsWith(".gsd/"));
-                const markerCandidates = Array.from(new Set([
-                    ...nonGsdUnmerged,
-                    ...nativeLsFiles(originalBasePath_, "."),
-                ])).filter((f) => !f.startsWith(".gsd/"));
-                const nonGsdMarkerConflicts = markerCandidates.filter((f) => hasConflictMarkers(join(originalBasePath_, 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(", "),
-                    });
-                }
-                // No non-.gsd conflicts remain — safe to drop the stash.
-                if (!hasRemainingNonGsdConflicts && 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)}`);
-                    }
-                }
-                else if (!hasRemainingNonGsdConflicts) {
-                    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
-                }
-            }
-            else if (gsdUU.length === 0 &&
-                nonGsdUU.length === 0 &&
-                alreadyExists.length > 0) {
-                // Untracked-file restore failure from stash pop where all collided paths
-                // already exist after merge (committed on target). Safe to drop the stash
-                // for the full alreadyExists set — they were untracked on source by
-                // definition of the "already exists, no checkout" failure.
-                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)}`);
-                    }
-                }
-                else {
-                    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
-                }
-            }
-            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).
-    restoreShelter();
-    // 9b. Safety check (#1792): if nothing was committed, verify the milestone
-    // work is already on the integration branch before allowing teardown.
-    // Compare only non-.gsd/ paths — .gsd/ state files diverge normally and
-    // are auto-resolved during the squash merge.
-    if (nothingToCommit) {
-        const numstat = nativeDiffNumstat(originalBasePath_, mainBranch, milestoneBranch);
-        const codeChanges = numstat.filter((entry) => !entry.path.startsWith(".gsd/"));
-        if (codeChanges.length > 0) {
-            // Milestone has unanchored code changes — abort teardown.
-            process.chdir(previousCwd);
-            throw new GSDError(GSD_GIT_ERROR, `${effectiveStrategy === "merge" ? "Merge" : "Squash merge"} produced nothing to commit but milestone branch "${milestoneBranch}" ` +
-                `has ${codeChanges.length} code file(s) not on "${mainBranch}". ` +
-                `Aborting worktree teardown to prevent data loss.`);
-        }
-    }
-    // 9c. Detect whether any non-.gsd/ code files were actually merged (#1906).
-    // 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 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) {
-            // 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;
-            }
-        }
-    }
-    const finalizeMilestoneCleanup = () => {
-        // 12. Remove worktree directory first (must happen before branch deletion)
-        try {
-            removeWorktree(originalBasePath_, milestoneId, {
-                branch: milestoneBranch,
-                deleteBranch: false,
-            });
-        }
-        catch (err) {
-            // Best-effort -- worktree dir may already be gone
-            logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        // 13. Delete milestone branch (after worktree removal so ref is unlocked)
-        try {
-            nativeBranchDelete(originalBasePath_, milestoneBranch);
-        }
-        catch (err) {
-            // Best-effort
-            logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        // 14. Clear module state
-        setActiveWorkspace(null);
-        nudgeGitBranchCache(previousCwd);
-        // 15. Anchor cwd at the project root on success-return. Step 12 removed
-        // the worktree dir; if cwd was inside it, every subsequent process.cwd()
-        // would throw ENOENT and trip auto/run-unit.ts:50's session-failed cancel
-        // path (the de73fb43d regression that closes headless gsd auto). Step 3
-        // already chdir'd here, but defending the success-return contract makes
-        // future maintainers safe against intervening chdir's between step 3 and
-        // here.
-        try {
-            // process.cwd() can throw ENOENT when cwd was removed, so attempt
-            // recovery directly.
-            process.chdir(originalBasePath_);
-        }
-        catch (err) {
-            logWarning("worktree", `chdir to project root after merge failed: ${err instanceof Error ? err.message : String(err)}`);
-            debugLog("mergeMilestoneToMain", {
-                phase: "post-merge-chdir-failed",
-                target: originalBasePath_,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-    };
-    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: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
-            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): if the worktree still has uncommitted
-        // changes (e.g. nativeHasChanges cache returned stale false), abort teardown.
-        // Committing here would be too late: the squash merge to the integration
-        // branch already happened, so a new milestone-branch commit would not be
-        // included and branch deletion could drop the only ref to that work.
-        //
-        // Guard: only run when worktreeCwd is on the milestone branch (#2929).
-        // In parallel mode or branch-mode merges, worktreeCwd may be the project
-        // root on the integration branch. Committing dirty state there would
-        // capture unrelated files from other milestones.
-        if (existsSync(worktreeCwd)) {
-            let preTeardownBranch = null;
-            try {
-                preTeardownBranch = nativeGetCurrentBranch(worktreeCwd);
-            }
-            catch (err) {
-                debugLog("mergeMilestoneToMain", { phase: "pre-teardown-branch-detect-failed", error: String(err) });
-            }
-            const isOnMilestoneBranch = preTeardownBranch === milestoneBranch;
-            if (isOnMilestoneBranch) {
-                try {
-                    const dirtyCheck = nativeWorkingTreeStatus(worktreeCwd);
-                    if (dirtyCheck) {
-                        process.chdir(previousCwd);
-                        throw new GSDError(GSD_GIT_ERROR, `Milestone worktree still has uncommitted changes after squash merge. ` +
-                            `Aborting teardown to preserve ${milestoneBranch}. Status:\n${dirtyCheck}`);
-                    }
-                }
-                catch (e) {
-                    if (e instanceof GSDError)
-                        throw e;
-                    debugLog("mergeMilestoneToMain", {
-                        phase: "pre-teardown-dirty-check-error",
-                        error: String(e),
-                    });
-                }
-            }
-        }
-        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.`);
-        }
-    }
-}