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

package/packages/pi-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-ai",
-  "version": "1.2.0-dev.d6c5343c",
+  "version": "1.2.0-dev.e8563f58",
   "description": "Unified LLM API with automatic model discovery and provider configuration",
   "type": "module",
   "gsd": {

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "1.2.0-dev.d6c5343c",
+  "version": "1.2.0-dev.e8563f58",
   "description": "Coding agent CLI (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -33,7 +33,7 @@
     "copy-assets": "node scripts/copy-assets.cjs"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.2.0-dev.d6c5343c",
+    "@opengsd/contracts": "^1.2.0-dev.e8563f58",
     "@mariozechner/jiti": "^2.6.2",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
@@ -53,11 +53,11 @@
     "typebox": "1.1.38",
     "undici": "7.26.0",
     "yaml": "2.9.0",
-    "@gsd/agent-core": "^1.2.0-dev.d6c5343c",
-    "@gsd/native": "^1.2.0-dev.d6c5343c",
-    "@gsd/pi-agent-core": "^1.2.0-dev.d6c5343c",
-    "@gsd/pi-ai": "^1.2.0-dev.d6c5343c",
-    "@gsd/pi-tui": "^1.2.0-dev.d6c5343c",
+    "@gsd/agent-core": "^1.2.0-dev.e8563f58",
+    "@gsd/native": "^1.2.0-dev.e8563f58",
+    "@gsd/pi-agent-core": "^1.2.0-dev.e8563f58",
+    "@gsd/pi-ai": "^1.2.0-dev.e8563f58",
+    "@gsd/pi-tui": "^1.2.0-dev.e8563f58",
     "@sinclair/typebox": "^0.34.41"
   },
   "devDependencies": {

package/packages/pi-tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-tui",
-  "version": "1.2.0-dev.d6c5343c",
+  "version": "1.2.0-dev.e8563f58",
   "description": "Terminal UI library (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -21,7 +21,7 @@
     "build": "node ../../scripts/clean-package-dist.cjs && tsc -p tsconfig.json --incremental false"
   },
   "dependencies": {
-    "@gsd/native": "^1.2.0-dev.d6c5343c",
+    "@gsd/native": "^1.2.0-dev.e8563f58",
     "get-east-asian-width": "1.6.0",
     "marked": "15.0.12",
     "@sinclair/typebox": "^0.34.41"

package/packages/rpc-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/rpc-client",
-  "version": "1.2.0-dev.d6c5343c",
+  "version": "1.2.0-dev.e8563f58",
   "description": "Standalone RPC client SDK for GSD — zero internal dependencies",
   "license": "MIT",
   "gsd": {
@@ -34,7 +34,7 @@
     "test": "node --test dist/rpc-client.test.js"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.2.0-dev.d6c5343c"
+    "@opengsd/contracts": "^1.2.0-dev.e8563f58"
   },
   "engines": {
     "node": ">=22.0.0"

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "1.2.0-dev.d6c5343c",
+  "version": "1.2.0-dev.e8563f58",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/extensions/browser-tools/tests/gsd-browser-launch-config.test.mjs

@@ -38,6 +38,17 @@ describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
     assert.equal(args[args.indexOf("--identity-key") + 1], "custom-key");
   });
 
