gsd-pi 2.81.0 → 2.82.0-dev.20138ae42

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

@@ -15,14 +15,14 @@ import { deriveState } from "./state.js";
 import { parseUnitId } from "./unit-id.js";
 import { assessInterruptedSession, readPausedSessionMetadata, PAUSED_SESSION_KV_KEY, } from "./interrupted-session.js";
 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 { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic, readActiveMilestoneId, } from "./session-forensics.js";
-import { writeLock, clearLock, readCrashLock, isLockProcessAlive, formatCrashInfo, emitCrashRecoveredUnitEnd, emitOpenUnitEndForUnit, } from "./crash-recovery.js";
+import { writeLock, clearLock, clearStaleWorkerLock, readCrashLock, isLockProcessAlive, formatCrashInfo, emitCrashRecoveredUnitEnd, emitOpenUnitEndForUnit, } from "./crash-recovery.js";
 import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
 import { sendDesktopNotification } from "./notifications.js";
@@ -45,11 +45,10 @@ import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
-import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, resolveProjectRoot, } from "./worktree.js";
+import { captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, 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, enterAutoWorktree, enterBranchModeForMilestone, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
+import { createAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
@@ -61,9 +60,9 @@ import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
 import { isClosedStatus } from "./status-guards.js";
-import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, } from "./auto-dashboard.js";
+import { updateProgressWidget as _updateProgressWidget, setCompletionProgressWidget, setAutoOutcomeWidget, updateSliceProgressCache, clearSliceProgressCache, unitVerb, } from "./auto-dashboard.js";
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } 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";
@@ -93,6 +92,7 @@ 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 { WorktreeLifecycle, } from "./worktree-lifecycle.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { reorderForCaching } from "./prompt-ordering.js";
@@ -253,11 +253,10 @@ function synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile
 export function _synthesizePausedSessionRecoveryForTest(basePath, unitType, unitId, sessionFile) {
     return synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile);
 }
-export function _resolvePausedResumeBasePathForTest(basePath, pausedWorktreePath, pathExists = existsSync) {
-    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;
 function withDetachedAutoKeepalive(run) {
     const keepAlive = setInterval(() => { }, DETACHED_AUTO_KEEPALIVE_INTERVAL_MS);
@@ -415,6 +414,9 @@ export function getAutoDashboardData() {
 export function isAutoActive() {
     return s.active;
 }
+export function isAutoCompletionStopInProgress() {
+    return s.completionStopInProgress;
+}
 /** Test-only seam for validating auto-mode guards (#4704). Do not use in production code. */
 export function _setAutoActiveForTest(active) {
     s.active = active;
@@ -611,6 +613,21 @@ function buildSnapshotOpts(_unitType, _unitId) {
         ...(s.currentUnitRouting ?? {}),
     };
 }
+function currentUnitLabel() {
+    if (!s.currentUnit)
+        return null;
+    return `${unitVerb(s.currentUnit.type)} ${s.currentUnit.id}`;
+}
+function setLifecycleOutcome(ctx, input) {
+    if (!ctx?.hasUI)
+        return;
+    const { unitLabel: unitLabelOverride, ...rest } = input;
+    setAutoOutcomeWidget(ctx, {
+        ...rest,
+        unitLabel: unitLabelOverride !== undefined ? unitLabelOverride : currentUnitLabel(),
+        startedAt: s.autoStartTime,
+    });
+}
 function handleLostSessionLock(ctx, lockStatus) {
     debugLog("session-lock-lost", {
         lockBase: lockBase(),
@@ -691,32 +708,76 @@ export async function cleanupAfterLoopExit(ctx) {
     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 });
         }
     }
 }
 export function _cleanupAfterLoopExitForTest(ctx) {
     return cleanupAfterLoopExit(ctx);
 }
+function normalizeFrontmatterList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map(item => typeof item === "string" ? item.trim() : "")
+        .filter(item => item.length > 0 && item !== "(none)");
+}
+function firstBoldParagraph(body) {
+    const match = body.match(/\*\*([^*\n][\s\S]*?)\*\*/);
+    return match?.[1]?.replace(/\s+/g, " ").trim() || undefined;
+}
+function loadMilestoneCompletionRollup(basePath, milestoneId) {
+    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, milestoneMergedInPhases, milestoneComplete) {
     const action = _selectStopAutoWorktreeExit({
         currentMilestoneId: currentMilestoneId ?? null,
@@ -725,15 +786,16 @@ export function _resolveAutoWorktreeExitActionForTest(currentMilestoneId, milest
     });
     return action === "none" ? "skip" : action;
 }
-export async function stopAuto(ctx, pi, reason) {
+export async function stopAuto(ctx, pi, reason, options = {}) {
     if (!s.active && !s.paused)
         return;
     const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
     const reasonSuffix = reason ? ` — ${reason}` : "";
-    // #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.
+    const preserveCompletionSurface = Boolean(options.completionWidget);
+    s.completionStopInProgress = preserveCompletionSurface;
+    // #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");
         // Normalize the free-form reason to a closed set so the telemetry
@@ -755,10 +817,13 @@ export async function stopAuto(ctx, pi, reason) {
                                 : 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) {
@@ -902,6 +967,21 @@ export async function stopAuto(ctx, pi, reason) {
                 });
             }
         }
+        // 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 = null;
+        let totalSlices = 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 {
@@ -914,49 +994,105 @@ export async function stopAuto(ctx, pi, reason) {
                 });
             }
         }
