gsd-pi 2.23.0 → 2.24.0

package/dist/resources/extensions/gsd/doctor.ts

@@ -11,6 +11,7 @@ import { RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { nativeIsRepo, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached } from "./native-git-bridge.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
 import { ensureGitignore } from "./gitignore.js";
+import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
@@ -24,6 +25,7 @@ export type DoctorIssueCode =
   | "all_tasks_done_roadmap_not_checked"
   | "slice_checked_missing_summary"
   | "slice_checked_missing_uat"
+  | "all_slices_done_missing_milestone_validation"
   | "all_slices_done_missing_milestone_summary"
   | "task_done_must_haves_not_verified"
   | "active_requirement_missing_owner"
@@ -36,6 +38,7 @@ export type DoctorIssueCode =
   | "tracked_runtime_files"
   | "legacy_slice_branches"
   | "stale_crash_lock"
+  | "stale_parallel_session"
   | "orphaned_completed_units"
   | "stale_hook_state"
   | "activity_log_bloat"
@@ -710,6 +713,31 @@ async function checkRuntimeHealth(
     // Non-fatal — crash lock check failed
   }
 
+  // ── Stale parallel sessions ────────────────────────────────────────────
+  try {
+    const parallelStatuses = readAllSessionStatuses(basePath);
+    for (const status of parallelStatuses) {
+      if (isSessionStale(status)) {
+        issues.push({
+          severity: "warning",
+          code: "stale_parallel_session",
+          scope: "project",
+          unitId: status.milestoneId,
+          message: `Stale parallel session for ${status.milestoneId} (PID ${status.pid}, started ${new Date(status.startedAt).toISOString()}, last heartbeat ${new Date(status.lastHeartbeat).toISOString()}) — process is no longer running`,
+          file: `.gsd/parallel/${status.milestoneId}.status.json`,
+          fixable: true,
+        });
+
+        if (shouldFix("stale_parallel_session")) {
+          removeSessionStatus(basePath, status.milestoneId);
+          fixesApplied.push(`cleaned up stale parallel session for ${status.milestoneId}`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — parallel session check failed
+  }
+
   // ── Orphaned completed-units keys ─────────────────────────────────────
   try {
     const completedKeysFile = join(root, "completed-units.json");
@@ -1066,11 +1094,13 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       const tasksDir = resolveTasksDir(basePath, milestoneId, slice.id);
       if (!tasksDir) {
         issues.push({
-          severity: "error",
+          severity: slice.done ? "warning" : "error",
           code: "missing_tasks_dir",
           scope: "slice",
           unitId,
-          message: `Missing tasks directory for ${unitId}`,
+          message: slice.done
+            ? `Missing tasks directory for ${unitId} (slice is complete — cosmetic only)`
+            : `Missing tasks directory for ${unitId}`,
           file: relSlicePath(basePath, milestoneId, slice.id),
           fixable: true,
         });
@@ -1084,15 +1114,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       const planContent = planPath ? await loadFile(planPath) : null;
       const plan = planContent ? parsePlan(planContent) : null;
       if (!plan) {
-        issues.push({
-          severity: "warning",
-          code: "missing_slice_plan",
-          scope: "slice",
-          unitId,
-          message: `Slice ${unitId} has no plan file`,
-          file: relSliceFile(basePath, milestoneId, slice.id, "PLAN"),
-          fixable: false,
-        });
+        if (!slice.done) {
+          issues.push({
+            severity: "warning",
+            code: "missing_slice_plan",
+            scope: "slice",
+            unitId,
+            message: `Slice ${unitId} has no plan file`,
+            file: relSliceFile(basePath, milestoneId, slice.id, "PLAN"),
+            fixable: false,
+          });
+        }
         continue;
       }
 
@@ -1255,6 +1287,19 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       }
     }
 
+    // Milestone-level check: all slices done but no validation file
+    if (isMilestoneComplete(roadmap) && !resolveMilestoneFile(basePath, milestoneId, "VALIDATION") && !resolveMilestoneFile(basePath, milestoneId, "SUMMARY")) {
+      issues.push({
+        severity: "info",
+        code: "all_slices_done_missing_milestone_validation",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `All slices are done but ${milestoneId}-VALIDATION.md is missing — milestone is in validating-milestone phase`,
+        file: relMilestoneFile(basePath, milestoneId, "VALIDATION"),
+        fixable: false,
+      });
+    }
+
     // Milestone-level check: all slices done but no milestone summary
     if (isMilestoneComplete(roadmap) && !resolveMilestoneFile(basePath, milestoneId, "SUMMARY")) {
       issues.push({

package/dist/resources/extensions/gsd/exit-command.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
-type StopAutoFn = (ctx: ExtensionCommandContext, pi: ExtensionAPI) => Promise<void>;
+type StopAutoFn = (ctx: ExtensionCommandContext, pi: ExtensionAPI, reason?: string) => Promise<void>;
 
 export function registerExitCommand(
   pi: ExtensionAPI,
@@ -11,7 +11,7 @@ export function registerExitCommand(
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
       // Stop auto-mode first so locks and activity state are cleaned up before shutdown.
       const stopAuto = deps.stopAuto ?? (await import("./auto.js")).stopAuto;
-      await stopAuto(ctx, pi);
+      await stopAuto(ctx, pi, "Graceful exit");
       ctx.shutdown();
     },
   });

package/dist/resources/extensions/gsd/gitignore.ts

@@ -19,6 +19,7 @@ const GSD_RUNTIME_PATTERNS = [
   ".gsd/forensics/",
   ".gsd/runtime/",
   ".gsd/worktrees/",
+  ".gsd/parallel/",
   ".gsd/auto.lock",
   ".gsd/metrics.json",
   ".gsd/completed-units.json",

package/dist/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 {

package/dist/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/dist/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/dist/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");
+}