gsd-pi 2.70.1 → 2.71.0-dev.246c32d

package/src/resources/extensions/gsd/tests/forensics-stuck-loops.test.ts

@@ -101,3 +101,65 @@ test("#1943 detectStuckLoops ignores watchdog duplicates but flags real re-dispa
   assert.equal(anomalies.length, 1, `expected 1 anomaly (for the 3x dispatched task), got ${anomalies.length}`);
   assert.ok(anomalies[0].summary.includes("3 times"));
 });
+
+test("#3760 detectStuckLoops ignores cross-session recovery re-dispatches", () => {
+  const anomalies: ForensicAnomaly[] = [];
+
+  const units: UnitMetrics[] = [
+    makeUnit({
+      type: "plan-slice",
+      id: "M001/S02",
+      startedAt: 1000,
+      finishedAt: 2000,
+      autoSessionKey: "session-a",
+    }),
+    makeUnit({
+      type: "plan-slice",
+      id: "M001/S02",
+      startedAt: 5000,
+      finishedAt: 6000,
+      autoSessionKey: "session-b",
+    }),
+  ];
+
+  detectStuckLoops(units, anomalies);
+
+  assert.equal(anomalies.length, 0, "cross-session recovery should not be flagged as a stuck loop");
+});
+
+test("#3760 detectStuckLoops still flags repeated dispatches within one auto session", () => {
+  const anomalies: ForensicAnomaly[] = [];
+
+  const units: UnitMetrics[] = [
+    makeUnit({
+      type: "complete-slice",
+      id: "M011/S02",
+      startedAt: 1000,
+      finishedAt: 2000,
+      autoSessionKey: "session-a",
+    }),
+    makeUnit({
+      type: "complete-slice",
+      id: "M011/S02",
+      startedAt: 5000,
+      finishedAt: 6000,
+      autoSessionKey: "session-a",
+    }),
+    makeUnit({
+      type: "complete-slice",
+      id: "M011/S02",
+      startedAt: 9000,
+      finishedAt: 10000,
+      autoSessionKey: "session-b",
+    }),
+  ];
+
+  detectStuckLoops(units, anomalies);
+
+  assert.equal(anomalies.length, 1, "within-session retries should still be flagged");
+  assert.ok(anomalies[0].summary.includes("2 times"), `summary should reflect the worst same-session loop: ${anomalies[0].summary}`);
+  assert.ok(
+    anomalies[0].details.includes("Cross-session recovery runs are ignored"),
+    `details should explain the session-aware rule: ${anomalies[0].details}`,
+  );
+});

package/src/resources/extensions/gsd/tests/format-shortcut.test.ts

@@ -4,6 +4,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { formatShortcut } from '../files.ts';
+import { formattedShortcutPair, primaryShortcutCombo, fallbackShortcutCombo } from '../shortcut-defs.ts';
 
 // ─── formatShortcut renders per-platform shortcuts ──────────────────────
 
@@ -67,3 +68,33 @@ test('formatShortcut: passes through plain key names', () => {
   assert.strictEqual(formatShortcut('Escape'), 'Escape');
   assert.strictEqual(formatShortcut('Enter'), 'Enter');
 });
+
+test("shortcut-defs: exposes canonical dashboard combos", () => {
+  assert.equal(primaryShortcutCombo("dashboard"), "Ctrl+Alt+G");
+  assert.equal(fallbackShortcutCombo("dashboard"), "Ctrl+Shift+G");
+});
+
+test("shortcut-defs: formats shortcut pair using platform symbols", () => {
+  const pair = formattedShortcutPair("notifications");
+  if (process.platform === "darwin") {
+    assert.equal(pair, "⌃⌥N / ⌃⇧N");
+  } else {
+    assert.equal(pair, "Ctrl+Alt+N / Ctrl+Shift+N");
+  }
+});
+
+test("shortcut-defs: parallel shortcut omits fallback (hasFallback: false)", () => {
+  const pair = formattedShortcutPair("parallel");
+  if (process.platform === "darwin") {
+    assert.equal(pair, "⌃⌥P", "parallel should only show primary combo");
+  } else {
+    assert.equal(pair, "Ctrl+Alt+P", "parallel should only show primary combo");
+  }
+  // Verify it does NOT contain the fallback separator
+  assert.ok(!pair.includes("/"), "parallel pair should not contain fallback separator");
+});
+
+test("shortcut-defs: dashboard shortcut includes fallback (hasFallback: true)", () => {
+  const pair = formattedShortcutPair("dashboard");
+  assert.ok(pair.includes("/"), "dashboard pair should contain fallback separator");
+});

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

