gsd-pi 2.80.0-dev.fbe7c8c6f → 2.81.0-dev.3cddbbba2

package/src/resources/extensions/gsd/tests/merge-conflict-stops-loop.test.ts

@@ -29,15 +29,49 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { WorktreeResolver } from "../worktree-resolver.ts";
+import {
+  WorktreeLifecycle,
+  type WorktreeLifecycleDeps,
+  type WorktreeLifecycleTestOverrides,
+} from "../worktree-lifecycle.ts";
+import { WorktreeStateProjection } from "../worktree-state-projection.ts";
 import { MergeConflictError } from "../git-service.ts";
-import type { WorktreeResolverDeps } from "../worktree-resolver.ts";
 import type { AutoSession } from "../auto/session.ts";
 
+// Test-local: extras the WorktreeResolver-era fixture passed but Lifecycle
+// does not need (shouldUseWorktreeIsolation, syncWorktreeStateBack,
+// captureIntegrationBranch). Lifecycle ignores them via structural typing.
+// The C1-C4-inlined primitive overrides come from
+// `WorktreeLifecycleTestOverrides`, the test seam exported by the Module.
+type LegacyTestDeps = WorktreeLifecycleDeps & WorktreeLifecycleTestOverrides & {
+  shouldUseWorktreeIsolation?: () => boolean;
+  syncWorktreeStateBack?: (
+    mainBasePath: string,
+    worktreePath: string,
+    milestoneId: string,
+  ) => { synced: string[] };
+  captureIntegrationBranch?: (basePath: string, mid: string | undefined) => void;
+  GitServiceImpl?: new (basePath: string, gitConfig: unknown) => unknown;
+};
+
+/**
+ * Shim factory preserving the legacy WorktreeResolver throw shape for
+ * `mergeAndExit` so the existing assert.throws bodies migrate verbatim.
+ */
+function makeResolver(s: AutoSession, deps: LegacyTestDeps) {
+  const lifecycle = new WorktreeLifecycle(s, deps);
+  return {
+    mergeAndExit: (mid: string, ctx: { notify: (msg: string, level?: "info" | "warning" | "error" | "success") => void }) => {
+      const r = lifecycle.exitMilestone(mid, { merge: true }, ctx);
+      if (!r.ok && r.cause instanceof Error) throw r.cause;
+    },
+  };
+}
+
 // ─── Test-only session double ───────────────────────────────────────────
 // `AutoSession` is a large class but `WorktreeResolver` only reads a few
 // fields from it (basePath, originalBasePath, currentMilestoneId).
