gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/tests/auto-mode-guards.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Regression tests for auto-mode guards (#4704 Tier 2 / #4712).
+ *
+ * Validates the defense-in-depth writer asserts in milestone-actions.ts —
+ * parkMilestone, unparkMilestone, and discardMilestone must refuse to run
+ * while auto-mode is active, regardless of the calling dispatch path.
+ */
+import { describe, test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { parkMilestone, unparkMilestone, discardMilestone } from '../milestone-actions.ts';
+import { _setAutoActiveForTest } from '../auto.ts';
+
+function createFixture(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-guard-test-'));
+  const mDir = join(base, '.gsd', 'milestones', 'M001');
+  mkdirSync(mDir, { recursive: true });
+  writeFileSync(join(mDir, 'M001-ROADMAP.md'), '# M001\n', 'utf-8');
+  return base;
+}
+
+describe('auto-mode guards (milestone-actions)', () => {
+  afterEach(() => {
+    _setAutoActiveForTest(false);
+  });
+
+  test('parkMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => parkMilestone(base, 'M001', 'test'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('unparkMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => unparkMilestone(base, 'M001'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('discardMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => discardMilestone(base, 'M001'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('parkMilestone proceeds normally when auto-mode is inactive', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(false);
+      const result = parkMilestone(base, 'M001', 'baseline');
+      assert.ok(result, 'park succeeds when auto is inactive');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/auto-paused-session-validation.test.ts

@@ -39,6 +39,18 @@ test("auto.ts validates milestone before restoring paused session (#1664)", () =
     source.includes('resolveMilestoneFile(base, meta.milestoneId, "SUMMARY")'),
     "auto.ts must check for SUMMARY file to detect completed milestones",
   );
+
+  // Resume path must sanitize paused session file metadata before unlink/recovery.
+  assert.ok(
+    source.includes("normalizeSessionFilePath(meta.sessionFile ?? null)"),
+    "auto.ts must sanitize paused-session metadata sessionFile before using it",
+  );
+
+  // Pause path must sanitize live session file path before persisting metadata.
+  assert.ok(
+    source.includes("normalizeSessionFilePath(ctx?.sessionManager?.getSessionFile() ?? null)"),
+    "auto.ts must sanitize sessionManager getSessionFile output before persisting",
+  );
 });
 
 // ─── Filesystem validation unit tests ───────────────────────────────────────

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

@@ -706,6 +706,79 @@ test("verifyExpectedArtifact complete-milestone passes with impl files (#1703)",
   }
 });
 
+test("verifyExpectedArtifact complete-milestone fails when DB milestone is not complete (#4658)", () => {
+  const base = makeGitBase();
+  try {
+    execFileSync("git", ["checkout", "-b", "feat/ms-db-active"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nverification FAILED — not complete.");
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "app.ts"), "console.log('hello');");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: implementation with failed summary"], { cwd: base, stdio: "ignore" });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+
+    const result = verifyExpectedArtifact("complete-milestone", "M001", base);
+    assert.equal(result, false, "complete-milestone must fail when DB status is not complete");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact complete-milestone passes when DB milestone is complete (#4658)", () => {
+  const base = makeGitBase();
+  try {
+    execFileSync("git", ["checkout", "-b", "feat/ms-db-complete"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nDone.");
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "app.ts"), "console.log('hello');");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: implementation complete"], { cwd: base, stdio: "ignore" });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "complete" });
+
+    const result = verifyExpectedArtifact("complete-milestone", "M001", base);
+    assert.equal(result, true, "complete-milestone should pass when DB status is complete");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact complete-milestone tolerates transient DB lag when SUMMARY is canonical success (#4658)", () => {
+  const base = makeGitBase();
+  try {
+    execFileSync("git", ["checkout", "-b", "feat/ms-db-lag-success"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"),
+      [
+        "---",
+        "id: M001",
+        "status: complete",
+        "---",
+        "",
+        "# M001: Success",
+      ].join("\n"),
+    );
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "app.ts"), "console.log('hello');");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: implementation with stale db"], { cwd: base, stdio: "ignore" });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+
+    const result = verifyExpectedArtifact("complete-milestone", "M001", base);
+    assert.equal(result, true, "canonical success SUMMARY should pass verification during transient DB lag");
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("verifyExpectedArtifact checks pending gate-evaluate artifacts without ESM require failures", () => {
   const base = makeTmpProject();
 
@@ -775,6 +848,55 @@ test("#4414: parallel-research sentinel path does not collide with RESEARCH suff
   }
 });
 
+test("#4068: verifyExpectedArtifact parallel-research treats PARALLEL-BLOCKER as terminal completion", () => {
+  // Regression: when a parallel-research unit times out and the timeout-recovery
+  // machinery writes a PARALLEL-BLOCKER placeholder, verifyExpectedArtifact must
+  // return true so the dispatch loop can advance.  Previously it only returned
+  // true when every slice had a RESEARCH file — meaning a timeout always left
+  // verifyExpectedArtifact returning false, the unit was never cleared from
+  // unitDispatchCount, and the dispatch rule re-fired on the next iteration
+  // (infinite loop, issue #4068 / #4355).
+  const base = makeTmpBase();
+  try {
+    // Write a minimal roadmap
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      [
+        "# M001: Timeout Test",
+        "",
+        "## Slices",
+        "",
+        "- [ ] **S01: Alpha** `risk:low` `depends:[]`",
+        "- [ ] **S02: Beta** `risk:low` `depends:[]`",
+        "",
+      ].join("\n"),
+      "utf-8",
+    );
+
+    // No RESEARCH files written — subagents timed out
+    clearParseCache();
+    invalidateAllCaches();
+
+    // Simulate timeout-recovery writing the PARALLEL-BLOCKER placeholder
+    const blockerPath = resolveExpectedArtifactPath("research-slice", "M001/parallel-research", base);
+    assert.ok(blockerPath, "PARALLEL-BLOCKER path must resolve for parallel-research unit");
+    writeFileSync(blockerPath!, "# BLOCKER — timeout recovery\n\n**Reason**: hard timeout.\n", "utf-8");
+
+    clearParseCache();
+    invalidateAllCaches();
+
+    // After blocker is written, verifyExpectedArtifact must return true
+    // so the dispatch loop treats this unit as complete and moves on.
+    assert.equal(
+      verifyExpectedArtifact("research-slice", "M001/parallel-research", base),
+      true,
+      "#4068: PARALLEL-BLOCKER on disk must satisfy verifyExpectedArtifact so the loop does not re-dispatch",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("#4414: verifyExpectedArtifact parallel-research succeeds when all research-ready slices have RESEARCH", () => {
   const base = makeTmpBase();
   try {

package/src/resources/extensions/gsd/tests/auto-start-bootstrap-await-3420.test.ts

@@ -0,0 +1,141 @@
+/**
+ * auto-start-bootstrap-await-3420.test.ts — Regression test for #3420.
+ *
+ * Bug: In bootstrapAutoSession, when state.phase === "pre-planning" and no
+ * context file exists, showSmartEntry is called to dispatch a discuss workflow.
+ * showSmartEntry calls dispatchWorkflow which calls pi.sendMessage() — a
+ * fire-and-forget call that returns immediately. The LLM discussion runs
+ * asynchronously in a separate turn.
+ *
+ * The bug: after showSmartEntry returns (before the LLM has run), the code
+ * immediately calls invalidateAllCaches() + deriveState() + checks postState.
+ * Since the discussion hasn't run yet, postState.phase is still "pre-planning"
+ * and the context check fails, producing the warning:
+ *   "Discussion completed but milestone context is still missing. Run /gsd to try again."
+ *
+ * The discussion never ran — the warning fires immediately.
+ *
+ * Fix: bootstrapAutoSession must return false (release lock) after showSmartEntry
+ * dispatches the workflow. The checkAutoStartAfterDiscuss callback in guided-flow.ts
+ * already handles re-entering auto-mode when the discussion completes.
+ *
+ * This test verifies the fix by asserting that the pre-planning !hasContext block
+ * does NOT contain a postState phase check after showSmartEntry — it must
+ * return false immediately to let the async dispatch complete.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const sourcePath = join(import.meta.dirname, "..", "auto-start.ts");
+const source = readFileSync(sourcePath, "utf-8");
+
+test("bootstrapAutoSession: pre-planning no-context path does NOT check postState immediately after showSmartEntry (#3420)", () => {
+  // Find the pre-planning block that handles the case where context is missing.
+  // This block dispatches showSmartEntry which is async (fire-and-forget via pi.sendMessage).
+  // After the dispatch, checking postState.phase immediately is premature — the
+  // LLM discussion hasn't run yet. The block should return false instead.
+  const prePlanningNoContextBlock = source.match(
+    /\/\/ Active milestone exists but has no roadmap\s*\n\s*if\s*\(\s*state\.phase\s*===\s*"pre-planning"\s*\)([\s\S]*?)\/\/ Active milestone has CONTEXT-DRAFT/,
+  );
+  assert.ok(
+    !!prePlanningNoContextBlock,
+    "auto-start.ts must have the pre-planning handler block before needs-discussion",
+  );
+
+  const block = prePlanningNoContextBlock![1];
+
+  // The block must call showSmartEntry when !hasContext
+  assert.ok(
+    block.includes("showSmartEntry"),
+    "pre-planning !hasContext block must call showSmartEntry to dispatch the discuss workflow",
+  );
+
+  // FAILING ASSERTION (before fix): after showSmartEntry, the block must NOT
+  // immediately check postState.phase — that check fires before the LLM runs.
+  // Instead, it must return false (release lock) so the async dispatch can complete.
+  // The warning "Discussion completed but milestone context is still missing"
+  // fires prematurely when this postState check exists.
+  assert.ok(
+    !block.includes("Discussion completed but milestone context is still missing"),
+    "pre-planning !hasContext block must NOT check postState.phase immediately after showSmartEntry — " +
+    "the dispatch is async (pi.sendMessage is fire-and-forget) and the discussion hasn't run yet; " +
+    "return false instead so checkAutoStartAfterDiscuss can re-enter auto-mode after discussion completes (#3420)",
+  );
+});
+
+test("bootstrapAutoSession: complete/no-milestone path does NOT check postState immediately after showSmartEntry (#3420)", () => {
+  // Find the complete/no-milestone block
+  const completeBlock = source.match(
+    /\/\/ No active work — start a new milestone via discuss flow\s*\n\s*if\s*\(!state\.activeMilestone\s*\|\|\s*state\.phase\s*===\s*"complete"\s*\)([\s\S]*?)\/\/ Active milestone exists but has no roadmap/,
+  );
+  assert.ok(
+    !!completeBlock,
+    "auto-start.ts must have the complete/no-milestone handler block",
+  );
+
+  const block = completeBlock![1];
+
+  // The block must call showSmartEntry
+  assert.ok(
+    block.includes("showSmartEntry"),
+    "complete/no-milestone block must call showSmartEntry",
+  );
+
+  // After showSmartEntry dispatches, checking postState.phase is premature —
+  // the LLM hasn't had a turn yet. The block should return false.
+  // Specifically, the "no milestone context was written" warning fires too early.
+  assert.ok(
+    !block.includes("Discussion completed but no milestone context was written"),
+    "complete/no-milestone block must NOT check postState.phase immediately after showSmartEntry dispatch — " +
+    "return false instead so the async LLM turn can complete (#3420)",
+  );
+});
+
+test("bootstrapAutoSession: showSmartEntry in pre-planning path is followed by releaseLockAndReturn, not postState check (#3420)", () => {
+  // After the fix, the pre-planning !hasContext branch should call showSmartEntry
+  // and then immediately return releaseLockAndReturn() — not check postState.
+  const prePlanningNoContextBlock = source.match(
+    /\/\/ Active milestone exists but has no roadmap\s*\n\s*if\s*\(\s*state\.phase\s*===\s*"pre-planning"\s*\)([\s\S]*?)\/\/ Active milestone has CONTEXT-DRAFT/,
+  );
+  assert.ok(!!prePlanningNoContextBlock, "pre-planning handler block found");
+
+  const block = prePlanningNoContextBlock![1];
+
+  // After the fix, the !hasContext branch ends with releaseLockAndReturn
+  assert.ok(
+    block.includes("releaseLockAndReturn"),
+    "pre-planning !hasContext block must call releaseLockAndReturn() after showSmartEntry dispatch (#3420)",
+  );
+
+  // The showSmartEntry call must appear before releaseLockAndReturn
+  const showSmartEntryIdx = block.indexOf("showSmartEntry");
+  const releaseLockIdx = block.indexOf("releaseLockAndReturn");
+  assert.ok(
+    showSmartEntryIdx > -1 && releaseLockIdx > -1,
+    "both showSmartEntry and releaseLockAndReturn must appear in the block",
+  );
+  assert.ok(
+    showSmartEntryIdx < releaseLockIdx,
+    "showSmartEntry must appear before releaseLockAndReturn in pre-planning !hasContext block",
+  );
+
+  // There must be NO invalidateAllCaches between showSmartEntry and releaseLockAndReturn
+  // (invalidateAllCaches + deriveState after showSmartEntry is the buggy premature check)
+  const afterShowSmartEntry = block.substring(showSmartEntryIdx);
+  const cacheInvalidateIdx = afterShowSmartEntry.indexOf("invalidateAllCaches");
+  const releaseFromShowIdx = afterShowSmartEntry.indexOf("releaseLockAndReturn");
+
+  // If invalidateAllCaches appears, it must appear AFTER releaseLockAndReturn
+  // (which is impossible since releaseLockAndReturn returns) — so invalidateAllCaches
+  // must not appear at all between showSmartEntry and the end of the !hasContext block.
+  if (cacheInvalidateIdx !== -1) {
+    assert.ok(
+      cacheInvalidateIdx > releaseFromShowIdx,
+      "invalidateAllCaches must NOT appear between showSmartEntry and releaseLockAndReturn — " +
+      "this is the premature postState check that causes #3420",
+    );
+  }
+});

package/src/resources/extensions/gsd/tests/auto-start-clean-runtime-db-gated.test.ts

@@ -0,0 +1,63 @@
+// GSD-2 auto-start regression test: cleanStaleRuntimeUnits is DB-gated (#4663)
+//
+// Source-level structural check that the stale-runtime-cleanup predicate in
+// auto-start.ts consults DB status when available instead of treating a
+// SUMMARY-file on disk as proof of milestone completion. Pairs with #4658 /
+// PR #4660 fix in auto-dispatch + auto-recovery.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourceFile = join(__dirname, "..", "auto-start.ts");
+
+describe("auto-start cleanStaleRuntimeUnits DB gating (#4663)", () => {
+  const source = readFileSync(sourceFile, "utf-8");
+
+  test("imports isClosedStatus for DB-status check", () => {
+    assert.match(
+      source,
+      /import\s*\{\s*isClosedStatus\s*\}\s*from\s*["']\.\/status-guards/,
+    );
+  });
+
+  test("cleanStaleRuntimeUnits is called after openProjectDbIfPresent", () => {
+    const openDbIdx = source.indexOf("await openProjectDbIfPresent(base)");
+    assert.ok(openDbIdx > -1, "openProjectDbIfPresent should be called in auto-start");
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(", openDbIdx);
+    assert.ok(
+      cleanIdx > -1,
+      "cleanStaleRuntimeUnits must run AFTER openProjectDbIfPresent so predicate can consult DB",
+    );
+  });
+
+  test("cleanStaleRuntimeUnits predicate consults DB status when available", () => {
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
+    assert.ok(cleanIdx > -1);
+    const snippet = source.slice(cleanIdx, cleanIdx + 600);
+    assert.match(
+      snippet,
+      /isDbAvailable\(\)/,
+      "predicate must branch on DB availability",
+    );
+    assert.match(
+      snippet,
+      /isClosedStatus\(/,
+      "predicate must check DB status via isClosedStatus",
+    );
+  });
+
+  test("cleanStaleRuntimeUnits predicate still falls back to SUMMARY-file when DB unavailable", () => {
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
+    assert.ok(cleanIdx > -1);
+    const snippet = source.slice(cleanIdx, cleanIdx + 600);
+    assert.match(
+      snippet,
+      /resolveMilestoneFile\(base,\s*mid,\s*["']SUMMARY["']\)/,
+      "legacy FS-fallback branch should still use SUMMARY file presence",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -144,3 +144,26 @@ describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", (
     );
   });
 });
+
+describe("#4365: tool_execution_start hook must pass toolName to markToolStart", () => {
+  test("tool_execution_start handler passes event.toolName to markToolStart", () => {
+    // The tool_execution_start handler must forward toolName so that
+    // hasInteractiveToolInFlight() can correctly identify ask_user_questions
+    // and prevent the idle watchdog from firing during interactive tool calls.
+    const startMarker = 'pi.on("tool_execution_start", async (event) => {';
+    const endMarker = 'pi.on("tool_execution_end", async (event) => {';
+    const toolExecutionStartSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(
+      toolExecutionStartSection.length > 0,
+      "Could not locate tool_execution_start handler section",
+    );
+    assert.ok(
+      toolExecutionStartSection.includes("markToolStart(event.toolCallId, event.toolName)"),
+      "tool_execution_start handler must pass event.toolName to markToolStart so hasInteractiveToolInFlight() works correctly",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/clean-root-preflight.test.ts

@@ -0,0 +1,186 @@
+/**
+ * clean-root-preflight.test.ts — Regression tests for #2909.
+ *
+ * Tests that preflightCleanRoot warns + stashes on dirty trees,
+ * is a no-op on clean trees, and that postflightPopStash restores
+ * stashed changes after a merge.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { preflightCleanRoot, postflightPopStash } from "../clean-root-preflight.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-preflight-test-")));
+  run("git init", dir);
+  run("git config user.email test@example.com", dir);
+  run("git config user.name Test", dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+  return dir;
+}
+
+// ── Clean tree: fast-path returns immediately without stashing ─────────────
+
+test("preflightCleanRoot — clean tree returns stashPushed=false and emits no notifications", () => {
+  const repo = createTempRepo();
+  try {
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M001", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, false, "stashPushed must be false for clean tree");
+    assert.equal(result.summary, "", "summary must be empty for clean tree");
+    assert.equal(notifications.length, 0, "no notifications on clean tree");
+
+    // Verify no stash was created
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "no stash entry on clean tree");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Dirty tree: warns, stashes, returns stashPushed=true ──────────────────
+
+test("preflightCleanRoot — dirty tree warns user and auto-stashes", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty an existing tracked file
+    writeFileSync(join(repo, "README.md"), "# locally modified\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M002", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true when tree was dirty");
+    assert.ok(result.summary.length > 0, "summary must be non-empty when stash was pushed");
+
+    // A warning notification must have been emitted before stashing
+    assert.ok(
+      notifications.some(n => n.level === "warning" && n.msg.includes("M002")),
+      "warning notification must mention the milestone ID",
+    );
+
+    // Working tree must now be clean (stash pushed)
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+
+    // The stash entry must exist
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("gsd-preflight-stash"), "stash entry must be named gsd-preflight-stash");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Untracked files are also stashed ─────────────────────────────────────
+
+test("preflightCleanRoot — untracked file triggers stash with --include-untracked", () => {
+  const repo = createTempRepo();
+  try {
+    // Add an untracked file
+    writeFileSync(join(repo, "untracked.ts"), "export const x = 1;\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M003", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true for untracked file");
+
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── postflightPopStash: restores stashed changes ──────────────────────────
+
+test("postflightPopStash — restores stashed changes and emits info notification", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty the working tree
+    writeFileSync(join(repo, "README.md"), "# stash me\n");
+
+    const preNotifications: Array<{ msg: string; level: string }> = [];
+    const preflight = preflightCleanRoot(repo, "M004", (msg, level) => {
+      preNotifications.push({ msg, level });
+    });
+    assert.equal(preflight.stashPushed, true, "preflight must have stashed");
+
+    // Simulate the merge (just a no-op commit here)
+    writeFileSync(join(repo, "merged.ts"), "export const merged = true;\n");
+    run("git add .", repo);
+    run('git commit -m "simulate merge"', repo);
+
+    const postNotifications: Array<{ msg: string; level: string }> = [];
+    postflightPopStash(repo, "M004", (msg, level) => {
+      postNotifications.push({ msg, level });
+    });
+
+    // The stashed README.md change must be restored
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# stash me\n", "stashed file must be restored");
+
+    // An info notification must have been emitted
+    assert.ok(
+      postNotifications.some(n => n.level === "info" && n.msg.includes("M004")),
+      "info notification must mention milestone ID after pop",
+    );
+
+    // Stash list must be empty
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "stash list must be empty after pop");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Round-trip: preflight + merge + postflight preserves changes ──────────
+
+test("preflight + merge + postflight round-trip preserves uncommitted changes", () => {
+  const repo = createTempRepo();
+  try {
+    const originalContent = "# my local work\n";
+    writeFileSync(join(repo, "README.md"), originalContent);
+
+    // Preflight: stash
+    const preflight = preflightCleanRoot(repo, "M005", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed");
+
+    // Merge: introduce a new file (no overlap with README.md)
+    writeFileSync(join(repo, "feature.ts"), "export const feature = true;\n");
+    run("git add feature.ts", repo);
+    run('git commit -m "feat: add feature"', repo);
+
+    // Postflight: pop stash
+    postflightPopStash(repo, "M005", () => {});
+
+    // README.md must still have our local content
+    const restored = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(restored.replace(/\r\n/g, "\n"), originalContent, "local changes must survive merge");
+
+    // feature.ts must also exist (the merge commit landed)
+    const featureContent = readFileSync(join(repo, "feature.ts"), "utf-8");
+    assert.ok(featureContent.includes("feature"), "merged feature must be present");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});