gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.d8826a445

package/src/resources/extensions/gsd/tests/gate-1b-recovery-bound.test.ts

@@ -0,0 +1,218 @@
+// GSD-2 + Gate 1b recovery counter bound — regression tests for H1 fix (#5012)
+//
+// Verifies that checkAutoStartAfterDiscuss stops emitting plan-blocked recovery
+// hints (with triggerTurn:true) after MAX_PLAN_BLOCKED_RECOVERIES attempts and
+// instead escalates to the user via ctx.ui.notify("error"), breaking the loop.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  checkAutoStartAfterDiscuss,
+  setPendingAutoStart,
+  clearPendingAutoStart,
+  _getPendingAutoStart,
+} from "../guided-flow.ts";
+import { drainLogs } from "../workflow-logger.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+
+// ─── Harness ───────────────────────────────────────────────────────────────
+
+interface MockCapture {
+  notifies: Array<{ msg: string; level: string }>;
+  messages: Array<{ payload: any; options: any }>;
+}
+
+function mkCapture(): MockCapture {
+  return { notifies: [], messages: [] };
+}
+
+function mkCtx(cap: MockCapture): any {
+  return {
+    ui: {
+      notify: (msg: string, level: string) => {
+        cap.notifies.push({ msg, level });
+      },
+    },
+  };
+}
+
+function mkPi(cap: MockCapture): any {
+  return {
+    sendMessage: (payload: any, options: any) => {
+      cap.messages.push({ payload, options });
+    },
+    setActiveTools: () => undefined,
+    getActiveTools: () => [],
+  };
+}
+
+function mkBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-gate1b-bound-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+    "# M001: Bound Test\n\nContext written by discuss phase.\n",
+  );
+  return base;
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe("Gate 1b recovery bound (H1)", () => {
+  let base: string;
+  let cap: MockCapture;
+
+  beforeEach(() => {
+    clearPendingAutoStart();
+    drainLogs();
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    clearPendingAutoStart();
+    if (base) {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test("first N-1 invocations increment counter and emit recovery with triggerTurn:true", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Bound Test", status: "queued" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    // MAX_PLAN_BLOCKED_RECOVERIES = 3; first two calls should emit recovery
+    const resultOne = checkAutoStartAfterDiscuss();
+    assert.equal(resultOne, false, "call 1: must return false");
+    assert.equal(cap.messages.length, 1, "call 1: exactly one sendMessage");
+    assert.equal(cap.messages[0].options.triggerTurn, true, "call 1: triggerTurn must be true");
+    assert.equal(cap.messages[0].payload.customType, "gsd-plan-milestone-blocked-recovery");
+
+    const entryAfterOne = _getPendingAutoStart(base);
+    assert.ok(entryAfterOne, "entry must still exist after call 1");
+    assert.equal(entryAfterOne.planBlockedRecoveryCount, 1, "counter must be 1 after call 1");
+
+    const resultTwo = checkAutoStartAfterDiscuss();
+    assert.equal(resultTwo, false, "call 2: must return false");
+    assert.equal(cap.messages.length, 2, "call 2: second sendMessage emitted");
+    assert.equal(cap.messages[1].options.triggerTurn, true, "call 2: triggerTurn must be true");
+
+    const entryAfterTwo = _getPendingAutoStart(base);
+    assert.ok(entryAfterTwo, "entry must still exist after call 2");
+    assert.equal(entryAfterTwo.planBlockedRecoveryCount, 2, "counter must be 2 after call 2");
+  });
+
+  test("Nth invocation (at MAX_PLAN_BLOCKED_RECOVERIES) escalates via notify(error) without sendMessage(triggerTurn)", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Bound Test", status: "queued" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    // Exhaust the recovery budget (MAX = 3): call 3 times to reach the limit
+    checkAutoStartAfterDiscuss(); // count → 1
+    checkAutoStartAfterDiscuss(); // count → 2
+    checkAutoStartAfterDiscuss(); // count → 3
+
+    // At count = 3 the counter equals MAX so the next call must escalate
+    cap.messages = [];
+    cap.notifies = [];
+    drainLogs();
+
+    const resultAtLimit = checkAutoStartAfterDiscuss();
+    assert.equal(resultAtLimit, false, "at-limit call: must return false");
+
+    // Must NOT trigger a new LLM turn
+    assert.equal(
+      cap.messages.length,
+      0,
+      "at-limit call: sendMessage must NOT be called (loop must stop)",
+    );
+    const triggerMessages = cap.messages.filter((m) => m.options?.triggerTurn);
+    assert.equal(triggerMessages.length, 0, "no triggerTurn message after limit");
+
+    // Must escalate to user via notify("error")
+    const errorNotify = cap.notifies.find((n) => n.level === "error");
+    assert.ok(errorNotify, "at-limit call: ctx.ui.notify('error') must be called");
+    assert.match(
+      errorNotify.msg,
+      /gsd-debug/i,
+      "error notification must direct user to run /gsd-debug",
+    );
+    assert.match(
+      errorNotify.msg,
+      /M001/,
+      "error notification must include the milestone ID",
+    );
+
+    // Confirm the log records the escalation
+    const logs = drainLogs();
+    const escalationLog = logs.find(
+      (e) => e.component === "guided" && /Gate 1b/.test(e.message) && /escalat/.test(e.message),
+    );
+    assert.ok(escalationLog, "escalation must be logged via logWarning");
+  });
+
+  test("after clearPendingAutoStart + setPendingAutoStart the counter is reset to 0", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Bound Test", status: "queued" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    // Advance counter to 2
+    checkAutoStartAfterDiscuss();
+    checkAutoStartAfterDiscuss();
+
+    const entryBefore = _getPendingAutoStart(base);
+    assert.ok(entryBefore, "entry must exist");
+    assert.equal(entryBefore.planBlockedRecoveryCount, 2, "counter must be 2 before reset");
+
+    // Simulate user retry: clear then re-set
+    clearPendingAutoStart(base);
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    const entryAfter = _getPendingAutoStart(base);
+    assert.ok(entryAfter, "entry must exist after re-set");
+    assert.equal(entryAfter.planBlockedRecoveryCount, 0, "counter must be 0 after re-set (fresh entry)");
+
+    // Verify first call after reset emits recovery, not escalation
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, false, "first call after reset must return false");
+    assert.equal(cap.messages.length, 1, "recovery hint must be emitted after reset");
+    assert.equal(cap.messages[0].options.triggerTurn, true, "triggerTurn must be true after reset");
+  });
+});

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

