@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

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

@@ -12,14 +12,17 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
-import type { AutoAdvanceResult, AutoOrchestrationModule, AutoSessionContext, AutoStatus } from "./contracts.js";
+import type { AutoAdvanceResult, AutoOrchestrationModule, AutoSessionContext, AutoStatus, AutoTerminalOutcome } from "./contracts.js";
 import type { AutoSession, PendingOrchestrationDispatch } from "./session.js";
-import type { GSDState } from "../types.js";
+import type { GSDState, Phase } from "../types.js";
 import type { MinimalModelRegistry } from "../context-budget.js";
 
-import { debugCount, debugTime } from "../debug-logger.js";
+type BlockedAdvanceResult = Extract<AutoAdvanceResult, { kind: "blocked" }>;
+
+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";
@@ -35,14 +38,21 @@ 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";
@@ -50,32 +60,52 @@ import {
   isDbAvailable,
   getSlice,
   getTask,
-  refreshOpenDatabaseFromDisk,
 } 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,
+  type DispatchHistory,
+} 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";
+
+type UokFlags = ReturnType<typeof resolveUokFlags>;
 
 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).
+ * 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;
+let _projectionRebuildFn: ((projectRoot: string) => Promise<void>) | null = null;
 
-function noRemainingUnitsReason(stateSnapshot: GSDState): string {
+function noRemainingUnitsOutcome(stateSnapshot: GSDState): AutoTerminalOutcome {
   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,
+  };
 }
 
 /**
@@ -118,7 +148,7 @@ export interface DispatchDecisionInput {
 
 function getAlreadyClosedDispatchReason(unitType: string, unitId: string): string | null {
   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);
@@ -177,14 +207,33 @@ 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 = 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
@@ -201,6 +250,7 @@ export async function decideOrchestratorDispatch(
   // 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.
@@ -215,8 +265,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,
@@ -238,8 +295,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,
@@ -248,6 +305,7 @@ export async function decideOrchestratorDispatch(
     sessionProvider,
     modelRegistry,
     activeTools,
+    registeredTools,
     sessionAuthMode: authMode,
     sessionBaseUrl: ctx.model?.baseUrl,
   });
@@ -282,8 +340,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;
   }
@@ -309,7 +367,13 @@ 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.
+  private lastDerivedPhase: Phase | null = 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.
@@ -322,6 +386,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) ──
@@ -445,6 +519,19 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
   // ── UokGateAdapter (folded) ──────────────────────────────────────────────
 
+  private resolveUokGateContext(): { activeBasePath: string; uokFlags: UokFlags } {
+    const activeBasePath = this.getLiveDispatchBasePath();
+    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) };
+  }
+
   private async emitUokGate(input: {
     gateId: string;
     gateType: "policy" | "execution";
@@ -453,11 +540,11 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     rationale: string;
     findings?: string;
     milestoneId?: string;
+    activeBasePath: string;
+    uokFlags: UokFlags;
   }): Promise<void> {
-    const activeBasePath = this.getLiveDispatchBasePath();
-    const prefs = loadEffectiveGSDPreferences(activeBasePath)?.preferences;
-    const uokFlags = resolveUokFlags(prefs);
-    if (!uokFlags.gates) return;
+    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");
@@ -532,6 +619,93 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     return decideOrchestratorDispatch(this.ctx, this.pi, this.dispatchBasePath, this.s, input);
   }
 
+  private evaluateNoRemainingUnitsSettlement(stateSnapshot: GSDState): BlockedAdvanceResult | null {
+    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,
+      },
+    };
+  }
+
+  private async mergePendingCompleteMilestone(milestoneId: string): Promise<{ ok: true } | { ok: false; reason: string }> {
+    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 };
+  }
+
+  private clearPendingDispatch(): void {
+    this.s.pendingOrchestrationDispatch = null;
+  }
+
+  private findPriorSliceCompletionBlocker(unitType: string, unitId: string): string | null {
+    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) ─────────────────────────────────────────
 
   private compileUnitToolContract(unitType: string): { ok: true; reason: string } | { ok: false; reason: string } {
@@ -543,8 +717,11 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   // ── WorktreeAdapter (folded) ─────────────────────────────────────────────
 
   private getEffectiveUnitIsolationMode(basePath: string): ReturnType<typeof getIsolationMode> {
-    const configuredMode = getIsolationMode(basePath);
-    return configuredMode === "worktree" && this.s.isolationDegraded ? "branch" : configuredMode;
+    return resolveEffectiveUnitIsolationMode(
+      getIsolationMode(basePath),
+      this.s.isolationDegraded,
+      this.s.strandedRecoveryIsolationMode,
+    );
   }
 
   private buildLifecycle(): WorktreeLifecycle {
@@ -554,7 +731,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return new GitServiceImpl(basePath, gitConfig);
       },
       worktreeProjection: new WorktreeStateProjection(),
-      mergeMilestoneToMain,
+      mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
     });
   }
 
@@ -584,9 +761,6 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         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"
@@ -595,7 +769,23 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     const activeBasePath = this.getLiveDispatchBasePath();
     const snapshot = await deriveState(activeBasePath);
     const milestoneId = snapshot.activeMilestone?.id ?? null;
-    const expectedBranch = milestoneId ? autoWorktreeBranch(milestoneId) : null;
+    const buildExpectedBranch = (mode: ReturnType<typeof getIsolationMode>) =>
+      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: ReturnType<typeof getIsolationMode>) =>
+      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,
@@ -604,7 +794,8 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       unitRoot: activeBasePath,
       milestoneId,
       isolationMode,
-      expectedBranch,
+      expectedBranch: buildExpectedBranch(isolationMode),
+      lease: buildLease(isolationMode),
     });
     if (!result.ok) {
       const repaired = await repairAutoWorktreeSafetyFailure({
@@ -621,16 +812,20 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
           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) {
@@ -655,6 +850,21 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     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).
+   */
+  private observePhaseTransition(from: Phase, to: Phase): void {
+    if (isLegalEdge(from, to)) return;
+    const violation = new IllegalPhaseTransitionError(from, to);
+    debugLog("phase-transition-advisory", { from, to, message: violation.message });
+  }
+
   // ── Lifecycle verbs ──────────────────────────────────────────────────────
 
   /**
@@ -673,7 +883,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;
@@ -685,7 +895,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;
@@ -716,8 +926,19 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async start(_sessionContext: AutoSessionContext): Promise<AutoAdvanceResult> {
     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" });
@@ -730,10 +951,12 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     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",
@@ -747,6 +970,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return blocked;
       }
       await this.emitUokGate({
+        ...uokGateContext,
         gateId: "resource-version-guard",
         gateType: "policy",
         outcome: "pass",
@@ -757,6 +981,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       const gate = await this.preAdvanceGate();
       if (gate.kind === "fail") {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "manual-attention",
@@ -775,6 +1000,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       }
       if (gate.kind === "threw") {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "manual-attention",
@@ -785,6 +1011,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         // intentional fall-through: matches runPreDispatch behaviour
       } else {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "pass",
@@ -807,17 +1034,65 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         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: AutoAdvanceResult = {
+                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: AutoAdvanceResult = {
           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);
@@ -848,25 +1123,41 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return blocked;
       }
 
-      const nextKey = `${decision.unitType}:${decision.unitId}`;
+      const priorSliceBlocker = this.findPriorSliceCompletionBlocker(decision.unitType, decision.unitId);
+      if (priorSliceBlocker) {
+        this.clearPendingDispatch();
+        const blocked: AutoAdvanceResult = {
+          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 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
         // 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: AutoAdvanceResult = {
           kind: "blocked",
           reason: `state did not advance after finalized ${decision.unitType} ${decision.unitId}`,
@@ -890,31 +1181,43 @@ 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) {
-        const blocked: AutoAdvanceResult = { 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: 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.
         if (this.tryStuckArtifactRecovery(decision.unitType, decision.unitId)) {
+          this.clearPendingDispatch();
           return this.stuckRecovered(decision, reconciliation.stateSnapshot);
         }
+        this.clearPendingDispatch();
         const blocked: AutoAdvanceResult = {
           kind: "blocked",
-          reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+          reason: `stuck-loop: ${stuckVerdict.reason}`,
           action: "stop",
         };
         this.journalTransition({
@@ -929,6 +1232,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
       const contract = this.compileUnitToolContract(decision.unitType);
       if (!contract.ok) {
+        this.clearPendingDispatch();
         const blocked: AutoAdvanceResult = {
           kind: "blocked",
           reason: contract.reason,
@@ -947,6 +1251,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
       const worktree = await this.prepareWorktreeForUnit(decision.unitType, decision.unitId);
       if (!worktree.ok) {
+        this.clearPendingDispatch();
         const blocked: AutoAdvanceResult = {
           kind: "blocked",
           reason: worktree.reason,
@@ -1006,7 +1311,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();
@@ -1035,8 +1340,18 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async resume(): Promise<AutoAdvanceResult> {
     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" });
@@ -1053,7 +1368,12 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     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 });
@@ -1066,9 +1386,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;
 
@@ -1086,9 +1406,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;
 
@@ -1156,3 +1476,19 @@ export function resolveLiveOrchestratorBasePath(input: {
 export function createAutoOrchestrator(context: OrchestratorContext): AutoOrchestrationModule {
   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: ((projectRoot: string) => Promise<void>) | null,
+): () => void {
+  _projectionRebuildFn = fn;
+  return () => { _projectionRebuildFn = null; };
+}