gsd-pi 2.80.0 → 2.81.0

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Auto-loop pipeline phases, merge closeout, and finalize handling.
 /**
  * auto/phases.ts — Pipeline phases for the auto-loop.
  *
@@ -32,13 +34,13 @@ import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
 import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "../worktree-root.js";
-import { PROJECT_FILES, hasProjectFileInAncestor } from "../detection.js";
+import { classifyProject } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.js";
 import { join, basename } from "node:path";
-import { existsSync, cpSync, readdirSync } from "node:fs";
+import { existsSync, cpSync } from "node:fs";
 import {
   logWarning,
   logError,
@@ -50,13 +52,14 @@ import {
 } from "../workflow-logger.js";
 import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
-import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.js";
+import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps, refreshRecoveryDbForArtifact } from "../auto-recovery.js";
 import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices, refreshOpenDatabaseFromDisk } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
 import type { MinimalModelRegistry } from "../context-budget.js";
+import type { PostflightResult, PreflightResult } from "../clean-root-preflight.js";
 import { ensurePlanV2Graph, isEmptyPlanV2GraphResult, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -69,6 +72,8 @@ import {
   getRequiredWorkflowToolsForAutoUnit,
   supportsStructuredQuestions,
 } from "../workflow-mcp.js";
+import { resolveManifest } from "../unit-context-manifest.js";
+import { createWorktreeSafetyModule, type WorktreeSafetyResult } from "../worktree-safety.js";
 
 // ─── Path Comparison Helper ───────────────────────────────────────────────
 /** Compare two paths for physical identity, tolerating trailing slashes and symlinks. */