@@ -0,0 +1,117 @@
+// GSD-2 + gsd-db failed-open restore: previous workspace connection survives a failed openDatabaseByWorkspace
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  openDatabase,
+  openDatabaseByWorkspace,
+  closeDatabase,
+  isDbAvailable,
+  getDbPath,
+  _getDbCache,
+} from "../gsd-db.ts";
+import { createWorkspace } from "../workspace.ts";
+import type { GsdWorkspace } from "../workspace.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(base: string): string {
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("openDatabaseByWorkspace: restores previous connection on failure", () => {
+  let tmpA: string;
+  let tmpB: string;
+
+  beforeEach(() => {
+    tmpA = mkdtempSync(join(tmpdir(), "gsd-db-restore-a-"));
+    tmpB = mkdtempSync(join(tmpdir(), "gsd-db-restore-b-"));
+    makeProjectDir(tmpA);
+    makeProjectDir(tmpB);
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmpA, { recursive: true, force: true });
+    rmSync(tmpB, { recursive: true, force: true });
+  });
+
+  test("previous workspace connection stays active after failed switch to non-existent path", () => {
+    // Open workspace A successfully
+    const wsA = createWorkspace(tmpA);
+    const openedA = openDatabaseByWorkspace(wsA);
+    assert.ok(openedA, "opening workspace A should succeed");
+    assert.ok(isDbAvailable(), "DB should be available after opening A");
+
+    const pathAfterA = getDbPath();
+    assert.ok(pathAfterA, "should have a DB path after opening A");
+
+    // Attempt to open a workspace pointing to a completely non-existent directory
+    // ("/does-not-exist-gsd-test" cannot be created), which will cause openDatabase to throw.
+    const fakeWs = {
+      identityKey: "fake-key-that-does-not-exist",
+      projectRoot: "/does-not-exist-gsd-test-ws-restore",
+      worktreeRoot: null,
+      mode: "project" as const,
+      contract: {
+        projectRoot: "/does-not-exist-gsd-test-ws-restore",
+        workRoot: "/does-not-exist-gsd-test-ws-restore",
+        projectGsd: "/does-not-exist-gsd-test-ws-restore/.gsd",
+        projectDb: "/does-not-exist-gsd-test-ws-restore/.gsd/does-not-exist.db",
+        worktreeGsd: null,
+        isWorktree: false,
+      },
+      lockRoot: "/does-not-exist-gsd-test-ws-restore",
+    } satisfies GsdWorkspace;
+
+    // This should throw because the path is invalid
+    assert.throws(
+      () => openDatabaseByWorkspace(fakeWs),
+      (err: Error) => err instanceof Error,
+    );
+
+    // After the failure, the previous workspace A connection must be restored
+    assert.ok(isDbAvailable(), "DB must still be available (workspace A connection restored)");
+    const pathAfterFailure = getDbPath();
+    assert.equal(pathAfterFailure, pathAfterA, "DB path must match workspace A's path after failed switch");
+  });
+
+  test("cache still contains workspace A entry after failed switch", () => {
+    const wsA = createWorkspace(tmpA);
+    openDatabaseByWorkspace(wsA);
+
+    const fakeWs = {
+      identityKey: "fake-key-cache-test",
+      projectRoot: "/does-not-exist-gsd-cache-test",
+      worktreeRoot: null,
+      mode: "project" as const,
+      contract: {
+        projectRoot: "/does-not-exist-gsd-cache-test",
+        workRoot: "/does-not-exist-gsd-cache-test",
+        projectGsd: "/does-not-exist-gsd-cache-test/.gsd",
+        projectDb: "/does-not-exist-gsd-cache-test/.gsd/no.db",
+        worktreeGsd: null,
+        isWorktree: false,
+      },
+      lockRoot: "/does-not-exist-gsd-cache-test",
+    } satisfies GsdWorkspace;
+
+    assert.throws(() => openDatabaseByWorkspace(fakeWs));
+
+    const cache = _getDbCache();
+    assert.ok(cache.has(wsA.identityKey), "cache must retain workspace A's entry after failed switch");
+
+    // Workspace A's connection is back as the active connection; switching back
+    // should succeed from cache (cache hit path) without re-opening.
+    const reopened = openDatabaseByWorkspace(wsA);
+    assert.ok(reopened, "switching back to workspace A should succeed from cache");
+    assert.ok(isDbAvailable(), "DB should be available after re-activating A");
+  });
+});

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

