gsd-pi 2.23.0 → 2.24.0

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

@@ -108,6 +108,7 @@ import {
   autoWorktreeBranch,
 } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
+import { consumeSignal } from "./session-status-io.js";
 import { showNextAction } from "../shared/next-action-ui.js";
 import { debugLog, debugTime, debugCount, debugPeak, enableDebug, isDebugEnabled, writeDebugSummary, getDebugLogPath } from "./debug-logger.js";
 import {
@@ -195,6 +196,35 @@ function syncStateToProjectRoot(worktreePath: string, projectRoot: string, miles
       cpSync(srcMilestone, dstMilestone, { recursive: true, force: true });
     }
   } catch { /* non-fatal */ }
+
+  // 3. Merge completed-units.json (set-union of both locations)
+  // Prevents already-completed units from being re-dispatched after crash/restart.
+  const srcKeysFile = join(wtGsd, "completed-units.json");
+  const dstKeysFile = join(prGsd, "completed-units.json");
+  if (existsSync(srcKeysFile)) {
+    try {
+      const srcKeys: string[] = JSON.parse(readFileSync(srcKeysFile, "utf8"));
+      let dstKeys: string[] = [];
+      if (existsSync(dstKeysFile)) {
+        try { dstKeys = JSON.parse(readFileSync(dstKeysFile, "utf8")); } catch { /* ignore corrupt dst */ }
+      }
+      const merged = [...new Set([...dstKeys, ...srcKeys])];
+      writeFileSync(dstKeysFile, JSON.stringify(merged, null, 2));
+    } catch { /* non-fatal */ }
+  }
+
+  // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
+  // Without this, a crash during a unit leaves the runtime record only in the
+  // worktree. If the next session resolves basePath before worktree re-entry,
+  // selfHeal can't find or clear the stale record (#769).
+  try {
+    const srcRuntime = join(wtGsd, "runtime", "units");
+    const dstRuntime = join(prGsd, "runtime", "units");
+    if (existsSync(srcRuntime)) {
+      mkdirSync(dstRuntime, { recursive: true });
+      cpSync(srcRuntime, dstRuntime, { recursive: true, force: true });
+    }
+  } catch { /* non-fatal */ }
 }
 
 // ─── State ────────────────────────────────────────────────────────────────────
@@ -361,11 +391,12 @@ let _sigtermHandler: (() => void) | null = null;
  */
 const inFlightTools = new Map<string, number>();
 
-type BudgetAlertLevel = 0 | 75 | 90 | 100;
+type BudgetAlertLevel = 0 | 75 | 80 | 90 | 100;
 
 export function getBudgetAlertLevel(budgetPct: number): BudgetAlertLevel {
   if (budgetPct >= 1.0) return 100;
   if (budgetPct >= 0.90) return 90;
+  if (budgetPct >= 0.80) return 80;
   if (budgetPct >= 0.75) return 75;
   return 0;
 }
@@ -552,11 +583,7 @@ function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void
       await dispatchNextUnit(ctx, pi);
     } catch (retryErr) {
       const message = retryErr instanceof Error ? retryErr.message : String(retryErr);
-      ctx.ui.notify(
-        `Dispatch gap recovery failed: ${message}. Stopping auto-mode.`,
-        "error",
-      );
-      await stopAuto(ctx, pi);
+      await stopAuto(ctx, pi, `Dispatch gap recovery failed: ${message}`);
       return;
     }
 
@@ -564,17 +591,14 @@ function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void
     // (no sendMessage called → no timeout set), auto-mode is permanently
     // stalled. Stop cleanly instead of leaving it active but idle (#537).
     if (active && !unitTimeoutHandle && !wrapupWarningHandle) {
-      ctx.ui.notify(
-        "Auto-mode stalled — no dispatchable unit found after retry. Stopping. Run /gsd auto to restart.",
-        "warning",
-      );
-      await stopAuto(ctx, pi);
+      await stopAuto(ctx, pi, "Stalled — no dispatchable unit after retry");
     }
   }, DISPATCH_GAP_TIMEOUT_MS);
 }
 
