gsd-pi 2.80.0-dev.fbe7c8c6f → 2.81.0-dev.3cddbbba2

package/src/resources/extensions/gsd/auto.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Auto-mode orchestration, session lifecycle, and stop handling.
 /**
  * GSD Auto Mode — Fresh Session Per Unit
  *
@@ -14,6 +16,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
   ExtensionCommandContext,
+  SessionMessageEntry,
 } from "@gsd/pi-coding-agent";
 
 import { deriveState } from "./state.js";
@@ -30,7 +33,7 @@ import {
   setRuntimeKv,
   deleteRuntimeKv,
 } from "./db/runtime-kv.js";
-import { getManifestStatus } from "./files.js";
+import { extractSection, getManifestStatus, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import {
@@ -59,6 +62,7 @@ import {
   isLockProcessAlive,
   formatCrashInfo,
   emitCrashRecoveredUnitEnd,
+  emitOpenUnitEndForUnit,
 } from "./crash-recovery.js";
 import {
   acquireSessionLock,
@@ -150,6 +154,7 @@ import {
   resolveProjectRoot,
 } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
+import { nativeCheckoutBranch } from "./native-git-bridge.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import {
   createAutoWorktree,
@@ -162,8 +167,6 @@ import {
   mergeMilestoneToMain,
   autoWorktreeBranch,
   syncWorktreeStateBack,
-  syncProjectRootToWorktree,
-  syncStateToProjectRoot,
   readResourceVersion,
   checkResourcesStale,
   escapeStaleWorktree,
@@ -186,6 +189,8 @@ import { isClosedStatus } from "./status-guards.js";
 import {
   type AutoDashboardData,
   updateProgressWidget as _updateProgressWidget,
+  setCompletionProgressWidget,
+  setAutoOutcomeWidget,
   updateSliceProgressCache,
   clearSliceProgressCache,
   describeNextUnit as _describeNextUnit,
@@ -199,7 +204,9 @@ import {
   deregisterSigtermHandler as _deregisterSigtermHandler,
   detectWorkingTreeActivity,
 } from "./auto-supervisor.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, getMilestoneSlices } from "./gsd-db.js";
+import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
+import { writeUnitRuntimeRecord } from "./unit-runtime.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS, type CmuxLogLevel } from "../shared/cmux-events.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
@@ -227,21 +234,41 @@ import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from
 import { initHealthWidget } from "./health-widget.js";
 import { runLegacyAutoLoop, runUokKernelLoop } from "./auto/loop.js";
 import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto/resolve.js";
-import type { LoopDeps } from "./auto/loop-deps.js";
+import type { LoopDeps, StopAutoOptions } from "./auto/loop-deps.js";
 import type { ErrorContext } from "./auto/types.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
 import { createAutoOrchestrator } from "./auto/orchestrator.js";
 import type { AutoOrchestrationModule, AutoOrchestratorDeps } from "./auto/contracts.js";
+import { reconcileBeforeDispatch } from "./state-reconciliation.js";
+import { compileUnitToolContract } from "./tool-contract.js";
+import { createWorktreeSafetyModule } from "./worktree-safety.js";
+import { resolveManifest } from "./unit-context-manifest.js";
+import { classifyFailure } from "./recovery-classification.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
 import {
-  WorktreeResolver,
-  type WorktreeResolverDeps,
-} from "./worktree-resolver.js";
+  WorktreeLifecycle,
+  type WorktreeLifecycleDeps,
+} from "./worktree-lifecycle.js";
+import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { reorderForCaching } from "./prompt-ordering.js";
+import { initTokenCounter } from "./token-counter.js";
+
+// Warm the tiktoken encoder at extension startup so context-budget computations
+// can use accurate token counts via countTokensSync without paying the load
+// cost mid-prompt-build. Fire-and-forget — failure falls back to the
+// provider-aware char-ratio estimator already used by getCharsPerToken().
+// Catch rejections explicitly: an unhandled rejection at module-import time
+// can destabilize startup before the engine logger is configured.
+void initTokenCounter().catch((err) => {
+  logWarning(
+    "engine",
+    `token counter warm-up failed: ${err instanceof Error ? err.message : String(err)}`,
+  );
+});
 
 // ─── Session State ─────────────────────────────────────────────────────────
 
@@ -293,11 +320,15 @@ const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
  * the DB is unavailable (e.g. fresh project before init) we skip registration
  * silently rather than blocking session start.
  */