@@ -0,0 +1,226 @@
+// GSD-2 + gsd-db workspace-scoped connection cache tests
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+import {
+  openDatabaseByWorkspace,
+  openDatabaseByScope,
+  closeDatabaseByWorkspace,
+  closeAllDatabases,
+  _getDbCache,
+  _getAdapter,
+} from "../gsd-db.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create a minimal project directory with the artifacts that make
+ * createWorkspace() resolve it as a proper project root (not a bare temp dir).
+ * Returns the realpath-normalised absolute path.
+ */
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-db-ws-scope-")));
+  // hasGsdBootstrapArtifacts checks for .gsd/milestones or .gsd/PREFERENCES.md
+  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+  return dir;
+}
+
+/**
+ * Create a worktree path inside a project's .gsd/worktrees/<MID>/ layout.
+ * createWorkspace() will detect the /.gsd/worktrees/ segment and resolve the
+ * project root back to `projectDir`.
+ */
+function makeWorktreeDir(projectDir: string, mid: string): string {
+  const worktreeDir = join(projectDir, ".gsd", "worktrees", mid);
+  mkdirSync(worktreeDir, { recursive: true });
+  return worktreeDir;
+}
+
+// ─── Suite: same realpath → same identityKey → same DB instance ──────────────
+
+describe("openDatabaseByWorkspace: same project reuses connection", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeAllDatabases();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("two createWorkspace calls with the same path share identityKey", () => {
+    const ws1 = createWorkspace(projectDir);
+    const ws2 = createWorkspace(projectDir);
+    assert.equal(ws1.identityKey, ws2.identityKey);
+  });
+
+  test("openDatabaseByWorkspace returns the same DB adapter for the same project", () => {
+    const ws1 = createWorkspace(projectDir);
+    const ws2 = createWorkspace(projectDir);
+
+    const ok1 = openDatabaseByWorkspace(ws1);
+    assert.ok(ok1, "first open should succeed");
+    const adapter1 = _getAdapter();
+
+    const ok2 = openDatabaseByWorkspace(ws2);
+    assert.ok(ok2, "second open should succeed");
+    const adapter2 = _getAdapter();
+
+    assert.equal(adapter1, adapter2, "same project → same DB adapter instance");
+    assert.equal(_getDbCache().size, 1, "only one cache entry for same project");
+  });
+});
+
+// ─── Suite: different projects → different DB instances ──────────────────────
+
+describe("openDatabaseByWorkspace: different projects get separate connections", () => {
+  let projectA: string;
+  let projectB: string;
+
+  beforeEach(() => {
+    projectA = makeProjectDir();
+    projectB = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeAllDatabases();
+    rmSync(projectA, { recursive: true, force: true });
+    rmSync(projectB, { recursive: true, force: true });
+  });
+
+  test("two different projects produce different identityKeys", () => {
+    const wsA = createWorkspace(projectA);
+    const wsB = createWorkspace(projectB);
+    assert.notEqual(wsA.identityKey, wsB.identityKey);
+  });
+
+  test("opening two different projects stores two cache entries", () => {
+    const wsA = createWorkspace(projectA);
+    const wsB = createWorkspace(projectB);
+
+    openDatabaseByWorkspace(wsA);
+    const adapterAfterA = _getAdapter();
+
+    openDatabaseByWorkspace(wsB);
+    const adapterAfterB = _getAdapter();
+
+    assert.notEqual(adapterAfterA, adapterAfterB, "different projects → different adapter instances");
+    assert.equal(_getDbCache().size, 2, "two cache entries for two distinct projects");
+  });
+});
+
+// ─── Suite: sibling worktrees share the same DB instance ─────────────────────
+
+describe("openDatabaseByWorkspace: sibling worktrees share DB connection", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeAllDatabases();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("worktree path resolves to same identityKey as project root", () => {
+    const worktreeDir = makeWorktreeDir(projectDir, "M001");
+    const wsProject = createWorkspace(projectDir);
+    const wsWorktree = createWorkspace(worktreeDir);
+    assert.equal(
+      wsProject.identityKey,
+      wsWorktree.identityKey,
+      "project root and sibling worktree share identityKey",
+    );
+  });
+
+  test("opening via project path and via worktree path yields the same DB adapter", () => {
+    const worktreeDir = makeWorktreeDir(projectDir, "M001");
+    const wsProject = createWorkspace(projectDir);
+    const wsWorktree = createWorkspace(worktreeDir);
+
+    openDatabaseByWorkspace(wsProject);
+    const adapterProject = _getAdapter();
+
+    openDatabaseByWorkspace(wsWorktree);
+    const adapterWorktree = _getAdapter();
+
+    assert.equal(
+      adapterProject,
+      adapterWorktree,
+      "sibling worktree reuses the same DB adapter as the project root",
+    );
+    assert.equal(_getDbCache().size, 1, "only one cache entry for project + sibling worktree");
+  });
+});
+
+// ─── Suite: closing removes only the targeted cache entry ─────────────────────
+
+describe("closeDatabaseByWorkspace: removes only the targeted cache entry", () => {
+  let projectA: string;
+  let projectB: string;
+
+  beforeEach(() => {
+    projectA = makeProjectDir();
+    projectB = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeAllDatabases();
+    rmSync(projectA, { recursive: true, force: true });
+    rmSync(projectB, { recursive: true, force: true });
+  });
+
+  test("closing workspace A removes only A from the cache", () => {
+    const wsA = createWorkspace(projectA);
+    const wsB = createWorkspace(projectB);
+
+    openDatabaseByWorkspace(wsA);
+    openDatabaseByWorkspace(wsB);
+    assert.equal(_getDbCache().size, 2, "precondition: two cache entries");
+
+    closeDatabaseByWorkspace(wsA);
+
+    assert.equal(_getDbCache().size, 1, "one entry remains after closing A");
+    assert.ok(!_getDbCache().has(wsA.identityKey), "A's entry is gone");
+    assert.ok(_getDbCache().has(wsB.identityKey), "B's entry is still present");
+  });
+
+  test("closing the active workspace via closeDatabaseByWorkspace nulls currentDb", () => {
+    const wsA = createWorkspace(projectA);
+
+    openDatabaseByWorkspace(wsA);
+    assert.ok(_getAdapter() !== null, "precondition: adapter is open");
+
+    // Make wsA the active connection explicitly.
+    openDatabaseByWorkspace(wsA);
+    closeDatabaseByWorkspace(wsA);
+
+    // After closing the active connection, the global adapter should be null.
+    assert.equal(_getAdapter(), null, "currentDb should be null after closing active workspace");
+    assert.equal(_getDbCache().size, 0, "cache should be empty after closing sole entry");
+  });
+
+  test("openDatabaseByScope delegates to workspace correctly", () => {
+    const ws = createWorkspace(projectA);
+    const scope = scopeMilestone(ws, "M001");
+
+    const ok = openDatabaseByScope(scope);
+    assert.ok(ok, "openDatabaseByScope should succeed");
+    assert.ok(_getDbCache().has(ws.identityKey), "cache entry exists after openDatabaseByScope");
+
+    closeDatabaseByWorkspace(ws);
+  });
+});

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

