gsd-pi 2.80.0-dev.710c06e97 → 2.80.0-dev.7582bf37a

package/dist/resources/extensions/gsd/tools/plan-slice.js

@@ -8,6 +8,7 @@ import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { validatePlanningPathScope } from "../planning-path-scope.js";
 function validateTasks(value) {
     if (!Array.isArray(value) || value.length === 0) {
         throw new Error("tasks must be a non-empty array");
@@ -91,6 +92,14 @@ export async function handlePlanSlice(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
+    const pathScopeError = validatePlanningPathScope(basePath, params.tasks.flatMap((task, index) => [
+        { field: `tasks[${index}].files`, values: task.files },
+        { field: `tasks[${index}].inputs`, values: task.inputs },
+        { field: `tasks[${index}].expectedOutput`, values: task.expectedOutput },
+    ]));
+    if (pathScopeError) {
+        return { error: `validation failed: ${pathScopeError}` };
+    }
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     // Guards must be inside the transaction so the state they check cannot
     // change between the read and the write (#2723).

package/dist/resources/extensions/gsd/tools/plan-task.js

@@ -8,6 +8,7 @@ import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { validatePlanningPathScope } from "../planning-path-scope.js";
 function validateParams(params) {
     if (!isNonEmptyString(params?.milestoneId))
         throw new Error("milestoneId is required");
@@ -41,6 +42,14 @@ export async function handlePlanTask(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
+    const pathScopeError = validatePlanningPathScope(basePath, [
+        { field: "files", values: params.files },
+        { field: "inputs", values: params.inputs },
+        { field: "expectedOutput", values: params.expectedOutput },
+    ]);
+    if (pathScopeError) {
+        return { error: `validation failed: ${pathScopeError}` };
+    }
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     // Guards must be inside the transaction so the state they check cannot
     // change between the read and the write (#2723).

package/dist/resources/extensions/gsd/tools/resume-tool.js

@@ -2,7 +2,12 @@
 // agents can re-orient after compaction or session resume without
 // re-deriving project memory state.
 import { readCompactionSnapshot } from "../compaction-snapshot.js";
+import { isContextModeEnabled } from "../preferences-types.js";
+import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 export function executeResume(_params, opts) {
+    if (!isContextModeEnabled(opts.preferences)) {
+        return contextModeDisabledResult("gsd_resume");
+    }
     const snapshot = readCompactionSnapshot(opts.baseDir);
     if (snapshot == null) {
         return {

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -680,7 +680,7 @@ export async function executeMilestoneStatus(params, basePath = process.cwd()) {
             };
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-                details: { operation: "milestone_status", milestoneId: milestone.id, sliceCount: slices.length },
+                details: { operation: "milestone_status", ...result },
             };
         });
     }

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -80,7 +80,15 @@ const CONTEXT_MODE_LANE_LABELS = {
     orchestration: "orchestration",
     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 = {
+    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
  * types, disabled config, and explicit `contextMode: "none"` all omit the
@@ -93,14 +101,15 @@ export function composeContextModeInstructions(unitType, opts) {
     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");
 }
 const SECTION_SEPARATOR = "\n\n---\n\n";

package/dist/resources/extensions/gsd/unit-runtime.js

@@ -4,6 +4,8 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { gsdRoot, relSliceFile, relTaskFile, resolveSliceFile, resolveTaskFile, } 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.
 // Within a single Node process this is moot (writeUnitRuntimeRecord is sync),
@@ -67,6 +69,17 @@ function withRecordLock(recordPath, fn) {
         catch { /* best-effort */ }
     }
 }
+export const IN_FLIGHT_RUNTIME_PHASES = new Set([
+    "dispatched",
+    "wrapup-warning-sent",
+    "timeout",
+    "finalize-timeout",
+    "crashed",
+    "paused",
+]);
+export function isInFlightRuntimePhase(phase) {
+    return IN_FLIGHT_RUNTIME_PHASES.has(phase);
+}
 function runtimeDir(basePath) {
     return join(gsdRoot(basePath), "runtime", "units");
 }
@@ -154,6 +167,12 @@ export async function inspectExecuteTaskDurability(basePath, unitId) {
     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;
     let mustHavesMentionedInSummary = 0;
@@ -177,11 +196,14 @@ export async function inspectExecuteTaskDurability(basePath, unitId) {
         summaryExists,
         taskChecked,
         nextActionAdvanced,
+        dbComplete,
         mustHaveCount,
         mustHavesMentionedInSummary,
     };
 }
 export function formatExecuteTaskRecoveryStatus(status) {
+    if (status.dbComplete)
+        return "DB task status is closed";
     const missing = [];
     if (!status.summaryExists)
         missing.push(`summary missing (${status.summaryPath})`);

package/dist/resources/extensions/gsd/workflow-protocol.js

@@ -0,0 +1,131 @@
+// 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, workflowPath, opts = {}) {
+    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) {
+    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, opts = {}) {
+    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, opts = {}) {
+    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() {
+    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, limit) {
+    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 = [];
+    const used = new Set();
+    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) {
+    const lines = markdown.split(/\r?\n/);
+    const sections = [];
+    let currentHeading = lines[0]?.startsWith("#") ? lines[0] : "# Preamble";
+    let current = [];
+    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) {
+    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, limit, notice) {
+    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/dist/resources/extensions/gsd/worktree-manager.js

@@ -22,6 +22,16 @@ import { logWarning } from "./workflow-logger.js";
 import { nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+function deleteBranchIfPresent(basePath, branch, warningPrefix) {
+    try {
+        if (!nativeBranchExists(basePath, branch))
+            return;
+        nativeBranchDelete(basePath, branch, true);
+    }
+    catch (e) {
+        logWarning("worktree", `${warningPrefix}: ${e.message}`);
+    }
+}
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -311,7 +321,7 @@ export function listWorktrees(basePath) {
 // of their object database, causing permanent silent data loss.
 /** 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",
 ]);
 /**
@@ -364,7 +374,9 @@ export function findNestedGitDirs(rootPath) {
                 }
             }
             catch (e) {
-                logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${e.message}`);
+                if (e.code !== "ENOENT") {
+                    logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${e.message}`);
+                }
             }
             walk(fullPath, depth + 1);
         }
@@ -430,12 +442,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     if (!existsSync(wtPath)) {
         nativeWorktreePrune(basePath);
         if (deleteBranch) {
-            try {
-                nativeBranchDelete(basePath, branch, true);
-            }
-            catch (e) {
-                logWarning("worktree", `nativeBranchDelete failed: ${e.message}`);
-            }
+            deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
         }
         return;
     }
@@ -549,12 +556,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     // Prune stale entries so git knows the worktree is gone
     nativeWorktreePrune(basePath);
     if (deleteBranch) {
-        try {
-            nativeBranchDelete(basePath, branch, true);
-        }
-        catch (e) {
-            logWarning("worktree", `final branch delete failed: ${e.message}`);
-        }
+        deleteBranchIfPresent(basePath, branch, "final branch delete failed");
     }
 }
 /**

package/dist/resources/extensions/gsd/worktree-resolver.js

@@ -22,7 +22,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 ────────────────────────────────────────────────
 /**
  * Compare two paths for physical identity, tolerating trailing slashes,
@@ -35,6 +35,14 @@ import { claimMilestoneLease, releaseMilestoneLease } from "./db/milestone-lease
 function isSamePath(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
+class UserNotifiedError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "UserNotifiedError";
+        this.cause = cause;
+    }
+}
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 /**
  * Resolve the project root from session path state.
@@ -119,24 +127,40 @@ 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) {
@@ -336,19 +360,38 @@ export class WorktreeResolver {
                 phase: "auto-commit-failed",
                 error: err instanceof Error ? err.message : String(err),
             });
+            ctx.notify(`Auto-commit before exiting ${milestoneId} failed: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`, "warning");
         }
+        if (this.s.originalBasePath) {
+            try {
+                process.chdir(this.s.originalBasePath);
+            }
+            catch (err) {
+                debugLog("WorktreeResolver", {
+                    action: "exitMilestone",
+                    milestoneId,
+                    phase: "pre-teardown-chdir-failed",
+                    originalBasePath: this.s.originalBasePath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                ctx.notify(`Could not leave milestone worktree before cleanup: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`, "warning");
+            }
+        }
+        let teardownFailed = false;
         try {
             this.deps.teardownAutoWorktree(this.s.originalBasePath, milestoneId, {
                 preserveBranch: opts?.preserveBranch ?? false,
             });
         }
         catch (err) {
+            teardownFailed = true;
             debugLog("WorktreeResolver", {
                 action: "exitMilestone",
                 milestoneId,
                 phase: "teardown-failed",
                 error: err instanceof Error ? err.message : String(err),
             });
+            ctx.notify(`Worktree cleanup failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`, "warning");
         }
         this.restoreToProjectRoot();
         debugLog("WorktreeResolver", {
@@ -357,7 +400,9 @@ export class WorktreeResolver {
             result: "done",
             basePath: this.s.basePath,
         });
-        ctx.notify(`Exited worktree for ${milestoneId}`, "info");
+        ctx.notify(teardownFailed
+            ? `Worktree exit for ${milestoneId} needs manual cleanup.`
+            : `Exited worktree for ${milestoneId}`, teardownFailed ? "warning" : "info");
     }
     // ── Merge and Exit ─────────────────────────────────────────────────────
     /**
@@ -647,16 +692,35 @@ export class WorktreeResolver {
             const currentBranch = this.deps.getCurrentBranch(this.s.basePath);
             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(this.s.basePath, milestoneId, "ROADMAP");
             if (!roadmapPath) {
@@ -697,7 +761,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;
         }
@@ -720,6 +786,8 @@ export class WorktreeResolver {
             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