gsd-pi 2.32.0 → 2.33.0-dev.bafba33

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

@@ -105,6 +105,7 @@ import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.j
 import { GSDError, GSD_ARTIFACT_MISSING } from "./errors.js";
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync, statSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
@@ -189,6 +190,7 @@ import {
   NEW_SESSION_TIMEOUT_MS, DISPATCH_HANG_TIMEOUT_MS,
 } from "./auto/session.js";
 import type { CompletedUnit, CurrentUnit, UnitRouting, StartModel, PendingVerificationRetry } from "./auto/session.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -213,52 +215,7 @@ export function shouldUseWorktreeIsolation(): boolean {
   return true; // default: worktree
 }
 
-/** Crash recovery prompt — set by startAuto, consumed by first dispatchNextUnit */
-
-/** Pending verification retry — set when gate fails with retries remaining, consumed by dispatchNextUnit */
-
-/** Verification retry count per unitId — separate from s.unitDispatchCount which tracks artifact-missing retries */
-
-/** Session file path captured at pause — used to synthesize recovery briefing on resume */
-
-/** Dashboard tracking */
-
-/** Track dynamic routing decision for the current unit (for metrics) */
-
-/** Queue of quick-task captures awaiting dispatch after triage resolution */
-
-/**
- * Model captured at auto-mode start. Used to prevent model bleed between
- * concurrent GSD instances sharing the same global settings.json (#650).
- * When preferences don't specify a model for a unit type, this ensures
- * the session's original model is re-applied instead of reading from
- * the shared global settings (which another instance may have overwritten).
- */
-
-/** Track current milestone to detect transitions */
-
-/** Model the user had selected before auto-mode started */
-
-/** Progress-aware timeout supervision */
-
-/** Context-pressure continue-here monitor — fires once when context usage >= 70% */
-
-/** Dispatch gap watchdog — detects when the state machine stalls between units.
- *  After handleAgentEnd completes, if auto-mode is still active but no new unit
- *  has been dispatched (sendMessage not called), this timer fires to force a
- *  re-evaluation. Covers the case where dispatchNextUnit silently fails or
- *  an unhandled error kills the dispatch chain. */
-
-/** Prompt character measurement for token savings analysis (R051). */
-
-/** SIGTERM handler registered while auto-mode is active — cleared on stop/pause. */
-
-/**
- * Tool calls currently being executed — prevents false idle detection during long-running tools.
- * Maps toolCallId → start timestamp (ms) so the idle watchdog can detect tools that have been
- * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
- */
-
+// All mutable state lives in AutoSession (auto/session.ts) — see encapsulation invariant above.
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
   s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
@@ -404,6 +361,79 @@ function buildSnapshotOpts(unitType: string, unitId: string): { continueHereFire
   };
 }
 
