gsd-pi 2.73.0-dev.e1c09f2 → 2.73.1-dev.06e4302

package/dist/resource-loader.js

@@ -358,7 +358,7 @@ function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
             if (entry.name.startsWith('.'))
                 continue;
             try {
-                symlinkSync(join(hoisted, entry.name), join(agentNodeModules, entry.name));
+                symlinkSync(join(hoisted, entry.name), join(agentNodeModules, entry.name), 'junction');
                 linkedCount++;
             }
             catch { /* skip individual */ }
@@ -382,7 +382,7 @@ function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
             }
             catch { /* didn't exist — will create below */ }
             try {
-                symlinkSync(join(internal, entry.name), link);
+                symlinkSync(join(internal, entry.name), link, 'junction');
                 linkedCount++;
             }
             catch { /* skip individual */ }

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -6,7 +6,7 @@
  * AssistantMessageEvents for TUI rendering, then strips tool-call blocks from
  * the final AssistantMessage so GSD's agent loop doesn't try to dispatch them.
  */
-import { EventStream } from "@gsd/pi-ai";
+import { EventStream, mapThinkingLevelToEffort, supportsAdaptiveThinking } from "@gsd/pi-ai";
 import { execSync } from "node:child_process";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
@@ -123,6 +123,63 @@ export function buildPromptFromContext(context) {
     }
     return parts.join("\n\n");
 }
+function stripDataUriPrefix(value) {
+    const commaIndex = value.indexOf(",");
+    if (value.startsWith("data:") && commaIndex !== -1) {
+        return value.slice(commaIndex + 1);
+    }
+    return value;
+}
+function inferMimeTypeFromDataUri(value) {
+    const match = /^data:([^;,]+);base64,/.exec(value);
+    return match?.[1] ?? null;
+}
+export function extractImageBlocksFromContext(context) {
+    const imageBlocks = [];
+    for (const msg of context.messages) {
+        if (msg.role !== "user" || !Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (!part || typeof part !== "object")
+                continue;
+            const block = part;
+            if (block.type !== "image" || typeof block.data !== "string")
+                continue;
+            const mimeType = typeof block.mimeType === "string" && block.mimeType.length > 0
+                ? block.mimeType
+                : inferMimeTypeFromDataUri(block.data);
+            if (!mimeType)
+                continue;
+            imageBlocks.push({
+                type: "image",
+                source: {
+                    type: "base64",
+                    media_type: mimeType,
+                    data: stripDataUriPrefix(block.data),
+                },
+            });
+        }
+    }
+    return imageBlocks;
+}
+export function buildSdkQueryPrompt(context, textPrompt = buildPromptFromContext(context)) {
+    const imageBlocks = extractImageBlocksFromContext(context);
+    if (imageBlocks.length === 0) {
+        return textPrompt;
+    }
+    const content = [...imageBlocks];
+    if (textPrompt) {
+        content.push({ type: "text", text: textPrompt });
+    }
+    const sdkMessage = {
+        type: "user",
+        message: { role: "user", content },
+        parent_tool_use_id: null,
+    };
+    return (async function* () {
+        yield sdkMessage;
+    })();
+}
 // ---------------------------------------------------------------------------
 // Error helper
 // ---------------------------------------------------------------------------
@@ -437,6 +494,7 @@ export async function resolveClaudePermissionMode(env = process.env) {
  * behaviour pass `permissionMode: "bypassPermissions"` explicitly.
  */
 export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
+    const { reasoning, ...sdkExtraOptions } = extraOptions;
     const mcpServers = buildWorkflowMcpServers();
     const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
     const disallowedTools = ["AskUserQuestion"];
@@ -455,6 +513,9 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         "Bash(pwd)",
         ...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
     ];