-function registerAutoWorkerForSession(session: AutoSession): void {
+function registerAutoWorkerForSession(
+  session: AutoSession,
+  projectRootOverride?: string,
+): void {
   if (session.workerId) return; // already registered (e.g. resume re-runs)
   try {
     const projectRootRealpath = normalizeRealPath(
-      session.scope?.workspace.projectRoot
+      projectRootOverride
+        ?? session.scope?.workspace.projectRoot
         ?? (session.originalBasePath || session.basePath),
     );
     session.workerId = registerAutoWorker({ projectRootRealpath });
@@ -332,6 +363,14 @@ function restoreProjectRootEnv(): void {
   s.projectRootEnvCaptured = false;
 }
 
+export function _captureProjectRootEnvForTest(projectRoot: string): void {
+  captureProjectRootEnv(projectRoot);
+}
+
+export function _restoreProjectRootEnvForTest(): void {
+  restoreProjectRootEnv();
+}
+
 function captureMilestoneLockEnv(milestoneId: string | null): void {
   if (!s.milestoneLockEnvCaptured) {
     s.hadMilestoneLockEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_MILESTONE_LOCK");
@@ -420,6 +459,11 @@ export function _synthesizePausedSessionRecoveryForTest(
   return synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile);
 }
 
+// `_resolvePausedResumeBasePathForTest` was retired in ADR-016 phase 2 / B3
+// (#5621). Production callers go through
+// `WorktreeLifecycle.resumeFromPausedSession`; the pure helper for tests is
+// `resolvePausedResumeBasePath` exported from `worktree-lifecycle.ts`.
+
 const DETACHED_AUTO_KEEPALIVE_INTERVAL_MS = 30_000;
 
 function withDetachedAutoKeepalive<T>(run: Promise<T>): Promise<T> {
@@ -501,9 +545,54 @@ export {
   getBudgetEnforcementAction,
 } from "./auto-budget.js";
 
+function closeOutSignalInterruptedUnit(currentBasePath: string): void {
+  const currentUnit = s.currentUnit;
+  if (!currentUnit) return;
+
+  const reason = "Auto-mode process received a termination signal";
+  const errorContext: ErrorContext = {
+    message: reason,
+    category: "aborted",
+    isTransient: false,
+  };
+  const basePath = s.basePath || currentBasePath;
+
+  try {
+    emitOpenUnitEndForUnit(basePath, currentUnit.type, currentUnit.id, "cancelled", errorContext);
+  } catch (err) {
+    logWarning("engine", `signal unit-end cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    writeUnitRuntimeRecord(basePath, currentUnit.type, currentUnit.id, currentUnit.startedAt, {
+      phase: "crashed",
+      lastProgressAt: Date.now(),
+      lastProgressKind: "signal",
+    });
+  } catch (err) {
+    logWarning("engine", `signal runtime cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    if (s.workerId) markLatestActiveForWorkerCanceled(s.workerId, "signal-exit");
+  } catch (err) {
+    logWarning("engine", `signal dispatch cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    resolveAgentEndCancelled(errorContext);
+  } catch (err) {
+    logWarning("engine", `signal resolve cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+}
+
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
-  s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
+  s.sigtermHandler = _registerSigtermHandler(
+    currentBasePath,
+    s.sigtermHandler,
+    () => closeOutSignalInterruptedUnit(currentBasePath),
+  );
 }
 
 /** Wrapper: deregister SIGTERM handler and clear reference. */
@@ -577,6 +666,10 @@ export function isAutoActive(): boolean {
   return s.active;
 }
 
+export function isAutoCompletionStopInProgress(): boolean {
+  return s.completionStopInProgress;
+}
+
 /** Test-only seam for validating auto-mode guards (#4704). Do not use in production code. */
 export function _setAutoActiveForTest(active: boolean): void {
   s.active = active;
@@ -606,6 +699,30 @@ export function isAutoPaused(): boolean {
   return s.paused;
 }
 
+export interface ResumeResourceRefreshDeps {
+  env?: NodeJS.ProcessEnv;
+  importModule?: (specifier: string) => Promise<any>;
+  openProjectDb?: (basePath: string) => Promise<void>;
+}
+
+export async function refreshResumeResourcesAndDb(
+  basePath: string,
+  deps: ResumeResourceRefreshDeps = {},
+): Promise<void> {
+  const env = deps.env ?? process.env;
+  const importModule = deps.importModule ?? ((specifier: string) => import(specifier));
+  const agentDir = env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
+  const pkgRoot = env.GSD_PKG_ROOT;
+  const resourceLoaderPath = pkgRoot
+    ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
+    : new URL("../../../resource-loader.js", import.meta.url).href;
+  const { initResources } = await importModule(resourceLoaderPath);
+  initResources(agentDir);
+  const { primeCache } = await importModule("./prompt-loader.js");
+  primeCache();
+  await (deps.openProjectDb ?? openProjectDbIfPresent)(basePath);
+}
+
 export function setActiveEngineId(id: string | null): void {
   s.activeEngineId = id;
 }
@@ -813,6 +930,31 @@ function buildSnapshotOpts(
   };
 }
 
+function currentUnitLabel(): string | null {
+  if (!s.currentUnit) return null;
+  return `${unitVerb(s.currentUnit.type)} ${s.currentUnit.id}`;
+}
+
+function setLifecycleOutcome(
+  ctx: ExtensionContext | undefined,
+  input: {
+    status: "paused" | "stopped" | "blocked" | "failed" | "complete" | "waiting" | "step";
+    title: string;
+    detail?: string | null;
+    nextAction: string;
+    commands?: string[];
+    unitLabel?: string | null;
+  },
+): void {
+  if (!ctx?.hasUI) return;
+  const { unitLabel: unitLabelOverride, ...rest } = input;
+  setAutoOutcomeWidget(ctx, {
+    ...rest,
+    unitLabel: unitLabelOverride !== undefined ? unitLabelOverride : currentUnitLabel(),
+    startedAt: s.autoStartTime,
+  });
+}
+
 function handleLostSessionLock(
   ctx?: ExtensionContext,
   lockStatus?: SessionLockStatus,
@@ -860,7 +1002,23 @@ function handleLostSessionLock(
  * the stale unit state, progress widget, status badge, and restores CWD so
  * the dashboard does not show an orphaned timer and the shell is usable.
  */
-function cleanupAfterLoopExit(ctx: ExtensionContext): void {
+export async function rerootCommandSession(
+  cmdCtx: Pick<ExtensionCommandContext, "newSession"> | null | undefined,
+  workspaceRoot: string,
+): Promise<{ status: "skipped" | "ok" | "cancelled" | "failed"; error?: string }> {
+  if (!cmdCtx || !workspaceRoot) return { status: "skipped" };
+  try {
+    const result = await cmdCtx.newSession({ workspaceRoot });
+    return result.cancelled ? { status: "cancelled" } : { status: "ok" };
+  } catch (err) {
+    return {
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void> {
   s.currentUnit = null;
   s.active = false;
   deactivateGSD();
@@ -884,35 +1042,132 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   // visible so the user still has a resumable auto-mode signal on screen.
   if (!s.paused) {
     ctx.ui.setStatus("gsd-auto", undefined);
-    ctx.ui.setWidget("gsd-progress", undefined);
+    if (s.completionStopInProgress) {
+      s.completionStopInProgress = false;
+    }
     initHealthWidget(ctx);
   }
 
-  // Restore CWD out of worktree back to original project root
+  // ADR-016 phase 3 (#5693): the stop-path basePath restore routes through
+  // `Lifecycle.restoreToProjectRoot()`, the sole owner of `s.basePath`
+  // mutation. The verb assigns `s.basePath` before any throwable work
+  // (rebuildGitService, cache invalidation), so a thrown error still leaves
+  // basePath restored — no fallback assignment needed at the call site.
+  // The chdir stays here because `restoreToProjectRoot` is a pure
+  // session-state mutation.
   if (s.originalBasePath) {
-    s.basePath = s.originalBasePath;
     try {
-      process.chdir(s.basePath);
+      buildLifecycle().restoreToProjectRoot();
     } catch (err) {
-      /* best-effort */
-      logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+      logWarning(
+        "engine",
+        `restore project root failed: ${err instanceof Error ? err.message : String(err)}`,
+        { file: "auto.ts" },
+      );
+    }
+    try {
+      process.chdir(s.originalBasePath);
+    } catch (err) {
+      logWarning("engine", `basePath restore/chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
   }
+
+  if (s.originalBasePath && s.cmdCtx) {
+    const result = await rerootCommandSession(s.cmdCtx, s.originalBasePath);
+    if (result.status === "cancelled") {
+      logWarning("engine", "post-loop session re-root was cancelled", { file: "auto.ts", basePath: s.originalBasePath });
+    } else if (result.status === "failed") {
+      logWarning("engine", `post-loop session re-root failed: ${result.error ?? "unknown"}`, { file: "auto.ts", basePath: s.originalBasePath });
+    }
+  }
+}
+
+export function _cleanupAfterLoopExitForTest(ctx: ExtensionContext): Promise<void> {
+  return cleanupAfterLoopExit(ctx);
+}
+
+export type AutoWorktreeExitAction = "skip" | "merge" | "preserve";
+
+interface MilestoneCompletionRollup {
+  milestoneTitle?: string;
+  oneLiner?: string;
+  successCriteriaResults?: string;
+  definitionOfDoneResults?: string;
+  requirementOutcomes?: string;
+  deviations?: string;
+  followUps?: string;
+  keyDecisions?: string[];
+  keyFiles?: string[];
+  lessonsLearned?: string[];
+}
+
+function normalizeFrontmatterList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map(item => typeof item === "string" ? item.trim() : "")
+    .filter(item => item.length > 0 && item !== "(none)");
+}
+
+function firstBoldParagraph(body: string): string | undefined {
+  const match = body.match(/\*\*([^*\n][\s\S]*?)\*\*/);
+  return match?.[1]?.replace(/\s+/g, " ").trim() || undefined;
+}
+
+function loadMilestoneCompletionRollup(basePath: string, milestoneId: string | null | undefined): MilestoneCompletionRollup {
+  if (!milestoneId) return {};
+  const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+  if (!summaryPath || !existsSync(summaryPath)) return {};
+
+  try {
+    const raw = readFileSync(summaryPath, "utf-8");
+    const [frontmatterLines, body] = splitFrontmatter(raw);
+    const frontmatter = frontmatterLines ? parseFrontmatterMap(frontmatterLines) : {};
+    return {
+      milestoneTitle: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+      oneLiner: firstBoldParagraph(body),
+      successCriteriaResults: extractSection(body, "Success Criteria Results") ?? undefined,
+      definitionOfDoneResults: extractSection(body, "Definition of Done Results") ?? undefined,
+      requirementOutcomes: extractSection(body, "Requirement Outcomes") ?? undefined,
+      deviations: extractSection(body, "Deviations") ?? undefined,
+      followUps: extractSection(body, "Follow-ups") ?? undefined,
+      keyDecisions: normalizeFrontmatterList(frontmatter.key_decisions),
+      keyFiles: normalizeFrontmatterList(frontmatter.key_files),
+      lessonsLearned: normalizeFrontmatterList(frontmatter.lessons_learned),
+    };
+  } catch (err) {
+    logWarning("dashboard", `completion roll-up summary read failed: ${err instanceof Error ? err.message : String(err)}`);
+    return {};
+  }
+}
+
+export function _resolveAutoWorktreeExitActionForTest(
+  currentMilestoneId: string | null | undefined,
+  milestoneMergedInPhases: boolean,
+  milestoneComplete: boolean,
+): AutoWorktreeExitAction {
+  const action = _selectStopAutoWorktreeExit({
+    currentMilestoneId: currentMilestoneId ?? null,
+    milestoneComplete,
+    milestoneMergedInPhases,
+  });
+  return action === "none" ? "skip" : action;
 }
 
 export async function stopAuto(
   ctx?: ExtensionContext,
   pi?: ExtensionAPI,
   reason?: string,
+  options: StopAutoOptions = {},
 ): Promise<void> {
   if (!s.active && !s.paused) return;
   const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
   const reasonSuffix = reason ? ` — ${reason}` : "";
+  const preserveCompletionSurface = Boolean(options.completionWidget);
+  s.completionStopInProgress = preserveCompletionSurface;
 
-  // #4764 — telemetry: record the exit reason and whether the current milestone
-  // was merged before we entered stopAuto. This is the producer-side signal for
-  // the #4761 orphan class: milestoneMerged=false + currentMilestoneId present
-  // is exactly the pattern that strands work.
+  // #4764 — telemetry: record the exit reason, isolation mode, whether an auto
+  // worktree was active, and whether the current milestone was merged before
+  // stopAuto. The unmerged-work warning is only meaningful for real worktrees.
   try {
     const { emitAutoExit } = await import("./worktree-telemetry.js");
     type AutoExitReason =
@@ -937,10 +1192,13 @@ export async function stopAuto(
                 : rawReason === "stop" || rawReason === "pause"
                   ? rawReason
                   : "other";
-    emitAutoExit(s.originalBasePath || s.basePath, {
+    const telemetryBase = s.originalBasePath || s.basePath;
+    emitAutoExit(telemetryBase, {
       reason: normalizedReason,
       milestoneId: s.currentMilestoneId ?? undefined,
       milestoneMerged: s.milestoneMergedInPhases === true,
+      isolationMode: getIsolationMode(telemetryBase),
+      worktreeActive: isInAutoWorktree(s.basePath),
     });
   } catch (err) {
     logWarning("engine", `auto-exit telemetry failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -968,6 +1226,8 @@ export async function stopAuto(
       if (s.workerId) {
         markWorkerStopping(s.workerId);
       }
+      s.workerId = null;
+      s.milestoneLeaseToken = null;
     } catch (e) {
       debugLog("stop-cleanup-coordination", { error: e instanceof Error ? e.message : String(e) });
     }
@@ -1011,7 +1271,7 @@ export async function stopAuto(
         const notifyCtx = ctx
           ? { notify: ctx.ui.notify.bind(ctx.ui) }
           : { notify: () => {} };
-        const resolver = buildResolver();
+        const lifecycle = buildLifecycle();
 
         // Check if the milestone is complete. DB status is the authoritative
         // signal — only a successful gsd_complete_milestone call flips it to
@@ -1049,17 +1309,35 @@ export async function stopAuto(
           logWarning("engine", `milestone summary check failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
 
-        if (milestoneComplete) {
+        const exitAction = _selectStopAutoWorktreeExit({
+          currentMilestoneId: s.currentMilestoneId,
+          milestoneComplete,
+          milestoneMergedInPhases: s.milestoneMergedInPhases,
+        });
+
+        if (exitAction === "merge") {
           // Milestone is complete — merge worktree branch back to main
-          resolver.mergeAndExit(s.currentMilestoneId, notifyCtx);
-        } else {
+          const r = lifecycle.exitMilestone(
+            s.currentMilestoneId,
+            { merge: true },
+            notifyCtx,
+          );
+          if (!r.ok && r.cause instanceof Error) throw r.cause;
+        } else if (exitAction === "preserve") {
           // Milestone still in progress — preserve branch for later resumption
-          resolver.exitMilestone(s.currentMilestoneId, notifyCtx, {
-            preserveBranch: true,
-          });
+          const r = lifecycle.exitMilestone(
+            s.currentMilestoneId,
+            { merge: false, preserveBranch: true },
+            notifyCtx,
+          );
+          if (!r.ok && r.cause instanceof Error) throw r.cause;
         }
       }
     } catch (e) {
+      ctx?.ui.notify(
+        `Worktree cleanup failed for ${s.currentMilestoneId ?? "current milestone"}: ${e instanceof Error ? e.message : String(e)}. Resolve the preserved branch/worktree and run /gsd auto to resume.`,
+        "warning",
+      );
       debugLog("stop-cleanup-worktree", { error: e instanceof Error ? e.message : String(e) });
     }
 
@@ -1078,6 +1356,21 @@ export async function stopAuto(
       }
     }
 
+    // Pre-compute completion widget slice counts while the DB is still open.
+    // Step 8 runs after closeDatabase(), so DB-backed slice lookups must happen here.
+    const completionMilestoneId = options.completionWidget?.milestoneId ?? s.currentMilestoneId;
+    let completedSlices: number | null = null;
+    let totalSlices: number | null = null;
+    if (preserveCompletionSurface && options.completionWidget && completionMilestoneId && isDbAvailable()) {
+      try {
+        const slices = getMilestoneSlices(completionMilestoneId);
+        completedSlices = slices.filter(slice => isClosedStatus(slice.status)).length;
+        totalSlices = slices.length;
+      } catch (err) {
+        logWarning("dashboard", `completion slice stats lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
     // ── Step 6: DB cleanup ──
     if (isDbAvailable()) {
       try {
@@ -1090,37 +1383,113 @@ export async function stopAuto(
       }
     }
 
-    // ── Step 7: Restore basePath and chdir ──
-    try {
-      if (s.originalBasePath) {
-        s.basePath = s.originalBasePath;
-        try {
-          process.chdir(s.basePath);
-        } catch (err) {
-          /* best-effort */
-          logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-        }
+    // ── Step 7: Restore basePath and chdir (ADR-016 phase 3, #5693) ──
+    // `restoreToProjectRoot` assigns s.basePath before any throwable work;
+    // no fallback assignment is needed at the call site.
+    if (s.originalBasePath) {
+      try {
+        buildLifecycle().restoreToProjectRoot();
+      } catch (e) {
+        debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
+      }
+      try {
+        process.chdir(s.basePath);
+      } catch (err) {
+        /* best-effort */
+        logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+      }
+    }
+
+    // Re-root the active command session/tool runtime after worktree teardown.
+    // mergeAndExit restores process.cwd(), but AgentSession has already captured
+    // its own cwd for tools and system prompt; refresh it before returning to the
+    // user so follow-up commands do not target a removed milestone worktree.
+    if (s.originalBasePath && ctx && s.cmdCtx) {
+      const result = await rerootCommandSession(s.cmdCtx, s.originalBasePath);
+      if (result.status === "cancelled") {
+        logWarning("engine", "post-stop session re-root was cancelled", { file: "auto.ts", basePath: s.originalBasePath });
+      } else if (result.status === "failed") {
+        logWarning("engine", `post-stop session re-root failed: ${result.error ?? "unknown"}`, { file: "auto.ts", basePath: s.originalBasePath });
       }
-    } catch (e) {
-      debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
     }
 
     // ── Step 8: Ledger notification ──
     try {
       const ledger = getLedger();
+      const isAllComplete = reason === "All milestones complete";
+      const isMilestoneComplete = /^Milestone\s+\S+\s+complete$/i.test(reason ?? "");
+      const notificationPrefix = isAllComplete
+        ? "All milestones complete"
+        : isMilestoneComplete
+          ? `${reason}. Auto-mode finished this milestone`
+          : `Auto-mode stopped${reasonSuffix}`;
       if (ledger && ledger.units.length > 0) {
         const totals = getProjectTotals(ledger.units);
         ctx?.ui.notify(
-          `Auto-mode stopped${reasonSuffix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`,
+          `${notificationPrefix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`,
           "info",
         );
       } else {
-        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}.`, "info");
+        ctx?.ui.notify(`${notificationPrefix}.`, "info");
       }
     } catch (e) {
       debugLog("stop-cleanup-ledger", { error: e instanceof Error ? e.message : String(e) });
     }
 
+    if (preserveCompletionSurface && ctx && options.completionWidget) {
+      const ledger = getLedger();
+      const units = ledger?.units ?? [];
+      const totals = units.length > 0 ? getProjectTotals(units) : null;
+      let totalInput = 0;
+      let totalCacheRead = 0;
+      try {
+        for (const entry of s.cmdCtx?.sessionManager?.getEntries?.() ?? []) {
+          if (entry.type === "message") {
+            const msgEntry = entry as SessionMessageEntry;
+            if (msgEntry.message?.role === "assistant") {
+              const usage = (msgEntry.message as any).usage;
+              if (usage) {
+                totalInput += usage.input || 0;
+                totalCacheRead += usage.cacheRead || 0;
+              }
+            }
+          }
+        }
+      } catch (err) {
+        logWarning("dashboard", `completion stats lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      const contextUsage = s.cmdCtx?.getContextUsage?.();
+      const milestoneId = completionMilestoneId;
+      const rollup = loadMilestoneCompletionRollup(s.originalBasePath || s.basePath, milestoneId);
+      setCompletionProgressWidget(ctx, {
+        milestoneId,
+        milestoneTitle: options.completionWidget.milestoneTitle ?? rollup.milestoneTitle,
+        oneLiner: rollup.oneLiner,
+        successCriteriaResults: rollup.successCriteriaResults,
+        definitionOfDoneResults: rollup.definitionOfDoneResults,
+        requirementOutcomes: rollup.requirementOutcomes,
+        deviations: rollup.deviations,
+        followUps: rollup.followUps,
+        keyDecisions: rollup.keyDecisions,
+        keyFiles: rollup.keyFiles,
+        lessonsLearned: rollup.lessonsLearned,
+        reason: reason ?? "Milestone complete",
+        startedAt: s.autoStartTime,
+        totalCost: totals?.cost ?? 0,
+        totalTokens: totals?.tokens.total ?? 0,
+        unitCount: units.length,
+        cacheHitRate: totalCacheRead + totalInput > 0
+          ? (totalCacheRead / (totalCacheRead + totalInput)) * 100
+          : null,
+        contextPercent: contextUsage?.percent ?? null,
+        contextWindow: contextUsage?.contextWindow ?? s.cmdCtx?.model?.contextWindow ?? null,
+        completedSlices,
+        totalSlices,
+        allMilestonesComplete: options.completionWidget.allMilestonesComplete,
+        basePath: s.originalBasePath || s.basePath || null,
+      });
+    }
+
     // ── Step 9: Cmux sidebar / event log ──
     try {
       pi?.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "clear" as const, preferences: loadedPreferences });
@@ -1211,8 +1580,20 @@ export async function stopAuto(
 
     // UI cleanup
     ctx?.ui.setStatus("gsd-auto", undefined);
-    ctx?.ui.setWidget("gsd-progress", undefined);
-    if (ctx) initHealthWidget(ctx);
+    if (!preserveCompletionSurface) {
+      ctx?.ui.setWidget("gsd-progress", undefined);
+      const status = reason?.startsWith("Blocked:") ? "blocked" : reason?.toLowerCase().includes("fail") ? "failed" : "stopped";
+      setLifecycleOutcome(ctx, {
+        status,
+        title: status === "blocked" ? "Auto-mode blocked" : status === "failed" ? "Auto-mode stopped with an issue" : "Auto-mode stopped",
+        detail: reason ?? "Auto-mode stopped.",
+        nextAction: status === "blocked"
+          ? "Fix the blocker, then run /gsd auto to resume."
+          : "Run /gsd status for the current project state, or /gsd auto to continue.",
+        commands: ["/gsd status for overview", "/gsd auto to run", "/gsd visualize to inspect", "/gsd notifications for history"],
+      });
+      if (ctx) initHealthWidget(ctx);
+    }
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
 
@@ -1229,10 +1610,21 @@ export async function stopAuto(
     }
 
     // Reset all session state in one call
-    s.reset();
+    s.resetAfterStop({ preserveCompletionSurface });
   }
 }
 
+export type StopAutoWorktreeExitAction = "none" | "merge" | "preserve";
+
+export function _selectStopAutoWorktreeExit(args: {
+  currentMilestoneId: string | null;
+  milestoneComplete: boolean;
+  milestoneMergedInPhases: boolean;
+}): StopAutoWorktreeExitAction {
+  if (!args.currentMilestoneId || args.milestoneMergedInPhases) return "none";
+  return args.milestoneComplete ? "merge" : "preserve";
+}
+
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
@@ -1292,6 +1684,8 @@ export async function pauseAuto(
     logWarning("engine", `paused-session DB write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
   }
 
+  const pausedUnitLabel = currentUnitLabel();
+
   // Close out the current unit so its runtime record doesn't stay at "dispatched"
   if (s.currentUnit && ctx) {
     try {
@@ -1342,8 +1736,16 @@ export async function pauseAuto(
   s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
   ctx?.ui.setWidget("gsd-progress", undefined);
-  if (ctx) initHealthWidget(ctx);
   const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
+  setLifecycleOutcome(ctx, {
+    status: "paused",
+    title: `${s.stepMode ? "Step" : "Auto"}-mode paused`,
+    detail: _errorContext?.message ?? "Paused by user request.",
+    nextAction: `Type to steer, or run ${resumeCmd} to resume.`,
+    commands: [resumeCmd, "/gsd status for overview", "/gsd notifications for history"],
+    unitLabel: pausedUnitLabel,
+  });
+  if (ctx) initHealthWidget(ctx);
   ctx?.ui.notify(
     `${s.stepMode ? "Step" : "Auto"}-mode paused (Escape). Type to interact, or ${resumeCmd} to resume.`,
     "info",
@@ -1351,43 +1753,43 @@ export async function pauseAuto(
 }
 
 /**
- * Build a WorktreeResolverDeps from auto.ts private scope.
- * Shared by buildResolver() and buildLoopDeps().
+ * Build a WorktreeLifecycle Module wrapping the current session.
+ *
+ * Per ADR-016, the Lifecycle Module is the typed-Interface owner of milestone
+ * entry/exit/merge verbs and calls Projection on lifecycle transitions. The
+ * deps bag is intentionally focused — Lifecycle does not see the wider auto-
+ * mode dependency graph.
+ */
+/**
+ * Construct a `WorktreeLifecycleDeps` bag without binding to any session.
+ *
+ * Exported so session-less callers (currently `parallel-merge.ts`) can build
+ * the same deps and call `mergeMilestoneStandalone` through the Worktree
+ * Lifecycle Module instead of bypassing it (ADR-016 phase 2 / A2).
  */
-function buildResolverDeps(): WorktreeResolverDeps {
+export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
+  // ADR-016 phase 2 / C-track close-out:
+  //   C1 (#5624) — fs + git-CLI primitives inlined
+  //   C2 (#5625) — worktree-manager helpers inlined
+  //   C3 (#5626) — cache + preferences + paths inlined
+  //   C4 (#5627) — GitServiceImpl constructor → gitServiceFactory
+  //
+  // Final WorktreeLifecycleDeps shape: 3 fields (gitServiceFactory,
+  // worktreeProjection, mergeMilestoneToMain). Down from 18 at slice-7
+  // closure.
   return {
-    isInAutoWorktree,
-    shouldUseWorktreeIsolation,
-    getIsolationMode,
+    gitServiceFactory: (basePath: string) => {
+      const gitConfig =
+        loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+      return new GitServiceImpl(basePath, gitConfig);
+    },
+    worktreeProjection: new WorktreeStateProjection(),
     mergeMilestoneToMain,
-    syncWorktreeStateBack,
-    teardownAutoWorktree,
-    createAutoWorktree,
-    enterAutoWorktree,
-    enterBranchModeForMilestone,
-    getAutoWorktreePath,
-    autoCommitCurrentBranch,
-    getCurrentBranch,
-    autoWorktreeBranch,
-    resolveMilestoneFile,
-    readFileSync: (path: string, encoding: string) =>
-      readFileSync(path, encoding as BufferEncoding),
-    GitServiceImpl:
-      GitServiceImpl as unknown as WorktreeResolverDeps["GitServiceImpl"],
-    loadEffectiveGSDPreferences:
-      loadEffectiveGSDPreferences as unknown as WorktreeResolverDeps["loadEffectiveGSDPreferences"],
-    invalidateAllCaches,
-    captureIntegrationBranch,
   };
 }
 
-/**
- * Build a WorktreeResolver wrapping the current session.
- * Cheap to construct — it's just a thin wrapper over `s` + deps.
- * Used by stopAuto(), resume path, and buildLoopDeps().
- */
-function buildResolver(): WorktreeResolver {
-  return new WorktreeResolver(s, buildResolverDeps());
+function buildLifecycle(): WorktreeLifecycle {
+  return new WorktreeLifecycle(s, buildWorktreeLifecycleDeps());
 }
 
 /**
@@ -1407,9 +1809,26 @@ export function createWiredAutoOrchestrationModule(
   let seq = 0;
 
   const deps: AutoOrchestratorDeps = {
+    stateReconciliation: {
+      async reconcileBeforeDispatch() {
+        const result = await reconcileBeforeDispatch(dispatchBasePath);
+        if (!result.ok) {
+          return {
+            ok: false,
+            reason: result.reason,
+            stateSnapshot: result.stateSnapshot,
+          };
+        }
+        return {
+          ok: true,
+          reason: result.repaired.join(", "),
+          stateSnapshot: result.stateSnapshot,
+        };
+      },
+    },
     dispatch: {
-      async decideNextUnit() {
-        const state = await deriveState(dispatchBasePath);
+      async decideNextUnit(input) {
+        const state = input.stateSnapshot;
         const active = state.activeMilestone;
         if (!active) return null;
 
@@ -1433,12 +1852,48 @@ export function createWiredAutoOrchestrationModule(
     },
     recovery: {
       async classifyAndRecover(input) {
-        const reason = input.error instanceof Error ? input.error.message : String(input.error ?? "unknown auto error");
-        return { action: "escalate" as const, reason };
+        const recovery = classifyFailure(input);
+        return { action: recovery.action, reason: recovery.reason };
+      },
+    },
+    toolContract: {
+      async compileUnitToolContract(unitType) {
+        const result = compileUnitToolContract(unitType);
+        if (!result.ok) return { ok: false, reason: result.detail };
+        return { ok: true, reason: result.contract.validationRules.join(", ") };
       },
     },
     worktree: {
-      async prepareForUnit() {},
+      async prepareForUnit(unitType, unitId) {
+        const manifest = resolveManifest(unitType);
+        if (!manifest) {
+          return {
+            ok: false,
+            reason: `No Unit manifest is registered for ${unitType}`,
+          };
+        }
+        const writeScope =
+          manifest.tools.mode === "all" || manifest.tools.mode === "docs"
+            ? "source-writing"
+            : "planning-only";
+        const safety = createWorktreeSafetyModule();
+        const snapshot = await deriveState(dispatchBasePath);
+        const milestoneId = snapshot.activeMilestone?.id ?? null;
+        const expectedBranch = milestoneId ? autoWorktreeBranch(milestoneId) : null;
+        const result = safety.validateUnitRoot({
+          unitType,
+          unitId,
+          writeScope,
+          projectRoot: runtimeBasePath,
+          unitRoot: dispatchBasePath,
+          milestoneId,
+          expectedBranch,
+        });
+        if (!result.ok) {
+          return { ok: false, reason: `${result.kind}: ${result.reason}` };
+        }
+        return { ok: true, reason: result.kind };
+      },
       async syncAfterUnit() {},
       async cleanupOnStop() {},
     },
@@ -1536,6 +1991,7 @@ function buildLoopDeps(pi: ExtensionAPI): LoopDeps {
   initRegistry(convertDispatchRules(DISPATCH_RULES));
 
   const cmux = makeCmuxEmitters(pi);
+  const worktreeProjection = new WorktreeStateProjection();
 
   return {
     lockBase,
@@ -1559,8 +2015,8 @@ function buildLoopDeps(pi: ExtensionAPI): LoopDeps {
     // Pre-dispatch health gate
     preDispatchHealthGate,
 
-    // Worktree sync
-    syncProjectRootToWorktree,
+    // Worktree state projection (ADR-016 — single Module Interface)
+    worktreeProjection,
 
     // Resource version guard
     checkResourcesStale,
@@ -1575,7 +2031,6 @@ function buildLoopDeps(pi: ExtensionAPI): LoopDeps {
     pruneQueueOrder,
     isInAutoWorktree,
     shouldUseWorktreeIsolation,
-    mergeMilestoneToMain,
     teardownAutoWorktree,
     createAutoWorktree,
     captureIntegrationBranch,
@@ -1632,8 +2087,9 @@ function buildLoopDeps(pi: ExtensionAPI): LoopDeps {
     // Git
     GitServiceImpl: GitServiceImpl as unknown as LoopDeps["GitServiceImpl"],
 
-    // WorktreeResolver
-    resolver: buildResolver(),
+    // Worktree Lifecycle Module (ADR-016 — single Module Interface for the
+    // milestone create/enter/exit/merge verbs)
+    lifecycle: buildLifecycle(),
 
     // Post-unit processing
     postUnitPreVerification,
@@ -1894,7 +2350,12 @@ export async function startAuto(
     s.verbose = verboseMode;
     s.stepMode = requestedStepMode;
     s.cmdCtx = ctx;
-    s.basePath = base;
+    // ADR-016 phase 2 / B2 (#5620): bootstrap basePath transition before
+    // the resume path consults persisted worktree state. Defensive about
+    // s.originalBasePath — the meta-restore above (line 2003 / 2055) may
+    // have already populated it from paused metadata; the verb preserves
+    // that value.
+    buildLifecycle().adoptSessionRoot(base);
     // ── Resume worktree: if the paused session was inside a milestone worktree,
     // apply that path as the dispatch basePath immediately (#3723).
     // This ensures the dispatch loop runs from the worktree directory even when
@@ -1910,9 +2371,8 @@ export async function startAuto(
         { file: "auto.ts", milestoneId: s.currentMilestoneId ?? "" },
       );
     }
-    if (resumeWorktreePath && existsSync(resumeWorktreePath)) {
-      s.basePath = resumeWorktreePath;
-    }
+    // ADR-016 phase 2 / B3 (#5621): paused-resume worktree-path adoption.
+    buildLifecycle().resumeFromPausedSession(base, resumeWorktreePath);
     // Rebuild scope now that s.basePath reflects the actual worktree (or project root).
     rebuildScope(s.basePath, s.currentMilestoneId);
     // Ensure the workflow-logger audit log is pinned to the project root
@@ -1940,9 +2400,17 @@ export async function startAuto(
       !detectWorktreeName(s.basePath) &&
       !detectWorktreeName(s.originalBasePath)
     ) {
-      buildResolver().enterMilestone(s.currentMilestoneId, {
+      const enterResult = buildLifecycle().enterMilestone(s.currentMilestoneId, {
         notify: ctx.ui.notify.bind(ctx.ui),
       });
+      if (!enterResult.ok && enterResult.reason === "lease-conflict") {
+        ctx.ui.notify(
+          `Cannot resume milestone ${s.currentMilestoneId}: lease is held by another worker.`,
+          "error",
+        );
+        await stopAuto(ctx, pi, "lease-conflict during resume");
+        return;
+      }
       // s.basePath may have been updated to a worktree path by enterMilestone.
       rebuildScope(s.basePath, s.currentMilestoneId);
     }
@@ -1964,16 +2432,7 @@ export async function startAuto(
     // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
     // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
     // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
-    const pkgRoot = process.env.GSD_PKG_ROOT;
-    const resourceLoaderPath = pkgRoot
-      ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
-      : new URL("../../../resource-loader.js", import.meta.url).href;
-    const { initResources } = await import(resourceLoaderPath);
-    initResources(agentDir);
-    // Open the project DB before rebuild/derive so resume uses DB-backed
-    // state instead of falling back to stale markdown parsing (#2940).
-    await openProjectDbIfPresent(s.basePath);
+    await refreshResumeResourcesAndDb(s.basePath);
     try {
       await rebuildState(s.basePath);
       pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync" as const, preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, state: await deriveState(s.basePath) });
@@ -2045,7 +2504,7 @@ export async function startAuto(
       runKernelLoop: runUokKernelLoop,
       runLegacyLoop: runLegacyAutoLoop,
     });
-    cleanupAfterLoopExit(ctx);
+    await cleanupAfterLoopExit(ctx);
     return;
   }
 
@@ -2054,9 +2513,14 @@ export async function startAuto(
     shouldUseWorktreeIsolation,
     registerSigtermHandler,
     lockBase,
-    buildResolver,
+    buildLifecycle,
   };
 
+  // Register the worker before bootstrap enters a milestone worktree.
+  // This ensures enterMilestone can claim a lease and seed dispatch claims
+  // for crash-recovery fidelity (#5405).
+  registerAutoWorkerForSession(s, base);
+
   const ready = await bootstrapAutoSession(
     s,
     ctx,
@@ -2100,7 +2564,7 @@ export async function startAuto(
     runKernelLoop: runUokKernelLoop,
     runLegacyLoop: runLegacyAutoLoop,
   });
-  cleanupAfterLoopExit(ctx);
+  await cleanupAfterLoopExit(ctx);
 }
 
 // describeNextUnit is imported from auto-dashboard.ts and re-exported
@@ -2210,7 +2674,12 @@ export async function dispatchHookUnit(
     s.pendingQuickTasks = [];
   }
 
-  s.basePath = targetBasePath;
+  // ADR-016 phase 2 / B2 (#5620): hook-trigger basePath transition. Treats
+  // the trigger as a bootstrap variant — if the session is fresh,
+  // `originalBasePath` gets set to `targetBasePath`; if the session was
+  // already active with an established `originalBasePath`, the verb
+  // preserves it.
+  buildLifecycle().adoptSessionRoot(targetBasePath);
   if (!s.orchestration) {
     ensureOrchestrationModule(ctx, pi, s.basePath);
   }
@@ -2224,24 +2693,7 @@ export async function dispatchHookUnit(
     startedAt: hookStartedAt,
   };
 
-  // Ensure cwd matches basePath BEFORE newSession() captures it (#1389).
-  // newSession() snapshots process.cwd() during construction; chdir-ing
-  // afterward leaves the session rooted to whatever cwd was when the call
-  // was made. Must be synchronous — no awaits between chdir and newSession.
-  try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch (err) {
-    const msg = `Failed to chdir before hook newSession (basePath: ${s.basePath}): ${err instanceof Error ? err.message : String(err)}`;
-    logWarning("engine", msg, { file: "auto.ts", basePath: s.basePath, error: err instanceof Error ? err.message : String(err) });
-    ctx.ui.notify(`${msg}. Cancelling hook dispatch to avoid running in the wrong directory.`, "error");
-    if (wasActive) {
-      s.basePath = previousBasePath;
-      s.currentUnit = previousCurrentUnit;
-    } else {
-      s.reset();
-    }
-    return false;
-  }
-
-  const result = await s.cmdCtx!.newSession();
+  const result = await s.cmdCtx!.newSession({ workspaceRoot: s.basePath });
   if (result.cancelled) {
     await stopAuto(ctx, pi);
     return false;