@opengsd/gsd-pi 1.2.0-dev.84c56d87 → 1.2.0-dev.9ad8ae33

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

@@ -22,7 +22,7 @@ type BlockedAdvanceResult = Extract<AutoAdvanceResult, { kind: "blocked" }>;
 import { debugCount, debugLog, debugTime } from "../debug-logger.js";
 import { reconcileBeforeDispatch } from "../state-reconciliation.js";
 import { isLegalEdge, IllegalPhaseTransitionError } from "../state-transition-matrix.js";
-import { resolveDispatch } from "../auto-dispatch.js";
+import { hasPendingDeepStage, resolveDispatch } from "../auto-dispatch.js";
 import { classifyFailure } from "../recovery-classification.js";
 import { verifyExpectedArtifact, refreshRecoveryDbForArtifact } from "../auto-recovery.js";
 import { invalidateAllCaches } from "../cache.js";
@@ -64,6 +64,13 @@ import {
 import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
 import { getErrorMessage } from "../error-utils.js";
 import { logWarning } from "../workflow-logger.js";
+import { normalizeRealPath } from "../paths.js";
+import {
+  buildDispatchKey,
+  createDispatchHistory,
+  STUCK_WINDOW_SIZE,
+  type DispatchHistory,
+} from "./dispatch-history.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { evaluateAllCompleteSettlement } from "../milestone-settlement.js";
@@ -72,16 +79,6 @@ function now(): number {
   return Date.now();
 }
 
-/**
- * Size of the dispatch-decision ring buffer used by the Auto Orchestration
- * module's stuck-loop detector. When the same `${unitType}:${unitId}` key
- * fills the window, advance() blocks with `action: "stop"`.
- *
- * Mirrors the legacy `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is
- * preserved across the eventual cutover (issue #5791).
- */
-export const STUCK_WINDOW_SIZE = 6;
-
 function noRemainingUnitsOutcome(stateSnapshot: GSDState): AutoTerminalOutcome {
   if (stateSnapshot.phase === "complete") {
     return {
@@ -196,14 +193,25 @@ export async function decideOrchestratorDispatch(
 ): Promise<DispatchDecision> {
   const state = input.stateSnapshot;
   const active = state.activeMilestone;
-  if (!active) return null;
-
   const activeSession = input.session ?? session;
   const activeDispatchBasePath = activeSession?.basePath || dispatchBasePath;
-  if (activeSession && shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath)) {
+  const prefs = loadEffectiveGSDPreferences(activeDispatchBasePath)?.preferences;
+  if (!active) {
+    if (state.phase !== "pre-planning") return null;
+    if (!hasPendingDeepStage(prefs, activeDispatchBasePath)) {
+      return {
+        kind: "blocked",
+        reason: state.nextAction || "No active milestone. Run /gsd unpark <id> or create a new milestone.",
+        action: "stop",
+      };
+    }
+  }
+
+  if (active && activeSession && shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath)) {
     activeSession.currentMilestoneId = active.id;
   }
-  const prefs = loadEffectiveGSDPreferences(activeDispatchBasePath)?.preferences;
+  const dispatchMid = active?.id ?? activeSession?.currentMilestoneId ?? "";
+  const dispatchMidTitle = active?.title ?? "";
 
   // Derive session-derived dispatch inputs the same way phases.ts:runDispatch does
   // (#5789). Prefer caller-supplied values when present so test harnesses and
@@ -235,8 +243,15 @@ export async function decideOrchestratorDispatch(
         ? "true"
         : "false");
 
+  // Only replay a milestone-scoped verification retry when a milestone is
+  // active. Pre-PR (#712 fix), `!active` returned null before reaching this
+  // block, so the retry was preserved for a future tick. The new
+  // pre-planning + deep-pending fall-through must keep that contract:
+  // otherwise a stale execute-task / complete-slice / complete-milestone
+  // retry whose target milestone has since been parked would preempt
+  // project-level deep rules like `discuss-project`.
   const pendingRetry = session?.pendingVerificationRetryDispatch;
-  if (session && pendingRetry) {
+  if (session && pendingRetry && active) {
     session.pendingVerificationRetryDispatch = null;
     const alreadyClosedReason = getAlreadyClosedDispatchReason(
       pendingRetry.unitType,
@@ -258,8 +273,8 @@ export async function decideOrchestratorDispatch(
 
   const action = await resolveDispatch({
     basePath: activeDispatchBasePath,
-    mid: active.id,
-    midTitle: active.title,
+    mid: dispatchMid,
+    midTitle: dispatchMidTitle,
     state,
     prefs,
     session: activeSession,
@@ -303,8 +318,8 @@ export async function decideOrchestratorDispatch(
       prompt: action.prompt,
       pauseAfterUatDispatch: action.pauseAfterDispatch ?? false,
       state,
-      mid: active.id,
-      midTitle: active.title,
+      mid: dispatchMid,
+      midTitle: dispatchMidTitle,
     };
     session.pendingOrchestrationDispatch = pending;
   }
@@ -330,7 +345,9 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   private seq = 0;
   private lastAdvanceKey: string | null = null;
   private lastFinalizedUnitKey: string | null = null;
-  private dispatchKeyWindow: string[] = [];
+  // Dispatch History module (#482): the dispatch-decision window with
+  // cross-session DB rehydration and full detect-stuck rules.
+  private readonly dispatchHistory: DispatchHistory;
   // ADR-030 Phase Transition Invariant: the prior advance's reconciled Phase,
   // the "from" endpoint of the edge check. In-memory; reset on start/resume/stop
   // so the first advance of a session has no edge to assert.
@@ -347,6 +364,16 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     this.runtimeBasePath = context.runtimeBasePath;
     this.s = context.session;
     this.flowId = `auto-orchestrator-${Date.now()}`;
+    this.dispatchHistory = createDispatchHistory({
+      windowSize: STUCK_WINDOW_SIZE,
+      // Same stable scope the auto-loop uses for stuck-state persistence so
+      // rehydration reads the rows the dispatch ledger wrote for this project.
+      resolveScopeId: () =>
+        normalizeRealPath(
+          this.s.scope?.workspace.projectRoot ??
+            (this.s.originalBasePath || this.s.basePath || this.runtimeBasePath),
+        ) || null,
+    });
   }
 
   // ── Live base-path resolution (was the wiring factory's getLiveDispatchBasePath) ──
@@ -765,7 +792,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
    * skipped result) instead of stopping.
    */
   private tryStuckArtifactRecovery(unitType: string, unitId: string): boolean {
-    const key = `${unitType}:${unitId}`;
+    const key = buildDispatchKey(unitType, unitId);
     if (this.lastStuckRecoveryKey === key) return false; // already tried this episode
     const basePath = this.getLiveDispatchBasePath();
     if (!verifyExpectedArtifact(unitType, unitId, basePath)) return false;
@@ -777,7 +804,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     if (!refreshed.ok && refreshed.fatal) return false;
     this.lastStuckRecoveryKey = key;
     invalidateAllCaches();
-    this.dispatchKeyWindow = [];
+    this.dispatchHistory.clearOnRecovery();
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
     return true;
@@ -808,7 +835,12 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async start(_sessionContext: AutoSessionContext): Promise<AutoAdvanceResult> {
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
-    this.dispatchKeyWindow = [];
+    // #482: the DB dispatch ledger is the source of truth across sessions.
+    // Discard any in-memory window and rebuild it from the ledger so a unit
+    // that was re-dispatched in previous sessions is detected as stuck here
+    // instead of silently re-dispatching forever.
+    this.dispatchHistory.clearOnRecovery();
+    this.dispatchHistory.rehydrate();
     this.lastStuckRecoveryKey = null;
     this.lastDerivedPhase = null;
     this.status.phase = "running";
@@ -913,7 +945,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
           this.status.phase = "paused";
           this.status.activeUnit = undefined;
           this.lastAdvanceKey = null;
-          this.dispatchKeyWindow = [];
+          this.dispatchHistory.clearOnRecovery();
           this.bumpTransition();
           this.journalTransition({ name: "advance-blocked", reason: settlementBlock.reason });
           this.postAdvanceRecord(settlementBlock);
@@ -929,7 +961,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         this.status.phase = "stopped";
         this.status.activeUnit = undefined;
         this.lastAdvanceKey = null;
-        this.dispatchKeyWindow = [];
+        this.dispatchHistory.clearOnRecovery();
         this.bumpTransition();
         this.journalTransition({ name: "advance-stopped", reason: stopped.reason });
         this.postAdvanceRecord(stopped);
@@ -979,18 +1011,13 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return blocked;
       }
 
-      const nextKey = `${decision.unitType}:${decision.unitId}`;
-
-      // Record every dispatch decision in the ring buffer before pre-flight
+      // Record every dispatch decision in the history window before pre-flight
       // checks so the stuck-loop detector observes the full decision history
       // (including decisions that idempotency would otherwise short-circuit).
-      // The ring is capped at STUCK_WINDOW_SIZE and evicts oldest-first.
-      this.dispatchKeyWindow.push(nextKey);
-      if (this.dispatchKeyWindow.length > STUCK_WINDOW_SIZE) {
-        this.dispatchKeyWindow.shift();
-      }
+      // The window is capped at STUCK_WINDOW_SIZE and evicts oldest-first.
+      const nextKey = this.dispatchHistory.recordDispatch(decision.unitType, decision.unitId);
 
-      const matchingCount = this.dispatchKeyWindow.filter((k) => k === nextKey).length;
+      const matchingCount = this.dispatchHistory.countMatching(nextKey);
       if (this.lastFinalizedUnitKey === nextKey) {
         // #442: the unit re-dispatched immediately after finalizing may have
         // actually completed on disk with a stale DB. Verify + recover before
@@ -1023,23 +1050,32 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       // checks coexist: idempotency for the common immediate-repeat case,
       // stuck-loop for the saturated-window case.
       if (this.lastAdvanceKey === nextKey && matchingCount < STUCK_WINDOW_SIZE) {
+        // Unit already active — benign no-op. Return skipped so the loop re-polls
+        // without cancelling the in-flight unit (blocked+pause would force-cancel it).
         this.clearPendingDispatch();
-        const blocked: AutoAdvanceResult = { kind: "blocked", reason: "idempotent advance: unit already active", action: "pause" };
+        const skipped: AutoAdvanceResult = { kind: "skipped", reason: "idempotent advance: unit already active" };
         this.journalTransition({
-          name: "advance-blocked",
-          reason: blocked.reason,
+          name: "advance-skipped",
+          reason: skipped.reason,
           unitType: decision.unitType,
           unitId: decision.unitId,
         });
-        this.postAdvanceRecord(blocked);
-        return blocked;
+        this.postAdvanceRecord(skipped);
+        return skipped;
       }
 
-      // Stuck-loop detection: when the ring is saturated with copies of
-      // `nextKey` (count >= STUCK_WINDOW_SIZE), the orchestrator has been
-      // picking the same unit across the whole window and must hard-stop with
-      // a diagnosable reason.
-      if (matchingCount >= STUCK_WINDOW_SIZE) {
+      // Stuck-loop detection: when the window is saturated with copies of
+      // `nextKey` (count >= STUCK_WINDOW_SIZE), consult the Dispatch History
+      // module's full detect-stuck rule set for the verdict instead of the old
+      // bare saturation count. This keeps the saturation threshold (the window
+      // deliberately records benign idempotent repeats, so earlier-firing
+      // rules would false-positive on pause/resume re-advances) while gaining
+      // retry-budget suppression and diagnosable rule reasons. A saturated
+      // window with no verdict means the dispatch ledger says we are inside
+      // the unit's retry-backoff budget — let the retry proceed.
+      const stuckVerdict =
+        matchingCount >= STUCK_WINDOW_SIZE ? this.dispatchHistory.detectStuck() : null;
+      if (stuckVerdict) {
         // #442: before declaring a stuck loop, verify the unit didn't actually
         // complete on disk (stale DB) and recover if so — legacy graduated
         // stuck-recovery parity. Otherwise hard-stop with a diagnosable reason.
@@ -1050,7 +1086,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         this.clearPendingDispatch();
         const blocked: AutoAdvanceResult = {
           kind: "blocked",
-          reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+          reason: `stuck-loop: ${stuckVerdict.reason}`,
           action: "stop",
         };
         this.journalTransition({
@@ -1144,7 +1180,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       if (result.kind === "stopped") {
         this.lastAdvanceKey = null;
         this.lastFinalizedUnitKey = null;
-        this.dispatchKeyWindow = [];
+        this.dispatchHistory.clearOnRecovery();
         this.status.activeUnit = undefined;
       }
       this.bumpTransition();
@@ -1173,8 +1209,14 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async resume(): Promise<AutoAdvanceResult> {
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
-    // Preserve dispatchKeyWindow across resume so stuck-loop detection
-    // accumulates across pause/resume cycles rather than resetting each time.
+    // Preserve the dispatch-history window across an in-process resume so
+    // stuck-loop detection accumulates across pause/resume cycles rather than
+    // resetting each time (#572 regression). When the window is empty (fresh
+    // orchestrator resuming a prior session), rehydrate it from the DB
+    // dispatch ledger so cross-session re-dispatch loops are detected (#482).
+    if (this.dispatchHistory.getRecentWindow().length === 0) {
+      this.dispatchHistory.rehydrate();
+    }
     this.lastStuckRecoveryKey = null;
     // ADR-030: drop the prior "from" — the first advance after resume has no
     // edge to assert (avoids a false illegal-edge across the pause boundary).
@@ -1196,10 +1238,10 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
     this.lastDerivedPhase = null;
-    // Preserve dispatchKeyWindow on pause so stuck-loop detection accumulates
-    // across pause/resume cycles. Only clear on a hard stop.
+    // Preserve the dispatch-history window on pause so stuck-loop detection
+    // accumulates across pause/resume cycles. Only clear on a hard stop.
     if (reason !== "pause") {
-      this.dispatchKeyWindow = [];
+      this.dispatchHistory.clearOnRecovery();
     }
     this.lastStuckRecoveryKey = null;
     this.bumpTransition();
@@ -1213,9 +1255,9 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   }
 
   public async completeActiveUnit(unit: { unitType: string; unitId: string }): Promise<void> {
-    const unitKey = `${unit.unitType}:${unit.unitId}`;
+    const unitKey = buildDispatchKey(unit.unitType, unit.unitId);
     const activeUnitKey = this.status.activeUnit
-      ? `${this.status.activeUnit.unitType}:${this.status.activeUnit.unitId}`
+      ? buildDispatchKey(this.status.activeUnit.unitType, this.status.activeUnit.unitId)
       : null;
     if (activeUnitKey !== unitKey) return;
 
@@ -1233,9 +1275,9 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   }
 
   public async retryActiveUnit(unit: { unitType: string; unitId: string }): Promise<void> {
-    const unitKey = `${unit.unitType}:${unit.unitId}`;
+    const unitKey = buildDispatchKey(unit.unitType, unit.unitId);
     const activeUnitKey = this.status.activeUnit
-      ? `${this.status.activeUnit.unitType}:${this.status.activeUnit.unitId}`
+      ? buildDispatchKey(this.status.activeUnit.unitType, this.status.activeUnit.unitId)
       : null;
     if (activeUnitKey !== unitKey && this.lastFinalizedUnitKey !== unitKey) return;
 

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

@@ -19,9 +19,9 @@ import {
   type PostUnitContext,
   type PreVerificationOpts,
 } from "../auto-post-unit.js";
-import { lastAssistantText } from "../user-input-boundary.js";
-import { resolveEffectiveUnitIsolationMode } from "../preferences.js";
-import type { Phase } from "../types.js";
+import { lastAssistantText } from "../consent-question.js";
+import { resolveEffectiveUnitIsolationMode, getIsolationMode } from "../preferences.js";
+import type { GSDState, Phase } from "../types.js";
 import {
   MAX_RECOVERY_CHARS,
   BUDGET_THRESHOLDS,
@@ -33,6 +33,7 @@ import {
   type IterationData,
 } from "./types.js";
 import { detectStuck } from "./detect-stuck.js";
+import { STUCK_WINDOW_SIZE } from "./dispatch-history.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
 import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "../worktree-root.js";
@@ -61,9 +62,10 @@ 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 { isSliceParallelActive, startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices, getSlice, getTask } from "../gsd-db.js";
+import { isDbAvailable, getMilestone, getMilestoneSlices, getSlice, getTask } from "../gsd-db.js";
 import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
 import { isClosedStatus } from "../status-guards.js";
+import { findUnmergedCompletedMilestones } from "../unmerged-milestone-guard.js";
 import { setRuntimeKv } from "../db/runtime-kv.js";
 import { getLatestForUnit } from "../db/unit-dispatches.js";
 import { reconcileBeforeSpawn } from "../state-reconciliation.js";
@@ -81,11 +83,8 @@ import { parseUnitId } from "../unit-id.js";
 import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js";
 import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
 import { getContextPauseAction } from "../auto-budget.js";
-import {
-  getWorkflowTransportSupportError,
-  getRequiredWorkflowToolsForAutoUnit,
-  supportsStructuredQuestions,
-} from "../workflow-mcp.js";
+import { supportsStructuredQuestions } from "../workflow-mcp.js";
+import { getUnitWorkflowDispatchReadinessError } from "../tool-contract.js";
 import { prepareWorkflowMcpForProject } from "../workflow-mcp-auto-prep.js";
 import {
   applyThinkingLevelForModel,
@@ -107,7 +106,6 @@ import {
 } from "../root-write-leak-guard.js";
 import { classifyError, isTransient } from "../error-classifier.js";
 
-export const STUCK_WINDOW_SIZE = 6;
 const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
 const ZERO_TOOL_PROVIDER_ERROR_PREFIX_RE =
   /^(?:api error(?::|$|\s*\()|provider error(?::|$|\s*\()|request failed\b|(?:http\s*)?(?:429|500|502|503)\b|\b(?:econnreset|etimedout|econnrefused|epipe)\b|socket hang up\b|fetch failed\b|(?:network|connection|server) error(?::|$)|connection (?:reset|refused)(?::|$|\s+by\b)|dns\b.*(?:fail|error|timeout)|unexpected eof\b|stream idle timeout\b|partial response received\b|stream_exhausted\b|terminated(?::|$)|(?:connection|stream|request)\b.{0,40}\bterminated\b|other side closed\b|rate.?limit(?:ed| exceeded| reached| error)|too many requests\b|you(?:'ve| have) (?:hit|reached) your (?:\w+ )?limit\b|.*\b(?:usage|session|weekly|daily|monthly|quota) limit\b|limit\b.{0,40}\bresets?\b|out of extra usage\b|service.?unavailable\b|internal(?: server)? error(?::|$)|internal(?:[_-]server)?[_-]error\b|server[_-]error\b|(?:provider|server|api|model|codex|claude|openai|anthropic|gemini)\b.{0,80}\boverloaded\b|overloaded\b.{0,80}\b(?:provider|server|api|model)\b|context (?:window|length) exceed|context window exceed)/i;
@@ -838,6 +836,39 @@ async function failClosedOnFinalizeTimeout(
   return { action: "break", reason: progressKind };
 }
 
+export async function shouldSkipTerminalMilestoneCloseout(
+  s: AutoSession,
+  state: Pick<GSDState, "phase" | "lastCompletedMilestone" | "activeMilestone">,
+  mid?: string | null,
+): Promise<{ skip: boolean; milestoneId?: string }> {
+  const closeoutMilestoneId = mid ?? s.currentMilestoneId ?? state.lastCompletedMilestone?.id;
+  if (s.completionStopInProgress) {
+    return { skip: true, milestoneId: closeoutMilestoneId };
+  }
+  if (!closeoutMilestoneId) {
+    return { skip: false };
+  }
+  if (isDbAvailable()) refreshWorkflowDatabaseFromDisk();
+  const closeoutBasePath = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+  let closeoutMergePending = false;
+  if (getIsolationMode(closeoutBasePath) !== "none") {
+    try {
+      const blockers = await findUnmergedCompletedMilestones(closeoutBasePath);
+      closeoutMergePending = blockers.some((blocker) => blocker.milestoneId === closeoutMilestoneId);
+    } catch {
+      // Fail open: without git/DB inspection we cannot safely treat closeout as done.
+      closeoutMergePending = true;
+    }
+  }
+  const milestoneAlreadyClosedOut = isDbAvailable()
+    && isClosedStatus(getMilestone(closeoutMilestoneId)?.status ?? "")
+    && !closeoutMergePending;
+  if (milestoneAlreadyClosedOut) {
+    return { skip: true, milestoneId: closeoutMilestoneId };
+  }
+  return { skip: false, milestoneId: closeoutMilestoneId };
+}
+
 // ─── runPreDispatch ───────────────────────────────────────────────────────────
 
 /**
@@ -1279,6 +1310,14 @@ export async function runPreDispatch(
 
   // ── Terminal conditions ──────────────────────────────────────────────
 
+  if (state.phase === "complete") {
+    const closeoutSkip = await shouldSkipTerminalMilestoneCloseout(s, state, mid);
+    if (closeoutSkip.skip) {
+      debugLog("autoLoop", { phase: "complete", reason: "milestone-already-closed", milestoneId: closeoutSkip.milestoneId });
+      return { action: "break", reason: "milestone-complete" };
+    }
+  }
+
   if (!mid) {
     if (s.currentUnit) {
       await deps.closeoutUnit(
@@ -2324,22 +2363,19 @@ export async function runUnitPhase(
     ? `${(s.currentUnitModel as any).provider ?? ""}/${(s.currentUnitModel as any).id ?? ""}`
     : null;
 
-  const compatibilityError = getWorkflowTransportSupportError(
-    s.currentUnitModel?.provider ?? ctx.model?.provider,
-    getRequiredWorkflowToolsForAutoUnit(unitType),
-    {
-      projectRoot: s.basePath,
-      surface: "auto-mode",
-      unitType,
-      authMode: s.currentUnitModel?.provider
-        ? ctx.modelRegistry.getProviderAuthMode(s.currentUnitModel.provider)
-        : ctx.model?.provider
-          ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-          : undefined,
-      baseUrl: (s.currentUnitModel as any)?.baseUrl ?? ctx.model?.baseUrl,
-      activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
-    },
-  );
+  const compatibilityError = getUnitWorkflowDispatchReadinessError({
+    provider: s.currentUnitModel?.provider ?? ctx.model?.provider,
+    projectRoot: s.basePath,
+    surface: "auto-mode",
+    unitType,
+    authMode: s.currentUnitModel?.provider
+      ? ctx.modelRegistry.getProviderAuthMode(s.currentUnitModel.provider)
+      : ctx.model?.provider
+        ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+        : undefined,
+    baseUrl: (s.currentUnitModel as any)?.baseUrl ?? ctx.model?.baseUrl,
+    activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+  });
   const workflowMcpPrepModel = s.currentUnitModel;
   if (compatibilityError) {
     s.currentUnitRouting = prevUnitRouting;
@@ -2409,6 +2445,9 @@ export async function runUnitPhase(
     causedBy: "unit-start",
   });
   s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
+  if (nextDispatchCount <= 1) {
+    s.toolUnavailableRetries = 0;
+  }
   const unitStartSeq = ic.nextSeq();
   deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
   deps.captureAvailableSkills();

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

@@ -212,6 +212,8 @@ export class AutoSession {
   /** Set when a GSD tool execution ends with isError due to malformed/truncated
    *  JSON arguments. Checked by postUnitPreVerification to break retry loops. */
   lastToolInvocationError: string | null = null;
+  /** Consecutive tool-unavailable retries for the current unit (MCP startup race). */
+  toolUnavailableRetries = 0;
   /** Agent-end messages from the just-finished unit, consumed during finalize. */
   lastUnitAgentEndMessages: unknown[] | null = null;
   /** Set when turn-level git action fails during closeout. */
@@ -406,6 +408,7 @@ export class AutoSession {
     this.lastPreExecFailure = null;
     this.preExecRetryCount.clear();
     this.lastToolInvocationError = null;
+    this.toolUnavailableRetries = 0;
     this.lastUnitAgentEndMessages = null;
     this.lastGitActionFailure = null;
     this.lastGitActionStatus = null;

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

@@ -10,10 +10,9 @@ import type {
 
 import { deriveState } from "./state.js";
 import { loadFile } from "./files.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
+import { isDbAvailable, getClosedSliceIds } from "./gsd-db.js";
 import {
-  resolveMilestoneFile, resolveSliceFile, relSliceFile,
+  resolveSliceFile, relSliceFile,
 } from "./paths.js";
 import {
   buildResearchSlicePrompt,
@@ -32,10 +31,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { MinimalModelRegistry } from "./context-budget.js";
 import { pauseAuto } from "./auto.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
-import {
-  getWorkflowTransportSupportError,
-  getRequiredWorkflowToolsForAutoUnit,
-} from "./workflow-mcp.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 
 export async function dispatchDirectPhase(
   ctx: ExtensionCommandContext,
@@ -182,21 +178,9 @@ export async function dispatchDirectPhase(
 
     case "reassess":
     case "reassess-roadmap": {
-      // DB primary path — get completed slices, fall back to file parsing when DB has no data
-      let completedSliceIds: string[] = [];
-      if (isDbAvailable()) {
-        completedSliceIds = getMilestoneSlices(mid).filter(s => s.status === "complete").map(s => s.id);
-      }
-      if (completedSliceIds.length === 0) {
-        // File-based fallback: parse roadmap checkboxes
-        const roadmapPath = resolveMilestoneFile(dispatchBase, mid, "ROADMAP");
-        if (roadmapPath) {
-          const roadmapContent = await loadFile(roadmapPath);
-          if (roadmapContent) {
-            completedSliceIds = parseRoadmap(roadmapContent).slices.filter(s => s.done).map(s => s.id);
-          }
-        }
-      }
+      // DB-authoritative read (ADR-017) — markdown projections are never
+      // consulted for dispatch decisions. No DB rows means no completed slices.
+      const completedSliceIds = isDbAvailable() ? getClosedSliceIds(mid) : [];
       if (completedSliceIds.length === 0) {
         ctx.ui.notify("Cannot dispatch reassess-roadmap: no completed slices.", "warning");
         return;
@@ -222,20 +206,9 @@ export async function dispatchDirectPhase(
       // incomplete) slice. After slice completion, state.activeSlice advances
       // to the next incomplete slice, so we find the last done slice from the
       // roadmap instead (#1693).
-      let uatCompletedSliceIds: string[] = [];
-      if (isDbAvailable()) {
-        uatCompletedSliceIds = getMilestoneSlices(mid).filter(s => s.status === "complete").map(s => s.id);
-      }
-      if (uatCompletedSliceIds.length === 0) {
-        // File-based fallback: parse roadmap checkboxes
-        const roadmapPath = resolveMilestoneFile(dispatchBase, mid, "ROADMAP");
-        if (roadmapPath) {
-          const roadmapContent = await loadFile(roadmapPath);
-          if (roadmapContent) {
-            uatCompletedSliceIds = parseRoadmap(roadmapContent).slices.filter(s => s.done).map(s => s.id);
-          }
-        }
-      }
+      // DB-authoritative read (ADR-017) — no markdown fallback for dispatch
+      // decisions.
+      const uatCompletedSliceIds = isDbAvailable() ? getClosedSliceIds(mid) : [];
       if (uatCompletedSliceIds.length === 0) {
         ctx.ui.notify("Cannot dispatch run-uat: no completed slices.", "warning");
         return;
@@ -280,18 +253,15 @@ export async function dispatchDirectPhase(
       return;
   }
 
-  const compatibilityError = getWorkflowTransportSupportError(
-    ctx.model?.provider,
-    getRequiredWorkflowToolsForAutoUnit(unitType),
-    {
-      projectRoot,
-      surface: "direct phase dispatch",
-      unitType,
-      authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined,
-      baseUrl: ctx.model?.baseUrl,
-      activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
-    },
-  );
+  const compatibilityError = getUnitWorkflowDispatchReadinessError({
+    provider: ctx.model?.provider,
+    projectRoot,
+    surface: "direct phase dispatch",
+    unitType,
+    authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined,
+    baseUrl: ctx.model?.baseUrl,
+    activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+  });
   if (compatibilityError) {
     ctx.ui.notify(compatibilityError, "error");
     return;