@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

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

@@ -0,0 +1,217 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+
+import type { RecoveryFailureKind } from "./recovery-classification.js";
+import type { DoctorIssueCode } from "./doctor-types.js";
+
+// ─── Shape ──────────────────────────────────────────────────────────────
+
+export interface Guidance {
+  summary: string;
+  steps: string[];
+}
+
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance: Guidance): string {
+  if (guidance.steps.length === 0) return guidance.summary;
+  const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+  return `${guidance.summary}\n\n${numbered}`;
+}
+
+// ─── Recovery Classification remediation ────────────────────────────────
+// Keyed by RecoveryFailureKind. The provider kind is split by transience,
+// which Recovery Classification resolves before looking up guidance.
+
+export type RecoveryGuidanceKey =
+  | Exclude<RecoveryFailureKind, "provider">
+  | "provider-transient"
+  | "provider-permanent";
+
+const RECOVERY_REMEDIATION: Record<RecoveryGuidanceKey, string> = {
+  "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+  "tool-contract":
+    "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+  "tool-unavailable":
+    "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+  "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+  "lifecycle-progression":
+    "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+  "stale-worker":
+    "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+  "worktree-invalid":
+    "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+  "verification-drift":
+    "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+  "reconciliation-drift":
+    "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+  "illegal-transition":
+    "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+  "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+  "provider-transient": "Retry after the provider/network condition clears.",
+  "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+
+export function recoveryRemediation(key: RecoveryGuidanceKey): string {
+  return RECOVERY_REMEDIATION[key];
+}
+
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+
+export function needsAttentionBlockerGuidance(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+    `Fix options:`,
+    `1. Review the validation details: \`/gsd status\``,
+    `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+    `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+    `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+  ].join("\n");
+}
+
+export function needsRemediationBlockerGuidance(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+    `Fix options:`,
+    `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+    `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+    `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+  ].join("\n");
+}
+
+// ─── Milestone closeout UAT sign-off blockers ───────────────────────────
+// The first sentence is the blocker finding; the numbered steps are the
+// resolution path. `verdict` is the recorded non-PASS verdict, or undefined
+// when no verdict has been recorded at all.
+
+export function uatSignoffBlockerGuidance(
+  milestoneId: string,
+  sliceId: string,
+  verdict?: string,
+): string {
+  const finding =
+    verdict === undefined
+      ? `missing UAT PASS verdict for ${sliceId}`
+      : `UAT verdict for ${sliceId} is "${verdict}"`;
+  const sliceSpecificRerunStep =
+    `If ${sliceId} is not the most recently completed slice, type a chat request to re-run UAT for ${sliceId}; run-uat will record the verdict through \`gsd_uat_result_save\`.`;
+  const steps =
+    verdict === undefined
+      ? [
+          `1. Run UAT for the most recently completed slice to record a verdict: \`/gsd dispatch uat\``,
+          `2. ${sliceSpecificRerunStep}`,
+          `3. Review the UAT criteria and progress: \`/gsd status\``,
+          `4. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ]
+      : [
+          `1. Review the failing UAT findings: \`/gsd status\` (the ${sliceId} ASSESSMENT records what failed)`,
+          `2. Fix the issue, then re-run UAT for the most recently completed slice to record a fresh verdict: \`/gsd dispatch uat\``,
+          `3. ${sliceSpecificRerunStep}`,
+          `4. If the fix needs new implementation work, add remediation slices: \`/gsd dispatch reassess\``,
+          `5. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ];
+  return [
+    `Cannot complete milestone ${milestoneId}: ${finding}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+    `Fix options:`,
+    ...steps,
+  ].join("\n");
+}
+
+// ─── Worktree isolation degradation ─────────────────────────────────────
+// The first sentence of each notice is load-bearing for log matching and
+// tests — keep it intact and append guidance after it.
+
+function restoreIsolationHint(milestoneId: string): string {
+  return `To restore isolation: close any processes using the old worktree, merge salvageable work with \`/gsd worktree merge ${milestoneId}\` or remove the stale worktree with \`/gsd worktree remove ${milestoneId}\`, then run \`/gsd doctor fix\`.`;
+}
+
+export function worktreeCreationFailedGuidance(milestoneId: string, error: string): string {
+  return [
+    `Auto-worktree creation for ${milestoneId} failed: ${error}. Continuing in project root.`,
+    `Worktree isolation is degraded for this session.`,
+    restoreIsolationHint(milestoneId),
+  ].join("\n");
+}
+
+export function isolationDegradedFallbackGuidance(milestoneId: string): string {
+  return [
+    `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+    `Work continues safely on the milestone branch in the project root.`,
+    restoreIsolationHint(milestoneId),
+  ].join("\n");
+}
+
+/** Hard entry blockers from auto-start: bootstrap stopped, user must act. */
+export function milestoneEntryBlockedGuidance(
+  milestoneId: string,
+  reason: "creation-failed" | "isolation-degraded",
+): string {
+  const finding =
+    reason === "creation-failed"
+      ? `worktree/branch creation failed. Isolation is degraded.`
+      : `isolation is degraded from a prior worktree failure.`;
+  return [
+    `Cannot enter milestone ${milestoneId}: ${finding}`,
+    restoreIsolationHint(milestoneId),
+    `Then run \`/gsd auto\` to retry.`,
+  ].join("\n");
+}
+
+// ─── Crash recovery resume hints ────────────────────────────────────────
+
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType: string, unitId: string): string | undefined {
+  if (unitType === "starting" && unitId === "bootstrap") {
+    return `No work was lost. Run /gsd auto to restart.`;
+  }
+  if (unitType.includes("research") || unitType.includes("plan")) {
+    return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+  }
+  if (unitType.includes("execute")) {
+    return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+  }
+  if (unitType.includes("complete")) {
+    return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+  }
+  return undefined;
+}
+
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+
+const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
+  db_unavailable:
+    "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+  stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
+  stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+  unresolved_git_conflicts:
+    "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+  conflict_markers_in_tracked_files:
+    "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+  worktree_dirty:
+    "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+  worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+  orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+  gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+  invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+  provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+  provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+  state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
+  state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
+  projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+  uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+
+export function doctorFixHint(code: DoctorIssueCode): string | undefined {
+  return DOCTOR_FIX_HINTS[code];
+}

