@opengsd/gsd-pi 1.2.0-dev.fb12b103 → 1.2.0-dev.fbdca60b

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

@@ -671,33 +671,54 @@ export function parseTaskPlanIO(content: string): { inputFiles: string[]; output
  */
 export type UatType = 'artifact-driven' | 'live-runtime' | 'human-experience' | 'mixed' | 'browser-executable' | 'runtime-executable';
 
+/** Canonical list of recognised UAT types — uat-policy.ts re-exports this as UAT_TYPES. */
+export const UAT_TYPE_KEYWORDS: readonly UatType[] = [
+  'artifact-driven',
+  'browser-executable',
+  'runtime-executable',
+  'live-runtime',
+  'mixed',
+  'human-experience',
+];
+
+/** Match a value against the recognised UAT type keywords (leading-keyword-only). */
+function matchUatTypeKeyword(value: string): UatType | undefined {
+  const normalized = value.trim().toLowerCase();
+  return UAT_TYPE_KEYWORDS.find(keyword => normalized.startsWith(keyword));
+}
+
 /**
  * Extract the UAT type from a UAT file's raw content.
  *
  * UAT files have no YAML frontmatter - pass raw file content directly.
  * Classification is leading-keyword-only: e.g. `mixed (artifact-driven + live-runtime)` → `'mixed'`.
  *
+ * The canonical form is a `- UAT mode: <type>` bullet under `## UAT Type`
+ * (case-insensitive prefix, `**bold**` tolerated). When no such line exists,
+ * a line that itself starts with a recognised keyword — e.g. a bare
+ * `browser-executable` under the heading — is accepted, so agent-authored
+ * format drift does not silently fall back to artifact-driven.
+ *
  * Returns `undefined` when:
  * - the `## UAT Type` section is absent
- * - no `UAT mode:` bullet is found in the section
- * - the value does not start with a recognised keyword
+ * - a `UAT mode:` line exists but its value starts with no recognised keyword
+ * - no line in the section starts with `UAT mode:` or a recognised keyword
  */
 export function extractUatType(content: string): UatType | undefined {
   const sectionText = extractSection(content, 'UAT Type');
   if (!sectionText) return undefined;
 
-  const bullets = parseBullets(sectionText);
-  const modeBullet = bullets.find(b => b.startsWith('UAT mode:'));
-  if (!modeBullet) return undefined;
+  const lines = parseBullets(sectionText).map(line => line.replace(/\*\*/g, ''));
 
-  const rawValue = modeBullet.slice('UAT mode:'.length).trim().toLowerCase();
+  for (const line of lines) {
+    const declared = /^uat mode:\s*(.*)$/i.exec(line);
+    if (declared) return matchUatTypeKeyword(declared[1]);
+  }
 
-  if (rawValue.startsWith('artifact-driven')) return 'artifact-driven';
-  if (rawValue.startsWith('browser-executable')) return 'browser-executable';
-  if (rawValue.startsWith('runtime-executable')) return 'runtime-executable';
-  if (rawValue.startsWith('live-runtime')) return 'live-runtime';
-  if (rawValue.startsWith('human-experience')) return 'human-experience';
-  if (rawValue.startsWith('mixed')) return 'mixed';
+  for (const line of lines) {
+    const matched = matchUatTypeKeyword(line);
+    if (matched) return matched;
+  }
 
   return undefined;
 }

package/src/resources/extensions/gsd/gsd-command-home.ts

@@ -66,7 +66,7 @@ function disabled(description: string, reason: string): string {
 
 export function buildGsdHomeModel(
   state: GSDState,
-  closeout?: Pick<CloseoutContext, "strandedQuick" | "unmergedMilestones">,
+  closeout?: Pick<CloseoutContext, "strandedQuick" | "unmergedMilestones" | "idleResidueHint">,
 ): GsdHomeModel {
   const blocked = isBlocked(state);
   const complete = state.phase === "complete";
@@ -74,10 +74,14 @@ export function buildGsdHomeModel(
   const workLabel = activeWorkLabel(state);
   const strandedQuick = closeout?.strandedQuick ?? null;
   const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+  const idleResidueHint = closeout?.idleResidueHint ?? null;
+  const hasIdleResidue = Boolean(idleResidueHint);
   const nextReason = complete
     ? "all milestones are complete"
     : blocked
       ? "the active milestone is blocked"
+      : hasIdleResidue
+        ? "milestone git residue needs recovery"
       : !hasActiveWork
         ? "there is no active milestone"
         : "";
@@ -91,6 +95,8 @@ export function buildGsdHomeModel(
       ? "finish_milestone"
       : blocked
         ? "fix_recover"
+        : hasIdleResidue
+          ? "fix_recover"
         : canAdvance
           ? "continue_step"
           : complete && unmappedActive > 0
@@ -107,6 +113,8 @@ export function buildGsdHomeModel(
     ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
     : unmergedMilestone
       ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
+      : idleResidueHint
+        ? [idleResidueHint.message]
       : completionSummary;
 
   return {
@@ -181,10 +189,12 @@ export function buildGsdHomeModel(
         label: "Fix or recover",
         description: blocked
           ? "Review the blocker and recovery commands for the active milestone."
+          : hasIdleResidue
+            ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
           : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-        enabled: blocked,
+        enabled: blocked || hasIdleResidue,
         recommended: recommended === "fix_recover",
-        disabledReason: blocked ? undefined : "no blocker is active",
+        disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
       },
       {
         id: "start_configure",

package/src/resources/extensions/gsd/gsd-db.ts

@@ -3,13 +3,15 @@
 //
 // ─── Single-writer invariant ─────────────────────────────────────────────
 // Every write-SQL statement against `.gsd/gsd.db` lives behind a typed
-// wrapper in the single-writer layer (this file plus db/writers/*). Connection
-// ownership, lifecycle, schema/migrations and transaction primitives live in
-// db/engine.ts and are re-exported here for backward compatibility, so callers
-// keep importing from "./gsd-db.js".
+// wrapper in the explicit writer allowlist: this compatibility barrel,
+// db/writers/*, typed coordination/runtime writers, schema/migration helpers,
+// and ADR backfill helpers. Connection ownership, lifecycle, schema/migrations,
+// and transaction primitives live in db/engine.ts and are re-exported here for
+// backward compatibility, so callers keep importing from "./gsd-db.js".
 //
 // `_getAdapter()` (re-exported from the engine) is retained for read-only
-// SELECTs in query modules. Do NOT use it for writes — add a wrapper here.
+// SELECTs in query modules. Do NOT use it for writes — add or call a typed
+// wrapper in the explicit writer layer.
 //
 // The separate `.gsd/unit-claims.db` (unit-ownership.ts) is an intentionally
 // independent store and is excluded from this invariant.
@@ -46,11 +48,11 @@ import { rowToSlice, rowToTask, type SliceRow, type TaskRow } from "./db-task-sl
 // primitives now live in the engine; re-export the full public surface so
 // existing `from "./gsd-db.js"` imports keep working.
 export * from "./db/engine.js";
-import { transaction, getDb, getDbOrNull } from "./db/engine.js";
+import { immediateTransaction, transaction, getDb, getDbOrNull } from "./db/engine.js";
 
 // ─── Single Writer Layer re-exports ──────────────────────────────────────
-// Write subsystems live in db/writers/*; re-exported here so callers keep
-// importing from "./gsd-db.js".
+// Domain write subsystems live in db/writers/*; re-exported here so callers
+// keep importing from "./gsd-db.js".
 export * from "./db/writers/memory.js";
 export * from "./db/writers/reconcile.js";
 export * from "./db/writers/import-restore.js";
@@ -246,9 +248,9 @@ export function insertMilestone(m: {
   status?: string;
   depends_on?: string[];
   planning?: Partial<MilestonePlanningRecord>;
-}): void {
+}): boolean {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-  getDbOrNull()!.prepare(
+  const result = getDbOrNull()!.prepare(
     `INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
@@ -279,7 +281,8 @@ export function insertMilestone(m: {
     ":definition_of_done": JSON.stringify(m.planning?.definitionOfDone ?? []),
     ":requirement_coverage": m.planning?.requirementCoverage ?? "",
     ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
-  });
+  }) as { changes?: number };
+  return (result.changes ?? 0) > 0;
 }
 
 export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord> & { title?: string; status?: string; depends_on?: string[] }): void {
@@ -706,19 +709,14 @@ export function insertVerificationEvidence(e: {
 
 
 export function setMilestoneQueueOrder(order: string[]): void {
-  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-  getDbOrNull()!.exec("BEGIN IMMEDIATE");
-  try {
-    getDbOrNull()!.prepare("UPDATE milestones SET sequence = 0").run();
-    const stmt = getDbOrNull()!.prepare("UPDATE milestones SET sequence = :sequence WHERE id = :id");
+  const db = getDb();
+  immediateTransaction(() => {
+    db.prepare("UPDATE milestones SET sequence = 0").run();
+    const stmt = db.prepare("UPDATE milestones SET sequence = :sequence WHERE id = :id");
     order.forEach((id, index) => {
       stmt.run({ ":id": id, ":sequence": index + 1 });
     });
-    getDbOrNull()!.exec("COMMIT");
-  } catch (err) {
-    getDbOrNull()!.exec("ROLLBACK");
-    throw err;
-  }
+  });
 }
 
 function getMilestoneStatusForUpdate(milestoneId: string): string | null {
@@ -1441,4 +1439,3 @@ export function upsertQualityGate(g: {
     ":evaluated_at": g.evaluatedAt,
   });
 }
-

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

@@ -88,6 +88,84 @@ export function needsRemediationBlockerGuidance(milestoneId: string): string {
   ].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. */

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,
@@ -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).
@@ -1708,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.