gsd-pi 2.32.0 → 2.33.0-dev.69bff0f

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

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync, readdirSync, cpSync, lstatSync as lstatSyncFn } from "node:fs";
 import { isAbsolute, join, sep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -38,12 +38,129 @@ import {
   nativeBranchDelete,
   nativeBranchExists,
 } from "./native-git-bridge.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Module State ──────────────────────────────────────────────────────────
 
 /** Original project root before chdir into auto-worktree. */
 let originalBase: string | null = null;
 
+// ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
+
+/**
+ * Sync .gsd/ state from the main repo into the worktree.
+ *
+ * When .gsd/ is a symlink to the external state directory, both the main
+ * repo and worktree share the same directory — no sync needed.
+ *
+ * When .gsd/ is a real directory (e.g., git-tracked or manage_gitignore:false),
+ * the worktree has its own copy that may be stale. This function copies
+ * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
+ * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
+ *
+ * Only adds missing content — never overwrites existing files in the worktree
+ * (the worktree's execution state is authoritative for in-progress work).
+ */
+export function syncGsdStateToWorktree(mainBasePath: string, worktreePath_: string): { synced: string[] } {
+  const mainGsd = gsdRoot(mainBasePath);
+  const wtGsd = gsdRoot(worktreePath_);
+  const synced: string[] = [];
+
+  // If both resolve to the same directory (symlink), no sync needed
+  try {
+    const mainResolved = realpathSync(mainGsd);
+    const wtResolved = realpathSync(wtGsd);
+    if (mainResolved === wtResolved) return { synced };
+  } catch {
+    // Can't resolve — proceed with sync as a safety measure
+  }
+
+  if (!existsSync(mainGsd) || !existsSync(wtGsd)) return { synced };
+
+  // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE)
+  const rootFiles = ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md", "OVERRIDES.md"];
+  for (const f of rootFiles) {
+    const src = join(mainGsd, f);
+    const dst = join(wtGsd, f);
+    if (existsSync(src) && !existsSync(dst)) {
+      try {
+        cpSync(src, dst);
+        synced.push(f);
+      } catch { /* non-fatal */ }
+    }
+  }
+
+  // Sync milestones: copy entire milestone directories that are missing
+  const mainMilestonesDir = join(mainGsd, "milestones");
+  const wtMilestonesDir = join(wtGsd, "milestones");
+  if (existsSync(mainMilestonesDir) && existsSync(wtMilestonesDir)) {
+    try {
+      const mainMilestones = readdirSync(mainMilestonesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && /^M\d{3}/.test(d.name))
+        .map(d => d.name);
+
+      for (const mid of mainMilestones) {
+        const srcDir = join(mainMilestonesDir, mid);
+        const dstDir = join(wtMilestonesDir, mid);
+
+        if (!existsSync(dstDir)) {
+          // Entire milestone missing from worktree — copy it
+          try {
+            cpSync(srcDir, dstDir, { recursive: true });
+            synced.push(`milestones/${mid}/`);
+          } catch { /* non-fatal */ }
+        } else {
+          // Milestone directory exists but may be missing files (stale snapshot).
+          // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
+          try {
+            const srcFiles = readdirSync(srcDir).filter(f => f.endsWith(".md") || f.endsWith(".json"));
+            for (const f of srcFiles) {
+              const srcFile = join(srcDir, f);
+              const dstFile = join(dstDir, f);
+              if (!existsSync(dstFile)) {
+                try {
+                  const srcStat = lstatSyncFn(srcFile);
+                  if (srcStat.isFile()) {
+                    cpSync(srcFile, dstFile);
+                    synced.push(`milestones/${mid}/${f}`);
+                  }
+                } catch { /* non-fatal */ }
+              }
+            }
+
+            // Sync slices directory if it exists in main but not in worktree
+            const srcSlicesDir = join(srcDir, "slices");
+            const dstSlicesDir = join(dstDir, "slices");
+            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
+              try {
+                cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+                synced.push(`milestones/${mid}/slices/`);
+              } catch { /* non-fatal */ }
+            } else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
+              // Both exist — sync missing slice directories
+              const srcSlices = readdirSync(srcSlicesDir, { withFileTypes: true })
+                .filter(d => d.isDirectory())
+                .map(d => d.name);
+              for (const sid of srcSlices) {
+                const srcSlice = join(srcSlicesDir, sid);
+                const dstSlice = join(dstSlicesDir, sid);
+                if (!existsSync(dstSlice)) {
+                  try {
+                    cpSync(srcSlice, dstSlice, { recursive: true });
+                    synced.push(`milestones/${mid}/slices/${sid}/`);
+                  } catch { /* non-fatal */ }
+                }
+              }
+            }
+          } catch { /* non-fatal */ }
+        }
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  return { synced };
+}
+
 // ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
 
 /**
@@ -81,7 +198,7 @@ export function runWorktreePostCreateHook(sourceDir: string, worktreeDir: string
     });
     return null;
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = getErrorMessage(err);
     return `Worktree post-create hook failed: ${msg}`;
   }
 }
@@ -124,6 +241,12 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
   // Ensure worktree shares external state via symlink
   ensureGsdSymlink(info.path);
 
+  // Sync .gsd/ state from main repo into the worktree (#1311).
+  // Even with the symlink, the worktree may have stale git-tracked files
+  // if .gsd/ is not gitignored. And on fresh create, the milestone files
+  // created on main since the branch point won't be in the worktree.
+  syncGsdStateToWorktree(basePath, info.path);
+
   // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets
   const hookError = runWorktreePostCreateHook(basePath, info.path);
   if (hookError) {
@@ -141,7 +264,7 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
     // Don't store originalBase -- caller can retry or clean up.
     throw new GSDError(
       GSD_IO_ERROR,
-      `Auto-worktree created at ${info.path} but chdir failed: ${err instanceof Error ? err.message : String(err)}`,
+      `Auto-worktree created at ${info.path} but chdir failed: ${getErrorMessage(err)}`,
     );
   }
 
@@ -168,7 +291,7 @@ export function teardownAutoWorktree(
   } catch (err) {
     throw new GSDError(
       GSD_IO_ERROR,
-      `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`,
+      `Failed to chdir back to ${originalBasePath} during teardown: ${getErrorMessage(err)}`,
     );
   }
 
@@ -266,6 +389,18 @@ export function enterAutoWorktree(basePath: string, milestoneId: string): string
     throw new GSDError(GSD_IO_ERROR, `Auto-worktree path ${p} exists but .git is unreadable`);
   }
 
+  // Ensure worktree shares external state via symlink (#1311).
+  // On resume (enterAutoWorktree), the symlink may be missing if it was
+  // created before ensureGsdSymlink existed, or the .gsd/ directory may be
+  // a stale git-tracked copy instead of a symlink. Refreshing here ensures
+  // the worktree sees the same milestone state as the main repo.
+  ensureGsdSymlink(p);
+
+  // Sync .gsd/ state from main repo into worktree (#1311).
+  // Covers the case where .gsd/ is a real directory (not symlinked) and
+  // milestones were created on main after the worktree was last used.
+  syncGsdStateToWorktree(basePath, p);
+
   const previousCwd = process.cwd();
 
   try {
@@ -274,7 +409,7 @@ export function enterAutoWorktree(basePath: string, milestoneId: string): string
   } catch (err) {
     throw new GSDError(
       GSD_IO_ERROR,
-      `Failed to enter auto-worktree at ${p}: ${err instanceof Error ? err.message : String(err)}`,
+      `Failed to enter auto-worktree at ${p}: ${getErrorMessage(err)}`,
     );
   }
 

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) {