gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

package/src/resources/extensions/gsd/tests/originalbase-path-comparison.test.ts

@@ -0,0 +1,329 @@
+// GSD-2 — Regression tests for originalBase path comparison correctness (M5 fix)
+//
+// After commit ade55a7f5, getAutoWorktreeOriginalBase() returns ws.projectRoot
+// which is realpath-normalized. Callers that compare it with string === against
+// a non-canonical s.basePath (trailing slash, symlink path, etc.) can get false
+// mismatches. M5 replaced those comparisons with isSamePath-based helpers.
+//
+// Tests here verify:
+//   1. getAutoWorktreeOriginalBase() always returns a canonical (realpath) path.
+//   2. normalizeWorktreePathForCompare(canonical) === normalizeWorktreePathForCompare(non-canonical)
+//      — i.e. the new comparison is true when raw === would be false.
+//   3. WorktreeResolver._mergeWorktreeMode: when s.basePath has a trailing slash
+//      (non-canonical form of originalBase), the roadmap-fallback branch is NOT
+//      triggered (correct behaviour post-fix); with raw ===, it would have been.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import {
+  getAutoWorktreeOriginalBase,
+  _resetAutoWorktreeOriginalBaseForTests,
+  createAutoWorktree,
+  teardownAutoWorktree,
+} from "../auto-worktree.ts";
+import { normalizeWorktreePathForCompare } from "../worktree-root.ts";
+import {
+  WorktreeResolver,
+  type WorktreeResolverDeps,
+  type NotifyCtx,
+} from "../worktree-resolver.ts";
+import { AutoSession } from "../auto/session.ts";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function git(args: string[], cwd: string): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function createTempRepo(t: { after: (fn: () => void) => void }): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "m5-obpath-")));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  git(["init"], dir);
+  git(["config", "user.email", "test@test.com"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  git(["add", "."], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+  return dir;
+}
+
+function makeSession(overrides?: Partial<{ basePath: string; originalBasePath: string }>): AutoSession {
+  const s = new AutoSession();
+  s.basePath = overrides?.basePath ?? "/project";
+  s.originalBasePath = overrides?.originalBasePath ?? "/project";
+  return s;
+}
+
+interface CallLog { fn: string; args: unknown[] }
+
+function makeDeps(overrides?: Partial<WorktreeResolverDeps>): WorktreeResolverDeps & { calls: CallLog[] } {
+  const calls: CallLog[] = [];
+
+  const deps: WorktreeResolverDeps & { calls: CallLog[] } = {
+    calls,
+    isInAutoWorktree: (basePath: string) => {
+      calls.push({ fn: "isInAutoWorktree", args: [basePath] });
+      return basePath.includes("worktrees");
+    },
+    shouldUseWorktreeIsolation: () => true,
+    getIsolationMode: () => "worktree",
+    mergeMilestoneToMain: (basePath: string, milestoneId: string, roadmapContent: string) => {
+      calls.push({ fn: "mergeMilestoneToMain", args: [basePath, milestoneId, roadmapContent] });
+      return { pushed: false, codeFilesChanged: true };
+    },
+    syncWorktreeStateBack: (mainBasePath: string, worktreePath: string, milestoneId: string) => {
+      calls.push({ fn: "syncWorktreeStateBack", args: [mainBasePath, worktreePath, milestoneId] });
+      return { synced: [] };
+    },
+    teardownAutoWorktree: (basePath: string, milestoneId: string, opts?: { preserveBranch?: boolean }) => {
+      calls.push({ fn: "teardownAutoWorktree", args: [basePath, milestoneId, opts] });
+    },
+    createAutoWorktree: (basePath: string, milestoneId: string) => {
+      calls.push({ fn: "createAutoWorktree", args: [basePath, milestoneId] });
+      return `${basePath}/.gsd/worktrees/${milestoneId}`;
+    },
+    enterAutoWorktree: (basePath: string, milestoneId: string) => {
+      calls.push({ fn: "enterAutoWorktree", args: [basePath, milestoneId] });
+      return `${basePath}/.gsd/worktrees/${milestoneId}`;
+    },
+    getAutoWorktreePath: (basePath: string, milestoneId: string) => {
+      calls.push({ fn: "getAutoWorktreePath", args: [basePath, milestoneId] });
+      return null;
+    },
+    autoCommitCurrentBranch: (basePath: string, reason: string, milestoneId: string) => {
+      calls.push({ fn: "autoCommitCurrentBranch", args: [basePath, reason, milestoneId] });
+    },
+    getCurrentBranch: (basePath: string) => {
+      calls.push({ fn: "getCurrentBranch", args: [basePath] });
+      return "main";
+    },
+    autoWorktreeBranch: (milestoneId: string) => `milestone/${milestoneId}`,
+    resolveMilestoneFile: (basePath: string, milestoneId: string, fileType: string) => {
+      calls.push({ fn: "resolveMilestoneFile", args: [basePath, milestoneId, fileType] });
+      return null;
+    },
+    readFileSync: (path: string, _enc: string) => {
+      calls.push({ fn: "readFileSync", args: [path] });
+      return "# Roadmap\n";
+    },
+    GitServiceImpl: class {
+      constructor(_basePath: string, _gitConfig: unknown) {}
+    } as unknown as WorktreeResolverDeps["GitServiceImpl"],
+    loadEffectiveGSDPreferences: () => ({ preferences: { git: {} } }),
+    invalidateAllCaches: () => { calls.push({ fn: "invalidateAllCaches", args: [] }); },
+    captureIntegrationBranch: (_basePath: string, _mid: string) => {},
+    enterBranchModeForMilestone: (_basePath: string, _milestoneId: string) => {},
+    ...overrides,
+  };
+
+  if (overrides) {
+    for (const [key, val] of Object.entries(overrides)) {
+      if (key !== "calls") (deps as unknown as Record<string, unknown>)[key] = val;
+    }
+  }
+  return deps;
+}
+
+function makeNotifyCtx(): NotifyCtx & { messages: Array<{ msg: string; level?: string }> } {
+  const messages: Array<{ msg: string; level?: string }> = [];
+  return {
+    messages,
+    notify: (msg: string, level?: "info" | "warning" | "error" | "success") => {
+      messages.push({ msg, level });
+    },
+  };
+}
+
+// ─── Suite 1: getAutoWorktreeOriginalBase() returns realpath-canonical path ──
+
+describe("getAutoWorktreeOriginalBase() is realpath-normalised", () => {
+  const savedCwd = process.cwd();
+
+  beforeEach(() => {
+    _resetAutoWorktreeOriginalBaseForTests();
+  });
+
+  afterEach(() => {
+    _resetAutoWorktreeOriginalBaseForTests();
+    try { process.chdir(savedCwd); } catch { /* ignore */ }
+  });
+
+  test("returns canonical realpath even when called from a realpath-resolved dir", (t) => {
+    const tempDir = createTempRepo(t);
+    // tempDir is already realpathSync()-resolved by createTempRepo
+    const msDir = join(tempDir, ".gsd", "milestones", "M001");
+    mkdirSync(msDir, { recursive: true });
+    writeFileSync(join(msDir, "CONTEXT.md"), "# M001\n");
+    git(["add", "."], tempDir);
+    git(["commit", "-m", "add M001"], tempDir);
+
+    createAutoWorktree(tempDir, "M001");
+
+    const base = getAutoWorktreeOriginalBase();
+    assert.ok(base !== null, "originalBase is set after createAutoWorktree");
+
+    // The returned path must equal its own realpathSync — i.e. it is canonical
+    let realBase: string;
+    try { realBase = realpathSync(base); } catch { realBase = base; }
+    assert.strictEqual(base, realBase,
+      "getAutoWorktreeOriginalBase() must return a realpath-normalised path");
+
+    teardownAutoWorktree(tempDir, "M001");
+    try { process.chdir(savedCwd); } catch { /* ignore */ }
+  });
+});
+
+// ─── Suite 2: normalizeWorktreePathForCompare makes trailing-slash safe ───────
+
+describe("normalizeWorktreePathForCompare equalises canonical vs non-canonical forms", () => {
+  test("trailing slash: normalize(p/) === normalize(p)", () => {
+    // Use a path that definitely exists on this machine
+    const base = realpathSync(tmpdir());
+    const withSlash = base + "/";
+    assert.strictEqual(
+      normalizeWorktreePathForCompare(withSlash),
+      normalizeWorktreePathForCompare(base),
+      "trailing slash should be stripped by normalizeWorktreePathForCompare",
+    );
+    // Confirm raw === would have returned false (test validity check)
+    assert.notStrictEqual(
+      withSlash,
+      base,
+      "sanity: raw === IS false for trailing-slash path (test is meaningful)",
+    );
+  });
+
+  test("double trailing slashes: normalize(p//) === normalize(p)", () => {
+    const base = realpathSync(tmpdir());
+    const withDoubleSlash = base + "//";
+    assert.strictEqual(
+      normalizeWorktreePathForCompare(withDoubleSlash),
+      normalizeWorktreePathForCompare(base),
+    );
+  });
+
+  test("same realpath, different string forms: isSamePath-style comparison is true; raw === is false", () => {
+    const base = realpathSync(tmpdir());
+    const canonical = normalizeWorktreePathForCompare(base);
+    const nonCanonical = normalizeWorktreePathForCompare(base + "/");
+    // Post-fix: the two forms compare as equal
+    assert.strictEqual(canonical, nonCanonical,
+      "isSamePath-style comparison returns true for same physical path");
+  });
+});
+
+// ─── Suite 3: WorktreeResolver roadmap-fallback branch under cwd-drift ───────
+//
+// The buggy line was:
+//   if (!roadmapPath && this.s.basePath !== originalBase) { /* try worktree */ }
+//
+// After the fix:
+//   if (!roadmapPath && !isSamePath(this.s.basePath, originalBase)) { ... }
+//
+// When s.basePath is a non-canonical form of originalBase (e.g. trailing slash),
+// the old code falsely entered the fallback branch (attempted a second
+// resolveMilestoneFile call against the "worktree" path that is actually the
+// same directory). The new code correctly skips the fallback.
+
+describe("WorktreeResolver: roadmap-fallback skipped when basePath is same physical path as originalBase", () => {
+  test("with trailing-slash basePath equal to originalBase: resolveMilestoneFile called once", () => {
+    // originalBase is canonical (as returned by workspace registry)
+    const canonicalBase = "/tmp/m5-test-project";
+    // s.basePath has a trailing slash — same physical dir, non-canonical string
+    const trailingSlashBase = canonicalBase + "/";
+
+    const s = makeSession({
+      basePath: trailingSlashBase,
+      originalBasePath: canonicalBase,
+    });
+
+    const calls: CallLog[] = [];
+    const deps = makeDeps({
+      // isInAutoWorktree: basePath has trailing slash but is NOT a worktree
+      isInAutoWorktree: (basePath: string) => {
+        calls.push({ fn: "isInAutoWorktree", args: [basePath] });
+        return false;
+      },
+      // resolveMilestoneFile always returns null (no roadmap found)
+      resolveMilestoneFile: (basePath: string, milestoneId: string, fileType: string) => {
+        calls.push({ fn: "resolveMilestoneFile", args: [basePath, milestoneId, fileType] });
+        return null;
+      },
+      teardownAutoWorktree: (basePath: string, milestoneId: string, opts?: { preserveBranch?: boolean }) => {
+        calls.push({ fn: "teardownAutoWorktree", args: [basePath, milestoneId, opts] });
+      },
+    });
+
+    // Override calls ref so we can inspect it directly
+    (deps as unknown as { calls: CallLog[] }).calls = calls;
+
+    const resolver = new WorktreeResolver(s, deps);
+    const ctx = makeNotifyCtx();
+
+    // mergeAndExit → _mergeWorktreeMode
+    // originalBase = s.originalBasePath = canonicalBase
+    // s.basePath = trailingSlashBase — physically same as canonicalBase
+    // Post-fix: isSamePath(trailingSlashBase, canonicalBase) is true
+    //   → roadmap fallback branch is skipped (resolveMilestoneFile called once)
+    // Pre-fix (bug): trailingSlashBase !== canonicalBase → fallback entered
+    //   → resolveMilestoneFile called twice
+
+    resolver.mergeAndExit("M001", ctx);
+
+    const rmfCalls = calls.filter(c => c.fn === "resolveMilestoneFile");
+    assert.strictEqual(rmfCalls.length, 1,
+      "resolveMilestoneFile must be called exactly once — fallback should be skipped when " +
+      "s.basePath is the same physical path as originalBase (isSamePath fix)");
+  });
+
+  test("with genuinely different basePath (inside worktree): resolveMilestoneFile called twice", () => {
+    // originalBase is the project root
+    const projectRoot = "/tmp/m5-test-project";
+    // s.basePath is inside a worktree — a physically different path
+    const worktreePath = projectRoot + "/.gsd/worktrees/M002";
+
+    const s = makeSession({
+      basePath: worktreePath,
+      originalBasePath: projectRoot,
+    });
+
+    const calls: CallLog[] = [];
+    const deps = makeDeps({
+      isInAutoWorktree: (basePath: string) => {
+        calls.push({ fn: "isInAutoWorktree", args: [basePath] });
+        return basePath.includes("worktrees");
+      },
+      resolveMilestoneFile: (basePath: string, milestoneId: string, fileType: string) => {
+        calls.push({ fn: "resolveMilestoneFile", args: [basePath, milestoneId, fileType] });
+        return null; // no roadmap in either location
+      },
+      teardownAutoWorktree: (basePath: string, milestoneId: string, opts?: { preserveBranch?: boolean }) => {
+        calls.push({ fn: "teardownAutoWorktree", args: [basePath, milestoneId, opts] });
+      },
+    });
+    (deps as unknown as { calls: CallLog[] }).calls = calls;
+
+    const resolver = new WorktreeResolver(s, deps);
+    const ctx = makeNotifyCtx();
+
+    resolver.mergeAndExit("M002", ctx);
+
+    const rmfCalls = calls.filter(c => c.fn === "resolveMilestoneFile");
+    assert.strictEqual(rmfCalls.length, 2,
+      "resolveMilestoneFile must be called twice when basePath is a genuine worktree path " +
+      "(fallback should run for different physical paths)");
+  });
+});

package/src/resources/extensions/gsd/tests/parallel-milestone-isolation.test.ts

@@ -0,0 +1,106 @@
+// gsd-2 + Parallel-worker isolation regression (Phase B coordination)
+//
+// Two simulated workers attempt to claim leases on the same project. The
+// lease infrastructure must guarantee:
+//   - On the same milestone: only one wins; the loser sees held_by error
+//   - On different milestones: both succeed independently
+//
+// This is the integration check that ties registerAutoWorker +
+// claimMilestoneLease + recordDispatchClaim together end-to-end.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+import { registerAutoWorker } from "../db/auto-workers.ts";
+import { claimMilestoneLease } from "../db/milestone-leases.ts";
+import { recordDispatchClaim } from "../db/unit-dispatches.ts";
+
+function makeBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-parallel-iso-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+test("two workers contesting the same milestone: only one wins the lease", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Contested", status: "active" });
+
+  const w1 = registerAutoWorker({ projectRootRealpath: base });
+  const w2 = registerAutoWorker({ projectRootRealpath: base });
+
+  const r1 = claimMilestoneLease(w1, "M001");
+  const r2 = claimMilestoneLease(w2, "M001");
+
+  assert.equal(r1.ok, true, "first claim wins");
+  assert.equal(r2.ok, false, "second claim is rejected");
+  if (!r2.ok) {
+    assert.equal(r2.error, "held_by");
+    assert.equal(r2.byWorker, w1);
+  }
+});
+
+test("two workers on different milestones can both proceed independently", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "First", status: "active" });
+  insertMilestone({ id: "M002", title: "Second", status: "active" });
+
+  const w1 = registerAutoWorker({ projectRootRealpath: base });
+  const w2 = registerAutoWorker({ projectRootRealpath: base });
+
+  const r1 = claimMilestoneLease(w1, "M001");
+  const r2 = claimMilestoneLease(w2, "M002");
+
+  assert.equal(r1.ok, true);
+  assert.equal(r2.ok, true);
+  if (r1.ok && r2.ok) {
+    assert.equal(r1.token, 1);
+    assert.equal(r2.token, 1);
+  }
+});
+
+test("dispatch ledger ties unit_id uniqueness to active status", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "T", status: "active" });
+
+  const w1 = registerAutoWorker({ projectRootRealpath: base });
+  const lease = claimMilestoneLease(w1, "M001");
+  assert.equal(lease.ok, true);
+  if (!lease.ok) return;
+
+  // The same lease holder attempts to claim the same unit twice.
+  // The partial unique index on unit_dispatches.unit_id WHERE status IN
+  // ('claimed','running') must serialize the writes even before the unit transitions.
+  const claim1 = recordDispatchClaim({
+    traceId: "t1", workerId: w1, milestoneLeaseToken: lease.token,
+    milestoneId: "M001", unitType: "plan-slice", unitId: "M001/S01",
+  });
+  const claim2 = recordDispatchClaim({
+    traceId: "t2", workerId: w1, milestoneLeaseToken: lease.token,
+    milestoneId: "M001", unitType: "plan-slice", unitId: "M001/S01",
+  });
+
+  assert.equal(claim1.ok, true);
+  assert.equal(claim2.ok, false);
+  if (!claim2.ok) {
+    assert.equal(claim2.error, "already_active");
+  }
+});

