@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts

@@ -45,11 +45,13 @@ import {
 	shouldRetryClaudeCodeToolSurfaceReadiness,
 	buildWorkflowMcpReadinessProgressMessage,
 	pushWorkflowMcpReadinessProgressEvent,
+	resolveWorkflowMcpPreflightServerConfig,
 } from "../stream-adapter.ts";
 import { CLAUDE_CODE_MODELS } from "../models.ts";
 import type { AssistantMessage, Context, Message } from "@gsd/pi-ai";
 import type { SDKUserMessage } from "../sdk-types.ts";
 import { _setAutoActiveForTest } from "../../gsd/auto.ts";
+import { autoSession } from "../../gsd/auto-runtime-state.ts";
 import { getInFlightToolCount, hasInteractiveToolInFlight, clearInFlightTools, isInteractiveElicitationInFlight } from "../../gsd/auto-tool-tracking.ts";
 import { clearMcpConfigCache } from "../../mcp-client/manager.ts";
 import { UNIT_TOOL_CONTRACTS } from "../../gsd/unit-tool-contracts.ts";
@@ -405,6 +407,10 @@ describe("stream-adapter — image prompt forwarding (#4183)", () => {
 			systemPrompt: "UNIT: Run UAT",
 			messages: [{ role: "user", content: "Run UAT." } as Message],
 		};
+		// The test requires a resolved GSD phase so the readiness gate fires.
+		// Auto-mode with a currentUnit provides the authoritative phase signal.
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = { type: "run-uat", id: "M001/S001", startedAt: 0, workspaceRoot: cwd } as never;
 		try {
 			const stream = streamViaClaudeCode(
 				{ id: "claude-sonnet-4-6" } as any,
@@ -473,6 +479,8 @@ describe("stream-adapter — image prompt forwarding (#4183)", () => {
 			assert.equal(queryCalls, 2);
 			assert.deepEqual(message.content, [{ type: "text", text: "fresh retry result" }]);
 		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
 			rmSync(cwd, { recursive: true, force: true });
 		}
 	});
@@ -1543,18 +1551,43 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		assert.equal(inferGsdPhaseFromContext(context), "plan-milestone");
 	});
 
