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

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

@@ -12,7 +12,7 @@
 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";
@@ -42,21 +42,14 @@ import { isDbAvailable, getSlice, getTask, } from "../gsd-db.js";
 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, } from "./dispatch-history.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { evaluateAllCompleteSettlement } from "../milestone-settlement.js";
 function now() {
     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) {
     if (stateSnapshot.phase === "complete") {
         return {
@@ -118,14 +111,25 @@ function shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath
 export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, session, input) {
     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
     // alternative wirings can inject deterministic snapshots; otherwise pull from
@@ -153,8 +157,15 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
             })
                 ? "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, pendingRetry.unitId);
         if (alreadyClosedReason) {
@@ -172,8 +183,8 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
     }
     const action = await resolveDispatch({
         basePath: activeDispatchBasePath,
-        mid: active.id,
-        midTitle: active.title,
+        mid: dispatchMid,
+        midTitle: dispatchMidTitle,
         state,
         prefs,
         session: activeSession,
@@ -218,8 +229,8 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
             prompt: action.prompt,
             pauseAfterUatDispatch: action.pauseAfterDispatch ?? false,
             state,
-            mid: active.id,
-            midTitle: active.title,
+            mid: dispatchMid,
+            midTitle: dispatchMidTitle,
         };
         session.pendingOrchestrationDispatch = pending;
     }
@@ -244,7 +255,9 @@ export class AutoOrchestrator {
     seq = 0;
     lastAdvanceKey = null;
     lastFinalizedUnitKey = null;
-    dispatchKeyWindow = [];
+    // Dispatch History module (#482): the dispatch-decision window with
+    // cross-session DB rehydration and full detect-stuck rules.
+    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.
@@ -260,6 +273,13 @@ export class AutoOrchestrator {
         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) ──
     getLiveDispatchBasePath() {
@@ -612,7 +632,7 @@ export class AutoOrchestrator {
      * skipped result) instead of stopping.
      */
     tryStuckArtifactRecovery(unitType, unitId) {
-        const key = `${unitType}:${unitId}`;
+        const key = buildDispatchKey(unitType, unitId);
         if (this.lastStuckRecoveryKey === key)
             return false; // already tried this episode
         const basePath = this.getLiveDispatchBasePath();
@@ -627,7 +647,7 @@ export class AutoOrchestrator {
             return false;
         this.lastStuckRecoveryKey = key;
         invalidateAllCaches();
-        this.dispatchKeyWindow = [];
+        this.dispatchHistory.clearOnRecovery();
         this.lastAdvanceKey = null;
         this.lastFinalizedUnitKey = null;
         return true;
@@ -653,7 +673,12 @@ export class AutoOrchestrator {
     async start(_sessionContext) {
         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";
@@ -753,7 +778,7 @@ export class AutoOrchestrator {
                     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);
@@ -769,7 +794,7 @@ export class AutoOrchestrator {
                 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);
@@ -817,16 +842,12 @@ export class AutoOrchestrator {
                 this.postAdvanceRecord(blocked);
                 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();
-            }
-            const matchingCount = this.dispatchKeyWindow.filter((k) => k === nextKey).length;
+            // The window is capped at STUCK_WINDOW_SIZE and evicts oldest-first.
+            const nextKey = this.dispatchHistory.recordDispatch(decision.unitType, decision.unitId);
+            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
@@ -858,22 +879,30 @@ export class AutoOrchestrator {
             // 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 = { kind: "blocked", reason: "idempotent advance: unit already active", action: "pause" };
+                const skipped = { 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.
@@ -884,7 +913,7 @@ export class AutoOrchestrator {
                 this.clearPendingDispatch();
                 const blocked = {
                     kind: "blocked",
-                    reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+                    reason: `stuck-loop: ${stuckVerdict.reason}`,
                     action: "stop",
                 };
                 this.journalTransition({
@@ -974,7 +1003,7 @@ export class AutoOrchestrator {
             if (result.kind === "stopped") {
                 this.lastAdvanceKey = null;
                 this.lastFinalizedUnitKey = null;
-                this.dispatchKeyWindow = [];
+                this.dispatchHistory.clearOnRecovery();
                 this.status.activeUnit = undefined;
             }
             this.bumpTransition();
@@ -1003,8 +1032,14 @@ export class AutoOrchestrator {
     async resume() {
         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).
@@ -1025,10 +1060,10 @@ export class AutoOrchestrator {
         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();
@@ -1040,9 +1075,9 @@ export class AutoOrchestrator {
         return { ...this.status, activeUnit: this.status.activeUnit ? { ...this.status.activeUnit } : undefined };
     }
     async completeActiveUnit(unit) {
-        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;
@@ -1059,9 +1094,9 @@ export class AutoOrchestrator {
         });
     }
     async retryActiveUnit(unit) {
-        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/dist/resources/extensions/gsd/auto/phases.js

@@ -10,10 +10,11 @@
  */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { USER_DRIVEN_DEEP_UNITS, isAwaitingUserInput, } from "../auto-post-unit.js";
-import { lastAssistantText } from "../user-input-boundary.js";
-import { resolveEffectiveUnitIsolationMode } from "../preferences.js";
+import { lastAssistantText } from "../consent-question.js";
+import { resolveEffectiveUnitIsolationMode, getIsolationMode } from "../preferences.js";
 import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, MAX_FINALIZE_TIMEOUTS, } 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";
@@ -34,9 +35,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";
@@ -49,7 +51,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, floorThinkingLevelForUnit, getRegisteredToolSnapshot, getToolBaselineSnapshot, } from "../auto-model-selection.js";
 import { resolveManifest } from "../unit-context-manifest.js";
@@ -60,7 +63,6 @@ import { buildPhaseHandoffOutcome, setAutoActiveStatus, setAutoOutcomeWidget } f
 import { getConsecutiveDispatchBlocker } from "../dispatch-guard.js";
 import { captureRootDirtySnapshot, detectRootWriteLeak, formatRootWriteLeakMessage, } 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;
 const ZERO_TOOL_PROVIDER_ERROR_SIGNAL_RE = /(?:\b(?:http|status(?: code)?|code|error:)\s*(?:429|500|502|503)\b|\b(?:api|provider) error\s*[:(]?\s*(?:429|500|502|503)\b|\b(?:typeerror|error):\s*(?:fetch failed\b|socket hang up\b|terminated(?::|$)|connection (?:reset|refused)(?::|$|\s+by\b)|(?:network|connection|server) error(?::|$)|stream idle timeout\b|partial response received\b|unexpected eof\b)|\b(?:server_error|api_error|stream_exhausted(?:_without_result)?)\b|\b(?:econnreset|etimedout|econnrefused|epipe)\b|context (?:window|length) exceed|context window exceed)/i;
@@ -600,6 +602,36 @@ async function failClosedOnFinalizeTimeout(ic, iterData, loopState, stage, start
     drainLogs();
     return { action: "break", reason: progressKind };
 }
+export async function shouldSkipTerminalMilestoneCloseout(s, state, mid) {
+    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 ───────────────────────────────────────────────────────────
 /**
  * Phase 1: Pre-dispatch — resource guard, health gate, state derivation,
@@ -962,6 +994,13 @@ export async function runPreDispatch(ic, loopState) {
         deps.setActiveMilestoneId(s.basePath, mid);
     }
     // ── 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(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
@@ -1769,7 +1808,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     s.currentDispatchedModelId = s.currentUnitModel
         ? `${s.currentUnitModel.provider ?? ""}/${s.currentUnitModel.id ?? ""}`
         : null;
-    const compatibilityError = getWorkflowTransportSupportError(s.currentUnitModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForAutoUnit(unitType), {
+    const compatibilityError = getUnitWorkflowDispatchReadinessError({
+        provider: s.currentUnitModel?.provider ?? ctx.model?.provider,
         projectRoot: s.basePath,
         surface: "auto-mode",
         unitType,
@@ -1848,6 +1888,9 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         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/dist/resources/extensions/gsd/auto/session.js

@@ -126,6 +126,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 = 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 = null;
     /** Set when turn-level git action fails during closeout. */
@@ -306,6 +308,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/dist/resources/extensions/gsd/auto-direct-dispatch.js

@@ -4,14 +4,13 @@
  */
 import { deriveState } from "./state.js";
 import { loadFile } from "./files.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { resolveMilestoneFile, resolveSliceFile, relSliceFile, } from "./paths.js";
+import { isDbAvailable, getClosedSliceIds } from "./gsd-db.js";
+import { resolveSliceFile, relSliceFile, } from "./paths.js";
 import { buildResearchSlicePrompt, buildResearchMilestonePrompt, buildPlanSlicePrompt, buildPlanMilestonePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReassessRoadmapPrompt, buildRunUatPrompt, buildReplanSlicePrompt, } from "./auto-prompts.js";
 import { loadEffectiveGSDPreferences } from "./preferences.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, pi, phase, base) {
     const state = await deriveState(base);
     const mid = state.activeMilestone?.id;
@@ -135,21 +134,9 @@ export async function dispatchDirectPhase(ctx, pi, phase, base) {
         }
         case "reassess":
         case "reassess-roadmap": {
-            // DB primary path — get completed slices, fall back to file parsing when DB has no data
-            let completedSliceIds = [];
-            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;
@@ -173,20 +160,9 @@ export async function dispatchDirectPhase(ctx, pi, phase, base) {
             // 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 = [];
-            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;
@@ -225,7 +201,8 @@ export async function dispatchDirectPhase(ctx, pi, phase, base) {
             ctx.ui.notify(`Unknown phase "${phase}". Valid phases: research, plan, execute, complete, validate, reassess, uat, replan.`, "warning");
             return;
     }
-    const compatibilityError = getWorkflowTransportSupportError(ctx.model?.provider, getRequiredWorkflowToolsForAutoUnit(unitType), {
+    const compatibilityError = getUnitWorkflowDispatchReadinessError({
+        provider: ctx.model?.provider,
         projectRoot,
         surface: "direct phase dispatch",
         unitType,