gsd-pi 2.80.0-dev.4ea7d80e7 → 2.80.0-dev.7582bf37a

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

@@ -3,223 +3,169 @@
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 import { join } from "node:path";
-
-const autoTimersPath = join(import.meta.dirname, "..", "auto-timers.ts");
-const autoTimersSrc = readFileSync(autoTimersPath, "utf-8");
-
-const autoPath = join(import.meta.dirname, "..", "auto.ts");
-const autoSrc = readFileSync(autoPath, "utf-8");
-
-const runUnitPath = join(import.meta.dirname, "..", "auto", "run-unit.ts");
-const runUnitSrc = readFileSync(runUnitPath, "utf-8");
-
-const registerHooksPath = join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts");
-const registerHooksSrc = readFileSync(registerHooksPath, "utf-8");
-
-describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () => {
-  test("soft timeout wrapup gates triggerTurn on getInFlightToolCount() === 0", () => {
-    // The soft timeout sendMessage must NOT use a hardcoded `triggerTurn: true`.
-    // It must check getInFlightToolCount() before deciding whether to trigger.
-    // Use the section marker comment to isolate the soft timeout block.
-    const startMarker = "── 1. Soft timeout warning";
-    const endMarker = "── 2. Idle watchdog";
-    const softTimeoutSection = autoTimersSrc.slice(
-      autoTimersSrc.indexOf(startMarker),
-      autoTimersSrc.indexOf(endMarker),
-    );
-    assert.ok(
-      softTimeoutSection.length > 0,
-      "Could not locate soft timeout section",
-    );
-
-    // Must reference getInFlightToolCount to gate the trigger
-    assert.ok(
-      softTimeoutSection.includes("getInFlightToolCount"),
-      "Soft timeout wrapup must gate triggerTurn behind getInFlightToolCount() check",
-    );
-
-    // Must NOT have a hardcoded triggerTurn: true
-    assert.ok(
-      !softTimeoutSection.includes("triggerTurn: true"),
-      "Soft timeout wrapup must not use hardcoded triggerTurn: true",
-    );
-  });
-
-  test("context-pressure wrapup gates triggerTurn on getInFlightToolCount() === 0", () => {
-    // The context budget sendMessage must NOT use a hardcoded `triggerTurn: true`.
-    // Use the section marker to isolate the context-pressure block.
-    const startMarker = "── 4. Context-pressure continue-here monitor";
-    const contextSection = autoTimersSrc.slice(
-      autoTimersSrc.indexOf(startMarker),
-    );
-    assert.ok(
-      contextSection.length > 0,
-      "Could not locate context budget section",
-    );
-
-    // Must reference getInFlightToolCount to gate the trigger
-    assert.ok(
-      contextSection.includes("getInFlightToolCount"),
-      "Context budget wrapup must gate triggerTurn behind getInFlightToolCount() check",
-    );
-
-    // Must NOT have a hardcoded triggerTurn: true
-    assert.ok(
-      !contextSection.includes("triggerTurn: true"),
-      "Context budget wrapup must not use hardcoded triggerTurn: true",
-    );
-  });
-});
-
-describe("#4276: pending/skipped tools stay visible to auto-mode hooks", () => {
-  test("tool_call handler marks GSD tools in-flight before execution_start", () => {
-    const startMarker = 'pi.on("tool_call", async (event, ctx) => {';
-    const endMarker = 'pi.on("tool_result", async (event) => {';
-    const toolCallSection = registerHooksSrc.slice(
-      registerHooksSrc.indexOf(startMarker),
-      registerHooksSrc.indexOf(endMarker),
-    );
-
-    assert.ok(toolCallSection.length > 0, "Could not locate tool_call handler section");
-    assert.ok(
-      toolCallSection.includes("markToolStart(event.toolCallId, event.toolName)"),
-      "tool_call handler must mark tools pending before tool_execution_start fires",
-    );
-  });
-
-  test("tool_result handler clears pending tools and records queued-skip errors", () => {
-    const startMarker = 'pi.on("tool_result", async (event) => {';
-    const endMarker = 'pi.on("tool_execution_start", async (event) => {';
-    const toolResultSection = registerHooksSrc.slice(
-      registerHooksSrc.indexOf(startMarker),
-      registerHooksSrc.indexOf(endMarker),
-    );
-
-    assert.ok(toolResultSection.length > 0, "Could not locate tool_result handler section");
-    assert.ok(
-      toolResultSection.includes("markToolEnd(event.toolCallId)"),
-      "tool_result handler must clear pending tool tracking even when execution hooks never fire",
-    );
-    assert.ok(
-      toolResultSection.includes("recordToolInvocationError(event.toolName, errorText)"),
-      "tool_result handler must surface queued-skip errors for GSD tools",
-    );
-  });
-});
-
-describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", () => {
-  test("stopAuto calls clearQueue()", () => {
-    // stopAuto must flush queued messages to prevent late async_job_result
-    // notifications from triggering extra LLM turns after stop.
-    const stopAutoSection = autoSrc.slice(
-      autoSrc.indexOf("export async function stopAuto("),
-      autoSrc.indexOf("export async function pauseAuto("),
-    );
-    assert.ok(stopAutoSection, "Could not locate stopAuto function");
-    assert.ok(
-      stopAutoSection.includes("clearQueue"),
-      "stopAuto must call clearQueue() to flush queued follow-up messages",
-    );
-  });
-
-  test("pauseAuto calls clearQueue()", () => {
-    // pauseAuto must also flush queued messages — same issue as stopAuto.
-    const pauseAutoSection = autoSrc.slice(
-      autoSrc.indexOf("export async function pauseAuto("),
-    );
-    assert.ok(pauseAutoSection, "Could not locate pauseAuto function");
-    assert.ok(
-      pauseAutoSection.includes("clearQueue"),
-      "pauseAuto must call clearQueue() to flush queued follow-up messages",
-    );
-  });
-
-  test("pauseAuto rebuilds STATE.md before releasing the session lock", () => {
-    // pauseAuto must persist the DB-backed state projection so resume/debugging
-    // does not see a stale STATE.md after a mid-unit interruption.
-    const start = autoSrc.indexOf("export async function pauseAuto(");
-    const end = autoSrc.indexOf("/**\n * Build a WorktreeResolverDeps", start);
-    const pauseAutoSection = autoSrc.slice(start, end);
-    assert.ok(pauseAutoSection.length > 0, "Could not locate pauseAuto function");
-
-    const rebuildIndex = pauseAutoSection.indexOf("await rebuildState(s.basePath)");
-    const releaseIndex = pauseAutoSection.indexOf("releaseSessionLock(lockBase())");
-    assert.ok(
-      rebuildIndex >= 0,
-      "pauseAuto must rebuild STATE.md from DB-backed state before pause completes",
-    );
-    assert.ok(
-      releaseIndex >= 0,
-      "pauseAuto must still release the session lock",
-    );
-    assert.ok(
-      rebuildIndex < releaseIndex,
-      "pauseAuto must rebuild state before releasing the session lock",
-    );
-  });
-
-  test("run-unit.ts still has its existing clearQueue() call (baseline)", () => {
-    // Verify the original clearQueue pattern in run-unit.ts hasn't been removed.
-    assert.ok(
-      runUnitSrc.includes("clearQueue"),
-      "run-unit.ts must retain its clearQueue() call after unit completion",
-    );
-  });
-});
-
-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",
-    );
+import { tmpdir } from "node:os";
+
+import { autoSession } from "../auto-runtime-state.ts";
+import { dispatchHookUnit } from "../auto.ts";
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { clearDiscussionFlowState, getPendingGate } from "../bootstrap/write-gate.ts";
+
+function makeHookHarness() {
+  const handlers = new Map<string, Array<(event: any, ctx: any) => Promise<any>>>();
+  const pi = {
+    on(name: string, handler: (event: any, ctx: any) => Promise<any>) {
+      const current = handlers.get(name) ?? [];
+      current.push(handler);
+      handlers.set(name, current);
+    },
+  };
+  const ctx = {
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setWidget: () => {},
+    },
+    modelRegistry: {
+      setDisabledModelProviders: () => {},
+    },
+    setCompactionThresholdOverride: () => {},
+  };
+  async function emit(name: string, event: any): Promise<any> {
+    for (const handler of handlers.get(name) ?? []) {
+      const result = await handler(event, ctx);
+      if (result?.block) return result;
+    }
+    return undefined;
+  }
+  registerHooks(pi as any, []);
+  return { emit };
+}
+
+describe("hook dispatch session workspace root", () => {
+  test("dispatchHookUnit passes basePath explicitly to newSession", async (t) => {
+    const originalCwd = process.cwd();
+    const basePath = mkdtempSync(join(tmpdir(), "gsd-hook-cwd-"));
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    autoSession.reset();
+    t.after(() => {
+      try {
+        process.chdir(originalCwd);
+      } catch {
+        // best effort cleanup after cwd-sensitive dispatch tests
+      }
+      autoSession.reset();
+      rmSync(basePath, { recursive: true, force: true });
+    });
+
+    let newSessionOptions: unknown;
+    const ctx = {
+      ui: {
+        notify: () => {},
+        setStatus: () => {},
+        setWidget: () => {},
+      },
+      modelRegistry: {
+        getAvailable: () => [],
+      },
+      sessionManager: {
+        getSessionFile: () => join(basePath, "session.jsonl"),
+      },
+      newSession: async (options?: unknown) => {
+        newSessionOptions = options;
+        return { cancelled: false };
+      },
+    };
+    const pi = {
+      sendMessage: () => {},
+      setModel: async () => true,
+    };
+
+    const dispatched = await dispatchHookUnit(
+      ctx as any,
+      pi as any,
+      "review",
+      "execute-task",
+      "M001/S01/T01",
+      "review the completed unit",
+      undefined,
+      basePath,
+    );
+
+    assert.equal(dispatched, true);
+    assert.deepEqual(newSessionOptions, { workspaceRoot: basePath });
   });
 });
 
 describe("deep setup approval questions pause immediately", () => {
-  test("register-hooks sets pending gate during message_update without aborting the stream", () => {
-    const startMarker = 'pi.on("message_update"';
-    const endMarker = 'pi.on("session_shutdown"';
-    const messageUpdateSection = registerHooksSrc.slice(
-      registerHooksSrc.indexOf(startMarker),
-      registerHooksSrc.indexOf(endMarker),
-    );
-
-    assert.ok(
-      messageUpdateSection.length > 0,
-      "Could not locate message_update approval pause handler",
-    );
-    assert.ok(
-      messageUpdateSection.includes("shouldPauseForUserApprovalQuestion"),
-      "message_update must detect approval/question boundaries",
-    );
-    assert.ok(
-      messageUpdateSection.includes("approvalGateIdForUnit") && messageUpdateSection.includes("setPendingGate"),
-      "plain-text approval questions must set the durable write gate",
-    );
-    assert.ok(
-      messageUpdateSection.includes("getDiscussionMilestoneIdFor") && messageUpdateSection.includes('"discuss-milestone"'),
-      "foreground milestone discussion questions must also set the durable write gate",
-    );
-    assert.ok(
-      !messageUpdateSection.includes("ctx.abort()"),
-      "message_update must NOT abort the stream — aborting eats the model's question text on external CLI providers; the pending gate set above blocks subsequent tool calls instead",
-    );
+  test("plain-text approval boundary defers durable gate until same-turn CONTEXT-DRAFT can save", async () => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-deferred-approval-")));
+    const previousCwd = process.cwd();
+    try {
+      mkdirSync(join(base, ".gsd", "milestones", "M003"), { recursive: true });
+      process.chdir(base);
+      clearDiscussionFlowState(base);
+      autoSession.reset();
+      autoSession.basePath = base;
+      autoSession.currentUnit = {
+        type: "discuss-milestone",
+        id: "M003",
+        startedAt: Date.now(),
+      };
+
+      const { emit } = makeHookHarness();
+      await emit("message_update", {
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Did I capture that correctly? If not, tell me what I missed." }],
+        },
+      });
+
+      assert.equal(
+        getPendingGate(base),
+        null,
+        "approval text should not install the durable pending gate until the assistant turn ends",
+      );
+
+      const draftResult = await emit("tool_call", {
+        toolCallId: "draft-save",
+        toolName: "gsd_summary_save",
+        input: {
+          milestone_id: "M003",
+          artifact_type: "CONTEXT-DRAFT",
+          content: "# M003 Draft\n",
+        },
+      });
+      assert.equal(
+        draftResult?.block,
+        undefined,
+        "same-turn CONTEXT-DRAFT persistence should remain allowed after the approval text streams",
+      );
+
+      const finalContextResult = await emit("tool_call", {
+        toolCallId: "final-context",
+        toolName: "gsd_summary_save",
+        input: {
+          milestone_id: "M003",
+          artifact_type: "CONTEXT",
+          content: "# M003 Context\n",
+        },
+      });
+      assert.equal(finalContextResult?.block, true, "final CONTEXT must still wait for approval");
+      assert.match(finalContextResult.reason, /Approval question "depth_verification_M003_confirm"/);
+
+      await emit("agent_end", { messages: [] });
+      assert.equal(
+        getPendingGate(base),
+        "depth_verification_M003_confirm",
+        "agent_end should activate the durable pending gate for the next turn",
+      );
+    } finally {
+      process.chdir(previousCwd);
+      autoSession.reset();
+      clearDiscussionFlowState(base);
+      rmSync(base, { recursive: true, force: true });
+    }
   });
 });

