gsd-pi 2.33.1 → 2.34.0-dev.6769913

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

@@ -18,20 +18,33 @@ import type {
 
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, getManifestStatus, resolveAllOverrides, parsePlan, parseSummary } from "./files.js";
-import { loadPrompt } from "./prompt-loader.js";
-import { runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit } from "./verification-gate.js";
-import { writeVerificationJSON } from "./verification-evidence.js";
+import { getManifestStatus } from "./files.js";
+export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import {
-  gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
-  resolveMilestonePath, resolveDir, resolveTasksDir, resolveTaskFile,
-  milestonesDir, buildTaskFileName,
+  gsdRoot,
+  resolveMilestoneFile,
+  resolveSliceFile,
+  resolveSlicePath,
+  resolveMilestonePath,
+  resolveDir,
+  resolveTasksDir,
+  resolveTaskFile,
+  milestonesDir,
+  buildTaskFileName,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
-import { saveActivityLog, clearActivityLogState } from "./activity-log.js";
-import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
-import { writeLock, clearLock, readCrashLock, formatCrashInfo, isLockProcessAlive } from "./crash-recovery.js";
+import { clearActivityLogState } from "./activity-log.js";
+import {
+  synthesizeCrashRecovery,
+  getDeepDiagnostic,
+} from "./session-forensics.js";
+import {
+  writeLock,
+  clearLock,
+  readCrashLock,
+  isLockProcessAlive,
+} from "./crash-recovery.js";
 import {
   acquireSessionLock,
   validateSessionLock,
@@ -44,7 +57,11 @@ import {
   readUnitRuntimeRecord,
   writeUnitRuntimeRecord,
 } from "./unit-runtime.js";
-import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, getIsolationMode } from "./preferences.js";
+import {
+  resolveAutoSupervisorConfig,
+  loadEffectiveGSDPreferences,
+  getIsolationMode,
+} from "./preferences.js";
 import { sendDesktopNotification } from "./notifications.js";
 import type { GSDPreferences } from "./preferences.js";
 import {
@@ -69,11 +86,13 @@ import { closeoutUnit } from "./auto-unit-closeout.js";
 import { recoverTimedOutUnit } from "./auto-timeout-recovery.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import {
+  syncProjectRootToWorktree,
+  syncStateToProjectRoot,
   readResourceVersion,
   checkResourcesStale,
   escapeStaleWorktree,
-} from "./resource-version.js";
-import { initRoutingHistory, resetRoutingHistory, recordOutcome } from "./routing-history.js";
+} from "./auto-worktree-sync.js";
+import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
 import {
   checkPostUnitHooks,
   getActiveHook,
@@ -85,8 +104,7 @@ import {
   restoreHookState,
   clearPersistedHookState,
 } from "./post-unit-hooks.js";
-import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { runGSDDoctor, rebuildState, summarizeDoctorIssues } from "./doctor.js";
+import { runGSDDoctor, rebuildState } from "./doctor.js";
 import {
   preDispatchHealthGate,
   recordHealthSnapshot,
@@ -95,20 +113,22 @@ import {
   formatHealthSummary,
   getConsecutiveErrorUnits,
 } from "./doctor-proactive.js";
-import { snapshotSkills, clearSkillSnapshot } from "./skill-discovery.js";
-import { captureAvailableSkills, getAndClearSkills, resetSkillTelemetry } from "./skill-telemetry.js";
+import { clearSkillSnapshot } from "./skill-discovery.js";
+import {
+  captureAvailableSkills,
+  resetSkillTelemetry,
+} from "./skill-telemetry.js";
 import {
-  initMetrics, resetMetrics, getLedger,
-  getProjectTotals, formatCost, formatTokenCount,
+  initMetrics,
+  resetMetrics,
+  getLedger,
+  getProjectTotals,
+  formatCost,
+  formatTokenCount,
 } from "./metrics.js";
-import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
-import { GSDError, GSD_ARTIFACT_MISSING } from "./errors.js";
 import { join } from "node:path";
-import { sep as pathSep } from "node:path";
-import { parseUnitId } from "./unit-id.js";
-import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync, statSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
 import {
   autoCommitCurrentBranch,
   captureIntegrationBranch,
@@ -119,9 +139,8 @@ import {
   parseSliceBranch,
   setActiveMilestoneId,
 } from "./worktree.js";
-import { createGitService, type TaskCommitContext } from "./git-service.js";
+import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import { formatGitError } from "./git-self-heal.js";
 import {
   createAutoWorktree,
   enterAutoWorktree,
@@ -131,26 +150,21 @@ import {
   getAutoWorktreeOriginalBase,
   mergeMilestoneToMain,
   autoWorktreeBranch,
+  syncWorktreeStateBack,
 } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
-import { consumeSignal } from "./session-status-io.js";
-import { showNextAction } from "../shared/mod.js";
-import { debugLog, debugTime, debugCount, debugPeak, enableDebug, isDebugEnabled, writeDebugSummary, getDebugLogPath } from "./debug-logger.js";
+
+import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import {
   resolveExpectedArtifactPath,
   verifyExpectedArtifact,
   writeBlockerPlaceholder,
   diagnoseExpectedArtifact,
   skipExecuteTask,
-  completedKeysPath,
-  persistCompletedKey,
-  removePersistedKey,
-  loadPersistedKeys,
-  selfHealRuntimeRecords,
   buildLoopRemediationSteps,
   reconcileMergeState,
 } from "./auto-recovery.js";
-import { resolveDispatch, resetRewriteCircuitBreaker } from "./auto-dispatch.js";
+import { resolveDispatch } from "./auto-dispatch.js";
 import {
   type AutoDashboardData,
   updateProgressWidget as _updateProgressWidget,
@@ -169,28 +183,52 @@ import {
   detectWorkingTreeActivity,
 } from "./auto-supervisor.js";
 import { isDbAvailable } from "./gsd-db.js";
-import { hasPendingCaptures, loadPendingCaptures, countPendingCaptures } from "./captures.js";
+import { countPendingCaptures } from "./captures.js";
 
 // ── Extracted modules ──────────────────────────────────────────────────────
-import { startUnitSupervision, type SupervisionContext } from "./auto-timers.js";
-import { checkIdempotency, type IdempotencyContext } from "./auto-idempotency.js";
-import { checkStuckAndRecover, type StuckContext } from "./auto-stuck-detection.js";
-import { runPostUnitVerification, type VerificationContext } from "./auto-verification.js";
-import { postUnitPreVerification, postUnitPostVerification, type PostUnitContext } from "./auto-post-unit.js";
+import { startUnitSupervision } from "./auto-timers.js";
+import { runPostUnitVerification } from "./auto-verification.js";
+import {
+  postUnitPreVerification,
+  postUnitPostVerification,
+} from "./auto-post-unit.js";
 import { bootstrapAutoSession, type BootstrapDeps } from "./auto-start.js";
+import { autoLoop, resolveAgentEnd, type LoopDeps } from "./auto-loop.js";
+import {
+  WorktreeResolver,
+  type WorktreeResolverDeps,
+} from "./worktree-resolver.js";
+import { reorderForCaching } from "./prompt-ordering.js";
 
-// Resource staleness, stale worktree escape → resource-version.ts
+// Worktree sync, resource staleness, stale worktree escape → auto-worktree-sync.ts
 
 // ─── Session State ─────────────────────────────────────────────────────────
 
 import {
   AutoSession,
-  MAX_UNIT_DISPATCHES, STUB_RECOVERY_THRESHOLD, MAX_LIFETIME_DISPATCHES,
-  MAX_CONSECUTIVE_SKIPS, DISPATCH_GAP_TIMEOUT_MS, MAX_SKIP_DEPTH,
-  NEW_SESSION_TIMEOUT_MS, DISPATCH_HANG_TIMEOUT_MS,
+  MAX_UNIT_DISPATCHES,
+  STUB_RECOVERY_THRESHOLD,
+  MAX_LIFETIME_DISPATCHES,
+  NEW_SESSION_TIMEOUT_MS,
+} from "./auto/session.js";
+import type {
+  CompletedUnit,
+  CurrentUnit,
+  UnitRouting,
+  StartModel,
+} from "./auto/session.js";
+export {
+  MAX_UNIT_DISPATCHES,
+  STUB_RECOVERY_THRESHOLD,
+  MAX_LIFETIME_DISPATCHES,
+  NEW_SESSION_TIMEOUT_MS,
+} from "./auto/session.js";
+export type {
+  CompletedUnit,
+  CurrentUnit,
+  UnitRouting,
+  StartModel,
 } from "./auto/session.js";
-import type { CompletedUnit, CurrentUnit, UnitRouting, StartModel, PendingVerificationRetry } from "./auto/session.js";
-import { getErrorMessage } from "./error-utils.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -206,7 +244,8 @@ import { getErrorMessage } from "./error-utils.js";
 // ─────────────────────────────────────────────────────────────────────────────
 const s = new AutoSession();
 
-import { STATE_REBUILD_MIN_INTERVAL_MS } from "./auto-constants.js";
+/** Throttle STATE.md rebuilds — at most once per 30 seconds */
+const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
@@ -215,7 +254,52 @@ export function shouldUseWorktreeIsolation(): boolean {
   return true; // default: worktree
 }
 
-// All mutable state lives in AutoSession (auto/session.ts) — see encapsulation invariant above.
+/** Crash recovery prompt — set by startAuto, consumed by the main loop */
+
+/** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */
+
+/** Verification retry count per unitId — separate from s.unitDispatchCount which tracks artifact-missing retries */
+
+/** Session file path captured at pause — used to synthesize recovery briefing on resume */
+
+/** Dashboard tracking */
+
+/** Track dynamic routing decision for the current unit (for metrics) */
+
+/** Queue of quick-task captures awaiting dispatch after triage resolution */
+
+/**
+ * Model captured at auto-mode start. Used to prevent model bleed between
+ * concurrent GSD instances sharing the same global settings.json (#650).
+ * When preferences don't specify a model for a unit type, this ensures
+ * the session's original model is re-applied instead of reading from
+ * the shared global settings (which another instance may have overwritten).
+ */
+
+/** Track current milestone to detect transitions */
+
+/** Model the user had selected before auto-mode started */
+
+/** Progress-aware timeout supervision */
+
+/** Context-pressure continue-here monitor — fires once when context usage >= 70% */
+
+/** Prompt character measurement for token savings analysis (R051). */
+
+/** SIGTERM handler registered while auto-mode is active — cleared on stop/pause. */
+
+/**
+ * Tool calls currently being executed — prevents false idle detection during long-running tools.
+ * Maps toolCallId → start timestamp (ms) so the idle watchdog can detect tools that have been
+ * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
+ */
+// Re-export budget utilities for external consumers
+export {
+  getBudgetAlertLevel,
+  getNewBudgetAlertLevel,
+  getBudgetEnforcementAction,
+} from "./auto-budget.js";
+
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
   s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
@@ -227,6 +311,8 @@ function deregisterSigtermHandler(): void {
   s.sigtermHandler = null;
 }
 
+export { type AutoDashboardData } from "./auto-dashboard.js";
+
 export function getAutoDashboardData(): AutoDashboardData {
   const ledger = getLedger();
   const totals = ledger ? getProjectTotals(ledger.units) : null;
@@ -239,12 +325,15 @@ export function getAutoDashboardData(): AutoDashboardData {
   } catch {
     // Non-fatal — captures module may not be loaded
   }
-  return { active: s.active, paused: s.paused,
+  return {
+    active: s.active,
+    paused: s.paused,
     stepMode: s.stepMode,
     startTime: s.autoStartTime,
-    elapsed: (s.active || s.paused) ? Date.now() - s.autoStartTime : 0,
+    elapsed: s.active || s.paused ? Date.now() - s.autoStartTime : 0,
     currentUnit: s.currentUnit ? { ...s.currentUnit } : null,
-    completedUnits: [...s.completedUnits], basePath: s.basePath,
+    completedUnits: [...s.completedUnits],
+    basePath: s.basePath,
     totalCost: totals?.cost ?? 0,
     totalTokens: totals?.tokens.total ?? 0,
     pendingCaptureCount,
@@ -266,7 +355,10 @@ export function isAutoPaused(): boolean {
  * Used by error-recovery to fall back to the session's own model
  * instead of reading (potentially stale) preferences from disk (#1065).
  */
-export function getAutoModeStartModel(): { provider: string; id: string } | null {
+export function getAutoModeStartModel(): {
+  provider: string;
+  id: string;
+} | null {
   return s.autoModeStartModel;
 }
 
@@ -287,9 +379,11 @@ export function getOldestInFlightToolAgeMs(): number {
  * Return the base path to use for the auto.lock file.
  * Always uses the original project root (not the worktree) so that
  * a second terminal can discover and stop a running auto-mode session.
+ *
+ * Delegates to AutoSession.lockBasePath — the single source of truth.
  */
 function lockBase(): string {
-  return s.originalBasePath || s.basePath;
+  return s.lockBasePath;
 }
 
 /**
@@ -299,7 +393,11 @@ function lockBase(): string {
  *
  * Returns true if a remote session was found and signaled, false otherwise.
  */
-export function stopAutoRemote(projectRoot: string): { found: boolean; pid?: number; error?: string } {
+export function stopAutoRemote(projectRoot: string): {
+  found: boolean;
+  pid?: number;
+  error?: string;
+} {
   const lock = readCrashLock(projectRoot);
   if (!lock) return { found: false };
 
@@ -340,19 +438,20 @@ function clearUnitTimeout(): void {
     s.continueHereHandle = null;
   }
   clearInFlightTools();
-  clearDispatchGapWatchdog();
-}
-
-function clearDispatchGapWatchdog(): void {
-  if (s.dispatchGapHandle) {
-    clearTimeout(s.dispatchGapHandle);
-    s.dispatchGapHandle = null;
-  }
 }
 
 /** Build snapshot metric opts, enriching with continueHereFired from the runtime record. */
-function buildSnapshotOpts(unitType: string, unitId: string): { continueHereFired?: boolean; promptCharCount?: number; baselineCharCount?: number } & Record<string, unknown> {
-  const runtime = s.currentUnit ? readUnitRuntimeRecord(s.basePath, unitType, unitId) : null;
+function buildSnapshotOpts(
+  unitType: string,
+  unitId: string,
+): {
+  continueHereFired?: boolean;
+  promptCharCount?: number;
+  baselineCharCount?: number;
+} & Record<string, unknown> {
+  const runtime = s.currentUnit
+    ? readUnitRuntimeRecord(s.basePath, unitType, unitId)
+    : null;
   return {
     promptCharCount: s.lastPromptCharCount,
     baselineCharCount: s.lastBaselineCharCount,
@@ -361,144 +460,45 @@ function buildSnapshotOpts(unitType: string, unitId: string): { continueHereFire
   };
 }
 
-// ─── Extracted Merge Helper ───────────────────────────────────────────────
-
-/**
- * Attempt to merge the current milestone branch to main.
- * Handles both worktree and branch isolation modes with a single code path.
- * Returns true if merge succeeded, false on error (non-fatal, logged).
- *
- * Extracted from 4 duplicate merge blocks in dispatchNextUnit to eliminate
- * the bug factory where fixing one copy didn't fix the others (#1308).
- */
-function tryMergeMilestone(ctx: ExtensionContext, milestoneId: string, mode: "transition" | "complete"): boolean {
-  const isolationMode = getIsolationMode();
-
-  // Worktree merge path
-  if (isInAutoWorktree(s.basePath) && s.originalBasePath) {
-    try {
-      const roadmapPath = resolveMilestoneFile(s.originalBasePath, milestoneId, "ROADMAP");
-      if (!roadmapPath) {
-        teardownAutoWorktree(s.originalBasePath, milestoneId);
-        ctx.ui.notify(`Exited worktree for ${milestoneId} (no roadmap for merge).`, "info");
-        return false;
-      }
-      const roadmapContent = readFileSync(roadmapPath, "utf-8");
-      const mergeResult = mergeMilestoneToMain(s.originalBasePath, milestoneId, roadmapContent);
-      s.basePath = s.originalBasePath;
-      s.gitService = createGitService(s.basePath);
-      ctx.ui.notify(
-        `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-        "info",
-      );
-      return true;
-    } catch (err) {
-      ctx.ui.notify(
-        `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
-        "warning",
-      );
-      if (s.originalBasePath) {
-        s.basePath = s.originalBasePath;
-        try { process.chdir(s.basePath); } catch { /* best-effort */ }
-      }
-      return false;
-    }
-  }
-
-  // Branch-mode merge path
-  if (isolationMode === "branch") {
-    try {
-      const currentBranch = getCurrentBranch(s.basePath);
-      const milestoneBranch = autoWorktreeBranch(milestoneId);
-      if (currentBranch === milestoneBranch) {
-        const roadmapPath = resolveMilestoneFile(s.basePath, milestoneId, "ROADMAP");
-        if (roadmapPath) {
-          const roadmapContent = readFileSync(roadmapPath, "utf-8");
-          const mergeResult = mergeMilestoneToMain(s.basePath, milestoneId, roadmapContent);
-          s.gitService = createGitService(s.basePath);
-          ctx.ui.notify(
-            `Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
-            "info",
-          );
-          return true;
-        }
-      }
-    } catch (err) {
-      ctx.ui.notify(
-        `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
-        "warning",
-      );
-    }
-  }
-
-  return false;
-}
-
-/**
- * Start a watchdog that fires if no new unit is dispatched within DISPATCH_GAP_TIMEOUT_MS
- * after handleAgentEnd completes. This catches the case where the dispatch chain silently
- * breaks (e.g., unhandled exception in dispatchNextUnit) and auto-mode is left s.active but idle.
- *
- * The watchdog is cleared on the next successful unit dispatch (clearUnitTimeout is called
- * at the start of handleAgentEnd, which calls clearDispatchGapWatchdog).
- */
-function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void {
-  clearDispatchGapWatchdog();
-  s.dispatchGapHandle = setTimeout(async () => {
-    s.dispatchGapHandle = null;
-    if (!s.active || !s.cmdCtx) return;
-
-    if (s.verbose) {
-      ctx.ui.notify(
-        "Dispatch gap detected — re-evaluating state.",
-        "info",
-      );
-    }
-
-    try {
-      await dispatchNextUnit(ctx, pi);
-    } catch (retryErr) {
-      const message = getErrorMessage(retryErr);
-      await stopAuto(ctx, pi, `Dispatch gap recovery failed: ${message}`);
-      return;
-    }
-
-    if (s.active && !s.unitTimeoutHandle && !s.wrapupWarningHandle) {
-      await stopAuto(ctx, pi, "Stalled — no dispatchable unit after retry");
-    }
-  }, DISPATCH_GAP_TIMEOUT_MS);
+function handleLostSessionLock(ctx?: ExtensionContext): void {
+  debugLog("session-lock-lost", { lockBase: lockBase() });
+  s.active = false;
+  s.paused = false;
+  clearUnitTimeout();
+  deregisterSigtermHandler();
+  ctx?.ui.notify(
+    "Session lock lost — another GSD process appears to have taken over. Stopping gracefully.",
+    "error",
+  );
+  ctx?.ui.setStatus("gsd-auto", undefined);
+  ctx?.ui.setWidget("gsd-progress", undefined);
+  ctx?.ui.setFooter(undefined);
 }
 
-export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason?: string): Promise<void> {
+export async function stopAuto(
+  ctx?: ExtensionContext,
+  pi?: ExtensionAPI,
+  reason?: string,
+): Promise<void> {
   if (!s.active && !s.paused) return;
   const reasonSuffix = reason ? ` — ${reason}` : "";
   clearUnitTimeout();
-  if (lockBase()) {
-    releaseSessionLock(lockBase());
-    clearLock(lockBase());
-  }
+  if (lockBase()) clearLock(lockBase());
+  if (lockBase()) releaseSessionLock(lockBase());
   clearSkillSnapshot();
   resetSkillTelemetry();
-  s.dispatching = false;
-  s.skipDepth = 0;
 
   // Remove SIGTERM handler registered at auto-mode start
   deregisterSigtermHandler();
 
   // ── Auto-worktree: exit worktree and reset s.basePath on stop ──
-  if (s.currentMilestoneId && isInAutoWorktree(s.basePath)) {
-    try {
-      try { autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId); } catch (e) { debugLog("stop-auto-commit-failed", { error: getErrorMessage(e) }); }
-      teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId, { preserveBranch: true });
-      s.basePath = s.originalBasePath;
-      s.gitService = createGitService(s.basePath);
-      ctx?.ui.notify("Exited auto-worktree (branch preserved for resume).", "info");
-    } catch (err) {
-      ctx?.ui.notify(
-        `Auto-worktree teardown failed: ${getErrorMessage(err)}`,
-        "warning",
-      );
-    }
+  if (s.currentMilestoneId) {
+    const notifyCtx = ctx
+      ? { notify: ctx.ui.notify.bind(ctx.ui) }
+      : { notify: () => {} };
+    buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
+      preserveBranch: true,
+    });
   }
 
   // ── DB cleanup: close the SQLite connection ──
@@ -506,12 +506,20 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
     try {
       const { closeDatabase } = await import("./gsd-db.js");
       closeDatabase();
-    } catch (e) { debugLog("db-close-failed", { error: getErrorMessage(e) }); }
+    } catch (e) {
+      debugLog("db-close-failed", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
   }
 
   if (s.originalBasePath) {
     s.basePath = s.originalBasePath;
-    try { process.chdir(s.basePath); } catch { /* best-effort */ }
+    try {
+      process.chdir(s.basePath);
+    } catch {
+      /* best-effort */
+    }
   }
 
   const ledger = getLedger();
@@ -526,7 +534,13 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   }
 
   if (s.basePath) {
-    try { await rebuildState(s.basePath); } catch (e) { debugLog("stop-rebuild-state-failed", { error: getErrorMessage(e) }); }
+    try {
+      await rebuildState(s.basePath);
+    } catch (e) {
+      debugLog("stop-rebuild-state-failed", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
   }
 
   if (isDebugEnabled()) {
@@ -545,7 +559,6 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   s.stepMode = false;
   s.unitDispatchCount.clear();
   s.unitRecoveryCount.clear();
-  s.unitConsecutiveSkips.clear();
   clearInFlightTools();
   s.lastBudgetAlertLevel = 0;
   s.lastStateRebuildAt = 0;
@@ -559,18 +572,19 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   clearSliceProgressCache();
   clearActivityLogState();
   resetProactiveHealing();
-  s.recentlyEvictedKeys.clear();
   s.pendingCrashRecovery = null;
   s.pendingVerificationRetry = null;
   s.verificationRetryCount.clear();
   s.pausedSessionFile = null;
-  s.handlingAgentEnd = false;
   ctx?.ui.setStatus("gsd-auto", undefined);
   ctx?.ui.setWidget("gsd-progress", undefined);
   ctx?.ui.setFooter(undefined);
 
   if (pi && ctx && s.originalModelId && s.originalModelProvider) {
-    const original = ctx.modelRegistry.find(s.originalModelProvider, s.originalModelId);
+    const original = ctx.modelRegistry.find(
+      s.originalModelProvider,
+      s.originalModelId,
+    );
     if (original) await pi.setModel(original);
     s.originalModelId = null;
     s.originalModelProvider = null;
@@ -584,16 +598,17 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
  * The user can interact with the agent, then `/gsd auto` resumes
  * from disk state. Called when the user presses Escape during auto-mode.
  */
-export async function pauseAuto(ctx?: ExtensionContext, _pi?: ExtensionAPI): Promise<void> {
+export async function pauseAuto(
+  ctx?: ExtensionContext,
+  _pi?: ExtensionAPI,
+): Promise<void> {
   if (!s.active) return;
   clearUnitTimeout();
 
   s.pausedSessionFile = ctx?.sessionManager?.getSessionFile() ?? null;
 
-  if (lockBase()) {
-    releaseSessionLock(lockBase());
-    clearLock(lockBase());
-  }
+  if (lockBase()) clearLock(lockBase());
+  if (lockBase()) releaseSessionLock(lockBase());
 
   deregisterSigtermHandler();
 
@@ -611,6 +626,158 @@ export async function pauseAuto(ctx?: ExtensionContext, _pi?: ExtensionAPI): Pro
   );
 }
 
+/**
+ * Build a WorktreeResolverDeps from auto.ts private scope.
+ * Shared by buildResolver() and buildLoopDeps().
+ */
+function buildResolverDeps(): WorktreeResolverDeps {
+  return {
+    isInAutoWorktree,
+    shouldUseWorktreeIsolation,
+    getIsolationMode,
+    mergeMilestoneToMain,
+    syncWorktreeStateBack,
+    teardownAutoWorktree,
+    createAutoWorktree,
+    enterAutoWorktree,
+    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());
+}
+
+/**
+ * Build the LoopDeps object from auto.ts private scope.
+ * This bundles all private functions that autoLoop needs without exporting them.
+ */
+function buildLoopDeps(): LoopDeps {
+  return {
+    lockBase,
+    buildSnapshotOpts,
+    stopAuto,
+    pauseAuto,
+    clearUnitTimeout,
+    updateProgressWidget,
+
+    // State and cache
+    invalidateAllCaches,
+    deriveState,
+    loadEffectiveGSDPreferences,
+
+    // Pre-dispatch health gate
+    preDispatchHealthGate,
+
+    // Worktree sync
+    syncProjectRootToWorktree,
+
+    // Resource version guard
+    checkResourcesStale,
+
+    // Session lock
+    validateSessionLock,
+    updateSessionLock,
+    handleLostSessionLock,
+
+    // Milestone transition
+    sendDesktopNotification,
+    setActiveMilestoneId,
+    pruneQueueOrder,
+    isInAutoWorktree,
+    shouldUseWorktreeIsolation,
+    mergeMilestoneToMain,
+    teardownAutoWorktree,
+    createAutoWorktree,
+    captureIntegrationBranch,
+    getIsolationMode,
+    getCurrentBranch,
+    autoWorktreeBranch,
+    resolveMilestoneFile,
+    reconcileMergeState,
+
+    // Budget/context/secrets
+    getLedger,
+    getProjectTotals,
+    formatCost,
+    getBudgetAlertLevel,
+    getNewBudgetAlertLevel,
+    getBudgetEnforcementAction,
+    getManifestStatus,
+    collectSecretsFromManifest,
+
+    // Dispatch
+    resolveDispatch,
+    runPreDispatchHooks,
+    getPriorSliceCompletionBlocker,
+    getMainBranch,
+    collectObservabilityWarnings: _collectObservabilityWarnings,
+    buildObservabilityRepairBlock,
+
+    // Unit closeout + runtime records
+    closeoutUnit,
+    verifyExpectedArtifact,
+    clearUnitRuntimeRecord,
+    writeUnitRuntimeRecord,
+    recordOutcome,
+    writeLock,
+    captureAvailableSkills,
+    ensurePreconditions,
+    updateSliceProgressCache,
+
+    // Model selection + supervision
+    selectAndApplyModel,
+    startUnitSupervision,
+
+    // Prompt helpers
+    getDeepDiagnostic,
+    isDbAvailable,
+    reorderForCaching,
+
+    // Filesystem
+    existsSync,
+    readFileSync: (path: string, encoding: string) =>
+      readFileSync(path, encoding as BufferEncoding),
+    atomicWriteSync,
+
+    // Git
+    GitServiceImpl: GitServiceImpl as unknown as LoopDeps["GitServiceImpl"],
+
+    // WorktreeResolver
+    resolver: buildResolver(),
+
+    // Post-unit processing
+    postUnitPreVerification,
+    runPostUnitVerification,
+    postUnitPostVerification,
+
+    // Session manager
+    getSessionFile: (ctx: ExtensionContext) => {
+      try {
+        return ctx.sessionManager?.getSessionFile() ?? "";
+      } catch {
+        return "";
+      }
+    },
+  } as unknown as LoopDeps;
+}
 
 export async function startAuto(
   ctx: ExtensionCommandContext,
@@ -626,13 +793,9 @@ export async function startAuto(
 
   // If resuming from paused state, just re-activate and dispatch next unit.
   if (s.paused) {
-    // Re-acquire session lock before resuming
     const resumeLock = acquireSessionLock(base);
     if (!resumeLock.acquired) {
-      ctx.ui.notify(
-        `Cannot resume: ${resumeLock.reason}`,
-        "error",
-      );
+      ctx.ui.notify(`Cannot resume: ${resumeLock.reason}`, "error");
       return;
     }
 
@@ -644,47 +807,52 @@ export async function startAuto(
     s.basePath = base;
     s.unitDispatchCount.clear();
     s.unitLifetimeDispatches.clear();
-    s.unitConsecutiveSkips.clear();
     if (!getLedger()) initMetrics(base);
     if (s.currentMilestoneId) setActiveMilestoneId(base, s.currentMilestoneId);
 
     // ── Auto-worktree: re-enter worktree on resume ──
-    if (s.currentMilestoneId && shouldUseWorktreeIsolation() && s.originalBasePath && !isInAutoWorktree(s.basePath) && !detectWorktreeName(s.basePath) && !detectWorktreeName(s.originalBasePath)) {
-      try {
-        const existingWtPath = getAutoWorktreePath(s.originalBasePath, s.currentMilestoneId);
-        if (existingWtPath) {
-          const wtPath = enterAutoWorktree(s.originalBasePath, s.currentMilestoneId);
-          s.basePath = wtPath;
-          s.gitService = createGitService(s.basePath);
-          ctx.ui.notify(`Re-entered auto-worktree at ${wtPath}`, "info");
-        } else {
-          const wtPath = createAutoWorktree(s.originalBasePath, s.currentMilestoneId);
-          s.basePath = wtPath;
-          s.gitService = createGitService(s.basePath);
-          ctx.ui.notify(`Recreated auto-worktree at ${wtPath}`, "info");
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Auto-worktree re-entry failed: ${getErrorMessage(err)}. Continuing at current path.`,
-          "warning",
-        );
-      }
+    if (
+      s.currentMilestoneId &&
+      shouldUseWorktreeIsolation() &&
+      s.originalBasePath &&
+      !isInAutoWorktree(s.basePath) &&
+      !detectWorktreeName(s.basePath) &&
+      !detectWorktreeName(s.originalBasePath)
+    ) {
+      buildResolver().enterMilestone(s.currentMilestoneId, {
+        notify: ctx.ui.notify.bind(ctx.ui),
+      });
     }
 
     registerSigtermHandler(lockBase());
 
     ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
     ctx.ui.setFooter(hideFooter);
-    ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
+    ctx.ui.notify(
+      s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.",
+      "info",
+    );
     restoreHookState(s.basePath);
-    try { await rebuildState(s.basePath); } catch (e) { debugLog("resume-rebuild-state-failed", { error: getErrorMessage(e) }); }
+    try {
+      await rebuildState(s.basePath);
+    } catch (e) {
+      debugLog("resume-rebuild-state-failed", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
     try {
       const report = await runGSDDoctor(s.basePath, { fix: true });
       if (report.fixesApplied.length > 0) {
-        ctx.ui.notify(`Resume: applied ${report.fixesApplied.length} fix(es) to state.`, "info");
+        ctx.ui.notify(
+          `Resume: applied ${report.fixesApplied.length} fix(es) to state.`,
+          "info",
+        );
       }
-    } catch (e) { debugLog("resume-doctor-failed", { error: getErrorMessage(e) }); }
-    await selfHealRuntimeRecords(s.basePath, ctx, s.completedKeySet);
+    } catch (e) {
+      debugLog("resume-doctor-failed", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
     invalidateAllCaches();
 
     if (s.pausedSessionFile) {
@@ -692,7 +860,8 @@ export async function startAuto(
       const recovery = synthesizeCrashRecovery(
         s.basePath,
         s.currentUnit?.type ?? "unknown",
-        s.currentUnit?.id ?? "unknown", s.pausedSessionFile ?? undefined,
+        s.currentUnit?.id ?? "unknown",
+        s.pausedSessionFile ?? undefined,
         activityDir,
       );
       if (recovery && recovery.trace.toolCallCount > 0) {
@@ -705,42 +874,20 @@ export async function startAuto(
       s.pausedSessionFile = null;
     }
 
-    // If resuming from a secrets pause, re-collect before dispatching (#1146)
-    if (s.pausedForSecrets && s.currentMilestoneId) {
-      try {
-        const manifestStatus = await getManifestStatus(s.basePath, s.currentMilestoneId);
-        if (manifestStatus && manifestStatus.pending.length > 0) {
-          const result = await collectSecretsFromManifest(s.basePath, s.currentMilestoneId, ctx);
-          if (result && result.applied.length > 0) {
-            ctx.ui.notify(
-              `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
-              "info",
-            );
-          } else if (result && result.applied.length === 0 && result.skipped.length > 0) {
-            // All keys were skipped — still pending, re-pause
-            s.paused = true;
-            s.active = false;
-            ctx.ui.notify(
-              `All env variables were skipped. Auto-mode remains paused.\nCollect them with /gsd secrets, then resume with /gsd auto.`,
-              "warning",
-            );
-            ctx.ui.setStatus("gsd-auto", "paused");
-            return;
-          }
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Secrets check error: ${getErrorMessage(err)}. Continuing without secrets.`,
-          "warning",
-        );
-      }
-      s.pausedForSecrets = false;
-    }
-
-    updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
-    writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
+    updateSessionLock(
+      lockBase(),
+      "resuming",
+      s.currentMilestoneId ?? "unknown",
+      s.completedUnits.length,
+    );
+    writeLock(
+      lockBase(),
+      "resuming",
+      s.currentMilestoneId ?? "unknown",
+      s.completedUnits.length,
+    );
 
-    await dispatchNextUnit(ctx, pi);
+    await autoLoop(ctx, pi, s, buildLoopDeps());
     return;
   }
 
@@ -749,210 +896,45 @@ export async function startAuto(
     shouldUseWorktreeIsolation,
     registerSigtermHandler,
     lockBase,
+    buildResolver,
   };
 
-  const ready = await bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, bootstrapDeps);
-  if (!ready) return;
-
-  // Dispatch the first unit
-  await dispatchNextUnit(ctx, pi);
-}
-
-// ─── Agent End Handler ────────────────────────────────────────────────────────
-
-/** Guard against concurrent handleAgentEnd execution. */
-
-export async function handleAgentEnd(
-  ctx: ExtensionContext,
-  pi: ExtensionAPI,
-): Promise<void> {
-  if (!s.active || !s.cmdCtx) return;
-  if (s.handlingAgentEnd) {
-    // Another agent_end arrived while we're still processing the previous one.
-    // This happens when a unit dispatched inside handleAgentEnd (e.g. via hooks,
-    // triage, or quick-task early-dispatch paths) completes before the outer
-    // handleAgentEnd returns. Queue a retry so the completed unit's agent_end
-    // is not silently dropped (#1072).
-    s.pendingAgentEndRetry = true;
-    return;
-  }
-  s.handlingAgentEnd = true;
-
-  try {
-
-  // Unit completed — clear its timeout
-  clearUnitTimeout();
-
-  // ── Pre-verification processing (commit, doctor, state rebuild, etc.) ──
-  const postUnitCtx: PostUnitContext = {
+  const ready = await bootstrapAutoSession(
     s,
     ctx,
     pi,
-    buildSnapshotOpts,
-    lockBase,
-    stopAuto,
-    pauseAuto,
-    updateProgressWidget,
-  };
-
-  const preResult = await postUnitPreVerification(postUnitCtx);
-  if (preResult === "dispatched") return;
-
-  // ── Verification gate: run typecheck/lint/test after execute-task ──
-  const verificationResult = await runPostUnitVerification(
-    { s, ctx, pi },
-    dispatchNextUnit,
-    startDispatchGapWatchdog,
-    pauseAuto,
+    base,
+    verboseMode,
+    requestedStepMode,
+    bootstrapDeps,
   );
-  if (verificationResult === "retry" || verificationResult === "pause") return;
-
-  // ── Post-verification processing (DB dual-write, hooks, triage, quick-tasks) ──
-  const postResult = await postUnitPostVerification(postUnitCtx);
-  if (postResult === "dispatched" || postResult === "stopped") return;
-  if (postResult === "step-wizard") {
-    await showStepWizard(ctx, pi);
-    return;
-  }
-
-  // ── Dispatch with hang detection (#1073) ────────────────────────────────
-  // Start a safety watchdog BEFORE calling dispatchNextUnit. If dispatch
-  // hangs at any await (newSession, model selection, etc.), the gap watchdog
-  // inside handleAgentEnd never fires because we never reach the check.
-  // This pre-dispatch watchdog ensures recovery even when dispatchNextUnit
-  // itself is permanently blocked.
-  const dispatchHangGuard = setTimeout(() => {
-    if (!s.active) return;
-    // dispatchNextUnit has been running for too long — it's likely hung.
-    // Start the gap watchdog which will retry dispatch from scratch.
-    if (!s.unitTimeoutHandle && !s.wrapupWarningHandle) {
-      ctx.ui.notify(
-        `Dispatch hang detected (${DISPATCH_HANG_TIMEOUT_MS / 1000}s without completion). Starting recovery watchdog.`,
-        "warning",
-      );
-      startDispatchGapWatchdog(ctx, pi);
-    }
-  }, DISPATCH_HANG_TIMEOUT_MS);
-
-  try {
-    await dispatchNextUnit(ctx, pi);
-  } catch (dispatchErr) {
-    const message = getErrorMessage(dispatchErr);
-    ctx.ui.notify(
-      `Dispatch error after unit completion: ${message}. Retrying in ${DISPATCH_GAP_TIMEOUT_MS / 1000}s.`,
-      "error",
-    );
-    startDispatchGapWatchdog(ctx, pi);
-    return;
-  } finally {
-    clearTimeout(dispatchHangGuard);
-  }
-
-  if (s.active && !s.unitTimeoutHandle && !s.wrapupWarningHandle) {
-    startDispatchGapWatchdog(ctx, pi);
-  }
+  if (!ready) return;
 
-  } finally {
-    s.handlingAgentEnd = false;
-
-    // If an agent_end event was dropped by the reentrancy guard while we were
-    // processing, re-enter handleAgentEnd on the next microtask. This prevents
-    // the summarizing phase stall (#1072) where a unit dispatched inside
-    // handleAgentEnd (hooks, triage, quick-task) completes before we return,
-    // and its agent_end is silently dropped — leaving auto-mode active but
-    // permanently stalled with no unit running and no watchdog set.
-    if (s.pendingAgentEndRetry) {
-      s.pendingAgentEndRetry = false;
-      // Clear gap watchdog from the previous cycle to prevent concurrent
-      // dispatch when the deferred handleAgentEnd calls dispatchNextUnit (#1272).
-      clearDispatchGapWatchdog();
-      setImmediate(() => {
-        handleAgentEnd(ctx, pi).catch((err) => {
-          const msg = getErrorMessage(err);
-          ctx.ui.notify(`Deferred agent_end retry failed: ${msg}`, "error");
-          pauseAuto(ctx, pi).catch(() => {});
-        });
-      });
-    }
-  }
+  // Dispatch the first unit
+  await autoLoop(ctx, pi, s, buildLoopDeps());
 }
 
-// ─── Step Mode Wizard ─────────────────────────────────────────────────────
+// ─── Agent End Handler ────────────────────────────────────────────────────────
 
 /**
- * Show the step-mode wizard after a unit completes.
+ * Deprecated thin wrapper — kept as export for backward compatibility.
+ * The actual agent_end processing now happens via resolveAgentEnd() in auto-loop.ts,
+ * which is called directly from index.ts. The autoLoop() while loop handles all
+ * post-unit processing (verification, hooks, dispatch) that this function used to do.
+ *
+ * If called by straggler code, it simply resolves the pending promise so the loop
+ * can continue.
  */
-async function showStepWizard(
+export async function handleAgentEnd(
   ctx: ExtensionContext,
   pi: ExtensionAPI,
 ): Promise<void> {
-  if (!s.cmdCtx) return;
-
-  const state = await deriveState(s.basePath);
-  const mid = state.activeMilestone?.id;
-
-  const justFinished = s.currentUnit
-    ? `${unitVerb(s.currentUnit.type)} ${s.currentUnit.id}`
-    : "previous unit";
-
-  if (!mid || state.phase === "complete") {
-    const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
-    if (incomplete.length > 0 && state.phase !== "complete" && state.phase !== "blocked" && state.phase !== "pre-planning") {
-      const ids = incomplete.map(m => m.id).join(", ");
-      const diag = `basePath=${s.basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
-      ctx.ui.notify(`Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`, "error");
-      await stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids})`);
-    } else {
-      await stopAuto(ctx, pi, state.phase === "complete" ? "All work complete" : "No active milestone");
-    }
-    return;
-  }
-
-  const nextDesc = _describeNextUnit(state);
-
-  const choice = await showNextAction(s.cmdCtx, {
-    title: `GSD — ${justFinished} complete`,
-    summary: [
-      `${mid}: ${state.activeMilestone?.title ?? mid}`,
-      ...(state.activeSlice ? [`${state.activeSlice.id}: ${state.activeSlice.title}`] : []),
-    ],
-    actions: [
-      {
-        id: "continue",
-        label: nextDesc.label,
-        description: nextDesc.description,
-        recommended: true,
-      },
-      {
-        id: "auto",
-        label: "Switch to auto",
-        description: "Continue without pausing between steps.",
-      },
-      {
-        id: "status",
-        label: "View status",
-        description: "Open the dashboard.",
-      },
-    ],
-    notYetMessage: "Run /gsd next when ready to continue.",
-  });
-
-  if (choice === "continue") {
-    await dispatchNextUnit(ctx, pi);
-  } else if (choice === "auto") {
-    s.stepMode = false;
-    ctx.ui.setStatus("gsd-auto", "auto");
-    ctx.ui.notify("Switched to auto-mode.", "info");
-    await dispatchNextUnit(ctx, pi);
-  } else if (choice === "status") {
-    const { fireStatusViaCommand } = await import("./commands.js");
-    await fireStatusViaCommand(ctx as ExtensionCommandContext);
-    await showStepWizard(ctx, pi);
-  } else {
-    await pauseAuto(ctx, pi);
-  }
+  if (!s.active || !s.cmdCtx) return;
+  clearUnitTimeout();
+  resolveAgentEnd({ messages: [] });
 }
-
+// describeNextUnit is imported from auto-dashboard.ts and re-exported
+export { describeNextUnit } from "./auto-dashboard.js";
 
 /** Thin wrapper: delegates to auto-dashboard.ts, passing state accessors. */
 function updateProgressWidget(
@@ -962,9 +944,17 @@ function updateProgressWidget(
   state: GSDState,
 ): void {
   const badge = s.currentUnitRouting?.tier
-    ? ({ light: "L", standard: "S", heavy: "H" }[s.currentUnitRouting.tier] ?? undefined)
+    ? ({ light: "L", standard: "S", heavy: "H" }[s.currentUnitRouting.tier] ??
+      undefined)
     : undefined;
-  _updateProgressWidget(ctx, unitType, unitId, state, widgetStateAccessors, badge);
+  _updateProgressWidget(
+    ctx,
+    unitType,
+    unitId,
+    state,
+    widgetStateAccessors,
+    badge,
+  );
 }
 
 /** State accessors for the widget — closures over module globals. */
@@ -976,695 +966,6 @@ const widgetStateAccessors: WidgetStateAccessors = {
   isVerbose: () => s.verbose,
 };
 
-// ─── Core Loop ────────────────────────────────────────────────────────────────
-
-async function dispatchNextUnit(
-  ctx: ExtensionContext,
-  pi: ExtensionAPI,
-): Promise<void> {
-  if (!s.active || !s.cmdCtx) {
-    debugLog(`dispatchNextUnit early return — active=${s.active}, cmdCtx=${!!s.cmdCtx}`);
-    if (s.active && !s.cmdCtx) {
-      ctx.ui.notify("Auto-mode session expired. Run /gsd auto to restart.", "info");
-    }
-    return;
-  }
-
-  // ── Session lock validation: detect if another process has taken over ──
-  if (lockBase() && !validateSessionLock(lockBase())) {
-    debugLog("dispatchNextUnit session-lock-lost — another process may have taken over");
-    ctx.ui.notify(
-      "Session lock lost — another GSD process appears to have taken over. Stopping gracefully.",
-      "error",
-    );
-    // Don't call stopAuto here to avoid releasing the lock we don't own
-    s.active = false;
-    s.paused = false;
-    clearUnitTimeout();
-    deregisterSigtermHandler();
-    ctx.ui.setStatus("gsd-auto", undefined);
-    ctx.ui.setWidget("gsd-progress", undefined);
-    ctx.ui.setFooter(undefined);
-    return;
-  }
-
-  // Reentrancy guard — unconditional to prevent concurrent dispatch from
-  // gap watchdog or pendingAgentEndRetry during skip chains (#1272).
-  // Previously the guard was bypassed when skipDepth > 0, but the recursive
-  // skip chain's inner finally block resets s.dispatching = false before the
-  // outer call's finally runs, opening a window for concurrent entry.
-  if (s.dispatching) {
-    debugLog("dispatchNextUnit reentrancy guard — another dispatch in progress, bailing");
-    return;
-  }
-  s.dispatching = true;
-  try {
-  // Recursion depth guard
-  if (s.skipDepth > MAX_SKIP_DEPTH) {
-    s.skipDepth = 0;
-    ctx.ui.notify(`Skipped ${MAX_SKIP_DEPTH}+ completed units. Yielding to UI before continuing.`, "info");
-    await new Promise(r => setTimeout(r, 200));
-  }
-
-  // Resource version guard
-  const staleMsg = checkResourcesStale(s.resourceVersionOnStart);
-  if (staleMsg) {
-    await stopAuto(ctx, pi, staleMsg);
-    return;
-  }
-
-  invalidateAllCaches();
-  s.lastPromptCharCount = undefined;
-  s.lastBaselineCharCount = undefined;
-
-  // ── Pre-dispatch health gate ──
-  try {
-    const healthGate = await preDispatchHealthGate(s.basePath);
-    if (healthGate.fixesApplied.length > 0) {
-      ctx.ui.notify(`Pre-dispatch: ${healthGate.fixesApplied.join(", ")}`, "info");
-    }
-    if (!healthGate.proceed) {
-      ctx.ui.notify(healthGate.reason ?? "Pre-dispatch health check failed.", "error");
-      await pauseAuto(ctx, pi);
-      return;
-    }
-  } catch {
-    // Non-fatal
-  }
-
-  const stopDeriveTimer = debugTime("derive-state");
-  let state = await deriveState(s.basePath);
-  stopDeriveTimer({
-    phase: state.phase,
-    milestone: state.activeMilestone?.id,
-    slice: state.activeSlice?.id,
-    task: state.activeTask?.id,
-  });
-  let mid = state.activeMilestone?.id;
-  let midTitle = state.activeMilestone?.title;
-
-  // Detect milestone transition
-  if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) {
-    ctx.ui.notify(
-      `Milestone ${ s.currentMilestoneId } complete. Advancing to ${mid}: ${midTitle}.`,
-      "info",
-    );
-    sendDesktopNotification("GSD", `Milestone ${s.currentMilestoneId} complete!`, "success", "milestone");
-    const vizPrefs = loadEffectiveGSDPreferences()?.preferences;
-    if (vizPrefs?.auto_visualize) {
-      ctx.ui.notify("Run /gsd visualize to see progress overview.", "info");
-    }
-    if (vizPrefs?.auto_report !== false) {
-      try {
-        const { loadVisualizerData } = await import("./visualizer-data.js");
-        const { generateHtmlReport } = await import("./export-html.js");
-        const { writeReportSnapshot, reportsDir } = await import("./reports.js");
-        const { basename } = await import("node:path");
-        const snapData = await loadVisualizerData(s.basePath);
-        const completedMs = snapData.milestones.find(m => m.id === s.currentMilestoneId);
-        const msTitle = completedMs?.title ?? s.currentMilestoneId;
-        const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
-        const projName = basename(s.basePath);
-        const doneSlices = snapData.milestones.reduce((s, m) => s + m.slices.filter(sl => sl.done).length, 0);
-        const totalSlices = snapData.milestones.reduce((s, m) => s + m.slices.length, 0);
-        const outPath = writeReportSnapshot({ basePath: s.basePath,
-          html: generateHtmlReport(snapData, {
-            projectName: projName,
-            projectPath: s.basePath,
-            gsdVersion,
-            milestoneId: s.currentMilestoneId,
-            indexRelPath: "index.html",
-          }),
-          milestoneId: s.currentMilestoneId,
-          milestoneTitle: msTitle,
-          kind: "milestone",
-          projectName: projName,
-          projectPath: s.basePath,
-          gsdVersion,
-          totalCost: snapData.totals?.cost ?? 0,
-          totalTokens: snapData.totals?.tokens.total ?? 0,
-          totalDuration: snapData.totals?.duration ?? 0,
-          doneSlices,
-          totalSlices,
-          doneMilestones: snapData.milestones.filter(m => m.status === "complete").length,
-          totalMilestones: snapData.milestones.length,
-          phase: snapData.phase,
-        });
-        ctx.ui.notify(
-          `Report saved: .gsd/reports/${basename(outPath)} — open index.html to browse progression.`,
-          "info",
-        );
-      } catch (err) {
-        ctx.ui.notify(
-          `Report generation failed: ${getErrorMessage(err)}`,
-          "warning",
-        );
-      }
-    }
-    // Reset stuck detection for new milestone
-    s.unitDispatchCount.clear();
-    s.unitRecoveryCount.clear();
-  s.unitConsecutiveSkips.clear();
-    s.unitLifetimeDispatches.clear();
-    try {
-      const file = completedKeysPath(s.basePath);
-      if (existsSync(file)) {
-        atomicWriteSync(file, JSON.stringify([]));
-      }
-      s.completedKeySet.clear();
-    } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
-
-    // ── Worktree lifecycle on milestone transition (#616) ──
-    if ((isInAutoWorktree(s.basePath) || getIsolationMode() === "branch") && shouldUseWorktreeIsolation()) {
-      tryMergeMilestone(ctx, s.currentMilestoneId, "transition");
-
-      // Reset to project root and re-derive state for the new milestone
-      if (s.originalBasePath) {
-        s.basePath = s.originalBasePath;
-        s.gitService = createGitService(s.basePath);
-      }
-      invalidateAllCaches();
-
-      state = await deriveState(s.basePath);
-      mid = state.activeMilestone?.id;
-      midTitle = state.activeMilestone?.title;
-
-      if (mid) {
-        captureIntegrationBranch(s.basePath, mid);
-        try {
-          const wtPath = createAutoWorktree(s.basePath, mid);
-          s.basePath = wtPath;
-          s.gitService = createGitService(s.basePath);
-          ctx.ui.notify(`Created auto-worktree for ${mid} at ${wtPath}`, "info");
-        } catch (err) {
-          ctx.ui.notify(
-            `Auto-worktree creation for ${mid} failed: ${getErrorMessage(err)}. Continuing in project root.`,
-            "warning",
-          );
-        }
-      }
-    } else {
-      if (getIsolationMode() !== "none") {
-        captureIntegrationBranch(s.originalBasePath || s.basePath, mid);
-      }
-    }
-
-    const pendingIds = (state.registry ?? [])
-      .filter(m => m.status !== "complete")
-      .map(m => m.id);
-    pruneQueueOrder(s.basePath, pendingIds);
-  }
-  if (mid) {
-    s.currentMilestoneId = mid;
-    setActiveMilestoneId(s.basePath, mid);
-  }
-
-  if (!mid) {
-    if (s.currentUnit) {
-      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-    }
-
-    const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
-    if (incomplete.length === 0) {
-      // Genuinely all complete (parked milestones excluded) — merge milestone branch to main before stopping (#962)
-      if (s.currentMilestoneId) {
-        tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
-      }
-      sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
-      await stopAuto(ctx, pi, "All milestones complete");
-    } else if (state.phase === "blocked") {
-      const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-      await stopAuto(ctx, pi, blockerMsg);
-      ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-      sendDesktopNotification("GSD", blockerMsg, "error", "attention");
-    } else {
-      const ids = incomplete.map(m => m.id).join(", ");
-      const diag = `basePath=${s.basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
-      ctx.ui.notify(`Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`, "error");
-      await stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids}), see diagnostic above`);
-    }
-    return;
-  }
-
-  if (!midTitle) {
-    midTitle = mid;
-    ctx.ui.notify(`Milestone ${mid} has no title in roadmap — using ID as fallback.`, "warning");
-  }
-
-  // ── Mid-merge safety check ──
-  if (reconcileMergeState(s.basePath, ctx)) {
-    invalidateAllCaches();
-    state = await deriveState(s.basePath);
-    mid = state.activeMilestone?.id;
-    midTitle = state.activeMilestone?.title;
-  }
-
-  if (!mid || !midTitle) {
-    if (s.currentUnit) {
-      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-    }
-    const noMilestoneReason = !mid
-      ? "No active milestone after merge reconciliation"
-      : `Milestone ${mid} has no title after reconciliation`;
-    await stopAuto(ctx, pi, noMilestoneReason);
-    return;
-  }
-
-  // Determine next unit
-  let unitType: string;
-  let unitId: string;
-  let prompt: string;
-
-  if (state.phase === "complete") {
-    if (s.currentUnit) {
-      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-    }
-    try {
-      const file = completedKeysPath(s.basePath);
-      if (existsSync(file)) {
-        atomicWriteSync(file, JSON.stringify([]));
-      }
-      s.completedKeySet.clear();
-    } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
-    // ── Milestone merge ──
-    if (s.currentMilestoneId) {
-      tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
-    }
-    sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
-    await stopAuto(ctx, pi, `Milestone ${mid} complete`);
-    return;
-  }
-
-  if (state.phase === "blocked") {
-    if (s.currentUnit) {
-      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-    }
-    const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-    await stopAuto(ctx, pi, blockerMsg);
-    ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-    sendDesktopNotification("GSD", blockerMsg, "error", "attention");
-    return;
-  }
-
-  // Budget ceiling guard, context window guard, secrets gate, dispatch table
-  const prefs = loadEffectiveGSDPreferences()?.preferences;
-
-  const budgetCeiling = prefs?.budget_ceiling;
-  if (budgetCeiling !== undefined && budgetCeiling > 0) {
-    const currentLedger = getLedger();
-    const totalCost = currentLedger ? getProjectTotals(currentLedger.units).cost : 0;
-    const budgetPct = totalCost / budgetCeiling;
-    const budgetAlertLevel = getBudgetAlertLevel(budgetPct);
-    const newBudgetAlertLevel = getNewBudgetAlertLevel(s.lastBudgetAlertLevel, budgetPct);
-    const enforcement = prefs?.budget_enforcement ?? "pause";
-
-    const budgetEnforcementAction = getBudgetEnforcementAction(enforcement, budgetPct);
-
-    if (newBudgetAlertLevel === 100 && budgetEnforcementAction !== "none") {
-      const msg = `Budget ceiling ${formatCost(budgetCeiling)} reached (spent ${formatCost(totalCost)}).`;
-      s.lastBudgetAlertLevel = newBudgetAlertLevel;
-      if (budgetEnforcementAction === "halt") {
-        sendDesktopNotification("GSD", msg, "error", "budget");
-        await stopAuto(ctx, pi, "Budget ceiling reached");
-        return;
-      }
-      if (budgetEnforcementAction === "pause") {
-        ctx.ui.notify(`${msg} Pausing auto-mode — /gsd auto to override and continue.`, "warning");
-        sendDesktopNotification("GSD", msg, "warning", "budget");
-        await pauseAuto(ctx, pi);
-        return;
-      }
-      ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
-      sendDesktopNotification("GSD", msg, "warning", "budget");
-    } else if (newBudgetAlertLevel === 90) {
-      s.lastBudgetAlertLevel = newBudgetAlertLevel;
-      ctx.ui.notify(`Budget 90%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning");
-      sendDesktopNotification("GSD", `Budget 90%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning", "budget");
-    } else if (newBudgetAlertLevel === 80) {
-      s.lastBudgetAlertLevel = newBudgetAlertLevel;
-      ctx.ui.notify(`Approaching budget ceiling — 80%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning");
-      sendDesktopNotification("GSD", `Approaching budget ceiling — 80%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning", "budget");
-    } else if (newBudgetAlertLevel === 75) {
-      s.lastBudgetAlertLevel = newBudgetAlertLevel;
-      ctx.ui.notify(`Budget 75%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "info");
-      sendDesktopNotification("GSD", `Budget 75%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "info", "budget");
-    } else if (budgetAlertLevel === 0) {
-      s.lastBudgetAlertLevel = 0;
-    }
-  } else {
-    s.lastBudgetAlertLevel = 0;
-  }
-
-  const contextThreshold = prefs?.context_pause_threshold ?? 0;
-  if (contextThreshold > 0 && s.cmdCtx) {
-    const contextUsage = s.cmdCtx.getContextUsage();
-    if (contextUsage && contextUsage.percent !== null && contextUsage.percent >= contextThreshold) {
-      const msg = `Context window at ${contextUsage.percent}% (threshold: ${contextThreshold}%). Pausing to prevent truncated output.`;
-      ctx.ui.notify(`${msg} Run /gsd auto to continue (will start fresh session).`, "warning");
-      sendDesktopNotification("GSD", `Context ${contextUsage.percent}% — paused`, "warning", "attention");
-      await pauseAuto(ctx, pi);
-      return;
-    }
-  }
-
-  // Secrets re-check gate
-  const runSecretsGate = async () => {
-    try {
-      const manifestStatus = await getManifestStatus(s.basePath, mid);
-      if (manifestStatus && manifestStatus.pending.length > 0) {
-        const result = await collectSecretsFromManifest(s.basePath, mid, ctx);
-        if (result && result.applied && result.skipped && result.existingSkipped) {
-          ctx.ui.notify(
-            `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
-            "info",
-          );
-        } else {
-          ctx.ui.notify("Secrets collection skipped.", "info");
-        }
-      }
-    } catch (err) {
-      ctx.ui.notify(
-        `Secrets collection error: ${getErrorMessage(err)}. Continuing with next task.`,
-        "warning",
-      );
-    }
-  };
-
-  await runSecretsGate();
-
-  // ── Interactive discussion gate ──
-  // If the active milestone needs discussion (has CONTEXT-DRAFT.md but no roadmap),
-  // stop auto-mode and route to the interactive discussion flow. The guided-flow
-  // handles needs-discussion correctly — it just needs to be called instead of
-  // letting the dispatch table fire "needs-discussion → stop" (#1170).
-  if (state.phase === "needs-discussion") {
-    if (s.currentUnit) {
-      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-    }
-    const cmdCtx = s.cmdCtx!;
-    const basePath = s.basePath;
-    await stopAuto(ctx, pi, `${mid}: ${midTitle} needs discussion before planning.`);
-    const { showSmartEntry } = await import("./guided-flow.js");
-    await showSmartEntry(cmdCtx, pi, basePath);
-    return;
-  }
-
-  // ── Dispatch table ──
-  const dispatchResult = await resolveDispatch({ basePath: s.basePath, mid, midTitle: midTitle!, state, prefs,
-  });
-
-  if (dispatchResult.action === "stop") {
-    if (s.currentUnit) {
-      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-    }
-    await stopAuto(ctx, pi, dispatchResult.reason);
-    return;
-  }
-
-  if (dispatchResult.action !== "dispatch") {
-    // Defer re-dispatch to next microtask so s.dispatching is released first,
-    // preventing reentrancy guard bypass during concurrent entry (#1272).
-    setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
-      ctx.ui.notify(`Deferred dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-      pauseAuto(ctx, pi).catch(() => {});
-    }));
-    return;
-  }
-
-  unitType = dispatchResult.unitType;
-  unitId = dispatchResult.unitId;
-  prompt = dispatchResult.prompt;
-
-  // ── Pre-dispatch hooks ──
-  const preDispatchResult = runPreDispatchHooks(unitType, unitId, prompt, s.basePath);
-  if (preDispatchResult.firedHooks.length > 0) {
-    ctx.ui.notify(
-      `Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`,
-      "info",
-    );
-  }
-  if (preDispatchResult.action === "skip") {
-    ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
-    setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
-      ctx.ui.notify(`Deferred dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-      pauseAuto(ctx, pi).catch(() => {});
-    }));
-    return;
-  }
-  if (preDispatchResult.action === "replace") {
-    prompt = preDispatchResult.prompt ?? prompt;
-    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
-  } else if (preDispatchResult.prompt) {
-    prompt = preDispatchResult.prompt;
-  }
-
-  const priorSliceBlocker = getPriorSliceCompletionBlocker(s.basePath, getMainBranch(s.basePath), unitType, unitId);
-  if (priorSliceBlocker) {
-    await stopAuto(ctx, pi, priorSliceBlocker);
-    return;
-  }
-
-  const observabilityIssues = await _collectObservabilityWarnings(ctx, s.basePath, unitType, unitId);
-
-  // ── Idempotency check (delegated to auto-idempotency.ts) ──
-  const idempotencyResult = checkIdempotency({
-    s,
-    unitType,
-    unitId,
-    basePath: s.basePath,
-    notify: (msg, level) => ctx.ui.notify(msg, level),
-  });
-
-  if (idempotencyResult.action === "skip") {
-    if (idempotencyResult.reason === "completed" || idempotencyResult.reason === "fallback-persisted" || idempotencyResult.reason === "phantom-loop-cleared" || idempotencyResult.reason === "evicted") {
-      if (!s.active) return;
-      s.skipDepth++;
-      const skipDelay = idempotencyResult.reason === "phantom-loop-cleared" ? 50 : 150;
-      // Defer re-dispatch so s.dispatching is released first (#1272).
-      setTimeout(() => {
-        dispatchNextUnit(ctx, pi).catch(err => {
-          ctx.ui.notify(`Deferred skip-dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-          pauseAuto(ctx, pi).catch(() => {});
-        }).finally(() => {
-          s.skipDepth = Math.max(0, s.skipDepth - 1);
-        });
-      }, skipDelay);
-      return;
-    }
-  } else if (idempotencyResult.action === "stop") {
-    await stopAuto(ctx, pi, idempotencyResult.reason);
-    ctx.ui.notify(
-      `Hard loop detected: ${unitType} ${unitId} hit lifetime cap during skip cycle.`,
-      "error",
-    );
-    return;
-  }
-  // "rerun" and "proceed" fall through to stuck detection
-
-  // ── Stuck detection (delegated to auto-stuck-detection.ts) ──
-  const stuckResult = await checkStuckAndRecover({
-    s,
-    ctx,
-    unitType,
-    unitId,
-    basePath: s.basePath,
-    buildSnapshotOpts: () => buildSnapshotOpts(unitType, unitId),
-  });
-
-  if (stuckResult.action === "stop") {
-    await stopAuto(ctx, pi, stuckResult.reason);
-    if (stuckResult.notifyMessage) {
-      ctx.ui.notify(stuckResult.notifyMessage, "error");
-    }
-    return;
-  }
-  if (stuckResult.action === "recovered" && stuckResult.dispatchAgain) {
-    // Defer re-dispatch so s.dispatching is released first (#1272).
-    setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
-      ctx.ui.notify(`Deferred recovery-dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-      pauseAuto(ctx, pi).catch(() => {});
-    }));
-    return;
-  }
-
-  // Snapshot metrics + activity log for the PREVIOUS unit before we reassign.
-  if (s.currentUnit) {
-    await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
-
-    if (s.currentUnitRouting) {
-      const isRetry = s.currentUnit.type === unitType && s.currentUnit.id === unitId;
-      recordOutcome(
-        s.currentUnit.type,
-        s.currentUnitRouting.tier as "light" | "standard" | "heavy",
-        !isRetry,
-      );
-    }
-
-    const closeoutKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
-    const incomingKey = `${unitType}/${unitId}`;
-    const isHookUnit = s.currentUnit.type.startsWith("hook/");
-    const artifactVerified = isHookUnit || verifyExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
-    if (closeoutKey !== incomingKey && artifactVerified) {
-      if (!isHookUnit) {
-        persistCompletedKey(s.basePath, closeoutKey);
-        s.completedKeySet.add(closeoutKey);
-      }
-
-      s.completedUnits.push({
-        type: s.currentUnit.type,
-        id: s.currentUnit.id,
-        startedAt: s.currentUnit.startedAt,
-        finishedAt: Date.now(),
-      });
-      if (s.completedUnits.length > 200) {
-        s.completedUnits = s.completedUnits.slice(-200);
-      }
-      clearUnitRuntimeRecord(s.basePath, s.currentUnit.type, s.currentUnit.id);
-      s.unitDispatchCount.delete(`${s.currentUnit.type}/${s.currentUnit.id}`);
-      s.unitRecoveryCount.delete(`${s.currentUnit.type}/${s.currentUnit.id}`);
-    }
-  }
-  s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
-  captureAvailableSkills();
-  writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
-    phase: "dispatched",
-    wrapupWarningSent: false,
-    timeoutAt: null,
-    lastProgressAt: s.currentUnit.startedAt,
-    progressCount: 0,
-    lastProgressKind: "dispatch",
-  });
-
-  // Status bar + progress widget
-  ctx.ui.setStatus("gsd-auto", "auto");
-  if (mid) updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
-  updateProgressWidget(ctx, unitType, unitId, state);
-
-  ensurePreconditions(unitType, unitId, s.basePath, state);
-
-  // Fresh session — with timeout to prevent permanent hangs (#1073).
-  // If newSession() hangs (e.g., session manager deadlock, network issue),
-  // without this timeout the entire dispatch chain stalls permanently: no
-  // timeouts are set, no gap watchdog fires, and auto-mode is left active
-  // but idle until the user Ctrl+C's.
-  let result: { cancelled: boolean };
-  try {
-    const sessionPromise = s.cmdCtx!.newSession();
-    const timeoutPromise = new Promise<{ cancelled: true }>((resolve) =>
-      setTimeout(() => resolve({ cancelled: true }), NEW_SESSION_TIMEOUT_MS),
-    );
-    result = await Promise.race([sessionPromise, timeoutPromise]);
-  } catch (sessionErr) {
-    const msg = getErrorMessage(sessionErr);
-    ctx.ui.notify(`Session creation failed: ${msg}. Retrying via watchdog.`, "error");
-    throw new Error(`newSession() failed: ${msg}`);
-  }
-  if (result.cancelled) {
-    ctx.ui.notify(
-      `Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`,
-      "warning",
-    );
-    await stopAuto(ctx, pi, "Session creation failed");
-    return;
-  }
-
-  const sessionFile = ctx.sessionManager.getSessionFile();
-  updateSessionLock(lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
-  writeLock(lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
-
-  // Prompt injection
-  const MAX_RECOVERY_CHARS = 50_000;
-  let finalPrompt = prompt;
-
-  if (s.pendingVerificationRetry) {
-    const retryCtx = s.pendingVerificationRetry;
-    s.pendingVerificationRetry = null;
-    const capped = retryCtx.failureContext.length > MAX_RECOVERY_CHARS
-      ? retryCtx.failureContext.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...failure context truncated]"
-      : retryCtx.failureContext;
-    finalPrompt = `**VERIFICATION FAILED — AUTO-FIX ATTEMPT ${retryCtx.attempt}**\n\nThe verification gate ran after your previous attempt and found failures. Fix these issues before completing the task.\n\n${capped}\n\n---\n\n${finalPrompt}`;
-  }
-
-  if (s.pendingCrashRecovery) {
-    const capped = s.pendingCrashRecovery.length > MAX_RECOVERY_CHARS
-      ? s.pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
-      : s.pendingCrashRecovery;
-    finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
-    s.pendingCrashRecovery = null;
-  } else if ((s.unitDispatchCount.get(`${unitType}/${unitId}`) ?? 0) > 1) {
-    const diagnostic = getDeepDiagnostic(s.basePath);
-    if (diagnostic) {
-      const cappedDiag = diagnostic.length > MAX_RECOVERY_CHARS
-        ? diagnostic.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...diagnostic truncated to prevent memory exhaustion]"
-        : diagnostic;
-      finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
-    }
-  }
-
-  const repairBlock = buildObservabilityRepairBlock(observabilityIssues);
-  if (repairBlock) {
-    finalPrompt = `${finalPrompt}${repairBlock}`;
-  }
-
-  // ── Prompt char measurement ──
-  s.lastPromptCharCount = finalPrompt.length;
-  s.lastBaselineCharCount = undefined;
-  if (isDbAvailable()) {
-    try {
-      const { inlineGsdRootFile } = await import("./auto-prompts.js");
-      const [decisionsContent, requirementsContent, projectContent] = await Promise.all([
-        inlineGsdRootFile(s.basePath, "decisions.md", "Decisions"),
-        inlineGsdRootFile(s.basePath, "requirements.md", "Requirements"),
-        inlineGsdRootFile(s.basePath, "project.md", "Project"),
-      ]);
-      s.lastBaselineCharCount =
-        (decisionsContent?.length ?? 0) +
-        (requirementsContent?.length ?? 0) +
-        (projectContent?.length ?? 0);
-    } catch {
-      // Non-fatal
-    }
-  }
-
-  // Cache-optimize prompt section ordering
-  try {
-    const { reorderForCaching } = await import("./prompt-ordering.js");
-    finalPrompt = reorderForCaching(finalPrompt);
-  } catch (reorderErr) {
-    const msg = getErrorMessage(reorderErr);
-    process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
-  }
-
-  // Select and apply model
-  const modelResult = await selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel);
-  s.currentUnitRouting = modelResult.routing;
-
-  // ── Start unit supervision (delegated to auto-timers.ts) ──
-  clearUnitTimeout();
-  startUnitSupervision({
-    s,
-    ctx,
-    pi,
-    unitType,
-    unitId,
-    prefs,
-    buildSnapshotOpts: () => buildSnapshotOpts(unitType, unitId),
-    buildRecoveryContext: () => buildRecoveryContext(),
-    pauseAuto,
-  });
-
-  // Inject prompt
-  if (!s.active) return;
-  pi.sendMessage(
-    { customType: "gsd-auto", content: finalPrompt, display: s.verbose },
-    { triggerTurn: true },
-  );
-
-  } finally {
-    s.dispatching = false;
-  }
-}
-
 // ─── Preconditions ────────────────────────────────────────────────────────────
 
 /**
@@ -1672,9 +973,13 @@ async function dispatchNextUnit(
  * dispatching a unit. The LLM should never need to mkdir or git checkout.
  */
 function ensurePreconditions(
-  unitType: string, unitId: string, base: string, state: GSDState,
+  unitType: string,
+  unitId: string,
+  base: string,
+  state: GSDState,
 ): void {
-  const { milestone: mid } = parseUnitId(unitId);
+  const parts = unitId.split("/");
+  const mid = parts[0]!;
 
   const mDir = resolveMilestonePath(base, mid);
   if (!mDir) {
@@ -1682,8 +987,8 @@ function ensurePreconditions(
     mkdirSync(join(newDir, "slices"), { recursive: true });
   }
 
-  const sid = parseUnitId(unitId).slice;
-  if (sid) {
+  if (parts.length >= 2) {
+    const sid = parts[1]!;
 
     const mDirResolved = resolveMilestonePath(base, mid);
     if (mDirResolved) {
@@ -1699,16 +1004,17 @@ function ensurePreconditions(
       }
     }
   }
-
 }
 
 // ─── Diagnostics ──────────────────────────────────────────────────────────────
 
 /** Build recovery context from module state for recoverTimedOutUnit */
 function buildRecoveryContext(): import("./auto-timeout-recovery.js").RecoveryContext {
-  return { basePath: s.basePath, verbose: s.verbose,
-    currentUnitStartedAt: s.currentUnit?.startedAt ?? Date.now(), unitRecoveryCount: s.unitRecoveryCount,
-    dispatchNextUnit,
+  return {
+    basePath: s.basePath,
+    verbose: s.verbose,
+    currentUnitStartedAt: s.currentUnit?.startedAt ?? Date.now(),
+    unitRecoveryCount: s.unitRecoveryCount,
   };
 }
 
@@ -1725,17 +1031,6 @@ export {
  * Test-only: expose skip-loop state for unit tests.
  * Not part of the public API.
  */
-export function _getUnitConsecutiveSkips(): Map<string, number> { return s.unitConsecutiveSkips; }
-export function _resetUnitConsecutiveSkips(): void { s.unitConsecutiveSkips.clear(); }
-
-/**
- * Test-only: expose dispatching / skipDepth state for reentrancy guard tests.
- * Not part of the public API.
- */
-export function _getDispatching(): boolean { return s.dispatching; }
-export function _setDispatching(v: boolean): void { s.dispatching = v; }
-export function _getSkipDepth(): number { return s.skipDepth; }
-export function _setSkipDepth(v: number): void { s.skipDepth = v; }
 
 /**
  * Dispatch a hook unit directly, bypassing normal pre-dispatch hooks.
@@ -1765,7 +1060,11 @@ export async function dispatchHookUnit(
   const hookUnitType = `hook/${hookName}`;
   const hookStartedAt = Date.now();
 
-  s.currentUnit = { type: triggerUnitType, id: triggerUnitId, startedAt: hookStartedAt };
+  s.currentUnit = {
+    type: triggerUnitType,
+    id: triggerUnitId,
+    startedAt: hookStartedAt,
+  };
 
   const result = await s.cmdCtx!.newSession();
   if (result.cancelled) {
@@ -1773,32 +1072,49 @@ export async function dispatchHookUnit(
     return false;
   }
 
-  s.currentUnit = { type: hookUnitType, id: triggerUnitId, startedAt: hookStartedAt };
+  s.currentUnit = {
+    type: hookUnitType,
+    id: triggerUnitId,
+    startedAt: hookStartedAt,
+  };
 
-  writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
-    phase: "dispatched",
-    wrapupWarningSent: false,
-    timeoutAt: null,
-    lastProgressAt: hookStartedAt,
-    progressCount: 0,
-    lastProgressKind: "dispatch",
-  });
+  writeUnitRuntimeRecord(
+    s.basePath,
+    hookUnitType,
+    triggerUnitId,
+    hookStartedAt,
+    {
+      phase: "dispatched",
+      wrapupWarningSent: false,
+      timeoutAt: null,
+      lastProgressAt: hookStartedAt,
+      progressCount: 0,
+      lastProgressKind: "dispatch",
+    },
+  );
 
   if (hookModel) {
     const availableModels = ctx.modelRegistry.getAvailable();
-    const match = availableModels.find(m =>
-      m.id === hookModel || `${m.provider}/${m.id}` === hookModel,
+    const match = availableModels.find(
+      (m) => m.id === hookModel || `${m.provider}/${m.id}` === hookModel,
     );
     if (match) {
       try {
         await pi.setModel(match);
-      } catch { /* non-fatal */ }
+      } catch {
+        /* non-fatal */
+      }
     }
   }
 
   const sessionFile = ctx.sessionManager.getSessionFile();
-  updateSessionLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
-  writeLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
+  writeLock(
+    lockBase(),
+    hookUnitType,
+    triggerUnitId,
+    s.completedUnits.length,
+    sessionFile,
+  );
 
   clearUnitTimeout();
   const supervisor = resolveAutoSupervisorConfig();
@@ -1807,10 +1123,16 @@ export async function dispatchHookUnit(
     s.unitTimeoutHandle = null;
     if (!s.active) return;
     if (s.currentUnit) {
-      writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
-        phase: "timeout",
-        timeoutAt: Date.now(),
-      });
+      writeUnitRuntimeRecord(
+        s.basePath,
+        hookUnitType,
+        triggerUnitId,
+        hookStartedAt,
+        {
+          phase: "timeout",
+          timeoutAt: Date.now(),
+        },
+      );
     }
     ctx.ui.notify(
       `Hook ${hookName} exceeded ${supervisor.hard_timeout_minutes ?? 30}min timeout. Pausing auto-mode.`,
@@ -1823,6 +1145,10 @@ export async function dispatchHookUnit(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
 
+  debugLog("dispatchHookUnit", {
+    phase: "send-message",
+    promptLength: hookPrompt.length,
+  });
   pi.sendMessage(
     { customType: "gsd-auto", content: hookPrompt, display: true },
     { triggerTurn: true },
@@ -1831,4 +1157,5 @@ export async function dispatchHookUnit(
   return true;
 }
 
-
+// Direct phase dispatch → auto-direct-dispatch.ts
+export { dispatchDirectPhase } from "./auto-direct-dispatch.js";