gsd-pi 2.80.0-dev.2be7caf18 → 2.80.0-dev.3065f7bfa

package/src/resources/extensions/gsd/tests/dispatch-rule-coverage.test.ts

@@ -0,0 +1,313 @@
+// gsd-2 / dispatch rule coverage canary test
+//
+// Iterates DISPATCH_RULES in order against representative GSDState stubs and
+// asserts that the first matching rule has the expected name and unitType
+// (mirroring auto-dispatch's first-match-wins semantics). The goal is a
+// canary: if a future PR adds a new rule in the wrong position and steals
+// a match from an existing one, this test fails.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { DISPATCH_RULES } from "../auto-dispatch.ts";
+import type { DispatchContext, DispatchAction } from "../auto-dispatch.ts";
+import type { GSDState } from "../types.ts";
+
+// ─── State helpers ────────────────────────────────────────────────────────
+
+function makeState(overrides: Partial<GSDState> = {}): GSDState {
+  return {
+    activeMilestone: { id: "M001", title: "Test Milestone" },
+    activeSlice: null,
+    activeTask: null,
+    phase: "pre-planning",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "",
+    registry: [],
+    ...overrides,
+  };
+}
+
+function makeCtx(basePath: string, state: GSDState, mid = "M001"): DispatchContext {
+  return {
+    basePath,
+    mid,
+    midTitle: "Test Milestone",
+    state,
+    prefs: undefined,
+  };
+}
+
+// ─── Disk scaffold helpers ────────────────────────────────────────────────
+
+function writeMilestoneFile(basePath: string, mid: string, suffix: string, content = "stub\n"): void {
+  const dir = join(basePath, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-${suffix}.md`), content);
+}
+
+function writeSliceFile(
+  basePath: string,
+  mid: string,
+  sid: string,
+  suffix: string,
+  content = "stub\n",
+): void {
+  const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${sid}-${suffix}.md`), content);
+}
+
+function writeTaskPlan(basePath: string, mid: string, sid: string, tid: string): void {
+  const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${tid}-PLAN.md`), `# ${tid}\n\n## Steps\n- [ ] Step\n`);
+}
+
+// ─── Rule evaluation ──────────────────────────────────────────────────────
+
+interface MatchEntry {
+  ruleName: string;
+  result: DispatchAction;
+}
+
+// First-match-wins semantics: walks DISPATCH_RULES in order and stops at the
+// first non-null result. This mirrors the production resolver and is the
+// canary against rule reordering or shadowing.
+async function findFirstMatch(ctx: DispatchContext): Promise<MatchEntry | null> {
+  for (const rule of DISPATCH_RULES) {
+    const result = await rule.match(ctx);
+    if (result) return { ruleName: rule.name, result };
+  }
+  return null;
+}
+
+function assertMatch(
+  match: MatchEntry | null,
+  expected: { ruleName: string; action: DispatchAction["action"]; unitType?: string },
+  scenario: string,
+): void {
+  assert.ok(match, `${scenario}: no rule matched`);
+  assert.equal(match.ruleName, expected.ruleName, `${scenario}: matched rule mismatch`);
+  assert.equal(match.result.action, expected.action, `${scenario}: action mismatch`);
+  if (expected.action === "dispatch" && expected.unitType) {
+    assert.ok(
+      match.result.action === "dispatch" && match.result.unitType === expected.unitType,
+      `${scenario}: unitType mismatch (got ${
+        match.result.action === "dispatch" ? match.result.unitType : match.result.action
+      })`,
+    );
+  }
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────
+
+test("dispatch-rule-coverage: escalating-task → stop (info)", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-esc-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  const ctx = makeCtx(
+    tmp,
+    makeState({
+      phase: "escalating-task",
+      activeSlice: { id: "S01", title: "Slice" },
+      nextAction: "Resolve escalation X",
+    }),
+  );
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    { ruleName: "escalating-task → pause-for-escalation", action: "stop" },
+    "escalating-task",
+  );
+});
+
+test("dispatch-rule-coverage: pre-planning, no CONTEXT → discuss-milestone", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-disc-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  // Bare milestone dir, no CONTEXT/RESEARCH/ROADMAP files.
+  mkdirSync(join(tmp, ".gsd", "milestones", "M001"), { recursive: true });
+
+  const ctx = makeCtx(tmp, makeState({ phase: "pre-planning" }));
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    {
+      ruleName: "pre-planning (no context) → discuss-milestone",
+      action: "dispatch",
+      unitType: "discuss-milestone",
+    },
+    "pre-planning no context",
+  );
+});
+
+test("dispatch-rule-coverage: pre-planning, has CONTEXT, no RESEARCH → research-milestone", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-res-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  writeMilestoneFile(tmp, "M001", "CONTEXT", "# Context\n");
+
+  const ctx = makeCtx(tmp, makeState({ phase: "pre-planning" }));
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    {
+      ruleName: "pre-planning (no research) → research-milestone",
+      action: "dispatch",
+      unitType: "research-milestone",
+    },
+    "pre-planning no research",
+  );
+});
+
+test("dispatch-rule-coverage: pre-planning, has CONTEXT + RESEARCH → plan-milestone", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-plan-m-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  writeMilestoneFile(tmp, "M001", "CONTEXT", "# Context\n");
+  writeMilestoneFile(tmp, "M001", "RESEARCH", "# Research\n");
+
+  const ctx = makeCtx(tmp, makeState({ phase: "pre-planning" }));
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    {
+      ruleName: "pre-planning (has research) → plan-milestone",
+      action: "dispatch",
+      unitType: "plan-milestone",
+    },
+    "pre-planning has research",
+  );
+});
+
+test("dispatch-rule-coverage: planning with active slice and skip_research → plan-slice", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-plan-s-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  writeMilestoneFile(tmp, "M001", "CONTEXT", "# Context\n");
+  writeMilestoneFile(tmp, "M001", "ROADMAP", "# Roadmap\n");
+
+  const state = makeState({
+    phase: "planning",
+    activeSlice: { id: "S01", title: "First Slice" },
+  });
+  const ctx: DispatchContext = {
+    basePath: tmp,
+    mid: "M001",
+    midTitle: "Test Milestone",
+    state,
+    // Skip slice research so the parallel/single research rules fall through.
+    prefs: { phases: { skip_slice_research: true } } as DispatchContext["prefs"],
+  };
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    {
+      ruleName: "planning → plan-slice",
+      action: "dispatch",
+      unitType: "plan-slice",
+    },
+    "planning → plan-slice",
+  );
+});
+
+test("dispatch-rule-coverage: executing with task plan present → execute-task", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-exec-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  writeMilestoneFile(tmp, "M001", "CONTEXT", "# Context\n");
+  writeSliceFile(tmp, "M001", "S01", "PLAN", "# Plan\n");
+  writeTaskPlan(tmp, "M001", "S01", "T01");
+
+  const state = makeState({
+    phase: "executing",
+    activeSlice: { id: "S01", title: "First Slice" },
+    activeTask: { id: "T01", title: "First Task" },
+  });
+  // Disable reactive dispatch so the parallel batching rule falls through.
+  const ctx: DispatchContext = {
+    basePath: tmp,
+    mid: "M001",
+    midTitle: "Test Milestone",
+    state,
+    prefs: { reactive_execution: { enabled: false } } as DispatchContext["prefs"],
+  };
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    {
+      ruleName: "executing → execute-task",
+      action: "dispatch",
+      unitType: "execute-task",
+    },
+    "executing → execute-task",
+  );
+});
+
+test("dispatch-rule-coverage: summarizing → complete-slice", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-sum-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  // Rule "execution-entry phase (no context)" fires for summarizing if CONTEXT
+  // is missing — write it so the summarizing rule wins.
+  writeMilestoneFile(tmp, "M001", "CONTEXT", "# Context\n");
+
+  const ctx = makeCtx(
+    tmp,
+    makeState({
+      phase: "summarizing",
+      activeSlice: { id: "S01", title: "First Slice" },
+    }),
+  );
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    {
+      ruleName: "summarizing → complete-slice",
+      action: "dispatch",
+      unitType: "complete-slice",
+    },
+    "summarizing → complete-slice",
+  );
+});
+
+test("dispatch-rule-coverage: complete phase → stop", async (t) => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-disp-cov-done-"));
+  t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+  const ctx = makeCtx(
+    tmp,
+    makeState({
+      phase: "complete",
+      activeMilestone: null,
+      lastCompletedMilestone: { id: "M001", title: "Test Milestone" },
+    }),
+  );
+  const match = await findFirstMatch(ctx);
+  assertMatch(
+    match,
+    { ruleName: "complete → stop", action: "stop" },
+    "complete → stop",
+  );
+});
+
+// ─── Ordering canary: every scenario above resolves to exactly one rule ────
+
+test("dispatch-rule-coverage: rule registry has the expected size", () => {
+  // Sanity check that complements the per-state assertions: if someone adds a
+  // new rule, this number changes — prompting them to add a state stub above.
+  // Exact count is a brittle but useful canary; update when adding rules
+  // intentionally.
+  assert.equal(
+    DISPATCH_RULES.length,
+    29,
+    `DISPATCH_RULES length changed (got ${DISPATCH_RULES.length}). ` +
+      "If you added a rule, add a state stub to dispatch-rule-coverage.test.ts " +
+      "and update this expected count.",
+  );
+});

