gsd-pi 2.51.0 → 2.52.0-dev.655ad8a

package/src/resources/extensions/gsd/tests/provider-errors.test.ts

@@ -1,6 +1,6 @@
 /**
  * Provider error handling tests — consolidated from:
- *   - provider-error-classify.test.ts (classifyProviderError)
+ *   - provider-error-classify.test.ts (classifyError)
  *   - network-error-fallback.test.ts (isTransientNetworkError, getNextFallbackModel)
  *   - agent-end-provider-error.test.ts (pauseAutoForProviderError)
  */
@@ -10,102 +10,111 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { classifyProviderError, pauseAutoForProviderError } from "../provider-error-pause.ts";
-import { getNextFallbackModel, isTransientNetworkError } from "../preferences.ts";
+import { classifyError, isTransient, isTransientNetworkError } from "../error-classifier.ts";
+import { pauseAutoForProviderError } from "../provider-error-pause.ts";
+import { getNextFallbackModel } from "../preferences.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// ── classifyProviderError ────────────────────────────────────────────────────
+// ── classifyError ────────────────────────────────────────────────────────────
 
-test("classifyProviderError detects rate limit from 429", () => {
-  const result = classifyProviderError("HTTP 429 Too Many Requests");
-  assert.ok(result.isTransient);
-  assert.ok(result.isRateLimit);
-  assert.ok(result.suggestedDelayMs > 0);
+test("classifyError detects rate limit from 429", () => {
+  const result = classifyError("HTTP 429 Too Many Requests");
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "rate-limit");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs > 0);
 });
 