package/src/resources/extensions/gsd/tests/path-cache-decoupled.test.ts

@@ -0,0 +1,209 @@
+// GSD-2 — Tests verifying gsdRootCache is decoupled from per-turn clearPathCache()
+
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, renameSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { gsdRoot, clearPathCache, _clearGsdRootCache } from '../paths.ts';
+
+// ---------------------------------------------------------------------------
+// Shared test setup helpers
+// ---------------------------------------------------------------------------
+
+interface Fixture {
+  projectDir: string;
+  fakeHome: string;
+  savedHome: string | undefined;
+  savedUserProfile: string | undefined;
+  savedGsdHome: string | undefined;
+}
+
+function makeFixture(): Fixture {
+  const projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-decoupled-')));
+  mkdirSync(join(projectDir, '.gsd'), { recursive: true });
+
+  const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-decoupled-home-')));
+
+  const savedHome = process.env.HOME;
+  const savedUserProfile = process.env.USERPROFILE;
+  const savedGsdHome = process.env.GSD_HOME;
+
+  // Redirect HOME so gsdRoot never accidentally resolves to the real ~/.gsd.
+  process.env.HOME = fakeHome;
+  process.env.USERPROFILE = fakeHome;
+  process.env.GSD_HOME = join(fakeHome, '.gsd');
+
+  _clearGsdRootCache();
+
+  return { projectDir, fakeHome, savedHome, savedUserProfile, savedGsdHome };
+}
+
+function teardownFixture(f: Fixture): void {
+  if (f.savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = f.savedHome;
+  if (f.savedUserProfile === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = f.savedUserProfile;
+  if (f.savedGsdHome === undefined) delete process.env.GSD_HOME;
+  else process.env.GSD_HOME = f.savedGsdHome;
+
+  _clearGsdRootCache();
+  clearPathCache();
+  rmSync(f.projectDir, { recursive: true, force: true });
+  rmSync(f.fakeHome, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// 1. gsdRoot() populates the cache
+// ---------------------------------------------------------------------------
+
+describe('gsdRoot cache population', () => {
+  let f: Fixture;
+  beforeEach(() => { f = makeFixture(); });
+  afterEach(() => teardownFixture(f));
+
+  test('first call populates cache; second call returns same value without re-probing', (t) => {
+    const first = gsdRoot(f.projectDir);
+    assert.equal(first, join(f.projectDir, '.gsd'), 'must resolve to projectDir/.gsd');
+
+    // Hide .gsd so a re-probe would yield the creation fallback (same path in this
+    // case, but the rename lets us verify no re-probe happens).
+    renameSync(join(f.projectDir, '.gsd'), join(f.projectDir, '.gsd-hidden'));
+    t.after(() => {
+      try { renameSync(join(f.projectDir, '.gsd-hidden'), join(f.projectDir, '.gsd')); } catch { /* ignore */ }
+    });
+
+    const second = gsdRoot(f.projectDir);
+    assert.equal(second, first, 'second call must return cached result, not re-probe');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. clearPathCache() does NOT invalidate gsdRootCache
+// ---------------------------------------------------------------------------
+
+describe('clearPathCache() does not evict gsdRootCache', () => {
+  let f: Fixture;
+  beforeEach(() => { f = makeFixture(); });
+  afterEach(() => teardownFixture(f));
+
+  test('cached gsdRoot survives clearPathCache()', (t) => {
+    // Prime the cache.
+    const primed = gsdRoot(f.projectDir);
+    assert.equal(primed, join(f.projectDir, '.gsd'));
+
+    // Mutate the filesystem so a fresh probe would return a different path.
+    renameSync(join(f.projectDir, '.gsd'), join(f.projectDir, '.gsd-gone'));
+    t.after(() => {
+      try { renameSync(join(f.projectDir, '.gsd-gone'), join(f.projectDir, '.gsd')); } catch { /* ignore */ }
+    });
+
+    // clearPathCache() only clears volatile dir caches — must not touch gsdRootCache.
+    clearPathCache();
+
+    const afterClear = gsdRoot(f.projectDir);
+    assert.equal(
+      afterClear,
+      primed,
+      'gsdRoot must return the original cached value after clearPathCache(), not re-probe',
+    );
+  });
+
+  test('multiple clearPathCache() calls still preserve gsdRoot cache', (t) => {
+    const primed = gsdRoot(f.projectDir);
+
+    renameSync(join(f.projectDir, '.gsd'), join(f.projectDir, '.gsd-gone'));
+    t.after(() => {
+      try { renameSync(join(f.projectDir, '.gsd-gone'), join(f.projectDir, '.gsd')); } catch { /* ignore */ }
+    });
+
+    // Simulate many agent turn-ends.
+    for (let i = 0; i < 10; i++) clearPathCache();
+
+    assert.equal(
+      gsdRoot(f.projectDir),
+      primed,
+      'gsdRoot cache must survive repeated clearPathCache() calls',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. _clearGsdRootCache() DOES invalidate gsdRootCache
+// ---------------------------------------------------------------------------
+
+describe('_clearGsdRootCache() evicts gsdRootCache', () => {
+  let f: Fixture;
+  beforeEach(() => { f = makeFixture(); });
+  afterEach(() => teardownFixture(f));
+
+  test('gsdRoot re-probes after _clearGsdRootCache()', (t) => {
+    // Prime the cache.
+    const primed = gsdRoot(f.projectDir);
+    assert.equal(primed, join(f.projectDir, '.gsd'));
+
+    // Hide .gsd — next probe would see it absent.
+    renameSync(join(f.projectDir, '.gsd'), join(f.projectDir, '.gsd-hidden'));
+    t.after(() => {
+      try { renameSync(join(f.projectDir, '.gsd-hidden'), join(f.projectDir, '.gsd')); } catch { /* ignore */ }
+    });
+
+    // _clearGsdRootCache() must evict, triggering a fresh probe.
+    _clearGsdRootCache();
+    const afterRootClear = gsdRoot(f.projectDir);
+
+    // Probe with .gsd absent falls through to creation fallback (same path value,
+    // but the probe definitely ran). Restore and re-prime to confirm it returns
+    // the live value rather than a stale cached one.
+    renameSync(join(f.projectDir, '.gsd-hidden'), join(f.projectDir, '.gsd'));
+    _clearGsdRootCache();
+    const reprobe = gsdRoot(f.projectDir);
+    assert.equal(reprobe, join(f.projectDir, '.gsd'), 're-probe with .gsd restored must find it');
+
+    // The result after root-clear + removal fell back to the creation path (same
+    // string as primed), which confirms the probe ran (not from cache).
+    assert.equal(afterRootClear, join(f.projectDir, '.gsd'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Realpath-normalized keys — /foo and /foo/ share the same cache entry
+//    (regression of A2 / H2 behavior)
+// ---------------------------------------------------------------------------
+
+describe('realpath normalization: trailing slash shares cache entry', () => {
+  let f: Fixture;
+  beforeEach(() => { f = makeFixture(); });
+  afterEach(() => teardownFixture(f));
+
+  test('/foo and /foo/ map to the same cache entry', () => {
+    const withoutSlash = gsdRoot(f.projectDir);
+
+    // Hide .gsd — if a re-probe happened, the result would differ.
+    renameSync(join(f.projectDir, '.gsd'), join(f.projectDir, '.gsd-hidden'));
+    try {
+      const withSlash = gsdRoot(f.projectDir + '/');
+      assert.equal(
+        withSlash,
+        withoutSlash,
+        'trailing-slash variant must hit the same cache entry as no-slash variant',
+      );
+    } finally {
+      try { renameSync(join(f.projectDir, '.gsd-hidden'), join(f.projectDir, '.gsd')); } catch { /* ignore */ }
+    }
+  });
+
+  test('_clearGsdRootCache() + gsdRoot with trailing slash re-probes correctly', () => {
+    const first = gsdRoot(f.projectDir);
+
+    _clearGsdRootCache();
+    const second = gsdRoot(f.projectDir + '/');
+
+    assert.equal(
+      first,
+      second,
+      '_clearGsdRootCache then call with trailing slash must return same resolved path',
+    );
+  });
+});