@opengsd/gsd-pi 1.2.0-dev.0b870afa → 1.2.0-dev.23d85b63

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

@@ -0,0 +1,347 @@
+// Project/App: gsd-pi
+// File Purpose: Auto-loop finalize phase — post-unit verification and UAT pause.
+import { clearCurrentPhase } from "../../shared/gsd-phase-state.js";
+import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
+import { writeUnitRuntimeRecord } from "../unit-runtime.js";
+import { buildManualValidationGuidance } from "../worktree-manager.js";
+import { relSliceFile } from "../paths.js";
+import { detectRootWriteLeak, formatRootWriteLeakMessage, } from "../root-write-leak-guard.js";
+import { drainLogs, drainAndSummarize, formatForNotification, hasAnyIssues, } from "../workflow-logger.js";
+import { debugLog } from "../debug-logger.js";
+import { buildPhaseHandoffOutcome, setAutoOutcomeWidget } from "../auto-dashboard.js";
+import { applyVerificationRetryPolicy, rememberRetryDispatch, isIsolatedWorktreeSession, } from "./phase-helpers.js";
+import { _runMilestoneMergeOnceWithStashRestore } from "./closeout.js";
+import { MAX_FINALIZE_TIMEOUTS } from "./types.js";
+export async function failClosedOnFinalizeTimeout(ic, iterData, loopState, stage, startedAt) {
+    const { ctx, pi, s, deps } = ic;
+    const now = Date.now();
+    const unitType = iterData.unitType;
+    const unitId = iterData.unitId;
+    const timeoutMs = stage === "pre" ? FINALIZE_PRE_TIMEOUT_MS : FINALIZE_POST_TIMEOUT_MS;
+    const progressKind = stage === "pre" ? "finalize-pre-timeout" : "finalize-post-timeout";
+    writeUnitRuntimeRecord(s.basePath, unitType, unitId, startedAt, {
+        phase: "finalize-timeout",
+        timeoutAt: now,
+        lastProgressAt: now,
+        lastProgressKind: progressKind,
+    });
+    deps.emitJournalEvent({
+        ts: new Date(now).toISOString(),
+        flowId: ic.flowId,
+        seq: ic.nextSeq(),
+        eventType: "unit-end",
+        data: {
+            unitType,
+            unitId,
+            status: "timed-out-finalize",
+            artifactVerified: false,
+            finalizeStage: stage,
+        },
+    });
+    loopState.consecutiveFinalizeTimeouts++;
+    debugLog("autoLoop", {
+        phase: progressKind,
+        iteration: ic.iteration,
+        unitType,
+        unitId,
+        consecutiveTimeouts: loopState.consecutiveFinalizeTimeouts,
+    });
+    ctx.ui.notify(`${stage === "pre" ? "postUnitPreVerification" : "postUnitPostVerification"} timed out after ${timeoutMs / 1000}s for ${unitType} ${unitId} (${loopState.consecutiveFinalizeTimeouts}/${MAX_FINALIZE_TIMEOUTS}) — pausing auto-mode for recovery.`, "warning");
+    await deps.pauseAuto(ctx, pi);
+    s.clearCurrentUnit();
+    clearCurrentPhase();
+    drainLogs();
+    return { action: "break", reason: progressKind };
+}
+/**
+ * Phase 5: Post-unit finalize — pre/post verification, UAT pause, step-wizard.
+ * Returns break/continue/next to control the outer loop.
+ */
+export async function runFinalize(ic, iterData, loopState, sidecarItem) {
+    const { ctx, pi, s, deps } = ic;
+    const { pauseAfterUatDispatch } = iterData;
+    debugLog("autoLoop", { phase: "finalize", iteration: ic.iteration });
+    // Clear unit timeout (unit completed)
+    deps.clearUnitTimeout();
+    // Post-unit context for pre/post verification
+    const postUnitCtx = {
+        s,
+        ctx,
+        pi,
+        buildSnapshotOpts: deps.buildSnapshotOpts,
+        lockBase: deps.lockBase,
+        stopAuto: deps.stopAuto,
+        pauseAuto: deps.pauseAuto,
+        updateProgressWidget: deps.updateProgressWidget,
+    };
+    // Pre-verification processing (commit, doctor, state rebuild, etc.)
+    // Timeout guard: if postUnitPreVerification hangs (e.g., safety harness
+    // deadlock, browser teardown hang, worktree sync stall), force-continue
+    // after timeout so the auto-loop is not permanently frozen (#3757).
+    //
+    // On timeout, null out s.currentUnit so the timed-out task's late async
+    // mutations are harmless — postUnitPreVerification guards all side effects
+    // behind `if (s.currentUnit)`. The next iteration sets a fresh currentUnit.
+    // Sidecar items use lightweight pre-verification opts
+    const preVerificationOpts = sidecarItem
+        ? sidecarItem.kind === "hook"
+            ? { skipSettleDelay: true, skipWorktreeSync: true, agentEndMessages: s.lastUnitAgentEndMessages ?? undefined }
+            : { skipSettleDelay: true, agentEndMessages: s.lastUnitAgentEndMessages ?? undefined }
+        : { agentEndMessages: s.lastUnitAgentEndMessages ?? undefined };
+    const preUnitSnapshot = s.currentUnit
+        ? { type: s.currentUnit.type, id: s.currentUnit.id, startedAt: s.currentUnit.startedAt }
+        : null;
+    const clearFinalizingUnit = () => {
+        if (preUnitSnapshot &&
+            s.currentUnit?.type === preUnitSnapshot.type &&
+            s.currentUnit?.id === preUnitSnapshot.id &&
+            s.currentUnit?.startedAt === preUnitSnapshot.startedAt) {
+            s.clearCurrentUnit();
+        }
+        s.rootWriteBaseline = null;
+    };
+    clearCurrentPhase();
+    const preResultGuard = await withTimeout(deps.postUnitPreVerification(postUnitCtx, preVerificationOpts), FINALIZE_PRE_TIMEOUT_MS, "postUnitPreVerification");
+    if (preResultGuard.timedOut) {
+        return failClosedOnFinalizeTimeout(ic, iterData, loopState, "pre", preUnitSnapshot?.startedAt ?? Date.now());
+    }
+    const preResult = preResultGuard.value;
+    if (preResult === "dispatched") {
+        const dispatchedReason = s.lastGitActionFailure
+            ? "git-closeout-failure"
+            : "pre-verification-dispatched";
+        debugLog("autoLoop", {
+            phase: "exit",
+            reason: dispatchedReason,
+            gitError: s.lastGitActionFailure ?? undefined,
+        });
+        clearFinalizingUnit();
+        return { action: "break", reason: dispatchedReason };
+    }
+    if (preResult === "retry") {
+        if (sidecarItem) {
+            // Sidecar artifact retries are skipped — just continue
+            debugLog("autoLoop", { phase: "sidecar-artifact-retry-skipped", iteration: ic.iteration });
+        }
+        else {
+            // s.pendingVerificationRetry was set by postUnitPreVerification.
+            // Emit a dedicated journal event so forensics can distinguish bounded
+            // verification retries from genuine stuck-loop dispatch repetitions (#4540).
+            const retryInfo = s.pendingVerificationRetry;
+            deps.emitJournalEvent({
+                ts: new Date().toISOString(),
+                flowId: ic.flowId,
+                seq: ic.nextSeq(),
+                eventType: "artifact-verification-retry",
+                data: {
+                    unitType: preUnitSnapshot?.type,
+                    unitId: retryInfo?.unitId,
+                    attempt: retryInfo?.attempt,
+                },
+            });
+            const retryPolicyResult = await applyVerificationRetryPolicy(ic, preUnitSnapshot?.type, "artifact-verification-retry");
+            if (retryPolicyResult) {
+                clearFinalizingUnit();
+                return retryPolicyResult;
+            }
+            // Continue the loop — next iteration will inject the retry context into the prompt.
+            rememberRetryDispatch(s, preUnitSnapshot, iterData);
+            debugLog("autoLoop", { phase: "artifact-verification-retry", iteration: ic.iteration });
+            clearFinalizingUnit();
+            return { action: "continue" };
+        }
+    }
+    if (pauseAfterUatDispatch) {
+        const pauseMid = iterData.mid;
+        const pauseSliceId = pauseMid && iterData.unitId.startsWith(`${pauseMid}/`)
+            ? iterData.unitId.slice(pauseMid.length + 1)
+            : undefined;
+        const guidance = pauseMid
+            ? buildManualValidationGuidance(s.basePath, pauseMid, {
+                uatPath: pauseSliceId
+                    ? relSliceFile(s.basePath, pauseMid, pauseSliceId, "UAT")
+                    : undefined,
+            })
+            : null;
+        const pauseMessage = guidance
+            ? `UAT requires human execution. Auto-mode will pause after this unit writes the result file.\n\n${guidance}`
+            : "UAT requires human execution. Auto-mode will pause after this unit writes the result file.";
+        ctx.ui.notify(pauseMessage, "info");
+        await deps.pauseAuto(ctx, pi);
+        debugLog("autoLoop", { phase: "exit", reason: "uat-pause" });
+        clearFinalizingUnit();
+        return { action: "break", reason: "uat-pause" };
+    }
+    // Verification gate
+    // Hook sidecar items skip verification entirely.
+    // Non-hook sidecar items run verification but skip retries (just continue).
+    const skipVerification = sidecarItem?.kind === "hook";
+    if (!skipVerification) {
+        const verificationResult = await deps.runPostUnitVerification({ s, ctx, pi }, deps.pauseAuto);
+        if (verificationResult === "pause") {
+            debugLog("autoLoop", { phase: "exit", reason: "verification-pause" });
+            clearFinalizingUnit();
+            return { action: "break", reason: "verification-pause" };
+        }
+        if (verificationResult === "retry") {
+            if (sidecarItem) {
+                // Sidecar verification retries are skipped — just continue
+                debugLog("autoLoop", { phase: "sidecar-verification-retry-skipped", iteration: ic.iteration });
+            }
+            else {
+                // s.pendingVerificationRetry was set by runPostUnitVerification.
+                const retryPolicyResult = await applyVerificationRetryPolicy(ic, iterData.unitType, "verification-retry");
+                if (retryPolicyResult) {
+                    clearFinalizingUnit();
+                    return retryPolicyResult;
+                }
+                // Continue the loop — next iteration will inject the retry context into the prompt.
+                rememberRetryDispatch(s, preUnitSnapshot, iterData);
+                debugLog("autoLoop", { phase: "verification-retry", iteration: ic.iteration });
+                clearFinalizingUnit();
+                return { action: "continue" };
+            }
+        }
+    }
+    // Post-verification processing (DB dual-write, hooks, triage, quick-tasks)
+    // Timeout guard: if postUnitPostVerification hangs (e.g., module import
+    // deadlock, SQLite transaction hang), force-continue after timeout so the
+    // auto-loop is not permanently frozen (#2344).
+    const postResultGuard = await withTimeout(deps.postUnitPostVerification(postUnitCtx), FINALIZE_POST_TIMEOUT_MS, "postUnitPostVerification");
+    if (postResultGuard.timedOut) {
+        return failClosedOnFinalizeTimeout(ic, iterData, loopState, "post", preUnitSnapshot?.startedAt ?? Date.now());
+    }
+    const postResult = postResultGuard.value;
+    if (postResult === "retry") {
+        if (sidecarItem) {
+            debugLog("autoLoop", { phase: "sidecar-pre-execution-retry-skipped", iteration: ic.iteration });
+        }
+        else {
+            const retryInfo = s.pendingVerificationRetry;
+            deps.emitJournalEvent({
+                ts: new Date().toISOString(),
+                flowId: ic.flowId,
+                seq: ic.nextSeq(),
+                eventType: "pre-execution-retry",
+                data: {
+                    unitType: preUnitSnapshot?.type,
+                    unitId: retryInfo?.unitId,
+                    attempt: retryInfo?.attempt,
+                },
+            });
+            const retryPolicyResult = await applyVerificationRetryPolicy(ic, preUnitSnapshot?.type, "pre-execution-retry");
+            if (retryPolicyResult) {
+                clearFinalizingUnit();
+                return retryPolicyResult;
+            }
+            rememberRetryDispatch(s, preUnitSnapshot, iterData);
+            debugLog("autoLoop", {
+                phase: "pre-execution-retry",
+                iteration: ic.iteration,
+                unitType: preUnitSnapshot?.type,
+                unitId: retryInfo?.unitId,
+                attempt: retryInfo?.attempt,
+            });
+            clearFinalizingUnit();
+            return { action: "continue" };
+        }
+    }
+    if (postResult === "stopped") {
+        debugLog("autoLoop", {
+            phase: "exit",
+            reason: "post-verification-stopped",
+        });
+        clearFinalizingUnit();
+        return { action: "break", reason: "post-verification-stopped" };
+    }
+    if (postResult === "step-wizard") {
+        // Step mode — exit the loop (caller handles wizard)
+        debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
+        clearFinalizingUnit();
+        return { action: "break", reason: "step-wizard" };
+    }
+    if (preUnitSnapshot && isIsolatedWorktreeSession(s)) {
+        const leak = detectRootWriteLeak({
+            rootPath: s.originalBasePath,
+            worktreePath: s.basePath,
+            unitType: preUnitSnapshot.type,
+            unitId: preUnitSnapshot.id,
+            before: s.rootWriteBaseline,
+        });
+        s.rootWriteBaseline = null;
+        if (leak) {
+            const message = formatRootWriteLeakMessage(leak);
+            debugLog("autoLoop", {
+                phase: "root-write-leak",
+                unitType: preUnitSnapshot.type,
+                unitId: preUnitSnapshot.id,
+                rootPath: leak.rootPath,
+                worktreePath: leak.worktreePath,
+                files: leak.files.map((file) => ({ path: file.path, status: file.status })),
+            });
+            ctx.ui.notify(message, "error");
+            await deps.stopAuto(ctx, pi, "Root-write leak during isolated auto-mode", {
+                preserveCompletedMilestoneBranch: true,
+            });
+            clearFinalizingUnit();
+            return { action: "break", reason: "root-write-leak" };
+        }
+    }
+    else {
+        s.rootWriteBaseline = null;
+    }
+    if (preUnitSnapshot?.type === "complete-milestone" && s.currentMilestoneId) {
+        const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId, {
+            preserveCloseoutTranscript: true,
+        });
+        if (stop) {
+            clearFinalizingUnit();
+            return stop;
+        }
+    }
+    // Both pre and post verification completed without timeout — reset counter
+    loopState.consecutiveFinalizeTimeouts = 0;
+    if (preUnitSnapshot) {
+        writeUnitRuntimeRecord(s.basePath, preUnitSnapshot.type, preUnitSnapshot.id, preUnitSnapshot.startedAt, {
+            phase: "finalized",
+            lastProgressAt: Date.now(),
+            lastProgressKind: "finalize-success",
+        });
+        if (!preUnitSnapshot.type.startsWith("hook/") &&
+            preUnitSnapshot.type !== "custom-step" &&
+            preUnitSnapshot.type !== "complete-milestone") {
+            setAutoOutcomeWidget(ctx, {
+                ...buildPhaseHandoffOutcome({
+                    unitType: preUnitSnapshot.type,
+                    unitId: preUnitSnapshot.id,
+                    agentEndMessages: s.lastUnitAgentEndMessages,
+                }),
+                startedAt: s.autoStartTime,
+            });
+        }
+    }
+    clearFinalizingUnit();
+    // Surface accumulated workflow-logger issues for this unit to the user.
+    // Warnings/errors logged during the unit are buffered in the logger and
+    // drained here so the user sees a single consolidated post-unit alert.
+    if (hasAnyIssues()) {
+        const { logs } = drainAndSummarize();
+        if (logs.length > 0) {
+            const severity = logs.some((e) => e.severity === "error") ? "error" : "warning";
+            ctx.ui.notify(formatForNotification(logs), severity);
+        }
+    }
+    if (preUnitSnapshot?.type === "complete-milestone" && s.currentMilestoneId) {
+        // cleanupAfterLoopExit skips gsd-progress when preserveCompletionSurface is true, so clear stale controls here.
+        ctx.ui.setStatus?.("gsd-step", undefined);
+        ctx.ui.setWidget?.("gsd-progress", undefined);
+        await deps.stopAuto(ctx, pi, `Milestone ${s.currentMilestoneId} complete`, {
+            completionWidget: {
+                milestoneId: s.currentMilestoneId,
+                milestoneTitle: iterData.midTitle,
+            },
+        });
+        return { action: "break", reason: "milestone-complete" };
+    }
+    return { action: "next", data: undefined };
+}

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

