gsd-pi 2.81.0 → 2.82.0

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -17,7 +17,7 @@
  * 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";
 
@@ -35,14 +35,46 @@ import {
   releaseMilestoneLease,
 } from "./db/milestone-leases.js";
 import { MergeConflictError } from "./git-service.js";
+import type { GitPreferences } 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 type { WorktreeStateProjection } from "./worktree-state-projection.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";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -64,19 +96,16 @@ export interface NotifyCtx {
  * recursion retires; shrinking it now would force a parallel migration.
  */
 export interface WorktreeLifecycleDeps {
-  // ── Entry / branch-mode setup ────────────────────────────────────────
-  enterAutoWorktree: (basePath: string, milestoneId: string) => string;
-  createAutoWorktree: (basePath: string, milestoneId: string) => string;
-  enterBranchModeForMilestone: (basePath: string, milestoneId: string) => void;
-  getAutoWorktreePath: (basePath: string, milestoneId: string) => string | null;
-  getIsolationMode: (basePath?: string) => "worktree" | "branch" | "none";
-
-  // ── Cache + git service rebuild ──────────────────────────────────────
-  invalidateAllCaches: () => void;
-  GitServiceImpl: new (basePath: string, gitConfig: unknown) => unknown;
-  loadEffectiveGSDPreferences: () =>
-    | { preferences?: { git?: Record<string, unknown> } }
-    | undefined;
+  // ── Git service factory (ADR-016 phase 2 / C4) ───────────────────────
+  /**
+   * Build a fresh `GitService` instance bound to `basePath`.
+   *
+   * Hides the constructor shape (new GitServiceImpl(basePath, gitConfig))
+   * and the gitConfig load from Lifecycle. The factory takes only a
+   * `basePath` and is responsible for loading any config it needs.
+   * Tests substitute fakes by passing a function that returns a stub.
+   */
+  gitServiceFactory: (basePath: string) => AutoSession["gitService"];
 
   // ── State Projection Module (ADR-016 one-way edge) ───────────────────
   /**
@@ -85,44 +114,60 @@ export interface WorktreeLifecycleDeps {
    */
   worktreeProjection: WorktreeStateProjection;
 
-  // ── Exit / merge / teardown ──────────────────────────────────────────
-  isInAutoWorktree: (basePath: string) => boolean;
-  autoCommitCurrentBranch: (
-    basePath: string,
-    reason: string,
-    milestoneId: string,
-  ) => void;
-  autoWorktreeBranch: (milestoneId: string) => string;
-  teardownAutoWorktree: (
-    basePath: string,
-    milestoneId: string,
-    opts?: { preserveBranch?: boolean },
-  ) => void;
-  mergeMilestoneToMain: (
-    basePath: string,
-    milestoneId: string,
-    roadmapContent: string,
-  ) => { pushed: boolean; codeFilesChanged: boolean };
-  getCurrentBranch: (basePath: string) => string;
+  // ── Merge primitive ──────────────────────────────────────────────────
   /**
-   * Force-checkout the named branch in `basePath`. Required by the branch-mode
-   * merge path when HEAD has been moved off the milestone branch — silently
-   * skipping the merge would strand the milestone's commits.
+   * Inner squash-merge primitive (`auto-worktree.ts:mergeMilestoneToMain`).
+   *
+   * **Module-internal seam — do not construct your own.** Only the wiring
+   * factory `auto.ts:buildWorktreeLifecycleDeps()` is permitted to populate
+   * this field. The primitive is `@internal`; production callers reach the
+   * merge body through `WorktreeLifecycle.exitMilestone({ merge: true })`,
+   * never by calling this dep directly.
    */
-  checkoutBranch: (basePath: string, branch: string) => void;
-  resolveMilestoneFile: (
+  mergeMilestoneToMain: (
     basePath: string,
     milestoneId: string,
-    fileType: string,
-  ) => string | null;
-  /**
-   * Roadmap file reader. Injected so unit tests can substitute fixture
-   * content without touching the filesystem; production wiring passes
-   * `node:fs.readFileSync`.
-   */
-  readFileSync: (path: string, encoding: string) => string;
+    roadmapContent: string,
+  ) => {
+    pushed: boolean;
+    codeFilesChanged: boolean;
+    commitMessage?: string;
+  };
+
+  // ADR-016 phase 2 / C1 + C2 + C3 + C4 inlined the following fields as
+  // direct imports — leaf primitives that did not vary across callers:
+  //   C1 (#5624): readFileSync, getCurrentBranch, checkoutBranch,
+  //               autoCommitCurrentBranch
+  //   C2 (#5625): enterAutoWorktree, createAutoWorktree,
+  //               enterBranchModeForMilestone, getAutoWorktreePath,
+  //               teardownAutoWorktree, isInAutoWorktree, autoWorktreeBranch
+  //   C3 (#5626): invalidateAllCaches, loadEffectiveGSDPreferences,
+  //               getIsolationMode, resolveMilestoneFile
+  //   C4 (#5627): GitServiceImpl constructor → gitServiceFactory above
+  //
+  // ADR-016 phase 3 (#5693) deleted the @deprecated optional fields that
+  // remained on this Interface for legacy test fixtures. Tests that need to
+  // substitute primitive implementations cast their deps to
+  // `WorktreeLifecycleTestOverrides` (exported below) — the test seam now
+  // lives outside the public Interface.
+  //
+  // Final dep bag: 3 fields. The ADR's envisioned shape was ≤6.
 }
 
+/**
+ * Test-only override shim. Production callers do not use this type — it
+ * exists so legacy test fixtures can substitute the primitive implementations
+ * that were inlined into Lifecycle in ADR-016 phase 2 (C1-C4). Pass an object
+ * typed `WorktreeLifecycleDeps & WorktreeLifecycleTestOverrides` to the
+ * `WorktreeLifecycle` constructor; Lifecycle reads the overrides through the
+ * structural-typing escape hatch in `primitiveOverrides()`.
+ *
+ * The fields here intentionally duplicate the C1-C4-inlined primitive
+ * signatures. Adding new fields is fine when a test needs to vary a primitive
+ * that has no other seam.
+ */
+export type WorktreeLifecycleTestOverrides = WorktreeLifecyclePrimitiveOverrides;
+
 /**
  * Internal sentinel — thrown by `_mergeBranchMode` when it has already
  * emitted a user-visible error. The outer `mergeAndExit` catches the type
@@ -166,6 +211,49 @@ export type ExitResult =
   | { ok: true; merged: boolean; codeFilesChanged: boolean }
   | { ok: false; reason: "merge-conflict" | "teardown-failed"; cause?: unknown };
 
+/**
+ * Session-less merge entry context. Per ADR-016 phase 2 / A1 (#5616), the
+ * merge body is structurally session-less — it reads project root, worktree
+ * path, and milestoneId. Single-loop callers (`_mergeAndExit`) build a
+ * MergeContext from `this.s`. Parallel callers (`parallel-merge.ts`) build
+ * one directly without an `AutoSession`.
+ */
+export interface MergeContext {
+  /** Project root — merge target (where `git merge --squash` lands). */
+  originalBasePath: string;
+  /**
+   * Current worktree path or project root when in branch mode. Used as the
+   * cwd anchor for `mergeMilestoneToMain` and the source for
+   * `Projection.finalizeProjectionForMerge`.
+   */
+  worktreeBasePath: string;
+  milestoneId: string;
+  /**
+   * When true, `mergeMilestoneStandalone` returns `{ merged: false,
+   * mode: "skipped" }` immediately (mirrors the single-loop guard). Default
+   * `false` for parallel callers, which never run with degraded isolation.
+   */
+  isolationDegraded?: boolean;
+  notify: NotifyCtx["notify"];
+}
+
+/**
+ * Result of `mergeMilestoneStandalone`. `mode` lets callers decide which
+ * session-bound side effects to run (worktree-mode → `restoreToProjectRoot`,
+ * branch-mode → `rebuildGitService`, skipped → none).
+ */
+export interface MergeStandaloneResult {
+  merged: boolean;
+  mode: "worktree" | "branch" | "skipped";
+  codeFilesChanged: boolean;
+  pushed: boolean;
+  /**
+   * Commit message produced by the squash merge, if available. Forwarded
+   * from `mergeMilestoneToMain`. Only populated when `merged === true`.
+   */
+  commitMessage?: string;
+}
+
 // ─── Validation ──────────────────────────────────────────────────────────
 
 function isValidMilestoneId(milestoneId: string): boolean {
@@ -178,6 +266,206 @@ function invalidMilestoneIdError(milestoneId: string): Error {
   );
 }
 
+type WorktreeLifecyclePrimitiveOverrides = {
+  readFileSync?: (path: string, encoding: BufferEncoding) => string;
+  getCurrentBranch?: (basePath: string) => string;
+  checkoutBranch?: (basePath: string, branch: string) => void;
+  autoCommitCurrentBranch?: (
+    basePath: string,
+    unitType: string,
+    unitId: string,
+    taskContext?: unknown,
+  ) => string | null;
+  getAutoWorktreePath?: (
+    basePath: string,
+    milestoneId: string,
+  ) => string | null;
+  // ADR-016 phase 2 / C2-inlined worktree-manager primitives. Tests still
+  // stub these via the structural-typing escape hatch on `WorktreeLifecycleDeps`,
+  // so the call sites below check for an override first and fall back to the
+  // imported direct primitive.
+  isInAutoWorktree?: (basePath: string) => boolean;
+  autoWorktreeBranch?: (milestoneId: string) => string;
+  teardownAutoWorktree?: (
+    basePath: string,
+    milestoneId: string,
+    opts?: { preserveBranch?: boolean },
+  ) => void;
+  createAutoWorktree?: (basePath: string, milestoneId: string) => string;
+  enterAutoWorktree?: (basePath: string, milestoneId: string) => string;
+  enterBranchModeForMilestone?: (basePath: string, milestoneId: string) => void;
+  // ADR-016 phase 2 / C3-inlined cache + preferences + path helpers.
+  getIsolationMode?: (basePath?: string) => "worktree" | "branch" | "none";
+  invalidateAllCaches?: () => void;
+  resolveMilestoneFile?: (
+    basePath: string,
+    milestoneId: string,
+    fileType: string,
+  ) => string | null;
+  loadEffectiveGSDPreferences?: (basePath?: string) =>
+    | { preferences?: { git?: Record<string, unknown> } }
+    | null
+    | undefined;
+};
+
+function primitiveOverrides(
+  deps: WorktreeLifecycleDeps,
+): WorktreeLifecyclePrimitiveOverrides {
+  return deps as WorktreeLifecycleDeps & WorktreeLifecyclePrimitiveOverrides;
+}
+
+function readLifecycleFile(
+  deps: WorktreeLifecycleDeps,
+  path: string,
+): string {
+  return primitiveOverrides(deps).readFileSync?.(path, "utf-8") ??
+    readFileSync(path, "utf-8");
+}
+
+function currentLifecycleBranch(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+): string {
+  return primitiveOverrides(deps).getCurrentBranch?.(basePath) ??
+    getCurrentBranch(basePath);
+}
+
+function checkoutLifecycleBranch(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  branch: string,
+): void {
+  const checkoutBranch = primitiveOverrides(deps).checkoutBranch;
+  if (checkoutBranch) {
+    checkoutBranch(basePath, branch);
+    return;
+  }
+  nativeCheckoutBranch(basePath, branch);
+}
+
+function autoCommitLifecycleBranch(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  unitType: string,
+  unitId: string,
+): string | null {
+  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: WorktreeLifecycleDeps,
+  basePath: string,
+): boolean {
+  return primitiveOverrides(deps).isInAutoWorktree?.(basePath) ??
+    isInAutoWorktree(basePath);
+}
+
+function lifecycleAutoWorktreeBranch(
+  deps: WorktreeLifecycleDeps,
+  milestoneId: string,
+): string {
+  return primitiveOverrides(deps).autoWorktreeBranch?.(milestoneId) ??
+    autoWorktreeBranch(milestoneId);
+}
+
+function lifecycleTeardownAutoWorktree(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  milestoneId: string,
+  opts?: { preserveBranch?: boolean },
+): void {
+  const override = primitiveOverrides(deps).teardownAutoWorktree;
+  if (override) {
+    override(basePath, milestoneId, opts);
+    return;
+  }
+  teardownAutoWorktree(basePath, milestoneId, opts);
+}
+
+function lifecycleCreateAutoWorktree(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  milestoneId: string,
+): string {
+  return primitiveOverrides(deps).createAutoWorktree?.(basePath, milestoneId) ??
+    createAutoWorktree(basePath, milestoneId);
+}
+
+function lifecycleEnterAutoWorktree(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  milestoneId: string,
+): string {
+  return primitiveOverrides(deps).enterAutoWorktree?.(basePath, milestoneId) ??
+    enterAutoWorktree(basePath, milestoneId);
+}
+
+function lifecycleEnterBranchMode(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  milestoneId: string,
+): void {
+  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: WorktreeLifecycleDeps,
+  basePath?: string,
+): "worktree" | "branch" | "none" {
+  return primitiveOverrides(deps).getIsolationMode?.(basePath) ??
+    getIsolationMode(basePath);
+}
+
+function lifecycleInvalidateAllCaches(deps: WorktreeLifecycleDeps): void {
+  const override = primitiveOverrides(deps).invalidateAllCaches;
+  if (override) {
+    override();
+    return;
+  }
+  invalidateAllCaches();
+}
+
+function lifecycleResolveMilestoneFile(
+  deps: WorktreeLifecycleDeps,
+  basePath: string,
+  milestoneId: string,
+  fileType: string,
+): string | null {
+  return primitiveOverrides(deps).resolveMilestoneFile?.(
+    basePath,
+    milestoneId,
+    fileType,
+  ) ?? resolveMilestoneFile(basePath, milestoneId, fileType);
+}
+
+function lifecycleLoadPreferences(
+  deps: WorktreeLifecycleDeps,
+  basePath?: string,
+):
+  | { preferences?: { git?: Record<string, unknown> } }
+  | null
+  | undefined {
+  const override = primitiveOverrides(deps).loadEffectiveGSDPreferences;
+  if (override) return override(basePath);
+  return loadEffectiveGSDPreferences(basePath) as
+    | { preferences?: { git?: Record<string, unknown> } }
+    | null
+    | undefined;
+}
+
 /**
  * Throwing variant used by the merge/exit paths that surface failures via
  * the typed `ExitResult` (callers wrap the throw → cause). The enter path
@@ -336,7 +624,7 @@ export function _enterMilestoneCore(
   // 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", {
@@ -380,12 +668,12 @@ export function _enterMilestoneCore(
   // ── 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,
@@ -421,18 +709,22 @@ export function _enterMilestoneCore(
 
   // ── Worktree mode ────────────────────────────────────────────────────────
   try {
-    const existingPath = deps.getAutoWorktreePath(basePath, milestoneId);
+    const existingPath =
+      (primitiveOverrides(deps).getAutoWorktreePath ?? getAutoWorktreePath)(
+        basePath,
+        milestoneId,
+      );
     let wtPath: string;
 
     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
@@ -511,122 +803,607 @@ export function _enterMilestoneCore(
   }
 }
 
+/**
+ * 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: string,
+  persistedWorktreePath: string | null | undefined,
+  pathExists: (p: string) => boolean = existsSync,
+): string {
+  return persistedWorktreePath && pathExists(persistedWorktreePath)
+    ? persistedWorktreePath
+    : base;
+}
+
 function rebuildGitService(
   s: AutoSession,
   deps: WorktreeLifecycleDeps,
 ): void {
-  const gitConfig =
-    deps.loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-  s.gitService = new deps.GitServiceImpl(
-    s.basePath,
-    gitConfig,
-  ) as AutoSession["gitService"];
+  // 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);
 }
 
-// ─── Module class ────────────────────────────────────────────────────────
+// ─── Session-less merge entry (ADR-016 phase 2 / A1) ─────────────────────
 
 /**
- * Worktree Lifecycle module instance.
+ * Worktree-mode merge body. Session-less — operates on a `MergeContext`.
  *
- * Constructed once per auto-mode session. Holds the session reference so
- * verbs can mutate `s.basePath` and related coordination state directly
- * without round-tripping through callers.
+ * 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.
  */
-export class WorktreeLifecycle {
-  private readonly s: AutoSession;
-  private readonly deps: WorktreeLifecycleDeps;
-
-  constructor(s: AutoSession, deps: WorktreeLifecycleDeps) {
-    this.s = s;
-    this.deps = deps;
+function _mergeWorktreeModeImpl(
+  deps: WorktreeLifecycleDeps,
+  mctx: MergeContext,
+): MergeStandaloneResult {
+  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,
+    };
   }
 
-  /**
-   * Enter or create the auto-worktree for `milestoneId`. Idempotent if
-   * already in this milestone (lease refreshed; basePath unchanged).
-   *
-   * Returns a typed `EnterResult` describing the outcome. Callers may
-   * ignore the result if they read `s.basePath` directly afterwards
-   * (legacy behaviour); new callers should branch on the result.
-   */
-  enterMilestone(milestoneId: string, ctx: NotifyCtx): EnterResult {
-    return _enterMilestoneCore(this.s, this.deps, milestoneId, ctx);
-  }
+  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,
+      });
+    }
 