package/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts

@@ -1,40 +1,23 @@
-import { describe, test } from "node:test";
+import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { extractSourceRegion } from "./test-helpers.ts";
+import { tmpdir } from "node:os";
 
-const systemContextSrc = readFileSync(
-  join(import.meta.dirname, "..", "bootstrap", "system-context.ts"),
-  "utf-8",
-);
-const registerHooksSrc = readFileSync(
-  join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts"),
-  "utf-8",
-);
+import { ensureDbOpen } from "../bootstrap/dynamic-tools.ts";
+import { closeDatabase, isDbAvailable } from "../gsd-db.ts";
+
+afterEach(() => {
+  if (isDbAvailable()) closeDatabase();
+});
 
 describe("bootstrap deriveState DB guards (#3844)", () => {
-  test("system-context opens DB before deriveState in resume flows", () => {
-    const helperIdx = systemContextSrc.indexOf("const ensureStateDbOpen = async () => {");
-    const firstDeriveIdx = systemContextSrc.indexOf("const state = await deriveState(basePath);");
-    assert.ok(helperIdx > -1, "system-context should define a DB-open helper for deriveState callers");
-    assert.ok(firstDeriveIdx > -1, "system-context should still derive state for resume flows");
-    assert.ok(helperIdx < firstDeriveIdx, "system-context should prepare DB opening before deriveState resume calls");
-    assert.match(
-      systemContextSrc,
-      /await ensureStateDbOpen\(\);\s*\n\s*const state = await deriveState\(basePath\);/g,
-      "system-context resume flows should open DB before deriveState",
-    );
-  });
+  test("ensureDbOpen creates and opens the project DB when .gsd exists", async (t) => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-ensure-db-")));
+    t.after(() => rmSync(base, { recursive: true, force: true }));
+    mkdirSync(join(base, ".gsd"), { recursive: true });
 
-  test("register-hooks opens DB before deriveState in session_before_compact", () => {
-    const compactIdx = registerHooksSrc.indexOf('pi.on("session_before_compact"');
-    assert.ok(compactIdx > -1, "register-hooks should define session_before_compact");
-    const compactSection = extractSourceRegion(registerHooksSrc, 'pi.on("session_before_compact"');
-    const ensureIdx = compactSection.indexOf("ensureDbOpen(basePath)");
-    const deriveIdx = compactSection.indexOf("deriveGsdState(basePath)");
-    assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen(basePath)");
-    assert.ok(deriveIdx > -1, "session_before_compact should derive state");
-    assert.ok(ensureIdx < deriveIdx, "session_before_compact should open DB before deriveState");
+    assert.equal(await ensureDbOpen(base), true);
+    assert.equal(isDbAvailable(), true);
   });
 });

package/src/resources/extensions/gsd/tests/browser-teardown.test.ts

@@ -90,44 +90,3 @@ test("getBrowser() guard triggers closeBrowser when browser is active", async ()
   assert.equal(closeCalled, true, "browser.close() should have been called");
   assert.equal(getBrowser(), null, "browser should be null after guarded teardown");
 });
