gsd-pi 2.80.0-dev.c5f2443b3 → 2.80.0-dev.d4fc28e6b

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -112,8 +112,22 @@ const CONTEXT_MODE_LANE_LABELS: Record<Exclude<ContextModePolicy, "none">, strin
   docs: "documentation",
 };
 
-const CONTEXT_MODE_GUIDANCE =
-  "Use `gsd_exec` for noisy commands, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.";
+const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">, string> = {
+  interview:
+    "Use `gsd_resume` to restore prior discussion, `gsd_exec` for noisy discovery, and `gsd_exec_search` before repeating scans.",
+  research:
+    "Use `gsd_exec` for noisy research scans, `gsd_exec_search` before reruns, and `gsd_resume` to restore prior findings.",
+  planning:
+    "Use `gsd_resume` for planning continuity, `gsd_exec` for noisy checks, and `gsd_exec_search` before rerunning diagnostics.",
+  execution:
+    "Use `gsd_exec` for builds, tests, and diagnostics, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.",
+  verification:
+    "Use `gsd_exec` for verification commands, `gsd_exec_search` to reuse prior evidence, and `gsd_resume` after compaction or resume.",
+  orchestration:
+    "Use `gsd_resume` before resuming orchestration, `gsd_exec_search` to reuse prior runs, and `gsd_exec` for noisy coordination checks.",
+  docs:
+    "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
+};
 
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
@@ -129,15 +143,16 @@ export function composeContextModeInstructions(
   if (!manifest || manifest.contextMode === "none") return "";
 
   const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
+  const guidance = CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
-    return `Context Mode (${lane} lane): ${CONTEXT_MODE_GUIDANCE}`;
+    return `Context Mode (${lane} lane): ${guidance}`;
   }
 
   return [
     "## Context Mode",
     "",
     `Lane: **${lane} lane**.`,
-    CONTEXT_MODE_GUIDANCE,
+    guidance,
   ].join("\n");
 }
 

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -10,6 +10,8 @@ import {
 } from "./paths.js";
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseUnitId } from "./unit-id.js";
+import { getTask, isDbAvailable, refreshOpenDatabaseFromDisk } from "./gsd-db.js";
+import { isClosedStatus } from "./status-guards.js";
 
 // Per-record advisory lock — prevents read-modify-write races between
 // concurrent writers updating disjoint fields of the same runtime record.
@@ -67,17 +69,32 @@ export type UnitRuntimePhase =
   | "wrapup-warning-sent"
   | "timeout"
   | "finalize-timeout"
+  | "crashed"
   | "recovered"
   | "finalized"
   | "paused"
   | "skipped";
 
+export const IN_FLIGHT_RUNTIME_PHASES: ReadonlySet<UnitRuntimePhase> = new Set([
+  "dispatched",
+  "wrapup-warning-sent",
+  "timeout",
+  "finalize-timeout",
+  "crashed",
+  "paused",
+]);
+
+export function isInFlightRuntimePhase(phase: UnitRuntimePhase): boolean {
+  return IN_FLIGHT_RUNTIME_PHASES.has(phase);
+}
+
 export interface ExecuteTaskRecoveryStatus {
   planPath: string;
   summaryPath: string;
   summaryExists: boolean;
   taskChecked: boolean;
   nextActionAdvanced: boolean;
+  dbComplete: boolean;
   mustHaveCount: number;
   mustHavesMentionedInSummary: number;
 }