-  /**
-   * Exit the current worktree. With `opts.merge === true`, runs the full
-   * merge-and-teardown path (worktree-mode or branch-mode auto-detected).
-   * With `opts.merge === false`, runs auto-commit and teardown without
-   * merging to main.
-   *
-   * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
-   * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
-   * giving callers a typed branch for the expected failure path.
-   * Unexpected failures (filesystem, git permissions, etc.) are wrapped
-   * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
-   * receive a discriminated union — no exceptions for any expected outcome.
-   */
-  exitMilestone(
-    milestoneId: string,
-    opts: { merge: boolean; preserveBranch?: boolean },
-    ctx: NotifyCtx,
-  ): ExitResult {
-    if (opts.merge) {
-      try {
-        const merged = this._mergeAndExit(milestoneId, ctx);
-        return { ok: true, merged, codeFilesChanged: false };
-      } catch (err) {
-        if (err instanceof MergeConflictError) {
-          return { ok: false, reason: "merge-conflict", cause: err };
-        }
-        return { ok: false, reason: "teardown-failed", cause: err };
+    // 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",
+        });
       }
     }
-    try {
-      this._exitWithoutMerge(milestoneId, ctx, {
-        preserveBranch: opts.preserveBranch,
+
+    if (!roadmapPath) {
+      // No roadmap at either location — teardown but PRESERVE the branch
+      // so commits are not orphaned (#1573).
+      lifecycleTeardownAutoWorktree(deps, originalBasePath, milestoneId, {
+        preserveBranch: true,
       });
-      return { ok: true, merged: false, codeFilesChanged: false };
-    } catch (err) {
-      return { ok: false, reason: "teardown-failed", cause: err };
+      notify(
+        `Exited worktree for ${milestoneId} (no roadmap found — branch preserved for manual merge).`,
+        "warning",
+      );
+      return {
+        merged: false,
+        mode: "worktree",
+        codeFilesChanged: false,
+        pushed: false,
+      };
     }
-  }
 
-  /**
-   * Milestone transition: merge the current milestone, then enter the next
-   * one. Pattern used when the loop detects that the active milestone has
-   * changed (current completed, next is now active). Caller is responsible
-   * for re-deriving state between the merge and the enter.
-   */
-  mergeAndEnterNext(
-    currentMilestoneId: string,
-    nextMilestoneId: string,
-    ctx: NotifyCtx,
-  ): void {
-    debugLog("WorktreeLifecycle", {
-      action: "mergeAndEnterNext",
-      currentMilestoneId,
-      nextMilestoneId,
-    });
-    let merged = false;
-    let mergeThrew = 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 {
-      merged = this._mergeAndExit(currentMilestoneId, ctx);
-    } catch (err) {
-      if (err instanceof UserNotifiedError) throw err;
-      mergeThrew = true;
-      // _mergeAndExit emits a warning and restores state on failure during
-      // merge/cleanup. If it throws before recovery runs (e.g. validation,
-      // emitJournalEvent), basePath isn't restored — re-throw so we don't
-      // enter the next milestone with the current one unmerged.
-      const projectRoot = resolveWorktreeProjectRoot(
-        this.s.basePath,
-        this.s.originalBasePath,
-      );
-      if (this.s.basePath !== projectRoot) throw err;
-      // Otherwise: merge attempted, failed cleanly with state restored.
-      // The loop intentionally continues to the next milestone — the
-      // failed milestone's branch is preserved for manual recovery.
+      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: WorktreeLifecycleDeps,
+  mctx: MergeContext,
+): MergeStandaloneResult {
+  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: WorktreeLifecycleDeps,
+  mctx: MergeContext,
+): MergeStandaloneResult {
+  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 ────────────────────────────────────────────────────────
+
+/**
+ * Worktree Lifecycle module instance.
+ *
+ * Constructed once per auto-mode session. Holds the session reference so
+ * verbs can mutate `s.basePath` and related coordination state directly
+ * without round-tripping through callers.
+ */
+export class WorktreeLifecycle {
+  private readonly s: AutoSession;
+  private readonly deps: WorktreeLifecycleDeps;
+
+  constructor(s: AutoSession, deps: WorktreeLifecycleDeps) {
+    this.s = s;
+    this.deps = deps;
+  }
+
+  /**
+   * Enter or create the auto-worktree for `milestoneId`. Idempotent if
+   * already in this milestone (lease refreshed; basePath unchanged).
+   *
+   * Returns a typed `EnterResult` describing the outcome. Callers may
+   * ignore the result if they read `s.basePath` directly afterwards
+   * (legacy behaviour); new callers should branch on the result.
+   */
+  enterMilestone(milestoneId: string, ctx: NotifyCtx): EnterResult {
+    return _enterMilestoneCore(this.s, this.deps, milestoneId, ctx);
+  }
+
+  /**
+   * Exit the current worktree. With `opts.merge === true`, runs the full
+   * merge-and-teardown path (worktree-mode or branch-mode auto-detected).
+   * With `opts.merge === false`, runs auto-commit and teardown without
+   * merging to main.
+   *
+   * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
+   * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
+   * giving callers a typed branch for the expected failure path.
+   * Unexpected failures (filesystem, git permissions, etc.) are wrapped
+   * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
+   * receive a discriminated union — no exceptions for any expected outcome.
+   */
+  exitMilestone(
+    milestoneId: string,
+    opts: { merge: boolean; preserveBranch?: boolean },
+    ctx: NotifyCtx,
+  ): ExitResult {
+    if (opts.merge) {
+      try {
+        const merged = this._mergeAndExit(milestoneId, ctx);
+        return {
+          ok: true,
+          merged: merged.merged,
+          codeFilesChanged: merged.codeFilesChanged,
+        };
+      } catch (err) {
+        if (err instanceof MergeConflictError) {
+          return { ok: false, reason: "merge-conflict", cause: err };
+        }
+        return { ok: false, reason: "teardown-failed", cause: err };
+      }
+    }
+    try {
+      this._exitWithoutMerge(milestoneId, ctx, {
+        preserveBranch: opts.preserveBranch,
+      });
+      return { ok: true, merged: false, codeFilesChanged: false };
+    } catch (err) {
+      return { ok: false, reason: "teardown-failed", cause: err };
+    }
+  }
+
+  /**
+   * Milestone transition: merge the current milestone, then enter the next
+   * one. Pattern used when the loop detects that the active milestone has
+   * changed (current completed, next is now active). Caller is responsible
+   * for re-deriving state between the merge and the enter.
+   */
+  mergeAndEnterNext(
+    currentMilestoneId: string,
+    nextMilestoneId: string,
+    ctx: NotifyCtx,
+  ): void {
+    debugLog("WorktreeLifecycle", {
+      action: "mergeAndEnterNext",
+      currentMilestoneId,
+      nextMilestoneId,
+    });
+    let merged = false;
+    let mergeThrew = false;
+    try {
+      merged = this._mergeAndExit(currentMilestoneId, ctx).merged;
+    } catch (err) {
+      if (err instanceof UserNotifiedError) throw err;
+      mergeThrew = true;
+      // _mergeAndExit emits a warning and restores state on failure during
+      // merge/cleanup. If it throws before recovery runs (e.g. validation,
+      // emitJournalEvent), basePath isn't restored — re-throw so we don't
+      // enter the next milestone with the current one unmerged.
+      const projectRoot = resolveWorktreeProjectRoot(
+        this.s.basePath,
+        this.s.originalBasePath,
+      );
+      if (this.s.basePath !== projectRoot) throw err;
+      // Otherwise: merge attempted, failed cleanly with state restored.
+      // The loop intentionally continues to the next milestone — the
+      // failed milestone's branch is preserved for manual recovery.
     }
     if (!merged && !mergeThrew && !this.s.isolationDegraded) {
       // _mergeAndExit returned without attempting a merge (no roadmap
@@ -654,7 +1431,7 @@ export class WorktreeLifecycle {
     opts: { preserveBranch?: boolean },
   ): void {
     validateMilestoneId(milestoneId);
-    if (!this.deps.isInAutoWorktree(this.s.basePath)) {
+    if (!lifecycleIsInAutoWorktree(this.deps, this.s.basePath)) {
       debugLog("WorktreeLifecycle", {
         action: "exitMilestone",
         milestoneId,
@@ -671,7 +1448,7 @@ export class WorktreeLifecycle {
     });
 
     try {
-      this.deps.autoCommitCurrentBranch(this.s.basePath, "stop", milestoneId);
+      autoCommitLifecycleBranch(this.deps, this.s.basePath, "stop", milestoneId);
     } catch (err) {
       debugLog("WorktreeLifecycle", {
         action: "exitMilestone",
@@ -680,7 +1457,7 @@ export class WorktreeLifecycle {
         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.`,
+        `Auto-commit before exiting ${milestoneId} failed: ${err instanceof Error ? err.message : String(err)}. Branch ${lifecycleAutoWorktreeBranch(this.deps, milestoneId)} is preserved for recovery.`,
         "warning",
       );
     }
@@ -697,7 +1474,7 @@ export class WorktreeLifecycle {
           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.`,
+          `Could not leave milestone worktree before cleanup: ${err instanceof Error ? err.message : String(err)}. Branch ${lifecycleAutoWorktreeBranch(this.deps, milestoneId)} is preserved for recovery.`,
           "warning",
         );
       }
@@ -705,7 +1482,7 @@ export class WorktreeLifecycle {
 
     let teardownFailed = false;
     try {
-      this.deps.teardownAutoWorktree(this.s.originalBasePath, milestoneId, {
+      lifecycleTeardownAutoWorktree(this.deps, this.s.originalBasePath, milestoneId, {
         preserveBranch: opts.preserveBranch ?? false,
       });
     } catch (err) {
@@ -717,7 +1494,7 @@ export class WorktreeLifecycle {
         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.`,
+        `Worktree cleanup failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Branch ${lifecycleAutoWorktreeBranch(this.deps, milestoneId)} is preserved for recovery.`,
         "warning",
       );
     }
@@ -742,103 +1519,60 @@ 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.
    */
-  private _mergeAndExit(milestoneId: string, ctx: NotifyCtx): boolean {
-    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),
-        });
-      }
-    }
-
+  private _mergeAndExit(
+    milestoneId: string,
+    ctx: NotifyCtx,
+  ): MergeStandaloneResult {
     // #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: MergeStandaloneResult;
+    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
@@ -848,19 +1582,20 @@ export class WorktreeLifecycle {
     try {
       const startSha = this.s.milestoneStartShas.get(milestoneId);
       if (startSha) {
-        const prefs = loadEffectiveGSDPreferences(
+        const prefs = lifecycleLoadPreferences(
+          this.deps,
           this.s.originalBasePath || this.s.basePath,
         )?.preferences;
         if (
           getCollapseCadence(prefs) === "slice" &&
           getMilestoneResquash(prefs)
         ) {
-          const result = resquashMilestoneOnMain(
+          const resquashResult = resquashMilestoneOnMain(
             this.s.originalBasePath || this.s.basePath,
             milestoneId,
             startSha,
           );
-          if (result.resquashed) {
+          if (resquashResult.resquashed) {
             ctx.notify(
               `slice-cadence: re-squashed slice commits for ${milestoneId} into a single milestone commit.`,
               "info",
@@ -900,291 +1635,29 @@ export class WorktreeLifecycle {
             : String(telemetryErr),
       });
     }
-    return true;
-  }
-
-  /** Worktree-mode merge body. Returns true when an actual squash-merge ran. */
-  private _mergeWorktreeMode(milestoneId: string, ctx: NotifyCtx): boolean {
-    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",
-      });
-      emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
-        ts: new Date().toISOString(),
-        flowId: randomUUID(),
-        seq: 0,
-        eventType: "worktree-merge-failed",
-        data: { milestoneId, error: msg },
+        result: "done",
+        basePath: this.s.basePath,
       });
-      // 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. */
-  private _mergeBranchMode(milestoneId: string, ctx: NotifyCtx): boolean {
-    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.
@@ -1210,9 +1683,9 @@ export class WorktreeLifecycle {
       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).`,
@@ -1240,7 +1713,161 @@ export class WorktreeLifecycle {
     if (!this.s.originalBasePath) 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: string, originalBase?: string): void {
+    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: string,
+    persistedWorktreePath: string | null,
+  ): void {
+    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<T extends { merged: boolean }>(
+    milestoneId: string,
+    base: string,
+    run: () => T,
+  ): T {
+    validateMilestoneId(milestoneId);
+
+    const priorBasePath = this.s.basePath;
+    const priorOriginalBasePath = this.s.originalBasePath;
+    const restorePriorPaths = (phase: string): void => {
+      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: string;
+    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: T;
+    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. */