@@ -13,7 +13,9 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { MAX_LOOP_ITERATIONS, } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
-import { runGuards, runFinalize } from "./phases.js";
+import { runGuards } from "./phases.js";
+import { runFinalize } from "./finalize.js";
+import { resetSessionTimeoutState } from "./unit-phase.js";
 import { STUCK_WINDOW_SIZE } from "./dispatch-history.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
@@ -274,6 +276,7 @@ function closeOutCrashedUnit(s, iterData, err) {
  */
 export async function autoLoop(ctx, pi, s, deps, options) {
     debugLog("autoLoop", { phase: "enter" });
+    resetSessionTimeoutState();
     let iteration = 0;
     const dispatchContract = options?.dispatchContract ?? "legacy-direct";
     const unitDispatchDeps = createExecutionGraphUnitDispatchDeps();

package/dist/resources/extensions/gsd/auto/milestone-lease-reclaim.js

@@ -0,0 +1,56 @@
+// Project/App: gsd-pi
+// File Purpose: Recover missing milestone lease state for resumed isolated workers.
+import { debugLog } from "../debug-logger.js";
+import { claimMilestoneLease } from "../db/milestone-leases.js";
+export function hasHeldMilestoneLease(session, milestoneId) {
+    return (Boolean(milestoneId) &&
+        session.currentMilestoneId === milestoneId &&
+        typeof session.milestoneLeaseToken === "number");
+}
+export function reclaimMissingMilestoneLease(session, milestoneId, isolationMode, phase) {
+    if (isolationMode === "none")
+        return;
+    if (!session.workerId || !milestoneId)
+        return;
+    if (hasHeldMilestoneLease(session, milestoneId))
+        return;
+    // Note: we intentionally do NOT bail just because the session already holds a
+    // lease for a *different* milestone. When dispatch advances to a new
+    // milestone the session's stale `currentMilestoneId`/token are for the prior
+    // one, and the active milestone's lease must still be claimed — otherwise
+    // worktree safety sees `held: false` and fails dispatch (#760). Claiming is
+    // safe: claimMilestoneLease refuses to steal a lease another worker holds.
+    try {
+        const claim = claimMilestoneLease(session.workerId, milestoneId);
+        if (claim.ok) {
+            session.currentMilestoneId = milestoneId;
+            session.milestoneLeaseToken = claim.token;
+            debugLog("worktreeSafety", {
+                phase: "lease-reclaimed",
+                source: phase,
+                milestoneId,
+                workerId: session.workerId,
+                token: claim.token,
+            });
+        }
+        else {
+            debugLog("worktreeSafety", {
+                phase: "lease-reclaim-blocked",
+                source: phase,
+                milestoneId,
+                workerId: session.workerId,
+                holderWorkerId: claim.byWorker,
+                expiresAt: claim.expiresAt,
+            });
+        }
+    }
+    catch (err) {
+        debugLog("worktreeSafety", {
+            phase: "lease-reclaim-failed",
+            source: phase,
+            milestoneId,
+            workerId: session.workerId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

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

@@ -25,7 +25,7 @@ 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, resolveEffectiveUnitIsolationMode } from "../preferences.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";
@@ -47,9 +47,20 @@ import { buildDispatchKey, createDispatchHistory, STUCK_WINDOW_SIZE, } from "./d
 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();
 }
+/**
+ * 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
+ */
+let _projectionRebuildFn = null;
 function noRemainingUnitsOutcome(stateSnapshot) {
     if (stateSnapshot.phase === "complete") {
         return {
@@ -113,7 +124,7 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
     const active = state.activeMilestone;
     const activeSession = input.session ?? session;
     const activeDispatchBasePath = activeSession?.basePath || dispatchBasePath;
-    const prefs = loadEffectiveGSDPreferences(activeDispatchBasePath)?.preferences;
+    const prefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, activeDispatchBasePath, resolveProfileAnchorProvider(ctx.model?.provider, session?.autoModeStartModel?.provider))?.preferences;
     if (!active) {
         if (state.phase !== "pre-planning")
             return null;
@@ -127,6 +138,7 @@ export async function decideOrchestratorDispatch(ctx, pi, dispatchBasePath, sess
     }
     if (active && activeSession && shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath)) {
         activeSession.currentMilestoneId = active.id;
+        activeSession.milestoneLeaseToken = null;
     }
     const dispatchMid = active?.id ?? activeSession?.currentMilestoneId ?? "";
     const dispatchMidTitle = active?.title ?? "";
@@ -384,7 +396,7 @@ export class AutoOrchestrator {
     // ── UokGateAdapter (folded) ──────────────────────────────────────────────
     async emitUokGate(input) {
         const activeBasePath = this.getLiveDispatchBasePath();
-        const prefs = loadEffectiveGSDPreferences(activeBasePath)?.preferences;
+        const prefs = loadEffectiveGSDPreferencesWithRegistry(this.ctx.modelRegistry, activeBasePath, resolveProfileAnchorProvider(this.ctx.model?.provider, this.s.autoModeStartModel?.provider))?.preferences;
         const uokFlags = resolveUokFlags(prefs);
         if (!uokFlags.gates)
             return;
@@ -476,6 +488,37 @@ export class AutoOrchestrator {
             },
         };
     }
+    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;
     }
@@ -536,9 +579,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";
@@ -546,7 +586,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,
@@ -555,7 +609,8 @@ export class AutoOrchestrator {
             unitRoot: activeBasePath,
             milestoneId,
             isolationMode,
-            expectedBranch,
+            expectedBranch: buildExpectedBranch(isolationMode),
+            lease: buildLease(isolationMode),
         });
         if (!result.ok) {
             const repaired = await repairAutoWorktreeSafetyFailure({
@@ -573,16 +628,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) {
@@ -775,6 +834,35 @@ export class AutoOrchestrator {
             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;
@@ -1155,3 +1243,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; };
+}