@@ -199,6 +216,12 @@ export async function inspectExecuteTaskDurability(
   const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const taskChecked = !!planContent && new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m").test(planContent);
   const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
+  let dbComplete = false;
+  if (isDbAvailable()) {
+    refreshOpenDatabaseFromDisk();
+    const task = getTask(mid, sid, tid);
+    dbComplete = !!task && isClosedStatus(task.status);
+  }
 
   // Must-have coverage: load task plan and count mentions in summary
   let mustHaveCount = 0;
@@ -225,12 +248,14 @@ export async function inspectExecuteTaskDurability(
     summaryExists,
     taskChecked,
     nextActionAdvanced,
+    dbComplete,
     mustHaveCount,
     mustHavesMentionedInSummary,
   };
 }
 
 export function formatExecuteTaskRecoveryStatus(status: ExecuteTaskRecoveryStatus): string {
+  if (status.dbComplete) return "DB task status is closed";
   const missing = [] as string[];
   if (!status.summaryExists) missing.push(`summary missing (${status.summaryPath})`);
   if (!status.taskChecked) missing.push(`task checkbox unchecked in ${status.planPath}`);

package/src/resources/extensions/gsd/workflow-protocol.ts

@@ -0,0 +1,160 @@
+// Project/App: GSD-2
+// File Purpose: Shared capped workflow protocol and doctor-heal prompt payload helpers.
+
+const DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS = 4_000;
+const MIN_WORKFLOW_PROTOCOL_EXCERPT_CHARS = 1_000;
+const DEFAULT_DOCTOR_SUMMARY_CHARS = 2_400;
+const DEFAULT_DOCTOR_ISSUE_CHARS = 300;
+const DEFAULT_DOCTOR_MAX_ISSUES = 12;
+const DEFAULT_DOCTOR_ISSUES_CHARS = 4_000;
+
+export function buildWorkflowProtocolExcerpt(
+  workflow: string,
+  workflowPath: string,
+  opts: { maxChars?: number } = {},
+): string {
+  const limit = opts.maxChars ?? getWorkflowProtocolExcerptLimit();
+  const trimmed = workflow.trim();
+  const excerpt = buildPrioritizedWorkflowExcerpt(trimmed, limit);
+  const truncated = trimmed.length > limit;
+  const lines = [
+    "## GSD Workflow Protocol Excerpt",
+    `Source: \`${workflowPath}\``,
+    "",
+    excerpt,
+  ];
+  if (truncated) {
+    lines.push(
+      "",
+      "[Workflow Protocol Truncated]",
+      "The full workflow protocol remains available at the source path above. Read it only if this excerpt lacks a rule required for the dispatched task.",
+    );
+  }
+  return lines.join("\n");
+}
+
+export function buildWorkflowDispatchContent(opts: {
+  workflow: string;
+  workflowPath: string;
+  task: string;
+  maxProtocolChars?: number;
+}): string {
+  return [
+    "Read the following GSD workflow protocol excerpt and execute exactly. Use the source path for a full protocol read only if the excerpt lacks a required rule.",
+    "",
+    buildWorkflowProtocolExcerpt(opts.workflow, opts.workflowPath, { maxChars: opts.maxProtocolChars }),
+    "",
+    "## Your Task",
+    "",
+    opts.task.trim(),
+  ].join("\n");
+}
+
+export function buildDoctorHealSummary(reportText: string, opts: { maxChars?: number } = {}): string {
+  const limit = opts.maxChars ?? DEFAULT_DOCTOR_SUMMARY_CHARS;
+  const lines = reportText.split(/\r?\n/).map((line) => line.trimEnd());
+  const summaryLines = lines.filter((line) =>
+    line.length > 0 && (
+      /^#/.test(line) ||
+      /^(scope|status|summary|checks?|errors?|warnings?|fixes?|issues?)\b/i.test(line) ||
+      /doctor/i.test(line)
+    ),
+  );
+  const selected = summaryLines.length > 0 ? summaryLines : lines.filter((line) => line.trim()).slice(0, 24);
+  return capText(selected.join("\n"), limit, "Full doctor report is available in the command output; use the structured issue list below for repairs.");
+}
+
+export function buildDoctorHealIssuePayload(
+  structuredIssues: string,
+  opts: { maxIssues?: number; maxIssueChars?: number; maxChars?: number } = {},
+): string {
+  const maxIssues = opts.maxIssues ?? DEFAULT_DOCTOR_MAX_ISSUES;
+  const maxIssueChars = opts.maxIssueChars ?? DEFAULT_DOCTOR_ISSUE_CHARS;
+  const maxChars = opts.maxChars ?? DEFAULT_DOCTOR_ISSUES_CHARS;
+  const blocks = splitIssueBlocks(structuredIssues);
+  const topBlocks = blocks.slice(0, maxIssues).map((block) =>
+    capText(block, maxIssueChars, "Issue details truncated; inspect the relevant artifact before editing."),
+  );
+  if (blocks.length > maxIssues) {
+    topBlocks.push(`[${blocks.length - maxIssues} additional actionable issue(s) omitted from prompt. Re-run /gsd doctor heal after this repair pass.]`);
+  }
+  return capText(topBlocks.join("\n\n"), maxChars, "Structured issue list truncated; repair top actionable issues first and re-run doctor heal.");
+}
+
+function getWorkflowProtocolExcerptLimit(): number {
+  const raw = process.env.PI_GSD_WORKFLOW_PROTOCOL_MAX_CHARS;
+  if (!raw) return DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < MIN_WORKFLOW_PROTOCOL_EXCERPT_CHARS) {
+    return DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS;
+  }
+  return Math.floor(parsed);
+}
+
+function buildPrioritizedWorkflowExcerpt(workflow: string, limit: number): string {
+  if (workflow.length <= limit) return workflow;
+  const sections = splitMarkdownSections(workflow);
+  const wanted = [
+    /^# /,
+    /^## Quick Start\b/i,
+    /^## The Hierarchy\b/i,
+    /^## The Phases\b/i,
+    /^### Phase 4: Execute\b/i,
+    /^### Phase 5: Verify\b/i,
+    /^### Observable Truths\b/i,
+    /^### Artifacts\b/i,
+    /^### Key Links\b/i,
+    /^### Phase 6: Summarize\b/i,
+    /^### Phase 7: Advance\b/i,
+  ];
+  const selected: string[] = [];
+  const used = new Set<number>();
+  for (const pattern of wanted) {
+    const index = sections.findIndex((section, sectionIndex) =>
+      !used.has(sectionIndex) && pattern.test(section.heading),
+    );
+    if (index >= 0) {
+      used.add(index);
+      selected.push(sections[index].text);
+    }
+  }
+  const body = selected.length > 0 ? selected.join("\n\n") : workflow;
+  return capText(body, limit, "Workflow protocol excerpt capped; read the source path for omitted details.");
+}
+
+function splitMarkdownSections(markdown: string): Array<{ heading: string; text: string }> {
+  const lines = markdown.split(/\r?\n/);
+  const sections: Array<{ heading: string; text: string }> = [];
+  let currentHeading = lines[0]?.startsWith("#") ? lines[0] : "# Preamble";
+  let current: string[] = [];
+  for (const line of lines) {
+    if (/^#{1,3}\s+/.test(line) && current.length > 0) {
+      sections.push({ heading: currentHeading, text: current.join("\n").trim() });
+      currentHeading = line;
+      current = [line];
+      continue;
+    }
+    if (/^#{1,3}\s+/.test(line)) currentHeading = line;
+    current.push(line);
+  }
+  if (current.length > 0) {
+    sections.push({ heading: currentHeading, text: current.join("\n").trim() });
+  }
+  return sections.filter((section) => section.text.length > 0);
+}
+
+function splitIssueBlocks(structuredIssues: string): string[] {
+  const trimmed = structuredIssues.trim();
+  if (!trimmed) return ["No structured issue details were provided."];
+  const split = trimmed.split(/\n(?=(?:#{2,6}\s+|\d+\.\s+|- \*\*|- \[[ x]\]))/i)
+    .map((block) => block.trim())
+    .filter(Boolean);
+  return split.length > 0 ? split : [trimmed];
+}
+
+function capText(text: string, limit: number, notice: string): string {
+  if (text.length <= limit) return text;
+  const suffix = `\n\n[Truncated]\n${notice}`;
+  const headBudget = Math.max(0, limit - suffix.length);
+  return `${text.slice(0, headBudget).trimEnd()}${suffix}`;
+}

package/src/resources/extensions/gsd/working-output-messages.ts

@@ -0,0 +1,120 @@
+// GSD-2 + src/resources/extensions/gsd/working-output-messages.ts - Formats and audits user-facing working-state messages.
+
+export type WorkingOutputSurface =
+  | "loader"
+  | "dashboard"
+  | "status"
+  | "notification"
+  | "assistant"
+  | "tool";
+
+export type WorkingHealthState =
+  | "healthy"
+  | "waiting"
+  | "recovering"
+  | "stalled"
+  | "provider-error"
+  | "timeout"
+  | "stopped";
+
+export interface WorkingOutputContext {
+  unitType?: string;
+  unitId?: string;
+  health?: WorkingHealthState;
+  elapsedMs?: number;
+  recoveryAttempts?: number;
+}
+
+export interface WorkingOutputMessage {
+  surface: WorkingOutputSurface;
+  message: string;
+  context?: WorkingOutputContext;
+}
+
+export interface WorkingOutputFinding {
+  code:
+    | "empty-message"
+    | "generic-working-message"
+    | "misleading-healthy-message"
+    | "fake-zero-progress"
+    | "missing-action";
+  severity: "error" | "warning";
+  detail: string;
+}
+
+const ACTION_RE = /\b(?:wait|pause|paused|retry|retrying|recover|recovering|resume|stop|stopped|run|press|type|configure|restart)\b/i;
+
+export function formatAutoUnitWorkingMessage(unitType: string, unitId: string): string {
+  switch (unitType) {
+    case "research-milestone":
+    case "research-slice":
+      return `Researching ${unitId}: waiting for provider response`;
+    case "plan-milestone":
+    case "plan-slice":
+      return `Planning ${unitId}: waiting for provider response`;
+    case "execute-task":
+      return `Executing ${unitId}: waiting for provider response`;
+    case "complete-slice":
+    case "complete-milestone":
+      return `Completing ${unitId}: waiting for provider response`;
+    default:
+      return `${unitType} ${unitId}: waiting for provider response`;
+  }
+}
+
+export function evaluateWorkingOutputMessage(
+  item: WorkingOutputMessage,
+): WorkingOutputFinding[] {
+  const findings: WorkingOutputFinding[] = [];
+  const message = item.message.trim();
+  const health = item.context?.health;
+
+  if (!message) {
+    findings.push({
+      code: "empty-message",
+      severity: "error",
+      detail: `${item.surface} message is empty`,
+    });
+    return findings;
+  }
+
+  if (/^Working(?:\.\.\.)?(?:\s|\(|$)/i.test(message)) {
+    findings.push({
+      code: "generic-working-message",
+      severity: "warning",
+      detail: `${item.surface} message should say what work is running`,
+    });
+  }
+
+  if (/Progressing well/i.test(message) && health && health !== "healthy") {
+    findings.push({
+      code: "misleading-healthy-message",
+      severity: "error",
+      detail: `${item.surface} says progress is healthy while runtime health is ${health}`,
+    });
+  }
+
+  if (/\b0\s*\/\s*0\s+slices\b/i.test(message)) {
+    findings.push({
+      code: "fake-zero-progress",
+      severity: "warning",
+      detail: `${item.surface} should hide roadmap progress before roadmap slices exist`,
+    });
+  }
+
+  if ((health === "stalled" || health === "provider-error" || health === "timeout") && !ACTION_RE.test(message)) {
+    findings.push({
+      code: "missing-action",
+      severity: "warning",
+      detail: `${item.surface} should give the user a next action for ${health}`,
+    });
+  }
+
+  return findings;
+}
+
+export function evaluateWorkingOutputMessages(
+  items: WorkingOutputMessage[],
+): WorkingOutputFinding[] {
+  return items.flatMap(evaluateWorkingOutputMessage);
+}

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

@@ -70,6 +70,15 @@ export interface WorktreeDiffSummary {
   removed: string[];
 }
 
+function deleteBranchIfPresent(basePath: string, branch: string, warningPrefix: string): void {
+  try {
+    if (!nativeBranchExists(basePath, branch)) return;
+    nativeBranchDelete(basePath, branch, true);
+  } catch (e) {
+    logWarning("worktree", `${warningPrefix}: ${(e as Error).message}`);
+  }
+}
+
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 
 function normalizePathForComparison(path: string): string {
@@ -408,7 +417,7 @@ export function listWorktrees(basePath: string): WorktreeInfo[] {
 
 /** Directories to skip when scanning for nested .git dirs. */
 const NESTED_GIT_SKIP_DIRS = new Set([
-  ".git", ".gsd", "node_modules", ".next", ".nuxt", "dist", "build",
+  ".git", ".gsd", ".bg-shell", "node_modules", ".next", ".nuxt", "dist", "build",
   "__pycache__", ".tox", ".venv", "venv", "target", "vendor",
 ]);
 
@@ -462,7 +471,9 @@ export function findNestedGitDirs(rootPath: string): string[] {
           continue;
         }
       } catch (e) {
-        logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${(e as Error).message}`);
+        if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
+          logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${(e as Error).message}`);
+        }
       }
 
       walk(fullPath, depth + 1);
@@ -535,7 +546,7 @@ export function removeWorktree(
   if (!existsSync(wtPath)) {
     nativeWorktreePrune(basePath);
     if (deleteBranch) {
-      try { nativeBranchDelete(basePath, branch, true); } catch (e) { logWarning("worktree", `nativeBranchDelete failed: ${(e as Error).message}`); }
+      deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
     }
     return;
   }
@@ -670,7 +681,7 @@ export function removeWorktree(
   nativeWorktreePrune(basePath);
 
   if (deleteBranch) {
-    try { nativeBranchDelete(basePath, branch, true); } catch (e) { logWarning("worktree", `final branch delete failed: ${(e as Error).message}`); }
+    deleteBranchIfPresent(basePath, branch, "final branch delete failed");
   }
 }
 

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

@@ -25,7 +25,7 @@ import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js
 import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain } from "./slice-cadence.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { claimMilestoneLease, releaseMilestoneLease } from "./db/milestone-leases.js";
+import { claimMilestoneLease, refreshMilestoneLease, releaseMilestoneLease } from "./db/milestone-leases.js";
 
 // ─── Path Comparison Helper ────────────────────────────────────────────────
 /**
@@ -40,6 +40,16 @@ function isSamePath(a: string, b: string): boolean {
   return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
 
+class UserNotifiedError extends Error {
+  readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = "UserNotifiedError";
+    this.cause = cause;
+  }
+}
+
 // ─── Dependency Interface ──────────────────────────────────────────────────
 
 export interface WorktreeResolverDeps {
@@ -71,6 +81,13 @@ export interface WorktreeResolverDeps {
     milestoneId: string,
   ) => void;
   getCurrentBranch: (basePath: string) => string;
+  /**
+   * Force-checkout the named branch in `basePath`. Required by `_mergeBranchMode`
+   * when it discovers the working tree is not on the milestone branch — preflight
+   * stash + later operations may have switched HEAD to main, and silently skipping
+   * the merge would strand the milestone's commits.
+   */
+  checkoutBranch: (basePath: string, branch: string) => void;
   autoWorktreeBranch: (milestoneId: string) => string;
   resolveMilestoneFile: (
     basePath: string,
@@ -207,23 +224,44 @@ export class WorktreeResolver {
     // milestone (re-entry within the same session).
     if (this.s.workerId) {
       if (this.s.currentMilestoneId === milestoneId && this.s.milestoneLeaseToken !== null) {
-        // Already held — no-op, the heartbeat in loop.ts refreshes TTL.
-      } else {
-        // If we held a different milestone, release it first so other
-        // workers don't have to wait for TTL.
-        if (this.s.currentMilestoneId && this.s.currentMilestoneId !== milestoneId && this.s.milestoneLeaseToken !== null) {
-          try {
-            releaseMilestoneLease(this.s.workerId, this.s.currentMilestoneId, this.s.milestoneLeaseToken);
-          } catch (err) {
-            debugLog("WorktreeResolver", {
-              action: "enterMilestone",
-              milestoneId,
-              releasePriorLeaseError: err instanceof Error ? err.message : String(err),
-            });
-          }
+        const refreshed = refreshMilestoneLease(
+          this.s.workerId,
+          milestoneId,
+          this.s.milestoneLeaseToken,
+        );
+        if (refreshed) {
+          debugLog("WorktreeResolver", {
+            action: "enterMilestone",
+            milestoneId,
+            leaseRefreshed: true,
+            fencingToken: this.s.milestoneLeaseToken,
+          });
+        } else {
+          debugLog("WorktreeResolver", {
+            action: "enterMilestone",
+            milestoneId,
+            staleLeaseToken: this.s.milestoneLeaseToken,
+          });
           this.s.milestoneLeaseToken = null;
         }
+      }
+
+      // If we held a different milestone, release it first so other
+      // workers don't have to wait for TTL.
+      if (this.s.currentMilestoneId && this.s.currentMilestoneId !== milestoneId && this.s.milestoneLeaseToken !== null) {
+        try {
+          releaseMilestoneLease(this.s.workerId, this.s.currentMilestoneId, this.s.milestoneLeaseToken);
+        } catch (err) {
+          debugLog("WorktreeResolver", {
+            action: "enterMilestone",
+            milestoneId,
+            releasePriorLeaseError: err instanceof Error ? err.message : String(err),
+          });
+        }
+        this.s.milestoneLeaseToken = null;
+      }
 
+      if (this.s.milestoneLeaseToken === null) {
         try {
           const claim = claimMilestoneLease(this.s.workerId, milestoneId);
           if (claim.ok) {
@@ -803,16 +841,41 @@ export class WorktreeResolver {
       const milestoneBranch = this.deps.autoWorktreeBranch(milestoneId);
 
       if (currentBranch !== milestoneBranch) {
+        // #5538-followup: previous behavior was to silently `return false`
+        // when HEAD wasn't on the milestone branch — that let the loop
+        // advance with the milestone's commits stranded on the branch (the
+        // exact failure mode reported in the test12345 repro). Attempt
+        // recovery by force-checking-out the milestone branch; if the
+        // checkout fails, throw so the caller pauses auto-mode and the user
+        // sees the failure instead of a silent merge skip.
         debugLog("WorktreeResolver", {
           action: "mergeAndExit",
           milestoneId,
           mode: "branch",
-          skipped: true,
-          reason: "not-on-milestone-branch",
+          recovery: "checkout-milestone-branch",
           currentBranch,
           milestoneBranch,
         });
-        return false;
+        try {
+          this.deps.checkoutBranch(this.s.basePath, milestoneBranch);
+        } catch (checkoutErr) {
+          const checkoutMsg = checkoutErr instanceof Error ? checkoutErr.message : String(checkoutErr);
+          ctx.notify(
+            `Cannot merge milestone ${milestoneId}: working tree is on ${currentBranch} and checkout to ${milestoneBranch} failed (${checkoutMsg}). Resolve manually and run /gsd auto to resume.`,
+            "error",
+          );
+          throw new UserNotifiedError(checkoutMsg, checkoutErr);
+        }
+
+        const reverify = this.deps.getCurrentBranch(this.s.basePath);
+        if (reverify !== milestoneBranch) {
+          const reverifyMsg = `branch checkout to ${milestoneBranch} reported success but current branch is ${reverify}`;
+          ctx.notify(
+            `Cannot merge milestone ${milestoneId}: ${reverifyMsg}. Resolve manually and run /gsd auto to resume.`,
+            "error",
+          );
+          throw new UserNotifiedError(reverifyMsg);
+        }
       }
 
       const roadmapPath = this.deps.resolveMilestoneFile(
@@ -869,7 +932,9 @@ export class WorktreeResolver {
         result: "error",
         error: msg,
       });
-      ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      if (!(err instanceof UserNotifiedError)) {
+        ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      }
       // Re-throw all errors so callers can apply their own recovery logic (#4380).
       throw err;
     }
@@ -897,6 +962,7 @@ export class WorktreeResolver {
     try {
       this.mergeAndExit(currentMilestoneId, ctx);
     } catch (err) {
+      if (err instanceof UserNotifiedError) throw err;
       // mergeAndExit emits a warning and restores state when it fails during
       // merge/cleanup. But if it throws before recovery runs (e.g., in
       // validateMilestoneId or emitJournalEvent), basePath won't be restored