-export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promise<void> {
+export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason?: string): Promise<void> {
   if (!active && !paused) return;
+  const reasonSuffix = reason ? ` — ${reason}` : "";
   clearUnitTimeout();
   if (lockBase()) clearLock(lockBase());
   clearSkillSnapshot();
@@ -626,11 +650,11 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   if (ledger && ledger.units.length > 0) {
     const totals = getProjectTotals(ledger.units);
     ctx?.ui.notify(
-      `Auto-mode stopped. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`,
+      `Auto-mode stopped${reasonSuffix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`,
       "info",
     );
   } else {
-    ctx?.ui.notify("Auto-mode stopped.", "info");
+    ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}.`, "info");
   }
 
   // Sync disk state so next resume starts from accurate state
@@ -1094,6 +1118,13 @@ export async function startAuto(
       }
       // Re-register SIGTERM handler with the original basePath (lock lives there)
       registerSigtermHandler(originalBasePath);
+
+      // After worktree entry, load completed keys from BOTH locations (project root
+      // + worktree) so the in-memory set is the union. Prevents re-dispatch of units
+      // completed in either location after crash/restart (#769).
+      if (basePath !== originalBasePath) {
+        loadPersistedKeys(basePath, completedKeySet);
+      }
     } catch (err) {
       // Worktree creation is non-fatal — continue in the project root.
       ctx.ui.notify(
@@ -1130,11 +1161,12 @@ export async function startAuto(
     }
   }
 
-  // Initialize metrics — loads existing ledger from disk
-  initMetrics(base);
+  // Initialize metrics — loads existing ledger from disk.
+  // Use basePath (not base) so worktree-mode reads the worktree ledger (#769).
+  initMetrics(basePath);
 
   // Initialize routing history for adaptive learning
-  initRoutingHistory(base);
+  initRoutingHistory(basePath);
 
   // Capture the session's current model at auto-mode start (#650).
   // This prevents model bleed when multiple GSD instances share the
@@ -1185,8 +1217,10 @@ export async function startAuto(
     );
   }
 
-  // Self-heal: clear stale runtime records where artifacts already exist
-  await selfHealRuntimeRecords(base, ctx, completedKeySet);
+  // Self-heal: clear stale runtime records where artifacts already exist.
+  // Use basePath (not base) — in worktree mode, basePath points to the worktree
+  // where runtime records and artifacts actually live (#769).
+  await selfHealRuntimeRecords(basePath, ctx, completedKeySet);
 
   // Self-heal: remove stale .git/index.lock from prior crash.
   // A stale lock file blocks all git operations (commit, merge, checkout).
@@ -1252,6 +1286,27 @@ export async function handleAgentEnd(
   // Unit completed — clear its timeout
   clearUnitTimeout();
 
+    // ── Parallel worker signal check ─────────────────────────────────────
+    // When running as a parallel worker (GSD_MILESTONE_LOCK set), check for
+    // coordinator signals before dispatching the next unit.
+    const milestoneLock = process.env.GSD_MILESTONE_LOCK;
+    if (milestoneLock) {
+      const signal = consumeSignal(basePath, milestoneLock);
+      if (signal) {
+        if (signal.signal === "stop") {
+          _handlingAgentEnd = false;
+          await stopAuto(ctx, pi);
+          return;
+        }
+        if (signal.signal === "pause") {
+          _handlingAgentEnd = false;
+          await pauseAuto(ctx, pi);
+          return;
+        }
+        // "resume" and "rebase" signals are handled elsewhere or no-op here
+      }
+    }
+
   // Invalidate all caches — the unit just completed and may have
   // written planning files (task summaries, roadmap checkboxes, etc.)
   invalidateAllCaches();
@@ -1485,7 +1540,7 @@ export async function handleAgentEnd(
       const result = await cmdCtx!.newSession();
       if (result.cancelled) {
         resetHookState();
-        await stopAuto(ctx, pi);
+        await stopAuto(ctx, pi, "Hook session cancelled");
         return;
       }
       const sessionFile = ctx.sessionManager.getSessionFile();
@@ -1783,7 +1838,15 @@ async function showStepWizard(
 
   // If no active milestone or everything is complete, stop
   if (!mid || state.phase === "complete") {
-    await stopAuto(ctx, pi);
+    const incomplete = state.registry.filter(m => m.status !== "complete");
+    if (incomplete.length > 0 && state.phase !== "complete" && state.phase !== "blocked") {
+      const ids = incomplete.map(m => m.id).join(", ");
+      const diag = `basePath=${basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
+      ctx.ui.notify(`Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`, "error");
+      await stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids})`);
+    } else {
+      await stopAuto(ctx, pi, state.phase === "complete" ? "All work complete" : "No active milestone");
+    }
     return;
   }
 
@@ -1906,8 +1969,7 @@ async function dispatchNextUnit(
   // doesn't provide. Stop gracefully instead of crashing.
   const staleMsg = checkResourcesStale();
   if (staleMsg) {
-    await stopAuto(ctx, pi);
-    ctx.ui.notify(staleMsg, "error");
+    await stopAuto(ctx, pi, staleMsg);
     return;
   }
 
@@ -2054,8 +2116,25 @@ async function dispatchNextUnit(
       snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId, { promptCharCount: lastPromptCharCount, baselineCharCount: lastBaselineCharCount, ...(currentUnitRouting ?? {}) });
       saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
     }
-    sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
-    await stopAuto(ctx, pi);
+
+    const incomplete = state.registry.filter(m => m.status !== "complete");
+    if (incomplete.length === 0) {
+      // Genuinely all complete
+      sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
+      await stopAuto(ctx, pi, "All milestones complete");
+    } else if (state.phase === "blocked") {
+      // Milestones exist but are dependency-blocked
+      const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+      await stopAuto(ctx, pi, blockerMsg);
+      ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+      sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+    } else {
+      // Milestones with remaining work exist but none became active — unexpected
+      const ids = incomplete.map(m => m.id).join(", ");
+      const diag = `basePath=${basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
+      ctx.ui.notify(`Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`, "error");
+      await stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids}), see diagnostic above`);
+    }
     return;
   }
 
@@ -2063,8 +2142,8 @@ async function dispatchNextUnit(
   // The !mid check above returns early if mid is falsy; midTitle comes from
   // the same object so it should always be present when mid is.
   if (!midTitle) {
-    await stopAuto(ctx, pi);
-    return;
+    midTitle = mid; // Defensive fallback: use milestone ID as title
+    ctx.ui.notify(`Milestone ${mid} has no title in roadmap — using ID as fallback.`, "warning");
   }
 
   // ── Mid-merge safety check: detect leftover merge state from a prior session ──
@@ -2082,7 +2161,10 @@ async function dispatchNextUnit(
       snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId, { promptCharCount: lastPromptCharCount, baselineCharCount: lastBaselineCharCount, ...(currentUnitRouting ?? {}) });
       saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
     }
-    await stopAuto(ctx, pi);
+    const noMilestoneReason = !mid
+      ? "No active milestone after merge reconciliation"
+      : `Milestone ${mid} has no title after reconciliation`;
+    await stopAuto(ctx, pi, noMilestoneReason);
     return;
   }
 
@@ -2157,7 +2239,7 @@ async function dispatchNextUnit(
       }
     }
     sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
-    await stopAuto(ctx, pi);
+    await stopAuto(ctx, pi, `Milestone ${mid} complete`);
     return;
   }
 
@@ -2167,8 +2249,8 @@ async function dispatchNextUnit(
       snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId, { promptCharCount: lastPromptCharCount, baselineCharCount: lastBaselineCharCount, ...(currentUnitRouting ?? {}) });
       saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
     }
-    await stopAuto(ctx, pi);
     const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+    await stopAuto(ctx, pi, blockerMsg);
     ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
     sendDesktopNotification("GSD", blockerMsg, "error", "attention");
     return;
@@ -2194,9 +2276,8 @@ async function dispatchNextUnit(
       const msg = `Budget ceiling ${formatCost(budgetCeiling)} reached (spent ${formatCost(totalCost)}).`;
       lastBudgetAlertLevel = newBudgetAlertLevel;
       if (budgetEnforcementAction === "halt") {
-        ctx.ui.notify(`${msg} Stopping auto-mode.`, "error");
         sendDesktopNotification("GSD", msg, "error", "budget");
-        await stopAuto(ctx, pi);
+        await stopAuto(ctx, pi, "Budget ceiling reached");
         return;
       }
       if (budgetEnforcementAction === "pause") {
@@ -2211,6 +2292,10 @@ async function dispatchNextUnit(
       lastBudgetAlertLevel = newBudgetAlertLevel;
       ctx.ui.notify(`Budget 90%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning");
       sendDesktopNotification("GSD", `Budget 90%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning", "budget");
+    } else if (newBudgetAlertLevel === 80) {
+      lastBudgetAlertLevel = newBudgetAlertLevel;
+      ctx.ui.notify(`Approaching budget ceiling — 80%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning");
+      sendDesktopNotification("GSD", `Approaching budget ceiling — 80%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning", "budget");
     } else if (newBudgetAlertLevel === 75) {
       lastBudgetAlertLevel = newBudgetAlertLevel;
       ctx.ui.notify(`Budget 75%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "info");
@@ -2275,8 +2360,7 @@ async function dispatchNextUnit(
       snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId, { promptCharCount: lastPromptCharCount, baselineCharCount: lastBaselineCharCount, ...(currentUnitRouting ?? {}) });
       saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
     }