+    const effort = reasoning && supportsAdaptiveThinking(modelId)
+        ? mapThinkingLevelToEffort(reasoning, modelId)
+        : undefined;
     return {
         pathToClaudeCodeExecutable: getClaudePath(),
         model: modelId,
@@ -469,7 +530,8 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         ...(allowedTools.length > 0 ? { allowedTools } : {}),
         ...(mcpServers ? { mcpServers } : {}),
         betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
-        ...extraOptions,
+        ...(effort ? { effort } : {}),
+        ...sdkExtraOptions,
     };
 }
 function normalizeToolResultContent(content) {
@@ -617,14 +679,16 @@ async function pumpSdkMessages(model, context, options, stream) {
             options.signal.addEventListener("abort", () => controller.abort(), { once: true });
         }
         const prompt = buildPromptFromContext(context);
+        const queryPrompt = buildSdkQueryPrompt(context, prompt);
         const permissionMode = await resolveClaudePermissionMode();
         const sdkOpts = buildSdkOptions(modelId, prompt, { permissionMode }, typeof options?.extensionUIContext === "object"
             ? {
+                reasoning: options?.reasoning,
                 onElicitation: createClaudeCodeElicitationHandler(options?.extensionUIContext),
             }
-            : {});
+            : { reasoning: options?.reasoning });
         const queryResult = sdk.query({
-            prompt,
+            prompt: queryPrompt,
             options: {
                 ...sdkOpts,
                 abortController: controller,

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

@@ -320,10 +320,13 @@ export async function runPreDispatch(ic, loopState) {
         }
         else if (state.phase === "blocked") {
             const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-            await deps.stopAuto(ctx, pi, blockerMsg);
-            ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-            deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention", basename(s.originalBasePath || s.basePath));
-            deps.logCmuxEvent(prefs, blockerMsg, "error");
+            // Pause instead of hard-stop so the session is resumable with `/gsd auto`.
+            // Hard-stop here was causing premature termination when slice dependencies
+            // were temporarily unresolvable (e.g. after reassessment added new slices).
+            await deps.pauseAuto(ctx, pi);
+            ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto to resume.`, "warning");
+            deps.sendDesktopNotification("GSD", blockerMsg, "warning", "attention", basename(s.originalBasePath || s.basePath));
+            deps.logCmuxEvent(prefs, blockerMsg, "warning");
         }
         else {
             const ids = incomplete.map((m) => m.id).join(", ");
@@ -392,13 +395,16 @@ export async function runPreDispatch(ic, loopState) {
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "terminal", data: { reason: "milestone-complete", milestoneId: mid } });
         return { action: "break", reason: "milestone-complete" };
     }
-    // Terminal: blocked
+    // Terminal: blocked — pause instead of hard-stop so the session is resumable.
     if (state.phase === "blocked") {
         const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-        await closeoutAndStop(ctx, pi, s, deps, blockerMsg);
-        ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-        deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention", basename(s.originalBasePath || s.basePath));
-        deps.logCmuxEvent(prefs, blockerMsg, "error");
+        if (s.currentUnit) {
+            await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+        }
+        await deps.pauseAuto(ctx, pi);
+        ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto to resume.`, "warning");
+        deps.sendDesktopNotification("GSD", blockerMsg, "warning", "attention", basename(s.originalBasePath || s.basePath));
+        deps.logCmuxEvent(prefs, blockerMsg, "warning");
         debugLog("autoLoop", { phase: "exit", reason: "blocked" });
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "terminal", data: { reason: "blocked", blockers: state.blockers } });
         return { action: "break", reason: "blocked" };

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -216,7 +216,12 @@ export const DISPATCH_RULES = [
     {
         name: "reassess-roadmap (post-completion)",
         match: async ({ state, mid, midTitle, basePath, prefs }) => {
-            if (prefs?.phases?.skip_reassess || !prefs?.phases?.reassess_after_slice)
+            if (prefs?.phases?.skip_reassess)
+                return null;
+            // Default reassess_after_slice to true — reassessment after slice completion
+            // is essential for roadmap integrity. Opt-out via explicit `false`.
+            const reassessEnabled = prefs?.phases?.reassess_after_slice ?? true;
+            if (!reassessEnabled)
                 return null;
             const needsReassess = await checkNeedsReassessment(basePath, mid, state);
             if (!needsReassess)
@@ -710,11 +715,14 @@ export async function resolveDispatch(ctx) {
             return result;
         }
     }
-    // No rule matched — unhandled phase
+    // No rule matched — unhandled phase.
+    // Use level "warning" so the loop pauses (resumable) instead of hard-stopping.
+    // Hard-stop here was causing premature termination for transient phase gaps
+    // (e.g. after reassessment modifies the roadmap and state needs re-derivation).
     return {
         action: "stop",
         reason: `Unhandled phase "${ctx.state.phase}" — run /gsd doctor to diagnose.`,
-        level: "info",
+        level: "warning",
         matchedRule: "<no-match>",
     };
 }

package/dist/resources/extensions/gsd/auto-model-selection.js

@@ -9,10 +9,8 @@ import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabil
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
 import { getSessionModelOverride } from "./session-model-override.js";
-export function resolvePreferredModelConfig(unitType, autoModeStartModel, 
-/** When false, only return explicit per-phase model configs — do not
- *  synthesize a routing ceiling from dynamic_routing.tier_models (#3962). */
-isAutoMode = true) {
+import { logWarning } from "./workflow-logger.js";
+export function resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode = true) {
     const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
     if (explicitConfig)
         return explicitConfig;
@@ -24,7 +22,7 @@ isAutoMode = true) {
     if (!routingConfig.enabled || !routingConfig.tier_models)
         return undefined;
     // Don't synthesize a routing config for flat-rate providers (#3453).
-    if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider))
+    if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx))
         return undefined;
     const ceilingModel = routingConfig.tier_models.heavy
         ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined);