@@ -55,8 +89,8 @@ function makeSession(basePath: string): AutoSession {
  * boring-tech approach — no mocking library, just plain objects.
  */
 function makeDeps(
-  overrides: Partial<WorktreeResolverDeps> = {},
-): WorktreeResolverDeps {
+  overrides: Partial<LegacyTestDeps> = {},
+): LegacyTestDeps {
   return {
     isInAutoWorktree: () => true,
     shouldUseWorktreeIsolation: () => true,
@@ -68,8 +102,14 @@ function makeDeps(
     enterAutoWorktree: () => "",
     enterBranchModeForMilestone: () => undefined,
     getAutoWorktreePath: () => null,
-    autoCommitCurrentBranch: () => undefined,
+    autoCommitCurrentBranch: (
+      _basePath: string,
+      _unitType: string,
+      _unitId: string,
+      _taskContext?: unknown,
+    ) => null,
     getCurrentBranch: () => "worktree/M001",
+    checkoutBranch: () => undefined,
     autoWorktreeBranch: (mid: string) => `worktree/${mid}`,
     resolveMilestoneFile: () => null, // no roadmap → early return path
     readFileSync: () => "",
@@ -79,6 +119,9 @@ function makeDeps(
     loadEffectiveGSDPreferences: () => ({ preferences: {} }),
     invalidateAllCaches: () => undefined,
     captureIntegrationBranch: () => undefined,
+    worktreeProjection: new WorktreeStateProjection(),
+    // ADR-016 phase 2 / C4 (#5627): GitServiceImpl constructor → factory.
+    gitServiceFactory: () => ({}) as never,
     ...overrides,
   };
 }
@@ -98,14 +141,36 @@ function makeNotifyCtx(): {
 
 describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", () => {
   let baseDir: string;
+  const savedCwd = process.cwd();
 
   beforeEach(() => {
     baseDir = mkdtempSync(join(tmpdir(), "merge-conflict-stops-loop-"));
     // Fake out a milestone directory so mergeAndExit reaches mergeMilestoneToMain.
     mkdirSync(join(baseDir, ".gsd", "milestones", "M001"), { recursive: true });
+    // ADR-016 phase 2 / C1 (#5624): worktree-lifecycle.ts now calls
+    // node:fs.readFileSync directly (the dep was retired), so the roadmap
+    // file must exist on disk for the test to reach mergeMilestoneToMain.
+    writeFileSync(
+      join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      "# M001\n",
+    );
+    // ADR-016 phase 2 / C3 (#5626): `getIsolationMode` is also inlined.
+    // Without explicit isolation preferences the mode defaults to "none"
+    // and the merge short-circuits before the test's mocked
+    // `mergeMilestoneToMain` is reached. Write a preferences file so the
+    // standalone routes through worktree-mode merge.
+    writeFileSync(
+      join(baseDir, ".gsd", "preferences.md"),
+      "## Git\n- isolation: worktree\n",
+    );
   });
 
   afterEach(() => {
+    // ADR-016 phase 2 / C2 (#5625): the inlined `mergeMilestoneStandalone`
+    // chdirs into the project root before the merge body runs. Restore
+    // cwd before deleting `baseDir` so the next test's `process.cwd()`
+    // doesn't fail with ENOENT.
+    try { process.chdir(savedCwd); } catch { /* best-effort */ }
     try {
       rmSync(baseDir, { recursive: true, force: true });
     } catch {
@@ -117,7 +182,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
     const conflicted = ["src/feature.ts", "README.md"];
     const roadmapPath = join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     const deps = makeDeps({
-      resolveMilestoneFile: (_base, _mid, type) =>
+      resolveMilestoneFile: (_base: string, _mid: string, type: string) =>
         type === "ROADMAP" ? roadmapPath : null,
       readFileSync: () => "# M001\n",
       mergeMilestoneToMain: () => {
@@ -125,7 +190,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
       },
     });
 
-    const resolver = new WorktreeResolver(makeSession(baseDir), deps);
+    const resolver = makeResolver(makeSession(baseDir), deps);
     const ctx = makeNotifyCtx();
 
     assert.throws(
@@ -148,7 +213,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
     const roadmapPath = join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     class FakePermError extends Error {}
     const deps = makeDeps({
-      resolveMilestoneFile: (_base, _mid, type) =>
+      resolveMilestoneFile: (_base: string, _mid: string, type: string) =>
         type === "ROADMAP" ? roadmapPath : null,
       readFileSync: () => "# M001\n",
       mergeMilestoneToMain: () => {
@@ -156,7 +221,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
       },
     });
 
-    const resolver = new WorktreeResolver(makeSession(baseDir), deps);
+    const resolver = makeResolver(makeSession(baseDir), deps);
     const ctx = makeNotifyCtx();
 
     assert.throws(
@@ -174,13 +239,13 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
   test("successful merge does not throw", () => {
     const roadmapPath = join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     const deps = makeDeps({
-      resolveMilestoneFile: (_base, _mid, type) =>
+      resolveMilestoneFile: (_base: string, _mid: string, type: string) =>
         type === "ROADMAP" ? roadmapPath : null,
       readFileSync: () => "# M001\n",
       mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: true }),
     });
 
-    const resolver = new WorktreeResolver(makeSession(baseDir), deps);
+    const resolver = makeResolver(makeSession(baseDir), deps);
     const ctx = makeNotifyCtx();
 
     // Should not throw — the success path.

package/src/resources/extensions/gsd/tests/migrate-writer-integration.test.ts

@@ -13,6 +13,9 @@ import { parseRoadmap, parsePlan } from '../parsers-legacy.ts';
 import { parseSummary } from '../files.ts';
 import { deriveState } from '../state.ts';
 import { invalidateAllCaches } from '../cache.ts';
+import { ensureDbOpen } from '../bootstrap/dynamic-tools.ts';
+import { closeDatabase, getAllMilestones } from '../gsd-db.ts';
+import { importWrittenMigrationToDb } from '../migrate/command.ts';
 import type {
   GSDProject,
   GSDMilestone,
@@ -250,6 +253,51 @@ test('Scenario 1: Incomplete project — write, parse, deriveState', async () =>
     }
 });
 
+test('Scenario 1b: written migration imports into authoritative DB state', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-writer-db-import-'));
+    try {
+      const project = buildIncompleteProject();
+      await writeGSDDirectory(project, base);
+
+      assert.equal(await ensureDbOpen(base), true, 'db import: ensureDbOpen creates authoritative DB');
+
+      invalidateAllCaches();
+      const before = await deriveState(base);
+      assert.equal(before.activeMilestone, null, 'db import: markdown-only migration is invisible before DB import');
+
+      const imported = await importWrittenMigrationToDb(base);
+      assert.deepStrictEqual(imported.hierarchy, { milestones: 1, slices: 2, tasks: 3 }, 'db import: hierarchy counts');
+
+      invalidateAllCaches();
+      const after = await deriveState(base);
+      assert.deepStrictEqual(after.phase, 'executing', 'db import: deriveState sees imported DB hierarchy');
+      assert.deepStrictEqual(after.activeMilestone?.id, 'M001', 'db import: active milestone');
+      assert.deepStrictEqual(after.activeSlice?.id, 'S02', 'db import: active slice');
+      assert.deepStrictEqual(after.activeTask?.id, 'T03', 'db import: active task');
+    } finally {
+      closeDatabase();
+      rmSync(base, { recursive: true, force: true });
+    }
+});
+
+test('Scenario 1c: DB import verification fails when preview counts do not match', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-writer-db-check-'));
+    try {
+      const project = buildIncompleteProject();
+      await writeGSDDirectory(project, base);
+
+      const preview = generatePreview(project);
+      await assert.rejects(
+        () => importWrittenMigrationToDb(base, { ...preview, totalTasks: preview.totalTasks + 1 }),
+        /migration DB import verification failed: tasks 3\/4/,
+      );
+      assert.deepStrictEqual(getAllMilestones(), [], 'db import: failed verification rolls back hierarchy rewrite');
+    } finally {
+      closeDatabase();
+      rmSync(base, { recursive: true, force: true });
+    }
+});
+
   // ─── Scenario 2: Fully complete project ────────────────────────────────
 
 test('Scenario 2: Fully complete project — deriveState phase', async () => {

package/src/resources/extensions/gsd/tests/migration-auto-check.test.ts

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+
+import { ensureDbOpen } from "../bootstrap/dynamic-tools.ts";
+import {
+  _getAdapter,
+  closeDatabase,
+  getAllMilestones,
+  getSliceTasks,
+} from "../gsd-db.ts";
+import {
+  autoImportMarkdownHierarchyIfDbMismatch,
+  countMarkdownHierarchy,
+} from "../migration-auto-check.ts";
+import { writeGSDDirectory } from "../migrate/writer.ts";
+import type { GSDProject } from "../migrate/types.ts";
+
+function makeBase(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-migration-auto-check-"));
+}
+
+function cleanup(base: string): void {
+  closeDatabase();
+  rmSync(base, { recursive: true, force: true });
+}
+
+function projectFixture(): GSDProject {
+  return {
+    projectContent: "# Legacy Project\n",
+    decisionsContent: "",
+    requirements: [],
+    milestones: [
+      {
+        id: "M001",
+        title: "Legacy Milestone",
+        vision: "Carry forward previous work",
+        successCriteria: ["Existing task is visible"],
+        research: null,
+        boundaryMap: [],
+        slices: [
+          {
+            id: "S01",
+            title: "Legacy Slice",
+            risk: "medium",
+            depends: [],
+            done: false,
+            demo: "Legacy slice demo",
+            goal: "Legacy slice demo",
+            research: null,
+            summary: null,
+            tasks: [
+              {
+                id: "T01",
+                title: "Legacy Task",
+                description: "Task carried from markdown",
+                done: false,
+                estimate: "",
+                files: ["src/index.ts"],
+                mustHaves: [],
+                summary: null,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+test("migration auto-check imports markdown hierarchy when DB is empty", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base);
+    assert.deepEqual(countMarkdownHierarchy(base), { milestones: 1, slices: 1, tasks: 1 });
+
+    assert.equal(await ensureDbOpen(base), true);
+    assert.equal(getAllMilestones().length, 0, "fresh authoritative DB starts empty");
+
+    const result = await autoImportMarkdownHierarchyIfDbMismatch(base);
+    assert.equal(result.action, "imported");
+    assert.equal(result.reason, "db-empty");
+    assert.deepEqual(result.afterDb, { milestones: 1, slices: 1, tasks: 1 });
+    assert.equal(getAllMilestones().length, 1);
+    assert.equal(getSliceTasks("M001", "S01").length, 1);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check repairs DB hierarchy count mismatch", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base);
+    await autoImportMarkdownHierarchyIfDbMismatch(base);
+
+    _getAdapter()!.prepare("DELETE FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?").run("M001", "S01", "T01");
+    assert.equal(getSliceTasks("M001", "S01").length, 0, "test fixture simulates stale DB task count");
+
+    const result = await autoImportMarkdownHierarchyIfDbMismatch(base);
+    assert.equal(result.action, "imported");
+    assert.equal(result.reason, "count-mismatch");
+    assert.deepEqual(result.beforeDb, { milestones: 1, slices: 1, tasks: 0 });
+    assert.deepEqual(result.afterDb, { milestones: 1, slices: 1, tasks: 1 });
+    assert.equal(getSliceTasks("M001", "S01").length, 1);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check leaves matching DB hierarchy alone", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base);
+    await autoImportMarkdownHierarchyIfDbMismatch(base);
+
+    const result = await autoImportMarkdownHierarchyIfDbMismatch(base);
+    assert.equal(result.action, "none");
+    assert.equal(result.reason, "in-sync");
+    assert.deepEqual(result.markdown, { milestones: 1, slices: 1, tasks: 1 });
+    assert.deepEqual(result.afterDb, { milestones: 1, slices: 1, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/milestone-merge-stash-restore.test.ts

@@ -0,0 +1,267 @@
+// GSD-2 + src/resources/extensions/gsd/tests/milestone-merge-stash-restore.test.ts
+// Regression: postflight stash pop must run even when mergeAndExit throws.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { _runMilestoneMergeWithStashRestore } from "../auto/phases.js";
+import type { IterationContext } from "../auto/types.js";
+import { MergeConflictError } from "../git-service.js";
+import type {
+  PostflightResult,
+  PreflightResult,
+} from "../clean-root-preflight.js";
+
+interface CallLog {
+  preflightCalls: number;
+  mergeCalls: number;
+  postflightCalls: number;
+  stopAutoCalls: Array<string | undefined>;
+  notifyCalls: Array<{ message: string; level: string }>;
+  milestoneMergedInPhases: boolean;
+}
+
+function buildIc(opts: {
+  preflightResult: PreflightResult;
+  mergeBehavior: "succeed" | (() => never);
+  postflightResult: PostflightResult;
+}): { ic: IterationContext; log: CallLog } {
+  const log: CallLog = {
+    preflightCalls: 0,
+    mergeCalls: 0,
+    postflightCalls: 0,
+    stopAutoCalls: [],
+    notifyCalls: [],
+    milestoneMergedInPhases: false,
+  };
+
+  const session = {
+    basePath: "/tmp/proj",
+    originalBasePath: "/tmp/proj",
+    get milestoneMergedInPhases() {
+      return log.milestoneMergedInPhases;
+    },
+    set milestoneMergedInPhases(v: boolean) {
+      log.milestoneMergedInPhases = v;
+    },
+  };
+
+  const ctx = {
+    ui: {
+      notify: (message: string, level: string) => {
+        log.notifyCalls.push({ message, level });
+      },
+    },
+  };
+
+  const deps = {
+    preflightCleanRoot: () => {
+      log.preflightCalls += 1;
+      return opts.preflightResult;
+    },
+    postflightPopStash: () => {
+      log.postflightCalls += 1;
+      return opts.postflightResult;
+    },
+    resolver: {
+      mergeAndExit: () => {
+        log.mergeCalls += 1;
+        if (opts.mergeBehavior !== "succeed") {
+          opts.mergeBehavior();
+        }
+      },
+    },
+    lifecycle: {
+      exitMilestone: (_mid: string, exitOpts: { merge: boolean }) => {
+        log.mergeCalls += 1;
+        if (opts.mergeBehavior === "succeed") {
+          return { ok: true, merged: exitOpts.merge, codeFilesChanged: false };
+        }
+        try {
+          opts.mergeBehavior();
+          return { ok: true, merged: exitOpts.merge, codeFilesChanged: false };
+        } catch (err) {
+          // Mirror Lifecycle's typed-result wrapping of MergeConflictError
+          // and other thrown values per worktree-lifecycle.exitMilestone.
+          const isMergeConflict =
+            err !== null &&
+            typeof err === "object" &&
+            err !== undefined &&
+            (err as { name?: string }).name === "MergeConflictError";
+          return {
+            ok: false,
+            reason: isMergeConflict ? "merge-conflict" : "teardown-failed",
+            cause: err,
+          } as const;
+        }
+      },
+    },
+    stopAuto: async (_c?: unknown, _p?: unknown, reason?: string) => {
+      log.stopAutoCalls.push(reason);
+    },
+  };
+
+  const ic = {
+    ctx,
+    pi: {},
+    s: session,
+    deps,
+  } as unknown as IterationContext;
+
+  return { ic, log };
+}
+
+const STASH_PUSHED: PreflightResult = {
+  stashPushed: true,
+  stashMarker: "gsd-preflight-stash:M002:42:1700000000000:abc",
+  summary: "Stashed uncommitted changes before merge (milestone M002).",
+};
+
+const STASH_NOT_PUSHED: PreflightResult = {
+  stashPushed: false,
+  summary: "",
+};
+
+const POP_OK: PostflightResult = {
+  restored: true,
+  needsManualRecovery: false,
+  message: "Restored stashed changes after milestone M002 merge.",
+  stashRef: "stash@{0}",
+};
+
+const POP_NEEDS_RECOVERY: PostflightResult = {
+  restored: false,
+  needsManualRecovery: true,
+  message: "git stash pop stash@{0} failed: conflict in lib/models.ts",
+};
+
+test("happy path: merge succeeds and stash is popped", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: "succeed",
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.equal(result, null, "happy path returns null (loop continues)");
+  assert.equal(log.preflightCalls, 1);
+  assert.equal(log.mergeCalls, 1);
+  assert.equal(log.postflightCalls, 1, "postflight pop must run on success");
+  assert.equal(log.stopAutoCalls.length, 0, "no stopAuto on happy path");
+  assert.equal(log.milestoneMergedInPhases, true, "merge flag set");
+});
+
+test("regression #5538-followup: postflight pop runs even when mergeAndExit throws non-conflict error", async () => {
+  // The original bug: when mergeAndExit threw, the catch block called
+  // stopAuto + return break BEFORE postflight pop ran. The user's
+  // gsd-preflight-stash:M00x stash was orphaned. This test exercises that
+  // exact scenario and asserts the pop is now invoked.
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: () => {
+      throw new Error("native git merge failed: index lock present");
+    },
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, { action: "break", reason: "merge-failed" });
+  assert.equal(log.mergeCalls, 1);
+  assert.equal(
+    log.postflightCalls,
+    1,
+    "postflight pop must run even on merge failure (was the bug)",
+  );
+  assert.equal(log.stopAutoCalls.length, 1);
+  assert.match(log.stopAutoCalls[0] ?? "", /Merge error on milestone M002/);
+  assert.equal(
+    log.milestoneMergedInPhases,
+    false,
+    "merge flag must NOT be set when merge throws",
+  );
+});
+
+test("regression #5538-followup: postflight pop runs even when mergeAndExit throws MergeConflictError", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: () => {
+      throw new MergeConflictError(
+        ["lib/models.ts", "app/page.tsx"],
+        "squash",
+        "milestone/M002",
+        "main",
+      );
+    },
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, { action: "break", reason: "merge-conflict" });
+  assert.equal(log.mergeCalls, 1);
+  assert.equal(
+    log.postflightCalls,
+    1,
+    "postflight pop must run on merge conflict (was the bug)",
+  );
+  assert.equal(log.stopAutoCalls.length, 1);
+  assert.match(log.stopAutoCalls[0] ?? "", /Merge conflict on milestone M002/);
+});
+
+test("clean tree: no stash to pop, merge succeeds, no pop attempted", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_NOT_PUSHED,
+    mergeBehavior: "succeed",
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.equal(result, null);
+  assert.equal(log.postflightCalls, 0, "no pop when nothing was stashed");
+  assert.equal(log.milestoneMergedInPhases, true);
+});
+
+test("merge succeeds but stash pop needs manual recovery -> postflight-stash-restore-failed break", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: "succeed",
+    postflightResult: POP_NEEDS_RECOVERY,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, {
+    action: "break",
+    reason: "postflight-stash-restore-failed",
+  });
+  assert.equal(log.postflightCalls, 1);
+  assert.equal(log.stopAutoCalls.length, 1);
+  assert.match(
+    log.stopAutoCalls[0] ?? "",
+    /Post-merge stash restore failed for milestone M002/,
+  );
+});
+
+test("merge error is reported even when stash pop also failed (merge-error takes priority)", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: () => {
+      throw new Error("network unreachable during push");
+    },
+    postflightResult: POP_NEEDS_RECOVERY,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, { action: "break", reason: "merge-failed" });
+  assert.equal(log.postflightCalls, 1, "postflight pop still attempted");
+  assert.equal(log.stopAutoCalls.length, 1, "stopAuto called once, not twice");
+  assert.match(
+    log.stopAutoCalls[0] ?? "",
+    /Merge error/,
+    "stopAuto message reflects merge error, not stash failure",
+  );
+});