@opengsd/gsd-pi 1.2.0-dev.d6c5343c → 1.2.0-dev.ddc97c10

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -2,7 +2,7 @@
 import { logWarning } from "../workflow-logger.js";
 import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
 import { clearPathCache } from "../paths.js";
-import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, isAutoCompletionStopInProgress, pauseAuto, setCurrentDispatchedModelId, } from "../auto.js";
+import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, isAutoCompletionStopInProgress, pauseAuto, setCurrentDispatchedModelId, setCurrentUnitModelForRecovery, } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchAbortGraceActive, isSessionSwitchInFlight, resolveAgentEnd, resolveAgentEndCancelled, } from "../auto/resolve.js";
@@ -13,7 +13,7 @@ import { clearDiscussionFlowState } from "./write-gate.js";
 import { clearGuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } from "../error-classifier.js";
-import { blockModel, isModelBlocked } from "../blocked-models.js";
+import { blockModel, blockModelUntil, isModelBlocked, isModelTemporarilyUnavailable } from "../blocked-models.js";
 import { getProjectGSDPreferencesPath } from "../preferences.js";
 import { resolveProviderErrorGuidance } from "../provider-error-guidance.js";
 import { formatGuidance } from "../guidance.js";
@@ -96,9 +96,12 @@ async function tryProviderModelFallback(params) {
             if (!nextModelId)
                 break;
             const candidate = resolveModelId(nextModelId, availableModels, rejectedProvider);
-            if (candidate && !isModelBlocked(basePath, candidate.provider, candidate.id)) {
+            if (candidate &&
+                !isModelBlocked(basePath, candidate.provider, candidate.id) &&
+                !isModelTemporarilyUnavailable(basePath, candidate.provider, candidate.id)) {
                 const ok = await pi.setModel(candidate, { persist: false });
                 if (ok) {
+                    setCurrentUnitModelForRecovery(candidate);
                     setCurrentDispatchedModelId({ provider: candidate.provider, id: candidate.id });
                     switchedNotify(`${candidate.provider}/${candidate.id}`);
                     pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -111,11 +114,13 @@ async function tryProviderModelFallback(params) {
     const sessionModel = getAutoModeStartModel();
     if (sessionModel &&
         !(sessionModel.provider === rejectedProvider && sessionModel.id === rejectedId) &&
-        !isModelBlocked(basePath, sessionModel.provider, sessionModel.id)) {
+        !isModelBlocked(basePath, sessionModel.provider, sessionModel.id) &&
+        !isModelTemporarilyUnavailable(basePath, sessionModel.provider, sessionModel.id)) {
         const startModel = availableModels.find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
         if (startModel) {
             const ok = await pi.setModel(startModel, { persist: false });
             if (ok) {
+                setCurrentUnitModelForRecovery(startModel);
                 setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
                 switchedNotify(`${startModel.provider}/${startModel.id}`);
                 pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -533,6 +538,10 @@ export async function handleAgentEnd(pi, event, ctx) {
             if (currentProvider === "openai-codex" || currentProvider === "google-gemini-cli") {
                 cls.retryAfterMs = Math.min(cls.retryAfterMs, 30_000);
             }
+            const dash = getAutoDashboardData();
+            if (dash.basePath && ctx.model?.provider && ctx.model?.id) {
+                blockModelUntil(dash.basePath, ctx.model.provider, ctx.model.id, Date.now() + cls.retryAfterMs, rawErrorMsg || displayMsg || "rate limit");
+            }
         }
         // ── 2. Decide & Act ──────────────────────────────────────────────────
         // --- Network errors: same-model retry with backoff ---
@@ -572,9 +581,14 @@ export async function handleAgentEnd(pi, event, ctx) {
                         retryState.networkRetryCount = 0;
                         retryState.currentRetryModelId = undefined;
                         const modelToSet = resolveModelId(nextModelId, availableModels, ctx.model?.provider);
-                        if (modelToSet) {
+                        const modelUnavailable = dash.basePath && modelToSet
+                            ? isModelBlocked(dash.basePath, modelToSet.provider, modelToSet.id) ||
+                                isModelTemporarilyUnavailable(dash.basePath, modelToSet.provider, modelToSet.id)
+                            : false;
+                        if (modelToSet && !modelUnavailable) {
                             const ok = await pi.setModel(modelToSet, { persist: false });
                             if (ok) {
+                                setCurrentUnitModelForRecovery(modelToSet);
                                 setCurrentDispatchedModelId({ provider: modelToSet.provider, id: modelToSet.id });
                                 ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
                                 pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -587,11 +601,17 @@ export async function handleAgentEnd(pi, event, ctx) {
             // Try restoring session model
             const sessionModel = getAutoModeStartModel();
             if (sessionModel) {
-                if (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider) {
+                const dash = getAutoDashboardData();
+                const sessionModelUnavailable = dash.basePath
+                    ? isModelBlocked(dash.basePath, sessionModel.provider, sessionModel.id) ||
+                        isModelTemporarilyUnavailable(dash.basePath, sessionModel.provider, sessionModel.id)
+                    : false;
+                if (!sessionModelUnavailable && (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider)) {
                     const startModel = ctx.modelRegistry.getAvailable().find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
                     if (startModel) {
                         const ok = await pi.setModel(startModel, { persist: false });
                         if (ok) {
+                            setCurrentUnitModelForRecovery(startModel);
                             setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
                             retryState.networkRetryCount = 0;
                             retryState.currentRetryModelId = undefined;

package/dist/resources/extensions/gsd/bootstrap/exec-tools.js

@@ -114,8 +114,8 @@ export function registerExecTools(pi) {
         ],
         parameters: Type.Object({
             query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
-            runtime: Type.Optional(Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
-                description: "Restrict to one runtime.",
+            runtime: Type.Optional(Type.String({
+                description: "Restrict to one runtime: bash, node, or python.",
             })),
             failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
             limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),

package/dist/resources/extensions/gsd/closeout-wizard.js

@@ -1,22 +1,107 @@
 // Project/App: gsd-pi
 // File Purpose: Shared closeout detection and merge actions for /gsd home and smart entry.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
 import { setAutoOutcomeWidget } from "./auto-dashboard.js";
 import { invalidateAllCaches } from "./cache.js";
+import { isDbAvailable } from "./db/engine.js";
+import { getMilestone } from "./db/queries.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { mergeCompletedMilestone } from "./parallel-merge.js";
 import { cleanupQuickBranch, detectStrandedQuickBranch } from "./quick.js";
+import { isClosedStatus } from "./status-guards.js";
 import { findUnmergedCompletedMilestones, } from "./unmerged-milestone-guard.js";
 import { appendRequirementsBacklogToSummary } from "./requirements-backlog.js";
+import { nativeBranchList, nativeIsRepo } from "./native-git-bridge.js";
+import { allWorktreesDirs } from "./worktree-manager.js";
 const MILESTONE_MERGE_CLOSEOUT_COMMANDS = [
     "/gsd status for overview",
     "/gsd visualize to inspect",
     "/gsd notifications for history",
     "/gsd start for new work",
 ];
+function listMilestoneWorktreeIds(basePath) {
+    const ids = new Set();
+    for (const wtDir of allWorktreesDirs(basePath)) {
+        if (!existsSync(wtDir))
+            continue;
+        for (const entry of readdirSync(wtDir)) {
+            if (!MILESTONE_ID_RE.test(entry))
+                continue;
+            try {
+                if (statSync(join(wtDir, entry)).isDirectory())
+                    ids.add(entry);
+            }
+            catch {
+                // skip unreadable entries
+            }
+        }
+    }
+    return [...ids].sort();
+}
+function listMilestoneBranchIds(basePath) {
+    try {
+        return nativeBranchList(basePath, "milestone/*")
+            .map((branch) => branch.replace(/^milestone\//, ""))
+            .filter((id) => MILESTONE_ID_RE.test(id))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * A milestone ID is "stranded residue" only when its worktree/branch artifacts
+ * exist for a milestone the DB does not consider currently in flight — i.e. the
+ * row is closed (complete/done/skipped/closed) or absent. Active, pending,
+ * blocked, parked, queued, and deferred rows describe normal in-flight or
+ * intentionally-preserved state, never residue. Returning `false` skips the ID;
+ * returning `true` keeps it in the hint.
+ */
+function isStrandedMilestoneId(milestoneId) {
+    if (!isDbAvailable())
+        return true;
+    const row = getMilestone(milestoneId);
+    if (!row)
+        return true;
+    return isClosedStatus(row.status);
+}
+/** Surface stranded milestone git residue when closeout guards did not classify it. */
+export function detectIdleMilestoneResidueHint(basePath) {
+    if (!nativeIsRepo(basePath))
+        return null;
+    const gsdDir = join(basePath, ".gsd");
+    const dbPath = join(gsdDir, "gsd.db");
+    if (!existsSync(gsdDir) || !existsSync(dbPath)) {
+        return {
+            milestoneIds: [],
+            message: "This git repo has no local GSD workflow database (.gsd/gsd.db). " +
+                "Workflow state may live in an external worktree, or run /gsd new-project to initialize here.",
+        };
+    }
+    const worktreeIds = listMilestoneWorktreeIds(basePath);
+    const branchIds = listMilestoneBranchIds(basePath);
+    const candidateIds = [...new Set([...worktreeIds, ...branchIds])].sort();
+    const milestoneIds = candidateIds.filter(isStrandedMilestoneId);
+    if (milestoneIds.length === 0)
+        return null;
+    const listed = milestoneIds.join(", ");
+    const recovery = milestoneIds.length === 1
+        ? `/gsd dispatch complete-milestone ${milestoneIds[0]}`
+        : "/gsd doctor --fix";
+    return {
+        milestoneIds,
+        message: `Stranded milestone git residue detected (${listed}: worktree dir and/or milestone/* branch). ` +
+            `Run ${recovery} or /gsd status to recover closeout before starting new work.`,
+    };
+}
 export async function loadCloseoutContext(basePath) {
     const unmergedMilestones = await findUnmergedCompletedMilestones(basePath);
+    const idleResidueHint = unmergedMilestones.length === 0 ? detectIdleMilestoneResidueHint(basePath) : null;
     return {
         strandedQuick: detectStrandedQuickBranch(basePath),
         unmergedMilestones,
+        idleResidueHint,
     };
 }
 export function getPrimaryCloseoutRecommendation(closeout) {
@@ -62,6 +147,13 @@ export function buildIdleMenuSummary(state, closeout) {
             `${blocker.milestoneId} is complete but not merged into ${blocker.integrationBranch}.`,
         ];
     }
+    // Surface idle residue before the completion summary so smart entry shows
+    // the same recovery text /gsd home would: a closed/unknown milestone with
+    // lingering worktree/branch artifacts must not be hidden behind the
+    // "all milestones complete" message.
+    if (closeout.idleResidueHint) {
+        return [closeout.idleResidueHint.message];
+    }
     if (state.phase === "complete") {
         const last = state.lastCompletedMilestone;
         return appendRequirementsBacklogToSummary(state, [

package/dist/resources/extensions/gsd/commands/context.js

@@ -1,4 +1,4 @@
-import { checkRemoteAutoSession, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
+import { checkRemoteAutoSession, forceStopAutoRemote, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
 import { validateDirectory } from "../validate-directory.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { showNextAction } from "../../shared/tui.js";
@@ -135,5 +135,19 @@ export async function guardRemoteSession(ctx, pi) {
         }
         return false;
     }
-    return choice === "force";
+    if (choice === "force") {
+        const result = forceStopAutoRemote(projectRoot());
+        if (result.error) {
+            ctx.ui.notify(`Failed to force-stop remote auto-mode: ${result.error}`, "error");
+            return false;
+        }
+        if (result.found) {
+            ctx.ui.notify(`Force-stopped auto-mode session (PID ${result.pid}). Starting a new session.`, "warning");
+        }
+        else {
+            ctx.ui.notify("Remote session is no longer running. Starting a new session.", "info");
+        }
+        return true;
+    }
+    return false;
 }

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -7,7 +7,7 @@
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { join, resolve as resolvePath, sep } from "node:path";
+import { join, resolve as resolvePath, sep, win32 as pathWin32 } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
@@ -20,6 +20,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";
+import { reconcileGsdBrowserPathAfterInstall } from "../../shared/gsd-browser-path-sync.js";
 import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import { buildDoctorHealIssuePayload, buildDoctorHealSummary, buildWorkflowDispatchContent, } from "./workflow-protocol.js";
 import { restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch, } from "./bootstrap/register-hooks.js";
@@ -51,8 +52,31 @@ function resolveInstallCommand(pkg) {
         return `bun add -g ${pkg}`;
     if (isPnpmInstall())
         return `pnpm add -g ${pkg}`;
+    const npmPrefix = resolveWindowsNpmGlobalPrefix();
+    if (npmPrefix)
+        return `npm --prefix ${quoteWindowsArg(npmPrefix)} install -g ${pkg}`;
     return `npm install -g ${pkg}`;
 }
+function resolveWindowsNpmGlobalPrefix(argv1 = process.argv[1], platform = process.platform) {
+    if (platform !== "win32" || !argv1)
+        return null;
+    const normalized = pathWin32.normalize(argv1);
+    const marker = `${pathWin32.sep}node_modules${pathWin32.sep}`;
+    const index = normalized.toLowerCase().lastIndexOf(marker);
+    if (index <= 0)
+        return null;
+    const prefix = normalized.slice(0, index);
+    // Verify this is a real npm global prefix: such a directory always contains
+    // npm's own bin shim (`npm.cmd`) as a sibling of `node_modules/`. Local
+    // project `node_modules/`, npx caches, and other non-global layouts do not,
+    // so without this check `--prefix` would target the wrong directory.
+    if (!existsSync(pathWin32.join(prefix, "npm.cmd")))
+        return null;
+    return prefix;
+}
+function quoteWindowsArg(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
 function notifyClaudeRuntimeFloorAdvisory(ctx) {
     let advisory = null;
     try {
@@ -484,11 +508,30 @@ export async function handleUpdate(ctx, args = "") {
         execSync(installCmd, {
             stdio: ["ignore", "pipe", "ignore"],
         });
+        let reconcile = null;
+        if (browserUpdate) {
+            try {
+                reconcile = reconcileGsdBrowserPathAfterInstall({
+                    latestVersion: latest,
+                    compareSemver: compareSemverLocal,
+                    resolvePathVersion: resolveGsdBrowserPathVersionForCommand,
+                });
+            }
+            catch {
+                // Reconciliation is best-effort: the install above already succeeded,
+                // so a reconcile failure must not flip the result to "Update failed".
+                reconcile = null;
+            }
+        }
         const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
-        const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
+        const pathNote = browserUpdate && !(newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0)
+            ? (reconcile?.message
+                ?? "Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+            : "";
         ctx.ui.notify(browserUpdate
             ? `Updated gsd-browser to v${latest}. Restart your GSD session to use the new browser automation version.` +
-                (pathReady ? "" : "\nNote: Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+                (reconcile?.action === "synced" && reconcile.message ? `\n${reconcile.message}` : "") +
+                (pathNote ? `\nNote: ${pathNote}` : "")
             : `Updated to v${latest}. Restart your GSD session to use the new version.`, "info");
         if (!browserUpdate)
             notifyClaudeRuntimeFloorAdvisory(ctx);

package/dist/resources/extensions/gsd/consent-question.js

@@ -62,6 +62,20 @@ export function hasApprovalQuestion(text) {
 export function hasResearchDecisionQuestion(text) {
     return hasQuestionMatching(text, [RESEARCH_DECISION_QUESTION_RE]);
 }
+/**
+ * Detect a plain-text "Next steps:" menu — numbered options with an "Other"
+ * choice — emitted as prose instead of a structured ask_user_questions call.
+ * Without this, auto-mode treats the menu as informational and loops on its
+ * own turn until tokens are exhausted (#454).
+ */
+export function hasPlainTextNextStepsMenu(lines) {
+    const nextStepsIndex = lines.findIndex((line) => /^next steps\s*:?$/i.test(line));
+    if (nextStepsIndex < 0)
+        return false;
+    const menuLines = lines.slice(nextStepsIndex + 1);
+    const numberedOptions = menuLines.filter((line) => /^\d+[.)]\s+\S/.test(line));
+    return numberedOptions.length >= 2 && numberedOptions.some((line) => /\bother\b/i.test(line));
+}
 // ── Message text extraction (moved from user-input-boundary) ────────────────
 function extractMessageText(msg, includeThinking) {
     if (!msg || typeof msg !== "object")
@@ -273,6 +287,8 @@ export function isAwaitingUserInput(messages) {
     const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (lines.some((line) => line.endsWith("?")))
         return true;
+    if (hasPlainTextNextStepsMenu(lines))
+        return true;
     return hasApprovalQuestion(text);
 }
 export function isAwaitingApprovalBoundary(messages) {

package/dist/resources/extensions/gsd/crash-recovery.js

@@ -186,6 +186,7 @@ export function writeLock(basePath, unitType, unitId, sessionFile) {
  * stale session-file pointer.
  */
 export function clearLock(basePath) {
+    const legacyLock = readLegacyLock(basePath);
     clearLegacyLockFile(basePath);
     if (!isDbAvailable())
         return;
@@ -198,9 +199,13 @@ export function clearLock(basePath) {
             deleteRuntimeKv("worker", staleWorker.worker_id, SESSION_FILE_KV_KEY);
             return;
         }
-        const lock = readLegacyLock(basePath);
-        if (lock?.pid)
-            markWorkerStoppingByPid(projectRoot, lock.pid);
+        if (legacyLock?.pid) {
+            markWorkerStoppingByPid(projectRoot, legacyLock.pid);
+            const workerByLegacyPid = getAllAutoWorkers().find((w) => w.pid === legacyLock.pid
+                && normalizeRealPath(w.project_root_realpath) === projectRoot);
+            if (workerByLegacyPid)
+                forceReleaseLeasesForWorker(workerByLegacyPid.worker_id);
+        }
         const worker = findActiveWorkerForCurrentProcess(projectRoot);
         if (worker)
             deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -5,7 +5,7 @@ import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -239,7 +239,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
                     if (!roadmapPath || !existsSync(roadmapPath)) {
                         try {
-                            await renderAllProjections(basePath, milestone.id);
+                            await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
                         }
                         catch {
@@ -250,7 +250,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     const projectionMtime = statSync(roadmapPath).mtimeMs;
                     if (lastEventTs > projectionMtime) {
                         try {
-                            await renderAllProjections(basePath, milestone.id);
+                            await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
                             fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
                         }
                         catch {

package/dist/resources/extensions/gsd/doctor-git-checks.js

@@ -3,10 +3,9 @@ import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { loadFile } from "./files.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { deriveState, isMilestoneComplete } from "./state.js";
+import { isCompletedMilestoneTerminal } from "./milestone-closeout.js";
+import { deriveState } from "./state.js";
 import { allWorktreesDirs, createWorktree, listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
@@ -141,21 +140,6 @@ function getSnapshotDiffCheckFailure(basePath) {
     }
     return failures.length > 0 ? failures.join("\n") : null;
 }
-async function isCompletedMilestoneTerminal(basePath, milestoneId) {
-    const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
-    if (!summaryPath)
-        return false;
-    if (isDbAvailable()) {
-        const milestone = getMilestone(milestoneId);
-        return !!milestone && milestone.status === "complete";
-    }
-    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-    if (!roadmapContent)
-        return false;
-    const roadmap = parseLegacyRoadmap(roadmapContent);
-    return isMilestoneComplete(roadmap);
-}
 export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none") {
     // Degrade gracefully if not a git repo
     if (!nativeIsRepo(basePath)) {

package/dist/resources/extensions/gsd/gsd-command-home.js

@@ -28,13 +28,17 @@ export function buildGsdHomeModel(state, closeout) {
     const workLabel = activeWorkLabel(state);
     const strandedQuick = closeout?.strandedQuick ?? null;
     const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+    const idleResidueHint = closeout?.idleResidueHint ?? null;
+    const hasIdleResidue = Boolean(idleResidueHint);
     const nextReason = complete
         ? "all milestones are complete"
         : blocked
             ? "the active milestone is blocked"
-            : !hasActiveWork
-                ? "there is no active milestone"
-                : "";
+            : hasIdleResidue
+                ? "milestone git residue needs recovery"
+                : !hasActiveWork
+                    ? "there is no active milestone"
+                    : "";
     const canAdvance = hasActiveWork && !blocked && !complete;
     const unmappedActive = complete ? countUnmappedActiveRequirements() : 0;
     const recommended = strandedQuick
@@ -43,11 +47,13 @@ export function buildGsdHomeModel(state, closeout) {
             ? "finish_milestone"
             : blocked
                 ? "fix_recover"
-                : canAdvance
-                    ? "continue_step"
-                    : complete && unmappedActive > 0
-                        ? "review_requirements_backlog"
-                        : "start_configure";
+                : hasIdleResidue
+                    ? "fix_recover"
+                    : canAdvance
+                        ? "continue_step"
+                        : complete && unmappedActive > 0
+                            ? "review_requirements_backlog"
+                            : "start_configure";
     const completionSummary = complete
         ? appendRequirementsBacklogToSummary(state, [
             `All milestones complete${state.lastCompletedMilestone ? ` after ${state.lastCompletedMilestone.id}: ${state.lastCompletedMilestone.title}` : ""}.`,
@@ -57,7 +63,9 @@ export function buildGsdHomeModel(state, closeout) {
         ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
         : unmergedMilestone
             ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
-            : completionSummary;
+            : idleResidueHint
+                ? [idleResidueHint.message]
+                : completionSummary;
     return {
         title: "GSD — What now?",
         summary: [
@@ -130,10 +138,12 @@ export function buildGsdHomeModel(state, closeout) {
                 label: "Fix or recover",
                 description: blocked
                     ? "Review the blocker and recovery commands for the active milestone."
-                    : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-                enabled: blocked,
+                    : hasIdleResidue
+                        ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
+                        : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
+                enabled: blocked || hasIdleResidue,
                 recommended: recommended === "fix_recover",
-                disabledReason: blocked ? undefined : "no blocker is active",
+                disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
             },
             {
                 id: "start_configure",

package/dist/resources/extensions/gsd/gsd-db.js

@@ -169,7 +169,7 @@ export function insertArtifact(a) {
 export function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
+    const result = getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
       verification_contract, verification_integration, verification_operational, verification_uat,
@@ -199,6 +199,7 @@ export function insertMilestone(m) {
         ":requirement_coverage": m.planning?.requirementCoverage ?? "",
         ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
     });
+    return (result.changes ?? 0) > 0;
 }
 export function upsertMilestonePlanning(milestoneId, planning) {
     if (!getDbOrNull())

package/dist/resources/extensions/gsd/guided-flow.js

@@ -44,7 +44,8 @@ import { buildCloseoutMenuActions, buildIdleMenuSummary, getPrimaryCloseoutRecom
 import { buildRequirementsBacklogDiscussContext, countUnmappedActiveRequirements, showRequirementsBacklogReview, } from "./requirements-backlog.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { supportsStructuredQuestions } from "./workflow-mcp.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
@@ -382,7 +383,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
     const projectRoot = resolveGuidedDispatchProjectRoot(resolvedOptions.basePath);
     const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
     const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
-    const getTransportSupportError = resolvedOptions.deps?.getTransportSupportError ?? getWorkflowTransportSupportError;
+    const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
+        ?? getUnitWorkflowDispatchReadinessError;
     // Route through the dynamic routing pipeline (complexity classification,
     // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
     if (ctx && unitType) {
@@ -396,7 +398,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                 routing: result.routing,
             });
         }
-        const compatibilityError = getTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
+        const compatibilityError = getDispatchReadinessError({
+            provider: result.appliedModel?.provider ?? ctx.model?.provider,
             projectRoot,
             surface: "guided flow",
             unitType,