@@ -51,6 +49,17 @@ sessionModelOverride) {
     const effectiveSessionModelOverride = sessionModelOverride === undefined
         ? getSessionModelOverride(ctx.sessionManager.getSessionId())
         : (sessionModelOverride ?? undefined);
+    // Enrich the start model with a flat-rate context up front so routing
+    // synthesis and the dispatch-time guard see the same signals (built-in
+    // list + user `flat_rate_providers` preference + externalCli auto-
+    // detection).  The dispatch-time primary-model check below builds its
+    // own per-provider context when it has a resolved primary model.
+    if (autoModeStartModel) {
+        autoModeStartModel = {
+            ...autoModeStartModel,
+            flatRateCtx: buildFlatRateContext(autoModeStartModel.provider, ctx, prefs),
+        };
+    }
     const modelConfig = effectiveSessionModelOverride
         ? undefined
         : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
@@ -76,12 +85,13 @@ sessionModelOverride) {
         if (routingConfig.enabled) {
             const primaryModel = resolveModelId(modelConfig.primary, availableModels, ctx.model?.provider);
             if (primaryModel) {
-                if (isFlatRateProvider(primaryModel.provider)) {
+                const primaryFlatRateCtx = buildFlatRateContext(primaryModel.provider, ctx, prefs);
+                if (isFlatRateProvider(primaryModel.provider, primaryFlatRateCtx)) {
                     routingConfig.enabled = false;
                 }
             }
-            else if ((autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider))
-                || (ctx.model?.provider && isFlatRateProvider(ctx.model.provider))) {
+            else if ((autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx))
+                || (ctx.model?.provider && isFlatRateProvider(ctx.model.provider, buildFlatRateContext(ctx.model.provider, ctx, prefs)))) {
                 // Primary model unresolvable but provider signals indicate flat-rate —
                 // disable routing to prevent quality degradation.
                 routingConfig.enabled = false;
@@ -331,7 +341,40 @@ export function resolveModelId(modelId, availableModels, currentProvider) {
  * Uses case-insensitive matching with alias support to prevent fail-open on
  * provider naming variations (e.g. "copilot" vs "github-copilot").
  */
-const FLAT_RATE_PROVIDERS = new Set(["github-copilot", "copilot", "claude-code"]);
-export function isFlatRateProvider(provider) {
-    return FLAT_RATE_PROVIDERS.has(provider.toLowerCase());
+const BUILTIN_FLAT_RATE = new Set(["github-copilot", "copilot", "claude-code"]);
+export function isFlatRateProvider(provider, opts) {
+    const p = provider.toLowerCase();
+    if (BUILTIN_FLAT_RATE.has(p))
+        return true;
+    if (opts?.userFlatRate?.some(id => id.toLowerCase() === p))
+        return true;
+    if (opts?.authMode === "externalCli")
+        return true;
+    return false;
+}
+/**
+ * Build a FlatRateContext for a given provider from live runtime state.
+ * Safe to call when ctx or prefs are undefined — missing pieces are
+ * treated as "no signal".
+ */
+export function buildFlatRateContext(provider, ctx, prefs) {
+    let authMode;
+    const getAuthMode = ctx?.modelRegistry?.getProviderAuthMode;
+    if (typeof getAuthMode === "function") {
+        try {
+            const mode = getAuthMode(provider);
+            if (mode === "apiKey" || mode === "oauth" || mode === "externalCli" || mode === "none") {
+                authMode = mode;
+            }
+        }
+        catch (err) {
+            // Registry lookup failure must never break flat-rate detection —
+            // fall through with authMode undefined and surface the cause.
+            logWarning("dispatch", `flat-rate auth-mode lookup failed for ${provider}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        authMode,
+        userFlatRate: prefs?.flat_rate_providers,
+    };
 }

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -67,6 +67,7 @@ const LIFECYCLE_ONLY_UNITS = new Set([
     "replan-slice", "complete-slice", "run-uat",
     "reassess-roadmap", "rewrite-docs",
 ]);
+import { describeNextUnit, } from "./auto-dashboard.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { _resetHasChangesCache } from "./native-git-bridge.js";
@@ -179,6 +180,15 @@ export function detectRogueFileWrites(unitType, unitId, basePath) {
     }
     return rogues;
 }
+export const STEP_COMPLETE_FALLBACK_MESSAGE = "Step complete. Run /clear, then /gsd to continue (or /gsd auto to run continuously).";
+export function buildStepCompleteMessage(nextState) {
+    if (nextState.phase === "complete") {
+        return "Step complete — milestone finished. Run /gsd status to review, or start the next milestone.";
+    }
+    const next = describeNextUnit(nextState);
+    return `Step complete. Next: ${next.label}\n`
+        + `Run /clear, then /gsd to continue (or /gsd auto to run continuously).`;
+}
 /**
  * Pre-verification processing: parallel worker signal check, cache invalidation,
  * auto-commit, doctor run, state rebuild, worktree sync, artifact verification.
@@ -509,6 +519,26 @@ export async function postUnitPreVerification(pctx, opts) {
                     const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1;
                     s.verificationRetryCount.set(retryKey, attempt);
                     if (attempt > MAX_VERIFICATION_RETRIES) {
+                        // #4175: For complete-milestone, a blocker placeholder is harmful —
+                        // the stub SUMMARY has no recovery value (milestone is terminal),
+                        // it does not update DB status (so deriveState never advances),
+                        // and it fools stopAuto's presence check into merging a milestone
+                        // that was never legitimately completed. Pause auto-mode with a
+                        // clear single failure signal and preserve the worktree branch.
+                        if (s.currentUnit.type === "complete-milestone") {
+                            debugLog("postUnit", {
+                                phase: "artifact-verify-pause-complete-milestone",
+                                unitType: s.currentUnit.type,
+                                unitId: s.currentUnit.id,
+                                attempt,
+                                maxRetries: MAX_VERIFICATION_RETRIES,
+                            });
+                            s.verificationRetryCount.delete(retryKey);
+                            s.pendingVerificationRetry = null;
+                            ctx.ui.notify(`Milestone ${s.currentUnit.id} verification failed after ${MAX_VERIFICATION_RETRIES} retries — worktree branch preserved. Re-run /gsd auto once blockers are resolved.`, "error");
+                            await pauseAuto(ctx, pi);
+                            return "dispatched";
+                        }
                         // Retries exhausted — write a blocker placeholder so the pipeline
                         // can advance past this stuck unit (#2653).
                         debugLog("postUnit", {
@@ -836,8 +866,18 @@ export async function postUnitPostVerification(pctx) {
             debugLog("postUnit", { phase: "quick-task-dispatch", error: String(e) });
         }
     }
-    // Step mode → show wizard instead of dispatch
+    // Step mode → show wizard instead of dispatch.
+    // Without this notify(), /gsd in step mode finishes a unit and silently
+    // exits the loop, leaving the user with no hint to /clear and /gsd again.
     if (s.stepMode) {
+        try {
+            const nextState = await deriveState(s.basePath);
+            ctx.ui.notify(buildStepCompleteMessage(nextState), "info");
+        }
+        catch (e) {
+            debugLog("postUnit", { phase: "step-wizard-notify", error: String(e) });
+            ctx.ui.notify(STEP_COMPLETE_FALLBACK_MESSAGE, "info");
+        }
         return "step-wizard";
     }
     return "continue";

package/dist/resources/extensions/gsd/auto-start.js

@@ -38,7 +38,7 @@ import { existsSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync, } fro
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
 import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
-import { resolveDefaultSessionModel, resolveDynamicRoutingConfig } from "./preferences-models.js";
+import { isCustomProvider, resolveDefaultSessionModel, resolveDynamicRoutingConfig, } from "./preferences-models.js";
 import { getSessionModelOverride } from "./session-model-override.js";
 /**
  * Bootstrap a fresh auto-mode session. Handles everything from git init
@@ -195,8 +195,18 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     //
     // This preserves #3517 defaults while honoring explicit runtime model
     // selection for subsequent /gsd runs in the same session.
+    //
+    // Exception (#4122): when the session provider is a custom provider declared
+    // in ~/.gsd/agent/models.json (Ollama, vLLM, OpenAI-compatible proxy, etc.),
+    // PREFERENCES.md is skipped entirely. PREFERENCES.md cannot reference custom
+    // providers, so honoring it would silently reroute auto-mode to a built-in
+    // provider the user is not logged into and surface as "Not logged in · Please
+    // run /login" before pausing and resetting to claude-code/claude-sonnet-4-6.
     const manualSessionOverride = getSessionModelOverride(ctx.sessionManager.getSessionId());
-    const preferredModel = resolveDefaultSessionModel(ctx.model?.provider);
+    const sessionProviderIsCustom = isCustomProvider(ctx.model?.provider);
+    const preferredModel = sessionProviderIsCustom
+        ? null
+        : resolveDefaultSessionModel(ctx.model?.provider);
     // Validate the preferred model against the live registry + provider auth so
     // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
     // start-model snapshot. Without this, every subsequent unit would try to
@@ -622,6 +632,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         }
         ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
         ctx.ui.setFooter(hideFooter);
+        // Hide gsd-health during AUTO — gsd-progress is the single source of truth
+        // for last-commit / cost / health signal while auto is running.
+        ctx.ui.setWidget("gsd-health", undefined);
         const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
         const pendingCount = (state.registry ?? []).filter((m) => m.status !== "complete" && m.status !== "parked").length;
         const scopeMsg = pendingCount > 1
@@ -636,12 +649,16 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         const startModelLabel = s.autoModeStartModel
             ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}`
             : ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "default";
-        // Flat-rate providers (e.g. GitHub Copilot, claude-code) suppress routing
-        // at dispatch time (#3453) — reflect that in the banner.
-        const { isFlatRateProvider } = await import("./auto-model-selection.js");
+        // Flat-rate providers (e.g. GitHub Copilot, claude-code, user-declared
+        // subscription proxies, externalCli CLIs) suppress routing at dispatch
+        // time (#3453) — reflect that in the banner.  Thread the same
+        // FlatRateContext used by selectAndApplyModel so user-declared
+        // flat-rate providers and externalCli auto-detection are respected.
+        const { isFlatRateProvider, buildFlatRateContext } = await import("./auto-model-selection.js");
+        const bannerPrefs = loadEffectiveGSDPreferences()?.preferences;
         const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
         const effectivelyEnabled = routingConfig.enabled
-            && !(effectiveProvider && isFlatRateProvider(effectiveProvider));
+            && !(effectiveProvider && isFlatRateProvider(effectiveProvider, buildFlatRateContext(effectiveProvider, ctx, bannerPrefs)));
         // The actual ceiling may come from tier_models.heavy, not the start model.
         const effectiveCeiling = (routingConfig.enabled && routingConfig.tier_models?.heavy)
             ? routingConfig.tier_models.heavy

package/dist/resources/extensions/gsd/auto-timeout-recovery.js

@@ -156,6 +156,19 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: steering ${unitType} ${unitId} to produce ${expected} (attempt ${attemptNumber}, session ${recoveryAttempts + 1}/${maxRecoveryAttempts}).`, "warning");
         return "recovered";
     }
+    // #4175: For complete-milestone, never write a blocker placeholder — a stub
+    // SUMMARY has no recovery value (milestone is terminal), it does not update
+    // DB status, and downstream merge paths can treat the stub as a legitimate
+    // completion signal. Pause instead so the worktree branch is preserved.
+    if (unitType === "complete-milestone") {
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            phase: "paused",
+            recoveryAttempts: recoveryAttempts + 1,
+            lastRecoveryReason: reason,
+        });
+        ctx.ui.notify(`Milestone ${unitId} ${reason}-recovery exhausted ${maxRecoveryAttempts} attempt(s) — worktree branch preserved. Re-run /gsd auto once blockers are resolved.`, "error");
+        return "paused";
+    }
     // Retries exhausted — write a blocker placeholder and advance the pipeline
     // instead of silently stalling.
     const placeholder = writeBlockerPlaceholder(unitType, unitId, basePath, `${reason} recovery exhausted ${maxRecoveryAttempts} attempts without producing the artifact.`);

package/dist/resources/extensions/gsd/auto-verification.js

@@ -10,10 +10,15 @@
  * checks the result and handles control flow.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { resolveSlicePath } from "./paths.js";
+import { resolveSlicePath, resolveMilestoneFile } from "./paths.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getTask, getSliceTasks } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSliceTasks, getMilestoneSlices } from "./gsd-db.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { extractVerdict } from "./verdict-parser.js";
+import { isClosedStatus } from "./status-guards.js";
+import { loadFile } from "./files.js";
+import { parseRoadmap } from "./parsers-legacy.js";
+import { isMilestoneComplete } from "./state.js";
 import { runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
@@ -22,6 +27,80 @@ import { join } from "node:path";
 function isInfraVerificationFailure(stderr) {
     return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(stderr);
 }
+/**
+ * Post-unit guard for `validate-milestone` units (#4094).
+ *
+ * When validate-milestone writes verdict=needs-remediation, the agent is
+ * expected to also call gsd_reassess_roadmap in the same turn to add
+ * remediation slices. If they don't, the state machine re-derives
+ * `phase: validating-milestone` indefinitely (all slices still complete +
+ * verdict still needs-remediation), wasting ~3 dispatches before the stuck
+ * detector fires.
+ *
+ * This guard fires immediately on the first occurrence: if VALIDATION.md
+ * verdict is needs-remediation and no incomplete slices exist for the
+ * milestone, pause the auto-loop with a clear blocker.
+ */
+async function runValidateMilestonePostCheck(vctx, pauseAuto) {
+    const { s, ctx, pi } = vctx;
+    if (!s.currentUnit)
+        return "continue";
+    const { milestone: mid } = parseUnitId(s.currentUnit.id);
+    if (!mid)
+        return "continue";
+    const validationFile = resolveMilestoneFile(s.basePath, mid, "VALIDATION");
+    if (!validationFile)
+        return "continue";
+    const validationContent = await loadFile(validationFile);
+    if (!validationContent)
+        return "continue";
+    const verdict = extractVerdict(validationContent);
+    if (verdict !== "needs-remediation")
+        return "continue";
+    const incompleteSliceCount = await countIncompleteSlices(s.basePath, mid);
+    // If any non-closed slices exist, the agent successfully queued remediation
+    // work — proceed normally. The state machine will execute those slices and
+    // re-validate per the #3596/#3670 fix.
+    if (incompleteSliceCount > 0)
+        return "continue";
+    ctx.ui.notify(`Milestone ${mid} validation returned verdict=needs-remediation but no remediation slices were added. Pausing for human review.`, "error");
+    process.stderr.write(`validate-milestone: pausing — verdict=needs-remediation with no incomplete slices for ${mid}. ` +
+        `The agent must call gsd_reassess_roadmap to add remediation slices before re-validation.\n`);
+    await pauseAuto(ctx, pi);
+    return "pause";
+}
+/**
+ * Count slices for a milestone that are not in a closed status.
+ * DB-backed projects are authoritative (#4094 peer review); falls back to
+ * roadmap parsing only when the DB is unavailable.
+ */
+async function countIncompleteSlices(basePath, milestoneId) {
+    if (isDbAvailable()) {
+        const slices = getMilestoneSlices(milestoneId);
+        if (slices.length === 0) {
+            // No DB rows — treat as "unknown", do not pause.
+            return 1;
+        }
+        return slices.filter((slice) => !isClosedStatus(slice.status)).length;
+    }
+    // Filesystem fallback: parse the roadmap markdown.
+    try {
+        const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        if (!roadmapFile)
+            return 1;
+        const roadmapContent = await loadFile(roadmapFile);
+        if (!roadmapContent)
+            return 1;
+        const roadmap = parseRoadmap(roadmapContent);
+        if (roadmap.slices.length === 0)
+            return 1;
+        return isMilestoneComplete(roadmap) ? 0 : 1;
+    }
+    catch {
+        // Parsing failures should not cause false-positive pauses.
+        return 1;
+    }
+}
 /**
  * Run the verification gate for the current execute-task unit.
  * Returns:
@@ -31,7 +110,13 @@ function isInfraVerificationFailure(stderr) {
  */
 export async function runPostUnitVerification(vctx, pauseAuto) {
     const { s, ctx, pi } = vctx;
-    if (!s.currentUnit || s.currentUnit.type !== "execute-task") {
+    if (!s.currentUnit) {
+        return "continue";
+    }
+    if (s.currentUnit.type === "validate-milestone") {
+        return await runValidateMilestonePostCheck(vctx, pauseAuto);
+    }
+    if (s.currentUnit.type !== "execute-task") {
         return "continue";
     }
     try {