@@ -76,10 +81,111 @@ function isSamePathLocal(a: string, b: string): boolean {
   return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
 
-function refreshPlanSliceRecoveryDbIfNeeded(unitType: string): boolean {
-  if (unitType !== "plan-slice") return true;
-  if (!isDbAvailable()) return true;
-  return refreshOpenDatabaseFromDisk();
+export function shouldDegradeEmptyWorktreeToProjectRoot(
+  worktreeClassification: ReturnType<typeof classifyProject>,
+  projectRootClassification: ReturnType<typeof classifyProject>,
+): boolean {
+  return (
+    worktreeClassification.kind === "greenfield" &&
+    projectRootClassification.kind !== "greenfield" &&
+    projectRootClassification.kind !== "invalid-repo"
+  );
+}
+
+function unitWritesSource(unitType: string): boolean | null {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) return null;
+  return manifest.tools.mode === "all" || manifest.tools.mode === "docs";
+}
+
+function formatWorktreeSafetyFailure(result: Extract<WorktreeSafetyResult, { ok: false }>): string {
+  return `Worktree Safety failed (${result.kind}): ${result.reason} ${result.remediation}`;
+}
+
+function resolveEmptyWorktreeWithProjectContent(
+  unitRoot: string,
+  projectRoot: string,
+): boolean {
+  if (isSamePathLocal(unitRoot, projectRoot)) return false;
+  const worktreeClassification = classifyProject(unitRoot);
+  if (worktreeClassification.kind !== "greenfield") return false;
+  const projectRootClassification = classifyProject(projectRoot);
+  return shouldDegradeEmptyWorktreeToProjectRoot(worktreeClassification, projectRootClassification);
+}
+
+async function validateSourceWriteWorktreeSafety(
+  ic: IterationContext,
+  unitType: string,
+  unitId: string,
+  milestoneId: string | undefined,
+  phase: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  const { ctx, pi, s, deps } = ic;
+  if (!s.basePath) return null;
+
+  // Custom engine workflows (graph-driven, registered via run dirs) define
+  // their own step ids that are not in the GSD UnitContextManifest. Don't
+  // fail closed for those — the custom engine owns its own dispatch
+  // contract. The fail-closed safety check applies only to built-in GSD
+  // units whose Tool Contract is registered in the manifest. Use a truthy
+  // check so undefined (test sessions that never set the field) routes
+  // through the safety check, matching the regression test contract.
+  if (s.activeEngineId) return null;
+
+  const writesSource = unitWritesSource(unitType);
+  if (writesSource === null) {
+    const msg = `Worktree Safety failed (missing-tool-contract): missing Tool Contract for ${unitType}. Add a UnitContextManifest entry before dispatching this Unit.`;
+    debugLog("worktreeSafety", {
+      phase,
+      unitType,
+      unitId,
+      milestoneId,
+      result: { ok: false, kind: "missing-tool-contract", reason: msg },
+      basePath: s.basePath,
+    });
+    ctx.ui.notify(msg, "error");
+    await deps.stopAuto(ctx, pi, msg);
+    return { action: "break", reason: "missing-tool-contract" };
+  }
+  if (!writesSource) return null;
+
+  const projectRoot = s.canonicalProjectRoot ?? resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
+  if (deps.getIsolationMode(projectRoot) !== "worktree") return null;
+
+  const safety = createWorktreeSafetyModule();
+  const result = safety.validateUnitRoot({
+    unitType,
+    unitId,
+    writeScope: "source-writing",
+    projectRoot,
+    unitRoot: s.basePath,
+    milestoneId,
+    expectedBranch: milestoneId ? deps.autoWorktreeBranch(milestoneId) : null,
+    emptyWorktreeWithProjectContent: resolveEmptyWorktreeWithProjectContent(s.basePath, projectRoot),
+    lease: s.workerId
+      ? {
+          required: true,
+          held: s.currentMilestoneId === milestoneId && s.milestoneLeaseToken !== null,
+          owner: s.workerId,
+        }
+      : undefined,
+  });
+
+  if (result.ok) return null;
+
+  const msg = formatWorktreeSafetyFailure(result);
+  debugLog("worktreeSafety", {
+    phase,
+    unitType,
+    unitId,
+    milestoneId,
+    result,
+    basePath: s.basePath,
+    projectRoot,
+  });
+  ctx.ui.notify(msg, "error");
+  await deps.stopAuto(ctx, pi, msg);
+  return { action: "break", reason: result.kind };
 }
 
 // ─── Session timeout auto-resume state ────────────────────────────────────────
@@ -120,10 +226,23 @@ const PLAN_V2_GATE_PHASES: ReadonlySet<Phase> = new Set([
   "completing-milestone",
 ]);
 
-function shouldRunPlanV2Gate(phase: Phase): boolean {
+export function shouldRunPlanV2Gate(phase: Phase): boolean {
   return PLAN_V2_GATE_PHASES.has(phase);
 }
 
+export function _shouldProceedWithInvalidRepoClassificationForTest(
+  reason: string | undefined,
+  hasGit: boolean,
+): boolean {
+  return reason === "missing .git" && hasGit;
+}
+
+export function _resolveCurrentUnitStartedAtForTest(
+  currentUnit: { startedAt: number } | null | undefined,
+): number | undefined {
+  return currentUnit?.startedAt;
+}
+
 /**
  * Generate and write an HTML milestone report snapshot.
  * Extracted from the milestone-transition block in autoLoop.
@@ -215,6 +334,136 @@ async function closeoutAndStop(
   await deps.stopAuto(ctx, pi, reason);
 }
 
+async function stopOnPostflightRecoveryNeeded(
+  ic: IterationContext,
+  result: PostflightResult,
+  milestoneId: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  if (!result.needsManualRecovery) return null;
+  const { ctx, pi, deps } = ic;
+  const reason = `Post-merge stash restore failed for milestone ${milestoneId}`;
+  ctx.ui.notify(
+    `${reason}. Resolve the working tree before resuming auto-mode. ${result.message}`,
+    "error",
+  );
+  await deps.stopAuto(ctx, pi, reason);
+  return { action: "break", reason: "postflight-stash-restore-failed" };
+}
+
+async function restorePreflightStashOrStop(
+  ic: IterationContext,
+  preflight: PreflightResult,
+  milestoneId: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  if (!preflight.stashPushed) return null;
+  const { ctx, s, deps } = ic;
+  const result = deps.postflightPopStash(
+    s.originalBasePath || s.basePath,
+    milestoneId,
+    preflight.stashMarker,
+    ctx.ui.notify.bind(ctx.ui),
+  );
+  return stopOnPostflightRecoveryNeeded(ic, result, milestoneId);
+}
+
+/**
+ * Run a milestone merge surrounded by preflight stash + always-on postflight
+ * pop. The previous code popped the stash only after a successful merge, which
+ * leaked `gsd-preflight-stash:M00x:*` entries whenever `mergeAndExit` threw —
+ * leaving the user's pre-merge working tree silently stashed away after a
+ * merge-conflict or other merge error. This helper restores the stash on
+ * every exit path, then surfaces the merge or stash failure (in priority
+ * order) as the loop's stop reason.
+ *
+ * Returns a `break` action when auto-mode must stop, or `null` when the merge
+ * succeeded and the stash (if any) was restored cleanly.
+ */
+export async function _runMilestoneMergeWithStashRestore(
+  ic: IterationContext,
+  milestoneId: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  const { ctx, pi, s, deps } = ic;
+
+  const preflight = deps.preflightCleanRoot(
+    s.originalBasePath || s.basePath,
+    milestoneId,
+    ctx.ui.notify.bind(ctx.ui),
+  );
+
+  let mergeError: unknown = null;
+  const exitResult = deps.lifecycle.exitMilestone(
+    milestoneId,
+    { merge: true },
+    ctx.ui,
+  );
+  if (exitResult.ok) {
+    s.milestoneMergedInPhases = true;
+  } else {
+    mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+  }
+
+  // Always attempt to restore the stashed working tree, even on merge error.
+  // postflightPopStash itself does not throw; failures surface via the
+  // PostflightResult.needsManualRecovery flag.
+  let stashResult: PostflightResult | null = null;
+  if (preflight.stashPushed) {
+    stashResult = deps.postflightPopStash(
+      s.originalBasePath || s.basePath,
+      milestoneId,
+      preflight.stashMarker,
+      ctx.ui.notify.bind(ctx.ui),
+    );
+  }
+
+  // Merge failure takes priority over stash recovery — the merge is the
+  // authoritative gate. If the stash also needed manual recovery, the user
+  // already saw the postflightPopStash notify above.
+  if (mergeError) {
+    if (mergeError instanceof MergeConflictError) {
+      ctx.ui.notify(
+        `Merge conflict: ${mergeError.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
+        "error",
+      );
+      await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${milestoneId}`);
+      return { action: "break", reason: "merge-conflict" };
+    }
+    logError("engine", "Milestone merge failed with non-conflict error", {
+      milestone: milestoneId,
+      error: String(mergeError),
+    });
+    ctx.ui.notify(
+      `Merge failed: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}. Resolve and run /gsd auto to resume.`,
+      "error",
+    );
+    await deps.stopAuto(
+      ctx,
+      pi,
+      `Merge error on milestone ${milestoneId}: ${String(mergeError)}`,
+    );
+    return { action: "break", reason: "merge-failed" };
+  }
+
+  if (stashResult) {
+    return stopOnPostflightRecoveryNeeded(ic, stashResult, milestoneId);
+  }
+  return null;
+}
+
+export async function _runMilestoneMergeOnceWithStashRestore(
+  ic: IterationContext,
+  milestoneId: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  if (ic.s.milestoneMergedInPhases) {
+    debugLog("autoLoop", {
+      phase: "milestone-merge-skip",
+      reason: "already-merged-in-phases",
+      milestoneId,
+    });
+    return null;
+  }
+  return _runMilestoneMergeWithStashRestore(ic, milestoneId);
+}
+
 async function emitCancelledUnitEnd(
   ic: IterationContext,
   unitType: string,
@@ -442,13 +691,10 @@ export async function runPreDispatch(
   if (
     s.originalBasePath &&
     !isSamePathLocal(s.basePath, s.originalBasePath) &&
-    s.currentMilestoneId
+    s.currentMilestoneId &&
+    s.scope
   ) {
-    deps.syncProjectRootToWorktree(
-      s.originalBasePath,
-      s.basePath,
-      s.currentMilestoneId,
-    );
+    deps.worktreeProjection.projectRootToWorktree(s.scope);
   }
 
   // Derive state — use canonical project root so the cache key is stable
@@ -651,41 +897,11 @@ export async function runPreDispatch(
     loopState.recentUnits.length = 0;
     loopState.stuckRecoveryAttempts = 0;
 
-    // Worktree lifecycle on milestone transition — merge current, enter next
-    // #2909: preflight — warn + stash dirty working tree before merge
-    const preflightTransition = deps.preflightCleanRoot(
-      s.originalBasePath || s.basePath,
-      s.currentMilestoneId!,
-      ctx.ui.notify.bind(ctx.ui),
-    );
-    try {
-      deps.resolver.mergeAndExit(s.currentMilestoneId!, ctx.ui);
-    } catch (mergeErr) {
-      if (mergeErr instanceof MergeConflictError) {
-        // Real code conflicts — stop the loop instead of retrying forever (#2330)
-        ctx.ui.notify(
-          `Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
-          "error",
-        );
-        await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
-        return { action: "break", reason: "merge-conflict" };
-      }
-      // Non-conflict merge errors — stop auto to avoid advancing with unmerged work
-      logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
-      ctx.ui.notify(
-        `Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`,
-        "error",
-      );
-      await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
-      return { action: "break", reason: "merge-failed" };
-    }
-    // #2909: postflight — restore stashed changes after successful merge
-    if (preflightTransition.stashPushed) {
-      deps.postflightPopStash(
-        s.originalBasePath || s.basePath,
-        s.currentMilestoneId!,
-        ctx.ui.notify.bind(ctx.ui),
-      );
+    // Worktree lifecycle on milestone transition — merge current, enter next.
+    // #2909 / #5538-followup: preflight stash + always-on postflight pop.
+    {
+      const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId!);
+      if (stop) return stop;
     }
 
     // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
@@ -700,7 +916,17 @@ export async function runPreDispatch(
       if (deps.getIsolationMode(s.basePath) !== "none") {
         deps.captureIntegrationBranch(s.basePath, mid);
       }
-      deps.resolver.enterMilestone(mid, ctx.ui);
+      const enterResult = deps.lifecycle.enterMilestone(mid, ctx.ui);
+      if (!enterResult.ok) {
+        ctx.ui.notify(
+          `Milestone transition stopped: failed to enter ${mid} (${enterResult.reason}).`,
+          "error",
+        );
+        if (enterResult.reason === "lease-conflict") {
+          await deps.pauseAuto(ctx, pi);
+        }
+        return { action: "break", reason: "milestone-enter-failed" };
+      }
     } else {
       // mid is undefined — no milestone to capture integration branch for
     }
@@ -763,44 +989,11 @@ export async function runPreDispatch(
         m.status !== "complete" && m.status !== "parked",
     );
     if (incomplete.length === 0 && state.registry.length > 0) {
-      // All milestones complete — merge milestone branch before stopping
+      // All milestones complete — merge milestone branch before stopping.
       if (s.currentMilestoneId) {
-        // #2909: preflight — warn + stash dirty working tree before merge
-        const preflightAllComplete = deps.preflightCleanRoot(
-          s.originalBasePath || s.basePath,
-          s.currentMilestoneId,
-          ctx.ui.notify.bind(ctx.ui),
-        );
-        try {
-          deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-          // Prevent stopAuto from attempting the same merge (#2645)
-          s.milestoneMergedInPhases = true;
-        } catch (mergeErr) {
-          if (mergeErr instanceof MergeConflictError) {
-            ctx.ui.notify(
-              `Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
-              "error",
-            );
-            await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
-            return { action: "break", reason: "merge-conflict" };
-          }
-          logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
-          ctx.ui.notify(
-            `Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`,
-            "error",
-          );
-          await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
-          return { action: "break", reason: "merge-failed" };
-        }
-        // #2909: postflight — restore stashed changes after successful merge
-        if (preflightAllComplete.stashPushed) {
-          deps.postflightPopStash(
-            s.originalBasePath || s.basePath,
-            s.currentMilestoneId,
-            ctx.ui.notify.bind(ctx.ui),
-          );
-        }
-
+        // #2909 / #5538-followup: preflight stash + always-on postflight pop.
+        const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
+        if (stop) return stop;
         // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
       }
       deps.sendDesktopNotification(
@@ -891,44 +1084,11 @@ export async function runPreDispatch(
 
   // Terminal: complete
   if (state.phase === "complete") {
-    // Milestone merge on complete (before closeout so branch state is clean)
+    // Milestone merge on complete (before closeout so branch state is clean).
     if (s.currentMilestoneId) {
-      // #2909: preflight — warn + stash dirty working tree before merge
-      const preflightComplete = deps.preflightCleanRoot(
-        s.originalBasePath || s.basePath,
-        s.currentMilestoneId,
-        ctx.ui.notify.bind(ctx.ui),
-      );
-      try {
-        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-        // Prevent stopAuto from attempting the same merge (#2645)
-        s.milestoneMergedInPhases = true;
-      } catch (mergeErr) {
-        if (mergeErr instanceof MergeConflictError) {
-          ctx.ui.notify(
-            `Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
-            "error",
-          );
-          await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
-          return { action: "break", reason: "merge-conflict" };
-        }
-        logError("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
-        ctx.ui.notify(
-          `Merge failed: ${mergeErr instanceof Error ? mergeErr.message : String(mergeErr)}. Resolve and run /gsd auto to resume.`,
-          "error",
-        );
-        await deps.stopAuto(ctx, pi, `Merge error on milestone ${s.currentMilestoneId}: ${String(mergeErr)}`);
-        return { action: "break", reason: "merge-failed" };
-      }
-      // #2909: postflight — restore stashed changes after successful merge
-      if (preflightComplete.stashPushed) {
-        deps.postflightPopStash(
-          s.originalBasePath || s.basePath,
-          s.currentMilestoneId,
-          ctx.ui.notify.bind(ctx.ui),
-        );
-      }
-
+      // #2909 / #5538-followup: preflight stash + always-on postflight pop.
+      const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
+      if (stop) return stop;
       // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
     }
     deps.sendDesktopNotification(
@@ -1051,6 +1211,58 @@ export async function runDispatch(
   let prompt = dispatchResult.prompt;
   const pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
 
+  // Resolve hooks and prior-slice gating before health/stuck accounting so
+  // those checks run against the final dispatch unit.
+  const preDispatchResult = deps.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",
+    );
+    deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "pre-dispatch-hook", data: { firedHooks: preDispatchResult.firedHooks, action: preDispatchResult.action } });
+  }
+  if (preDispatchResult.action === "skip") {
+    ctx.ui.notify(
+      `Skipping ${unitType} ${unitId} (pre-dispatch hook).`,
+      "info",
+    );
+    await new Promise((r) => setImmediate(r));
+    return { action: "continue" };
+  }
+  if (preDispatchResult.action === "replace") {
+    prompt = preDispatchResult.prompt ?? prompt;
+    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
+  } else if (preDispatchResult.prompt) {
+    prompt = preDispatchResult.prompt;
+  }
+
+  const guardBasePath = _resolveDispatchGuardBasePath(s);
+  const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(
+    guardBasePath,
+    deps.getMainBranch(guardBasePath),
+    unitType,
+    unitId,
+  );
+  if (priorSliceBlocker) {
+    await deps.stopAuto(ctx, pi, priorSliceBlocker);
+    debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
+    return { action: "break", reason: "prior-slice-blocker" };
+  }
+
+  const worktreeSafetyBlock = await validateSourceWriteWorktreeSafety(
+    ic,
+    unitType,
+    unitId,
+    mid,
+    "pre-dispatch",
+  );
+  if (worktreeSafetyBlock) return worktreeSafetyBlock;
+
   // ── Sliding-window stuck detection with graduated recovery ──
   const derivedKey = `${unitType}/${unitId}`;
 
@@ -1097,17 +1309,24 @@ export async function runDispatch(
             level: 1,
             action: "artifact-found",
           });
-          ctx.ui.notify(
-            `Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`,
-            "info",
-          );
-          if (!refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+          const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+          if (!recoveryDb.ok) {
             ctx.ui.notify(
-              `Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Keeping stuck state for retry.`,
+              recoveryDb.fatal
+                ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                : `${recoveryDb.message} Keeping stuck state for retry.`,
               "warning",
             );
+            if (recoveryDb.fatal) {
+              await deps.pauseAuto(ctx, pi);
+              return { action: "break", reason: recoveryDb.reason };
+            }
             return { action: "continue" };
           }
+          ctx.ui.notify(
+            `Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`,
+            "info",
+          );
           deps.invalidateAllCaches();
           loopState.recentUnits.length = 0;
           loopState.stuckRecoveryAttempts = 0;
@@ -1132,19 +1351,26 @@ export async function runDispatch(
             level: 2,
             action: "artifact-found",
           });
-          ctx.ui.notify(
-            `Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`,
-            "info",
-          );
-          if (refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+          const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+          if (recoveryDb.ok) {
+            ctx.ui.notify(
+              `Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`,
+              "info",
+            );
             loopState.recentUnits.length = 0;
             loopState.stuckRecoveryAttempts = 0;
             return { action: "continue" };
           }
           ctx.ui.notify(
-            `Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Stopping for manual recovery.`,
+            recoveryDb.fatal
+              ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+              : `${recoveryDb.message} Stopping for manual recovery.`,
             "warning",
           );
+          if (recoveryDb.fatal) {
+            await deps.pauseAuto(ctx, pi);
+            return { action: "break", reason: recoveryDb.reason };
+          }
         }
         debugLog("autoLoop", {
           phase: "stuck-detected",
@@ -1178,48 +1404,6 @@ export async function runDispatch(
     }
   }
 
-  // Pre-dispatch hooks
-  const preDispatchResult = deps.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",
-    );
-    deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "pre-dispatch-hook", data: { firedHooks: preDispatchResult.firedHooks, action: preDispatchResult.action } });
-  }
-  if (preDispatchResult.action === "skip") {
-    ctx.ui.notify(
-      `Skipping ${unitType} ${unitId} (pre-dispatch hook).`,
-      "info",
-    );
-    await new Promise((r) => setImmediate(r));
-    return { action: "continue" };
-  }
-  if (preDispatchResult.action === "replace") {
-    prompt = preDispatchResult.prompt ?? prompt;
-    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
-  } else if (preDispatchResult.prompt) {
-    prompt = preDispatchResult.prompt;
-  }
-
-  const guardBasePath = _resolveDispatchGuardBasePath(s);
-  const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(
-    guardBasePath,
-    deps.getMainBranch(guardBasePath),
-    unitType,
-    unitId,
-  );
-  if (priorSliceBlocker) {
-    await deps.stopAuto(ctx, pi, priorSliceBlocker);
-    debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
-    return { action: "break", reason: "prior-slice-blocker" };
-  }
-
   return {
     action: "next",
     data: {
@@ -1480,46 +1664,46 @@ export async function runUnitPhase(
     unitId,
   });
 
-  // ── Worktree health check (#1833, #1843) ────────────────────────────
-  // Verify the working directory is a valid git checkout with project
-  // files before dispatching work. A broken worktree causes agents to
-  // hallucinate summaries since they cannot read or write any files.
-  // Uses the shared PROJECT_FILES list from detection.ts to support all
-  // ecosystems (Rust, Go, Python, Java, etc.), not just JS.
+  const worktreeSafetyBlock = await validateSourceWriteWorktreeSafety(
+    ic,
+    unitType,
+    unitId,
+    mid,
+    "unit-execution",
+  );
+  if (worktreeSafetyBlock) return worktreeSafetyBlock;
+
+  // ── Project classification notice (#1833, #1843) ─────────────────────
+  // Worktree Safety owns source-write root validity. Classification now only
+  // shapes user/model guidance for valid roots.
+  let projectClassification: ReturnType<typeof classifyProject> | null = null;
   if (s.basePath && unitType === "execute-task") {
-    const gitMarker = join(s.basePath, ".git");
-    const hasGit = deps.existsSync(gitMarker);
-    if (!hasGit) {
-      const msg = `Worktree health check failed: ${s.basePath} has no .git — refusing to dispatch ${unitType} ${unitId}`;
-      debugLog("runUnitPhase", { phase: "worktree-health-fail", basePath: s.basePath, hasGit });
-      ctx.ui.notify(msg, "error");
-      await deps.stopAuto(ctx, pi, msg);
-      return { action: "break", reason: "worktree-invalid" };
-    }
-    const hasProjectFile = PROJECT_FILES.some((f) => deps.existsSync(join(s.basePath, f)));
-    const hasSrcDir = deps.existsSync(join(s.basePath, "src"));
-    // Xcode bundles have project-specific names (*.xcodeproj, *.xcworkspace)
-    // that cannot be matched by exact filename — scan the directory by suffix.
-    let hasXcodeBundle = false;
-    try {
-      const entries = deps.existsSync(s.basePath) ? readdirSync(s.basePath) : [];
-      hasXcodeBundle = entries.some((e: string) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"));
-    } catch (err) {
-      debugLog("runUnitPhase", { phase: "xcode-bundle-scan-failed", basePath: s.basePath, error: String(err) });
+    projectClassification = classifyProject(s.basePath);
+    if (projectClassification.kind === "invalid-repo") {
+      const msg = `Worktree health check failed: ${s.basePath} classified as invalid-repo (${projectClassification.reason}) — refusing to dispatch ${unitType} ${unitId}`;
+      debugLog("runUnitPhase", { phase: "worktree-health-invalid-repo", basePath: s.basePath, classification: projectClassification });
+      const hasGit = deps.existsSync(join(s.basePath, ".git"));
+      if (_shouldProceedWithInvalidRepoClassificationForTest(projectClassification.reason, hasGit)) {
+        ctx.ui.notify(
+          `Warning: ${s.basePath} project classification could not confirm .git; assuming it has no project content yet — proceeding as greenfield project because worktree health reported .git present`,
+          "warning",
+        );
+      } else {
+        ctx.ui.notify(msg, "error");
+        await deps.stopAuto(ctx, pi, msg);
+        return { action: "break", reason: "worktree-invalid" };
+      }
     }
-    // Monorepo support (#2347): if no project files in the worktree directory,
-    // walk parent directories up to the filesystem root. In monorepos,
-    // package.json / Cargo.toml etc. live in a parent directory.
-    const hasProjectFileInParent =
-      !hasProjectFile && !hasSrcDir && !hasXcodeBundle
-        ? hasProjectFileInAncestor(s.basePath, deps.existsSync)
-        : false;
-    if (!hasProjectFile && !hasSrcDir && !hasXcodeBundle && !hasProjectFileInParent) {
-      // Greenfield projects won't have project files yet — the first task creates them.
-      // Log a warning but allow execution to proceed. The .git check above is sufficient
-      // to ensure we're in a valid working directory.
-      debugLog("runUnitPhase", { phase: "worktree-health-warn-greenfield", basePath: s.basePath, hasProjectFile, hasSrcDir, hasXcodeBundle });
-      ctx.ui.notify(`Warning: ${s.basePath} has no recognized project files — proceeding as greenfield project`, "warning");
+
+    if (projectClassification.kind === "greenfield") {
+      debugLog("runUnitPhase", { phase: "worktree-health-greenfield", basePath: s.basePath, classification: projectClassification });
+      ctx.ui.notify(`Warning: ${s.basePath} has no project content yet — proceeding as greenfield project`, "warning");
+    } else if (projectClassification.kind === "untyped-existing") {
+      debugLog("runUnitPhase", { phase: "worktree-health-untyped-existing", basePath: s.basePath, classification: projectClassification });
+      ctx.ui.notify(
+        `Notice: ${s.basePath} has existing project content but no recognized tooling markers — using generic file-level workflow guidance`,
+        "info",
+      );
     }
   }
 
@@ -1598,6 +1782,17 @@ export async function runUnitPhase(
   // Prompt injection
   let finalPrompt = prompt;
 
+  if (unitType === "execute-task") {
+    projectClassification ??= classifyProject(s.basePath);
+    if (projectClassification.kind === "untyped-existing") {
+      const samples = projectClassification.contentFiles.slice(0, 8).join(", ") || "project files";
+      finalPrompt +=
+        "\n\n**Project classification:** Existing untyped project. No recognized build/tooling markers were detected, " +
+        "so use generic file-level workflow guidance. Task plans and completion summaries must list every concrete " +
+        `project file changed in \`files\` or \`expected_output\`. Detected content sample: ${samples}.`;
+    }
+  }
+
   if (s.pendingVerificationRetry) {
     const retryCtx = s.pendingVerificationRetry;
     s.pendingVerificationRetry = null;
@@ -1982,7 +2177,7 @@ export async function runUnitPhase(
     const currentLedger = deps.getLedger() as { units: Array<{ type: string; id: string; startedAt: number; toolCalls: number }> } | null;
     if (currentLedger?.units) {
       const lastUnit = [...currentLedger.units].reverse().find(
-        (u: { type: string; id: string; startedAt: number; toolCalls: number }) => u.type === unitType && u.id === unitId && u.startedAt === s.currentUnit?.startedAt,
+        (u: { type: string; id: string; startedAt: number; toolCalls: number }) => u.type === unitType && u.id === unitId && u.startedAt === _resolveCurrentUnitStartedAtForTest(s.currentUnit),
       );
       if (lastUnit && lastUnit.toolCalls === 0) {
         if (USER_DRIVEN_DEEP_UNITS.has(unitType) && isAwaitingUserInput(s.lastUnitAgentEndMessages ?? undefined)) {
@@ -2004,7 +2199,7 @@ export async function runUnitPhase(
           );
           // Fall through to next iteration where dispatch will re-derive
           // and re-dispatch this unit.
-          return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt, requestDispatchedAt: unitResult.requestDispatchedAt } };
+          return { action: "next", data: { unitStartedAt: _resolveCurrentUnitStartedAtForTest(s.currentUnit), requestDispatchedAt: unitResult.requestDispatchedAt } };
         }
       }
     }
@@ -2069,7 +2264,7 @@ export async function runUnitPhase(
     s.checkpointSha = null;
   }
 
-  return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt, requestDispatchedAt: unitResult.requestDispatchedAt } };
+  return { action: "next", data: { unitStartedAt: _resolveCurrentUnitStartedAtForTest(s.currentUnit), requestDispatchedAt: unitResult.requestDispatchedAt } };
 }
 
 // ─── runFinalize ──────────────────────────────────────────────────────────────
@@ -2249,8 +2444,20 @@ export async function runFinalize(
     return { action: "break", reason: "step-wizard" };
   }
 
+  if (preUnitSnapshot?.type === "complete-milestone" && s.currentMilestoneId) {
+    const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
+    if (stop) return stop;
+  }
+
   // Both pre and post verification completed without timeout — reset counter
   loopState.consecutiveFinalizeTimeouts = 0;
+  if (preUnitSnapshot) {
+    writeUnitRuntimeRecord(s.basePath, preUnitSnapshot.type, preUnitSnapshot.id, preUnitSnapshot.startedAt, {
+      phase: "finalized",
+      lastProgressAt: Date.now(),
+      lastProgressKind: "finalize-success",
+    });
+  }
   s.currentUnit = null;
   clearCurrentPhase();