gsd-pi 2.82.0-dev.dfbc5f58f → 2.82.0-dev.e7a7f1ed5

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

@@ -26,10 +26,11 @@ import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.j
 import { nativeAddAll, nativeCommit, nativeHasCommittedHead, nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getIsolationMode, loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
 import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
+import { isFutureMilestoneStatus } from "./status-guards.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
 import { showConfirm } from "../shared/tui.js";
@@ -43,8 +44,10 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
-import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
+import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
+import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
+export { _getPendingAutoStart, clearPendingAutoStart, getDiscussionMilestoneId, setPendingAutoStart, } from "./pending-auto-start.js";
 export function shouldSkipGitBootstrapAfterInit(result) {
     return result.gitEnabled === false;
 }
@@ -56,6 +59,8 @@ import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
 import { buildWorkflowDispatchContent } from "./workflow-protocol.js";
 import { isFullGsdToolSurfaceRequested, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "./bootstrap/register-hooks.js";
+import { resolveActiveTaskChoiceRoute, } from "./smart-entry-routing.js";
+export { resolveGuidedExecuteLaunchMode } from "./smart-entry-routing.js";
 function scheduleAutoStartAfterIdle(ctx, pi, basePath, verboseMode, options, launch = startAutoDetached) {
     const waitForIdle = typeof ctx.waitForIdle === "function"
         ? ctx.waitForIdle.bind(ctx)
@@ -157,7 +162,6 @@ const MAX_PLAN_BLOCKED_RECOVERIES = 3;
 // to emit. Accepts any M-prefixed milestone ID (three digits + optional
 // suffix) with optional trailing punctuation.
 const READY_PHRASE_RE = /\bMilestone\s+M\d{3}[A-Z0-9-]*\s+ready\.?/i;
-const pendingAutoStartMap = new Map();
 const pendingDeepProjectSetupMap = new Map();
 const USER_DRIVEN_DEEP_SETUP_UNITS = new Set([
     "discuss-project",
@@ -183,18 +187,6 @@ This stage is running inside the foreground \`/gsd new-project --deep\` intervie
 
 - Do NOT call \`ask_user_questions\`, \`AskUserQuestion\`, or ToolSearch to discover user-input tools.
 - Ask one focused round, then stop and wait for the user's normal chat response.`;
-/**
- * Backward-compat bridge: returns a mutable reference to the entry matching
- * basePath, or the sole entry when only one session exists.
- * Exported for testing — internal use only in production code.
- */
-export function _getPendingAutoStart(basePath) {
-    if (basePath)
-        return pendingAutoStartMap.get(basePath) ?? null;
-    if (pendingAutoStartMap.size === 1)
-        return pendingAutoStartMap.values().next().value;
-    return null;
-}
 function hasNestedFileOrSymlink(dir) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         if (entry.isFile() || entry.isSymbolicLink())
@@ -228,28 +220,6 @@ function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
     }
     return remaining;
 }
-/**
- * Store pending auto-start state for a project.
- * Exported for testing (#2985).
- */
-export function setPendingAutoStart(basePath, entry) {
-    const ws = createWorkspace(entry.basePath);
-    const scope = scopeMilestone(ws, entry.milestoneId);
-    pendingAutoStartMap.set(basePath, { createdAt: Date.now(), planBlockedRecoveryCount: 0, ...entry, scope });
-}
-/**
- * Clear pending auto-start state.
- * If basePath is given, clears only that project.  Otherwise clears all.
- * Exported for testing (#2985).
- */
-export function clearPendingAutoStart(basePath) {
-    if (basePath) {
-        pendingAutoStartMap.delete(basePath);
-    }
-    else {
-        pendingAutoStartMap.clear();
-    }
-}
 export function clearPendingDeepProjectSetup(basePath) {
     if (basePath) {
         pendingDeepProjectSetupMap.delete(basePath);
@@ -258,22 +228,6 @@ export function clearPendingDeepProjectSetup(basePath) {
         pendingDeepProjectSetupMap.clear();
     }
 }
-/**
- * Returns the milestoneId being discussed for the given project.
- * When basePath is omitted and only one session is active, returns that
- * session's milestoneId for backward compatibility.  Returns null when
- * multiple sessions exist and basePath is not specified (#2985 Bug 4).
- */
-export function getDiscussionMilestoneId(basePath) {
-    if (basePath) {
-        return pendingAutoStartMap.get(basePath)?.milestoneId ?? null;
-    }
-    // Backward compat: return the sole entry's milestoneId, or null if ambiguous
-    if (pendingAutoStartMap.size === 1) {
-        return pendingAutoStartMap.values().next().value.milestoneId;
-    }
-    return null;
-}
 function _getPendingDeepProjectSetup(basePath) {
     if (basePath)
         return pendingDeepProjectSetupMap.get(basePath) ?? null;
@@ -399,12 +353,12 @@ async function dispatchNextDeepProjectSetupStage(entry) {
     entry.currentUnitType = result.unitType;
     entry.currentUnitId = result.unitId;
     entry.createdAt = Date.now();
-    await dispatchWorkflow(entry.pi, `${result.prompt}\n\n${FOREGROUND_DEEP_SETUP_QUESTION_POLICY}`, "gsd-run", entry.ctx, result.unitType);
+    await dispatchWorkflow(entry.pi, `${result.prompt}\n\n${FOREGROUND_DEEP_SETUP_QUESTION_POLICY}`, "gsd-run", entry.ctx, result.unitType, { basePath: entry.basePath });
     return true;
 }
 /** Called from agent_end to check if auto-mode should start after discuss */
-export function checkAutoStartAfterDiscuss() {
-    const entry = _getPendingAutoStart();
+export function checkAutoStartAfterDiscuss(lookupBasePath) {
+    const entry = _getPendingAutoStart(lookupBasePath);
     if (!entry)
         return false;
     const { ctx, pi, basePath, milestoneId, step } = entry;
@@ -569,7 +523,7 @@ export function checkAutoStartAfterDiscuss() {
             return false;
         }
     }
-    pendingAutoStartMap.delete(basePath);
+    deletePendingAutoStart(basePath);
     ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
     scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step });
     return true;
@@ -641,8 +595,8 @@ function hasToolUse(msg) {
  * Returns true when a nudge (or give-up) was emitted, signaling the caller to
  * skip `resolveAgentEnd`.
  */
-export function maybeHandleReadyPhraseWithoutFiles(event) {
-    const entry = _getPendingAutoStart();
+export function maybeHandleReadyPhraseWithoutFiles(event, lookupBasePath) {
+    const entry = _getPendingAutoStart(lookupBasePath);
     if (!entry)
         return false;
     const { ctx, pi, basePath, milestoneId } = entry;
@@ -684,7 +638,7 @@ export function maybeHandleReadyPhraseWithoutFiles(event) {
     if (entry.readyRejectCount > MAX_READY_REJECTS) {
         // Give up: clear state and tell the user to re-run /gsd. Avoids an
         // infinite nudge loop when the LLM never produces the writes.
-        pendingAutoStartMap.delete(basePath);
+        deletePendingAutoStart(basePath);
         ctx.ui.notify(`Milestone ${milestoneId}: LLM signaled "ready" ${entry.readyRejectCount} times without writing files. ` +
             `Stopping auto-nudge. Run /gsd to try again.`, "error");
         return true;
@@ -747,10 +701,10 @@ export function resetEmptyTurnCounter(basePath) {
     else
         emptyTurnCounterByBase.clear();
 }
-export function maybeHandleEmptyIntentTurn(event, isAuto) {
+export function maybeHandleEmptyIntentTurn(event, isAuto, lookupBasePath) {
     // Gate: only fire when there is system-driven work in flight. Interactive
     // /gsd discuss (user-driven) produces legitimate text-only turns.
-    if (!isAuto && pendingAutoStartMap.size === 0)
+    if (!isAuto && !hasPendingAutoStart(lookupBasePath))
         return false;
     const lastMsg = event.messages[event.messages.length - 1];
     if (!lastMsg)
@@ -778,7 +732,7 @@ export function maybeHandleEmptyIntentTurn(event, isAuto) {
         return false;
     // Resolve the target basePath + pi for injection. Prefer the pending
     // autostart entry (discuss flow); otherwise we cannot inject.
-    const entry = _getPendingAutoStart();
+    const entry = _getPendingAutoStart(lookupBasePath);
     if (!entry)
         return false;
     const { ctx, pi, basePath } = entry;
@@ -817,7 +771,9 @@ function parseMilestoneSequenceFromProject(content) {
     }
     return ids;
 }
-// ─── Helpers ──────────────────────────────────────────────────────────────────
+export function resolveGuidedDispatchProjectRoot(basePath) {
+    return basePath ?? process.cwd();
+}
 /**
  * Read GSD-WORKFLOW.md and dispatch it to the LLM with a contextual note.
  * This is the only way the wizard triggers work — everything else is the LLM's job.
@@ -827,12 +783,17 @@ function parseMilestoneSequenceFromProject(content) {
  * dispatching. This ensures guided-flow dispatches respect the same
  * per-phase model preferences that auto-mode uses.
  */
-async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType) {
+async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType, options) {
+    const resolvedOptions = options ?? {};
+    const projectRoot = resolveGuidedDispatchProjectRoot(resolvedOptions.basePath);
+    const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
+    const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
+    const getTransportSupportError = resolvedOptions.deps?.getTransportSupportError ?? getWorkflowTransportSupportError;
     // Route through the dynamic routing pipeline (complexity classification,
     // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
     if (ctx && unitType) {
-        const prefs = loadEffectiveGSDPreferences()?.preferences;
-        const result = await selectAndApplyModel(ctx, pi, unitType, /* unitId */ "", /* basePath */ process.cwd(), prefs, /* verbose */ false, /* autoModeStartModel */ null, 
+        const prefs = loadPreferences(projectRoot)?.preferences;
+        const result = await selectModel(ctx, pi, unitType, /* unitId */ "", projectRoot, prefs, /* verbose */ false, /* autoModeStartModel */ null, 
         /* retryContext */ undefined, /* isAutoMode */ false);
         if (result.appliedModel) {
             debugLog("guided-flow-model-applied", {
@@ -841,8 +802,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
                 routing: result.routing,
             });
         }
-        const compatibilityError = getWorkflowTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
-            projectRoot: process.cwd(),
+        const compatibilityError = getTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
+            projectRoot,
             surface: "guided flow",
             unitType,
             authMode: result.appliedModel?.provider
@@ -851,6 +812,7 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
                     ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
                     : undefined,
             baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+            activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
         });
         if (compatibilityError) {
             ctx.ui.notify(compatibilityError, "error");
@@ -894,11 +856,19 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
         }
         const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
         const workflow = readFileSync(workflowPath, "utf-8");
-        pi.sendMessage({
-            customType,
-            content: buildWorkflowDispatchContent({ workflow, workflowPath, task: note }),
-            display: false,
-        }, { triggerTurn: true });
+        if (unitType)
+            setGuidedUnitContext(projectRoot, unitType);
+        try {
+            pi.sendMessage({
+                customType,
+                content: buildWorkflowDispatchContent({ workflow, workflowPath, task: note }),
+                display: false,
+            }, { triggerTurn: true });
+        }
+        catch (err) {
+            clearGuidedUnitContext(projectRoot);
+            throw err;
+        }
     }
     finally {
         // Restore full tool set after the message is queued. The LLM turn has
@@ -1086,7 +1056,7 @@ export async function showHeadlessMilestoneCreation(ctx, pi, basePath, seedConte
     // model/tool routing to skip discuss-flow tool scoping and
     // `checkAutoStartAfterDiscuss` guardrails that rely on the
     // "discuss-"-prefixed unitType.
-    await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "discuss-milestone");
+    await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "discuss-milestone", { basePath });
 }
 // ─── Discuss Flow ─────────────────────────────────────────────────────────────
 /**
@@ -1196,7 +1166,7 @@ export async function showDiscuss(ctx, pi, basePath) {
     // No active milestone (or corrupted milestone with undefined id) —
     // check for pending milestones to discuss instead
     if (!state.activeMilestone?.id) {
-        const pendingMilestones = state.registry.filter(m => m.status === "pending");
+        const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
         if (pendingMilestones.length === 0) {
             ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
             return;
@@ -1247,7 +1217,7 @@ export async function showDiscuss(ctx, pi, basePath) {
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
-            await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
+            await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone", { basePath });
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
@@ -1258,7 +1228,7 @@ export async function showDiscuss(ctx, pi, basePath) {
                 milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
                 fastPathInstruction: "",
-            }), "gsd-discuss", ctx, "discuss-milestone");
+            }), "gsd-discuss", ctx, "discuss-milestone", { basePath });
         }
         else if (choice === "skip_milestone") {
             const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
@@ -1267,7 +1237,7 @@ export async function showDiscuss(ctx, pi, basePath) {
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false });
-            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
         }
         return;
     }
@@ -1301,7 +1271,7 @@ export async function showDiscuss(ctx, pi, basePath) {
     const pendingSlices = normSlices.filter(s => !s.done);
     if (pendingSlices.length === 0) {
         // All slices complete — but queued milestones may still need discussion (#3150)
-        const pendingMilestones = state.registry.filter(m => m.status === "pending");
+        const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
         if (pendingMilestones.length > 0) {
             await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones);
             return;
@@ -1322,7 +1292,7 @@ export async function showDiscuss(ctx, pi, basePath) {
         // If all pending slices are discussed, check for queued milestones before exiting (#3150)
         const allDiscussed = pendingSlices.every(s => discussedMap.get(s.id));
         if (allDiscussed) {
-            const pendingMilestones = state.registry.filter(m => m.status === "pending");
+            const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
             if (pendingMilestones.length > 0) {
                 await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones);
                 return;
@@ -1353,7 +1323,7 @@ export async function showDiscuss(ctx, pi, basePath) {
             };
         });
         // Offer access to queued milestones when any exist
-        const pendingMilestones = state.registry.filter(m => m.status === "pending");
+        const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
         if (pendingMilestones.length > 0) {
             actions.push({
                 id: "discuss_queued_milestone",
@@ -1399,7 +1369,7 @@ export async function showDiscuss(ctx, pi, basePath) {
         }
         const sqAvail = getStructuredQuestionsAvailability(pi, ctx);
         const prompt = await buildDiscussSlicePrompt(mid, chosen.id, chosen.title, basePath, { rediscuss: isRediscuss, structuredQuestionsAvailable: sqAvail });
-        await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-slice");
+        await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-slice", { basePath });
         // Wait for the discuss session to finish, then loop back to the picker
         await ctx.waitForIdle();
         invalidateAllCaches();
@@ -1417,10 +1387,11 @@ async function showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones)
         const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
         const hasDraft = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
         const contextStatus = hasContext ? "context ✓" : hasDraft ? "draft context" : "no context yet";
+        const statusLabel = m.status === "planned" ? "planned" : "queued";
         return {
             id: m.id,
             label: `${m.id}: ${m.title}`,
-            description: `[queued] · ${contextStatus}`,
+            description: `[${statusLabel}] · ${contextStatus}`,
             recommended: i === 0,
         };
     });
@@ -1501,7 +1472,7 @@ async function dispatchDiscussForMilestone(ctx, pi, basePath, mid, milestoneTitl
     const prompt = draftContent
         ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
         : basePrompt;
-    await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-milestone");
+    await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-milestone", { basePath });
 }
 // ─── Smart Entry Point ────────────────────────────────────────────────────────
 /**
@@ -1627,7 +1598,7 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
         const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
         const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
         setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
         return true;
     }
     // "back" or null
@@ -1758,16 +1729,17 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     }
     if (interrupted.classification !== "recoverable") {
         try {
-            const { autoImportMarkdownHierarchyIfDbMismatch } = await import("./migration-auto-check.js");
-            const result = await autoImportMarkdownHierarchyIfDbMismatch(basePath);
-            if (result.action === "imported") {
-                ctx.ui.notify(`Recovered migrated planning state into gsd.db (${result.reason}): ${result.afterDb.milestones} milestone(s), ${result.afterDb.slices} slice(s), ${result.afterDb.tasks} task(s).`, "info");
+            const { checkMarkdownHierarchyAgainstDb } = await import("./migration-auto-check.js");
+            const result = await checkMarkdownHierarchyAgainstDb(basePath);
+            if (result.action === "recovery-required") {
+                ctx.ui.notify(result.message ??
+                    `Markdown planning artifacts do not match the authoritative DB. Run \`${result.recoveryCommand ?? "gsd recover"}\` to import markdown explicitly.`, "warning");
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            ctx.ui.notify(`GSD could not auto-import existing planning state into gsd.db: ${message}`, "warning");
-            logWarning("guided", `planning state auto-import failed: ${message}`, { file: "guided-flow.ts" });
+            ctx.ui.notify(`GSD could not compare markdown planning artifacts with gsd.db: ${message}`, "warning");
+            logWarning("guided", `planning state DB/markdown comparison failed: ${message}`, { file: "guided-flow.ts" });
         }
     }
     // Always derive from the project root — the assessment may have derived
@@ -1805,17 +1777,17 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // Both /gsd and /gsd auto reach this branch when no milestone exists yet.
         // Without this guard, every subsequent /gsd call overwrites the pending auto-start
         // and fires another dispatchWorkflow, resetting the conversation mid-interview.
-        if (pendingAutoStartMap.has(basePath)) {
+        if (hasPendingAutoStart(basePath)) {
             // #3274: If /clear interrupted the discussion, the pending entry is stale.
             // Detect staleness: no manifest, no milestone CONTEXT artifact, AND entry is older than
             // 30s (avoids race between .set() and LLM writing first artifact).
-            const entry = pendingAutoStartMap.get(basePath);
+            const entry = _getPendingAutoStart(basePath);
             const ageMs = Date.now() - (entry.createdAt || 0);
             const manifestExists = existsSync(join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json"));
             const milestoneHasContext = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT");
             if (!manifestExists && !milestoneHasContext && ageMs > 30_000) {
                 // Stale entry from an interrupted discussion — clear and continue
-                pendingAutoStartMap.delete(basePath);
+                deletePendingAutoStart(basePath);
             }
             else {
                 ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
@@ -1849,7 +1821,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             // First ever — skip wizard, just ask directly
             ctx.ui.setStatus("gsd-step", "New Milestone · answer the questions above to plan");
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
         }
         else {
             const choice = await showNextAction(ctx, {
@@ -1876,7 +1848,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             else if (choice === "new_milestone") {
                 ctx.ui.setStatus("gsd-step", "New Milestone · answer the questions above to plan");
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-                await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+                await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
             }
         }
         return;
@@ -1885,7 +1857,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     const milestoneTitle = state.activeMilestone.title;
     if (planV2GateDecision === "recover-missing-context") {
         setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
-        await dispatchWorkflow(pi, await buildDiscussMilestonePrompt(milestoneId, milestoneTitle, basePath, getStructuredQuestionsAvailability(pi, ctx)), "gsd-discuss", ctx, "discuss-milestone");
+        await dispatchWorkflow(pi, await buildDiscussMilestonePrompt(milestoneId, milestoneTitle, basePath, getStructuredQuestionsAvailability(pi, ctx)), "gsd-discuss", ctx, "discuss-milestone", { basePath });
         return;
     }
     // ── All milestones complete → New milestone ──────────────────────────
@@ -1921,7 +1893,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
         }
         else if (choice === "status") {
             const { fireStatusViaCommand } = await import("./commands.js");
@@ -1969,7 +1941,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
-            await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
+            await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone", { basePath });
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
@@ -1980,14 +1952,14 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
                 fastPathInstruction: "",
-            }), "gsd-discuss", ctx, "discuss-milestone");
+            }), "gsd-discuss", ctx, "discuss-milestone", { basePath });
         }
         else if (choice === "skip_milestone") {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
         }
         return;
     }
@@ -2051,7 +2023,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             else if (choice === "plan") {
                 ctx.ui.setStatus("gsd-step", "Planning Milestone · decomposing into slices");
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
-                await dispatchWorkflow(pi, await buildPlanMilestonePrompt(milestoneId, milestoneTitle, basePath), "gsd-run", ctx, "plan-milestone");
+                await dispatchWorkflow(pi, await buildPlanMilestonePrompt(milestoneId, milestoneTitle, basePath), "gsd-run", ctx, "plan-milestone", { basePath });
             }
             else if (choice === "discuss") {
                 const discussMilestoneTemplates = inlineTemplate("context", "Context");
@@ -2061,14 +2033,14 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                     milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                     commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
                     fastPathInstruction: "",
-                }), "gsd-run", ctx, "discuss-milestone");
+                }), "gsd-run", ctx, "discuss-milestone", { basePath });
             }
             else if (choice === "skip_milestone") {
                 const milestoneIds = findMilestoneIds(basePath);
                 const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
                 const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-                await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+                await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone", { basePath });
             }
             else if (choice === "discard_milestone") {
                 const confirmed = await showConfirm(ctx, {
@@ -2176,11 +2148,11 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         });
         if (choice === "plan") {
             ctx.ui.setStatus("gsd-step", "Slice Planning · answer the questions above");
-            await dispatchWorkflow(pi, await buildPlanSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath), "gsd-run", ctx, "plan-slice");
+            await dispatchWorkflow(pi, await buildPlanSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath), "gsd-run", ctx, "plan-slice", { basePath });
         }
         else if (choice === "discuss") {
             const sqAvail = getStructuredQuestionsAvailability(pi, ctx);
-            await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext, structuredQuestionsAvailable: sqAvail }), "gsd-run", ctx, "discuss-slice");
+            await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext, structuredQuestionsAvailable: sqAvail }), "gsd-run", ctx, "discuss-slice", { basePath });
         }
         else if (choice === "research") {
             const researchTemplates = inlineTemplate("research", "Research");
@@ -2196,7 +2168,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                     sliceTitle,
                     extraContext: [researchTemplates],
                 }),
-            }), "gsd-run", ctx, "research-slice");
+            }), "gsd-run", ctx, "research-slice", { basePath });
         }
         else if (choice === "status") {
             const { fireStatusViaCommand } = await import("./commands.js");
@@ -2236,7 +2208,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         });
         if (choice === "complete") {
             ctx.ui.setStatus("gsd-step", "Completing Slice · review changes above");
-            await dispatchWorkflow(pi, await buildCompleteSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath), "gsd-run", ctx, "complete-slice");
+            await dispatchWorkflow(pi, await buildCompleteSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath), "gsd-run", ctx, "complete-slice", { basePath });
         }
         else if (choice === "status") {
             const { fireStatusViaCommand } = await import("./commands.js");
@@ -2291,11 +2263,18 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             ],
             notYetMessage: "Run /gsd when ready.",
         });
-        if (choice === "auto") {
-            startAutoDetached(ctx, pi, basePath, false);
+        if (choice === "not_yet")
+            return;
+        const route = resolveActiveTaskChoiceRoute({
+            choice: choice,
+            isolationMode: getIsolationMode(basePath),
+            milestoneId,
+        });
+        if (route.kind === "auto-bootstrap") {
+            startAutoDetached(ctx, pi, basePath, route.verboseMode, route.options);
             return;
         }
-        if (choice === "execute") {
+        if (route.kind === "guided-dispatch") {
             ctx.ui.setStatus("gsd-step", "Executing Task · follow progress above");
             if (hasInterrupted) {
                 await dispatchWorkflow(pi, loadPrompt("guided-resume-task", {
@@ -2308,17 +2287,17 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                         taskId,
                         taskTitle,
                     }),
-                }), "gsd-run", ctx, "execute-task");
+                }), "gsd-run", ctx, "execute-task", { basePath });
             }
             else {
-                await dispatchWorkflow(pi, await buildExecuteTaskPrompt(milestoneId, sliceId, sliceTitle, taskId, taskTitle, basePath), "gsd-run", ctx, "execute-task");
+                await dispatchWorkflow(pi, await buildExecuteTaskPrompt(milestoneId, sliceId, sliceTitle, taskId, taskTitle, basePath), "gsd-run", ctx, "execute-task", { basePath });
             }
         }
-        else if (choice === "status") {
+        else if (route.kind === "status") {
             const { fireStatusViaCommand } = await import("./commands.js");
             await fireStatusViaCommand(ctx);
         }
-        else if (choice === "milestone_actions") {
+        else if (route.kind === "milestone-actions") {
             const acted = await handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneTitle, options);
             if (acted)
                 return showSmartEntry(ctx, pi, basePath, options);

package/dist/resources/extensions/gsd/guided-unit-context.js

@@ -0,0 +1,23 @@
+// GSD-2 — Guided workflow Unit context.
+// Tracks the guided Unit whose queued turn should use manifest Tool Contract policy.
+const guidedUnitContextByBasePath = new Map();
+export function setGuidedUnitContext(basePath, unitType) {
+    const context = { basePath, unitType, startedAt: Date.now() };
+    guidedUnitContextByBasePath.set(basePath, context);
+    return context;
+}
+export function getGuidedUnitContext(basePath) {
+    if (basePath)
+        return guidedUnitContextByBasePath.get(basePath) ?? null;
+    if (guidedUnitContextByBasePath.size === 1)
+        return guidedUnitContextByBasePath.values().next().value;
+    return null;
+}
+export function clearGuidedUnitContext(basePath) {
+    if (basePath) {
+        guidedUnitContextByBasePath.delete(basePath);
+    }
+    else {
+        guidedUnitContextByBasePath.clear();
+    }
+}

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -1,10 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
-import { clearEngineHierarchy, getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, transaction, } from "./gsd-db.js";
-import { migrateHierarchyToDb } from "./md-importer.js";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, } from "./gsd-db.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
 import { milestonesDir, resolveMilestoneFile, resolveSliceFile, } from "./paths.js";
-import { invalidateStateCache } from "./state.js";
 function zeroCounts() {
     return { milestones: 0, slices: 0, tasks: 0 };
 }
@@ -50,7 +48,7 @@ export function countDbHierarchy() {
     }
     return counts;
 }
-export async function autoImportMarkdownHierarchyIfDbMismatch(basePath) {
+export async function checkMarkdownHierarchyAgainstDb(basePath) {
     const markdown = countMarkdownHierarchy(basePath);
     if (sameCounts(markdown, zeroCounts())) {
         return {
@@ -70,18 +68,15 @@ export async function autoImportMarkdownHierarchyIfDbMismatch(basePath) {
         return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };
     }
     const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
-    const imported = transaction(() => {
-        clearEngineHierarchy();
-        return migrateHierarchyToDb(basePath);
-    });
-    invalidateStateCache();
-    const afterDb = {
-        milestones: imported.milestones,
-        slices: imported.slices,
-        tasks: imported.tasks,
+    return {
+        action: "recovery-required",
+        reason,
+        markdown,
+        beforeDb,
+        afterDb: beforeDb,
+        recoveryCommand: "gsd recover",
+        message: `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
+            `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). ` +
+            "Runtime startup will not import markdown automatically; run explicit GSD recovery if markdown should repopulate the database.",
     };
-    if (!sameCounts(markdown, afterDb)) {
-        throw new Error(`migration auto-import verification failed: markdown ${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T, db ${afterDb.milestones}M/${afterDb.slices}S/${afterDb.tasks}T`);
-    }
-    return { action: "imported", reason, markdown, beforeDb, afterDb };
 }