@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -9,9 +9,10 @@
 // the real collaborators (state-reconciliation, doctor-proactive,
 // auto-dispatch, recovery-classification, tool-contract, worktree-safety,
 // uok/gate-runner, journal, session-lock, ctx.ui.notify) directly.
-import { debugCount, debugTime } from "../debug-logger.js";
+import { debugCount, debugLog, debugTime } from "../debug-logger.js";
 import { reconcileBeforeDispatch } from "../state-reconciliation.js";
-import { resolveDispatch } from "../auto-dispatch.js";
+import { isLegalEdge, IllegalPhaseTransitionError } from "../state-transition-matrix.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";
@@ -24,44 +25,60 @@ import { checkResourcesStale, autoWorktreeBranch, mergeMilestoneToMain } from ".
 import { getSessionLockStatus } from "../session-lock.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { emitJournalEvent as _emitJournalEvent } from "../journal.js";
-import { loadEffectiveGSDPreferences, getIsolationMode } from "../preferences.js";
-import { detectWorktreeName, resolveProjectRoot } from "../worktree.js";
+import { loadEffectiveGSDPreferences, loadEffectiveGSDPreferencesWithRegistry, getIsolationMode, resolveEffectiveUnitIsolationMode, resolveProfileAnchorProvider } from "../preferences.js";
+import { detectWorktreeName, getMainBranch, resolveProjectRoot, resolveWorktreeProjectRoot, } from "../worktree.js";
+import { getPriorSliceCompletionBlocker } from "../dispatch-guard.js";
 import { GitServiceImpl } from "../git-service.js";
 import { WorktreeStateProjection } from "../worktree-state-projection.js";
 import { WorktreeLifecycle } from "../worktree-lifecycle.js";
+import { createMilestoneMergeTransaction } from "../milestone-merge-transaction.js";
 import { createWorkspace, scopeMilestone } from "../workspace.js";
 import { supportsStructuredQuestions } from "../workflow-mcp.js";
-import { getToolBaselineSnapshot } from "../auto-model-selection.js";
+import { getRegisteredToolSnapshot, getToolBaselineSnapshot } from "../auto-model-selection.js";
 import { deriveState } from "../state.js";
 import { parseUnitId } from "../unit-id.js";
 import { isClosedStatus } from "../status-guards.js";
-import { isDbAvailable, getSlice, getTask, refreshOpenDatabaseFromDisk, } from "../gsd-db.js";
+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";
+import { hasHeldMilestoneLease, reclaimMissingMilestoneLease } from "./milestone-lease-reclaim.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).
+ * Optional override for the post-settlement markdown projection rebuild
+ * (mergePendingCompleteMilestone). Production leaves this null so the real
+ * rebuild runs; tests inject a throwing function to deterministically exercise
+ * the best-effort failure path (orchestrator.ts:637), which is otherwise only
+ * reachable by driving advance() through a full merge-pending milestone
+ * settlement and then contriving a projection-rebuild fault.
+ * @internal
  */
-export const STUCK_WINDOW_SIZE = 6;
-function noRemainingUnitsReason(stateSnapshot) {
+let _projectionRebuildFn = null;
+function noRemainingUnitsOutcome(stateSnapshot) {
     if (stateSnapshot.phase === "complete") {
-        return "all milestones complete";
+        return {
+            code: "all-complete",
+            displayReason: "All milestones complete",
+            allMilestonesComplete: true,
+        };
     }
-    return "no remaining units";
+    return {
+        code: "no-remaining-units",
+        displayReason: "No remaining units",
+        allMilestonesComplete: false,
+    };
 }
 function getAlreadyClosedDispatchReason(unitType, unitId) {
     if (!isDbAvailable())
         return null;
-    refreshOpenDatabaseFromDisk();
+    refreshWorkflowDatabaseFromDisk();
     const { milestone, slice, task } = parseUnitId(unitId);
     if (unitType === "execute-task" && milestone && slice && task) {
         const row = getTask(milestone, slice, task);
@@ -105,14 +122,28 @@ 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 = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, activeDispatchBasePath, resolveProfileAnchorProvider(ctx.model?.provider, session?.autoModeStartModel?.provider), activeSession?.autoModeStartModel
+        ? `${activeSession.autoModeStartModel.provider}/${activeSession.autoModeStartModel.id}`
+        : undefined)?.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;
+        activeSession.milestoneLeaseToken = null;
     }
-    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
@@ -127,6 +158,7 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
     // active set may be narrowed by the prior unit before selectAndApplyModel
     // restores it, causing false transport-preflight failures (#477 follow-up).
     const activeTools = getToolBaselineSnapshot(pi);
+    const registeredTools = getRegisteredToolSnapshot(pi);
     // Mirrors runDispatch: deep-planning keeps approval gates in plain chat
     // because structured questions can be cancelled outside the chat turn on
     // some transports.
@@ -139,8 +171,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) {
@@ -158,8 +197,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,
@@ -168,6 +207,7 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
         sessionProvider,
         modelRegistry,
         activeTools,
+        registeredTools,
         sessionAuthMode: authMode,
         sessionBaseUrl: ctx.model?.baseUrl,
     });
