gsd-pi 2.81.0 → 2.82.0-dev.c22380fc3

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

@@ -16,6 +16,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
   ExtensionCommandContext,
+  SessionMessageEntry,
 } from "@gsd/pi-coding-agent";
 
 import { deriveState } from "./state.js";
@@ -32,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 {
@@ -188,6 +189,8 @@ import { isClosedStatus } from "./status-guards.js";
 import {
   type AutoDashboardData,
   updateProgressWidget as _updateProgressWidget,
+  setCompletionProgressWidget,
+  setAutoOutcomeWidget,
   updateSliceProgressCache,
   clearSliceProgressCache,
   describeNextUnit as _describeNextUnit,
@@ -201,7 +204,7 @@ 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";
@@ -231,18 +234,20 @@ 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 type { AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } 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";
+import { supportsStructuredQuestions } from "./workflow-mcp.js";
+import type { MinimalModelRegistry } from "./context-budget.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -456,15 +461,10 @@ export function _synthesizePausedSessionRecoveryForTest(
   return synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile);
 }
 
-export function _resolvePausedResumeBasePathForTest(
-  basePath: string,
-  pausedWorktreePath: string | null | undefined,
-  pathExists: (path: string) => boolean = existsSync,
-): string {
-  return pausedWorktreePath && pathExists(pausedWorktreePath)
-    ? pausedWorktreePath
-    : basePath;
-}
+// `_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;
 
@@ -668,6 +668,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;
@@ -928,6 +932,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,
@@ -1015,27 +1044,35 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<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 + chdir routes
+  // through `Lifecycle.restoreToProjectRoot()`, the sole owner of both
+  // `s.basePath` mutation and the paired `process.chdir` for auto-loop
+  // transitions. The verb assigns `s.basePath` before any throwable work, so
+  // a thrown error still leaves basePath restored.
   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" },
+      );
     }
   }
 
   if (s.originalBasePath && s.cmdCtx) {
-    const result = await rerootCommandSession(s.cmdCtx, s.basePath);
+    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.basePath });
+      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.basePath });
+      logWarning("engine", `post-loop session re-root failed: ${result.error ?? "unknown"}`, { file: "auto.ts", basePath: s.originalBasePath });
     }
   }
 }
@@ -1046,6 +1083,58 @@ export function _cleanupAfterLoopExitForTest(ctx: ExtensionContext): Promise<voi
 
 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,
@@ -1063,15 +1152,17 @@ 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 =
@@ -1096,10 +1187,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)}`);
@@ -1257,6 +1351,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 {
@@ -1269,19 +1378,15 @@ 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` owns both s.basePath restore and process.chdir;
+    // no paired chdir 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) });
       }
-    } catch (e) {
-      debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
     }
 
     // Re-root the active command session/tool runtime after worktree teardown.
@@ -1289,30 +1394,91 @@ export async function stopAuto(
     // 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.basePath);
+      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.basePath });
+        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.basePath });
+        logWarning("engine", `post-stop session re-root failed: ${result.error ?? "unknown"}`, { file: "auto.ts", basePath: s.originalBasePath });
       }
     }
 
     // ── 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 });
@@ -1403,8 +1569,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();
 
@@ -1421,7 +1599,7 @@ export async function stopAuto(
     }
 
     // Reset all session state in one call
-    s.reset();
+    s.resetAfterStop({ preserveCompletionSurface });
   }
 }
 
