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

package/src/resources/extensions/gsd/tests/unstructured-continue-context-injection.test.ts

@@ -1,4 +1,5 @@
-// GSD-2 — Regression test for #3615: unstructured "continue" must inject task context
+// Project/App: GSD-2
+// File Purpose: Regression test for unstructured continue task-context injection.
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 /**
@@ -55,12 +56,12 @@ describe("#3615 — structural: fallback exists with correct guards", () => {
     );
   });
 
-  test("fallback is intent-gated via RESUME_INTENT_PATTERNS", () => {
+  test("fallback is intent-gated via isLowEntropyResumePrompt", () => {
     const afterFallback = fnBody.indexOf("// Fallback:");
     const fallbackSection = fnBody.slice(afterFallback);
     assert.ok(
-      fallbackSection.includes("RESUME_INTENT_PATTERNS"),
-      "fallback must check RESUME_INTENT_PATTERNS before deriveState",
+      fallbackSection.includes("isLowEntropyResumePrompt(prompt)"),
+      "fallback must check isLowEntropyResumePrompt before deriveState",
     );
   });
 

package/src/resources/extensions/gsd/tests/workflow-dispatch-claim.test.ts

@@ -7,7 +7,9 @@ import test from "node:test";
 import type { AutoSession } from "../auto/session.ts";
 import type { IterationData } from "../auto/types.ts";
 import {
+  ensureDispatchLease,
   openDispatchClaim,
+  type EnsureDispatchLeaseDeps,
   type OpenDispatchClaimDeps,
 } from "../auto/workflow-dispatch-claim.ts";
 
@@ -49,6 +51,25 @@ function makeDeps(overrides?: Partial<OpenDispatchClaimDeps>): OpenDispatchClaim
   };
 }
 
+function makeLeaseDeps(overrides?: Partial<EnsureDispatchLeaseDeps>): {
+  deps: EnsureDispatchLeaseDeps;
+  calls: unknown[];
+  failures: unknown[];
+} {
+  const calls: unknown[] = [];
+  const failures: unknown[] = [];
+  const deps: EnsureDispatchLeaseDeps = {
+    claimMilestoneLease: (workerId, milestoneId) => {
+      calls.push(["claim", workerId, milestoneId]);
+      return { ok: true, token: 8, expiresAt: "2030-01-01T00:00:00.000Z" };
+    },
+    logLeaseRecovered: details => calls.push(["recovered", details]),
+    logLeaseRecoveryFailed: details => failures.push(details),
+    ...overrides,
+  };
+  return { deps, calls, failures };
+}
+
 test("openDispatchClaim degrades when worker identity or lease token is missing", () => {
   assert.deepEqual(
     openDispatchClaim(makeSession({ workerId: null }), "flow", "turn", makeIterationData(), makeDeps({
@@ -156,3 +177,124 @@ test("openDispatchClaim degrades on claim write failures", () => {
   assert.deepEqual(outcome, { kind: "degraded" });
   assert.deepEqual(logged, [writeError]);
 });
+
+test("ensureDispatchLease degrades without worker identity or milestone id", () => {
+  const { deps, calls } = makeLeaseDeps({
+    claimMilestoneLease: () => assert.fail("claimMilestoneLease should not be called"),
+  });
+
+  assert.deepEqual(
+    ensureDispatchLease(makeSession({ workerId: null }), "M001", deps),
+    { kind: "degraded", reason: "missing-worker" },
+  );
+  assert.deepEqual(
+    ensureDispatchLease(makeSession(), undefined, deps),
+    { kind: "degraded", reason: "missing-milestone" },
+  );
+  assert.deepEqual(calls, []);
+});
+
+test("ensureDispatchLease reuses an existing numeric token", () => {
+  const { deps, calls } = makeLeaseDeps({
+    claimMilestoneLease: () => assert.fail("claimMilestoneLease should not be called"),
+  });
+
+  const session = makeSession({ milestoneLeaseToken: 7 });
+  const outcome = ensureDispatchLease(session, "M001", deps);
+
+  assert.deepEqual(outcome, { kind: "ready", token: 7, recovered: false });
+  assert.equal(session.milestoneLeaseToken, 7);
+  assert.deepEqual(calls, []);
+});
+
+test("ensureDispatchLease claims a lease when the session has no token", () => {
+  const { deps, calls, failures } = makeLeaseDeps();
+  const session = makeSession({
+    currentMilestoneId: "M001",
+    milestoneLeaseToken: null,
+  });
+
+  const outcome = ensureDispatchLease(session, "M001", deps);
+
+  assert.deepEqual(outcome, { kind: "ready", token: 8, recovered: false });
+  assert.equal(session.currentMilestoneId, "M001");
+  assert.equal(session.milestoneLeaseToken, 8);
+  assert.deepEqual(calls, [
+    ["claim", "worker-1", "M001"],
+    ["recovered", {
+      milestoneId: "M001",
+      workerId: "worker-1",
+      token: 8,
+      recovered: false,
+    }],
+  ]);
+  assert.deepEqual(failures, []);
+});
+
+test("ensureDispatchLease force-reclaims after a stale dispatch claim", () => {
+  const { deps, calls } = makeLeaseDeps({
+    claimMilestoneLease: (workerId, milestoneId) => {
+      calls.push(["claim", workerId, milestoneId]);
+      return { ok: true, token: 9, expiresAt: "2030-01-01T00:00:00.000Z" };
+    },
+  });
+  const session = makeSession({ milestoneLeaseToken: 7 });
+
+  const outcome = ensureDispatchLease(session, "M001", deps, { forceReclaim: true });
+
+  assert.deepEqual(outcome, { kind: "ready", token: 9, recovered: true });
+  assert.equal(session.milestoneLeaseToken, 9);
+  assert.deepEqual(calls, [
+    ["claim", "worker-1", "M001"],
+    ["recovered", {
+      milestoneId: "M001",
+      workerId: "worker-1",
+      token: 9,
+      recovered: true,
+    }],
+  ]);
+});
+
+test("ensureDispatchLease blocks when another worker holds the lease", () => {
+  const { deps, failures } = makeLeaseDeps({
+    claimMilestoneLease: () => ({
+      ok: false,
+      error: "held_by",
+      byWorker: "worker-2",
+      expiresAt: "2030-01-01T00:00:00.000Z",
+    }),
+  });
+  const session = makeSession({ milestoneLeaseToken: null });
+
+  const outcome = ensureDispatchLease(session, "M001", deps);
+
+  assert.deepEqual(outcome, {
+    kind: "blocked",
+    reason: "Milestone M001 is held by worker worker-2 until 2030-01-01T00:00:00.000Z.",
+  });
+  assert.equal(session.milestoneLeaseToken, null);
+  assert.deepEqual(failures, [{
+    milestoneId: "M001",
+    workerId: "worker-1",
+    reason: "Milestone M001 is held by worker worker-2 until 2030-01-01T00:00:00.000Z.",
+  }]);
+});
+
+test("ensureDispatchLease fails closed on claim errors", () => {
+  const { deps, failures } = makeLeaseDeps({
+    claimMilestoneLease: () => {
+      throw new Error("db unavailable");
+    },
+  });
+  const session = makeSession({ milestoneLeaseToken: null });
+
+  const outcome = ensureDispatchLease(session, "M001", deps);
+
+  assert.deepEqual(outcome, { kind: "failed", reason: "db unavailable" });
+  assert.equal(session.milestoneLeaseToken, null);
+  assert.deepEqual(failures, [{
+    milestoneId: "M001",
+    workerId: "worker-1",
+    reason: "db unavailable",
+  }]);
+});

package/src/resources/extensions/gsd/tests/workflow-protocol-excerpt.test.ts

@@ -0,0 +1,99 @@
+// Project/App: GSD-2
+// File Purpose: Tests for capped GSD workflow protocol and doctor-heal payload helpers.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildDoctorHealIssuePayload,
+  buildDoctorHealSummary,
+  buildWorkflowDispatchContent,
+  buildWorkflowProtocolExcerpt,
+} from "../workflow-protocol.ts";
+
+test("workflow protocol helper emits capped excerpt plus source path", () => {
+  const workflow = `# Protocol\n${"FULL_WORKFLOW_BODY ".repeat(500)}`;
+  const excerpt = buildWorkflowProtocolExcerpt(workflow, "/tmp/GSD-WORKFLOW.md", { maxChars: 1200 });
+
+  assert.match(excerpt, /Source: `\/tmp\/GSD-WORKFLOW\.md`/);
+  assert.match(excerpt, /\[Workflow Protocol Truncated\]/);
+  assert.ok(excerpt.length < workflow.length);
+  assert.ok(excerpt.length < 1600);
+});
+
+test("workflow dispatch uses excerpt instead of full workflow body", () => {
+  const workflow = `# Protocol\n${"FULL_WORKFLOW_BODY ".repeat(500)}`;
+  const content = buildWorkflowDispatchContent({
+    workflow,
+    workflowPath: "/tmp/GSD-WORKFLOW.md",
+    task: "Run the selected unit.",
+    maxProtocolChars: 1200,
+  });
+
+  assert.match(content, /## GSD Workflow Protocol Excerpt/);
+  assert.match(content, /## Your Task/);
+  assert.match(content, /Run the selected unit/);
+  assert.ok(content.length < workflow.length);
+});
+
+test("workflow protocol excerpt includes late verification and advance rules", () => {
+  const workflow = [
+    "# GSD Workflow",
+    "intro",
+    "## Quick Start",
+    "quick",
+    "## File Format Reference",
+    "format ".repeat(400),
+    "## The Phases",
+    "phase overview",
+    "### Phase 4: Execute",
+    "execute rules",
+    "### Phase 5: Verify",
+    "verification rules",
+    "### Phase 7: Advance",
+    "advance rules",
+  ].join("\n");
+
+  const excerpt = buildWorkflowProtocolExcerpt(workflow, "/tmp/GSD-WORKFLOW.md", { maxChars: 1300 });
+
+  assert.match(excerpt, /Quick Start/);
+  assert.match(excerpt, /Phase 5: Verify/);
+  assert.match(excerpt, /Phase 7: Advance/);
+  assert.doesNotMatch(excerpt, /format format format format format/);
+});
+
+test("doctor heal summary omits duplicated full report body", () => {
+  const report = [
+    "# GSD doctor heal prep.",
+    "Scope: M001",
+    "Status: warning",
+    "Warnings: 9",
+    "",
+    "VERY_LONG_FULL_REPORT_BODY ".repeat(300),
+  ].join("\n");
+
+  const summary = buildDoctorHealSummary(report, { maxChars: 900 });
+
+  assert.match(summary, /GSD doctor heal prep/);
+  assert.match(summary, /Warnings: 9/);
+  assert.ok(summary.length <= 900);
+  assert.doesNotMatch(summary, /VERY_LONG_FULL_REPORT_BODY VERY_LONG_FULL_REPORT_BODY VERY_LONG_FULL_REPORT_BODY/);
+});
+
+test("doctor heal issue payload keeps top actionable issues and caps detail", () => {
+  const issues = Array.from({ length: 20 }, (_, index) =>
+    `### Issue ${index + 1}\n${`detail ${index + 1} `.repeat(80)}`,
+  ).join("\n");
+
+  const payload = buildDoctorHealIssuePayload(issues, {
+    maxIssues: 3,
+    maxIssueChars: 180,
+    maxChars: 900,
+  });
+
+  assert.match(payload, /Issue 1/);
+  assert.match(payload, /Issue 3/);
+  assert.doesNotMatch(payload, /Issue 4/);
+  assert.match(payload, /17 additional actionable issue/);
+  assert.ok(payload.length <= 900);
+});

package/src/resources/extensions/gsd/tests/workflow-worker-heartbeat.test.ts

@@ -14,9 +14,11 @@ function makeDeps(overrides?: Partial<MaintainWorkerHeartbeatDeps>): {
   deps: MaintainWorkerHeartbeatDeps;
   calls: unknown[];
   errors: unknown[];
+  misses: unknown[];
 } {
   const calls: unknown[] = [];
   const errors: unknown[] = [];
+  const misses: unknown[] = [];
   const deps: MaintainWorkerHeartbeatDeps = {
     heartbeatAutoWorker: workerId => calls.push(["heartbeat", workerId]),
     refreshMilestoneLease: (workerId, milestoneId, token) => {
@@ -24,9 +26,10 @@ function makeDeps(overrides?: Partial<MaintainWorkerHeartbeatDeps>): {
       return true;
     },
     logHeartbeatFailure: err => errors.push(err),
+    logLeaseRefreshMiss: details => misses.push(details),
     ...overrides,
   };
-  return { deps, calls, errors };
+  return { deps, calls, errors, misses };
 }
 
 test("maintainWorkerHeartbeat no-ops without a worker id", () => {
@@ -121,3 +124,31 @@ test("maintainWorkerHeartbeat logs and suppresses lease refresh failures", () =>
   ]);
   assert.deepEqual(errors, [failure]);
 });
+
+test("maintainWorkerHeartbeat clears stale lease tokens when refresh misses", () => {
+  const { deps, calls, errors, misses } = makeDeps({
+    refreshMilestoneLease: (workerId, milestoneId, token) => {
+      calls.push(["refresh", workerId, milestoneId, token]);
+      return false;
+    },
+  });
+  const session: WorkerHeartbeatSession = {
+    workerId: "worker-1",
+    currentMilestoneId: "M001",
+    milestoneLeaseToken: 7,
+  };
+
+  maintainWorkerHeartbeat(session, deps);
+
+  assert.deepEqual(calls, [
+    ["heartbeat", "worker-1"],
+    ["refresh", "worker-1", "M001", 7],
+  ]);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(misses, [{
+    workerId: "worker-1",
+    milestoneId: "M001",
+    fencingToken: 7,
+  }]);
+  assert.equal(session.milestoneLeaseToken, null);
+});

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -39,6 +39,7 @@ function makeDeps(
     getAutoWorktreePath: () => null,
     autoCommitCurrentBranch: () => {},
     getCurrentBranch: () => "main",
+    checkoutBranch: () => {},
     autoWorktreeBranch: (milestoneId: string) => `milestone/${milestoneId}`,
     resolveMilestoneFile: (_basePath: string, milestoneId: string) =>
       `/project/.gsd/milestones/${milestoneId}/${milestoneId}-ROADMAP.md`,

package/src/resources/extensions/gsd/tests/worktree-path-injection.test.ts

@@ -79,7 +79,7 @@ async function waitFor(condition: () => boolean, label: string): Promise<void> {
   assert.fail(`Timed out waiting for ${label} after ${timeoutMs}ms`);
 }
 
-test("runUnit changes cwd to basePath before creating a new session", async (t) => {
+test("runUnit passes basePath as workspaceRoot without changing process cwd", async (t) => {
   _resetPendingResolve();
 
   const originalCwd = process.cwd();
@@ -93,13 +93,15 @@ test("runUnit changes cwd to basePath before creating a new session", async (t)
 
   process.chdir(drifted);
 
+  let newSessionWorkspaceRoot: string | undefined;
   let cwdAtNewSession: string | undefined;
   const session = {
     active: true,
     basePath: base,
     verbose: false,
     cmdCtx: {
-      newSession: () => {
+      newSession: (options?: { workspaceRoot?: string }) => {
+        newSessionWorkspaceRoot = options?.workspaceRoot;
         cwdAtNewSession = process.cwd();
         return Promise.resolve({ cancelled: false });
       },
@@ -119,10 +121,12 @@ test("runUnit changes cwd to basePath before creating a new session", async (t)
 
   const result = await resultPromise;
   assert.equal(result.status, "completed");
-  assert.equal(cwdAtNewSession, base);
+  assert.equal(newSessionWorkspaceRoot, base);
+  assert.equal(cwdAtNewSession, drifted);
+  assert.equal(process.cwd(), drifted);
 });
 
-test("runUnit cancels before creating a session when basePath chdir fails", async (t) => {
+test("runUnit does not chdir or cancel when basePath is not a live directory", async (t) => {
   _resetPendingResolve();
 
   const originalCwd = process.cwd();
@@ -136,14 +140,14 @@ test("runUnit cancels before creating a session when basePath chdir fails", asyn
 
   process.chdir(drifted);
 
-  let newSessionCalled = false;
+  let newSessionWorkspaceRoot: string | undefined;
   const session = {
     active: true,
     basePath: base,
     verbose: false,
     cmdCtx: {
-      newSession: () => {
-        newSessionCalled = true;
+      newSession: (options?: { workspaceRoot?: string }) => {
+        newSessionWorkspaceRoot = options?.workspaceRoot;
         return Promise.resolve({ cancelled: false });
       },
     },
@@ -156,15 +160,14 @@ test("runUnit cancels before creating a session when basePath chdir fails", asyn
   } as any;
   const ctx = { ui: { notify: () => {} }, model: { id: "test-model" } } as any;
 
-  const result = await runUnit(ctx, pi, session, "task", "T01", "prompt");
+  const resultPromise = runUnit(ctx, pi, session, "task", "T01", "prompt");
+  await waitFor(() => pi.calls.length === 1, "runUnit dispatch");
+  resolveAgentEnd({ messages: [{ role: "assistant" }] });
 
-  assert.equal(result.status, "cancelled");
-  assert.equal(result.errorContext?.category, "session-failed");
-  assert.equal(result.errorContext?.isTransient, true);
-  assert.match(result.errorContext?.message ?? "", /Failed to chdir to basePath before newSession/);
-  assert.ok(result.errorContext?.message.includes(base), "error should include the failed basePath");
-  assert.equal(newSessionCalled, false, "newSession must not run after chdir failure");
-  assert.equal(pi.calls.length, 0, "unit must not dispatch after chdir failure");
+  const result = await resultPromise;
+  assert.equal(result.status, "completed");
+  assert.equal(newSessionWorkspaceRoot, base);
+  assert.equal(process.cwd(), drifted);
 });
 
 test("direct dispatch redirects to the canonical milestone worktree before newSession", async (t) => {
@@ -185,12 +188,12 @@ test("direct dispatch redirects to the canonical milestone worktree before newSe
 
   process.chdir(drifted);
 
-  let cwdAtNewSession: string | undefined;
+  let newSessionWorkspaceRoot: string | undefined;
   let sentPrompt: string | undefined;
   const ctx = {
     ui: { notify: () => {} },
-    newSession: async () => {
-      cwdAtNewSession = process.cwd();
+    newSession: async (options?: { workspaceRoot?: string }) => {
+      newSessionWorkspaceRoot = options?.workspaceRoot;
       return { cancelled: false };
     },
   } as any;
@@ -202,7 +205,7 @@ test("direct dispatch redirects to the canonical milestone worktree before newSe
 
   await dispatchDirectPhase(ctx, pi, "research-milestone", base);
 
-  assert.equal(cwdAtNewSession, worktreeRoot);
+  assert.equal(newSessionWorkspaceRoot, worktreeRoot);
   assert.equal(process.cwd(), drifted);
   assert.ok(sentPrompt?.includes(worktreeRoot), "prompt should name the canonical worktree root");
 });

package/src/resources/extensions/gsd/tests/worktree-project-root-degrade.test.ts

@@ -0,0 +1,66 @@
+// GSD-2 + Worktree dispatch guard: degrade empty worktrees over real project roots.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { shouldDegradeEmptyWorktreeToProjectRoot } from "../auto/phases.ts";
+import type { ProjectClassification } from "../detection.ts";
+
+function classification(kind: ProjectClassification["kind"]): ProjectClassification {
+  return {
+    kind,
+    signals: {
+      detectedFiles: [],
+      isGitRepo: true,
+      isMonorepo: false,
+      xcodePlatforms: [],
+      hasCI: false,
+      hasTests: false,
+      verificationCommands: [],
+    },
+    trackedFiles: [],
+    untrackedFiles: [],
+    contentFiles: [],
+    markers: [],
+    reason: kind,
+  };
+}
+
+describe("worktree project-root degradation", () => {
+  test("degrades when worktree is greenfield but project root has content", () => {
+    assert.equal(
+      shouldDegradeEmptyWorktreeToProjectRoot(
+        classification("greenfield"),
+        classification("typed-existing"),
+      ),
+      true,
+    );
+    assert.equal(
+      shouldDegradeEmptyWorktreeToProjectRoot(
+        classification("greenfield"),
+        classification("untyped-existing"),
+      ),
+      true,
+    );
+  });
+
+  test("keeps true greenfield worktrees in worktree mode", () => {
+    assert.equal(
+      shouldDegradeEmptyWorktreeToProjectRoot(
+        classification("greenfield"),
+        classification("greenfield"),
+      ),
+      false,
+    );
+  });
+
+  test("does not degrade when project root classification is invalid", () => {
+    assert.equal(
+      shouldDegradeEmptyWorktreeToProjectRoot(
+        classification("greenfield"),
+        classification("invalid-repo"),
+      ),
+      false,
+    );
+  });
+});

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

@@ -118,6 +118,9 @@ function makeDeps(
       calls.push({ fn: "getCurrentBranch", args: [basePath] });
       return "main";
     },
+    checkoutBranch: (basePath: string, branch: string) => {
+      calls.push({ fn: "checkoutBranch", args: [basePath, branch] });
+    },
     autoWorktreeBranch: (milestoneId: string) => {
       calls.push({ fn: "autoWorktreeBranch", args: [milestoneId] });
       return `milestone/${milestoneId}`;
@@ -802,21 +805,92 @@ test("mergeAndExit in branch mode merges when on milestone branch", () => {
   assert.ok(ctx.messages.some((m) => m.msg.includes("branch mode")));
 });
 
-test("mergeAndExit in branch mode skips when not on milestone branch", () => {
+test("mergeAndExit in branch mode checks out the milestone branch and merges (#5538-followup)", () => {
+  // Regression: previously this case silently returned without merging,
+  // stranding the milestone's commits on the branch (the test12345 repro).
+  // The fix forces a checkout first; merge proceeds when checkout succeeds.
   const s = makeSession({ basePath: "/project", originalBasePath: "/project" });
+  let currentBranch = "main";
+  const checkoutInvocations: Array<{ basePath: string; branch: string }> = [];
   const deps = makeDeps({
     isInAutoWorktree: () => false,
     getIsolationMode: () => "branch",
-    getCurrentBranch: () => "main",
+    getCurrentBranch: () => currentBranch,
     autoWorktreeBranch: () => "milestone/M001",
+    checkoutBranch: (basePath: string, branch: string) => {
+      checkoutInvocations.push({ basePath, branch });
+      currentBranch = branch;
+    },
   });
   const ctx = makeNotifyCtx();
   const resolver = new WorktreeResolver(s, deps);
 
   resolver.mergeAndExit("M001", ctx);
 
+  assert.equal(checkoutInvocations.length, 1, "must attempt checkout when on wrong branch");
+  assert.deepEqual(checkoutInvocations[0], { basePath: "/project", branch: "milestone/M001" });
+  assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 1);
+});
+
+test("mergeAndExit in branch mode throws when checkout fails", () => {
+  // Regression for the silent-skip bug: if the working tree is on the wrong
+  // branch and checkout fails, we must throw so the caller pauses auto-mode
+  // — never silently advance with the milestone unmerged.
+  const s = makeSession({ basePath: "/project", originalBasePath: "/project" });
+  const deps = makeDeps({
+    isInAutoWorktree: () => false,
+    getIsolationMode: () => "branch",
+    getCurrentBranch: () => "main",
+    autoWorktreeBranch: () => "milestone/M001",
+    checkoutBranch: () => {
+      throw new Error("dirty working tree blocks checkout");
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  assert.throws(
+    () => resolver.mergeAndExit("M001", ctx),
+    /dirty working tree blocks checkout/,
+  );
+  assert.equal(
+    findCalls(deps.calls, "mergeMilestoneToMain").length,
+    0,
+    "merge must not run when checkout failed",
+  );
+  const errorNotify = ctx.messages.find((m) => m.level === "error");
+  assert.ok(errorNotify, "an error notification must be emitted");
+  assert.match(errorNotify!.msg, /milestone\/M001 failed/);
+  assert.match(errorNotify!.msg, /Resolve manually/);
+  assert.equal(
+    ctx.messages.some((m) => m.level === "warning" && m.msg.includes("Milestone merge failed")),
+    false,
+    "checkout failures with explicit recovery guidance must not emit a duplicate warning",
+  );
+});
+
+test("mergeAndExit in branch mode throws when checkout reports success but HEAD is still wrong", () => {
+  // Defense in depth: even if checkoutBranch returns without throwing, we
+  // re-verify and throw if HEAD didn't actually move. Prevents merging on
+  // top of the wrong branch on platforms where the checkout is a no-op.
+  const s = makeSession({ basePath: "/project", originalBasePath: "/project" });
+  const deps = makeDeps({
+    isInAutoWorktree: () => false,
+    getIsolationMode: () => "branch",
+    getCurrentBranch: () => "main", // never changes — simulates no-op checkout
+    autoWorktreeBranch: () => "milestone/M001",
+    checkoutBranch: () => {
+      // Pretend success — but getCurrentBranch will still return "main".
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  assert.throws(
+    () => resolver.mergeAndExit("M001", ctx),
+    /reported success but current branch is main/,
+  );
   assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 0);
-  assert.equal(ctx.messages.length, 0);
 });
 
 test("mergeAndExit in branch mode handles merge failure gracefully", () => {
@@ -1039,6 +1113,33 @@ test("mergeAndEnterNext enters next milestone even if merge fails", () => {
   );
 });
 
+test("mergeAndEnterNext halts after branch-mode user-notified checkout failure", () => {
+  const s = makeSession({ basePath: "/project", originalBasePath: "/project" });
+  const deps = makeDeps({
+    isInAutoWorktree: () => false,
+    getIsolationMode: () => "branch",
+    getCurrentBranch: () => "main",
+    autoWorktreeBranch: () => "milestone/M001",
+    checkoutBranch: () => {
+      throw new Error("dirty working tree blocks checkout");
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  assert.throws(
+    () => resolver.mergeAndEnterNext("M001", "M002", ctx),
+    /dirty working tree blocks checkout/,
+  );
+  assert.equal(
+    findCalls(deps.calls, "enterBranchModeForMilestone").length,
+    0,
+    "must not enter the next milestone after a user-notified branch-mode failure",
+  );
+  assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 0);
+  assert.ok(ctx.messages.some((m) => m.level === "error" && m.msg.includes("Resolve manually")));
+});
+
 // ─── GitService Rebuild Atomicity ────────────────────────────────────────────
 
 test("GitService is rebuilt with the NEW basePath after enterMilestone", () => {