package/src/resources/extensions/gsd/tests/execute-task-rendering.test.ts

@@ -39,6 +39,7 @@ test("execute-task prompt renders compact execution and completion gates", async
     taskPlanPath: ".gsd/milestones/M001/slices/S01/tasks/T01-PLAN.md",
     priorTaskLines: "- None",
     skillActivation: "Load relevant skills.",
+    inlinedTemplates: "### Output Template: Task Summary\nSource: `templates/task-summary.md`",
     templatesDir: join(fixtureRoot, "templates"),
     taskSummaryTemplatePath: "C:\\Users\\Test\\.gsd\\agent\\extensions\\gsd\\templates\\task-summary.md",
     verificationBudget: "~10K chars",
@@ -46,12 +47,14 @@ test("execute-task prompt renders compact execution and completion gates", async
   });
 
   assert.match(prompt, /You execute\./);
-  assert.match(prompt, /Call `memory_query`/);
+  assert.match(prompt, /Call `memory_query`.*only when no injected memory block exists/s);
   assert.match(prompt, /Before any `Write` that creates an artifact or output file/);
   assert.match(prompt, /Build real behavior/);
   assert.match(prompt, /Background process rule/);
   assert.match(prompt, /blocker_discovered: true/);
-  assert.match(prompt, /C:\\Users\\Test\\.gsd\\agent\\extensions\\gsd\\templates\\task-summary\.md/);
+  assert.match(prompt, /Use the inlined Task Summary template below/);
+  assert.match(prompt, /Read `C:\\Users\\Test\\.gsd\\agent\\extensions\\gsd\\templates\\task-summary\.md` only if the inlined template is absent or visibly truncated/);
+  assert.match(prompt, /### Output Template: Task Summary/);
   assert.doesNotMatch(prompt, /\{\{templatesDir\}\}\/task-summary\.md/);
   assert.match(prompt, /Call `gsd_task_complete`/);
   assert.match(prompt, /Do not run git commands/);

package/src/resources/extensions/gsd/tests/fast-forward-reused-milestone-branch.test.ts

@@ -0,0 +1,219 @@
+// GSD-2 + src/resources/extensions/gsd/tests/fast-forward-reused-milestone-branch.test.ts
+// Regression: when createAutoWorktree reuses an existing milestone branch,
+// it must be fast-forwarded onto integration so the next milestone forks
+// from up-to-date code (#5538-followup).
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+import {
+  fastForwardReusedMilestoneBranchIfSafe,
+  _isBranchCheckedOutElsewhere,
+} from "../auto-worktree.js";
+
+const NO_PROMPT_ENV = {
+  ...process.env,
+  GIT_TERMINAL_PROMPT: "0",
+  GIT_AUTHOR_NAME: "test",
+  GIT_AUTHOR_EMAIL: "test@example.com",
+  GIT_COMMITTER_NAME: "test",
+  GIT_COMMITTER_EMAIL: "test@example.com",
+};
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: NO_PROMPT_ENV,
+  });
+}
+
+function rev(cwd: string, ref: string): string {
+  return git(cwd, "rev-parse", ref).trim();
+}
+
+describe("fastForwardReusedMilestoneBranchIfSafe", () => {
+  let repo: string;
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), "ff-reused-branch-"));
+    git(repo, "init", "-q", "-b", "main");
+    git(repo, "config", "user.email", "test@example.com");
+    git(repo, "config", "user.name", "test");
+    writeFileSync(join(repo, "seed.txt"), "seed\n");
+    git(repo, "add", "seed.txt");
+    git(repo, "commit", "-q", "-m", "initial");
+  });
+
+  afterEach(() => {
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  test("fast-forwards a milestone branch that is strictly behind integration (regression: stale base)", () => {
+    // Create milestone/M001 from main's initial commit, then advance main.
+    git(repo, "branch", "milestone/M001");
+    const m001Initial = rev(repo, "milestone/M001");
+
+    writeFileSync(join(repo, "seed.txt"), "advanced\n");
+    git(repo, "add", "seed.txt");
+    git(repo, "commit", "-q", "-m", "main moved forward");
+    const mainTip = rev(repo, "main");
+
+    assert.notEqual(m001Initial, mainTip, "main must be ahead before the test");
+
+    fastForwardReusedMilestoneBranchIfSafe(repo, "M001", "milestone/M001");
+
+    assert.equal(
+      rev(repo, "milestone/M001"),
+      mainTip,
+      "milestone/M001 must be fast-forwarded to main's tip",
+    );
+  });
+
+  test("does not touch a milestone branch that has its own commits ahead", () => {
+    // Branch from main, add a unique commit, then advance main.
+    git(repo, "checkout", "-q", "-b", "milestone/M001");
+    writeFileSync(join(repo, "milestone-only.txt"), "milestone work\n");
+    git(repo, "add", "milestone-only.txt");
+    git(repo, "commit", "-q", "-m", "M001 work");
+    const milestoneTip = rev(repo, "milestone/M001");
+
+    git(repo, "checkout", "-q", "main");
+    writeFileSync(join(repo, "seed.txt"), "advanced\n");
+    git(repo, "add", "seed.txt");
+    git(repo, "commit", "-q", "-m", "main moved forward");
+
+    fastForwardReusedMilestoneBranchIfSafe(repo, "M001", "milestone/M001");
+
+    assert.equal(
+      rev(repo, "milestone/M001"),
+      milestoneTip,
+      "diverged milestone branch must NOT be touched (would lose work)",
+    );
+  });
+
+  test("is a no-op when milestone branch is already up-to-date with main", () => {
+    git(repo, "branch", "milestone/M001");
+    const before = rev(repo, "milestone/M001");
+
+    fastForwardReusedMilestoneBranchIfSafe(repo, "M001", "milestone/M001");
+
+    assert.equal(rev(repo, "milestone/M001"), before, "ref must not move");
+  });
+
+  test("does nothing when the milestone branch does not exist", () => {
+    // Should silently return — no error, no side effects.
+    assert.doesNotThrow(() =>
+      fastForwardReusedMilestoneBranchIfSafe(repo, "M999", "milestone/M999"),
+    );
+  });
+
+  test("does nothing in a non-git directory", () => {
+    const nonRepo = mkdtempSync(join(tmpdir(), "ff-not-a-repo-"));
+    try {
+      assert.doesNotThrow(() =>
+        fastForwardReusedMilestoneBranchIfSafe(nonRepo, "M001", "milestone/M001"),
+      );
+    } finally {
+      rmSync(nonRepo, { recursive: true, force: true });
+    }
+  });
+
+  test("skips fast-forward when branch is checked out in another worktree (peer-review regression)", () => {
+    // Codex peer review caught: `nativeUpdateRef` succeeds even when the
+    // branch is checked out in a linked worktree, leaving that worktree's
+    // HEAD inconsistent with its index/work tree. The fix calls
+    // `nativeWorktreeList` first and skips the FF if any worktree owns the
+    // target branch. This test sets up the exact scenario.
+    git(repo, "branch", "milestone/M001");
+    const m001Initial = rev(repo, "milestone/M001");
+
+    // Add a linked worktree that checks out milestone/M001.
+    const wtPath = join(repo, "..", `${basename(repo)}-wt`);
+    git(repo, "worktree", "add", wtPath, "milestone/M001");
+
+    // Advance main so a fast-forward would otherwise apply.
+    writeFileSync(join(repo, "seed.txt"), "advanced\n");
+    git(repo, "add", "seed.txt");
+    git(repo, "commit", "-q", "-m", "main moved forward");
+
+    try {
+      fastForwardReusedMilestoneBranchIfSafe(repo, "M001", "milestone/M001");
+
+      assert.equal(
+        rev(repo, "milestone/M001"),
+        m001Initial,
+        "milestone/M001 must NOT move while a linked worktree has it checked out",
+      );
+    } finally {
+      git(repo, "worktree", "remove", "--force", wtPath);
+      rmSync(wtPath, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("_isBranchCheckedOutElsewhere", () => {
+  let repo: string;
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), "is-checked-out-"));
+    git(repo, "init", "-q", "-b", "main");
+    git(repo, "config", "user.email", "test@example.com");
+    git(repo, "config", "user.name", "test");
+    writeFileSync(join(repo, "seed.txt"), "seed\n");
+    git(repo, "add", "seed.txt");
+    git(repo, "commit", "-q", "-m", "initial");
+  });
+
+  afterEach(() => {
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  test("returns true when branch is checked out in a linked worktree", () => {
+    git(repo, "branch", "milestone/M001");
+    const wtPath = join(repo, "..", `${basename(repo)}-wt`);
+    git(repo, "worktree", "add", wtPath, "milestone/M001");
+    try {
+      assert.equal(_isBranchCheckedOutElsewhere(repo, "milestone/M001"), true);
+    } finally {
+      git(repo, "worktree", "remove", "--force", wtPath);
+      rmSync(wtPath, { recursive: true, force: true });
+    }
+  });
+
+  test("returns true when branch is checked out in the main worktree itself", () => {
+    // The default checkout. `git worktree list --porcelain` reports the
+    // primary worktree too, so a branch checked out there counts as
+    // "checked out elsewhere" relative to a fresh ref update intent.
+    git(repo, "checkout", "-q", "-b", "milestone/M002");
+    assert.equal(_isBranchCheckedOutElsewhere(repo, "milestone/M002"), true);
+  });
+
+  test("returns false when branch exists but is not checked out anywhere", () => {
+    git(repo, "branch", "milestone/M003");
+    assert.equal(_isBranchCheckedOutElsewhere(repo, "milestone/M003"), false);
+  });
+
+  test("returns false for an unknown branch in a clean repo", () => {
+    assert.equal(_isBranchCheckedOutElsewhere(repo, "milestone/M999"), false);
+  });
+
+  test("returns false on a non-git directory (empty worktree list)", () => {
+    // nativeWorktreeList does not throw on a non-repo — it returns []. The
+    // parent function `fastForwardReusedMilestoneBranchIfSafe` never reaches
+    // this code path on a non-repo because `nativeBranchExists` short-circuits
+    // earlier. Documenting actual behavior so future readers don't expect a
+    // fail-safe `true` here.
+    const nonRepo = mkdtempSync(join(tmpdir(), "is-checked-out-not-repo-"));
+    try {
+      assert.equal(_isBranchCheckedOutElsewhere(nonRepo, "milestone/M001"), false);
+    } finally {
+      rmSync(nonRepo, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/finalize-survivor-branch.test.ts

@@ -0,0 +1,132 @@
+// GSD-2 + src/resources/extensions/gsd/tests/finalize-survivor-branch.test.ts
+// Regression: a thrown error from `_mergeBranchMode` (made fail-loud in
+// commit 68ef58a3c) must be caught at the survivor-finalize call site so
+// bootstrap surfaces an error notify instead of an unhandled exception
+// propagating to the slash-command caller (#5549 post-merge audit, R2).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { _finalizeSurvivorBranch } from "../auto-start.js";
+import type { WorktreeResolver } from "../worktree-resolver.js";
+
+interface FakeResolverState {
+  mergeCalls: Array<{ milestoneId: string }>;
+  shouldThrow?: unknown;
+}
+
+function fakeResolver(state: FakeResolverState): WorktreeResolver {
+  return {
+    mergeAndExit: (milestoneId: string) => {
+      state.mergeCalls.push({ milestoneId });
+      if (state.shouldThrow) throw state.shouldThrow;
+    },
+  } as unknown as WorktreeResolver;
+}
+
+interface FakeUiState {
+  notifications: Array<{ message: string; level: string }>;
+}
+
+function fakeUi(state: FakeUiState): {
+  notify: (msg: string, level?: "info" | "warning" | "error" | "success") => void;
+} {
+  return {
+    notify: (message: string, level?: "info" | "warning" | "error" | "success") => {
+      state.notifications.push({ message, level: level ?? "info" });
+    },
+  };
+}
+
+test("happy path: survivor merge runs, returns merged:true, info notify announces the merge", () => {
+  const resolverState: FakeResolverState = { mergeCalls: [] };
+  const uiState: FakeUiState = { notifications: [] };
+  const result = _finalizeSurvivorBranch(
+    fakeResolver(resolverState),
+    "M001",
+    fakeUi(uiState),
+  );
+
+  assert.deepEqual(result, { merged: true });
+  assert.deepEqual(resolverState.mergeCalls, [{ milestoneId: "M001" }]);
+  assert.equal(uiState.notifications.length, 1);
+  assert.equal(uiState.notifications[0].level, "info");
+  assert.match(
+    uiState.notifications[0].message,
+    /Milestone M001 is complete but branch\/worktree was not finalized/,
+  );
+});
+
+test("regression: thrown error from mergeAndExit (e.g. wrong-branch) is caught and surfaced as error notify", () => {
+  // Pre-PR-5549 commit 5: `_mergeBranchMode` returned false silently.
+  // Post-commit 5: it throws. Without this fix, the throw at auto-start.ts
+  // line ~810 would bubble through `bootstrapAutoSession` to
+  // `startAutoDetached`'s top-level .catch as an unhandled-exception log
+  // — observable as a stack trace instead of a clean failure notification.
+  const boom = new Error("dirty working tree blocks checkout");
+  const resolverState: FakeResolverState = { mergeCalls: [], shouldThrow: boom };
+  const uiState: FakeUiState = { notifications: [] };
+
+  // Must not throw.
+  const result = _finalizeSurvivorBranch(
+    fakeResolver(resolverState),
+    "M001",
+    fakeUi(uiState),
+  );
+
+  assert.equal(result.merged, false);
+  assert.equal(result.error, boom);
+
+  // Two notifies: info (announce) + error (the failure detail).
+  assert.equal(uiState.notifications.length, 2);
+  assert.equal(uiState.notifications[0].level, "info");
+  assert.equal(uiState.notifications[1].level, "error");
+  assert.match(
+    uiState.notifications[1].message,
+    /Survivor-branch finalization for M001 failed/,
+  );
+  assert.match(uiState.notifications[1].message, /dirty working tree blocks checkout/);
+  assert.match(uiState.notifications[1].message, /Resolve manually/);
+});
+
+test("non-Error thrown values are stringified into the user-facing message", () => {
+  const resolverState: FakeResolverState = {
+    mergeCalls: [],
+    shouldThrow: "git lock contention",
+  };
+  const uiState: FakeUiState = { notifications: [] };
+
+  const result = _finalizeSurvivorBranch(
+    fakeResolver(resolverState),
+    "M001",
+    fakeUi(uiState),
+  );
+
+  assert.equal(result.merged, false);
+  assert.equal(result.error, resolverState.shouldThrow);
+  assert.equal(uiState.notifications[1].level, "error");
+  assert.match(uiState.notifications[1].message, /git lock contention/);
+});
+
+test("inner notifications from mergeAndExit's NotifyCtx reach the same UI", () => {
+  // The resolver's NotifyCtx must be wired to ui.notify so messages emitted
+  // inside mergeAndExit (e.g. "Milestone Mxxx merged. Pushed to remote.")
+  // appear in the same UI stream as the outer notifies.
+  const uiState: FakeUiState = { notifications: [] };
+  const ui = fakeUi(uiState);
+
+  const resolver = {
+    mergeAndExit: (_milestoneId: string, ctx: { notify: (msg: string, level?: "info" | "warning" | "error" | "success") => void }) => {
+      ctx.notify("Milestone M001 merged.", "success");
+    },
+  } as unknown as WorktreeResolver;
+
+  const result = _finalizeSurvivorBranch(resolver, "M001", ui);
+
+  assert.equal(result.merged, true);
+  // 1: outer announce
+  // 2: inner success
+  assert.equal(uiState.notifications.length, 2);
+  assert.equal(uiState.notifications[1].level, "success");
+  assert.equal(uiState.notifications[1].message, "Milestone M001 merged.");
+});