gsd-pi 2.23.0 → 2.24.0

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

@@ -6,14 +6,14 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { AuthStorage } from "@gsd/pi-coding-agent";
-import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, unlinkSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { enableDebug, isDebugEnabled } from "./debug-logger.js";
 import { fileURLToPath } from "node:url";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
-import { showQueue, showDiscuss } from "./guided-flow.js";
+import { showQueue, showDiscuss, showHeadlessMilestoneCreation } from "./guided-flow.js";
 import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote, dispatchDirectPhase } from "./auto.js";
 import { resolveProjectRoot } from "./worktree.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
@@ -42,6 +42,14 @@ import { handleQuick } from "./quick.js";
 import { handleHistory } from "./history.js";
 import { handleUndo } from "./undo.js";
 import { handleExport } from "./export.js";
+import {
+  isParallelActive, getOrchestratorState, getWorkerStatuses,
+  prepareParallelStart, startParallel, stopParallel,
+  pauseWorker, resumeWorker,
+} from "./parallel-orchestrator.js";
+import { formatEligibilityReport } from "./parallel-eligibility.js";
+import { mergeAllCompleted, mergeCompletedMilestone, formatMergeResults } from "./parallel-merge.js";
+import { resolveParallelConfig } from "./preferences.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
@@ -69,20 +77,53 @@ function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge",
+    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge|new-milestone|parallel",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
-        "help", "next", "auto", "stop", "pause", "status", "visualize", "queue", "quick", "discuss",
-        "capture", "triage", "dispatch",
-        "history", "undo", "skip", "export", "cleanup", "mode", "prefs",
-        "config", "hooks", "run-hook", "skill-health", "doctor", "forensics", "migrate", "remote", "steer", "inspect", "knowledge",
+        { cmd: "help", desc: "Categorized command reference with descriptions" },
+        { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
+        { cmd: "auto", desc: "Autonomous mode — research, plan, execute, commit, repeat" },
+        { cmd: "stop", desc: "Stop auto mode gracefully" },
+        { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
+        { cmd: "status", desc: "Progress dashboard" },
+        { cmd: "visualize", desc: "Open workflow visualizer (progress, deps, metrics, timeline)" },
+        { cmd: "queue", desc: "Queue and reorder future milestones" },
+        { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
+        { cmd: "discuss", desc: "Discuss architecture and decisions" },
+        { cmd: "capture", desc: "Fire-and-forget thought capture" },
+        { cmd: "triage", desc: "Manually trigger triage of pending captures" },
+        { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+        { cmd: "history", desc: "View execution history" },
+        { cmd: "undo", desc: "Revert last completed unit" },
+        { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
+        { cmd: "export", desc: "Export milestone/slice results" },
+        { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
+        { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
+        { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
+        { cmd: "config", desc: "Set API keys for external tools" },
+        { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
+        { cmd: "run-hook", desc: "Manually trigger a specific hook" },
+        { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
+        { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
+        { cmd: "forensics", desc: "Examine execution logs" },
+        { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
+        { cmd: "remote", desc: "Control remote auto-mode" },
+        { cmd: "steer", desc: "Hard-steer plan documents during execution" },
+        { cmd: "inspect", desc: "Show SQLite DB diagnostics" },
+        { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
+        { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
+        { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge)" },
       ];
       const parts = prefix.trim().split(/\s+/);
 
       if (parts.length <= 1) {
         return subcommands
-          .filter((cmd) => cmd.startsWith(parts[0] ?? ""))
-          .map((cmd) => ({ value: cmd, label: cmd }));
+          .filter((item) => item.cmd.startsWith(parts[0] ?? ""))
+          .map((item) => ({ 
+            value: item.cmd, 
+            label: item.cmd, 
+            description: item.desc 
+          }));
       }
 
       if (parts[0] === "auto" && parts.length <= 2) {
@@ -99,6 +140,13 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((cmd) => ({ value: `mode ${cmd}`, label: cmd }));
       }
 
+      if (parts[0] === "parallel" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        return ["start", "status", "stop", "pause", "resume", "merge"]
+          .filter((cmd) => cmd.startsWith(subPrefix))
+          .map((cmd) => ({ value: `parallel ${cmd}`, label: cmd }));
+      }
+
       if (parts[0] === "prefs" && parts.length <= 2) {
         const subPrefix = parts[1] ?? "";
         return ["global", "project", "status", "wizard", "setup", "import-claude"]
@@ -251,7 +299,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           }
           return;
         }
-        await stopAuto(ctx, pi);
+        await stopAuto(ctx, pi, "User requested stop");
         return;
       }
 
@@ -288,6 +336,108 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      // ─── Parallel Orchestration ────────────────────────────────────────
+      if (trimmed.startsWith("parallel")) {
+        const parallelArgs = trimmed.slice("parallel".length).trim();
+        const [subCmd = "", ...restParts] = parallelArgs.split(/\s+/);
+        const rest = restParts.join(" ");
+
+        if (subCmd === "start" || subCmd === "") {
+          const loaded = loadEffectiveGSDPreferences();
+          const config = resolveParallelConfig(loaded?.preferences);
+          if (!config.enabled) {
+            pi.sendMessage({
+              customType: "gsd-parallel",
+              content: "Parallel mode is not enabled. Set `parallel.enabled: true` in your preferences.",
+              display: false,
+            });
+            return;
+          }
+          const candidates = await prepareParallelStart(projectRoot(), loaded?.preferences);
+          const report = formatEligibilityReport(candidates);
+          if (candidates.eligible.length === 0) {
+            pi.sendMessage({ customType: "gsd-parallel", content: report + "\n\nNo milestones are eligible for parallel execution.", display: false });
+            return;
+          }
+          const result = await startParallel(
+            projectRoot(),
+            candidates.eligible.map(e => e.milestoneId),
+            loaded?.preferences,
+          );
+          const lines = [`Parallel orchestration started.`, `Workers: ${result.started.join(", ")}`];
+          if (result.errors.length > 0) {
+            lines.push(`Errors: ${result.errors.map(e => `${e.mid}: ${e.error}`).join("; ")}`);
+          }
+          pi.sendMessage({ customType: "gsd-parallel", content: report + "\n\n" + lines.join("\n"), display: false });
+          return;
+        }
+
+        if (subCmd === "status") {
+          if (!isParallelActive()) {
+            pi.sendMessage({ customType: "gsd-parallel", content: "No parallel orchestration is currently active.", display: false });
+            return;
+          }
+          const workers = getWorkerStatuses();
+          const lines = ["# Parallel Workers\n"];
+          for (const w of workers) {
+            lines.push(`- **${w.milestoneId}** (${w.title}) — ${w.state} — ${w.completedUnits} units — $${w.cost.toFixed(2)}`);
+          }
+          const orchState = getOrchestratorState();
+          if (orchState) {
+            lines.push(`\nTotal cost: $${orchState.totalCost.toFixed(2)}`);
+          }
+          pi.sendMessage({ customType: "gsd-parallel", content: lines.join("\n"), display: false });
+          return;
+        }
+
+        if (subCmd === "stop") {
+          const mid = rest.trim() || undefined;
+          await stopParallel(projectRoot(), mid);
+          pi.sendMessage({ customType: "gsd-parallel", content: mid ? `Stopped worker for ${mid}.` : "All parallel workers stopped.", display: false });
+          return;
+        }
+
+        if (subCmd === "pause") {
+          const mid = rest.trim() || undefined;
+          pauseWorker(projectRoot(), mid);
+          pi.sendMessage({ customType: "gsd-parallel", content: mid ? `Paused worker for ${mid}.` : "All parallel workers paused.", display: false });
+          return;
+        }
+
+        if (subCmd === "resume") {
+          const mid = rest.trim() || undefined;
+          resumeWorker(projectRoot(), mid);
+          pi.sendMessage({ customType: "gsd-parallel", content: mid ? `Resumed worker for ${mid}.` : "All parallel workers resumed.", display: false });
+          return;
+        }
+
+        if (subCmd === "merge") {
+          const mid = rest.trim() || undefined;
+          if (mid) {
+            // Merge a specific milestone
+            const result = await mergeCompletedMilestone(projectRoot(), mid);
+            pi.sendMessage({ customType: "gsd-parallel", content: formatMergeResults([result]), display: false });
+            return;
+          }
+          // Merge all completed milestones
+          const workers = getWorkerStatuses();
+          if (workers.length === 0) {
+            pi.sendMessage({ customType: "gsd-parallel", content: "No parallel workers to merge.", display: false });
+            return;
+          }
+          const results = await mergeAllCompleted(projectRoot(), workers);
+          pi.sendMessage({ customType: "gsd-parallel", content: formatMergeResults(results), display: false });
+          return;
+        }
+
+        pi.sendMessage({
+          customType: "gsd-parallel",
+          content: `Unknown parallel subcommand "${subCmd}". Usage: /gsd parallel [start|status|stop|pause|resume|merge]`,
+          display: false,
+        });
+        return;
+      }
+
       if (trimmed === "cleanup") {
         await handleCleanupBranches(ctx, projectRoot());
         await handleCleanupSnapshots(ctx, projectRoot());
@@ -314,6 +464,21 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "new-milestone") {
+        const basePath = projectRoot();
+        const headlessContextPath = join(basePath, ".gsd", "runtime", "headless-context.md");
+        if (existsSync(headlessContextPath)) {
+          const seedContext = readFileSync(headlessContextPath, "utf-8");
+          try { unlinkSync(headlessContextPath); } catch { /* non-fatal */ }
+          await showHeadlessMilestoneCreation(ctx, pi, basePath, seedContext);
+        } else {
+          // No headless context — fall back to interactive smart entry
+          const { showSmartEntry } = await import("./guided-flow.js");
+          await showSmartEntry(ctx, pi, basePath);
+        }
+        return;
+      }
+
       if (trimmed.startsWith("capture ") || trimmed === "capture") {
         await handleCapture(trimmed.replace(/^capture\s*/, "").trim(), ctx);
         return;
@@ -434,6 +599,7 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd stop           Stop auto-mode gracefully",
     "  /gsd pause          Pause auto-mode (preserves state, /gsd auto to resume)",
     "  /gsd discuss        Start guided milestone/slice discussion",
+    "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
     "",
     "VISIBILITY",
     "  /gsd status         Show progress dashboard  (Ctrl+Alt+G)",

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

@@ -87,6 +87,7 @@ const UNIT_TYPE_TIERS: Record<string, ComplexityTier> = {
   "execute-task": "standard",
   "replan-slice": "heavy",
   "reassess-roadmap": "heavy",
+  "validate-milestone": "heavy",
   "complete-milestone": "standard",
 };
 

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -19,6 +19,7 @@ import {
 } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getActiveWorktreeName } from "./worktree-command.js";
+import { getWorkerBatches, hasActiveWorkers, type WorkerEntry } from "../subagent/worker-registry.js";
 
 function formatDuration(ms: number): string {
   const s = Math.floor(ms / 1000);
@@ -363,6 +364,43 @@ export class GSDDashboardOverlay {
       lines.push(blank());
     }
 
+    // Parallel workers section — shows active subagent sessions
+    if (hasActiveWorkers()) {
+      lines.push(hr());
+      lines.push(row(th.fg("text", th.bold("Parallel Workers"))));
+      lines.push(blank());
+
+      const batches = getWorkerBatches();
+      for (const [batchId, workers] of batches) {
+        const running = workers.filter(w => w.status === "running").length;
+        const done = workers.filter(w => w.status === "completed").length;
+        const failed = workers.filter(w => w.status === "failed").length;
+        const total = workers[0]?.batchSize ?? workers.length;
+
+        lines.push(row(joinColumns(
+          `  ${th.fg("accent", "⟐")} ${th.fg("text", `Batch ${batchId.slice(0, 8)}`)}`,
+          th.fg("dim", `${done + failed}/${total} done`),
+          contentWidth,
+        )));
+
+        for (const w of workers) {
+          const icon = w.status === "running"
+            ? th.fg("accent", "▸")
+            : w.status === "completed"
+              ? th.fg("success", "✓")
+              : th.fg("error", "✗");
+          const elapsed = th.fg("dim", formatDuration(Date.now() - w.startedAt));
+          const taskPreview = truncateToWidth(w.task, Math.max(20, contentWidth - 30));
+          lines.push(row(joinColumns(
+            `    ${icon} ${th.fg("text", w.agent)} ${th.fg("dim", taskPreview)}`,
+            elapsed,
+            contentWidth,
+          )));
+        }
+      }
+      lines.push(blank());
+    }
+
     // Pending captures badge — only shown when captures are waiting for triage
     if (this.dashData.pendingCaptureCount > 0) {
       const count = this.dashData.pendingCaptureCount;

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

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;
     }