@@ -1495,6 +1673,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 {
@@ -1545,8 +1725,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",
@@ -1561,29 +1749,105 @@ export async function pauseAuto(
  * deps bag is intentionally focused — Lifecycle does not see the wider auto-
  * mode dependency graph.
  */
-function buildLifecycle(): WorktreeLifecycle {
-  const lifecycleDeps = {
-    enterAutoWorktree,
-    createAutoWorktree,
-    enterBranchModeForMilestone,
-    getAutoWorktreePath,
-    getIsolationMode,
-    invalidateAllCaches,
-    GitServiceImpl,
-    loadEffectiveGSDPreferences,
+/**
+ * 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).
+ */
+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 {
+    gitServiceFactory: (basePath: string) => {
+      const gitConfig =
+        loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+      return new GitServiceImpl(basePath, gitConfig);
+    },
     worktreeProjection: new WorktreeStateProjection(),
-    isInAutoWorktree,
-    autoCommitCurrentBranch,
-    autoWorktreeBranch,
-    teardownAutoWorktree,
     mergeMilestoneToMain,
-    getCurrentBranch,
-    checkoutBranch: nativeCheckoutBranch,
-    resolveMilestoneFile,
-    readFileSync: (path: string, encoding: string) =>
-      readFileSync(path, encoding as BufferEncoding),
-  } as unknown as WorktreeLifecycleDeps;
-  return new WorktreeLifecycle(s, lifecycleDeps);
+  };
+}
+
+function buildLifecycle(): WorktreeLifecycle {
+  return new WorktreeLifecycle(s, buildWorktreeLifecycleDeps());
+}
+
+/**
+ * Build the production `DispatchAdapter` used by `createWiredAutoOrchestrationModule`.
+ *
+ * Exported so tests can verify parity with `runDispatch`'s `resolveDispatch` call —
+ * the wired adapter must derive `structuredQuestionsAvailable`, `sessionContextWindow`,
+ * `sessionProvider`, and `modelRegistry` the same way phases.ts:runDispatch does.
+ */
+export function createWiredDispatchAdapter(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  dispatchBasePath: string,
+): DispatchAdapter {
+  return {
+    async decideNextUnit(input) {
+      const state = input.stateSnapshot;
+      const active = state.activeMilestone;
+      if (!active) return null;
+
+      const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+
+      // Derive session-derived dispatch inputs the same way phases.ts:runDispatch does
+      // (#5789). Prefer caller-supplied values when present so test harnesses and
+      // alternative wirings can inject deterministic snapshots; otherwise pull from
+      // the captured pi/ctx references.
+      const sessionProvider = input.sessionProvider ?? ctx.model?.provider;
+      const sessionContextWindow = input.sessionContextWindow ?? ctx.model?.contextWindow;
+      const modelRegistry = input.modelRegistry ?? (ctx.modelRegistry as MinimalModelRegistry | undefined);
+      const authMode =
+        sessionProvider && typeof ctx.modelRegistry?.getProviderAuthMode === "function"
+          ? ctx.modelRegistry.getProviderAuthMode(sessionProvider)
+          : undefined;
+      const activeTools = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+      // Mirrors runDispatch: deep-planning keeps approval gates in plain chat
+      // because structured questions can be cancelled outside the chat turn on
+      // some transports.
+      const structuredQuestionsAvailable =
+        input.structuredQuestionsAvailable ??
+        (prefs?.planning_depth === "deep"
+          ? "false"
+          : supportsStructuredQuestions(activeTools, {
+              authMode,
+              baseUrl: ctx.model?.baseUrl,
+            })
+            ? "true"
+            : "false");
+
+      const action = await resolveDispatch({
+        basePath: dispatchBasePath,
+        mid: active.id,
+        midTitle: active.title,
+        state,
+        prefs,
+        structuredQuestionsAvailable,
+        sessionContextWindow,
+        sessionProvider,
+        modelRegistry,
+      });
+
+      if (action.action !== "dispatch") return null;
+      return {
+        unitType: action.unitType,
+        unitId: action.unitId,
+        reason: action.matchedRule ?? "dispatch",
+        preconditions: [],
+      };
+    },
+  };
 }
 
 /**
@@ -1595,7 +1859,7 @@ function buildLifecycle(): WorktreeLifecycle {
  */
 export function createWiredAutoOrchestrationModule(
   ctx: ExtensionContext,
-  _pi: ExtensionAPI,
+  pi: ExtensionAPI,
   dispatchBasePath: string,
   runtimeBasePath = resolveProjectRoot(dispatchBasePath),
 ): AutoOrchestrationModule {
@@ -1606,44 +1870,25 @@ export function createWiredAutoOrchestrationModule(
     stateReconciliation: {
       async reconcileBeforeDispatch() {
         const result = await reconcileBeforeDispatch(dispatchBasePath);
-        if (!result.ok) {
+        if (result.blockers.length > 0) {
           return {
             ok: false,
-            reason: result.reason,
+            reason: result.blockers[0],
             stateSnapshot: result.stateSnapshot,
           };
         }
+        const repairedKinds = result.repaired.map((d) => d.kind);
         return {
           ok: true,
-          reason: result.repaired.join(", "),
+          reason:
+            repairedKinds.length > 0
+              ? `repaired: ${repairedKinds.join(", ")}`
+              : "clean",
           stateSnapshot: result.stateSnapshot,
         };
       },
     },
-    dispatch: {
-      async decideNextUnit(input) {
-        const state = input.stateSnapshot;
-        const active = state.activeMilestone;
-        if (!active) return null;
-
-        const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
-        const action = await resolveDispatch({
-          basePath: dispatchBasePath,
-          mid: active.id,
-          midTitle: active.title,
-          state,
-          prefs,
-        });
-
-        if (action.action !== "dispatch") return null;
-        return {
-          unitType: action.unitType,
-          unitId: action.unitId,
-          reason: action.matchedRule ?? "dispatch",
-          preconditions: [],
-        };
-      },
-    },
+    dispatch: createWiredDispatchAdapter(ctx, pi, dispatchBasePath),
     recovery: {
       async classifyAndRecover(input) {
         const recovery = classifyFailure(input);
@@ -1692,12 +1937,25 @@ export function createWiredAutoOrchestrationModule(
       async cleanupOnStop() {},
     },
     health: {
+      checkResourcesStale() {
+        return checkResourcesStale(s.resourceVersionOnStart);
+      },
       async preAdvanceGate() {
-        const gate = await preDispatchHealthGate(dispatchBasePath);
-        return {
-          allow: gate.proceed,
-          reason: gate.reason,
-        };
+        try {
+          const gate = await preDispatchHealthGate(dispatchBasePath);
+          if (gate.proceed) {
+            return {
+              kind: "pass",
+              fixesApplied: gate.fixesApplied,
+            };
+          }
+          return {
+            kind: "fail",
+            reason: gate.reason ?? "Pre-dispatch health check failed — run /gsd doctor for details.",
+          };
+        } catch (error) {
+          return { kind: "threw", error };
+        }
       },
       async postAdvanceRecord(result) {
         if (result.kind === "error") {
@@ -1765,6 +2023,43 @@ export function createWiredAutoOrchestrationModule(
         }
       },
     },
+    uokGate: {
+      async emit(input) {
+        const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+        const uokFlags = resolveUokFlags(prefs);
+        if (!uokFlags.gates) return;
+        const milestoneId = input.milestoneId ?? s.currentMilestoneId ?? undefined;
+        try {
+          const { UokGateRunner } = await import("./uok/gate-runner.js");
+          const runner = new UokGateRunner();
+          runner.register({
+            id: input.gateId,
+            type: input.gateType,
+            execute: async () => ({
+              outcome: input.outcome,
+              failureClass: input.failureClass,
+              rationale: input.rationale,
+              findings: input.findings ?? "",
+            }),
+          });
+          await runner.run(input.gateId, {
+            basePath: dispatchBasePath,
+            traceId: `pre-dispatch:${flowId}`,
+            turnId: `orch-${seq}`,
+            milestoneId,
+            unitType: "pre-dispatch",
+            unitId: `orch-${seq}`,
+          });
+        } catch (err) {
+          logWarning("engine", `uok gate emit failed: ${getErrorMessage(err)}`, {
+            file: "auto.ts",
+            gateId: input.gateId,
+            gateType: input.gateType,
+            ...(milestoneId ? { milestoneId } : {}),
+          });
+        }
+      },
+    },
   };
 
   return createAutoOrchestrator(deps);
@@ -1825,7 +2120,6 @@ function buildLoopDeps(pi: ExtensionAPI): LoopDeps {
     pruneQueueOrder,
     isInAutoWorktree,
     shouldUseWorktreeIsolation,
-    mergeMilestoneToMain,
     teardownAutoWorktree,
     createAutoWorktree,
     captureIntegrationBranch,
@@ -2145,7 +2439,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
@@ -2161,7 +2460,8 @@ export async function startAuto(
         { file: "auto.ts", milestoneId: s.currentMilestoneId ?? "" },
       );
     }
-    s.basePath = _resolvePausedResumeBasePathForTest(base, 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
@@ -2463,7 +2763,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);
   }