gsd-pi 2.22.0 → 2.24.0

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

@@ -201,6 +201,81 @@ function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string)
   });
 }
 
+/**
+ * Build the discuss prompt for headless milestone creation.
+ * Uses the discuss-headless prompt template with seed context injected.
+ */
+function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, _basePath: string): string {
+  const milestoneRel = `.gsd/milestones/${nextId}`;
+  const inlinedTemplates = [
+    inlineTemplate("project", "Project"),
+    inlineTemplate("requirements", "Requirements"),
+    inlineTemplate("context", "Context"),
+    inlineTemplate("roadmap", "Roadmap"),
+    inlineTemplate("decisions", "Decisions"),
+  ].join("\n\n---\n\n");
+  return loadPrompt("discuss-headless", {
+    milestoneId: nextId,
+    seedContext,
+    contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
+    roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`,
+    inlinedTemplates,
+  });
+}
+
+/**
+ * Bootstrap a .gsd/ project from scratch for headless use.
+ * Ensures git repo, .gsd/ structure, gitignore, and preferences all exist.
+ */
+function bootstrapGsdProject(basePath: string): void {
+  if (!nativeIsRepo(basePath)) {
+    const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
+    nativeInit(basePath, mainBranch);
+  }
+
+  const root = gsdRoot(basePath);
+  mkdirSync(join(root, "milestones"), { recursive: true });
+  mkdirSync(join(root, "runtime"), { recursive: true });
+
+  const commitDocs = loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs;
+  ensureGitignore(basePath, { commitDocs });
+  ensurePreferences(basePath);
+  untrackRuntimeFiles(basePath);
+}
+
+/**
+ * Headless milestone creation from a seed specification document.
+ * Bootstraps the project if needed, generates the next milestone ID,
+ * and dispatches the headless discuss prompt (no Q&A rounds).
+ */
+export async function showHeadlessMilestoneCreation(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  seedContext: string,
+): Promise<void> {
+  // Ensure .gsd/ is bootstrapped
+  bootstrapGsdProject(basePath);
+
+  // Generate next milestone ID
+  const existingIds = findMilestoneIds(basePath);
+  const prefs = loadEffectiveGSDPreferences();
+  const nextId = nextMilestoneId(existingIds, prefs?.preferences?.unique_milestone_ids ?? false);
+
+  // Create milestone directory
+  const milestoneDir = join(basePath, ".gsd", "milestones", nextId, "slices");
+  mkdirSync(milestoneDir, { recursive: true });
+
+  // Build and dispatch the headless discuss prompt
+  const prompt = buildHeadlessDiscussPrompt(nextId, seedContext, basePath);
+
+  // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
+  pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+
+  // Dispatch
+  dispatchWorkflow(pi, prompt);
+}
+
 export function findMilestoneIds(basePath: string): string[] {
   const dir = milestonesDir(basePath);
   try {
@@ -821,8 +896,9 @@ export async function showDiscuss(
 
     if (choice === "discuss_draft") {
       const discussMilestoneTemplates = inlineTemplate("context", "Context");
+      const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
       const basePrompt = loadPrompt("guided-discuss-milestone", {
-        milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
+        milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
       });
       const seed = draftContent
         ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
@@ -831,9 +907,10 @@ export async function showDiscuss(
       dispatchWorkflow(pi, seed, "gsd-discuss");
     } else if (choice === "discuss_fresh") {
       const discussMilestoneTemplates = inlineTemplate("context", "Context");
+      const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
       pendingAutoStart = { ctx, pi, basePath, milestoneId: mid, step: false };
       dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
-        milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
+        milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
       }), "gsd-discuss");
     } else if (choice === "skip_milestone") {
       const milestoneIds = findMilestoneIds(basePath);
@@ -1136,8 +1213,9 @@ export async function showSmartEntry(
 
     if (choice === "discuss_draft") {
       const discussMilestoneTemplates = inlineTemplate("context", "Context");
+      const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
       const basePrompt = loadPrompt("guided-discuss-milestone", {
-        milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
+        milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
       });
       const seed = draftContent
         ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
@@ -1146,9 +1224,10 @@ export async function showSmartEntry(
       dispatchWorkflow(pi, seed, "gsd-discuss");
     } else if (choice === "discuss_fresh") {
       const discussMilestoneTemplates = inlineTemplate("context", "Context");
+      const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
       pendingAutoStart = { ctx, pi, basePath, milestoneId, step: stepMode };
       dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
-        milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
+        milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
       }), "gsd-discuss");
     } else if (choice === "skip_milestone") {
       const milestoneIds = findMilestoneIds(basePath);
@@ -1220,8 +1299,9 @@ export async function showSmartEntry(
         }));
       } else if (choice === "discuss") {
         const discussMilestoneTemplates = inlineTemplate("context", "Context");
+        const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
         dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
-          milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates,
+          milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
         }));
       } else if (choice === "skip_milestone") {
         const milestoneIds = findMilestoneIds(basePath);

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

@@ -129,6 +129,23 @@ export default function (pi: ExtensionAPI) {
   registerWorktreeCommand(pi);
   registerExitCommand(pi);
 
+  // ── EPIPE guard — prevent crash when stdout/stderr pipe closes unexpectedly ──
+  // Node.js throws a fatal `Error: write EPIPE` when the parent process closes
+  // its end of the stdio pipe (e.g. during shell/IPC teardown) while auto-mode
+  // is still writing diagnostics. Catching this here gives auto-mode a clean
+  // chance to persist state and pause instead of crashing (see issue #739).
+  if (!process.listeners("uncaughtException").some(l => l.name === "_gsdEpipeGuard")) {
+    const _gsdEpipeGuard = (err: Error): void => {
+      if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+        // Pipe closed — nothing we can write; just exit cleanly
+        process.exit(0);
+      }
+      // Re-throw anything that isn't EPIPE so real crashes still surface
+      throw err;
+    };
+    process.on("uncaughtException", _gsdEpipeGuard);
+  }
+
   // ── /kill — immediate exit (bypass cleanup) ─────────────────────────────
   pi.registerCommand("kill", {
     description: "Exit GSD immediately (no cleanup)",
@@ -699,7 +716,23 @@ export default function (pi: ExtensionAPI) {
         }
       }
 
-      await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi));
+      // Detect rate-limit errors and extract retry delay for auto-resume
+      const errorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+      const isRateLimit = /rate.?limit|too many requests|429/i.test(errorMsg);
+      const retryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number")
+        ? lastMsg.retryAfterMs
+        : (() => { const m = errorMsg.match(/reset in (\d+)s/i); return m ? Number(m[1]) * 1000 : undefined; })();
+
+      await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi), {
+        isRateLimit,
+        retryAfterMs,
+        resume: () => {
+          pi.sendMessage(
+            { customType: "gsd-auto-timeout-recovery", content: "Continue execution \u2014 rate limit window elapsed.", display: false },
+            { triggerTurn: true },
+          );
+        },
+      });
       return;
     }
 

package/src/resources/extensions/gsd/mcp-server.ts

@@ -1,15 +1,24 @@
-// @ts-ignore — @modelcontextprotocol/sdk types may not be in extensions tsconfig
-import { Server } from '@modelcontextprotocol/sdk/server'
-// @ts-ignore
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio'
-// @ts-ignore
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types'
+/**
+ * MCP (Model Context Protocol) server for the GSD extension.
+ *
+ * This module provides the same MCP server functionality as src/mcp-server.ts
+ * but can be loaded via jiti in the extension runtime context. It enables
+ * GSD's tools to be used by external AI clients (Claude Desktop, VS Code
+ * Copilot, etc.) via the MCP standard protocol over stdin/stdout.
+ */
 
 interface McpTool {
   name: string
   description: string
   parameters: Record<string, unknown>
-  execute(toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal, onUpdate?: unknown): Promise<{ content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }>
+  execute(
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal?: AbortSignal,
+    onUpdate?: unknown,
+  ): Promise<{
+    content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>
+  }>
 }
 
 export async function startMcpServer(options: {
@@ -18,6 +27,16 @@ export async function startMcpServer(options: {
 }): Promise<void> {
   const { tools, version = '0.0.0' } = options
 
+  // Dynamic imports — MCP SDK subpath exports use a "./*" wildcard pattern
+  // that cannot be statically resolved by all TypeScript configurations.
+  // @ts-ignore
+  const { Server } = await import('@modelcontextprotocol/sdk/server')
+  // @ts-ignore
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js')
+  // @ts-ignore
+  const sdkTypes = await import('@modelcontextprotocol/sdk/types')
+  const { ListToolsRequestSchema, CallToolRequestSchema } = sdkTypes
+
   const toolMap = new Map<string, McpTool>()
   for (const tool of tools) {
     toolMap.set(tool.name, tool)
@@ -28,9 +47,10 @@ export async function startMcpServer(options: {
     { capabilities: { tools: {} } },
   )
 
+  // tools/list — return every registered GSD tool with its JSON Schema parameters
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-      tools: tools.map((t) => ({
+      tools: tools.map((t: McpTool) => ({
         name: t.name,
         description: t.description,
         inputSchema: t.parameters,
@@ -38,6 +58,7 @@ export async function startMcpServer(options: {
     }
   })
 
+  // tools/call — execute the requested tool and return content blocks
   server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
     const { name, arguments: args } = request.params
     const tool = toolMap.get(name)
@@ -56,15 +77,15 @@ export async function startMcpServer(options: {
         undefined,
       )
 
-      const content = result.content.map((block) => {
+      const content = result.content.map((block: any) => {
         if (block.type === 'text') {
-          return { type: 'text' as const, text: block.text }
+          return { type: 'text' as const, text: block.text ?? '' }
         }
         if (block.type === 'image') {
           return {
             type: 'image' as const,
-            data: block.data,
-            mimeType: block.mimeType,
+            data: block.data ?? '',
+            mimeType: block.mimeType ?? 'image/png',
           }
         }
         return { type: 'text' as const, text: JSON.stringify(block) }

package/src/resources/extensions/gsd/parallel-eligibility.ts

@@ -0,0 +1,233 @@
+/**
+ * GSD Parallel Eligibility — Milestone parallelism analysis.
+ *
+ * Analyzes which milestones can safely run in parallel by checking
+ * dependency satisfaction and file overlap across slice plans.
+ */
+
+import { deriveState } from "./state.js";
+import { parseRoadmap, parsePlan, loadFile } from "./files.js";
+import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import { findMilestoneIds } from "./guided-flow.js";
+import type { MilestoneRegistryEntry } from "./types.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface EligibilityResult {
+  milestoneId: string;
+  title: string;
+  eligible: boolean;
+  reason: string;
+}
+
+export interface ParallelCandidates {
+  eligible: EligibilityResult[];
+  ineligible: EligibilityResult[];
+  fileOverlaps: Array<{ mid1: string; mid2: string; files: string[] }>;
+}
+
+// ─── File Collection ─────────────────────────────────────────────────────────
+
+/**
+ * Collect all `filesLikelyTouched` across every slice plan in a milestone.
+ * Returns a deduplicated list of file paths.
+ */
+async function collectTouchedFiles(
+  basePath: string,
+  milestoneId: string,
+): Promise<string[]> {
+  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (!roadmapPath) return [];
+
+  const roadmapContent = await loadFile(roadmapPath);
+  if (!roadmapContent) return [];
+
+  const roadmap = parseRoadmap(roadmapContent);
+  const files = new Set<string>();
+
+  for (const slice of roadmap.slices) {
+    const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+    if (!planPath) continue;
+
+    const planContent = await loadFile(planPath);
+    if (!planContent) continue;
+
+    const plan = parsePlan(planContent);
+    for (const f of plan.filesLikelyTouched) {
+      files.add(f);
+    }
+  }
+
+  return [...files];
+}
+
+// ─── Overlap Detection ──────────────────────────────────────────────────────
+
+/**
+ * Compare file sets across milestones and return pairs with overlapping files.
+ */
+function detectFileOverlaps(
+  fileSets: Map<string, string[]>,
+): Array<{ mid1: string; mid2: string; files: string[] }> {
+  const overlaps: Array<{ mid1: string; mid2: string; files: string[] }> = [];
+  const ids = [...fileSets.keys()];
+
+  for (let i = 0; i < ids.length; i++) {
+    const files1 = new Set(fileSets.get(ids[i])!);
+    for (let j = i + 1; j < ids.length; j++) {
+      const files2 = fileSets.get(ids[j])!;
+      const shared = files2.filter(f => files1.has(f));
+      if (shared.length > 0) {
+        overlaps.push({ mid1: ids[i], mid2: ids[j], files: shared.sort() });
+      }
+    }
+  }
+
+  return overlaps;
+}
+
+// ─── Analysis ────────────────────────────────────────────────────────────────
+
+/**
+ * Analyze milestones for parallel execution eligibility.
+ *
+ * A milestone is eligible if:
+ * 1. It is not complete
+ * 2. Its dependencies (`dependsOn`) are all complete
+ * 3. It does not have file overlap with other eligible milestones
+ *    (overlaps are flagged as warnings but do not disqualify)
+ */
+export async function analyzeParallelEligibility(
+  basePath: string,
+): Promise<ParallelCandidates> {
+  const milestoneIds = findMilestoneIds(basePath);
+  const state = await deriveState(basePath);
+  const registry = state.registry;
+
+  // Build a lookup for quick status checks
+  const registryMap = new Map<string, MilestoneRegistryEntry>();
+  for (const entry of registry) {
+    registryMap.set(entry.id, entry);
+  }
+
+  const eligible: EligibilityResult[] = [];
+  const ineligible: EligibilityResult[] = [];
+
+  for (const mid of milestoneIds) {
+    const entry = registryMap.get(mid);
+    const title = entry?.title ?? mid;
+    const status = entry?.status ?? "pending";
+
+    // Rule 1: skip complete milestones
+    if (status === "complete") {
+      ineligible.push({
+        milestoneId: mid,
+        title,
+        eligible: false,
+        reason: "Already complete.",
+      });
+      continue;
+    }
+
+    // Rule 2: check dependency satisfaction
+    const deps = entry?.dependsOn ?? [];
+    const unsatisfied = deps.filter(dep => {
+      const depEntry = registryMap.get(dep);
+      return !depEntry || depEntry.status !== "complete";
+    });
+
+    if (unsatisfied.length > 0) {
+      ineligible.push({
+        milestoneId: mid,
+        title,
+        eligible: false,
+        reason: `Blocked by incomplete dependencies: ${unsatisfied.join(", ")}.`,
+      });
+      continue;
+    }
+
+    eligible.push({
+      milestoneId: mid,
+      title,
+      eligible: true,
+      reason: "All dependencies satisfied.",
+    });
+  }
+
+  // Rule 3: check file overlap among eligible milestones
+  const fileSets = new Map<string, string[]>();
+  for (const result of eligible) {
+    const files = await collectTouchedFiles(basePath, result.milestoneId);
+    fileSets.set(result.milestoneId, files);
+  }
+
+  const fileOverlaps = detectFileOverlaps(fileSets);
+
+  // Annotate eligible milestones that have file overlaps
+  const overlappingIds = new Set<string>();
+  for (const overlap of fileOverlaps) {
+    overlappingIds.add(overlap.mid1);
+    overlappingIds.add(overlap.mid2);
+  }
+
+  for (const result of eligible) {
+    if (overlappingIds.has(result.milestoneId)) {
+      result.reason = "All dependencies satisfied. WARNING: has file overlap with another eligible milestone.";
+    }
+  }
+
+  return { eligible, ineligible, fileOverlaps };
+}
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+/**
+ * Produce a human-readable report of parallel eligibility analysis.
+ */
+export function formatEligibilityReport(candidates: ParallelCandidates): string {
+  const lines: string[] = [];
+
+  lines.push("# Parallel Eligibility Report");
+  lines.push("");
+
+  // Eligible milestones
+  lines.push(`## Eligible for Parallel Execution (${candidates.eligible.length})`);
+  lines.push("");
+  if (candidates.eligible.length === 0) {
+    lines.push("No milestones are currently eligible for parallel execution.");
+  } else {
+    for (const e of candidates.eligible) {
+      lines.push(`- **${e.milestoneId}** — ${e.title}`);
+      lines.push(`  ${e.reason}`);
+    }
+  }
+  lines.push("");
+
+  // Ineligible milestones
+  lines.push(`## Ineligible (${candidates.ineligible.length})`);
+  lines.push("");
+  if (candidates.ineligible.length === 0) {
+    lines.push("All milestones are eligible.");
+  } else {
+    for (const e of candidates.ineligible) {
+      lines.push(`- **${e.milestoneId}** — ${e.title}`);
+      lines.push(`  ${e.reason}`);
+    }
+  }
+  lines.push("");
+
+  // File overlap warnings
+  if (candidates.fileOverlaps.length > 0) {
+    lines.push(`## File Overlap Warnings (${candidates.fileOverlaps.length})`);
+    lines.push("");
+    for (const overlap of candidates.fileOverlaps) {
+      lines.push(`- **${overlap.mid1}** <-> **${overlap.mid2}** — ${overlap.files.length} shared file(s):`);
+      for (const f of overlap.files) {
+        lines.push(`  - \`${f}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -0,0 +1,156 @@
+/**
+ * GSD Parallel Merge — Worktree reconciliation for parallel milestones.
+ *
+ * Handles merging completed milestone worktrees back to main branch
+ * with safety checks for parallel execution context.
+ */
+
+import { loadFile } from "./files.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { mergeMilestoneToMain } from "./auto-worktree.js";
+import { MergeConflictError } from "./git-service.js";
+import { removeSessionStatus } from "./session-status-io.js";
+import type { WorkerInfo } from "./parallel-orchestrator.js";
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export interface MergeResult {
+  milestoneId: string;
+  success: boolean;
+  commitMessage?: string;
+  pushed?: boolean;
+  error?: string;
+  conflictFiles?: string[];
+}
+
+export type MergeOrder = "sequential" | "by-completion";
+
+// ─── Merge Queue ───────────────────────────────────────────────────────────
+
+/**
+ * Determine safe merge order for completed milestones.
+ * Sequential: merge in milestone ID order (M001 before M002).
+ * By-completion: merge in the order milestones finished.
+ */
+export function determineMergeOrder(
+  workers: WorkerInfo[],
+  order: MergeOrder = "sequential",
+): string[] {
+  const completed = workers.filter(w => w.state === "stopped" && w.completedUnits > 0);
+  if (order === "by-completion") {
+    return completed
+      .sort((a, b) => a.startedAt - b.startedAt) // earliest first
+      .map(w => w.milestoneId);
+  }
+  return completed
+    .sort((a, b) => a.milestoneId.localeCompare(b.milestoneId))
+    .map(w => w.milestoneId);
+}
+
+/**
+ * Attempt to merge a single milestone's worktree back to main.
+ * Wraps mergeMilestoneToMain with error handling for parallel context.
+ */
+export async function mergeCompletedMilestone(
+  basePath: string,
+  milestoneId: string,
+): Promise<MergeResult> {
+  try {
+    // Load the roadmap content (needed by mergeMilestoneToMain)
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (!roadmapPath) {
+      return {
+        milestoneId,
+        success: false,
+        error: `No roadmap found for ${milestoneId}`,
+      };
+    }
+
+    const roadmapContent = await loadFile(roadmapPath);
+    if (!roadmapContent) {
+      return {
+        milestoneId,
+        success: false,
+        error: `Could not read roadmap for ${milestoneId}`,
+      };
+    }
+
+    // Attempt the merge
+    const result = mergeMilestoneToMain(basePath, milestoneId, roadmapContent);
+
+    // Clean up parallel session status
+    removeSessionStatus(basePath, milestoneId);
+
+    return {
+      milestoneId,
+      success: true,
+      commitMessage: result.commitMessage,
+      pushed: result.pushed,
+    };
+  } catch (err) {
+    if (err instanceof MergeConflictError) {
+      return {
+        milestoneId,
+        success: false,
+        error: `Merge conflict: ${err.conflictedFiles.length} conflicting file(s)`,
+        conflictFiles: err.conflictedFiles,
+      };
+    }
+    return {
+      milestoneId,
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Merge all completed milestones in sequence.
+ * Stops on first conflict and returns results so far.
+ */
+export async function mergeAllCompleted(
+  basePath: string,
+  workers: WorkerInfo[],
+  order: MergeOrder = "sequential",
+): Promise<MergeResult[]> {
+  const mergeOrder = determineMergeOrder(workers, order);
+  const results: MergeResult[] = [];
+
+  for (const mid of mergeOrder) {
+    const result = await mergeCompletedMilestone(basePath, mid);
+    results.push(result);
+
+    // Stop on first conflict — later merges may depend on this one
+    if (!result.success && result.conflictFiles) {
+      break;
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format merge results for display.
+ */
+export function formatMergeResults(results: MergeResult[]): string {
+  if (results.length === 0) return "No completed milestones to merge.";
+
+  const lines: string[] = ["# Merge Results\n"];
+
+  for (const r of results) {
+    if (r.success) {
+      const pushStatus = r.pushed ? " (pushed)" : "";
+      lines.push(`- **${r.milestoneId}** — merged successfully${pushStatus}`);
+    } else if (r.conflictFiles) {
+      lines.push(`- **${r.milestoneId}** — CONFLICT (${r.conflictFiles.length} file(s)):`);
+      for (const f of r.conflictFiles) {
+        lines.push(`  - \`${f}\``);
+      }
+      lines.push(`  Resolve conflicts manually and run \`/gsd parallel merge ${r.milestoneId}\` to retry.`);
+    } else {
+      lines.push(`- **${r.milestoneId}** — failed: ${r.error}`);
+    }
+  }
+
+  return lines.join("\n");
+}