-
-// ─── Source code verification ───────────────────────────────────────────────
-
-test("stopAuto finally block includes browser teardown", async () => {
-  // Verify the source code contains the browser teardown call
-  const { readFileSync } = await import("node:fs");
-  const { resolve } = await import("node:path");
-  const autoSource = readFileSync(resolve(import.meta.dirname, "..", "auto.ts"), "utf-8");
-
-  assert.ok(
-    autoSource.includes("closeBrowser"),
-    "auto.ts should reference closeBrowser for teardown in stopAuto",
-  );
-  assert.ok(
-    autoSource.includes("getBrowser"),
-    "auto.ts should check getBrowser() before calling closeBrowser",
-  );
-  assert.ok(
-    autoSource.includes("browser-tools/lifecycle"),
-    "auto.ts should import from browser-tools/lifecycle",
-  );
-});
-
-test("postUnitPreVerification includes browser teardown between units", async () => {
-  const { readFileSync } = await import("node:fs");
-  const { resolve } = await import("node:path");
-  const postUnitSource = readFileSync(resolve(import.meta.dirname, "..", "auto-post-unit.ts"), "utf-8");
-
-  assert.ok(
-    postUnitSource.includes("closeBrowser"),
-    "auto-post-unit.ts should reference closeBrowser for inter-unit teardown",
-  );
-  assert.ok(
-    postUnitSource.includes("getBrowser"),
-    "auto-post-unit.ts should check getBrowser() before calling closeBrowser",
-  );
-  assert.ok(
-    postUnitSource.includes("browser-teardown"),
-    "auto-post-unit.ts should have browser-teardown debug phase",
-  );
-});

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

