gsd-pi 2.80.0 → 2.81.0

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

@@ -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.
  *
@@ -13,22 +15,22 @@ 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, _resetLogs, drainLogs, drainAndSummarize, formatForNotification, hasAnyIssues, } 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 { ensurePlanV2Graph, isEmptyPlanV2GraphResult, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -37,17 +39,102 @@ import { parseUnitId } from "../unit-id.js";
 import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js";
 import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, supportsStructuredQuestions, } from "../workflow-mcp.js";
+import { resolveManifest } from "../unit-context-manifest.js";
+import { createWorktreeSafetyModule } from "../worktree-safety.js";
 // ─── Path Comparison Helper ───────────────────────────────────────────────
 /** Compare two paths for physical identity, tolerating trailing slashes and symlinks. */
 function isSamePathLocal(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
-function refreshPlanSliceRecoveryDbIfNeeded(unitType) {
-    if (unitType !== "plan-slice")
-        return true;
-    if (!isDbAvailable())
-        return true;
-    return refreshOpenDatabaseFromDisk();
+export function shouldDegradeEmptyWorktreeToProjectRoot(worktreeClassification, projectRootClassification) {
+    return (worktreeClassification.kind === "greenfield" &&
+        projectRootClassification.kind !== "greenfield" &&
+        projectRootClassification.kind !== "invalid-repo");
+}
+function unitWritesSource(unitType) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return null;
+    return manifest.tools.mode === "all" || manifest.tools.mode === "docs";
+}
+function formatWorktreeSafetyFailure(result) {
+    return `Worktree Safety failed (${result.kind}): ${result.reason} ${result.remediation}`;
+}
+function resolveEmptyWorktreeWithProjectContent(unitRoot, projectRoot) {
+    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, unitType, unitId, milestoneId, phase) {
+    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 ────────────────────────────────────────
 let consecutiveSessionTimeouts = 0;
@@ -78,9 +165,15 @@ const PLAN_V2_GATE_PHASES = new Set([
     "validating-milestone",
     "completing-milestone",
 ]);
-function shouldRunPlanV2Gate(phase) {
+export function shouldRunPlanV2Gate(phase) {
     return PLAN_V2_GATE_PHASES.has(phase);
 }
+export function _shouldProceedWithInvalidRepoClassificationForTest(reason, hasGit) {
+    return reason === "missing .git" && hasGit;
+}
+export function _resolveCurrentUnitStartedAtForTest(currentUnit) {
+    return currentUnit?.startedAt;
+}
 /**
  * Generate and write an HTML milestone report snapshot.
  * Extracted from the milestone-transition block in autoLoop.
@@ -136,6 +229,85 @@ async function closeoutAndStop(ctx, pi, s, deps, reason) {
     }
     await deps.stopAuto(ctx, pi, reason);
 }
+async function stopOnPostflightRecoveryNeeded(ic, result, milestoneId) {
+    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, preflight, milestoneId) {
+    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, milestoneId) {
+    const { ctx, pi, s, deps } = ic;
+    const preflight = deps.preflightCleanRoot(s.originalBasePath || s.basePath, milestoneId, ctx.ui.notify.bind(ctx.ui));
+    let mergeError = 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 = 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, milestoneId) {
+    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, unitType, unitId, unitStartSeq, errorContext) {
     ic.deps.emitJournalEvent({
         ts: new Date().toISOString(),
@@ -309,8 +481,9 @@ export async function runPreDispatch(ic, loopState) {
     // Sync project root artifacts into worktree
     if (s.originalBasePath &&
         !isSamePathLocal(s.basePath, s.originalBasePath) &&
-        s.currentMilestoneId) {
-        deps.syncProjectRootToWorktree(s.originalBasePath, s.basePath, s.currentMilestoneId);
+        s.currentMilestoneId &&
+        s.scope) {
+        deps.worktreeProjection.projectRootToWorktree(s.scope);
     }
     // Derive state — use canonical project root so the cache key is stable
     // across worktree↔project-root path-form alternation. See PR #5236
@@ -477,28 +650,12 @@ export async function runPreDispatch(ic, loopState) {
         s.unitLifetimeDispatches.clear();
         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)
         deps.invalidateAllCaches();
@@ -509,7 +666,14 @@ export async function runPreDispatch(ic, loopState) {
             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
@@ -552,30 +716,12 @@ export async function runPreDispatch(ic, loopState) {
         }
         const incomplete = state.registry.filter((m) => 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("GSD", "All milestones complete!", "success", "milestone", basename(s.originalBasePath || s.basePath));
@@ -638,30 +784,12 @@ export async function runPreDispatch(ic, loopState) {
     }
     // 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("GSD", `Milestone ${mid} complete!`, "success", "milestone", basename(s.originalBasePath || s.basePath));
@@ -754,6 +882,36 @@ export async function runDispatch(ic, preData, loopState) {
     let unitId = dispatchResult.unitId;
     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}`;
     // Always record this dispatch in the sliding window so detectStuck() has
@@ -795,11 +953,18 @@ export async function runDispatch(ic, preData, loopState) {
                         level: 1,
                         action: "artifact-found",
                     });
-                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
-                    if (!refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
-                        ctx.ui.notify(`Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Keeping stuck state for retry.`, "warning");
+                    const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId);
+                    if (!recoveryDb.ok) {
+                        ctx.ui.notify(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;
@@ -818,13 +983,20 @@ export async function runDispatch(ic, preData, loopState) {
                         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.`, "warning");
+                    ctx.ui.notify(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",
@@ -856,32 +1028,6 @@ export async function runDispatch(ic, preData, loopState) {
             }
         }
     }
-    // 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: {
@@ -1080,46 +1226,35 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         unitType,
         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 = 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) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"));
+        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" };
+            }
         }
-        catch (err) {
-            debugLog("runUnitPhase", { phase: "xcode-bundle-scan-failed", basePath: s.basePath, error: String(err) });
+        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");
         }
-        // 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");
+        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");
         }
     }
     // Detect retry and capture previous tier for escalation
@@ -1182,6 +1317,16 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     }
     // 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;
@@ -1457,7 +1602,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     {
         const currentLedger = deps.getLedger();
         if (currentLedger?.units) {
-            const lastUnit = [...currentLedger.units].reverse().find((u) => u.type === unitType && u.id === unitId && u.startedAt === s.currentUnit?.startedAt);
+            const lastUnit = [...currentLedger.units].reverse().find((u) => 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)) {
                     debugLog("runUnitPhase", {
@@ -1476,7 +1621,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                     ctx.ui.notify(`${unitType} ${unitId} completed with 0 tool calls — context exhaustion, will retry`, "warning");
                     // 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 } };
                 }
             }
         }
@@ -1530,7 +1675,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         }
         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 ──────────────────────────────────────────────────────────────
 /**
@@ -1663,8 +1808,20 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
         debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
         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();
     // Surface accumulated workflow-logger issues for this unit to the user.