+// ─── Extracted Merge Helper ───────────────────────────────────────────────
+
+/**
+ * Attempt to merge the current milestone branch to main.
+ * Handles both worktree and branch isolation modes with a single code path.
+ * Returns true if merge succeeded, false on error (non-fatal, logged).
+ *
+ * Extracted from 4 duplicate merge blocks in dispatchNextUnit to eliminate
+ * the bug factory where fixing one copy didn't fix the others (#1308).
+ */
+function tryMergeMilestone(ctx: ExtensionContext, milestoneId: string, mode: "transition" | "complete"): boolean {
+  const isolationMode = getIsolationMode();
+
+  // Worktree merge path
+  if (isInAutoWorktree(s.basePath) && s.originalBasePath) {
+    try {
+      const roadmapPath = resolveMilestoneFile(s.originalBasePath, milestoneId, "ROADMAP");
+      if (!roadmapPath) {
+        teardownAutoWorktree(s.originalBasePath, milestoneId);
+        ctx.ui.notify(`Exited worktree for ${milestoneId} (no roadmap for merge).`, "info");
+        return false;
+      }
+      const roadmapContent = readFileSync(roadmapPath, "utf-8");
+      const mergeResult = mergeMilestoneToMain(s.originalBasePath, milestoneId, roadmapContent);
+      s.basePath = s.originalBasePath;
+      s.gitService = createGitService(s.basePath);
+      ctx.ui.notify(
+        `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
+        "info",
+      );
+      return true;
+    } catch (err) {
+      ctx.ui.notify(
+        `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+      if (s.originalBasePath) {
+        s.basePath = s.originalBasePath;
+        try { process.chdir(s.basePath); } catch { /* best-effort */ }
+      }
+      return false;
+    }
+  }
+
+  // Branch-mode merge path
+  if (isolationMode === "branch") {
+    try {
+      const currentBranch = getCurrentBranch(s.basePath);
+      const milestoneBranch = autoWorktreeBranch(milestoneId);
+      if (currentBranch === milestoneBranch) {
+        const roadmapPath = resolveMilestoneFile(s.basePath, milestoneId, "ROADMAP");
+        if (roadmapPath) {
+          const roadmapContent = readFileSync(roadmapPath, "utf-8");
+          const mergeResult = mergeMilestoneToMain(s.basePath, milestoneId, roadmapContent);
+          s.gitService = createGitService(s.basePath);
+          ctx.ui.notify(
+            `Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
+            "info",
+          );
+          return true;
+        }
+      }
+    } catch (err) {
+      ctx.ui.notify(
+        `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+    }
+  }
+
+  return false;
+}
+
 /**
  * Start a watchdog that fires if no new unit is dispatched within DISPATCH_GAP_TIMEOUT_MS
  * after handleAgentEnd completes. This catches the case where the dispatch chain silently
@@ -428,7 +458,7 @@ function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void
     try {
       await dispatchNextUnit(ctx, pi);
     } catch (retryErr) {
-      const message = retryErr instanceof Error ? retryErr.message : String(retryErr);
+      const message = getErrorMessage(retryErr);
       await stopAuto(ctx, pi, `Dispatch gap recovery failed: ${message}`);
       return;
     }
@@ -458,14 +488,14 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   // ── Auto-worktree: exit worktree and reset s.basePath on stop ──
   if (s.currentMilestoneId && isInAutoWorktree(s.basePath)) {
     try {
-      try { autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId); } catch (e) { debugLog("stop-auto-commit-failed", { error: e instanceof Error ? e.message : String(e) }); }
+      try { autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId); } catch (e) { debugLog("stop-auto-commit-failed", { error: getErrorMessage(e) }); }
       teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId, { preserveBranch: true });
       s.basePath = s.originalBasePath;
       s.gitService = createGitService(s.basePath);
       ctx?.ui.notify("Exited auto-worktree (branch preserved for resume).", "info");
     } catch (err) {
       ctx?.ui.notify(
-        `Auto-worktree teardown failed: ${err instanceof Error ? err.message : String(err)}`,
+        `Auto-worktree teardown failed: ${getErrorMessage(err)}`,
         "warning",
       );
     }
@@ -476,7 +506,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
     try {
       const { closeDatabase } = await import("./gsd-db.js");
       closeDatabase();
-    } catch (e) { debugLog("db-close-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("db-close-failed", { error: getErrorMessage(e) }); }
   }
 
   if (s.originalBasePath) {
@@ -496,7 +526,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   }
 
   if (s.basePath) {
-    try { await rebuildState(s.basePath); } catch (e) { debugLog("stop-rebuild-state-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    try { await rebuildState(s.basePath); } catch (e) { debugLog("stop-rebuild-state-failed", { error: getErrorMessage(e) }); }
   }
 
   if (isDebugEnabled()) {
@@ -635,7 +665,7 @@ export async function startAuto(
         }
       } catch (err) {
         ctx.ui.notify(
-          `Auto-worktree re-entry failed: ${err instanceof Error ? err.message : String(err)}. Continuing at current path.`,
+          `Auto-worktree re-entry failed: ${getErrorMessage(err)}. Continuing at current path.`,
           "warning",
         );
       }
@@ -647,13 +677,13 @@ export async function startAuto(
     ctx.ui.setFooter(hideFooter);
     ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
     restoreHookState(s.basePath);
-    try { await rebuildState(s.basePath); } catch (e) { debugLog("resume-rebuild-state-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    try { await rebuildState(s.basePath); } catch (e) { debugLog("resume-rebuild-state-failed", { error: getErrorMessage(e) }); }
     try {
       const report = await runGSDDoctor(s.basePath, { fix: true });
       if (report.fixesApplied.length > 0) {
         ctx.ui.notify(`Resume: applied ${report.fixesApplied.length} fix(es) to state.`, "info");
       }
-    } catch (e) { debugLog("resume-doctor-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("resume-doctor-failed", { error: getErrorMessage(e) }); }
     await selfHealRuntimeRecords(s.basePath, ctx, s.completedKeySet);
     invalidateAllCaches();
 
@@ -700,7 +730,7 @@ export async function startAuto(
         }
       } catch (err) {
         ctx.ui.notify(
-          `Secrets check error: ${err instanceof Error ? err.message : String(err)}. Continuing without secrets.`,
+          `Secrets check error: ${getErrorMessage(err)}. Continuing without secrets.`,
           "warning",
         );
       }
@@ -807,7 +837,7 @@ export async function handleAgentEnd(
   try {
     await dispatchNextUnit(ctx, pi);
   } catch (dispatchErr) {
-    const message = dispatchErr instanceof Error ? dispatchErr.message : String(dispatchErr);
+    const message = getErrorMessage(dispatchErr);
     ctx.ui.notify(
       `Dispatch error after unit completion: ${message}. Retrying in ${DISPATCH_GAP_TIMEOUT_MS / 1000}s.`,
       "error",
@@ -838,7 +868,7 @@ export async function handleAgentEnd(
       clearDispatchGapWatchdog();
       setImmediate(() => {
         handleAgentEnd(ctx, pi).catch((err) => {
-          const msg = err instanceof Error ? err.message : String(err);
+          const msg = getErrorMessage(err);
           ctx.ui.notify(`Deferred agent_end retry failed: ${msg}`, "error");
           pauseAuto(ctx, pi).catch(() => {});
         });
@@ -1086,7 +1116,7 @@ async function dispatchNextUnit(
         );
       } catch (err) {
         ctx.ui.notify(
-          `Report generation failed: ${err instanceof Error ? err.message : String(err)}`,
+          `Report generation failed: ${getErrorMessage(err)}`,
           "warning",
         );
       }
@@ -1102,35 +1132,17 @@ async function dispatchNextUnit(
         atomicWriteSync(file, JSON.stringify([]));
       }
       s.completedKeySet.clear();
-    } catch (e) { debugLog("completed-keys-reset-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
 
     // ── Worktree lifecycle on milestone transition (#616) ──
-    if (isInAutoWorktree(s.basePath) && s.originalBasePath && shouldUseWorktreeIsolation()) {
-      try {
-        const roadmapPath = resolveMilestoneFile(s.originalBasePath, s.currentMilestoneId, "ROADMAP");
-        if (roadmapPath) {
-          const roadmapContent = readFileSync(roadmapPath, "utf-8");
-          const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
-          ctx.ui.notify(
-            `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-            "info",
-          );
-        } else {
-          teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId);
-          ctx.ui.notify(`Exited worktree for ${ s.currentMilestoneId } (no roadmap for merge).`, "info");
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Milestone merge failed during transition: ${err instanceof Error ? err.message : String(err)}`,
-          "warning",
-        );
-        if (s.originalBasePath) {
-          try { process.chdir(s.originalBasePath); } catch { /* best-effort */ }
-        }
-      }
+    if ((isInAutoWorktree(s.basePath) || getIsolationMode() === "branch") && shouldUseWorktreeIsolation()) {
+      tryMergeMilestone(ctx, s.currentMilestoneId, "transition");
 
-      s.basePath = s.originalBasePath;
-      s.gitService = createGitService(s.basePath);
+      // Reset to project root and re-derive state for the new milestone
+      if (s.originalBasePath) {
+        s.basePath = s.originalBasePath;
+        s.gitService = createGitService(s.basePath);
+      }
       invalidateAllCaches();
 
       state = await deriveState(s.basePath);
@@ -1146,7 +1158,7 @@ async function dispatchNextUnit(
           ctx.ui.notify(`Created auto-worktree for ${mid} at ${wtPath}`, "info");
         } catch (err) {
           ctx.ui.notify(
-            `Auto-worktree creation for ${mid} failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
+            `Auto-worktree creation for ${mid} failed: ${getErrorMessage(err)}. Continuing in project root.`,
             "warning",
           );
         }
@@ -1175,51 +1187,8 @@ async function dispatchNextUnit(
     const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
     if (incomplete.length === 0) {
       // Genuinely all complete (parked milestones excluded) — merge milestone branch to main before stopping (#962)
-      if (s.currentMilestoneId && isInAutoWorktree(s.basePath) && s.originalBasePath) {
-        try {
-          const roadmapPath = resolveMilestoneFile(s.originalBasePath, s.currentMilestoneId, "ROADMAP");
-          if (roadmapPath) {
-            const roadmapContent = readFileSync(roadmapPath, "utf-8");
-            const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
-            s.basePath = s.originalBasePath;
-            s.gitService = createGitService(s.basePath);
-            ctx.ui.notify(
-              `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-              "info",
-            );
-          }
-        } catch (err) {
-          ctx.ui.notify(
-            `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
-            "warning",
-          );
-          if (s.originalBasePath) {
-            s.basePath = s.originalBasePath;
-            try { process.chdir(s.basePath); } catch { /* best-effort */ }
-          }
-        }
-      } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() === "branch") {
-        try {
-          const currentBranch = getCurrentBranch(s.basePath);
-          const milestoneBranch = autoWorktreeBranch(s.currentMilestoneId);
-          if (currentBranch === milestoneBranch) {
-            const roadmapPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "ROADMAP");
-            if (roadmapPath) {
-              const roadmapContent = readFileSync(roadmapPath, "utf-8");
-              const mergeResult = mergeMilestoneToMain(s.basePath, s.currentMilestoneId, roadmapContent);
-              s.gitService = createGitService(s.basePath);
-              ctx.ui.notify(
-                `Milestone ${ s.currentMilestoneId } merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
-                "info",
-              );
-            }
-          }
-        } catch (err) {
-          ctx.ui.notify(
-            `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
-            "warning",
-          );
-        }
+      if (s.currentMilestoneId) {
+        tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
       }
       sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
       await stopAuto(ctx, pi, "All milestones complete");
@@ -1276,52 +1245,10 @@ async function dispatchNextUnit(
         atomicWriteSync(file, JSON.stringify([]));
       }
       s.completedKeySet.clear();
-    } catch (e) { debugLog("completed-keys-reset-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
     // ── Milestone merge ──
-    if (s.currentMilestoneId && isInAutoWorktree(s.basePath) && s.originalBasePath) {
-      try {
-        const roadmapPath = resolveMilestoneFile(s.originalBasePath, s.currentMilestoneId, "ROADMAP");
-        if (!roadmapPath) throw new GSDError(GSD_ARTIFACT_MISSING, `Cannot resolve ROADMAP file for milestone ${ s.currentMilestoneId }`);
-        const roadmapContent = readFileSync(roadmapPath, "utf-8");
-        const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
-        s.basePath = s.originalBasePath;
-        s.gitService = createGitService(s.basePath);
-        ctx.ui.notify(
-          `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
-          "info",
-        );
-      } catch (err) {
-        ctx.ui.notify(
-          `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
-          "warning",
-        );
-        if (s.originalBasePath) {
-          s.basePath = s.originalBasePath;
-          try { process.chdir(s.basePath); } catch { /* best-effort */ }
-        }
-      }
-    } else if (s.currentMilestoneId && !isInAutoWorktree(s.basePath) && getIsolationMode() === "branch") {
-      try {
-        const currentBranch = getCurrentBranch(s.basePath);
-        const milestoneBranch = autoWorktreeBranch(s.currentMilestoneId);
-        if (currentBranch === milestoneBranch) {
-          const roadmapPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "ROADMAP");
-          if (roadmapPath) {
-            const roadmapContent = readFileSync(roadmapPath, "utf-8");
-            const mergeResult = mergeMilestoneToMain(s.basePath, s.currentMilestoneId, roadmapContent);
-            s.gitService = createGitService(s.basePath);
-            ctx.ui.notify(
-              `Milestone ${ s.currentMilestoneId } merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
-              "info",
-            );
-          }
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
-          "warning",
-        );
-      }
+    if (s.currentMilestoneId) {
+      tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
     }
     sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
     await stopAuto(ctx, pi, `Milestone ${mid} complete`);