-	test("inferGsdPhaseFromContext recognizes discuss-slice and refine-slice prompts", () => {
-		const discussSlice = {
-			messages: [{ role: "user", content: "Discuss slice S001 in milestone M001." }],
-		} as Context;
+	test("inferGsdPhaseFromContext recognizes the refine-slice UNIT header", () => {
 		const refineSlice = {
 			messages: [{ role: "user", content: "## UNIT: Refine Slice S001 (\"Auth\") - Milestone M001" }],
 		} as Context;
 
-		assert.equal(inferGsdPhaseFromContext(discussSlice), "discuss-slice");
 		assert.equal(inferGsdPhaseFromContext(refineSlice), "refine-slice");
 	});
 
+	test("inferGsdPhaseFromContext ignores bare phase slugs and prose (only the UNIT header counts)", () => {
+		// Prose mentioning a phase must NOT classify the turn — this was the leak
+		// that stripped tools the moment a user said "slice" or "UAT".
+		const prose = {
+			messages: [{ role: "user", content: "Can you discuss the slice S001 and then run UAT for me?" }],
+		} as Context;
+		const bareSlug = {
+			messages: [{ role: "user", content: "I edited e2e/m039-s05-comparison-legibility.spec.ts (plan-slice, run-uat)" }],
+		} as Context;
+
+		assert.equal(inferGsdPhaseFromContext(prose), undefined);
+		assert.equal(inferGsdPhaseFromContext(bareSlug), undefined);
+	});
+
+	test("inferGsdPhaseFromContext does not match a UNIT header buried in scrollback", () => {
+		// A UNIT header from a prior turn (e.g. a SUMMARY the agent read) must not
+		// re-classify later ad-hoc turns. Only the system prompt + latest user
+		// message are scanned.
+		const context = {
+			messages: [
+				{ role: "user", content: "## UNIT: Run UAT — M001/S001" },
+				{ role: "assistant", content: "Done." },
+				{ role: "user", content: "Thanks, now what files changed?" },
+			],
+		} as Context;
+
+		assert.equal(inferGsdPhaseFromContext(context), undefined);
+	});
+
 	test("resolveGsdPhaseForSdk prefers guided unit context over prompt inference", () => {
 		const projectRoot = "/tmp/gsd-guided-phase-project";
 		clearGuidedUnitContext();
@@ -1582,12 +1615,67 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		}
 	});
 
-	test("resolveGsdPhaseForSdk falls back to prompt inference when guided context is absent", () => {
+	test("resolveGsdPhaseForSdk returns undefined for ad-hoc turns (no guided context, auto inactive)", () => {
+		// The core bug: an ad-hoc turn must keep the full tool surface even when
+		// its text contains a UNIT header (e.g. pasted from a prior unit). No
+		// guided context + auto inactive => no phase, no preflight, no stripping.
 		clearGuidedUnitContext();
-		const context = {
-			messages: [{ role: "user", content: "## UNIT: Run UAT — M001/S001" }],
-		} as Context;
-		assert.equal(resolveGsdPhaseForSdk(context, "/tmp/unrelated-project"), "run-uat");
+		_setAutoActiveForTest(false);
+		try {
+			const context = {
+				messages: [{ role: "user", content: "## UNIT: Run UAT — M001/S001 (pasted from earlier)" }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/unrelated-project"), undefined);
+		} finally {
+			_setAutoActiveForTest(false);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk uses the authoritative auto currentUnit, even with no UNIT header in the prompt", () => {
+		// gate-evaluate / validate-milestone dispatch prompts have no `UNIT:`
+		// header, so header inference alone would drop their phase (and their
+		// workflow-MCP preflight). The dispatched unit type is authoritative.
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = { type: "gate-evaluate", id: "M001/S001", startedAt: 0, workspaceRoot: "/tmp/p" } as never;
+		try {
+			const context = {
+				messages: [{ role: "user", content: "Quality Gate Evaluation — Parallel Dispatch. Call gsd_save_gate_result." }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/p"), "gate-evaluate");
+		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk ignores hook/* pseudo-units from currentUnit", () => {
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = { type: "hook/agent-end", id: "x", startedAt: 0, workspaceRoot: "/tmp/p" } as never;
+		try {
+			const context = { messages: [{ role: "user", content: "no phase here" }] } as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/p"), undefined);
+		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk infers from the UNIT header only while auto-mode is active and no currentUnit is recorded", () => {
+		// Last-resort fallback: auto running but currentUnit unexpectedly absent.
+		// Classifies from the `UNIT:` dispatch header only.
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = null;
+		try {
+			const context = {
+				messages: [{ role: "user", content: "## UNIT: Run UAT — M001/S001" }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/unrelated-project"), "run-uat");
+		} finally {
+			_setAutoActiveForTest(false);
+		}
 	});
 
 	test("buildSdkOptions presents ask_user_questions for discuss phases", () => {
@@ -1913,6 +2001,90 @@ describe("stream-adapter — session persistence (#2859)", () => {
 });
 
 describe("stream-adapter — workflow MCP readiness", () => {
+	test("resolves the workflow MCP preflight config from SDK mcpServers", () => {
+		const workflowConfig = { command: "node", args: ["workflow-server.js"] };
+		const browserConfig = { command: "gsd-browser" };
+
+		assert.equal(
+			resolveWorkflowMcpPreflightServerConfig(
+				{ "gsd-workflow": workflowConfig, "gsd-browser": browserConfig },
+				"gsd-workflow",
+			),
+			workflowConfig,
+		);
+		assert.equal(resolveWorkflowMcpPreflightServerConfig({ "gsd-workflow": "invalid" }, "gsd-workflow"), undefined);
+		assert.equal(resolveWorkflowMcpPreflightServerConfig({ "gsd-workflow": workflowConfig }, undefined), undefined);
+	});
+
+	test("workflow MCP preflight uses the same inline config passed to the SDK", async () => {
+		const projectRoot = realpathSync(mkdtempSync(join(tmpdir(), "claude-sdk-inline-preflight-")));
+		const restore = setWorkflowMcpEnv({});
+		let queryCalls = 0;
+		try {
+			const require = createRequire(import.meta.url);
+			const mcpModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/mcp.js")).href;
+			const stdioModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/stdio.js")).href;
+			const serverPath = join(projectRoot, "fake-workflow-mcp-server.mjs");
+			writeFileSync(
+				serverPath,
+				[
+					`const { McpServer } = await import(${JSON.stringify(mcpModuleUrl)});`,
+					`const { StdioServerTransport } = await import(${JSON.stringify(stdioModuleUrl)});`,
+					'const server = new McpServer({ name: "fake", version: "1.0.0" }, { capabilities: { tools: {} } });',
+					'server.tool("gsd_plan_slice", "Plan slice", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+					'server.tool("gsd_reassess_roadmap", "Reassess roadmap", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+					'await server.connect(new StdioServerTransport());',
+				].join("\n"),
+				"utf-8",
+			);
+			process.env.GSD_WORKFLOW_MCP_COMMAND = process.execPath;
+			process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify([serverPath]);
+			process.env.GSD_WORKFLOW_MCP_NAME = "gsd-workflow";
+
+			const stream = streamViaClaudeCode(
+				{ id: "claude-sonnet-4-6" } as any,
+				{
+					systemPrompt: "UNIT: Plan Slice",
+					messages: [{ role: "user", content: "Plan the next slice." } as Message],
+				},
+				{
+					cwd: projectRoot,
+					async *_sdkQueryForTest() {
+						queryCalls += 1;
+						yield {
+							type: "result",
+							subtype: "success",
+							uuid: "result-1",
+							session_id: "session-1",
+							duration_ms: 1,
+							duration_api_ms: 1,
+							is_error: false,
+							num_turns: 1,
+							result: "planned",
+							stop_reason: "end_turn",
+							total_cost_usd: 0,
+							usage: {
+								input_tokens: 0,
+								output_tokens: 0,
+								cache_read_input_tokens: 0,
+								cache_creation_input_tokens: 0,
+							},
+						};
+					},
+				} as any,
+			);
+
+			const message = await stream.result();
+
+			assert.equal(queryCalls, 1);
+			assert.deepEqual(message.content, [{ type: "text", text: "planned" }]);
+		} finally {
+			restore();
+			rmSync(projectRoot, { recursive: true, force: true });
+			clearMcpConfigCache();
+		}
+	});
+
 	test("emits visible progress text before workflow MCP readiness waits", () => {
 		const partial: AssistantMessage = {
 			role: "assistant",

package/src/resources/extensions/google-cli/stream-adapter.ts

@@ -204,6 +204,27 @@ function emitText(stream: AssistantMessageEventStream, message: AssistantMessage
 	stream.end(message);
 }
 
+function isGeminiCliDeprecatedCliOutput(text: string): boolean {
+	return (
+		/IneligibleTierError/i.test(text)
+		|| /UNSUPPORTED_CLIENT/i.test(text)
+		|| /no longer supported for Gemini Code Assist for individuals/i.test(text)
+		|| /migrate to the Antigravity suite/i.test(text)
+	);
+}
+
+const GEMINI_CLI_DEPRECATION_HINT =
+	"Gemini CLI is no longer supported for individual users. Install Antigravity CLI " +
+	"(curl -fsSL https://antigravity.google/cli/install.sh | bash), run `agy` to authenticate, " +
+	"then use /login → Antigravity or restart GSD to auto-migrate.";
+
+function formatGoogleCliError(detail: string, provider: GoogleCliProviderId): string {
+	if (provider === "google-gemini-cli" && isGeminiCliDeprecatedCliOutput(detail)) {
+		return `${detail}\n\n${GEMINI_CLI_DEPRECATION_HINT}`;
+	}
+	return detail;
+}
+
 function emitError(stream: AssistantMessageEventStream, model: Model<Api>, error: unknown): void {
 	const message = error instanceof Error ? error.message : String(error);
 	const output = buildAssistantMessage(model, "", "error", message);
@@ -228,7 +249,7 @@ export function streamViaGoogleCli(
 
 			if (result.code !== 0) {
 				const detail = (result.stderr || result.stdout || `CLI exited with code ${result.code}`).trim();
-				throw new Error(detail);
+				throw new Error(formatGoogleCliError(detail, provider));
 			}
 
 			const text = provider === "google-gemini-cli"

package/src/resources/extensions/gsd/auto/dispatch-history.ts

@@ -82,6 +82,19 @@ export interface DispatchHistoryOptions {
    */
   resolveScopeId: () => string | null;
   windowSize?: number;
+  /**
+   * Session-level trace_id used to scope `rehydrate()` to the CURRENT session
+   * so stale finalize-retry entries from PREVIOUS sessions don't fire
+   * detectStuck Rule 1 on the first advance of a new session — killing
+   * auto-mode before any new dispatch runs (#852). When provided, only
+   * dispatches recorded with this trace_id are returned by the DB query;
+   * a brand-new session trace_id that has never been written to unit_dispatches
+   * returns 0 rows, giving a clean stuck window on session start.
+   *
+   * The unscoped (no resolveTraceId) path is preserved for callers without a
+   * session context so existing behaviour for those paths is unchanged.
+   */
+  resolveTraceId?: () => string | null;
 }
 
 /**
@@ -137,7 +150,12 @@ export function createDispatchHistory(options: DispatchHistoryOptions): Dispatch
       const scopeId = options.resolveScopeId();
       if (!scopeId) return 0;
       try {
-        const persisted = getRecentUnitKeysForProjectRoot(scopeId, windowSize);
+        // Scope to the current session's trace_id when available (#852):
+        // a fresh session UUID that has never been written to unit_dispatches
+        // returns 0 rows so prior-session failures don't pre-populate the
+        // stuck window and immediately block the new session.
+        const traceId = options.resolveTraceId?.() ?? undefined;
+        const persisted = getRecentUnitKeysForProjectRoot(scopeId, windowSize, traceId);
         if (persisted.length === 0) return 0;
         const rebuilt: WindowEntry[] = [];
         for (const { key } of persisted) {

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

@@ -175,6 +175,7 @@ function resolveCompletionStopFromOutcome(
 // tolerates — same behavior as a fresh session.
 const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
 const MAX_CONSECUTIVE_ALREADY_ACTIVE_SKIPS = 3;
+const MAX_CONSECUTIVE_ORCHESTRATION_SKIPS = 3;
 const ORCHESTRATION_MISSING_REASON =
   "Auto Orchestration Module is not wired; cannot dispatch built-in GSD Unit.";
 
@@ -186,7 +187,20 @@ function loadStuckState(s: AutoSession): { recentUnits: Array<{ key: string }>;
   const scopeId = stableStuckStateScopeId(s);
   if (!scopeId) return { recentUnits: [], stuckRecoveryAttempts: 0 };
   try {
-    const recentUnits = getRecentUnitKeysForProjectRoot(scopeId, STUCK_WINDOW_SIZE);
+    // Scope the stuck window to the CURRENT session (trace_id) so stale
+    // finalize-retry entries from previous sessions don't fire detectStuck
+    // Rule 1 on the first iteration — killing auto-mode before any new
+    // dispatch runs (#852). A prior session's two consecutive finalize-retry
+    // failures would otherwise permanently block every new session.
+    //
+    // s.currentTraceId is only set inside the first loop iteration (line ~443),
+    // so at this call-site it is always null for a fresh session. Return []
+    // directly in that case — no prior dispatch has occurred in this session,
+    // so the stuck window is trivially empty and the DB query is skipped.
+    const recentUnits =
+      s.currentTraceId != null
+        ? getRecentUnitKeysForProjectRoot(scopeId, STUCK_WINDOW_SIZE, s.currentTraceId)
+        : [];
     const stuckRecoveryAttempts =
       getRuntimeKv<number>("global", scopeId, STUCK_RECOVERY_ATTEMPTS_KEY) ?? 0;
     return { recentUnits, stuckRecoveryAttempts };
@@ -406,6 +420,8 @@ export async function autoLoop(
   let consecutiveErrors = 0;
   let consecutiveCooldowns = 0;
   let consecutiveAlreadyActiveSkips = 0;
+  let consecutiveOrchestrationSkips = 0;
+  let lastOrchestrationSkipKey: string | null = null;
   const recentErrorMessages: string[] = [];
 
   while (s.active) {
@@ -925,12 +941,53 @@ export async function autoLoop(
 
           if (orchestrationResult.kind === "skipped") {
             s.pendingOrchestrationDispatch = null;
+            // Idempotent re-poll skips are benign (an active unit is still running).
+            // The orchestrator's own stuck-window detection handles the truly-stuck case.
+            // Do not count these toward the consecutive-skip streak.
+            if (orchestrationResult.reason === "idempotent advance: unit already active") {
+              emitIterationEnd({ skipped: true });
+              completeIteration();
+              finishTurn("skipped");
+              continue;
+            }
+            const skipState = orchestrationResult.stateSnapshot;
+            const skipKey = [
+              orchestrationResult.reason,
+              skipState?.phase,
+              skipState?.activeMilestone?.id,
+              skipState?.activeSlice?.id,
+              skipState?.activeTask?.id,
+            ].join("|");
+            consecutiveOrchestrationSkips = skipKey === lastOrchestrationSkipKey
+              ? consecutiveOrchestrationSkips + 1
+              : 1;
+            lastOrchestrationSkipKey = skipKey;
+            if (consecutiveOrchestrationSkips >= MAX_CONSECUTIVE_ORCHESTRATION_SKIPS) {
+              const msg = `Orchestration skipped ${consecutiveOrchestrationSkips} consecutive attempts without progress. Pausing auto-mode for manual recovery.`;
+              ctx.ui.notify(msg, "error");
+              await deps.pauseAuto(ctx, pi, {
+                message: msg,
+                category: "unknown",
+              }, {
+                expectedCurrentUnit: null,
+              });
+              finishTurn("paused", "manual-attention", orchestrationResult.reason ?? "orchestration-skipped");
+              finishIncompleteIteration({
+                status: "paused",
+                reason: orchestrationResult.reason ?? "orchestration-skipped",
+                failureClass: "manual-attention",
+              });
+              break;
+            }
             emitIterationEnd({ skipped: true });
             completeIteration();
             finishTurn("skipped");
             continue;
           }
 
+          consecutiveOrchestrationSkips = 0;
+          lastOrchestrationSkipKey = null;
+
           if (orchestrationResult.kind === "paused") {
             s.pendingOrchestrationDispatch = null;
             finishIncompleteIteration({
@@ -1331,7 +1388,17 @@ export async function autoLoop(
         finalizeResult.action === "break"
           ? { action: "break", reason: finalizeResult.reason }
           : finalizeResult.action === "continue"
-            ? { action: "continue" }
+            ? {
+                action: "continue",
+                // Surface the specific verification failure (e.g. "roadmap has
+                // zero slices") in the ledger/stuck-loop reason instead of the
+                // opaque bare "finalize-retry" token. The retry paths in
+                // runFinalize set s.pendingVerificationRetry.failureContext
+                // from describeArtifactVerificationFailure before returning
+                // continue; it is cleared on the next dispatch, so reading it
+                // here captures the reason for THIS finalize (#852 follow-up).
+                failureDetail: s.pendingVerificationRetry?.failureContext,
+              }
             : { action: "next" },
       );
       if (finalizeDecision.action === "stop") {

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

@@ -38,7 +38,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,
@@ -80,6 +80,17 @@ function now(): number {
   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: ((projectRoot: string) => Promise<void>) | null = null;
+
 function noRemainingUnitsOutcome(stateSnapshot: GSDState): AutoTerminalOutcome {
   if (stateSnapshot.phase === "complete") {
     return {
@@ -196,7 +207,14 @@ export async function decideOrchestratorDispatch(
   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),
+    activeSession?.autoModeStartModel
+      ? `${activeSession.autoModeStartModel.provider}/${activeSession.autoModeStartModel.id}`
+      : undefined,
+  )?.preferences;
   if (!active) {
     if (state.phase !== "pre-planning") return null;
     if (!hasPendingDeepStage(prefs, activeDispatchBasePath)) {
@@ -509,7 +527,14 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     milestoneId?: string;
   }): Promise<void> {
     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),
+      this.s.autoModeStartModel
+        ? `${this.s.autoModeStartModel.provider}/${this.s.autoModeStartModel.id}`
+        : undefined,
+    )?.preferences;
     const uokFlags = resolveUokFlags(prefs);
     if (!uokFlags.gates) return;
     const milestoneId = input.milestoneId ?? this.s.currentMilestoneId ?? undefined;
@@ -631,8 +656,15 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     this.s.milestoneSettlement = { ok: true, reason: "settled" };
     try {
       const projectRoot = this.s.originalBasePath || this.s.canonicalProjectRoot || this.runtimeBasePath;
-      const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
-      await rebuildMarkdownProjectionsFromDb(projectRoot);
+      // 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",
@@ -886,12 +918,17 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async start(_sessionContext: AutoSessionContext): Promise<AutoAdvanceResult> {
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
-    // #482: the DB dispatch ledger is the source of truth across sessions.
-    // Discard any in-memory window and rebuild it from the ledger so a unit
-    // that was re-dispatched in previous sessions is detected as stuck here
-    // instead of silently re-dispatching forever.
+    // #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.dispatchHistory.rehydrate();
     this.lastStuckRecoveryKey = null;
     this.lastDerivedPhase = null;
     this.status.phase = "running";
@@ -1425,3 +1462,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; };
+}

package/src/resources/extensions/gsd/auto/pre-dispatch.ts

@@ -38,13 +38,19 @@ import {
 } from "./closeout.js";
 import type { IterationContext, LoopState, PhaseResult, PreDispatchData } from "./types.js";
 
-type BlockerKind = "needs-remediation-dead-end" | "other";
+type BlockerKind = "needs-remediation-dead-end" | "completed-milestone-reopened" | "other";
 
 function classifyBlocker(blocker: string): BlockerKind {
   const normalized = blocker.toLowerCase();
   if (normalized.includes("needs-remediation") && normalized.includes("all slices are complete")) {
     return "needs-remediation-dead-end";
   }
+  if (
+    normalized.includes("completed closeout dispatch history") ||
+    normalized.includes("completed complete-milestone dispatch history")
+  ) {
+    return "completed-milestone-reopened";
+  }
   return "other";
 }
 
@@ -67,6 +73,12 @@ function formatBlockedResumeMessage(blockers: string[]): string {
   if (hasNeedsRemediationDeadEnd) {
     return "Blocked: milestone validation requires remediation but all slices are complete. Run /gsd dispatch reassess to add remediation slices, then /gsd auto to continue.";
   }
+  const completedMilestoneReopened = classifiedBlockers.find(
+    (classifiedBlocker) => classifiedBlocker.kind === "completed-milestone-reopened",
+  );
+  if (completedMilestoneReopened) {
+    return completedMilestoneReopened.blocker;
+  }
   return `Blocked: ${classifiedBlockers.map((classifiedBlocker) => classifiedBlocker.blocker).join(", ")}. Fix and run /gsd auto to resume.`;
 }
 

package/src/resources/extensions/gsd/auto/workflow-kernel.ts

@@ -34,7 +34,7 @@ export type EngineDispatchDecision =
 
 export type FinalizeInput =
   | { action: "break"; reason?: string }
-  | { action: "continue" }
+  | { action: "continue"; failureDetail?: string }
   | { action: "next" };
 
 export type FinalizeDecision =
@@ -46,7 +46,14 @@ export type FinalizeDecision =
     }
   | {
       action: "retry";
-      ledgerErrorSummary: "finalize-retry";
+      /**
+       * Stable `"finalize-retry"` prefix plus, when available, the specific
+       * verification failure (e.g. `finalize-retry: roadmap has zero slices`).
+       * The prefix keeps legacy ledger filters matching; the suffix makes a
+       * stuck-loop kill message actionable instead of the opaque bare token
+       * that forced a full forensics dive to diagnose (#852 follow-up).
+       */
+      ledgerErrorSummary: string;
     }
   | { action: "complete" }
   | { action: "complete-and-break" };
@@ -295,6 +302,16 @@ function isCompleteAndBreakReason(
   );
 }
 
+/** Strip per-attempt counter suffixes so detect-stuck Rule 1 can match repeats. */
+const FAILURE_DETAIL_ATTEMPT_SUFFIX_RE = /\s*\(attempt\s+\d+(?:\/\d+)?\)\.?$/i;
+
+function failureDetailForLedger(detail: string | undefined): string | undefined {
+  const trimmed = detail?.trim();
+  if (!trimmed) return undefined;
+  const normalized = trimmed.replace(FAILURE_DETAIL_ATTEMPT_SUFFIX_RE, "").trim();
+  return normalized || undefined;
+}
+
 export function decideFinalizeResult(input: FinalizeInput): FinalizeDecision {
   if (input.action === "break") {
     const reason = input.reason ?? "unknown";
@@ -310,9 +327,14 @@ export function decideFinalizeResult(input: FinalizeInput): FinalizeDecision {
   }
 
   if (input.action === "continue") {
+    // Carry the specific verification failure (e.g. "roadmap has zero slices",
+    // "15-SUMMARY.md was not found on disk") into the ledger summary so the
+    // stuck-loop kill message is actionable. The `finalize-retry` prefix is
+    // preserved so legacy ledger filters and dashboards still match (#852).
+    const detail = failureDetailForLedger(input.failureDetail);
     return {
       action: "retry",
-      ledgerErrorSummary: "finalize-retry",
+      ledgerErrorSummary: detail ? `finalize-retry: ${detail}` : "finalize-retry",
     };
   }