package/src/resources/extensions/gsd/guided-flow.ts

@@ -76,13 +76,25 @@ import {
   countUnmappedActiveRequirements,
   showRequirementsBacklogReview,
 } from "./requirements-backlog.js";
-import { selectAndApplyModel } from "./auto-model-selection.js";
+import { selectAndApplyModel, getRegisteredToolSnapshot } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import {
-  getWorkflowTransportSupportError,
-  getRequiredWorkflowToolsForGuidedUnit,
+  detectWorkflowMcpLaunchConfig,
+  resolveWorkflowMcpProjectRoot,
   supportsStructuredQuestions,
 } from "./workflow-mcp.js";
+import { usesWorkflowMcpTransport } from "./question-transport.js";
+import {
+  getCachedWorkflowMcpProbe,
+  probeAndCacheWorkflowMcp,
+  warmWorkflowMcpProbeInBackground,
+  workflowMcpProbeAdvertisesSurface,
+  WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+} from "./workflow-mcp-readiness-cache.js";
+import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import {
   runPreparation,
   formatCodebaseBrief,
@@ -90,7 +102,7 @@ import {
 } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import type { MilestoneScope } from "./workspace.js";
-import { getPendingGate } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import {
   _getPendingAutoStart,
   clearPendingAutoStart,
@@ -100,7 +112,7 @@ import {
   setPendingAutoStart,
 } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
-import { scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
+import { checkAutoStartAfterDiscuss, scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
 export {
   maybeHandleEmptyIntentTurn,
   maybeHandleReadyPhraseWithoutFiles,
@@ -555,7 +567,7 @@ interface DispatchWorkflowOptions {
   deps?: {
     loadPreferences?: typeof loadEffectiveGSDPreferences;
     selectModel?: typeof selectAndApplyModel;
-    getTransportSupportError?: typeof getWorkflowTransportSupportError;
+    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessError;
   };
 }
 
@@ -563,6 +575,93 @@ export function resolveGuidedDispatchProjectRoot(basePath?: string): string {
   return basePath ?? process.cwd();
 }
 
+/**
+ * Wait until the workflow MCP server is reachable and advertising its tool
+ * surface. Returns failure details when timed out, or null when ready (or MCP
+ * is not the transport). Called inside dispatchWorkflow() so every guided-flow
+ * dispatch path is gated automatically.
+ */
+const MCP_READINESS_TIMEOUT_MS = 15_000;
+const MCP_READINESS_POLL_MS = 200;
+
+export interface WorkflowMcpReadinessFailure {
+  server: string;
+  error?: string;
+}
+
+async function awaitWorkflowMcpReadiness(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  basePath: string,
+  options: {
+    unitType?: string;
+    timeoutMs?: number;
+    pollMs?: number;
+    probeTimeoutMs?: number;
+    probe?: typeof probeAndCacheWorkflowMcp;
+  } = {},
+): Promise<WorkflowMcpReadinessFailure | null> {
+  const provider = ctx.model?.provider;
+  const authMode = provider ? ctx.modelRegistry.getProviderAuthMode(provider) : undefined;
+  if (!usesWorkflowMcpTransport(authMode, ctx.model?.baseUrl)) return null;
+
+  const projectRoot = resolveWorkflowMcpProjectRoot(basePath);
+  const launch = detectWorkflowMcpLaunchConfig(projectRoot);
+  if (!launch) return null;
+
+  const requiredTools = options.unitType
+    ? getRequiredWorkflowToolsForUnit(options.unitType).filter(isWorkflowToolSurfaceName)
+    : [];
+  const coversExpectedSurface = (tools: readonly string[]) =>
+    requiredTools.length > 0
+      ? probeCoversRequiredWorkflowTools(tools, requiredTools)
+      : workflowMcpProbeAdvertisesSurface(tools);
+
+  const serverPrefix = `mcp__${launch.name}__`;
+  const systemPrompt = () => typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : "";
+  const systemPromptCoversExpectedSurface = () => {
+    const prompt = systemPrompt();
+    return requiredTools.length > 0
+      ? requiredTools.every((tool) => prompt.includes(`${serverPrefix}${tool}`))
+      : prompt.includes(serverPrefix);
+  };
+  const sessionAlreadyReady = () =>
+    coversExpectedSurface(getRegisteredToolSnapshot(pi)) ||
+    systemPromptCoversExpectedSurface();
+  if (sessionAlreadyReady()) return null;
+
+  if (coversExpectedSurface(getCachedWorkflowMcpProbe(projectRoot)?.tools ?? [])) {
+    return null;
+  }
+
+  const probe = options.probe ?? probeAndCacheWorkflowMcp;
+  const probeTimeoutMs = options.probeTimeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS;
+
+  ctx.ui.setStatus("gsd-step", `Waiting for ${launch.name} MCP server…`);
+  let lastError: string | undefined;
+  const deadline = Date.now() + (options.timeoutMs ?? MCP_READINESS_TIMEOUT_MS);
+  const pollMs = options.pollMs ?? MCP_READINESS_POLL_MS;
+  while (Date.now() < deadline) {
+    if (sessionAlreadyReady()) {
+      ctx.ui.setStatus("gsd-step", "");
+      return null;
+    }
+
+    const result = await probe(projectRoot, { timeoutMs: probeTimeoutMs });
+    if (result.ok && coversExpectedSurface(result.tools)) {
+      ctx.ui.setStatus("gsd-step", "");
+      return null;
+    }
+    lastError = result.error;
+
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  ctx.ui.setStatus("gsd-step", "");
+  return lastError ? { server: launch.name, error: lastError } : { server: launch.name };
+}
+
+export const _awaitWorkflowMcpReadinessForTest = awaitWorkflowMcpReadiness;
+
 /**
  * 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.
@@ -584,7 +683,8 @@ async function dispatchWorkflow(
   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).
@@ -603,29 +703,49 @@ async function dispatchWorkflow(
       });
     }
 
-    const compatibilityError = getTransportSupportError(
-      result.appliedModel?.provider ?? ctx.model?.provider,
-      getRequiredWorkflowToolsForGuidedUnit(unitType),
-      {
-        projectRoot,
-        surface: "guided flow",
-        unitType,
-        authMode: result.appliedModel?.provider
-          ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
-          : ctx.model?.provider
-            ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-            : undefined,
-        baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-        // Guided flow starts the MCP workflow server as part of dispatch, so the
-        // parent session's activeTools doesn't include MCP tools yet. The MCP
-        // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
-        // here — not whether MCP tools are pre-registered in the parent session.
-      },
-    );
+    const compatibilityError = getDispatchReadinessError({
+      provider: result.appliedModel?.provider ?? ctx.model?.provider,
+      projectRoot,
+      surface: "guided flow",
+      unitType,
+      authMode: result.appliedModel?.provider
+        ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
+        : ctx.model?.provider
+          ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+          : undefined,
+      baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+      // Guided flow starts the MCP workflow server as part of dispatch, so the
+      // parent session's activeTools doesn't include MCP tools yet. The MCP
+      // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+      // here — not whether MCP tools are pre-registered in the parent session.
+    });
     if (compatibilityError) {
       ctx.ui.notify(compatibilityError, "error");
       return;
     }
+
+    // ── Live MCP readiness gate ────────────────────────────────────────
+    // Units with required workflow tools must not dispatch until the MCP
+    // surface covers that exact contract; otherwise the model can race into
+    // "No such tool available" before recovery sees a clean readiness error.
+    warmWorkflowMcpProbeInBackground(projectRoot);
+    const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+    const strictBlocking = requiredWorkflowTools.length > 0
+      && (process.env.GSD_GUIDED_MCP_BLOCKING ?? "").trim() !== "0";
+    if (strictBlocking) {
+      // If the workflow MCP server is configured but still connecting, wait
+      // for it instead of dispatching into a child session that will abort.
+      const readinessFailure = await awaitWorkflowMcpReadiness(pi, ctx, projectRoot, { unitType });
+      if (readinessFailure) {
+        const detail = readinessFailure.error ? ` ${readinessFailure.error}` : "";
+        ctx.ui.notify(
+          `GSD workflow server "${readinessFailure.server}" did not connect in time.${detail} ` +
+          `Run \`/gsd mcp check ${readinessFailure.server}\` for details.`,
+          "warning",
+        );
+        return;
+      }
+    }
   }
 
   // Scope tools for guided workflow turns (#2949, token-consumption savings).
@@ -1582,6 +1702,25 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea
   }
 }
 
+/**
+ * True when an agent turn is currently streaming or a dispatched message is
+ * still queued waiting to trigger one. Used by the pending-auto-start stale
+ * check: a live discuss turn can run for minutes before writing its first
+ * artifact, and deleting its entry as "stale" re-dispatches the workflow —
+ * resetting the interview and producing a duplicate completion turn.
+ */
+function isAgentTurnInFlight(ctx: ExtensionCommandContext): boolean {
+  try {
+    if (typeof ctx.isIdle === "function" && !ctx.isIdle()) return true;
+    if (typeof ctx.hasPendingMessages === "function" && ctx.hasPendingMessages()) return true;
+  } catch {
+    // assertActive() throws on a stale runner context; fall through to
+    // artifact/age staleness signals.
+    logWarning("guided", "isAgentTurnInFlight: ctx method threw (stale runner); assuming no turn in flight");
+  }
+  return false;
+}
+
 // ─── Milestone Actions Submenu ──────────────────────────────────────────────
 
 /**
@@ -1689,6 +1828,7 @@ export async function showSmartEntry(
   options?: { step?: boolean },
 ): Promise<void> {
   const stepMode = options?.step ?? true;
+  warmWorkflowMcpProbeInBackground(basePath);
 
   // ── Clear stale milestone ID reservations from previous cancelled sessions ──
   // Reservations only need to survive within a single /gsd interaction.
@@ -1911,12 +2051,18 @@ export async function showSmartEntry(
     // and fires another dispatchWorkflow, resetting the conversation mid-interview.
     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).
+      // Detect staleness: no manifest, no milestone CONTEXT/CONTEXT-DRAFT artifact,
+      // the entry is older than 30s (avoids race between .set() and LLM writing the
+      // first artifact), AND no agent turn is in flight. A dispatched discuss turn
+      // can think for well over 30s before its first question round writes any
+      // artifact; deleting the entry while that turn is live re-dispatches the
+      // workflow, which both resets the interview and queues a duplicate turn that
+      // replays the final "context written" message after the real one.
       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");
+      const milestoneHasDraft = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT-DRAFT");
       const milestoneHasRoadmap = !!resolveMilestoneFile(basePath, entry.milestoneId, "ROADMAP");
       const milestoneRow = isDbAvailable() ? getMilestone(entry.milestoneId) : null;
       const discussPlanComplete = milestoneHasRoadmap && !!milestoneRow && milestoneRow.status !== "queued";
@@ -1924,10 +2070,30 @@ export async function showSmartEntry(
         // The discuss flow already completed, but pending auto-start cleanup handshake did not run.
         // Clear stale in-memory guard and continue through normal active-milestone routing.
         deletePendingAutoStart(basePath);
-      } else if (!manifestExists && !milestoneHasContext && ageMs > 30_000) {
+      } else if (
+        !manifestExists &&
+        !milestoneHasContext &&
+        !milestoneHasDraft &&
+        ageMs > 30_000 &&
+        !isAgentTurnInFlight(ctx)
+      ) {
         // Stale entry from an interrupted discussion — clear and continue
         deletePendingAutoStart(basePath);
       } else {
+        if (milestoneHasContext && !isAgentTurnInFlight(ctx)) {
+          // The discussion already produced CONTEXT but the agent_end handoff
+          // never consumed the entry — e.g. an external-engine post-hoc gate
+          // re-arm wiped the depth verification after the save (write-gate
+          // two-process sync). CONTEXT can only be written through a verified
+          // depth gate, so a gate still pending for this milestone is stale:
+          // clear it and re-run the handoff instead of dead-ending.
+          const gateBasePath = entry.scope.workspace.projectRoot;
+          const pendingGateId = getPendingGate(gateBasePath);
+          if (pendingGateId && extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId) {
+            clearPendingGate(gateBasePath);
+          }
+          if (checkAutoStartAfterDiscuss(basePath)) return;
+        }
         ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
         return;
       }