-        // ── 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.
         // 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.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`, "info");
+                ctx?.ui.notify(`${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;
+                        if (msgEntry.message?.role === "assistant") {
+                            const usage = msgEntry.message.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", preferences: loadedPreferences });
@@ -1047,9 +1183,21 @@ export async function stopAuto(ctx, pi, reason) {
         resetProactiveHealing();
         // 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();
         // Drop the active-tool baseline so a subsequent /gsd auto run on the
@@ -1065,7 +1213,7 @@ export async function stopAuto(ctx, pi, reason) {
             debugLog("stop-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
         }
         // Reset all session state in one call
-        s.reset();
+        s.resetAfterStop({ preserveCompletionSurface });
     }
 }
 export function _selectStopAutoWorktreeExit(args) {
@@ -1126,6 +1274,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
         // Non-fatal — resume will still work via full bootstrap, just without worktree context
         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 {
@@ -1173,9 +1322,17 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     s.verificationRetryCount.clear();
     ctx?.ui.setStatus("gsd-auto", "paused");
     ctx?.ui.setWidget("gsd-progress", undefined);
+    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);
-    const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
     ctx?.ui.notify(`${s.stepMode ? "Step" : "Auto"}-mode paused (Escape). Type to interact, or ${resumeCmd} to resume.`, "info");
 }
 /**
@@ -1186,28 +1343,101 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
  * deps bag is intentionally focused — Lifecycle does not see the wider auto-
  * mode dependency graph.
  */
-function buildLifecycle() {
-    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() {
+    // 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) => {
+            const gitConfig = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+            return new GitServiceImpl(basePath, gitConfig);
+        },
         worktreeProjection: new WorktreeStateProjection(),
-        isInAutoWorktree,
-        autoCommitCurrentBranch,
-        autoWorktreeBranch,
-        teardownAutoWorktree,
         mergeMilestoneToMain,
-        getCurrentBranch,
-        checkoutBranch: nativeCheckoutBranch,
-        resolveMilestoneFile,
-        readFileSync: (path, encoding) => readFileSync(path, encoding),
     };
-    return new WorktreeLifecycle(s, lifecycleDeps);
+}
+function buildLifecycle() {
+    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, pi, dispatchBasePath) {
+    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;
+            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 === "stop") {
+                return {
+                    kind: "blocked",
+                    reason: action.reason,
+                    action: action.level === "warning" ? "pause" : "stop",
+                };
+            }
+            if (action.action !== "dispatch")
+                return null;
+            return {
+                unitType: action.unitType,
+                unitId: action.unitId,
+                reason: action.matchedRule ?? "dispatch",
+                preconditions: [],
+            };
+        },
+    };
 }
 /**
  * Thin entry glue for the new Auto Orchestration module.
@@ -1216,51 +1446,31 @@ function buildLifecycle() {
  * no behavior changes to the existing auto loop. It provides a concrete seam
  * the next refactor steps can adopt incrementally.
  */
-export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
+export function createWiredAutoOrchestrationModule(ctx, pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
     const flowId = `auto-orchestrator-${Date.now()}`;
     let seq = 0;
     const deps = {
         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);
@@ -1309,12 +1519,26 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
             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") {
@@ -1382,9 +1606,59 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
                 }
             },
         },
+        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);
 }
+function notifyResumeBlocked(ctx, result) {
+    const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
+    ctx.ui.notify(`Auto-mode blocked: ${result.reason}. Fix and run ${resumeCmd} to resume.`, "warning");
+    setLifecycleOutcome(ctx, {
+        status: "blocked",
+        title: "Auto-mode blocked",
+        detail: result.reason,
+        nextAction: `Fix the blocker, then run ${resumeCmd} to resume.`,
+        commands: ["/gsd status for overview", `${resumeCmd} to resume`, "/gsd doctor to diagnose"],
+    });
+}
 function ensureOrchestrationModule(ctx, pi, basePath) {
     s.orchestration = createWiredAutoOrchestrationModule(ctx, pi, basePath, lockBase());
 }
@@ -1431,7 +1705,6 @@ function buildLoopDeps(pi) {
         pruneQueueOrder,
         isInAutoWorktree,
         shouldUseWorktreeIsolation,
-        mergeMilestoneToMain,
         teardownAutoWorktree,
         createAutoWorktree,
         captureIntegrationBranch,
@@ -1670,7 +1943,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // This closes the journal gap reported in #3348 where the worker wrote side
         // effects (SUMMARY.md, DB updates) but died before emitting unit-end.
         emitCrashRecoveredUnitEnd(base, freshStartAssessment.lock);
-        clearLock(base);
+        clearStaleWorkerLock(base);
     }
     if (!s.paused) {
         s.pendingCrashRecovery =
@@ -1701,7 +1974,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         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
@@ -1713,7 +1991,8 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         if (resumeWorktreePath && !existsSync(resumeWorktreePath)) {
             logWarning("session", `Worktree was expected at ${resumeWorktreePath} but is missing. Continuing in project-root mode. To restart with a fresh worktree, run /gsd-debug or recreate the milestone.`, { 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
@@ -1727,6 +2006,8 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             initMetrics(base);
         if (s.currentMilestoneId)
             setActiveMilestoneId(base, s.currentMilestoneId);
+        await openProjectDbIfPresent(base);
+        registerAutoWorkerForSession(s, base);
         // Re-register health level notification callback lost across process restart
         setLevelChangeCallback((_from, to, summary) => {
             const level = to === "red" ? "error" : to === "yellow" ? "warning" : "info";
@@ -1802,7 +2083,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         }
         pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
         try {
-            await s.orchestration?.resume();
+            const resumeResult = await s.orchestration?.resume();
+            if (resumeResult?.kind === "blocked") {
+                notifyResumeBlocked(ctx, resumeResult);
+                await cleanupAfterLoopExit(ctx);
+                return;
+            }
         }
         catch (err) {
             debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
@@ -1823,6 +2109,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     const bootstrapDeps = {
         shouldUseWorktreeIsolation,
         registerSigtermHandler,
+        registerAutoWorkerForSession: (projectRoot) => registerAutoWorkerForSession(s, projectRoot),
         lockBase,
         buildLifecycle,
     };
@@ -1936,7 +2223,12 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         s.currentUnit = null;
         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);
     }