@@ -203,8 +243,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;
     }
@@ -229,7 +269,13 @@ 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.
+    lastDerivedPhase = null;
     // #442: the unit key we last attempted graduated stuck-recovery for. Bounds
     // recovery to one attempt per stuck episode per run (reset on start/resume/
     // stop), mirroring the legacy Level-1-then-Level-2 escalation in phases.ts.
@@ -241,6 +287,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() {
@@ -343,12 +396,17 @@ export class AutoOrchestrator {
         }
     }
     // ── UokGateAdapter (folded) ──────────────────────────────────────────────
-    async emitUokGate(input) {
+    resolveUokGateContext() {
         const activeBasePath = this.getLiveDispatchBasePath();
-        const prefs = loadEffectiveGSDPreferences(activeBasePath)?.preferences;
-        const uokFlags = resolveUokFlags(prefs);
-        if (!uokFlags.gates)
+        const prefs = loadEffectiveGSDPreferencesWithRegistry(this.ctx.modelRegistry, activeBasePath, resolveProfileAnchorProvider(this.ctx.model?.provider, this.s.autoModeStartModel?.provider), this.s.autoModeStartModel
+            ? `${this.s.autoModeStartModel.provider}/${this.s.autoModeStartModel.id}`
+            : undefined)?.preferences;
+        return { activeBasePath, uokFlags: resolveUokFlags(prefs) };
+    }
+    async emitUokGate(input) {
+        if (!input.uokFlags.gates)
             return;
+        const activeBasePath = input.activeBasePath;
         const milestoneId = input.milestoneId ?? this.s.currentMilestoneId ?? undefined;
         try {
             const { UokGateRunner } = await import("../uok/gate-runner.js");
@@ -412,6 +470,78 @@ export class AutoOrchestrator {
     decideNextUnit(input) {
         return decideOrchestratorDispatch(this.ctx, this.pi, this.dispatchBasePath, this.s, input);
     }
+    evaluateNoRemainingUnitsSettlement(stateSnapshot) {
+        const settlement = evaluateAllCompleteSettlement({
+            milestoneId: this.s.currentMilestoneId ?? stateSnapshot.activeMilestone?.id,
+            statePhase: stateSnapshot.phase,
+            basePath: this.s.basePath || this.getLiveDispatchBasePath(),
+            originalBasePath: this.s.originalBasePath || this.runtimeBasePath,
+            milestoneMerged: this.s.milestoneMergedInPhases,
+        });
+        this.s.milestoneSettlement = settlement;
+        if (settlement.ok)
+            return null;
+        return {
+            kind: "blocked",
+            reason: settlement.message,
+            action: settlement.action,
+            stateSnapshot,
+            terminalOutcome: {
+                code: "settlement-blocked",
+                displayReason: settlement.message,
+                nextAction: settlement.nextAction,
+                milestoneId: settlement.milestoneId,
+                allMilestonesComplete: false,
+            },
+        };
+    }
+    async mergePendingCompleteMilestone(milestoneId) {
+        const result = this.buildLifecycle().exitMilestone(milestoneId, { merge: true }, this.ctx.ui);
+        if (!result.ok) {
+            const detail = result.cause instanceof Error
+                ? result.cause.message
+                : result.reason;
+            return {
+                ok: false,
+                reason: `Milestone ${milestoneId} is complete, but the system-owned merge failed: ${detail}`,
+            };
+        }
+        this.s.milestoneMergedInPhases = true;
+        this.s.milestoneSettlement = { ok: true, reason: "settled" };
+        try {
+            const projectRoot = this.s.originalBasePath || this.s.canonicalProjectRoot || this.runtimeBasePath;
+            // Test seam: when _projectionRebuildFn is injected, route the rebuild
+            // through it so the best-effort failure path (:637) is deterministically
+            // reachable. Production leaves it null → real rebuildMarkdownProjectionsFromDb.
+            if (_projectionRebuildFn) {
+                await _projectionRebuildFn(projectRoot);
+            }
+            else {
+                const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+                await rebuildMarkdownProjectionsFromDb(projectRoot);
+            }
+        }
+        catch (err) {
+            logWarning("engine", `markdown projection rebuild after settlement merge failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { ok: true };
+    }
+    clearPendingDispatch() {
+        this.s.pendingOrchestrationDispatch = null;
+    }
+    findPriorSliceCompletionBlocker(unitType, unitId) {
+        const guardBasePath = resolveWorktreeProjectRoot(this.getLiveDispatchBasePath(), this.s.originalBasePath);
+        let mainBranch = "main";
+        try {
+            mainBranch = getMainBranch(guardBasePath);
+        }
+        catch (err) {
+            // Preserve legacy dispatch behavior: fall back to main when branch
+            // discovery fails, then let the guard make the progression decision.
+            logWarning("engine", `branch discovery failed, falling back to main: ${getErrorMessage(err)}`, { file: "orchestrator.ts" });
+        }
+        return getPriorSliceCompletionBlocker(guardBasePath, mainBranch, unitType, unitId);
+    }
     // ── ToolContractAdapter (folded) ─────────────────────────────────────────
     compileUnitToolContract(unitType) {
         const result = compileUnitToolContract(unitType);
@@ -421,8 +551,7 @@ export class AutoOrchestrator {
     }
     // ── WorktreeAdapter (folded) ─────────────────────────────────────────────
     getEffectiveUnitIsolationMode(basePath) {
-        const configuredMode = getIsolationMode(basePath);
-        return configuredMode === "worktree" && this.s.isolationDegraded ? "branch" : configuredMode;
+        return resolveEffectiveUnitIsolationMode(getIsolationMode(basePath), this.s.isolationDegraded, this.s.strandedRecoveryIsolationMode);
     }
     buildLifecycle() {
         return new WorktreeLifecycle(this.s, {
@@ -431,7 +560,7 @@ export class AutoOrchestrator {
                 return new GitServiceImpl(basePath, gitConfig);
             },
             worktreeProjection: new WorktreeStateProjection(),
-            mergeMilestoneToMain,
+            mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
         });
     }
     rebuildScope(rawPath, milestoneId) {
@@ -457,9 +586,6 @@ export class AutoOrchestrator {
                 reason: `No Unit manifest is registered for ${unitType}`,
             };
         }
-        if (isolationMode !== "worktree") {
-            return { ok: true, reason: "not-required" };
-        }
         const writeScope = manifest.tools.mode === "all" || manifest.tools.mode === "docs"
             ? "source-writing"
             : "planning-only";
@@ -467,7 +593,21 @@ export class AutoOrchestrator {
         const activeBasePath = this.getLiveDispatchBasePath();
         const snapshot = await deriveState(activeBasePath);
         const milestoneId = snapshot.activeMilestone?.id ?? null;
-        const expectedBranch = milestoneId ? autoWorktreeBranch(milestoneId) : null;
+        const buildExpectedBranch = (mode) => mode !== "none" && milestoneId ? autoWorktreeBranch(milestoneId) : null;
+        // The milestone lease coordinates concurrent workers on an isolated
+        // milestone worktree/branch. `none` mode has no per-milestone isolation
+        // and does not reliably claim a lease, so requiring one there would
+        // falsely fail dispatch; enforce it only in isolated modes.
+        const buildLease = (mode) => milestoneId && this.s.workerId
+            ? {
+                required: writeScope === "source-writing" && mode !== "none",
+                held: hasHeldMilestoneLease(this.s, milestoneId),
+                owner: this.s.workerId,
+            }
+            : undefined;
+        if (writeScope === "source-writing") {
+            reclaimMissingMilestoneLease(this.s, milestoneId, isolationMode, "orchestrator");
+        }
         let result = safety.validateUnitRoot({
             unitType,
             unitId,
@@ -476,7 +616,8 @@ export class AutoOrchestrator {
             unitRoot: activeBasePath,
             milestoneId,
             isolationMode,
-            expectedBranch,
+            expectedBranch: buildExpectedBranch(isolationMode),
+            lease: buildLease(isolationMode),
         });
         if (!result.ok) {
             const repaired = await repairAutoWorktreeSafetyFailure({
@@ -494,16 +635,20 @@ export class AutoOrchestrator {
                     this.rebuildScope(this.s.basePath, this.s.currentMilestoneId);
                     return { ok: true };
                 },
-                revalidate: () => safety.validateUnitRoot({
-                    unitType,
-                    unitId,
-                    writeScope,
-                    projectRoot: this.runtimeBasePath,
-                    unitRoot: this.getLiveDispatchBasePath(),
-                    milestoneId,
-                    isolationMode: this.getEffectiveUnitIsolationMode(this.runtimeBasePath),
-                    expectedBranch,
-                }),
+                revalidate: () => {
+                    const revalidatedMode = this.getEffectiveUnitIsolationMode(this.runtimeBasePath);
+                    return safety.validateUnitRoot({
+                        unitType,
+                        unitId,
+                        writeScope,
+                        projectRoot: this.runtimeBasePath,
+                        unitRoot: this.getLiveDispatchBasePath(),
+                        milestoneId,
+                        isolationMode: revalidatedMode,
+                        expectedBranch: buildExpectedBranch(revalidatedMode),
+                        lease: buildLease(revalidatedMode),
+                    });
+                },
             });
             result = repaired.result;
             if (result.ok) {
@@ -521,6 +666,21 @@ export class AutoOrchestrator {
         const recovery = classifyFailure(input);
         return { action: recovery.action, reason: recovery.reason };
     }
+    /**
+     * ADR-030 Phase Transition Invariant (advisory mode). The matrix is an
+     * assertion, not a decision-maker — deriveState already chose the phase; we
+     * only observe illegal *derived* edges that survived reconciliation. The
+     * matrix is still a sparse hardening spec, so this is telemetry-only (no
+     * block) until it is expanded into a validated legal-edge graph. To enforce:
+     * `throw violation;` instead of logging — recovery-classification maps
+     * IllegalPhaseTransitionError to kind "illegal-transition" (escalate).
+     */
+    observePhaseTransition(from, to) {
+        if (isLegalEdge(from, to))
+            return;
+        const violation = new IllegalPhaseTransitionError(from, to);
+        debugLog("phase-transition-advisory", { from, to, message: violation.message });
+    }
     // ── Lifecycle verbs ──────────────────────────────────────────────────────
     /**
      * #442: graduated stuck recovery, ported from the legacy
@@ -538,7 +698,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();
@@ -553,7 +713,7 @@ export class AutoOrchestrator {
             return false;
         this.lastStuckRecoveryKey = key;
         invalidateAllCaches();
-        this.dispatchKeyWindow = [];
+        this.dispatchHistory.clearOnRecovery();
         this.lastAdvanceKey = null;
         this.lastFinalizedUnitKey = null;
         return true;
@@ -579,8 +739,19 @@ export class AutoOrchestrator {
     async start(_sessionContext) {
         this.lastAdvanceKey = null;
         this.lastFinalizedUnitKey = null;
-        this.dispatchKeyWindow = [];
+        // #852: a fresh user-triggered session must start with a clean stuck window.
+        // Cross-session rehydration at start() was removed because it caused false
+        // stuck-loop verdicts when prior sessions left consecutive finalize-retry
+        // entries in unit_dispatches — the new session would be killed before its
+        // first dispatch ran. Within-session stuck detection (accumulated through
+        // recordDispatch() calls during advance()) remains fully active and catches
+        // genuine stuck patterns after STUCK_WINDOW_SIZE dispatches.
+        //
+        // resume() retains cross-session rehydration: an interrupted session resuming
+        // after a crash should see the dispatch history it had been accumulating.
+        this.dispatchHistory.clearOnRecovery();
         this.lastStuckRecoveryKey = null;
+        this.lastDerivedPhase = null;
         this.status.phase = "running";
         this.bumpTransition();
         this.journalTransition({ name: "start" });
@@ -592,9 +763,11 @@ export class AutoOrchestrator {
         const stopAdvanceTimer = debugTime("orchestrator-advance");
         try {
             this.ensureLockOwnership();
+            const uokGateContext = this.resolveUokGateContext();
             const staleMsg = this.checkResourcesStale();
             if (staleMsg) {
                 await this.emitUokGate({
+                    ...uokGateContext,
                     gateId: "resource-version-guard",
                     gateType: "policy",
                     outcome: "fail",
@@ -608,6 +781,7 @@ export class AutoOrchestrator {
                 return blocked;
             }
             await this.emitUokGate({
+                ...uokGateContext,
                 gateId: "resource-version-guard",
                 gateType: "policy",
                 outcome: "pass",
@@ -617,6 +791,7 @@ export class AutoOrchestrator {
             const gate = await this.preAdvanceGate();
             if (gate.kind === "fail") {
                 await this.emitUokGate({
+                    ...uokGateContext,
                     gateId: "pre-dispatch-health-gate",
                     gateType: "execution",
                     outcome: "manual-attention",
@@ -635,6 +810,7 @@ export class AutoOrchestrator {
             }
             if (gate.kind === "threw") {
                 await this.emitUokGate({
+                    ...uokGateContext,
                     gateId: "pre-dispatch-health-gate",
                     gateType: "execution",
                     outcome: "manual-attention",
@@ -646,6 +822,7 @@ export class AutoOrchestrator {
             }
             else {
                 await this.emitUokGate({
+                    ...uokGateContext,
                     gateId: "pre-dispatch-health-gate",
                     gateType: "execution",
                     outcome: "pass",
@@ -666,17 +843,64 @@ export class AutoOrchestrator {
                 this.postAdvanceRecord(blocked);
                 return blocked;
             }
+            const reconciledPhase = reconciliation.stateSnapshot.phase;
+            if (this.lastDerivedPhase !== null) {
+                this.observePhaseTransition(this.lastDerivedPhase, reconciledPhase);
+            }
+            this.lastDerivedPhase = reconciledPhase;
             const decision = await this.decideNextUnit({ stateSnapshot: reconciliation.stateSnapshot });
             if (!decision) {
+                const settlementBlock = this.evaluateNoRemainingUnitsSettlement(reconciliation.stateSnapshot);
+                if (settlementBlock) {
+                    const settlement = this.s.milestoneSettlement;
+                    if (settlement && !settlement.ok && settlement.reason === "merge-pending") {
+                        const merged = await this.mergePendingCompleteMilestone(settlement.milestoneId);
+                        if (merged.ok) {
+                            const terminalOutcome = noRemainingUnitsOutcome(reconciliation.stateSnapshot);
+                            const stopped = {
+                                kind: "stopped",
+                                reason: terminalOutcome.displayReason,
+                                stateSnapshot: reconciliation.stateSnapshot,
+                                terminalOutcome,
+                            };
+                            this.status.phase = "stopped";
+                            this.status.activeUnit = undefined;
+                            this.lastAdvanceKey = null;
+                            this.dispatchHistory.clearOnRecovery();
+                            this.bumpTransition();
+                            this.journalTransition({ name: "advance-stopped", reason: stopped.reason });
+                            this.postAdvanceRecord(stopped);
+                            return stopped;
+                        }
+                        settlementBlock.reason = merged.reason;
+                        settlementBlock.terminalOutcome = {
+                            code: "settlement-blocked",
+                            displayReason: merged.reason,
+                            nextAction: `Fix the merge failure, then retry \`/gsd dispatch complete-milestone ${settlement.milestoneId}\`.`,
+                            milestoneId: settlement.milestoneId,
+                            allMilestonesComplete: false,
+                        };
+                    }
+                    this.status.phase = "paused";
+                    this.status.activeUnit = undefined;
+                    this.lastAdvanceKey = null;
+                    this.dispatchHistory.clearOnRecovery();
+                    this.bumpTransition();
+                    this.journalTransition({ name: "advance-blocked", reason: settlementBlock.reason });
+                    this.postAdvanceRecord(settlementBlock);
+                    return settlementBlock;
+                }
+                const terminalOutcome = noRemainingUnitsOutcome(reconciliation.stateSnapshot);
                 const stopped = {
                     kind: "stopped",
-                    reason: noRemainingUnitsReason(reconciliation.stateSnapshot),
+                    reason: terminalOutcome.displayReason,
                     stateSnapshot: reconciliation.stateSnapshot,
+                    terminalOutcome,
                 };
                 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);
@@ -706,23 +930,39 @@ 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
+            const priorSliceBlocker = this.findPriorSliceCompletionBlocker(decision.unitType, decision.unitId);
+            if (priorSliceBlocker) {
+                this.clearPendingDispatch();
+                const blocked = {
+                    kind: "blocked",
+                    reason: priorSliceBlocker,
+                    action: "stop",
+                    stateSnapshot: reconciliation.stateSnapshot,
+                };
+                this.journalTransition({
+                    name: "advance-blocked",
+                    reason: blocked.reason,
+                    unitType: decision.unitType,
+                    unitId: decision.unitId,
+                });
+                this.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            // 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
                 // hard-stopping (legacy graduated stuck-recovery parity).
                 if (this.tryStuckArtifactRecovery(decision.unitType, decision.unitId)) {
+                    this.clearPendingDispatch();
                     return this.stuckRecovered(decision, reconciliation.stateSnapshot);
                 }
+                this.clearPendingDispatch();
                 const blocked = {
                     kind: "blocked",
                     reason: `state did not advance after finalized ${decision.unitType} ${decision.unitId}`,
@@ -745,30 +985,41 @@ 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) {
-                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active", action: "pause" };
+                // 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 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.
                 if (this.tryStuckArtifactRecovery(decision.unitType, decision.unitId)) {
+                    this.clearPendingDispatch();
                     return this.stuckRecovered(decision, reconciliation.stateSnapshot);
                 }
+                this.clearPendingDispatch();
                 const blocked = {
                     kind: "blocked",
-                    reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+                    reason: `stuck-loop: ${stuckVerdict.reason}`,
                     action: "stop",
                 };
                 this.journalTransition({
@@ -782,6 +1033,7 @@ export class AutoOrchestrator {
             }
             const contract = this.compileUnitToolContract(decision.unitType);
             if (!contract.ok) {
+                this.clearPendingDispatch();
                 const blocked = {
                     kind: "blocked",
                     reason: contract.reason,
@@ -799,6 +1051,7 @@ export class AutoOrchestrator {
             }
             const worktree = await this.prepareWorktreeForUnit(decision.unitType, decision.unitId);
             if (!worktree.ok) {
+                this.clearPendingDispatch();
                 const blocked = {
                     kind: "blocked",
                     reason: worktree.reason,
@@ -856,7 +1109,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();
@@ -885,8 +1138,18 @@ export class AutoOrchestrator {
     async resume() {
         this.lastAdvanceKey = null;
         this.lastFinalizedUnitKey = null;
-        this.dispatchKeyWindow = [];
+        // 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).
+        this.lastDerivedPhase = null;
         this.status.phase = "running";
         this.bumpTransition();
         this.journalTransition({ name: "resume" });
@@ -902,7 +1165,12 @@ export class AutoOrchestrator {
         this.status.activeUnit = undefined;
         this.lastAdvanceKey = null;
         this.lastFinalizedUnitKey = null;
-        this.dispatchKeyWindow = [];
+        this.lastDerivedPhase = null;
+        // 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.dispatchHistory.clearOnRecovery();
+        }
         this.lastStuckRecoveryKey = null;
         this.bumpTransition();
         this.journalTransition({ name: "stop", reason });
@@ -913,9 +1181,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;
@@ -932,9 +1200,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;
@@ -993,3 +1261,16 @@ export function resolveLiveOrchestratorBasePath(input) {
 export function createAutoOrchestrator(context) {
     return new AutoOrchestrator(context);
 }
+/**
+ * Inject an override for the post-settlement markdown projection rebuild,
+ * returning a function that restores the default (real rebuild) behavior. Used
+ * by tests to deterministically exercise the best-effort rebuild-failure path
+ * (orchestrator.ts:637) — otherwise only reachable by driving advance() through
+ * a full merge-pending milestone settlement and then contriving a projection
+ * fault. No production caller.
+ * @internal
+ */
+export function _setProjectionRebuildFnForTests(fn) {
+    _projectionRebuildFn = fn;
+    return () => { _projectionRebuildFn = null; };
+}