gsd-pi 2.76.0 → 2.77.0-dev.538325aea

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

@@ -54,7 +54,8 @@ import type { MinimalModelRegistry } from "../context-budget.js";
 import { ensurePlanV2Graph } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
-import { resetEvidence } from "../safety/evidence-collector.js";
+import { resetEvidence, loadEvidenceFromDisk } from "../safety/evidence-collector.js";
+import { parseUnitId } from "../unit-id.js";
 import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js";
 import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
 import {
@@ -80,7 +81,11 @@ export function resetSessionTimeoutState(): void {
  * Exported for testing as _resolveReportBasePath.
  */
 export function _resolveReportBasePath(s: Pick<AutoSession, "originalBasePath" | "basePath">): string {
-  return s.originalBasePath || s.basePath;
+  // Strip /.gsd/worktrees/ suffix when basePath is itself a worktree path and
+  // originalBasePath is falsy — prevents reports landing in the worktree (#3729).
+  const resolved = s.originalBasePath || s.basePath;
+  const markerIdx = resolved.indexOf("/.gsd/worktrees/");
+  return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
 }
 
 /**
@@ -91,7 +96,12 @@ export function _resolveReportBasePath(s: Pick<AutoSession, "originalBasePath" |
 export function _resolveDispatchGuardBasePath(
   s: Pick<AutoSession, "originalBasePath" | "basePath">,
 ): string {
-  return s.originalBasePath || s.basePath;
+  // Strip /.gsd/worktrees/ suffix when basePath is itself a worktree path and
+  // originalBasePath is falsy — prevents guard checks running against the
+  // worktree instead of the project root (#3729).
+  const resolved = s.originalBasePath || s.basePath;
+  const markerIdx = resolved.indexOf("/.gsd/worktrees/");
+  return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
 }
 
 const PLAN_V2_GATE_PHASES: ReadonlySet<Phase> = new Set([
@@ -419,7 +429,7 @@ export async function runPreDispatch(
         findings: reason,
         milestoneId: state.activeMilestone?.id ?? undefined,
       });
-      ctx.ui.notify(`Plan gate failed-closed: ${reason}`, "error");
+      ctx.ui.notify(`Plan gate failed-closed: ${reason}\n\nIf this keeps happening, try: /gsd doctor heal`, "error");
       await deps.pauseAuto(ctx, pi);
       return { action: "break", reason: "plan-v2-gate-failed" };
     }
@@ -545,6 +555,12 @@ export async function runPreDispatch(
     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) {
@@ -566,6 +582,14 @@ export async function runPreDispatch(
       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),
+      );
+    }
 
     // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
 
@@ -644,6 +668,12 @@ export async function runPreDispatch(
     if (incomplete.length === 0 && state.registry.length > 0) {
       // 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)
@@ -665,6 +695,14 @@ export async function runPreDispatch(
           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),
+          );
+        }
 
         // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
       }
@@ -758,6 +796,12 @@ export async function runPreDispatch(
   if (state.phase === "complete") {
     // 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)
@@ -779,6 +823,14 @@ export async function runPreDispatch(
         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),
+        );
+      }
 
       // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
     }
@@ -1131,16 +1183,42 @@ export async function runGuards(
       s.lastBudgetAlertLevel =
         newBudgetAlertLevel as AutoSession["lastBudgetAlertLevel"];
 
-      if (threshold.pct === 100 && budgetEnforcementAction !== "none") {
+      // Emit Layer 2 budget_threshold event (post-plan hook recommendation).
+      // Extensions / Layer 0 shell hooks may return an action override.
+      let hookAction: "pause" | "downgrade" | "continue" | undefined;
+      try {
+        const { emitBudgetThreshold } = await import("../hook-emitter.js");
+        const hookResult = await emitBudgetThreshold({
+          fraction: budgetPct,
+          spent: totalCost,
+          limit: budgetCeiling,
+        });
+        if (hookResult?.action) hookAction = hookResult.action;
+      } catch (hookErr) {
+        logWarning("engine", `budget_threshold hook emission failed: ${(hookErr as Error).message}`);
+      }
+
+      // Apply hook override to enforcement action. "continue" → "none" (no enforcement),
+      // "pause" and "downgrade" map to the matching enforcement path below.
+      let effectiveAction = budgetEnforcementAction;
+      if (hookAction === "continue") {
+        effectiveAction = "none";
+      } else if (hookAction === "pause") {
+        effectiveAction = "pause";
+      } else if (hookAction === "downgrade") {
+        effectiveAction = "warn";
+      }
+
+      if (threshold.pct === 100 && effectiveAction !== "none") {
         // 100% — special enforcement logic (halt/pause/warn)
         const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
-        if (budgetEnforcementAction === "halt") {
+        if (effectiveAction === "halt") {
           deps.sendDesktopNotification("GSD", msg, "error", "budget", basename(s.originalBasePath || s.basePath));
           await deps.stopAuto(ctx, pi, "Budget ceiling reached");
           debugLog("autoLoop", { phase: "exit", reason: "budget-halt" });
           return { action: "break", reason: "budget-halt" };
         }
-        if (budgetEnforcementAction === "pause") {
+        if (effectiveAction === "pause") {
           ctx.ui.notify(
             `${msg} Pausing auto-mode — /gsd auto to override and continue.`,
             "warning",
@@ -1359,6 +1437,14 @@ export async function runUnitPhase(
   );
   if (safetyConfig.enabled && safetyConfig.evidence_collection) {
     resetEvidence();
+    // Restore persisted evidence so session-restart resumes don't produce
+    // false-positive "no bash calls" warnings (Bug #4385).
+    if (s.basePath && unitType === "execute-task") {
+      const { milestone: eMid, slice: eSid, task: eTid } = parseUnitId(unitId);
+      if (eMid && eSid && eTid) {
+        loadEvidenceFromDisk(s.basePath, eMid, eSid, eTid);
+      }
+    }
   }
   // Only checkpoint code-executing units (not lifecycle/planning units)
   if (safetyConfig.enabled && safetyConfig.checkpoints && unitType === "execute-task") {
@@ -1445,6 +1531,7 @@ export async function runUnitPhase(
     sidecarItem ? undefined : { isRetry, previousTier },
     undefined,
     s.manualSessionModelOverride,
+    s.autoModeStartThinkingLevel,
   );
   s.currentUnitRouting =
     modelResult.routing as AutoSession["currentUnitRouting"];
@@ -1459,6 +1546,9 @@ export async function runUnitPhase(
     if (match) {
       const ok = await pi.setModel(match, { persist: false });
       if (ok) {
+        if (s.autoModeStartThinkingLevel) {
+          pi.setThinkingLevel(s.autoModeStartThinkingLevel);
+        }
         s.currentUnitModel = match as AutoSession["currentUnitModel"];
         ctx.ui.notify(`Hook model override: ${match.provider}/${match.id}`, "info");
       } else {
@@ -1589,21 +1679,24 @@ export async function runUnitPhase(
   }
 
   if (unitResult.status === "cancelled") {
+    const errorCategory = unitResult.errorContext?.category;
     // Provider-error pause: pauseAuto already handled cleanup and scheduled
     // recovery. Don't hard-stop — just break out of the loop (#2762).
-    if (unitResult.errorContext?.category === "provider") {
+    if (errorCategory === "provider") {
       await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
-      debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient });
+      debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext?.isTransient });
       return { action: "break", reason: "provider-pause" };
     }
     // Timeout category covers two distinct scenarios:
     //   1. Session creation timeout (120s) — transient, auto-resume with backoff
     //   2. Unit hard timeout (30min+) — stuck agent, pause for manual review
+    // Transient session-failed covers recoverable newSession failures and should
+    // pause instead of hard-stopping.
     // Structural errors (TypeError, is not a function) are NOT transient
     // and must hard-stop to avoid infinite retry loops.
     if (
       unitResult.errorContext?.isTransient &&
-      unitResult.errorContext?.category === "timeout"
+      errorCategory === "timeout"
     ) {
       const isSessionCreationTimeout = unitResult.errorContext.message?.includes("Session creation timed out");
 
@@ -1666,6 +1759,20 @@ export async function runUnitPhase(
       await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
       return { action: "break", reason: "unit-hard-timeout" };
     }
+    if (
+      unitResult.errorContext?.isTransient &&
+      errorCategory === "session-failed"
+    ) {
+      ctx.ui.notify(
+        `Session creation failed transiently for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Pausing auto-mode (recoverable).`,
+        "warning",
+      );
+      debugLog("autoLoop", { phase: "session-start-transient-pause", unitType, unitId, category: errorCategory });
+      await deps.pauseAuto(ctx, pi);
+      await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+      await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+      return { action: "break", reason: "session-timeout" };
+    }
     // All other cancelled states (structural errors, non-transient failures): hard stop
     if (s.currentUnit) {
       await deps.closeoutUnit(
@@ -1881,6 +1988,20 @@ export async function runFinalize(
       debugLog("autoLoop", { phase: "sidecar-artifact-retry-skipped", iteration: ic.iteration });
     } else {
       // s.pendingVerificationRetry was set by postUnitPreVerification.
+      // Emit a dedicated journal event so forensics can distinguish bounded
+      // verification retries from genuine stuck-loop dispatch repetitions (#4540).
+      const retryInfo = s.pendingVerificationRetry;
+      deps.emitJournalEvent({
+        ts: new Date().toISOString(),
+        flowId: ic.flowId,
+        seq: ic.nextSeq(),
+        eventType: "artifact-verification-retry",
+        data: {
+          unitType: preUnitSnapshot?.type,
+          unitId: retryInfo?.unitId,
+          attempt: retryInfo?.attempt,
+        },
+      });
       // Continue the loop — next iteration will inject the retry context into the prompt.
       debugLog("autoLoop", { phase: "artifact-verification-retry", iteration: ic.iteration });
       return { action: "continue" };

package/src/resources/extensions/gsd/auto/run-unit.ts

@@ -42,16 +42,25 @@ export async function runUnit(
   let sessionResult: { cancelled: boolean };
   let sessionTimeoutHandle: ReturnType<typeof setTimeout> | undefined;
   const mySessionSwitchGeneration = ++sessionSwitchGeneration;
+  // #3731: Cancellation controller for newSession(). When the session-creation
+  // timeout fires, we abort this controller so that the still-in-flight
+  // newSession() discards itself after await this.abort() completes, preventing
+  // it from capturing the (now-root) process.cwd() and rebuilding the tool
+  // runtime with the wrong cwd.
+  const sessionAbortController = new AbortController();
   _setSessionSwitchInFlight(true);
   try {
-    const sessionPromise = s.cmdCtx!.newSession().finally(() => {
+    const sessionPromise = s.cmdCtx!.newSession({ abortSignal: sessionAbortController.signal }).finally(() => {
       if (sessionSwitchGeneration === mySessionSwitchGeneration) {
         _setSessionSwitchInFlight(false);
       }
     });
     const timeoutPromise = new Promise<{ cancelled: true }>((resolve) => {
       sessionTimeoutHandle = setTimeout(
-        () => resolve({ cancelled: true }),
+        () => {
+          sessionAbortController.abort();
+          resolve({ cancelled: true });
+        },
         NEW_SESSION_TIMEOUT_MS,
       );
     });
@@ -118,6 +127,35 @@ export async function runUnit(
     logWarning("engine", "Failed to chdir to basePath before dispatch", { basePath: s.basePath, error: String(e) });
   }
 
+  // ── Provider request-readiness pre-check (#4555) ──
+  // Verify the provider can accept requests before dispatching. If the token
+  // has expired since bootstrap, return cancelled immediately so the unit is
+  // not wasted on a guaranteed 401.
+  {
+    const provider = s.currentUnitModel?.provider ?? ctx.model?.provider;
+    const registry = (ctx as any).modelRegistry;
+
+    if (provider && registry != null && typeof registry.isProviderRequestReady === "function") {
+      let ready = false;
+      try {
+        ready = registry.isProviderRequestReady(provider);
+      } catch {
+        ready = false;
+      }
+
+      if (!ready) {
+        return {
+          status: "cancelled",
+          errorContext: {
+            message: `Provider ${provider} is not request-ready (login/token expired)`,
+            category: "provider",
+            isTransient: false,
+          },
+        };
+      }
+    }
+  }
+
   // ── Send the prompt ──
   debugLog("runUnit", { phase: "send-message", unitType, unitId });
 

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

@@ -17,7 +17,7 @@
  */
 
 import type { Api, Model } from "@gsd/pi-ai";
-import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import type { GitServiceImpl } from "../git-service.js";
 import type { CaptureEntry } from "../captures.js";
 import type { BudgetAlertLevel } from "../auto-budget.js";
@@ -40,6 +40,8 @@ export interface StartModel {
   id: string;
 }
 
+export type ThinkingLevelSnapshot = ReturnType<ExtensionAPI["getThinkingLevel"]>;
+
 export interface PendingVerificationRetry {
   unitId: string;
   failureContext: string;
@@ -62,6 +64,15 @@ export interface SidecarItem {
   captureId?: string;
 }
 
+export interface PreExecFailure {
+  /** Milestone/slice that failed (e.g. "M001/S02"). */
+  unitId: string;
+  /** Verbatim blocking check strings from the failed gate run. */
+  blockingFindings: string[];
+  /** Condensed gate verdict excerpt for context (status + rationale). */
+  verdictExcerpt: string;
+}
+
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 export const MAX_UNIT_DISPATCHES = 3;
@@ -120,6 +131,8 @@ export class AutoSession {
   currentDispatchedModelId: string | null = null;
   originalModelId: string | null = null;
   originalModelProvider: string | null = null;
+  autoModeStartThinkingLevel: ThinkingLevelSnapshot | null = null;
+  originalThinkingLevel: ThinkingLevelSnapshot | null = null;
   lastBudgetAlertLevel: BudgetAlertLevel = 0;
 
   // ── Recovery ─────────────────────────────────────────────────────────────
@@ -135,6 +148,18 @@ export class AutoSession {
   // ── Sidecar queue ─────────────────────────────────────────────────────
   sidecarQueue: SidecarItem[] = [];
 
+  // ── Pre-exec gate failure context (#4551) ───────────────────────────
+  /**
+   * Persisted when a pre-execution gate fails on a plan-slice or refine-slice
+   * unit. The planning → plan-slice dispatch rule reads this field and injects
+   * the failure details into the next re-dispatch prompt so the LLM can fix the
+   * specific issues instead of producing an identical plan.
+   *
+   * Cleared after it has been consumed (injected into the prompt) to avoid
+   * stale context bleeding into unrelated slices.
+   */
+  lastPreExecFailure: PreExecFailure | null = null;
+
   // ── Tool invocation errors (#2883) ──────────────────────────────────
   /** Set when a GSD tool execution ends with isError due to malformed/truncated
    *  JSON arguments. Checked by postUnitPreVerification to break retry loops. */
@@ -195,7 +220,12 @@ export class AutoSession {
   }
 
   get lockBasePath(): string {
-    return this.originalBasePath || this.basePath;
+    // Prefer originalBasePath (project root); fall back to basePath.
+    // Strip /.gsd/worktrees/ suffix if basePath is itself a worktree path
+    // to avoid reading/writing the lock inside the worktree (#3729).
+    const resolved = this.originalBasePath || this.basePath;
+    const markerIdx = resolved.indexOf("/.gsd/worktrees/");
+    return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
   }
 
   reset(): void {
@@ -241,6 +271,8 @@ export class AutoSession {
     this.currentDispatchedModelId = null;
     this.originalModelId = null;
     this.originalModelProvider = null;
+    this.autoModeStartThinkingLevel = null;
+    this.originalThinkingLevel = null;
     this.lastBudgetAlertLevel = 0;
 
     // Recovery
@@ -261,6 +293,7 @@ export class AutoSession {
     this.sidecarQueue = [];
     this.rewriteAttemptCount = 0;
     this.consecutiveCompleteBootstraps = 0;
+    this.lastPreExecFailure = null;
     this.lastToolInvocationError = null;
     this.lastGitActionFailure = null;
     this.lastGitActionStatus = null;

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

@@ -33,7 +33,7 @@ import { parseRoadmap } from "./parsers-legacy.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { join } from "node:path";
-import { hasImplementationArtifacts } from "./auto-recovery.js";
+import { hasImplementationArtifacts, classifyMilestoneSummaryContent } from "./auto-recovery.js";
 import {
   buildDiscussMilestonePrompt,
   buildResearchMilestonePrompt,
@@ -568,15 +568,28 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "planning → plan-slice",
-    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry, session }) => {
       if (state.phase !== "planning") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
+      // #4551: Consume any persisted pre-exec failure for this slice so the
+      // re-dispatched prompt includes the exact blocked references. Clear the
+      // field immediately after reading to prevent stale context leaking into
+      // a later, unrelated plan-slice run.
+      const unitId = `${mid}/${sid}`;
+      let priorPreExecFailure: { blockingFindings: string[]; verdictExcerpt: string } | undefined;
+      if (session?.lastPreExecFailure?.unitId === unitId) {
+        priorPreExecFailure = {
+          blockingFindings: session.lastPreExecFailure.blockingFindings,
+          verdictExcerpt: session.lastPreExecFailure.verdictExcerpt,
+        };
+        session.lastPreExecFailure = null;
+      }
       return {
         action: "dispatch",
         unitType: "plan-slice",
-        unitId: `${mid}/${sid}`,
+        unitId,
         prompt: await buildPlanSlicePrompt(
           mid,
           midTitle,
@@ -584,7 +597,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           sTitle,
           basePath,
           undefined,
-          { sessionContextWindow, modelRegistry },
+          { sessionContextWindow, modelRegistry, priorPreExecFailure },
         ),
       };
     },
@@ -870,21 +883,13 @@ export const DISPATCH_RULES: DispatchRule[] = [
         }
       }
 
-      // Reconciliation guard (#4324): when the SUMMARY file already exists
-      // on disk but the DB says the milestone is not complete, the DB is
-      // out of sync (e.g. journal reset, partial merge, crash recovery).
-      // Reconcile the DB status directly instead of re-dispatching the
-      // tool, which would overwrite the richer on-disk SUMMARY with a
-      // thinner regenerated version — causing silent data loss.
       const existingSummary = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      let summaryOutcome: "success" | "failure" | "unknown" = "unknown";
       if (existingSummary && isDbAvailable()) {
-        try {
-          updateMilestoneStatus(mid, "complete", new Date().toISOString());
-          logWarning("dispatch", `Milestone ${mid} has SUMMARY on disk but DB status was not complete — reconciled DB to complete (#4324)`);
-        } catch (err) {
-          logWarning("dispatch", `Failed to reconcile milestone ${mid} status: ${err instanceof Error ? err.message : String(err)}`);
+        const summaryContent = await loadFile(existingSummary);
+        if (summaryContent) {
+          summaryOutcome = classifyMilestoneSummaryContent(summaryContent);
         }
-        return { action: "skip" };
       }
 
       // Safety guard (#2675): block completion when VALIDATION verdict is
@@ -969,6 +974,44 @@ export const DISPATCH_RULES: DispatchRule[] = [
         logWarning("dispatch", `verification class check failed: ${err instanceof Error ? err.message : String(err)}`);
       }
 
+      // Disk/DB mismatch handling (#4658): SUMMARY presence alone is not enough.
+      // Apply post-gate policy:
+      // - success summary: reconcile DB and skip re-dispatch
+      // - failure summary: pause/fail-closed
+      // - unknown summary: pause/fail-closed
+      if (existingSummary && isDbAvailable()) {
+        const milestone = getMilestone(mid);
+        const status = milestone?.status ?? "missing";
+
+        if (summaryOutcome === "success") {
+          try {
+            updateMilestoneStatus(mid, "complete", new Date().toISOString());
+            logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB status was "${status}" — reconciled DB to complete (#4658)`);
+            return { action: "skip" };
+          } catch (err) {
+            return {
+              action: "stop",
+              level: "warning",
+              reason: `Milestone ${mid} SUMMARY indicates completion but DB reconciliation failed (${err instanceof Error ? err.message : String(err)}). Auto-mode paused for manual review.`,
+            };
+          }
+        }
+
+        if (summaryOutcome === "failure") {
+          return {
+            action: "stop",
+            level: "warning",
+            reason: `Milestone ${mid} has a failure-path SUMMARY while DB status is "${status}". Auto-mode will not promote completion from failure artifacts. Re-run complete-milestone only after blockers are resolved and verification passes.`,
+          };
+        }
+
+        return {
+          action: "stop",
+          level: "warning",
+          reason: `Milestone ${mid} has an ambiguous SUMMARY while DB status is "${status}". Auto-mode paused instead of promoting completion from file presence alone.`,
+        };
+      }
+
       return {
         action: "dispatch",
         unitType: "complete-milestone",