gsd-pi 2.75.0 → 2.76.0

package/src/resources/extensions/gsd/tests/finalize-timeout-guard.test.ts

@@ -213,25 +213,42 @@ function getRunFinalizeBody(phasesSource: string): string {
 
   const fnBody = getRunFinalizeBody(phasesSource);
 
-  // Both timeout handlers should increment consecutiveFinalizeTimeouts
-  const incrementCount = (fnBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;
+  const helperCallCount = (fnBody.match(/failClosedOnFinalizeTimeout\(/g) || []).length;
   assertTrue(
-    incrementCount >= 2,
-    `should increment consecutiveFinalizeTimeouts in both pre and post handlers (found ${incrementCount})`,
+    helperCallCount >= 2,
+    `runFinalize should route both timeout branches through failClosedOnFinalizeTimeout (found ${helperCallCount})`,
   );
 
-  // Both timeout handlers should check MAX_FINALIZE_TIMEOUTS for escalation
-  const escalationCount = (fnBody.match(/MAX_FINALIZE_TIMEOUTS/g) || []).length;
+  const helperStart = phasesSource.indexOf("async function failClosedOnFinalizeTimeout");
+  assertTrue(helperStart > 0, "failClosedOnFinalizeTimeout helper should exist");
+  const helperEnd = phasesSource.indexOf("// ─── runPreDispatch", helperStart);
+  const helperBody = phasesSource.slice(helperStart, helperEnd > helperStart ? helperEnd : undefined);
+
+  const incrementCount = (helperBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;
   assertTrue(
-    escalationCount >= 2,
-    `should check MAX_FINALIZE_TIMEOUTS in both handlers (found ${escalationCount})`,
+    incrementCount >= 1,
+    `timeout helper should increment consecutiveFinalizeTimeouts (found ${incrementCount})`,
   );
 
-  // Both timeout handlers should null out s.currentUnit to prevent late mutations
-  const detachCount = (fnBody.match(/s\.currentUnit\s*=\s*null/g) || []).length;
+  const detachCount = (helperBody.match(/s\.currentUnit\s*=\s*null/g) || []).length;
+  assertTrue(
+    detachCount >= 1,
+    `timeout helper should detach s.currentUnit (found ${detachCount})`,
+  );
+
+  const pauseCount = (helperBody.match(/pauseAuto\(/g) || []).length;
+  assertTrue(
+    pauseCount >= 1,
+    `timeout helper should pause auto-mode (found ${pauseCount})`,
+  );
+
+  assertTrue(
+    helperBody.includes('eventType: "unit-end"'),
+    "timeout helper should emit a terminal unit-end event",
+  );
   assertTrue(
-    detachCount >= 2,
-    `should detach s.currentUnit in both timeout handlers (found ${detachCount})`,
+    helperBody.includes('phase: "finalize-timeout"'),
+    "timeout helper should persist finalize-timeout runtime state",
   );
 
   // Successful finalize should reset the counter

package/src/resources/extensions/gsd/tests/flat-rate-routing-guard.test.ts

@@ -6,8 +6,14 @@
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { buildFlatRateContext, isFlatRateProvider, resolvePreferredModelConfig } from "../auto-model-selection.ts";
 
+const __dirname_4386 = dirname(fileURLToPath(import.meta.url));
+
 describe("flat-rate provider routing guard (#3453)", () => {
 
   test("isFlatRateProvider returns true for github-copilot", () => {
@@ -184,3 +190,103 @@ describe("buildFlatRateContext()", () => {
     assert.equal(result.authMode, undefined);
   });
 });
+
+// ─── #4386: allow_flat_rate_providers opt-in ────────────────────────────────
+
+describe("flat-rate routing opt-in (#4386)", () => {
+  function withPrefs(prefsYaml: string, fn: () => void): void {
+    const originalCwd = process.cwd();
+    const originalGsdHome = process.env.GSD_HOME;
+    const tempProject = mkdtempSync(join(tmpdir(), "gsd-4386-project-"));
+    const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-4386-home-"));
+    try {
+      mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+      writeFileSync(
+        join(tempProject, ".gsd", "PREFERENCES.md"),
+        ["---", "version: 1", prefsYaml, "---"].join("\n"),
+        "utf-8",
+      );
+      process.env.GSD_HOME = tempGsdHome;
+      process.chdir(tempProject);
+      fn();
+    } finally {
+      process.chdir(originalCwd);
+      if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = originalGsdHome;
+      rmSync(tempProject, { recursive: true, force: true });
+      rmSync(tempGsdHome, { recursive: true, force: true });
+    }
+  }
+
+  test("default (opt-in absent): flat-rate start model still returns undefined", () => {
+    withPrefs(
+      [
+        "dynamic_routing:",
+        "  enabled: true",
+        "  tier_models:",
+        "    heavy: claude-opus-4-6",
+      ].join("\n"),
+      () => {
+        const result = resolvePreferredModelConfig("execute-task", {
+          provider: "claude-code",
+          id: "claude-opus-4-6",
+        });
+        assert.equal(result, undefined, "default must preserve #3453 bypass");
+      },
+    );
+  });
+
+  test("opt-in: synthesizes a routing config for flat-rate start model", () => {
+    withPrefs(
+      [
+        "dynamic_routing:",
+        "  enabled: true",
+        "  allow_flat_rate_providers: true",
+        "  tier_models:",
+        "    heavy: claude-opus-4-6",
+      ].join("\n"),
+      () => {
+        const result = resolvePreferredModelConfig("execute-task", {
+          provider: "claude-code",
+          id: "claude-opus-4-6",
+        });
+        assert.ok(result, "routing config should be synthesized");
+        assert.equal(result!.primary, "claude-opus-4-6");
+      },
+    );
+  });
+
+  test("explicit opt-out: flat-rate bypass still fires", () => {
+    withPrefs(
+      [
+        "dynamic_routing:",
+        "  enabled: true",
+        "  allow_flat_rate_providers: false",
+        "  tier_models:",
+        "    heavy: claude-opus-4-6",
+      ].join("\n"),
+      () => {
+        const result = resolvePreferredModelConfig("execute-task", {
+          provider: "claude-code",
+          id: "claude-opus-4-6",
+        });
+        assert.equal(result, undefined, "explicit opt-out behaves like default");
+      },
+    );
+  });
+});
+
+// ─── Banner transparency: auto-start respects the opt-in (#4386) ────────────
+
+describe("auto-start banner respects allow_flat_rate_providers (#4386)", () => {
+  test("banner expression gates flat-rate disable on allow_flat_rate_providers", () => {
+    const src = readFileSync(
+      join(__dirname_4386, "..", "auto-start.ts"),
+      "utf-8",
+    );
+    assert.ok(
+      src.includes("routingConfig.allow_flat_rate_providers"),
+      "auto-start banner must read allow_flat_rate_providers so the banner reflects the opt-in",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/forensics-hook-key-parse.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Regression test for #2826: detectMissingArtifacts must parse hook/
+ * compound unit types correctly, not just the first slash segment.
+ *
+ * Keys like "hook/telegram-progress/M007/S01" must yield:
+ *   unitType = "hook/telegram-progress"  (not "hook")
+ *   unitId   = "M007/S01"               (not "telegram-progress/M007/S01")
+ *
+ * The fix extracts a shared splitCompletedKey() helper used by both
+ * forensics.ts and doctor-runtime-checks.ts.
+ */
+import { describe, it } 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 gsdDir = join(__dirname, "..");
+
+describe("forensics hook compound key parsing (#2826)", () => {
+  const forensicsSrc = readFileSync(join(gsdDir, "forensics.ts"), "utf-8");
+  const doctorSrc = readFileSync(join(gsdDir, "doctor-runtime-checks.ts"), "utf-8");
+
+  it("forensics.ts exports splitCompletedKey helper", () => {
+    assert.ok(
+      forensicsSrc.includes("export function splitCompletedKey("),
+      "forensics.ts must export splitCompletedKey()",
+    );
+  });
+
+  it("splitCompletedKey handles hook/ prefix by splitting on the second slash", () => {
+    assert.ok(
+      forensicsSrc.includes('key.startsWith("hook/")'),
+      'splitCompletedKey must branch on key.startsWith("hook/")',
+    );
+    assert.ok(
+      forensicsSrc.includes('key.indexOf("/", 5)'),
+      'splitCompletedKey must use indexOf("/", 5) to find second slash past "hook/"',
+    );
+  });
+
+  it("detectMissingArtifacts delegates to splitCompletedKey", () => {
+    const fnStart = forensicsSrc.indexOf("function detectMissingArtifacts(");
+    assert.ok(fnStart !== -1, "detectMissingArtifacts must exist in forensics.ts");
+    const fnBody = forensicsSrc.slice(fnStart, fnStart + 1000);
+    assert.ok(
+      fnBody.includes("splitCompletedKey("),
+      "detectMissingArtifacts must call splitCompletedKey() rather than inline the split logic",
+    );
+  });
+
+  it("doctor-runtime-checks.ts imports and uses splitCompletedKey", () => {
+    assert.ok(
+      doctorSrc.includes('from "./forensics.js"'),
+      'doctor-runtime-checks.ts must import from "./forensics.js"',
+    );
+    assert.ok(
+      doctorSrc.includes("splitCompletedKey"),
+      "doctor-runtime-checks.ts must use splitCompletedKey()",
+    );
+  });
+
+  it("splitCompletedKey unit: plain type", () => {
+    // Inline test of the helper logic to guard against future regressions
+    // without needing a filesystem setup.
+    const src = forensicsSrc;
+    // Confirm the plain-type branch also exists
+    assert.ok(
+      src.includes('slashIdx = key.indexOf("/")') || src.includes("key.indexOf(\"/\")"),
+      "splitCompletedKey must handle plain (non-hook) keys via first-slash split",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/graph-operations.test.ts

@@ -19,7 +19,6 @@ import {
   markStepComplete,
   expandIteration,
   initializeGraph,
-  graphFromDefinition,
   type WorkflowGraph,
   type GraphStep,
 } from "../graph.ts";
@@ -459,9 +458,6 @@ describe("initializeGraph", () => {
     assert.deepStrictEqual(graph.steps[2].dependsOn, ["s1", "s2"]);
   });
 
-  it("is also exported as graphFromDefinition (backward compat)", (t) => {
-    assert.equal(graphFromDefinition, initializeGraph);
-  });
 });
 
 // ─── Atomic write safety ─────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/gsd-db.test.ts

@@ -23,6 +23,7 @@ import {
   insertTask,
   getTask,
   getSliceTasks,
+  checkpointDatabase,
 } from '../gsd-db.ts';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -80,7 +81,7 @@ describe('gsd-db', () => {
     // Check schema_version table
     const adapter = _getAdapter()!;
     const version = adapter.prepare('SELECT MAX(version) as version FROM schema_version').get();
-    assert.deepStrictEqual(version?.['version'], 15, 'schema version should be 15');
+    assert.deepStrictEqual(version?.['version'], 20, 'schema version should be 20');
 
     // Check tables exist by querying them
     const dRows = adapter.prepare('SELECT count(*) as cnt FROM decisions').get();
@@ -518,6 +519,48 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  // ─── checkpointDatabase ────────────────────────────────────────────────────
+
+  describe('checkpointDatabase', () => {
+    test('checkpointDatabase: flushes WAL into base file (TRUNCATE)', (t) => {
+      const dbPath = tempDbPath();
+      t.after(() => cleanup(dbPath));
+
+      openDatabase(dbPath);
+
+      // Write enough data to ensure WAL has content
+      transaction(() => {
+        insertDecision({
+          id: 'D001',
+          when_context: 'test',
+          scope: 'global',
+          decision: 'WAL flush test',
+          choice: 'checkpoint',
+          rationale: 'WAL checkpoint regression test — #4418',
+          revisable: 'yes',
+          made_by: 'agent',
+          superseded_by: null,
+        });
+      });
+
+      const walPath = dbPath + '-wal';
+      assert.ok(fs.existsSync(walPath), 'WAL file should exist after write');
+      const walSizeBefore = fs.statSync(walPath).size;
+      assert.ok(walSizeBefore > 0, 'WAL file should be non-empty after write');
+
+      checkpointDatabase();
+
+      const walSizeAfter = fs.existsSync(walPath) ? fs.statSync(walPath).size : 0;
+      assert.equal(walSizeAfter, 0, 'WAL file should be truncated to 0 after checkpoint');
+    });
+
+    test('checkpointDatabase: is a no-op when no database is open', () => {
+      closeDatabase();
+      // Must not throw
+      assert.doesNotThrow(() => checkpointDatabase());
+    });
+  });
+
   // ─── Final Report ──────────────────────────────────────────────────────────
 
 });

package/src/resources/extensions/gsd/tests/health-widget.test.ts

@@ -191,6 +191,7 @@ test("session_start bootstraps the health widget alongside notifications", async
   });
 
   const widgets: string[] = [];
+  const statuses: string[] = [];
   const handlers = new Map<string, (event: unknown, ctx: any) => Promise<void> | void>();
   const pi = {
     on(event: string, handler: (event: unknown, ctx: any) => Promise<void> | void) {
@@ -206,7 +207,9 @@ test("session_start bootstraps the health widget alongside notifications", async
     hasUI: true,
     ui: {
       notify: () => {},
-      setStatus: () => {},
+      setStatus: (key: string) => {
+        statuses.push(key);
+      },
       setWorkingMessage: () => {},
       onTerminalInput: () => () => {},
       setWidget: (key: string) => {
@@ -220,5 +223,8 @@ test("session_start bootstraps the health widget alongside notifications", async
   } as any);
 
   assert.ok(widgets.includes("gsd-health"), "health widget is bootstrapped");
-  assert.ok(widgets.includes("gsd-notifications"), "notification widget still boots");
+  assert.ok(
+    statuses.some((k) => k.includes("notifications")),
+    "notification status chip is registered",
+  );
 });

package/src/resources/extensions/gsd/tests/init-prefs-routing.test.ts

@@ -0,0 +1,190 @@
+// GSD — /gsd init → unified preferences-write routing tests.
+//
+// Verifies the refactor that routes init's preferences write through the same
+// writePreferencesFile helper used by handlePrefsWizard, and that the typed
+// ProjectPreferences shape maps correctly into the wizard's
+// Record<string, unknown> shape.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { mapInitPrefsToWizardShape } from "../init-wizard.ts";
+import { writePreferencesFile } from "../commands-prefs-wizard.ts";
+
+test("mapInitPrefsToWizardShape — full roundtrip with all fields", () => {
+  const out = mapInitPrefsToWizardShape({
+    mode: "team",
+    gitIsolation: "branch",
+    mainBranch: "develop",
+    verificationCommands: ["npm test", "npm run lint"],
+    customInstructions: ["Use TypeScript strict mode", "Always write tests"],
+    tokenProfile: "quality",
+    skipResearch: true,
+    autoPush: false,
+  });
+
+  assert.equal(out.mode, "team");
+  assert.deepEqual(out.git, { isolation: "branch", main_branch: "develop", auto_push: false });
+  assert.deepEqual(out.verification_commands, ["npm test", "npm run lint"]);
+  assert.deepEqual(out.custom_instructions, ["Use TypeScript strict mode", "Always write tests"]);
+  assert.equal(out.token_profile, "quality");
+  assert.deepEqual(out.phases, { skip_research: true });
+});
+
+test("mapInitPrefsToWizardShape — omits defaults to keep YAML clean", () => {
+  const out = mapInitPrefsToWizardShape({
+    mode: "solo",
+    gitIsolation: "worktree",
+    mainBranch: "main",
+    verificationCommands: [],
+    customInstructions: [],
+    tokenProfile: "balanced",
+    skipResearch: false,
+    autoPush: true,
+  });
+
+  // tokenProfile=balanced is the default — should not be serialized.
+  assert.equal(out.token_profile, undefined);
+  // skipResearch=false is the default — phases should not appear.
+  assert.equal(out.phases, undefined);
+  // Empty arrays should not be serialized.
+  assert.equal(out.verification_commands, undefined);
+  assert.equal(out.custom_instructions, undefined);
+});
+
+test("writePreferencesFile — writes valid frontmatter from prefill", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+
+  try {
+    const prefs = mapInitPrefsToWizardShape({
+      mode: "solo",
+      gitIsolation: "worktree",
+      mainBranch: "main",
+      verificationCommands: ["npm test"],
+      customInstructions: [],
+      tokenProfile: "balanced",
+      skipResearch: false,
+      autoPush: true,
+    });
+
+    await writePreferencesFile(path, prefs, null, { scope: "project" });
+
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /^---/);
+    assert.match(content, /mode: solo/);
+    assert.match(content, /git:/);
+    assert.match(content, /isolation: worktree/);
+    assert.match(content, /main_branch: main/);
+    assert.match(content, /auto_push: true/);
+    assert.match(content, /verification_commands:/);
+    assert.match(content, /- npm test/);
+    // version: 1 is added by writePreferencesFile if missing
+    assert.match(content, /version: 1/);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("writePreferencesFile — preserves existing markdown body", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+  const customBody = "\n# My Custom Notes\n\nUser-edited content here.\n";
+
+  try {
+    // Seed file with frontmatter + custom body
+    writeFileSync(path, `---\nmode: solo\nversion: 1\n---${customBody}`, "utf-8");
+
+    await writePreferencesFile(path, { mode: "team", version: 1 }, null);
+
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /mode: team/);
+    assert.match(content, /My Custom Notes/);
+    assert.match(content, /User-edited content here/);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("writePreferencesFile — falls back to default body for new files", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+  const initBody = "\n# Init body marker\n";
+
+  try {
+    await writePreferencesFile(path, { mode: "solo" }, null, { defaultBody: initBody });
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /Init body marker/);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ─── Regression tests from #4457 codex adversarial review ──────────────────
+
+test("init — Step 9b shape: 'not_yet' option is recognized as defer (#4457 review)", async () => {
+  // The init wizard relies on showNextAction always appending a `not_yet` action
+  // and mapping Escape to it. The Step 9b code must explicitly handle `not_yet`
+  // as defer (return without bootstrapping or persisting prefs). This test
+  // documents the contract — it doesn't drive the full wizard, but it locks in
+  // that "not_yet" is the canonical defer signal so a future refactor can't
+  // silently drop the explicit branch.
+  const { showNextAction } = await import("../../shared/tui.ts") as { showNextAction: unknown };
+  assert.equal(typeof showNextAction, "function");
+
+  // Read the source to assert Step 9b explicitly handles not_yet — a static
+  // smoke test cheaper than spinning up the full wizard with a mocked ctx.
+  const src = readFileSync(
+    new URL("../init-wizard.ts", import.meta.url),
+    "utf-8",
+  );
+  assert.match(
+    src,
+    /reviewChoice === "not_yet"[\s\S]*?return \{ completed: false, bootstrapped: false \}/,
+    "init Step 9b must short-circuit on not_yet without writing preferences",
+  );
+});
+
+test("init — preferences path is basePath-derived, not cwd-derived (#4457 review)", async () => {
+  // If basePath !== process.cwd(), preferences must still write to
+  // join(gsdRoot(basePath), "PREFERENCES.md"), not the cwd-derived path.
+  // Static check: the post-#4457-review code constructs the path from gsdRoot(basePath).
+  const src = readFileSync(
+    new URL("../init-wizard.ts", import.meta.url),
+    "utf-8",
+  );
+  assert.match(
+    src,
+    /projectPrefsPath\s*=\s*join\(gsdRoot\(basePath\),\s*"PREFERENCES\.md"\)/,
+    "init must derive the project preferences path from basePath",
+  );
+  // And neither write site should call getProjectGSDPreferencesPath() (which
+  // resolves from process.cwd()).
+  assert.doesNotMatch(
+    src,
+    /getProjectGSDPreferencesPath\s*\(/,
+    "init must not use the cwd-derived getProjectGSDPreferencesPath()",
+  );
+});
+
+test("handlePrefsWizard — accepts pathOverride to target a non-cwd location", async () => {
+  // The wizard's signature must support pathOverride so /gsd init can route
+  // both the review and skip branches to the basePath-derived path.
+  const { handlePrefsWizard } = await import("../commands-prefs-wizard.ts");
+  assert.equal(handlePrefsWizard.length >= 2, true);
+  // Read source to confirm the opts.pathOverride wiring exists — calling
+  // handlePrefsWizard end-to-end requires a full ExtensionCommandContext
+  // mock, which is heavier than this contract check warrants.
+  const src = readFileSync(
+    new URL("../commands-prefs-wizard.ts", import.meta.url),
+    "utf-8",
+  );
+  assert.match(
+    src,
+    /opts\?\.pathOverride[\s\S]*?\?\?[\s\S]*?(getProjectGSDPreferencesPath|getGlobalGSDPreferencesPath)/,
+    "handlePrefsWizard must honor opts.pathOverride before falling back to scope-derived path",
+  );
+});

package/src/resources/extensions/gsd/tests/integration/doctor-git-symlink-cwd.test.ts

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import { execSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { runGSDDoctor } from "../../doctor.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createRepoWithCompletedMilestone(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "doc-git-symlink-cwd-")));
+  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");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+
+  const milestoneDir = join(dir, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(join(milestoneDir, "ROADMAP.md"), `---
+id: M001
+title: "Test Milestone"
+---
+
+# M001: Test Milestone
+
+## Vision
+Test
+
+## Success Criteria
+- Done
+
+## Slices
+- [x] **S01: Test slice** \`risk:low\` \`depends:[]\`
+  > After this: done
+
+## Boundary Map
+_None_
+`);
+
+  run("git add -A", dir);
+  run("git commit -m \"add milestone\"", dir);
+
+  return dir;
+}
+
+test("doctor removes orphaned milestone worktree when cwd uses a symlink alias", { skip: process.platform === "win32" }, async (t) => {
+  const previousCwd = process.cwd();
+  const dir = createRepoWithCompletedMilestone();
+  const alias = join(tmpdir(), `doc-git-alias-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+
+  t.after(() => {
+    try { process.chdir(previousCwd); } catch { process.chdir(tmpdir()); }
+    rmSync(alias, { recursive: true, force: true });
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(dir, ".gsd", "worktrees"), { recursive: true });
+  run("git worktree add -b milestone/M001 .gsd/worktrees/M001", dir);
+
+  symlinkSync(dir, alias);
+  process.chdir(join(alias, ".gsd", "worktrees", "M001"));
+
+  const fixed = await runGSDDoctor(dir, { fix: true, isolationMode: "worktree" });
+  assert.ok(
+    fixed.fixesApplied.some(f => f.includes("removed orphaned worktree")),
+    `removes orphaned worktree even when cwd uses a symlink alias (got: ${JSON.stringify(fixed.fixesApplied)})`,
+  );
+
+  const wtList = run("git worktree list", dir);
+  assert.ok(!wtList.includes("milestone/M001"), "worktree removed after symlink-cwd fix");
+});

package/src/resources/extensions/gsd/tests/integration/doctor-git.test.ts

@@ -696,6 +696,45 @@ describe('doctor-git', async () => {
       assert.deepStrictEqual(staleIssues.length, 0, "recent commit with dirty tree NOT flagged as stale");
     });
 
+    // ─── Test: stale_uncommitted_changes suppressed by git.snapshots:false (#4420) ──
+    test('stale_uncommitted_changes (suppressed by git.snapshots:false)', async () => {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      const pastDate = new Date(Date.now() - 45 * 60 * 1000).toISOString();
+      run(`git commit --amend --no-edit --date="${pastDate}"`, dir);
+      execSync(`git commit --amend --no-edit`, {
+        cwd: dir,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: { ...process.env, GIT_COMMITTER_DATE: pastDate },
+      });
+
+      writeFileSync(join(dir, "README.md"), "# test\nmodified content\n");
+      writeFileSync(join(dir, ".gsd", "PREFERENCES.md"), `---\ngit:\n  snapshots: false\n---\n`);
+
+      const commitsBefore = run("git rev-list --count HEAD", dir);
+
+      const previousCwd = process.cwd();
+      process.chdir(dir);
+      try {
+        const detect = await runGSDDoctor(dir);
+        const staleIssues = detect.issues.filter(i => i.code === "stale_uncommitted_changes");
+        assert.deepStrictEqual(staleIssues.length, 0, "git.snapshots:false suppresses stale detection");
+
+        const fixed = await runGSDDoctor(dir, { fix: true });
+        assert.ok(
+          !fixed.fixesApplied.some(f => f.includes("gsd snapshot")),
+          `git.snapshots:false suppresses snapshot fix (got: ${JSON.stringify(fixed.fixesApplied)})`,
+        );
+      } finally {
+        process.chdir(previousCwd);
+      }
+
+      const commitsAfter = run("git rev-list --count HEAD", dir);
+      assert.strictEqual(commitsAfter, commitsBefore, "no snapshot commit was created when git.snapshots:false");
+    });
+
     // ─── Test: stale_uncommitted_changes NOT flagged when tree is clean ──
     test('stale_uncommitted_changes (no false positive on clean tree)', async () => {
       const dir = createRepoWithActiveMilestone();