gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

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

@@ -16,7 +16,7 @@
  * call the same body during its internal `mergeAndEnterNext` recursion without
  * a circular reference. Both classes share the body until the Resolver retires.
  */
-import { existsSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { debugLog } from "./debug-logger.js";
@@ -26,8 +26,28 @@ import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare, } from "./
 import { claimMilestoneLease, refreshMilestoneLease, releaseMilestoneLease, } from "./db/milestone-leases.js";
 import { MergeConflictError } from "./git-service.js";
 import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain, } from "./slice-cadence.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
+// ADR-016 phase 2 / C3 (#5626): cache + preferences + path helpers inlined
+// as direct imports. They are leaf-level functions that do not vary across
+// callers — production wiring previously injected them via deps; the seam
+// added type churn without enabling test variation.
+import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { invalidateAllCaches } from "./cache.js";
+import { resolveMilestoneFile } from "./paths.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
+// ADR-016 phase 2 / C1 (#5624): file-system + git-CLI leaf primitives
+// inlined as direct imports rather than injected through `WorktreeLifecycleDeps`.
+// These four symbols (`readFileSync` from node:fs, `getCurrentBranch` and
+// `autoCommitCurrentBranch` from `./worktree.js`, `nativeCheckoutBranch` from
+// `./native-git-bridge.js`) are leaf-level primitives — no environment varies
+// across callers — so the dependency-injection seam they used to inhabit was
+// adding type churn without enabling any test variation.
+import { autoCommitCurrentBranch, getCurrentBranch, } from "./worktree.js";
+import { nativeCheckoutBranch } from "./native-git-bridge.js";
+// ADR-016 phase 2 / C2 (#5625): worktree-manager helpers inlined from
+// `./auto-worktree.js`. These seven functions are not real seams — Lifecycle
+// is the only Module that calls them, and they live alongside the Module's
+// other primitives in `auto-worktree.ts`.
+import { autoWorktreeBranch, createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, getAutoWorktreePath, isInAutoWorktree, teardownAutoWorktree, } from "./auto-worktree.js";
 /**
  * Internal sentinel — thrown by `_mergeBranchMode` when it has already
  * emitted a user-visible error. The outer `mergeAndExit` catches the type
@@ -59,6 +79,85 @@ function isValidMilestoneId(milestoneId) {
 function invalidMilestoneIdError(milestoneId) {
     return new Error(`Invalid milestoneId: ${milestoneId} — contains path separators or traversal`);
 }
+function primitiveOverrides(deps) {
+    return deps;
+}
+function readLifecycleFile(deps, path) {
+    return primitiveOverrides(deps).readFileSync?.(path, "utf-8") ??
+        readFileSync(path, "utf-8");
+}
+function currentLifecycleBranch(deps, basePath) {
+    return primitiveOverrides(deps).getCurrentBranch?.(basePath) ??
+        getCurrentBranch(basePath);
+}
+function checkoutLifecycleBranch(deps, basePath, branch) {
+    const checkoutBranch = primitiveOverrides(deps).checkoutBranch;
+    if (checkoutBranch) {
+        checkoutBranch(basePath, branch);
+        return;
+    }
+    nativeCheckoutBranch(basePath, branch);
+}
+function autoCommitLifecycleBranch(deps, basePath, unitType, unitId) {
+    return primitiveOverrides(deps).autoCommitCurrentBranch?.(basePath, unitType, unitId) ?? autoCommitCurrentBranch(basePath, unitType, unitId);
+}
+// ADR-016 phase 2 / C2-inlined worktree-manager primitives — helpers that
+// honour the structural-typing override pattern so legacy test fixtures keep
+// working without rewriting them onto real-git fixtures.
+function lifecycleIsInAutoWorktree(deps, basePath) {
+    return primitiveOverrides(deps).isInAutoWorktree?.(basePath) ??
+        isInAutoWorktree(basePath);
+}
+function lifecycleAutoWorktreeBranch(deps, milestoneId) {
+    return primitiveOverrides(deps).autoWorktreeBranch?.(milestoneId) ??
+        autoWorktreeBranch(milestoneId);
+}
+function lifecycleTeardownAutoWorktree(deps, basePath, milestoneId, opts) {
+    const override = primitiveOverrides(deps).teardownAutoWorktree;
+    if (override) {
+        override(basePath, milestoneId, opts);
+        return;
+    }
+    teardownAutoWorktree(basePath, milestoneId, opts);
+}
+function lifecycleCreateAutoWorktree(deps, basePath, milestoneId) {
+    return primitiveOverrides(deps).createAutoWorktree?.(basePath, milestoneId) ??
+        createAutoWorktree(basePath, milestoneId);
+}
+function lifecycleEnterAutoWorktree(deps, basePath, milestoneId) {
+    return primitiveOverrides(deps).enterAutoWorktree?.(basePath, milestoneId) ??
+        enterAutoWorktree(basePath, milestoneId);
+}
+function lifecycleEnterBranchMode(deps, basePath, milestoneId) {
+    const override = primitiveOverrides(deps).enterBranchModeForMilestone;
+    if (override) {
+        override(basePath, milestoneId);
+        return;
+    }
+    enterBranchModeForMilestone(basePath, milestoneId);
+}
+// ADR-016 phase 2 / C3-inlined cache + preferences + path helpers.
+function lifecycleGetIsolationMode(deps, basePath) {
+    return primitiveOverrides(deps).getIsolationMode?.(basePath) ??
+        getIsolationMode(basePath);
+}
+function lifecycleInvalidateAllCaches(deps) {
+    const override = primitiveOverrides(deps).invalidateAllCaches;
+    if (override) {
+        override();
+        return;
+    }
+    invalidateAllCaches();
+}
+function lifecycleResolveMilestoneFile(deps, basePath, milestoneId, fileType) {
+    return primitiveOverrides(deps).resolveMilestoneFile?.(basePath, milestoneId, fileType) ?? resolveMilestoneFile(basePath, milestoneId, fileType);
+}
+function lifecycleLoadPreferences(deps, basePath) {
+    const override = primitiveOverrides(deps).loadEffectiveGSDPreferences;
+    if (override)
+        return override(basePath);
+    return loadEffectiveGSDPreferences(basePath);
+}
 /**
  * Throwing variant used by the merge/exit paths that surface failures via
  * the typed `ExitResult` (callers wrap the throw → cause). The enter path
@@ -193,7 +292,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx) {
     // Handles the case where originalBasePath is falsy and basePath is itself
     // a worktree path — prevents double-nested worktree paths (#3729).
     const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-    const mode = deps.getIsolationMode(basePath);
+    const mode = getIsolationMode(basePath);
     if (mode === "none") {
         debugLog("WorktreeLifecycle", {
             action: "enterMilestone",
@@ -231,12 +330,12 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx) {
     // ── Branch mode: create/checkout milestone branch, stay in project root ──
     if (mode === "branch") {
         try {
-            deps.enterBranchModeForMilestone(basePath, milestoneId);
+            lifecycleEnterBranchMode(deps, basePath, milestoneId);
             // basePath does not change — no worktree, no chdir.
             // Rebuild GitService so the new HEAD is reflected, then flush any
             // path-keyed caches that may have been populated before the checkout.
             rebuildGitService(s, deps);
-            deps.invalidateAllCaches();
+            invalidateAllCaches();
             debugLog("WorktreeLifecycle", {
                 action: "enterMilestone",
                 milestoneId,
@@ -269,17 +368,17 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx) {
     }
     // ── Worktree mode ────────────────────────────────────────────────────────
     try {
-        const existingPath = deps.getAutoWorktreePath(basePath, milestoneId);
+        const existingPath = (primitiveOverrides(deps).getAutoWorktreePath ?? getAutoWorktreePath)(basePath, milestoneId);
         let wtPath;
         if (existingPath) {
-            wtPath = deps.enterAutoWorktree(basePath, milestoneId);
+            wtPath = lifecycleEnterAutoWorktree(deps, basePath, milestoneId);
         }
         else {
-            wtPath = deps.createAutoWorktree(basePath, milestoneId);
+            wtPath = lifecycleCreateAutoWorktree(deps, basePath, milestoneId);
         }
         s.basePath = wtPath;
         rebuildGitService(s, deps);
-        deps.invalidateAllCaches();
+        invalidateAllCaches();
         // Per ADR-016: Lifecycle calls Projection on entry, before any Unit
         // dispatches. Build a temporary scope from the new basePath; callers may
         // later set s.scope via their own rebuildScope hook (the two are
@@ -354,9 +453,411 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx) {
         return { ok: false, reason: "creation-failed", cause: err };
     }
 }
+/**
+ * Resolve the basePath to adopt on resume from a paused session.
+ *
+ * Returns `persistedWorktreePath` when the path is non-null and exists on
+ * disk; otherwise falls back to `base`. Used by
+ * `WorktreeLifecycle.resumeFromPausedSession` (#5621). Exported as a pure
+ * function so unit tests can exercise the path-resolution logic without
+ * constructing a `WorktreeLifecycle` instance.
+ *
+ * The optional `pathExists` parameter exists only for tests that need to
+ * substitute a stub for `existsSync`.
+ */
+export function resolvePausedResumeBasePath(base, persistedWorktreePath, pathExists = existsSync) {
+    return persistedWorktreePath && pathExists(persistedWorktreePath)
+        ? persistedWorktreePath
+        : base;
+}
 function rebuildGitService(s, deps) {
-    const gitConfig = deps.loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-    s.gitService = new deps.GitServiceImpl(s.basePath, gitConfig);
+    // ADR-016 phase 2 / C4 (#5627): the gitConfig load and constructor
+    // construction live behind `gitServiceFactory`. Lifecycle no longer
+    // sees the constructor shape, the gitConfig type, or the unknown→
+    // GitService cast.
+    s.gitService = deps.gitServiceFactory(s.basePath);
+}
+// ─── Session-less merge entry (ADR-016 phase 2 / A1) ─────────────────────
+/**
+ * Worktree-mode merge body. Session-less — operates on a `MergeContext`.
+ *
+ * On error: emits the "worktree-merge-failed" journal event, notifies the
+ * user, cleans up stale `SQUASH_MSG` / `MERGE_HEAD` / `MERGE_MSG` files
+ * (#1389), and chdirs back to project root before rethrowing. Session-side
+ * cleanup (`restoreToProjectRoot`, `gitService` rebuild) is the caller's
+ * responsibility.
+ */
+function _mergeWorktreeModeImpl(deps, mctx) {
+    const { originalBasePath, worktreeBasePath, milestoneId, notify } = mctx;
+    if (!originalBasePath) {
+        debugLog("WorktreeLifecycle", {
+            action: "mergeAndExit",
+            milestoneId,
+            mode: "worktree",
+            skipped: true,
+            reason: "missing-original-base",
+        });
+        return {
+            merged: false,
+            mode: "worktree",
+            codeFilesChanged: false,
+            pushed: false,
+        };
+    }
+    try {
+        // ADR-016: final projection before teardown. Replaces the legacy
+        // syncWorktreeStateBack(originalBase, basePath, milestoneId) call.
+        const finalScope = scopeMilestone(createWorkspace(worktreeBasePath), milestoneId);
+        const { synced } = deps.worktreeProjection.finalizeProjectionForMerge(finalScope);
+        if (synced.length > 0) {
+            debugLog("WorktreeLifecycle", {
+                action: "mergeAndExit",
+                milestoneId,
+                phase: "reverse-sync",
+                synced: synced.length,
+            });
+        }
+        // Resolve roadmap — try project root first, then worktree path as
+        // fallback. The worktree may hold the only copy when state-back
+        // projection silently dropped it or .gsd/ is not symlinked. Without
+        // the fallback, a missing roadmap triggers bare teardown which
+        // deletes the branch and orphans all milestone commits (#1573).
+        let roadmapPath = resolveMilestoneFile(originalBasePath, milestoneId, "ROADMAP");
+        if (!roadmapPath &&
+            !isSamePathPhysical(worktreeBasePath, originalBasePath)) {
+            roadmapPath = resolveMilestoneFile(worktreeBasePath, milestoneId, "ROADMAP");
+            if (roadmapPath) {
+                debugLog("WorktreeLifecycle", {
+                    action: "mergeAndExit",
+                    milestoneId,
+                    phase: "roadmap-fallback",
+                    note: "resolved from worktree path",
+                });
+            }
+        }
+        if (!roadmapPath) {
+            // No roadmap at either location — teardown but PRESERVE the branch
+            // so commits are not orphaned (#1573).
+            lifecycleTeardownAutoWorktree(deps, originalBasePath, milestoneId, {
+                preserveBranch: true,
+            });
+            notify(`Exited worktree for ${milestoneId} (no roadmap found — branch preserved for manual merge).`, "warning");
+            return {
+                merged: false,
+                mode: "worktree",
+                codeFilesChanged: false,
+                pushed: false,
+            };
+        }
+        const roadmapContent = readLifecycleFile(deps, roadmapPath);
+        const mergeResult = deps.mergeMilestoneToMain(originalBasePath, milestoneId, roadmapContent);
+        // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
+        // cleanup internally (step 12), but it can silently fail on Windows
+        // or when the worktree directory is locked. Perform a secondary
+        // teardown here to ensure the worktree is properly cleaned up.
+        // Idempotent — if already removed, teardownAutoWorktree no-ops.
+        try {
+            lifecycleTeardownAutoWorktree(deps, originalBasePath, milestoneId);
+        }
+        catch {
+            // Best-effort — primary cleanup in mergeMilestoneToMain may have
+            // already removed the worktree.
+        }
+        if (mergeResult.codeFilesChanged) {
+            notify(`Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
+        }
+        else {
+            // #1906 — milestone produced only .gsd/ metadata. Surface
+            // clearly so the user knows the milestone is not truly complete.
+            notify(`WARNING: Milestone ${milestoneId} merged to main but contained NO code changes — only .gsd/ metadata files. ` +
+                `The milestone summary may describe planned work that was never implemented. ` +
+                `Review the milestone output and re-run if code is missing.`, "warning");
+        }
+        return {
+            merged: true,
+            mode: "worktree",
+            codeFilesChanged: mergeResult.codeFilesChanged,
+            pushed: mergeResult.pushed,
+            commitMessage: mergeResult.commitMessage,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        debugLog("WorktreeLifecycle", {
+            action: "mergeAndExit",
+            milestoneId,
+            result: "error",
+            error: msg,
+            fallback: "chdir-to-project-root",
+        });
+        emitJournalEvent(originalBasePath || worktreeBasePath, {
+            ts: new Date().toISOString(),
+            flowId: randomUUID(),
+            seq: 0,
+            eventType: "worktree-merge-failed",
+            data: { milestoneId, error: msg },
+        });
+        // Surface a clear, actionable error. Worktree and milestone branch
+        // are intentionally preserved — nothing has been deleted. User can
+        // retry /gsd dispatch complete-milestone or merge manually once the
+        // underlying issue is fixed (#1668, #1891).
+        notify(`Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry with \`/gsd dispatch complete-milestone\` or merge manually.`, "warning");
+        // Clean up stale merge state left by failed squash-merge (#1389)
+        try {
+            const gitDir = join(originalBasePath || worktreeBasePath, ".git");
+            for (const f of ["SQUASH_MSG", "MERGE_HEAD", "MERGE_MSG"]) {
+                const p = join(gitDir, f);
+                if (existsSync(p))
+                    unlinkSync(p);
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+        // Error recovery: chdir back to project root only when no real worktree
+        // path is available. Session-side cleanup (restoreToProjectRoot,
+        // gitService rebuild) is the caller's responsibility.
+        if (originalBasePath && !worktreeBasePath) {
+            try {
+                process.chdir(originalBasePath);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        // Re-throw: MergeConflictError stops the auto loop (#2330);
+        // non-conflict errors must also propagate so broken states are
+        // diagnosable (#4380).
+        throw err;
+    }
+}
+/**
+ * Branch-mode merge body. Session-less.
+ *
+ * Session-side `gitService` rebuild after HEAD changes is the caller's
+ * responsibility. The branch-mode `UserNotifiedError` sentinel still flows
+ * through unchanged so the outer caller can suppress duplicate toasts.
+ */
+function _mergeBranchModeImpl(deps, mctx) {
+    const { worktreeBasePath, milestoneId, notify } = mctx;
+    try {
+        const currentBranch = currentLifecycleBranch(deps, worktreeBasePath);
+        const milestoneBranch = lifecycleAutoWorktreeBranch(deps, milestoneId);
+        if (currentBranch !== milestoneBranch) {
+            // #5538-followup: previous behaviour was to silently `return false`
+            // when HEAD wasn't on the milestone branch — that let the loop
+            // advance with the milestone's commits stranded on the branch.
+            // Attempt recovery by force-checking-out the milestone branch; if
+            // that fails, throw so the caller pauses auto-mode and the user
+            // sees the failure instead of a silent merge skip.
+            debugLog("WorktreeLifecycle", {
+                action: "mergeAndExit",
+                milestoneId,
+                mode: "branch",
+                recovery: "checkout-milestone-branch",
+                currentBranch,
+                milestoneBranch,
+            });
+            try {
+                checkoutLifecycleBranch(deps, worktreeBasePath, milestoneBranch);
+            }
+            catch (checkoutErr) {
+                const checkoutMsg = checkoutErr instanceof Error
+                    ? checkoutErr.message
+                    : String(checkoutErr);
+                notify(`Cannot merge milestone ${milestoneId}: working tree is on ${currentBranch} and checkout to ${milestoneBranch} failed (${checkoutMsg}). Resolve manually and run /gsd auto to resume.`, "error");
+                throw new UserNotifiedError(checkoutMsg, checkoutErr);
+            }
+            const reverify = currentLifecycleBranch(deps, worktreeBasePath);
+            if (reverify !== milestoneBranch) {
+                const reverifyMsg = `branch checkout to ${milestoneBranch} reported success but current branch is ${reverify}`;
+                notify(`Cannot merge milestone ${milestoneId}: ${reverifyMsg}. Resolve manually and run /gsd auto to resume.`, "error");
+                throw new UserNotifiedError(reverifyMsg);
+            }
+        }
+        const roadmapPath = resolveMilestoneFile(worktreeBasePath, milestoneId, "ROADMAP");
+        if (!roadmapPath) {
+            debugLog("WorktreeLifecycle", {
+                action: "mergeAndExit",
+                milestoneId,
+                mode: "branch",
+                skipped: true,
+                reason: "no-roadmap",
+            });
+            return {
+                merged: false,
+                mode: "branch",
+                codeFilesChanged: false,
+                pushed: false,
+            };
+        }
+        const roadmapContent = readLifecycleFile(deps, roadmapPath);
+        const mergeResult = deps.mergeMilestoneToMain(worktreeBasePath, milestoneId, roadmapContent);
+        if (mergeResult.codeFilesChanged) {
+            notify(`Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
+        }
+        else {
+            notify(`WARNING: Milestone ${milestoneId} merged (branch mode) but contained NO code changes — only .gsd/ metadata. ` +
+                `Review the milestone output and re-run if code is missing.`, "warning");
+        }
+        debugLog("WorktreeLifecycle", {
+            action: "mergeAndExit",
+            milestoneId,
+            mode: "branch",
+            result: "success",
+        });
+        return {
+            merged: true,
+            mode: "branch",
+            codeFilesChanged: mergeResult.codeFilesChanged,
+            pushed: mergeResult.pushed,
+            commitMessage: mergeResult.commitMessage,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        debugLog("WorktreeLifecycle", {
+            action: "mergeAndExit",
+            milestoneId,
+            mode: "branch",
+            result: "error",
+            error: msg,
+        });
+        if (!(err instanceof UserNotifiedError)) {
+            notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+        }
+        // Re-throw all errors so callers can apply their own recovery (#4380).
+        throw err;
+    }
+}
+/**
+ * Session-less merge entry (ADR-016 phase 2 / A1, issue #5618).
+ *
+ * Runs the worktree-mode or branch-mode merge body without touching session
+ * state. Used directly by `parallel-merge.ts` and indirectly (via
+ * `_mergeAndExit`) by the single-loop path. Caller is responsible for any
+ * session-side cleanup based on the returned `mode`.
+ *
+ * **CWD anchor**: anchors `process.cwd()` at `originalBasePath` before
+ * non-worktree merge paths to mirror the single-loop guard against ENOENT
+ * after teardown (de73fb43d). Worktree-mode merge paths keep the real
+ * worktree as cwd because `mergeMilestoneToMain()` infers source worktree
+ * state from `process.cwd()`. Best-effort; silent on failure.
+ *
+ * **Failure handling**: `MergeConflictError` and other unrecoverable errors
+ * propagate to the caller. The caller is responsible for any state restore
+ * (single-loop callers re-`chdir` and `restoreToProjectRoot`; parallel
+ * callers surface to the user as a `MergeResult` with `success: false`).
+ */
+export function mergeMilestoneStandalone(deps, mctx) {
+    const { originalBasePath, worktreeBasePath, milestoneId, notify } = mctx;
+    validateMilestoneId(milestoneId);
+    if (mctx.isolationDegraded) {
+        if (originalBasePath) {
+            try {
+                process.chdir(originalBasePath);
+            }
+            catch (err) {
+                debugLog("WorktreeLifecycle", {
+                    action: "mergeAndExit",
+                    phase: "pre-merge-chdir-failed",
+                    milestoneId,
+                    originalBasePath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        debugLog("WorktreeLifecycle", {
+            action: "mergeAndExit",
+            milestoneId,
+            skipped: true,
+            reason: "isolation-degraded",
+        });
+        notify(`Skipping worktree merge for ${milestoneId} — isolation was degraded (worktree creation failed earlier). Work is on the current branch.`, "info");
+        return {
+            merged: false,
+            mode: "skipped",
+            codeFilesChanged: false,
+            pushed: false,
+        };
+    }
+    const mode = getIsolationMode(originalBasePath || worktreeBasePath);
+    debugLog("WorktreeLifecycle", {
+        action: "mergeAndExit",
+        milestoneId,
+        mode,
+        basePath: worktreeBasePath,
+    });
+    emitJournalEvent(originalBasePath || worktreeBasePath, {
+        ts: new Date().toISOString(),
+        flowId: randomUUID(),
+        seq: 0,
+        eventType: "worktree-merge-start",
+        data: { milestoneId, mode },
+    });
+    // #2625: If we are physically inside an auto-worktree, we MUST merge
+    // regardless of the current isolation config. This prevents data loss
+    // when the default isolation mode changes between versions.
+    const inWorktree = lifecycleIsInAutoWorktree(deps, worktreeBasePath) && Boolean(originalBasePath);
+    if (mode === "none" && !inWorktree) {
+        debugLog("WorktreeLifecycle", {
+            action: "mergeAndExit",
+            milestoneId,
+            skipped: true,
+            reason: "mode-none",
+        });
+        // Anchor cwd at project root before the early return so subsequent
+        // process.cwd() calls after the skip don't ENOENT if we were inside a
+        // worktree directory that gets torn down later. Best-effort.
+        if (originalBasePath) {
+            try {
+                process.chdir(originalBasePath);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        return {
+            merged: false,
+            mode: "skipped",
+            codeFilesChanged: false,
+            pushed: false,
+        };
+    }
+    // Set cwd to the correct anchor before dispatching to mode implementations.
+    // Worktree mode / in-worktree override must run from the live worktree so
+    // mergeMilestoneToMain can find worktree-local state; branch mode runs from
+    // the original project root. Best-effort for synthetic test paths.
+    const targetCwd = mode === "worktree" || inWorktree
+        ? worktreeBasePath
+        : originalBasePath;
+    if (targetCwd) {
+        try {
+            process.chdir(targetCwd);
+        }
+        catch (err) {
+            debugLog("WorktreeLifecycle", {
+                action: "mergeAndExit",
+                phase: "pre-merge-chdir-failed",
+                milestoneId,
+                targetCwd,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (mode === "worktree" || inWorktree) {
+        return _mergeWorktreeModeImpl(deps, mctx);
+    }
+    if (mode === "branch") {
+        return _mergeBranchModeImpl(deps, mctx);
+    }
+    // Defensive fallback — should not reach here given the mode-none guard above.
+    return {
+        merged: false,
+        mode: "skipped",
+        codeFilesChanged: false,
+        pushed: false,
+    };
 }
 // ─── Module class ────────────────────────────────────────────────────────
 /**
@@ -401,7 +902,11 @@ export class WorktreeLifecycle {
         if (opts.merge) {
             try {
                 const merged = this._mergeAndExit(milestoneId, ctx);
-                return { ok: true, merged, codeFilesChanged: false };
+                return {
+                    ok: true,
+                    merged: merged.merged,
+                    codeFilesChanged: merged.codeFilesChanged,
+                };
             }
             catch (err) {
                 if (err instanceof MergeConflictError) {
@@ -435,7 +940,7 @@ export class WorktreeLifecycle {
         let merged = false;
         let mergeThrew = false;
         try {
-            merged = this._mergeAndExit(currentMilestoneId, ctx);
+            merged = this._mergeAndExit(currentMilestoneId, ctx).merged;
         }
         catch (err) {
             if (err instanceof UserNotifiedError)
@@ -470,7 +975,7 @@ export class WorktreeLifecycle {
     // ── Private — exit without merge ─────────────────────────────────────
     _exitWithoutMerge(milestoneId, ctx, opts) {
         validateMilestoneId(milestoneId);
-        if (!this.deps.isInAutoWorktree(this.s.basePath)) {
+        if (!lifecycleIsInAutoWorktree(this.deps, this.s.basePath)) {
             debugLog("WorktreeLifecycle", {
                 action: "exitMilestone",
                 milestoneId,
@@ -485,7 +990,7 @@ export class WorktreeLifecycle {
             basePath: this.s.basePath,
         });
         try {
-            this.deps.autoCommitCurrentBranch(this.s.basePath, "stop", milestoneId);
+            autoCommitLifecycleBranch(this.deps, this.s.basePath, "stop", milestoneId);
         }
         catch (err) {
             debugLog("WorktreeLifecycle", {
@@ -494,7 +999,7 @@ export class WorktreeLifecycle {
                 phase: "auto-commit-failed",
                 error: err instanceof Error ? err.message : String(err),
             });
-            ctx.notify(`Auto-commit before exiting ${milestoneId} failed: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`, "warning");
+            ctx.notify(`Auto-commit before exiting ${milestoneId} failed: ${err instanceof Error ? err.message : String(err)}. Branch ${lifecycleAutoWorktreeBranch(this.deps, milestoneId)} is preserved for recovery.`, "warning");
         }
         if (this.s.originalBasePath) {
             try {
@@ -508,12 +1013,12 @@ export class WorktreeLifecycle {
                     originalBasePath: this.s.originalBasePath,
                     error: err instanceof Error ? err.message : String(err),
                 });
-                ctx.notify(`Could not leave milestone worktree before cleanup: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`, "warning");
+                ctx.notify(`Could not leave milestone worktree before cleanup: ${err instanceof Error ? err.message : String(err)}. Branch ${lifecycleAutoWorktreeBranch(this.deps, milestoneId)} is preserved for recovery.`, "warning");
             }
         }
         let teardownFailed = false;
         try {
-            this.deps.teardownAutoWorktree(this.s.originalBasePath, milestoneId, {
+            lifecycleTeardownAutoWorktree(this.deps, this.s.originalBasePath, milestoneId, {
                 preserveBranch: opts.preserveBranch ?? false,
             });
         }
@@ -525,7 +1030,7 @@ export class WorktreeLifecycle {
                 phase: "teardown-failed",
                 error: err instanceof Error ? err.message : String(err),
             });
-            ctx.notify(`Worktree cleanup failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`, "warning");
+            ctx.notify(`Worktree cleanup failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Branch ${lifecycleAutoWorktreeBranch(this.deps, milestoneId)} is preserved for recovery.`, "warning");
         }
         this.restoreToProjectRoot();
         debugLog("WorktreeLifecycle", {
@@ -542,91 +1047,56 @@ export class WorktreeLifecycle {
     /**
      * Merge the completed milestone branch back to main and exit the worktree.
      *
-     * - **worktree mode**: reads the roadmap, runs squash merge, projects
-     *   final state back via Projection.finalizeProjectionForMerge, tears
-     *   down the worktree, restores `s.basePath`. Falls back to bare
-     *   teardown (preserving the branch) if no roadmap exists.
-     * - **branch mode**: validates HEAD is on the milestone branch (recovers
-     *   via checkout if not), merges, rebuilds GitService.
-     * - **none**: no-op unless physically inside an auto-worktree (#2625).
+     * Session-bound wrapper around `mergeMilestoneStandalone`. Builds a
+     * `MergeContext` from `this.s`, layers session-side bookkeeping on top of
+     * the result:
+     *
+     * - resquash-on-merge using `s.milestoneStartShas`
+     * - merge-completion telemetry (duration)
+     * - mode-specific session restore: worktree-mode → `restoreToProjectRoot`,
+     *   branch-mode → `gitService` rebuild
      *
-     * Returns true when an actual squash-merge ran. Throws MergeConflictError
-     * (and other non-recoverable errors) for callers to handle.
+     * Returns the session-less merge result. Errors propagate after
+     * `restoreToProjectRoot()` runs so callers always receive a consistent
+     * session.
      */
     _mergeAndExit(milestoneId, ctx) {
-        validateMilestoneId(milestoneId);
-        // Anchor cwd at the project root before any merge work. Some merge
-        // paths (mergeMilestoneToMain, slice-cadence) chdir explicitly; others
-        // (branch-mode, isolation-degraded skip) do not. If the worktree dir
-        // is later torn down while cwd still points into it, every subsequent
-        // process.cwd() throws ENOENT — which after de73fb43d surfaces as a
-        // session-failed cancel and (in headless mode) terminates the whole
-        // gsd process. Best-effort: silent on failure so synthetic test paths
-        // still pass.
-        if (this.s.originalBasePath) {
-            try {
-                process.chdir(this.s.originalBasePath);
-            }
-            catch (err) {
-                debugLog("WorktreeLifecycle", {
-                    action: "mergeAndExit",
-                    phase: "pre-merge-chdir-failed",
-                    milestoneId,
-                    originalBasePath: this.s.originalBasePath,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
         // #4764 — telemetry: record start timestamp so we can emit merge duration.
         const mergeStartedAt = new Date().toISOString();
         const mergeStartMs = Date.now();
-        if (this.s.isolationDegraded) {
-            debugLog("WorktreeLifecycle", {
-                action: "mergeAndExit",
-                milestoneId,
-                skipped: true,
-                reason: "isolation-degraded",
-            });
-            ctx.notify(`Skipping worktree merge for ${milestoneId} — isolation was degraded (worktree creation failed earlier). Work is on the current branch.`, "info");
-            return false;
-        }
-        const mode = this.deps.getIsolationMode(this.s.originalBasePath || this.s.basePath);
-        debugLog("WorktreeLifecycle", {
-            action: "mergeAndExit",
-            milestoneId,
-            mode,
-            basePath: this.s.basePath,
-        });
-        emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
-            ts: new Date().toISOString(),
-            flowId: randomUUID(),
-            seq: 0,
-            eventType: "worktree-merge-start",
-            data: { milestoneId, mode },
-        });
-        // #2625: If we are physically inside an auto-worktree, we MUST merge
-        // regardless of the current isolation config. This prevents data loss
-        // when the default isolation mode changes between versions.
-        const inWorktree = this.deps.isInAutoWorktree(this.s.basePath) && this.s.originalBasePath;
-        if (mode === "none" && !inWorktree) {
-            debugLog("WorktreeLifecycle", {
-                action: "mergeAndExit",
+        let result;
+        try {
+            result = mergeMilestoneStandalone(this.deps, {
+                originalBasePath: this.s.originalBasePath,
+                worktreeBasePath: this.s.basePath,
                 milestoneId,
-                skipped: true,
-                reason: "mode-none",
+                isolationDegraded: this.s.isolationDegraded,
+                notify: ctx.notify,
             });
-            return false;
-        }
-        let actuallyMerged = false;
-        if (mode === "worktree" || inWorktree) {
-            actuallyMerged = this._mergeWorktreeMode(milestoneId, ctx);
         }
-        else if (mode === "branch") {
-            actuallyMerged = this._mergeBranchMode(milestoneId, ctx);
+        catch (err) {
+            // Standalone has already done its session-less cleanup
+            // (chdir, SQUASH_MSG cleanup, journal event). Layer session-side
+            // restore on top so callers get a consistent session.
+            this.restoreToProjectRoot();
+            throw err;
         }
-        if (!actuallyMerged) {
+        if (!result.merged) {
+            // Skip / no-roadmap / mode-none paths. milestoneStartShas housekeeping
+            // is unconditional; mode-specific session restore happens for
+            // worktree-mode (preserve-branch path tore down the worktree, so
+            // basePath must restore) and not for branch-mode (no basePath change).
             this.s.milestoneStartShas.delete(milestoneId);
-            return false;
+            if (result.mode === "worktree") {
+                this.restoreToProjectRoot();
+                debugLog("WorktreeLifecycle", {
+                    action: "mergeAndExit",
+                    milestoneId,
+                    result: "done",
+                    basePath: this.s.basePath,
+                });
+            }
+            return result;
         }
         // #4765 — when collapse_cadence=slice AND milestone_resquash=true, the
         // N per-slice commits on main should be collapsed into one milestone
@@ -635,11 +1105,11 @@ export class WorktreeLifecycle {
         try {
             const startSha = this.s.milestoneStartShas.get(milestoneId);
             if (startSha) {
-                const prefs = loadEffectiveGSDPreferences(this.s.originalBasePath || this.s.basePath)?.preferences;
+                const prefs = lifecycleLoadPreferences(this.deps, this.s.originalBasePath || this.s.basePath)?.preferences;
                 if (getCollapseCadence(prefs) === "slice" &&
                     getMilestoneResquash(prefs)) {
-                    const result = resquashMilestoneOnMain(this.s.originalBasePath || this.s.basePath, milestoneId, startSha);
-                    if (result.resquashed) {
+                    const resquashResult = resquashMilestoneOnMain(this.s.originalBasePath || this.s.basePath, milestoneId, startSha);
+                    if (resquashResult.resquashed) {
                         ctx.notify(`slice-cadence: re-squashed slice commits for ${milestoneId} into a single milestone commit.`, "info");
                     }
                 }
@@ -672,232 +1142,27 @@ export class WorktreeLifecycle {
                     : String(telemetryErr),
             });
         }
-        return true;
-    }
-    /** Worktree-mode merge body. Returns true when an actual squash-merge ran. */
-    _mergeWorktreeMode(milestoneId, ctx) {
-        const originalBase = this.s.originalBasePath;
-        if (!originalBase) {
-            debugLog("WorktreeLifecycle", {
-                action: "mergeAndExit",
-                milestoneId,
-                mode: "worktree",
-                skipped: true,
-                reason: "missing-original-base",
-            });
-            return false;
-        }
-        let merged = false;
-        try {
-            // ADR-016: final projection before teardown. Replaces the legacy
-            // syncWorktreeStateBack(originalBase, basePath, milestoneId) call.
-            const finalScope = scopeMilestone(createWorkspace(this.s.basePath), milestoneId);
-            const { synced } = this.deps.worktreeProjection.finalizeProjectionForMerge(finalScope);
-            if (synced.length > 0) {
-                debugLog("WorktreeLifecycle", {
-                    action: "mergeAndExit",
-                    milestoneId,
-                    phase: "reverse-sync",
-                    synced: synced.length,
-                });
-            }
-            // Resolve roadmap — try project root first, then worktree path as
-            // fallback. The worktree may hold the only copy when state-back
-            // projection silently dropped it or .gsd/ is not symlinked. Without
-            // the fallback, a missing roadmap triggers bare teardown which
-            // deletes the branch and orphans all milestone commits (#1573).
-            let roadmapPath = this.deps.resolveMilestoneFile(originalBase, milestoneId, "ROADMAP");
-            if (!roadmapPath &&
-                !isSamePathPhysical(this.s.basePath, originalBase)) {
-                roadmapPath = this.deps.resolveMilestoneFile(this.s.basePath, milestoneId, "ROADMAP");
-                if (roadmapPath) {
-                    debugLog("WorktreeLifecycle", {
-                        action: "mergeAndExit",
-                        milestoneId,
-                        phase: "roadmap-fallback",
-                        note: "resolved from worktree path",
-                    });
-                }
-            }
-            if (roadmapPath) {
-                const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
-                const mergeResult = this.deps.mergeMilestoneToMain(originalBase, milestoneId, roadmapContent);
-                merged = true;
-                // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
-                // cleanup internally (step 12), but it can silently fail on Windows
-                // or when the worktree directory is locked. Perform a secondary
-                // teardown here to ensure the worktree is properly cleaned up.
-                // Idempotent — if already removed, teardownAutoWorktree no-ops.
-                try {
-                    this.deps.teardownAutoWorktree(originalBase, milestoneId);
-                }
-                catch {
-                    // Best-effort — primary cleanup in mergeMilestoneToMain may have
-                    // already removed the worktree.
-                }
-                if (mergeResult.codeFilesChanged) {
-                    ctx.notify(`Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
-                }
-                else {
-                    // #1906 — milestone produced only .gsd/ metadata. Surface
-                    // clearly so the user knows the milestone is not truly complete.
-                    ctx.notify(`WARNING: Milestone ${milestoneId} merged to main but contained NO code changes — only .gsd/ metadata files. ` +
-                        `The milestone summary may describe planned work that was never implemented. ` +
-                        `Review the milestone output and re-run if code is missing.`, "warning");
-                }
-            }
-            else {
-                // No roadmap at either location — teardown but PRESERVE the branch
-                // so commits are not orphaned (#1573).
-                this.deps.teardownAutoWorktree(originalBase, milestoneId, {
-                    preserveBranch: true,
-                });
-                ctx.notify(`Exited worktree for ${milestoneId} (no roadmap found — branch preserved for manual merge).`, "warning");
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
+        // Mode-specific session restore.
+        if (result.mode === "worktree") {
+            this.restoreToProjectRoot();
             debugLog("WorktreeLifecycle", {
                 action: "mergeAndExit",
                 milestoneId,
-                result: "error",
-                error: msg,
-                fallback: "chdir-to-project-root",
+                result: "done",
+                basePath: this.s.basePath,
             });
-            emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
-                ts: new Date().toISOString(),
-                flowId: randomUUID(),
-                seq: 0,
-                eventType: "worktree-merge-failed",
-                data: { milestoneId, error: msg },
-            });
-            // Surface a clear, actionable error. Worktree and milestone branch
-            // are intentionally preserved — nothing has been deleted. User can
-            // retry /gsd dispatch complete-milestone or merge manually once the
-            // underlying issue is fixed (#1668, #1891).
-            ctx.notify(`Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry with \`/gsd dispatch complete-milestone\` or merge manually.`, "warning");
-            // Clean up stale merge state left by failed squash-merge (#1389)
-            try {
-                const gitDir = join(originalBase || this.s.basePath, ".git");
-                for (const f of ["SQUASH_MSG", "MERGE_HEAD", "MERGE_MSG"]) {
-                    const p = join(gitDir, f);
-                    if (existsSync(p))
-                        unlinkSync(p);
-                }
-            }
-            catch {
-                /* best-effort */
-            }
-            // Error recovery: always restore to project root
-            if (originalBase) {
-                try {
-                    process.chdir(originalBase);
-                }
-                catch {
-                    /* best-effort */
-                }
-            }
-            // Restore state before re-throwing so callers always get a
-            // consistent session (#4380).
-            this.restoreToProjectRoot();
-            // Re-throw: MergeConflictError stops the auto loop (#2330);
-            // non-conflict errors must also propagate so broken states are
-            // diagnosable (#4380).
-            throw err;
         }
-        // Always restore basePath and rebuild — whether merge succeeded or failed
-        this.restoreToProjectRoot();
-        debugLog("WorktreeLifecycle", {
-            action: "mergeAndExit",
-            milestoneId,
-            result: "done",
-            basePath: this.s.basePath,
-        });
-        return merged;
-    }
-    /** Branch-mode merge body. Returns true when a merge actually ran. */
-    _mergeBranchMode(milestoneId, ctx) {
-        try {
-            const currentBranch = this.deps.getCurrentBranch(this.s.basePath);
-            const milestoneBranch = this.deps.autoWorktreeBranch(milestoneId);
-            if (currentBranch !== milestoneBranch) {
-                // #5538-followup: previous behaviour was to silently `return false`
-                // when HEAD wasn't on the milestone branch — that let the loop
-                // advance with the milestone's commits stranded on the branch.
-                // Attempt recovery by force-checking-out the milestone branch; if
-                // that fails, throw so the caller pauses auto-mode and the user
-                // sees the failure instead of a silent merge skip.
-                debugLog("WorktreeLifecycle", {
-                    action: "mergeAndExit",
-                    milestoneId,
-                    mode: "branch",
-                    recovery: "checkout-milestone-branch",
-                    currentBranch,
-                    milestoneBranch,
-                });
-                try {
-                    this.deps.checkoutBranch(this.s.basePath, milestoneBranch);
-                }
-                catch (checkoutErr) {
-                    const checkoutMsg = checkoutErr instanceof Error
-                        ? checkoutErr.message
-                        : String(checkoutErr);
-                    ctx.notify(`Cannot merge milestone ${milestoneId}: working tree is on ${currentBranch} and checkout to ${milestoneBranch} failed (${checkoutMsg}). Resolve manually and run /gsd auto to resume.`, "error");
-                    throw new UserNotifiedError(checkoutMsg, checkoutErr);
-                }
-                const reverify = this.deps.getCurrentBranch(this.s.basePath);
-                if (reverify !== milestoneBranch) {
-                    const reverifyMsg = `branch checkout to ${milestoneBranch} reported success but current branch is ${reverify}`;
-                    ctx.notify(`Cannot merge milestone ${milestoneId}: ${reverifyMsg}. Resolve manually and run /gsd auto to resume.`, "error");
-                    throw new UserNotifiedError(reverifyMsg);
-                }
-            }
-            const roadmapPath = this.deps.resolveMilestoneFile(this.s.basePath, milestoneId, "ROADMAP");
-            if (!roadmapPath) {
-                debugLog("WorktreeLifecycle", {
-                    action: "mergeAndExit",
-                    milestoneId,
-                    mode: "branch",
-                    skipped: true,
-                    reason: "no-roadmap",
-                });
-                return false;
-            }
-            const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
-            const mergeResult = this.deps.mergeMilestoneToMain(this.s.basePath, milestoneId, roadmapContent);
+        else if (result.mode === "branch") {
             // Rebuild GitService after merge (branch HEAD changed)
             rebuildGitService(this.s, this.deps);
-            if (mergeResult.codeFilesChanged) {
-                ctx.notify(`Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
-            }
-            else {
-                ctx.notify(`WARNING: Milestone ${milestoneId} merged (branch mode) but contained NO code changes — only .gsd/ metadata. ` +
-                    `Review the milestone output and re-run if code is missing.`, "warning");
-            }
-            debugLog("WorktreeLifecycle", {
-                action: "mergeAndExit",
-                milestoneId,
-                mode: "branch",
-                result: "success",
-            });
-            return true;
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            debugLog("WorktreeLifecycle", {
-                action: "mergeAndExit",
-                milestoneId,
-                mode: "branch",
-                result: "error",
-                error: msg,
-            });
-            if (!(err instanceof UserNotifiedError)) {
-                ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
-            }
-            // Re-throw all errors so callers can apply their own recovery (#4380).
-            throw err;
         }
+        return result;
     }
+    // ── Removed: _mergeWorktreeMode / _mergeBranchMode bodies ────────────
+    // The merge bodies moved to file-scope `_mergeWorktreeModeImpl` and
+    // `_mergeBranchModeImpl`, callable from the session-less
+    // `mergeMilestoneStandalone` entry. The previous private methods are
+    // gone; `_mergeAndExit` above is the only session-bound caller.
     /**
      * Fall back to branch-mode for `milestoneId` after a failed worktree
      * creation, marking the session's isolation as degraded.
@@ -920,9 +1185,9 @@ export class WorktreeLifecycle {
         }
         const basePath = resolveWorktreeProjectRoot(this.s.basePath, this.s.originalBasePath);
         try {
-            this.deps.enterBranchModeForMilestone(basePath, milestoneId);
+            lifecycleEnterBranchMode(this.deps, basePath, milestoneId);
             rebuildGitService(this.s, this.deps);
-            this.deps.invalidateAllCaches();
+            invalidateAllCaches();
             this.s.isolationDegraded = true;
             ctx.notify(`Switched to branch milestone/${milestoneId} (isolation degraded).`, "info");
         }
@@ -945,7 +1210,148 @@ export class WorktreeLifecycle {
             return;
         this.s.basePath = this.s.originalBasePath;
         rebuildGitService(this.s, this.deps);
-        this.deps.invalidateAllCaches();
+        invalidateAllCaches();
+    }
+    /**
+     * Adopt a session root (ADR-016 phase 2 / B2, issue #5620).
+     *
+     * Sole owner of `s.basePath` mutation for bootstrap-class transitions:
+     * initial session start, paused-resume entry (before persisted-state
+     * consultation), and hook-trigger session activation. Defensive about
+     * `s.originalBasePath`:
+     *
+     * - When `originalBase` is explicit: overwrite.
+     * - Otherwise, set `s.originalBasePath` only if it is currently empty —
+     *   resume paths that already restored `s.originalBasePath` from paused
+     *   metadata keep their value.
+     *
+     * Does NOT chdir; callers that need cwd alignment with the new basePath
+     * are responsible for it. Does NOT rebuild `s.gitService` — callers that
+     * mutate `s.basePath` to a non-project-root path (e.g. a worktree on a
+     * subsequent milestone enter) go through `enterMilestone`, which handles
+     * the rebuild.
+     */
+    adoptSessionRoot(base, originalBase) {
+        this.s.basePath = base;
+        if (originalBase !== undefined) {
+            this.s.originalBasePath = originalBase;
+        }
+        else if (!this.s.originalBasePath) {
+            this.s.originalBasePath = base;
+        }
+    }
+    /**
+     * Resume from a paused session (ADR-016 phase 2 / B3, issue #5621).
+     *
+     * Adopts `persistedWorktreePath` as `s.basePath` when the path is
+     * non-null and exists on disk; otherwise falls back to `base`. Mirrors
+     * the resume guard at `auto.ts:2164` — a stale or removed worktree
+     * directory must not strand the resumed session in an invalid root.
+     *
+     * Folds in the body of the legacy `_resolvePausedResumeBasePathForTest`
+     * helper (see `resolvePausedResumeBasePath` below). After this verb
+     * lands the helper is deleted from `auto.ts` per the slice-7 closure
+     * decision to retire `_*ForTest` suffixes from production paths.
+     *
+     * Like `adoptSessionRoot`, this is a pure session-state mutation — no
+     * chdir, no git service rebuild, no cache invalidation.
+     */
+    resumeFromPausedSession(base, persistedWorktreePath) {
+        this.s.basePath = resolvePausedResumeBasePath(base, persistedWorktreePath);
+    }
+    /**
+     * Adopt an orphan worktree for a bootstrap-time merge (ADR-016 phase 2 / B4,
+     * issue #5622).
+     *
+     * Owns the swap-run-revert protocol that bootstrap previously open-coded:
+     *
+     *   1. Snapshot prior `s.basePath` and `s.originalBasePath`.
+     *   2. Resolve `getAutoWorktreePath(base, milestoneId) ?? base` before
+     *      mutating session state, then set `s.originalBasePath = base` and
+     *      `s.basePath` to the resolved path.
+     *   3. Invoke the caller-supplied `run` callback under the swap.
+     *   4. On `!result.merged`: revert to `base` and `chdir(base)` so the
+     *      caller can return early without leaving the session in a half-
+     *      swapped state.
+     *   5. On `result.merged && !s.active`: revert to the snapshotted prior
+     *      paths (the orphan merge succeeded but bootstrap chose not to keep
+     *      the session active).
+     *   6. On `result.merged && s.active`: leave the swap in place — the
+     *      loop will continue from the worktree path.
+     *
+     * The callback shape forces every caller through the same revert
+     * protocol; an open-coded swap that forgets to revert on failure was the
+     * original bug pattern this verb is designed to prevent.
+     */
+    adoptOrphanWorktree(milestoneId, base, run) {
+        validateMilestoneId(milestoneId);
+        const priorBasePath = this.s.basePath;
+        const priorOriginalBasePath = this.s.originalBasePath;
+        const restorePriorPaths = (phase) => {
+            this.s.basePath = priorBasePath || base;
+            this.s.originalBasePath = priorOriginalBasePath || base;
+            try {
+                process.chdir(this.s.originalBasePath || base);
+            }
+            catch (err) {
+                debugLog("WorktreeLifecycle", {
+                    action: "adoptOrphanWorktree",
+                    phase,
+                    base: this.s.originalBasePath || base,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        };
+        let adoptedBasePath;
+        try {
+            const wtPathFn = primitiveOverrides(this.deps).getAutoWorktreePath ?? getAutoWorktreePath;
+            adoptedBasePath = wtPathFn(base, milestoneId) ?? base;
+        }
+        catch (err) {
+            restorePriorPaths("rollback-resolve-worktree-failed");
+            throw err;
+        }
+        // Swap into the orphan worktree.
+        this.s.originalBasePath = base;
+        this.s.basePath = adoptedBasePath;
+        let result;
+        try {
+            result = run();
+        }
+        catch (err) {
+            restorePriorPaths("rollback-run-failed");
+            throw err;
+        }
+        if (!result.merged) {
+            // Failed orphan merge — revert to project root so the caller can
+            // safely return early without leaving the session in an invalid
+            // basePath. Mirror the chdir that bootstrap performed inline.
+            this.s.basePath = base;
+            this.s.originalBasePath = base;
+            try {
+                process.chdir(base);
+            }
+            catch (err) {
+                debugLog("WorktreeLifecycle", {
+                    action: "adoptOrphanWorktree",
+                    phase: "revert-chdir-failed",
+                    base,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return result;
+        }
+        if (!this.s.active) {
+            // Merge succeeded but the session was not (re)activated — restore
+            // the snapshotted paths so the calling context resumes where it
+            // was, with the orphan branch now merged on main.
+            this.s.basePath = priorBasePath || base;
+            this.s.originalBasePath = priorOriginalBasePath || base;
+        }
+        // else: merged && active — leave the swap; the loop continues from
+        // the worktree path. Subsequent milestone enters mutate `s.basePath`
+        // through their own Lifecycle verbs.
+        return result;
     }
     /** True if `milestoneId` is the session's currently-active milestone. */
     isInMilestone(milestoneId) {