@@ -131,9 +131,11 @@ test("postflightPopStash — restores stashed changes and emits info notificatio
     run('git commit -m "simulate merge"', repo);
 
     const postNotifications: Array<{ msg: string; level: string }> = [];
-    postflightPopStash(repo, "M004", (msg, level) => {
+    const postflight = postflightPopStash(repo, "M004", preflight.stashMarker, (msg, level) => {
       postNotifications.push({ msg, level });
     });
+    assert.equal(postflight.restored, true, "postflight must report successful restore");
+    assert.equal(postflight.needsManualRecovery, false, "successful restore must not need manual recovery");
 
     // The stashed README.md change must be restored
     const content = readFileSync(join(repo, "README.md"), "utf-8");
@@ -171,7 +173,8 @@ test("preflight + merge + postflight round-trip preserves uncommitted changes",
     run('git commit -m "feat: add feature"', repo);
 
     // Postflight: pop stash
-    postflightPopStash(repo, "M005", () => {});
+    const postflight = postflightPopStash(repo, "M005", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "clean restore must not stop auto-mode");
 
     // README.md must still have our local content
     const restored = readFileSync(join(repo, "README.md"), "utf-8");
@@ -184,3 +187,95 @@ test("preflight + merge + postflight round-trip preserves uncommitted changes",
     try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
   }
 });
+
+test("postflightPopStash conflict warning names the exact stash ref", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# local work\n");
+    const preflight = preflightCleanRoot(repo, "M005C", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed");
+
+    writeFileSync(join(repo, "README.md"), "# merged work\n");
+    run("git add README.md", repo);
+    run('git commit -m "simulate conflicting merge"', repo);
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const postflight = postflightPopStash(repo, "M005C", preflight.stashMarker, (msg, level) => {
+      notifications.push({ msg, level });
+    });
+    assert.equal(postflight.restored, false, "conflicted restore must report restored=false");
+    assert.equal(postflight.needsManualRecovery, true, "conflicted restore must require manual recovery");
+    assert.match(postflight.message, /failed after merge of milestone M005C/);
+
+    const warning = notifications.find((n) => n.level === "warning")?.msg ?? "";
+    assert.match(warning, /git stash pop stash@\{\d+\}/);
+    assert.match(warning, /git stash apply stash@\{\d+\}/);
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+test("postflightPopStash restores the matching GSD stash, not stash@{0}", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# target stash\n");
+    const preflight = preflightCleanRoot(repo, "M006", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed target change");
+
+    writeFileSync(join(repo, "other.txt"), "other stash\n");
+    run('git stash push --include-untracked -m "unrelated newer stash"', repo);
+
+    const postflight = postflightPopStash(repo, "M006", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "targeted restore must not need manual recovery");
+
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# target stash\n");
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("unrelated newer stash"), "unrelated newer stash must remain");
+    assert.ok(!stashList.includes("gsd-preflight-stash [gsd-preflight-stash:M006"), "target stash should be consumed");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+test("postflightPopStash restores the exact preflight marker when another same-milestone stash exists", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# target stash\n");
+    const preflight = preflightCleanRoot(repo, "M007", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed target change");
+    assert.ok(preflight.stashMarker, "preflight must expose exact stash marker");
+
+    writeFileSync(join(repo, "same-milestone.txt"), "newer same milestone stash\n");
+    run('git stash push --include-untracked -m "gsd-preflight-stash [gsd-preflight-stash:M007:other]"', repo);
+
+    const postflight = postflightPopStash(repo, "M007", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "exact marker restore must not need manual recovery");
+
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# target stash\n");
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("gsd-preflight-stash:M007:other"), "newer same-milestone stash must remain");
+    assert.ok(!stashList.includes(preflight.stashMarker), "exact target stash should be consumed");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+test("postflightPopStash falls back to milestone marker prefix when exact marker is unavailable", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# fallback stash\n");
+    run('git stash push --include-untracked -m "gsd-preflight-stash [gsd-preflight-stash:M008:fallback]"', repo);
+
+    const postflight = postflightPopStash(repo, "M008", undefined, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "fallback marker restore must not need manual recovery");
+
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# fallback stash\n");
+    const stashList = run("git stash list", repo);
+    assert.ok(!stashList.includes("gsd-preflight-stash:M008:fallback"), "fallback stash should be consumed");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});