@@ -186,4 +186,31 @@ describe("evaluating-gates phase", () => {
     insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q5", scope: "task", taskId: "T01" });
     assert.equal(getPendingSliceGateCount("M001", "S01"), 1);
   });
+
+  test("Q8 (owned by complete-slice) does not block evaluating-gates phase", async () => {
+    // Regression: Q8 is stored with scope:"slice" but owned by the
+    // complete-slice turn. Before the gate registry landed, deriveState
+    // counted Q8 as a blocker for evaluating-gates while the gate-evaluate
+    // prompt silently dropped Q8 — an unrecoverable stall. After the
+    // registry change, deriveState filters by owner turn, so Q8 never
+    // blocks evaluating-gates.
+    planSlice(tmpDir);
+    await renderPlanFromDb(tmpDir, "M001", "S01");
+
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q4", scope: "slice" });
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q8", scope: "slice" });
+
+    saveGateResult({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", verdict: "pass", rationale: "OK", findings: "" });
+    saveGateResult({ milestoneId: "M001", sliceId: "S01", gateId: "Q4", verdict: "omitted", rationale: "N/A", findings: "" });
+    // Q8 deliberately left pending — it's complete-slice's problem.
+
+    invalidateStateCache();
+    const state = await deriveState(tmpDir);
+    assert.equal(
+      state.phase,
+      "executing",
+      `pending Q8 must not stall evaluating-gates — got phase=${state.phase}`,
+    );
+  });
 });