@@ -1417,7 +1344,7 @@ async function dispatchNextUnit(
       }
     } catch (err) {
       ctx.ui.notify(
-        `Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`,
+        `Secrets collection error: ${getErrorMessage(err)}. Continuing with next task.`,
         "warning",
       );
     }
@@ -1628,7 +1555,7 @@ async function dispatchNextUnit(
     );
     result = await Promise.race([sessionPromise, timeoutPromise]);
   } catch (sessionErr) {
-    const msg = sessionErr instanceof Error ? sessionErr.message : String(sessionErr);
+    const msg = getErrorMessage(sessionErr);
     ctx.ui.notify(`Session creation failed: ${msg}. Retrying via watchdog.`, "error");
     throw new Error(`newSession() failed: ${msg}`);
   }
@@ -1704,7 +1631,7 @@ async function dispatchNextUnit(
     const { reorderForCaching } = await import("./prompt-ordering.js");
     finalPrompt = reorderForCaching(finalPrompt);
   } catch (reorderErr) {
-    const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
+    const msg = getErrorMessage(reorderErr);
     process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
   }
 
@@ -1747,8 +1674,7 @@ async function dispatchNextUnit(
 function ensurePreconditions(
   unitType: string, unitId: string, base: string, state: GSDState,
 ): void {
-  const parts = unitId.split("/");
-  const mid = parts[0]!;
+  const { milestone: mid } = parseUnitId(unitId);
 
   const mDir = resolveMilestonePath(base, mid);
   if (!mDir) {
@@ -1756,8 +1682,8 @@ function ensurePreconditions(
     mkdirSync(join(newDir, "slices"), { recursive: true });
   }
 
-  if (parts.length >= 2) {
-    const sid = parts[1]!;
+  const sid = parseUnitId(unitId).slice;
+  if (sid) {
 
     const mDirResolved = resolveMilestonePath(base, mid);
     if (mDirResolved) {

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

@@ -5,6 +5,7 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { getErrorMessage } from "./error-utils.js";
 
 export interface InspectData {
   schemaVersion: number | null;
@@ -84,7 +85,7 @@ export async function handleInspect(ctx: ExtensionCommandContext): Promise<void>
 
     ctx.ui.notify(formatInspectOutput(data), "info");
   } catch (err) {
-    process.stderr.write(`gsd-db: /gsd inspect failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.stderr.write(`gsd-db: /gsd inspect failed: ${getErrorMessage(err)}\n`);
     ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error");
   }
 }

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -21,6 +21,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -439,7 +440,7 @@ export async function handleStart(
         branchCreated = true;
       }
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       ctx.ui.notify(
         `Could not create branch ${branchName}: ${message}. Working on current branch.`,
         "warning",

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

@@ -6,6 +6,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { getAdaptiveTierAdjustment } from "./routing-history.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -180,15 +181,14 @@ function analyzePlanComplexity(
   basePath: string,
 ): TaskAnalysis | null {
   // Check if this is a milestone-level plan (more complex) vs single slice
-  const parts = unitId.split("/");
-  if (parts.length === 1) {
+  const { milestone: mid, slice: sid } = parseUnitId(unitId);
+  if (!sid) {
     // Milestone-level planning is always at least standard
     return { tier: "standard", reason: "milestone-level planning" };
   }
 
   // For slice planning, try to read the context/research to gauge complexity
   // If research exists and is large, bump to heavy
-  const [mid, sid] = parts;
   const researchPath = join(gsdRoot(basePath), mid, "slices", sid, "RESEARCH.md");
   try {
     if (existsSync(researchPath)) {
@@ -210,10 +210,8 @@ function analyzePlanComplexity(
  */
 function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata {
   const meta: TaskMetadata = {};
-  const parts = unitId.split("/");
-  if (parts.length !== 3) return meta;
-
-  const [mid, sid, tid] = parts;
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+  if (!mid || !sid || !tid) return meta;
   const taskPlanPath = join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
 
   try {

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -98,11 +98,24 @@ export function isLockProcessAlive(lock: LockData): boolean {
 
 /** Format crash info for display or injection into a prompt. */
 export function formatCrashInfo(lock: LockData): string {
-  return [
+  const lines = [
     `Previous auto-mode session was interrupted.`,
     `  Was executing: ${lock.unitType} (${lock.unitId})`,
     `  Started at: ${lock.unitStartedAt}`,
     `  Units completed before crash: ${lock.completedUnits}`,
     `  PID: ${lock.pid}`,
-  ].join("\n");
+  ];
+
+  // Add recovery guidance based on what was happening when it crashed
+  if (lock.unitType === "starting" && lock.unitId === "bootstrap" && lock.completedUnits === 0) {
+    lines.push(`No work was lost. Run /gsd auto to restart.`);
+  } else if (lock.unitType.includes("research") || lock.unitType.includes("plan")) {
+    lines.push(`The ${lock.unitType} unit may be incomplete. Run /gsd auto to re-run it.`);
+  } else if (lock.unitType.includes("execute")) {
+    lines.push(`Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`);
+  } else if (lock.unitType.includes("complete")) {
+    lines.push(`Slice/milestone completion was interrupted. Run /gsd auto to finish.`);
+  }
+
+  return lines.join("\n");
 }

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -5,6 +5,7 @@ import { readdirSync } from "node:fs";
 import { resolveMilestoneFile, milestonesDir } from "./paths.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { findMilestoneIds } from "./guided-flow.js";
+import { parseUnitId } from "./unit-id.js";
 
 const SLICE_DISPATCH_TYPES = new Set([
   "research-slice",
@@ -39,7 +40,7 @@ function readRoadmapFromDisk(base: string, milestoneId: string): string | null {
 export function getPriorSliceCompletionBlocker(base: string, _mainBranch: string, unitType: string, unitId: string): string | null {
   if (!SLICE_DISPATCH_TYPES.has(unitType)) return null;
 
-  const [targetMid, targetSid] = unitId.split("/");
+  const { milestone: targetMid, slice: targetSid } = parseUnitId(unitId);
   if (!targetMid || !targetSid) return null;
 
   // Use findMilestoneIds to respect custom queue order.

package/src/resources/extensions/gsd/error-utils.ts

@@ -0,0 +1,6 @@
+/**
+ * Extract a human-readable message from an unknown caught value.
+ */
+export function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

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

@@ -12,6 +12,7 @@ import {
 import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/mod.js";
+import { getErrorMessage } from "./error-utils.js";
 
 /**
  * Open a file in the user's default browser.
@@ -226,7 +227,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
       }
     } catch (err) {
       ctx.ui.notify(
-        `HTML export failed: ${err instanceof Error ? err.message : String(err)}`,
+        `HTML export failed: ${getErrorMessage(err)}`,
         "error",
       );
     }

package/src/resources/extensions/gsd/git-service.ts

@@ -33,6 +33,7 @@ import {
   nativeAddPaths,
 } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -281,7 +282,7 @@ export function runGit(basePath: string, args: string[], options: { allowFailure
     }).trim();
   } catch (error) {
     if (options.allowFailure) return "";
-    const message = error instanceof Error ? error.message : String(error);
+    const message = getErrorMessage(error);
     throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}: ${filterGitSvnNoise(message)}`);
   }
 }
@@ -533,7 +534,7 @@ export class GitServiceImpl {
       execSync(command, { cwd: this.basePath, stdio: "pipe", encoding: "utf-8" });
       return { passed: true, skipped: false, command };
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = getErrorMessage(err);
       return { passed: false, skipped: false, command, error: msg };
     }
   }

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

@@ -44,6 +44,7 @@ export {
   showQueue, handleQueueReorder, showQueueAdd,
   buildExistingMilestonesContext,
 } from "./guided-flow-queue.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 
@@ -158,9 +159,9 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   pendingAutoStart = null;
   startAuto(ctx, pi, basePath, false, { step }).catch((err) => {
-    ctx.ui.notify(`Auto-start failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+    ctx.ui.notify(`Auto-start failed: ${getErrorMessage(err)}`, "error");
     if (process.env.GSD_DEBUG) console.error('[gsd] auto start error:', err);
-    debugLog("auto-start-failed", { error: err instanceof Error ? err.message : String(err) });
+    debugLog("auto-start-failed", { error: getErrorMessage(err) });
   });
   return true;
 }