-test("classifyProviderError detects rate limit from message", () => {
-  const result = classifyProviderError("rate limit exceeded");
-  assert.ok(result.isTransient);
-  assert.ok(result.isRateLimit);
+test("classifyError detects rate limit from message", () => {
+  const result = classifyError("rate limit exceeded");
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "rate-limit");
 });
 
-test("classifyProviderError extracts reset delay from message", () => {
-  const result = classifyProviderError("rate limit exceeded, reset in 45s");
-  assert.ok(result.isRateLimit);
-  assert.equal(result.suggestedDelayMs, 45000);
+test("classifyError extracts reset delay from message", () => {
+  const result = classifyError("rate limit exceeded, reset in 45s");
+  assert.equal(result.kind, "rate-limit");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 45000);
 });
 
-test("classifyProviderError defaults to 60s for rate limit without reset", () => {
-  const result = classifyProviderError("429 too many requests");
-  assert.ok(result.isRateLimit);
-  assert.equal(result.suggestedDelayMs, 60_000);
+test("classifyError defaults to 60s for rate limit without reset", () => {
+  const result = classifyError("429 too many requests");
+  assert.equal(result.kind, "rate-limit");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 60_000);
 });
 
-test("classifyProviderError detects Anthropic internal server error", () => {
+test("classifyError treats stream_exhausted_without_result as transient connection failure", () => {
+  const result = classifyError("stream_exhausted_without_result");
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "connection");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 15_000);
+});
+
+test("classifyError detects Anthropic internal server error", () => {
   const msg = '{"type":"error","error":{"details":null,"type":"api_error","message":"Internal server error"}}';
-  const result = classifyProviderError(msg);
-  assert.ok(result.isTransient);
-  assert.ok(!result.isRateLimit);
-  assert.equal(result.suggestedDelayMs, 30_000);
+  const result = classifyError(msg);
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "server");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 30_000);
 });
 
-test("classifyProviderError detects Codex server_error from extracted message", () => {
+test("classifyError detects Codex server_error from extracted message", () => {
   // After fix, mapCodexEvents extracts the nested error type and produces
   // "Codex server_error: <message>" instead of raw JSON.
   const msg = "Codex server_error: An error occurred while processing your request.";
-  const result = classifyProviderError(msg);
-  assert.ok(result.isTransient);
-  assert.ok(!result.isRateLimit);
-  assert.equal(result.suggestedDelayMs, 30_000);
+  const result = classifyError(msg);
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "server");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 30_000);
 });
 
-test("classifyProviderError detects overloaded error", () => {
-  const result = classifyProviderError("overloaded_error: Overloaded");
-  assert.ok(result.isTransient);
-  assert.equal(result.suggestedDelayMs, 30_000);
+test("classifyError detects overloaded error", () => {
+  const result = classifyError("overloaded_error: Overloaded");
+  assert.ok(isTransient(result));
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 30_000);
 });
 
-test("classifyProviderError detects 503 service unavailable", () => {
-  const result = classifyProviderError("HTTP 503 Service Unavailable");
-  assert.ok(result.isTransient);
+test("classifyError detects 503 service unavailable", () => {
+  const result = classifyError("HTTP 503 Service Unavailable");
+  assert.ok(isTransient(result));
 });
 
-test("classifyProviderError detects 502 bad gateway", () => {
-  const result = classifyProviderError("HTTP 502 Bad Gateway");
-  assert.ok(result.isTransient);
+test("classifyError detects 502 bad gateway", () => {
+  const result = classifyError("HTTP 502 Bad Gateway");
+  assert.ok(isTransient(result));
 });
 
-test("classifyProviderError detects auth error as permanent", () => {
-  const result = classifyProviderError("unauthorized: invalid API key");
-  assert.ok(!result.isTransient);
-  assert.ok(!result.isRateLimit);
+test("classifyError detects auth error as permanent", () => {
+  const result = classifyError("unauthorized: invalid API key");
+  assert.ok(!isTransient(result));
+  assert.equal(result.kind, "permanent");
 });
 
-test("classifyProviderError detects billing error as permanent", () => {
-  const result = classifyProviderError("billing issue: payment required");
-  assert.ok(!result.isTransient);
+test("classifyError detects billing error as permanent", () => {
+  const result = classifyError("billing issue: payment required");
+  assert.ok(!isTransient(result));
 });
 
-test("classifyProviderError detects quota exceeded as permanent", () => {
-  const result = classifyProviderError("quota exceeded for this month");
-  assert.ok(!result.isTransient);
+test("classifyError detects quota exceeded as permanent", () => {
+  const result = classifyError("quota exceeded for this month");
+  assert.ok(!isTransient(result));
 });
 
-test("classifyProviderError treats unknown error as permanent", () => {
-  const result = classifyProviderError("something went wrong");
-  assert.ok(!result.isTransient);
+test("classifyError treats unknown error as not transient", () => {
+  const result = classifyError("something went wrong");
+  assert.ok(!isTransient(result));
+  assert.equal(result.kind, "unknown");
 });
 
-test("classifyProviderError treats empty string as permanent", () => {
-  const result = classifyProviderError("");
-  assert.ok(!result.isTransient);
+test("classifyError treats empty string as not transient", () => {
+  const result = classifyError("");
+  assert.ok(!isTransient(result));
 });
 
-test("classifyProviderError: rate limit takes precedence over auth keywords", () => {
-  const result = classifyProviderError("429 unauthorized rate limit");
-  assert.ok(result.isRateLimit);
-  assert.ok(result.isTransient);
+test("classifyError: rate limit takes precedence over auth keywords", () => {
+  const result = classifyError("429 unauthorized rate limit");
+  assert.equal(result.kind, "rate-limit");
+  assert.ok(isTransient(result));
 });
 
 // ── isTransientNetworkError ──────────────────────────────────────────────────
@@ -265,8 +274,8 @@ test("agent-end-recovery.ts tracks consecutive transient errors for escalating b
   const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
 
   assert.ok(
-    src.includes("consecutiveTransientErrors"),
-    "agent-end-recovery.ts must track consecutiveTransientErrors for escalating backoff (#1166)",
+    src.includes("consecutiveTransientCount"),
+    "agent-end-recovery.ts must track consecutiveTransientCount for escalating backoff (#1166)",
   );
   assert.ok(
     src.includes("MAX_TRANSIENT_AUTO_RESUMES"),
@@ -274,15 +283,13 @@ test("agent-end-recovery.ts tracks consecutive transient errors for escalating b
   );
 });
 
-test("agent-end-recovery.ts resets consecutive transient error counter on success", () => {
+test("agent-end-recovery.ts resets retry state before resolveAgentEnd on success", () => {
   const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
 
-  // After successful agent_end (before resolveAgentEnd), the counter must be reset.
-  // Use a regex across the success block so CRLF checkouts on Windows do not
-  // push the reset line outside a fixed substring window.
+  // After successful agent_end, resetRetryState must be called before resolveAgentEnd.
   assert.ok(
-    /consecutiveTransientErrors\s*=\s*0\s*;[\s\S]{0,250}resolveAgentEnd/.test(src),
-    "consecutive transient error counter must be reset before resolveAgentEnd on the success path (#1166)",
+    /resetRetryState[\s\S]{0,250}resolveAgentEnd/.test(src),
+    "resetRetryState must be called before resolveAgentEnd on the success path (#1166)",
   );
 });
 
@@ -291,7 +298,7 @@ test("agent-end-recovery.ts applies escalating delay for repeated transient erro
 
   // Must contain the exponential backoff formula (may span multiple lines)
   assert.ok(
-    src.includes("2 ** Math.max(0, consecutiveTransientErrors"),
+    src.includes("2 ** Math.max(0, retryState.consecutiveTransientCount"),
     "agent-end-recovery.ts must escalate retryAfterMs exponentially for consecutive transient errors (#1166)",
   );
 });

package/src/resources/extensions/gsd/tests/rate-limit-model-fallback.test.ts

@@ -0,0 +1,90 @@
+/**
+ * rate-limit-model-fallback.test.ts — Regression test for #2770.
+ *
+ * Rate-limit errors enter the model fallback path before falling through
+ * to pause. This verifies the structural contract in agent-end-recovery.ts.
+ */
+
+import 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 RECOVERY_PATH = join(__dirname, "..", "bootstrap", "agent-end-recovery.ts");
+
+function getRecoverySource(): string {
+  return readFileSync(RECOVERY_PATH, "utf-8");
+}
+
+// ── Rate-limit errors attempt model fallback (#2770) ─────────────────────────
+
+test("rate-limit errors enter the model fallback branch alongside other transient errors", () => {
+  const src = getRecoverySource();
+
+  // The condition that gates model fallback must include rate-limit.
+  // Match the if-condition that contains both "rate-limit" and fallback-related kinds.
+  const fallbackConditionRe = /if\s*\([^)]*cls\.kind\s*===\s*"rate-limit"[^)]*cls\.kind\s*===\s*"network"/;
+  const fallbackConditionReAlt = /if\s*\([^)]*cls\.kind\s*===\s*"network"[^)]*cls\.kind\s*===\s*"rate-limit"/;
+
+  assert.ok(
+    fallbackConditionRe.test(src) || fallbackConditionReAlt.test(src),
+    'rate-limit must appear in the same if-condition as network/server for model fallback (#2770)',
+  );
+});
+
+test("rate-limit errors are NOT short-circuited to pause before model fallback", () => {
+  const src = getRecoverySource();
+
+  // The old code had a dedicated rate-limit early-return block before the fallback block.
+  // Verify it no longer exists.
+  const earlyRateLimitPause = /if\s*\(\s*cls\.kind\s*===\s*"rate-limit"\s*\)\s*\{[^}]*pauseTransientWithBackoff/;
+  assert.ok(
+    !earlyRateLimitPause.test(src),
+    'rate-limit must NOT have a dedicated early pause before the model fallback path (#2770)',
+  );
+});
+
+test("rate-limit errors fall through to pause if no fallback model is available", () => {
+  const src = getRecoverySource();
+
+  // After the fallback block, the transient fallback pause must still fire for rate-limit.
+  // The isTransient check covers rate-limit (verified by error-classifier tests).
+  // Verify pauseTransientWithBackoff is called with isRateLimit derived from cls.kind.
+  assert.ok(
+    src.includes('cls.kind === "rate-limit"'),
+    'agent-end-recovery.ts must reference cls.kind === "rate-limit" for fallback and pause paths (#2770)',
+  );
+
+  // The transient fallback pause must pass the isRateLimit flag correctly.
+  const pauseCallRe = /pauseTransientWithBackoff\([^)]*cls\.kind\s*===\s*"rate-limit"/;
+  assert.ok(
+    pauseCallRe.test(src),
+    'pauseTransientWithBackoff must receive isRateLimit based on cls.kind === "rate-limit" (#2770)',
+  );
+});
+
+test("other transient errors (server, connection, stream) still attempt model fallback", () => {
+  const src = getRecoverySource();
+
+  // All transient kinds must appear in the fallback condition.
+  for (const kind of ["server", "connection", "stream"]) {
+    assert.ok(
+      src.includes(`cls.kind === "${kind}"`),
+      `model fallback condition must include cls.kind === "${kind}"`,
+    );
+  }
+});
+
+test("permanent errors still bypass model fallback and pause indefinitely", () => {
+  const src = getRecoverySource();
+
+  // The permanent/unknown error handler must exist and call pauseAutoForProviderError
+  // with isTransient: false.
+  const permanentPauseRe = /pauseAutoForProviderError[\s\S]{0,300}isTransient:\s*false/;
+  assert.ok(
+    permanentPauseRe.test(src),
+    'permanent errors must pause with isTransient: false (no auto-resume)',
+  );
+});

package/src/resources/extensions/gsd/tests/remediation-completion-guard.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Regression test for #2675: completing-milestone dispatch rule must
+ * block completion when VALIDATION verdict is "needs-remediation".
+ *
+ * Without this guard, needs-remediation + allSlicesDone causes a loop:
+ * complete-milestone dispatched → agent refuses (correct) → no SUMMARY
+ * → re-dispatch → repeat until stuck detection fires.
+ */
+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";
+
+/** Find the completing-milestone dispatch rule */
+const completingRule = DISPATCH_RULES.find(r => r.name === "completing-milestone → complete-milestone");
+
+test("completing-milestone dispatch rule exists", () => {
+  assert.ok(completingRule, "rule should exist in DISPATCH_RULES");
+});
+
+test("completing-milestone blocks when VALIDATION verdict is needs-remediation (#2675)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-remediation-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    // Write a VALIDATION file with needs-remediation verdict
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"),
+      [
+        "---",
+        "verdict: needs-remediation",
+        "remediation_round: 0",
+        "---",
+        "",
+        "# Validation Report",
+        "",
+        "3 success criteria failed. Remediation required.",
+      ].join("\n"),
+    );
+
+    const ctx = {
+      mid: "M001",
+      midTitle: "Test Milestone",
+      basePath: base,
+      state: { phase: "completing-milestone" } as any,
+      prefs: {} as any,
+      session: undefined,
+    };
+
+    const result = await completingRule!.match(ctx);
+
+    assert.ok(result !== null, "rule should match");
+    assert.equal(result!.action, "stop", "should return stop action");
+    if (result!.action === "stop") {
+      assert.equal(result!.level, "warning", "should be warning level (pausable)");
+      assert.ok(
+        result!.reason.includes("needs-remediation"),
+        "reason should mention needs-remediation",
+      );
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("completing-milestone proceeds normally when VALIDATION verdict is pass (#2675 guard)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-remediation-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    // Write a VALIDATION file with pass verdict
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"),
+      [
+        "---",
+        "verdict: pass",
+        "---",
+        "",
+        "# Validation Report",
+        "",
+        "All criteria met.",
+      ].join("\n"),
+    );
+
+    const ctx = {
+      mid: "M001",
+      midTitle: "Test Milestone",
+      basePath: base,
+      state: { phase: "completing-milestone" } as any,
+      prefs: {} as any,
+      session: undefined,
+    };
+
+    const result = await completingRule!.match(ctx);
+
+    // Should NOT return a stop — should either dispatch or return stop for
+    // a different reason (e.g. missing SUMMARY files, no implementation)
+    if (result && result.action === "stop") {
+      assert.ok(
+        !result.reason.includes("needs-remediation"),
+        "pass verdict should NOT trigger the remediation guard",
+      );
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/remote-questions.test.ts

@@ -724,3 +724,32 @@ test("resolveRemoteConfig returns null when preferences are absent (no env side-
     if (savedTelegram !== undefined) process.env.TELEGRAM_BOT_TOKEN = savedTelegram;
   }
 });
+
+test("config source-level: hydration skips api_key entries with empty keys", () => {
+  const configSrc = readFileSync(
+    join(__dirname, "..", "..", "remote-questions", "config.ts"),
+    "utf-8",
+  );
+  // The find() call in hydrateRemoteTokensFromAuth must filter for non-empty keys,
+  // not just match on type === "api_key". This prevents stale empty-key entries
+  // (left by removeProviderToken) from shadowing valid tokens.
+  assert.ok(
+    configSrc.includes('c.type === "api_key" && !!c.key'),
+    "hydrateRemoteTokensFromAuth find() should require a non-empty key",
+  );
+});
+
+test("config source-level: removeProviderToken uses auth.remove not auth.set with empty key", () => {
+  const commandSrc = readFileSync(
+    join(__dirname, "..", "..", "remote-questions", "remote-command.ts"),
+    "utf-8",
+  );
+  // removeProviderToken should call auth.remove(provider), not auth.set(provider, { key: "" }).
+  // Setting an empty key pollutes the credentials array and shadows valid tokens.
+  const fnStart = commandSrc.indexOf("function removeProviderToken");
+  assert.ok(fnStart !== -1, "removeProviderToken should exist");
+  const fnEnd = commandSrc.indexOf("\n}", fnStart);
+  const fnBody = commandSrc.slice(fnStart, fnEnd);
+  assert.ok(fnBody.includes("auth.remove("), "removeProviderToken should call auth.remove()");
+  assert.ok(!fnBody.includes('key: ""'), "removeProviderToken should not set an empty key");
+});

package/src/resources/extensions/gsd/tests/session-lock-transient-read.test.ts

@@ -95,13 +95,13 @@ async function main(): Promise<void> {
       writeFileSync(lockFile, JSON.stringify(lockData, null, 2));
 
       // Simulate transient unavailability: move file away, spawn a child process
-      // to restore it after 100ms. The child runs outside our event loop so it
-      // fires even during busy-wait retries.
+      // to restore it shortly after. The child runs outside our event loop so it
+      // fires even during busy-wait retries. Give the test extra retry budget so
+      // it stays stable under full-suite CPU contention.
       renameSync(lockFile, tmpFile);
-      spawn('bash', ['-c', `sleep 0.1 && mv "${tmpFile}" "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
+      spawn('bash', ['-c', `sleep 0.05 && mv "${tmpFile}" "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
 
-      // With retries (3 attempts, 200ms delay), it should recover on 2nd or 3rd attempt
-      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 3, delayMs: 200 });
+      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 8, delayMs: 400 });
       assertTrue(result !== null, 'data recovered after transient unavailability');
       if (result) {
         assertEq(result.pid, process.pid, 'correct PID after recovery');
@@ -131,11 +131,12 @@ async function main(): Promise<void> {
       writeFileSync(lockFile, JSON.stringify(lockData, null, 2));
 
       // Remove read permission to simulate NFS/CIFS latency, then spawn a child
-      // to restore permissions after 100ms (runs outside our event loop).
+      // to restore permissions shortly after (runs outside our event loop).
+      // Use the same wider retry window as the rename case for full-suite stability.
       chmodSync(lockFile, 0o000);
-      spawn('bash', ['-c', `sleep 0.1 && chmod 644 "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
+      spawn('bash', ['-c', `sleep 0.05 && chmod 644 "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
 
-      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 3, delayMs: 200 });
+      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 8, delayMs: 400 });
       assertTrue(result !== null, 'data recovered after transient permission error');
       if (result) {
         assertEq(result.pid, process.pid, 'correct PID after permission recovery');

package/src/resources/extensions/gsd/tests/stash-pop-gsd-conflict.test.ts

@@ -0,0 +1,125 @@
+/**
+ * stash-pop-gsd-conflict.test.ts — Regression test for #2766.
+ *
+ * When a squash merge stash-pops and hits conflicts on .gsd/ state files,
+ * the UU entries block every subsequent merge. This test verifies that
+ * mergeMilestoneToMain auto-resolves .gsd/ conflicts by accepting HEAD
+ * and drops the stash, leaving the repo in a clean state.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { createAutoWorktree, mergeMilestoneToMain } from "../auto-worktree.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(), "wt-stashpop-test-")));
+  run("git init", dir);
+  run("git config user.email test@test.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"), "version: 1\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+  return dir;
+}
+
+function makeRoadmap(milestoneId: string, title: string, slices: Array<{ id: string; title: string }>): string {
+  const sliceLines = slices.map(s => `- [x] **${s.id}: ${s.title}**`).join("\n");
+  return `# ${milestoneId}: ${title}\n\n## Slices\n${sliceLines}\n`;
+}
+
+test("#2766: stash pop conflict on .gsd/ files is auto-resolved", () => {
+  const repo = createTempRepo();
+  try {
+    const wtPath = createAutoWorktree(repo, "M300");
+
+    // Add a slice with real code on the milestone branch
+    const normalizedPath = wtPath.replaceAll("\\", "/");
+    const worktreeName = normalizedPath.split("/").pop() || "M300";
+    const sliceBranch = `slice/${worktreeName}/S01`;
+    run(`git checkout -b "${sliceBranch}"`, wtPath);
+    writeFileSync(join(wtPath, "feature.ts"), "export const feature = true;\n");
+
+    // Modify .gsd/STATE.md on the milestone branch (diverges from main)
+    writeFileSync(join(wtPath, ".gsd", "STATE.md"), "version: 2-milestone\n");
+    run("git add .", wtPath);
+    run('git commit -m "add feature and update state"', wtPath);
+    run("git checkout milestone/M300", wtPath);
+    run(`git merge --no-ff "${sliceBranch}" -m "merge S01: feature"`, wtPath);
+
+    // Dirty .gsd/STATE.md in the main repo (stash will conflict on pop)
+    writeFileSync(join(repo, ".gsd", "STATE.md"), "version: 2-main-dirty\n");
+
+    const roadmap = makeRoadmap("M300", "Stash pop conflict test", [
+      { id: "S01", title: "Feature" },
+    ]);
+
+    // mergeMilestoneToMain should succeed — .gsd/ conflict auto-resolved
+    const result = mergeMilestoneToMain(repo, "M300", roadmap);
+    assert.ok(
+      result.commitMessage.includes("GSD-Milestone: M300"),
+      "merge succeeds despite stash pop conflict on .gsd/ file",
+    );
+    assert.ok(existsSync(join(repo, "feature.ts")), "milestone code merged to main");
+
+    // Verify repo is clean (no UU entries blocking future merges)
+    const status = run("git status --porcelain", repo);
+    assert.ok(
+      !status.includes("UU "),
+      "no unmerged (UU) entries remain after stash pop conflict resolution",
+    );
+
+    // Stash should be dropped (no remaining stash entries)
+    let stashList = "";
+    try { stashList = run("git stash list", repo); } catch { /* empty stash */ }
+    assert.strictEqual(stashList, "", "stash is empty after .gsd/ conflict auto-resolution");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* cleanup best-effort */ }
+  }
+});
+
+test("#2766: stash pop conflict on non-.gsd files preserves stash for manual resolution", () => {
+  const repo = createTempRepo();
+  try {
+    const wtPath = createAutoWorktree(repo, "M301");
+
+    // Add a slice that modifies a file also dirty on main
+    const normalizedPath = wtPath.replaceAll("\\", "/");
+    const worktreeName = normalizedPath.split("/").pop() || "M301";
+    const sliceBranch = `slice/${worktreeName}/S01`;
+    run(`git checkout -b "${sliceBranch}"`, wtPath);
+    writeFileSync(join(wtPath, "README.md"), "# milestone version\n");
+    run("git add .", wtPath);
+    run('git commit -m "update readme"', wtPath);
+    run("git checkout milestone/M301", wtPath);
+    run(`git merge --no-ff "${sliceBranch}" -m "merge S01: readme"`, wtPath);
+
+    // Dirty README.md in the main repo — this will conflict on stash pop
+    // and is NOT a .gsd/ file, so it should be left for manual resolution
+    writeFileSync(join(repo, "README.md"), "# locally modified\n");
+
+    const roadmap = makeRoadmap("M301", "Non-gsd stash conflict", [
+      { id: "S01", title: "Readme update" },
+    ]);
+
+    // The merge itself should still succeed (stash pop conflict is non-fatal)
+    const result = mergeMilestoneToMain(repo, "M301", roadmap);
+    assert.ok(
+      result.commitMessage.includes("GSD-Milestone: M301"),
+      "merge succeeds even with non-.gsd stash pop conflict",
+    );
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* cleanup best-effort */ }
+  }
+});

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

@@ -0,0 +1,30 @@
+// GSD — status-guards unit tests
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { isClosedStatus } from '../status-guards.ts';
+
+test('isClosedStatus: "complete" returns true', () => {
+  assert.equal(isClosedStatus('complete'), true);
+});
+
+test('isClosedStatus: "done" returns true', () => {
+  assert.equal(isClosedStatus('done'), true);
+});
+
+test('isClosedStatus: "pending" returns false', () => {
+  assert.equal(isClosedStatus('pending'), false);
+});
+
+test('isClosedStatus: "in_progress" returns false', () => {
+  assert.equal(isClosedStatus('in_progress'), false);
+});
+
+test('isClosedStatus: "active" returns false', () => {
+  assert.equal(isClosedStatus('active'), false);
+});
+
+test('isClosedStatus: "" (empty string) returns false', () => {
+  assert.equal(isClosedStatus(''), false);
+});