package/src/resources/extensions/gsd/tests/gate-registry.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Gate registry tests — enforce that every declared GateId has a registry
+ * entry, that every owner-turn bucket is non-empty, and that coverage
+ * assertions fail loudly instead of silently skipping unknown gates.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  GATE_REGISTRY,
+  assertGateCoverage,
+  getGateDefinition,
+  getGateIdsForTurn,
+  getGatesForTurn,
+  getOwnerTurn,
+  type OwnerTurn,
+} from "../gate-registry.ts";
+import type { GateId } from "../types.ts";
+
+/** Authoritative list of GateIds as declared in types.ts. */
+const ALL_GATE_IDS: readonly GateId[] = [
+  "Q3", "Q4", "Q5", "Q6", "Q7", "Q8",
+  "MV01", "MV02", "MV03", "MV04",
+];
+
+const ALL_OWNER_TURNS: readonly OwnerTurn[] = [
+  "gate-evaluate",
+  "execute-task",
+  "complete-slice",
+  "validate-milestone",
+];
+
+describe("gate-registry", () => {
+  test("every declared GateId has a registry entry", () => {
+    for (const id of ALL_GATE_IDS) {
+      const def = GATE_REGISTRY[id];
+      assert.ok(def, `missing registry entry for gate ${id}`);
+      assert.equal(def.id, id);
+      assert.ok(def.question.length > 0, `${id} missing question`);
+      assert.ok(def.guidance.length > 0, `${id} missing guidance`);
+      assert.ok(def.promptSection.length > 0, `${id} missing promptSection`);
+    }
+  });
+
+  test("registry contains no extra gate entries", () => {
+    const registryIds = new Set(Object.keys(GATE_REGISTRY));
+    const declaredIds = new Set<string>(ALL_GATE_IDS);
+    for (const id of registryIds) {
+      assert.ok(declaredIds.has(id), `registry has unknown gate ${id}`);
+    }
+  });
+
+  test("every owner turn owns at least one gate", () => {
+    for (const turn of ALL_OWNER_TURNS) {
+      const gates = getGatesForTurn(turn);
+      assert.ok(
+        gates.length > 0,
+        `owner turn "${turn}" has no gates — likely a registry mistake`,
+      );
+    }
+  });
+
+  test("owner turn buckets are disjoint", () => {
+    const seen = new Set<string>();
+    for (const turn of ALL_OWNER_TURNS) {
+      for (const def of getGatesForTurn(turn)) {
+        assert.ok(!seen.has(def.id), `gate ${def.id} claimed by two turns`);
+        seen.add(def.id);
+      }
+    }
+    // Every gate should appear in exactly one bucket.
+    assert.equal(seen.size, ALL_GATE_IDS.length);
+  });
+
+  test("getOwnerTurn round-trips against GATE_REGISTRY", () => {
+    for (const id of ALL_GATE_IDS) {
+      const turn = getOwnerTurn(id);
+      const idsForTurn = getGateIdsForTurn(turn);
+      assert.ok(idsForTurn.has(id), `${id} not in ${turn} bucket`);
+    }
+  });
+
+  test("getGateDefinition returns undefined for unknown ids", () => {
+    assert.equal(getGateDefinition("Q99"), undefined);
+    assert.equal(getGateDefinition("not-a-gate"), undefined);
+  });
+});
+
+describe("assertGateCoverage", () => {
+  test("throws when a row is owned by a different turn", () => {
+    // Q8 is owned by complete-slice, not gate-evaluate — this used to be
+    // silently dropped by the old `if (!meta) continue;` filter, causing
+    // the evaluating-gates phase to stall.
+    assert.throws(
+      () => assertGateCoverage([{ gate_id: "Q8" }], "gate-evaluate"),
+      (err: Error) =>
+        err.message.includes("Q8") && err.message.includes("gate-evaluate"),
+    );
+  });
+
+  test("throws when a row has an unknown gate id", () => {
+    assert.throws(
+      () => assertGateCoverage([{ gate_id: "Q999" as GateId }], "gate-evaluate", { requireAll: false }),
+      (err: Error) => err.message.includes("Q999"),
+    );
+  });
+
+  test("throws when requireAll is true and an owned gate is missing", () => {
+    // gate-evaluate owns Q3 and Q4. Passing only Q3 should fail.
+    assert.throws(
+      () => assertGateCoverage([{ gate_id: "Q3" }], "gate-evaluate", { requireAll: true }),
+      (err: Error) => err.message.includes("Q4"),
+    );
+  });
+
+  test("passes when requireAll is false and only a subset is pending", () => {
+    // execute-task owns Q5/Q6/Q7, but a task with no external dependencies
+    // may only have Q7 seeded. That's still valid coverage.
+    assert.doesNotThrow(() =>
+      assertGateCoverage([{ gate_id: "Q7" }], "execute-task", { requireAll: false }),
+    );
+  });
+
+  test("passes when requireAll is true and every owned gate is pending", () => {
+    assert.doesNotThrow(() =>
+      assertGateCoverage(
+        [{ gate_id: "Q3" }, { gate_id: "Q4" }],
+        "gate-evaluate",
+        { requireAll: true },
+      ),
+    );
+  });
+
+  test("empty pending list passes when requireAll is false", () => {
+    assert.doesNotThrow(() =>
+      assertGateCoverage([], "complete-slice", { requireAll: false }),
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/gsd-no-project-error.test.ts

@@ -0,0 +1,73 @@
+/**
+ * GSDNoProjectError — tests for friendly home-directory error handling.
+ *
+ * Verifies that GSDNoProjectError is thrown for blocked directories and
+ * that the dispatcher catches it with a user-friendly message.
+ */
+
+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 contextSrc = readFileSync(join(__dirname, "..", "commands", "context.ts"), "utf-8");
+const dispatcherSrc = readFileSync(join(__dirname, "..", "commands", "dispatcher.ts"), "utf-8");
+
+// ─── GSDNoProjectError class ──────────────────────────────────────────────
+
+test("GSDNoProjectError class is exported from context.ts", () => {
+  assert.ok(
+    contextSrc.includes("export class GSDNoProjectError extends Error"),
+    "GSDNoProjectError should be an exported Error subclass",
+  );
+});
+
+test("GSDNoProjectError sets name property", () => {
+  assert.ok(
+    contextSrc.includes('this.name = "GSDNoProjectError"'),
+    "GSDNoProjectError should set its name for instanceof checks",
+  );
+});
+
+// ─── projectRoot blocked directory handling ───────────────────────────────
+
+test("projectRoot uses validateDirectory and checks for blocked severity", () => {
+  assert.ok(
+    contextSrc.includes("validateDirectory(pathToCheck)"),
+    "projectRoot should call validateDirectory",
+  );
+  assert.ok(
+    contextSrc.includes('result.severity === "blocked"'),
+    "projectRoot should check for blocked severity",
+  );
+});
+
+test("projectRoot throws GSDNoProjectError on blocked directory", () => {
+  assert.ok(
+    contextSrc.includes("throw new GSDNoProjectError"),
+    "projectRoot should throw GSDNoProjectError when directory is blocked",
+  );
+});
+
+// ─── Dispatcher catch ─────────────────────────────────────────────────────
+
+test("dispatcher catches GSDNoProjectError with user-friendly message", () => {
+  assert.ok(
+    dispatcherSrc.includes("err instanceof GSDNoProjectError"),
+    "dispatcher should catch GSDNoProjectError specifically",
+  );
+  assert.ok(
+    dispatcherSrc.includes("cd"),
+    "error message should suggest cd-ing into a project directory",
+  );
+});
+
+test("dispatcher re-throws non-GSDNoProjectError exceptions", () => {
+  assert.ok(
+    dispatcherSrc.includes("throw err"),
+    "dispatcher should re-throw unexpected errors",
+  );
+});

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

@@ -0,0 +1,180 @@
+// gsd / infra-errors cooldown detection tests
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  isTransientCooldownError,
+  getCooldownRetryAfterMs,
+  MAX_COOLDOWN_RETRIES,
+  COOLDOWN_FALLBACK_WAIT_MS,
+} from "../auto/infra-errors.js";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+describe("infra-errors cooldown constants", () => {
+  test("COOLDOWN_FALLBACK_WAIT_MS is a positive number greater than the 30s rate-limit backoff", () => {
+    assert.ok(typeof COOLDOWN_FALLBACK_WAIT_MS === "number");
+    assert.ok(COOLDOWN_FALLBACK_WAIT_MS > 30_000, "should exceed the 30s rate-limit window");
+  });
+
+  test("MAX_COOLDOWN_RETRIES is a positive integer", () => {
+    assert.ok(typeof MAX_COOLDOWN_RETRIES === "number");
+    assert.ok(Number.isInteger(MAX_COOLDOWN_RETRIES));
+    assert.ok(MAX_COOLDOWN_RETRIES > 0);
+  });
+
+  test("COOLDOWN_FALLBACK_WAIT_MS is 35_000", () => {
+    assert.equal(COOLDOWN_FALLBACK_WAIT_MS, 35_000);
+  });
+
+  test("MAX_COOLDOWN_RETRIES is 5", () => {
+    assert.equal(MAX_COOLDOWN_RETRIES, 5);
+  });
+});
+
+// ─── isTransientCooldownError: structured detection ──────────────────────────
+
+describe("isTransientCooldownError — structured code detection", () => {
+  test("returns true for an object with code === AUTH_COOLDOWN", () => {
+    const err = { code: "AUTH_COOLDOWN", message: "credentials in cooldown" };
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns true for a real CredentialCooldownError-shaped error", () => {
+    // Simulate CredentialCooldownError without importing sdk.ts (leaf-module rule)
+    const err = Object.assign(new Error('All credentials for "anthropic" are in a cooldown window.'), {
+      code: "AUTH_COOLDOWN",
+      retryAfterMs: 30_000,
+      name: "CredentialCooldownError",
+    });
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns false for an object with a different code", () => {
+    const err = { code: "ENOSPC", message: "disk full" };
+    assert.equal(isTransientCooldownError(err), false);
+  });
+
+  test("returns false for an object with no code property", () => {
+    const err = { message: "some random error" };
+    assert.equal(isTransientCooldownError(err), false);
+  });
+});
+
+// ─── isTransientCooldownError: message fallback ───────────────────────────────
+
+describe("isTransientCooldownError — message fallback (cross-process)", () => {
+  test("returns true when message contains 'in a cooldown window'", () => {
+    const err = new Error('All credentials for "openai" are in a cooldown window. Please wait.');
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns true when message matches case-insensitively", () => {
+    const err = new Error("credentials IN A COOLDOWN WINDOW");
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns true for a plain string containing cooldown window phrase", () => {
+    assert.equal(isTransientCooldownError("all keys in a cooldown window"), true);
+  });
+
+  test("returns false for a generic error message", () => {
+    const err = new Error("rate limit exceeded");
+    assert.equal(isTransientCooldownError(err), false);
+  });
+
+  test("returns false for an error message about auth failure without cooldown phrase", () => {
+    const err = new Error("Authentication failed: invalid API key");
+    assert.equal(isTransientCooldownError(err), false);
+  });
+});
+
+// ─── isTransientCooldownError: edge cases ────────────────────────────────────
+
+describe("isTransientCooldownError — edge cases", () => {
+  test("returns false for null", () => {
+    assert.equal(isTransientCooldownError(null), false);
+  });
+
+  test("returns false for undefined", () => {
+    assert.equal(isTransientCooldownError(undefined), false);
+  });
+
+  test("returns false for a number", () => {
+    assert.equal(isTransientCooldownError(42), false);
+  });
+
+  test("returns false for an empty object", () => {
+    assert.equal(isTransientCooldownError({}), false);
+  });
+
+  test("returns false for an object with code === AUTH_COOLDOWN as a non-string", () => {
+    // code must be a string matching "AUTH_COOLDOWN" exactly
+    const err = { code: 42 };
+    assert.equal(isTransientCooldownError(err), false);
+  });
+});
+
+// ─── getCooldownRetryAfterMs: structured extraction ──────────────────────────
+
+describe("getCooldownRetryAfterMs — structured extraction", () => {
+  test("returns retryAfterMs when code is AUTH_COOLDOWN and retryAfterMs is set", () => {
+    const err = { code: "AUTH_COOLDOWN", retryAfterMs: 30_000 };
+    assert.equal(getCooldownRetryAfterMs(err), 30_000);
+  });
+
+  test("returns undefined when code is AUTH_COOLDOWN but retryAfterMs is absent", () => {
+    const err = { code: "AUTH_COOLDOWN" };
+    assert.equal(getCooldownRetryAfterMs(err), undefined);
+  });
+
+  test("returns 0 when retryAfterMs is explicitly 0", () => {
+    const err = { code: "AUTH_COOLDOWN", retryAfterMs: 0 };
+    assert.equal(getCooldownRetryAfterMs(err), 0);
+  });
+
+  test("returns undefined for an error with a different code even if retryAfterMs is set", () => {
+    const err = { code: "ENOSPC", retryAfterMs: 5_000 };
+    assert.equal(getCooldownRetryAfterMs(err), undefined);
+  });
+
+  test("returns undefined for a plain Error with no code property", () => {
+    const err = new Error("something went wrong");
+    assert.equal(getCooldownRetryAfterMs(err), undefined);
+  });
+
+  test("returns retryAfterMs from a full CredentialCooldownError-shaped object", () => {
+    const err = Object.assign(new Error('All credentials for "anthropic" are in a cooldown window.'), {
+      code: "AUTH_COOLDOWN",
+      retryAfterMs: 15_000,
+      name: "CredentialCooldownError",
+    });
+    assert.equal(getCooldownRetryAfterMs(err), 15_000);
+  });
+});
+
+// ─── getCooldownRetryAfterMs: edge cases ─────────────────────────────────────
+
+describe("getCooldownRetryAfterMs — edge cases", () => {
+  test("returns undefined for null", () => {
+    assert.equal(getCooldownRetryAfterMs(null), undefined);
+  });
+
+  test("returns undefined for undefined", () => {
+    assert.equal(getCooldownRetryAfterMs(undefined), undefined);
+  });
+
+  test("returns undefined for a plain string", () => {
+    assert.equal(getCooldownRetryAfterMs("AUTH_COOLDOWN"), undefined);
+  });
+
+  test("returns undefined for an empty object", () => {
+    assert.equal(getCooldownRetryAfterMs({}), undefined);
+  });
+
+  test("returns undefined for a number", () => {
+    assert.equal(getCooldownRetryAfterMs(42), undefined);
+  });
+});

package/src/resources/extensions/gsd/tests/integration/auto-worktree-milestone-merge.test.ts

@@ -12,7 +12,7 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, readFileSync, symlinkSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -44,6 +44,27 @@ function createTempRepo(): string {
   return dir;
 }
 
+function createTempRepoWithExternalGsd(): { repo: string; externalState: string } {
+  const realTmp = realpathSync(tmpdir());
+  const repo = realpathSync(mkdtempSync(join(realTmp, "wt-ms-merge-ext-test-")));
+  const externalState = realpathSync(mkdtempSync(join(realTmp, "wt-ms-merge-ext-state-")));
+
+  run("git init", repo);
+  run("git config user.email test@test.com", repo);
+  run("git config user.name Test", repo);
+
+  mkdirSync(join(externalState, "worktrees"), { recursive: true });
+  symlinkSync(externalState, join(repo, ".gsd"));
+
+  writeFileSync(join(repo, "README.md"), "# test\n");
+  writeFileSync(join(externalState, "STATE.md"), "# State\n");
+  run("git add .", repo);
+  run("git commit -m init", repo);
+  run("git branch -M main", repo);
+
+  return { repo, externalState };
+}
+
 /** Minimal roadmap content for mergeMilestoneToMain. */
 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");
@@ -87,6 +108,12 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     return d;
   }
 
+  function freshRepoWithExternalGsd(): { repo: string; externalState: string } {
+    const { repo, externalState } = createTempRepoWithExternalGsd();
+    tempDirs.push(repo, externalState);
+    return { repo, externalState };
+  }
+
   afterEach(() => {
     process.chdir(savedCwd);
     for (const d of tempDirs) {
@@ -638,6 +665,44 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
       "#1906: codeFilesChanged must be false when only .gsd/ files were merged");
   });
 
+  test("#2156: mergeMilestoneToMain removes external-state worktrees using the milestone branch name", () => {
+    const { repo, externalState } = freshRepoWithExternalGsd();
+    const wtPath = createAutoWorktree(repo, "M215");
+
+    addSliceToMilestone(repo, wtPath, "M215", "S01", "External cleanup", [
+      { file: "external-cleanup.ts", content: "export const externalCleanup = true;\n", message: "add external cleanup" },
+    ]);
+
+    const realWtPath = realpathSync(wtPath);
+    assert.ok(
+      realWtPath.startsWith(externalState),
+      `worktree should be registered under external .gsd state, got ${realWtPath}`,
+    );
+
+    // Recreate the exact divergence from #1852: local .gsd/ is replaced with a
+    // stale real directory, so worktreePath() no longer matches git's record.
+    unlinkSync(join(repo, ".gsd"));
+    mkdirSync(join(repo, ".gsd", "worktrees", "M215"), { recursive: true });
+    writeFileSync(join(repo, ".gsd", "STATE.md"), "# Local stale state\n");
+    writeFileSync(join(repo, ".gsd", "worktrees", "M215", "stale.txt"), "stale local artifact\n");
+
+    const roadmap = makeRoadmap("M215", "External cleanup", [
+      { id: "S01", title: "External cleanup" },
+    ]);
+
+    mergeMilestoneToMain(repo, "M215", roadmap);
+
+    assert.ok(
+      !run("git worktree list", repo).includes("M215"),
+      "merged milestone worktree should be removed from git worktree list",
+    );
+    assert.ok(!existsSync(realWtPath), "real external worktree directory should be removed");
+    assert.ok(
+      !run("git branch", repo).includes("milestone/M215"),
+      "milestone branch should be deleted after merge cleanup",
+    );
+  });
+
   test("#2912: MERGE_HEAD cleaned up after squash-merge conflict", () => {
     const repo = freshRepo();
     const wtPath = createAutoWorktree(repo, "M291");