-    await stopAuto(ctx, pi);
-    ctx.ui.notify(dispatchResult.reason, dispatchResult.level);
+    await stopAuto(ctx, pi, dispatchResult.reason);
     return;
   }
 
@@ -2316,8 +2400,7 @@ async function dispatchNextUnit(
 
   const priorSliceBlocker = getPriorSliceCompletionBlocker(basePath, getMainBranch(basePath), unitType, unitId);
   if (priorSliceBlocker) {
-    await stopAuto(ctx, pi);
-    ctx.ui.notify(priorSliceBlocker, "error");
+    await stopAuto(ctx, pi, priorSliceBlocker);
     return;
   }
 
@@ -2434,9 +2517,9 @@ async function dispatchNextUnit(
     }
     saveActivityLog(ctx, basePath, unitType, unitId);
     const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
-    await stopAuto(ctx, pi);
+    await stopAuto(ctx, pi, `Hard loop: ${unitType} ${unitId}`);
     ctx.ui.notify(
-      `Hard loop detected: ${unitType} ${unitId} dispatched ${lifetimeCount} times total (across reconciliation cycles). Stopping.${expected ? `\n   Expected artifact: ${expected}` : ""}\n   This may indicate deriveState() keeps returning the same unit despite artifacts existing.\n   Check .gsd/completed-units.json and the slice plan checkbox state.`,
+      `Hard loop detected: ${unitType} ${unitId} dispatched ${lifetimeCount} times total (across reconciliation cycles).${expected ? `\n   Expected artifact: ${expected}` : ""}\n   This may indicate deriveState() keeps returning the same unit despite artifacts existing.\n   Check .gsd/completed-units.json and the slice plan checkbox state.`,
       "error",
     );
     return;
@@ -2529,7 +2612,7 @@ async function dispatchNextUnit(
 
     const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
     const remediation = buildLoopRemediationSteps(unitType, unitId, basePath);
-    await stopAuto(ctx, pi);
+    await stopAuto(ctx, pi, `Loop: ${unitType} ${unitId}`);
     sendDesktopNotification("GSD", `Loop detected: ${unitType} ${unitId}`, "error", "error");
     ctx.ui.notify(
       `Loop detected: ${unitType} ${unitId} dispatched ${prevCount + 1} times total. Expected artifact not found.${expected ? `\n   Expected: ${expected}` : ""}${remediation ? `\n\n   Remediation steps:\n${remediation}` : "\n   Check branch state and .gsd/ artifacts."}`,
@@ -2670,8 +2753,7 @@ async function dispatchNextUnit(
   // Fresh session
   const result = await cmdCtx!.newSession();
   if (result.cancelled) {
-    await stopAuto(ctx, pi);
-    ctx.ui.notify("Auto-mode stopped.", "info");
+    await stopAuto(ctx, pi, "Session cancelled");
     return;
   }
 

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