@@ -11,6 +11,7 @@ import {
   wasDbOpenAttempted,
   getDbProvider,
   getDbStatus,
+  SCHEMA_VERSION,
   insertDecision,
   getDecisionById,
   insertRequirement,
@@ -101,7 +102,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'], 22, 'schema version should be 22');
+    assert.deepStrictEqual(version?.['version'], SCHEMA_VERSION, `schema version should be ${SCHEMA_VERSION}`);
 
     // Check tables exist by querying them
     const dRows = adapter.prepare('SELECT count(*) as cnt FROM decisions').get();

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

@@ -0,0 +1,66 @@
+// GSD-2 + gsd-root-canonical: gsdRoot() result is realpath-canonicalized before caching
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { gsdRoot, _clearGsdRootCache } from "../paths.ts";
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("gsdRoot: returns realpath-canonicalized result", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-root-canon-")));
+    mkdirSync(join(projectDir, ".gsd"), { recursive: true });
+    _clearGsdRootCache();
+  });
+
+  afterEach(() => {
+    _clearGsdRootCache();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("gsdRoot from a canonical project path returns a realpath-canonicalized result", () => {
+    const result = gsdRoot(projectDir);
+    const canonical = realpathSync(join(projectDir, ".gsd"));
+    assert.equal(result, canonical, "gsdRoot must return the realpath of the .gsd directory");
+  });
+
+  test("gsdRoot via a symlinked project path returns the realpath-canonicalized .gsd", (t) => {
+    // Create a symlink pointing to projectDir
+    const linkPath = join(tmpdir(), `gsd-root-link-${randomUUID()}`);
+    symlinkSync(projectDir, linkPath);
+    t.after(() => {
+      try { rmSync(linkPath); } catch { /* ignore */ }
+    });
+
+    _clearGsdRootCache();
+
+    const result = gsdRoot(linkPath);
+    // The canonical .gsd is under the realpath of projectDir, not the symlink
+    const canonicalGsd = realpathSync(join(projectDir, ".gsd"));
+
+    assert.equal(
+      result,
+      canonicalGsd,
+      `gsdRoot via symlink ("${linkPath}") must return the realpath'd .gsd ("${canonicalGsd}"), not a symlink-based path`,
+    );
+
+    // Also verify that the result does NOT contain the symlink in its path
+    assert.ok(
+      !result.startsWith(linkPath),
+      `gsdRoot result must not start with the symlink path "${linkPath}"`,
+    );
+  });
+});