+  it("splits GSD_BROWSER_MCP_COMMAND command lines before spawning", () => {
+    const commandLine = '"C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\Test User\\AppData\\Roaming\\npm\\node_modules\\@opengsd\\gsd-browser\\bin\\gsd-browser"';
+    const { command, args } = resolveGsdBrowserMcpLaunchConfig("C:\\Users\\Test User\\project", {
+      GSD_BROWSER_MCP_COMMAND: commandLine,
+    });
+
+    assert.equal(command, "C:\\Program Files\\nodejs\\node.exe");
+    assert.equal(args[0], "C:\\Users\\Test User\\AppData\\Roaming\\npm\\node_modules\\@opengsd\\gsd-browser\\bin\\gsd-browser");
+    assert.equal(args[1], "mcp");
+  });
+
   it("uses a path-safe identity-project identifier", () => {
     const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example/project", {});
     const projectId = args[args.indexOf("--identity-project") + 1];

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

@@ -22,7 +22,7 @@ type BlockedAdvanceResult = Extract<AutoAdvanceResult, { kind: "blocked" }>;
 import { debugCount, debugLog, debugTime } from "../debug-logger.js";
 import { reconcileBeforeDispatch } from "../state-reconciliation.js";
 import { isLegalEdge, IllegalPhaseTransitionError } from "../state-transition-matrix.js";
-import { resolveDispatch } from "../auto-dispatch.js";
+import { hasPendingDeepStage, resolveDispatch } from "../auto-dispatch.js";
 import { classifyFailure } from "../recovery-classification.js";
 import { verifyExpectedArtifact, refreshRecoveryDbForArtifact } from "../auto-recovery.js";
 import { invalidateAllCaches } from "../cache.js";
@@ -193,14 +193,25 @@ export async function decideOrchestratorDispatch(
 ): Promise<DispatchDecision> {
   const state = input.stateSnapshot;
   const active = state.activeMilestone;
-  if (!active) return null;
-
   const activeSession = input.session ?? session;
   const activeDispatchBasePath = activeSession?.basePath || dispatchBasePath;
-  if (activeSession && shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath)) {
+  const prefs = loadEffectiveGSDPreferences(activeDispatchBasePath)?.preferences;
+  if (!active) {
+    if (state.phase !== "pre-planning") return null;
+    if (!hasPendingDeepStage(prefs, activeDispatchBasePath)) {
+      return {
+        kind: "blocked",
+        reason: state.nextAction || "No active milestone. Run /gsd unpark <id> or create a new milestone.",
+        action: "stop",
+      };
+    }
+  }
+
+  if (active && activeSession && shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath)) {
     activeSession.currentMilestoneId = active.id;
   }
-  const prefs = loadEffectiveGSDPreferences(activeDispatchBasePath)?.preferences;
+  const dispatchMid = active?.id ?? activeSession?.currentMilestoneId ?? "";
+  const dispatchMidTitle = active?.title ?? "";
 
   // Derive session-derived dispatch inputs the same way phases.ts:runDispatch does
   // (#5789). Prefer caller-supplied values when present so test harnesses and
@@ -232,8 +243,15 @@ export async function decideOrchestratorDispatch(
         ? "true"
         : "false");
 
+  // Only replay a milestone-scoped verification retry when a milestone is
+  // active. Pre-PR (#712 fix), `!active` returned null before reaching this
+  // block, so the retry was preserved for a future tick. The new
+  // pre-planning + deep-pending fall-through must keep that contract:
+  // otherwise a stale execute-task / complete-slice / complete-milestone
+  // retry whose target milestone has since been parked would preempt
+  // project-level deep rules like `discuss-project`.
   const pendingRetry = session?.pendingVerificationRetryDispatch;
-  if (session && pendingRetry) {
+  if (session && pendingRetry && active) {
     session.pendingVerificationRetryDispatch = null;
     const alreadyClosedReason = getAlreadyClosedDispatchReason(
       pendingRetry.unitType,
@@ -255,8 +273,8 @@ export async function decideOrchestratorDispatch(
 
   const action = await resolveDispatch({
     basePath: activeDispatchBasePath,
-    mid: active.id,
-    midTitle: active.title,
+    mid: dispatchMid,
+    midTitle: dispatchMidTitle,
     state,
     prefs,
     session: activeSession,
@@ -300,8 +318,8 @@ export async function decideOrchestratorDispatch(
       prompt: action.prompt,
       pauseAfterUatDispatch: action.pauseAfterDispatch ?? false,
       state,
-      mid: active.id,
-      midTitle: active.title,
+      mid: dispatchMid,
+      midTitle: dispatchMidTitle,
     };
     session.pendingOrchestrationDispatch = pending;
   }

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -18,7 +18,7 @@ import { getSessionModelOverride } from "./session-model-override.js";
 import { logWarning } from "./workflow-logger.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { applyModelPolicyFilter } from "./uok/model-policy.js";
-import { isModelBlocked } from "./blocked-models.js";
+import { isModelBlocked, isModelTemporarilyUnavailable } from "./blocked-models.js";
 import { getRequiredWorkflowToolsForAutoUnit, isWorkflowMcpSurfaceTool } from "./workflow-mcp.js";
 
 /**
@@ -272,6 +272,15 @@ function buildModelPolicyBlockReasons(
   }];
 }
 
+function isModelUnavailable(
+  basePath: string,
+  provider: string | undefined,
+  id: string | undefined,
+): boolean {
+  return isModelBlocked(basePath, provider, id) ||
+    isModelTemporarilyUnavailable(basePath, provider, id);
+}
+
 function restoreToolBaseline(pi: ExtensionAPI): void {
   const key = pi as unknown as object;
   const baseline = TOOL_BASELINE.get(key);
@@ -817,9 +826,9 @@ export async function selectAndApplyModel(
       // (issue #4513).  The block is persisted in .gsd/runtime/blocked-models.json
       // so it survives /gsd auto restarts — without this, the same dead model
       // gets reselected after every restart.
-      if (isModelBlocked(basePath, model.provider, model.id)) {
+      if (isModelUnavailable(basePath, model.provider, model.id)) {
         ctx.ui.notify(
-          `Skipping blocked model ${model.provider}/${model.id} (provider rejected it for this account).`,
+          `Skipping unavailable model ${model.provider}/${model.id}.`,
           "warning",
         );
         continue;
@@ -896,7 +905,7 @@ export async function selectAndApplyModel(
       for (const model of buildPolicyEligibleFallbackOrder(ctx, routingEligibleModels, autoModeStartModel)) {
         const key = `${model.provider.toLowerCase()}/${model.id.toLowerCase()}`;
         if (!policyAllowedModelKeys.has(key)) continue;
-        if (isModelBlocked(basePath, model.provider, model.id)) continue;
+        if (isModelUnavailable(basePath, model.provider, model.id)) continue;
         const ok = await pi.setModel(model, { persist: false });
         if (!ok) continue;
         appliedModel = model;
@@ -926,10 +935,10 @@ export async function selectAndApplyModel(
       autoModeStartModel,
       effectiveSessionModelOverride,
     );
-    const startBlocked = isModelBlocked(basePath, autoModeStartModel.provider, autoModeStartModel.id);
+    const startBlocked = isModelUnavailable(basePath, autoModeStartModel.provider, autoModeStartModel.id);
     if (startBlocked) {
       ctx.ui.notify(
-        `Auto-mode start model ${autoModeStartModel.provider}/${autoModeStartModel.id} is blocked for this account. Using current session model instead.`,
+        `Auto-mode start model ${autoModeStartModel.provider}/${autoModeStartModel.id} is unavailable. Using current session model instead.`,
         "warning",
       );
     } else {
@@ -940,7 +949,7 @@ export async function selectAndApplyModel(
         const ok = await pi.setModel(startModel, { persist: false });
         if (!ok) {
           const byId = availableModels.find(
-            m => m.id === autoModeStartModel.id && !isModelBlocked(basePath, m.provider, m.id),
+            m => m.id === autoModeStartModel.id && !isModelUnavailable(basePath, m.provider, m.id),
           );
           if (byId) {
             const fallbackOk = await pi.setModel(byId, { persist: false });

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

@@ -924,6 +924,14 @@ export function setCurrentDispatchedModelId(model: { provider: string; id: strin
   s.currentDispatchedModelId = model ? `${model.provider}/${model.id}` : null;
 }
 
+/**
+ * Update the active unit model after runtime recovery switches models mid-unit.
+ * The next session restore path reads this field before dispatching again.
+ */
+export function setCurrentUnitModelForRecovery(model: any | null): void {
+  s.currentUnitModel = model;
+}
+
 // Tool tracking — delegates to auto-tool-tracking.ts
 export function markToolStart(toolCallId: string, toolName?: string): void {
   _markToolStart(toolCallId, s.active, toolName);

package/src/resources/extensions/gsd/blocked-models.ts

@@ -23,6 +23,15 @@ interface BlockedModelsFile {
   blocked: BlockedModelEntry[];
 }
 
+interface TemporaryBlockedModelEntry {
+  provider: string;
+  id: string;
+  reason: string;
+  blockedUntil: number;
+}
+
+const temporaryBlockedModels = new Map<string, TemporaryBlockedModelEntry>();
+
 function blockedModelsPath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "blocked-models.json");
 }
@@ -31,6 +40,10 @@ function modelKey(provider: string, id: string): string {
   return `${provider.toLowerCase()}/${id.toLowerCase()}`;
 }
 
+function temporaryModelKey(basePath: string, provider: string, id: string): string {
+  return `${basePath}:${modelKey(provider, id)}`;
+}
+
 function readFileSafe(path: string): BlockedModelsFile {
   if (!existsSync(path)) return { version: 1, blocked: [] };
   try {
@@ -66,6 +79,42 @@ export function isModelBlocked(
   );
 }
 
+export function blockModelUntil(
+  basePath: string,
+  provider: string,
+  id: string,
+  blockedUntil: number,
+  reason: string,
+): void {
+  const key = temporaryModelKey(basePath, provider, id);
+  if (blockedUntil <= Date.now()) {
+    temporaryBlockedModels.delete(key);
+    return;
+  }
+  temporaryBlockedModels.set(key, { provider, id, reason, blockedUntil });
+}
+
+export function isModelTemporarilyUnavailable(
+  basePath: string,
+  provider: string | undefined,
+  id: string | undefined,
+  now = Date.now(),
+): boolean {
+  if (!provider || !id) return false;
+  const key = temporaryModelKey(basePath, provider, id);
+  const entry = temporaryBlockedModels.get(key);
+  if (!entry) return false;
+  if (entry.blockedUntil <= now) {
+    temporaryBlockedModels.delete(key);
+    return false;
+  }
+  return true;
+}
+
+export function clearTemporaryModelBlocksForTest(): void {
+  temporaryBlockedModels.clear();
+}
+
 export function blockModel(
   basePath: string,
   provider: string,

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -19,6 +19,7 @@ import {
   isAutoCompletionStopInProgress,
   pauseAuto,
   setCurrentDispatchedModelId,
+  setCurrentUnitModelForRecovery,
 } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
@@ -41,7 +42,7 @@ import {
   isTransient,
   type ErrorClass,
 } 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";
@@ -143,9 +144,14 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
       const nextModelId = getNextFallbackModel(cursorModelId, modelConfig);
       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(
@@ -163,7 +169,8 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
   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,
@@ -171,6 +178,7 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
     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(
@@ -676,6 +684,16 @@ export async function handleAgentEnd(
       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 ──────────────────────────────────────────────────
@@ -721,9 +739,14 @@ export async function handleAgentEnd(
             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 });
@@ -737,11 +760,17 @@ export async function handleAgentEnd(
       // 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/src/resources/extensions/gsd/bootstrap/exec-tools.ts

@@ -137,8 +137,8 @@ export function registerExecTools(pi: ExtensionAPI): void {
     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.",
+        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." })),

package/src/resources/extensions/gsd/closeout-wizard.ts

@@ -1,25 +1,40 @@
 // 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 type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import type { NextAction } from "../shared/next-action-ui.js";
 import type { GSDState } from "./types.js";
 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, type StrandedQuickBranch } from "./quick.js";
+import { isClosedStatus } from "./status-guards.js";
 import {
   findUnmergedCompletedMilestones,
   type UnmergedMilestoneBlocker,
 } 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";
 
 export type CloseoutActionId = "finish_quick" | "finish_milestone";
 
+export interface IdleMilestoneResidueHint {
+  message: string;
+  milestoneIds: string[];
+}
+
 export interface CloseoutContext {
   strandedQuick: StrandedQuickBranch | null;
   unmergedMilestones: UnmergedMilestoneBlocker[];
+  idleResidueHint?: IdleMilestoneResidueHint | null;
 }
 
 const MILESTONE_MERGE_CLOSEOUT_COMMANDS = [
@@ -29,11 +44,90 @@ const MILESTONE_MERGE_CLOSEOUT_COMMANDS = [
   "/gsd start for new work",
 ];
 
+function listMilestoneWorktreeIds(basePath: string): string[] {
+  const ids = new Set<string>();
+  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: string): string[] {
+  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: string): boolean {
+  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: string): IdleMilestoneResidueHint | null {
+  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: string): Promise<CloseoutContext> {
   const unmergedMilestones = await findUnmergedCompletedMilestones(basePath);
+  const idleResidueHint =
+    unmergedMilestones.length === 0 ? detectIdleMilestoneResidueHint(basePath) : null;
   return {
     strandedQuick: detectStrandedQuickBranch(basePath),
     unmergedMilestones,
+    idleResidueHint,
   };
 }
 
@@ -87,6 +181,14 @@ export function buildIdleMenuSummary(state: GSDState, closeout: CloseoutContext)
     ];
   }
 
+  // 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, [