gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

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

@@ -0,0 +1,81 @@
+/**
+ * Runtime regression — `projectRoot()` throws `GSDNoProjectError` when
+ * invoked outside a project directory (#4902).
+ *
+ * The deleted `gsd-no-project-error.test.ts` was a source-grep check.
+ * This rewrite chdirs to $HOME, calls the real `projectRoot()`, and
+ * asserts a `GSDNoProjectError` is thrown with the project-required
+ * message.
+ */
+
+import { describe, test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { projectRoot, GSDNoProjectError } from '../commands/context.ts';
+
+const ORIGINAL_CWD = process.cwd();
+
+after(() => {
+  try { process.chdir(ORIGINAL_CWD); } catch { /* swallow */ }
+});
+
+describe('projectRoot() throws GSDNoProjectError outside a project (#4902)', () => {
+  test('throws GSDNoProjectError when cwd is $HOME', () => {
+    const home = os.homedir();
+    process.chdir(home);
+    try {
+      assert.throws(
+        () => projectRoot(),
+        (err: unknown) => {
+          assert.ok(err instanceof GSDNoProjectError, 'should throw GSDNoProjectError');
+          assert.match(
+            (err as Error).message,
+            /home directory|project directory/i,
+            'error message should mention home/project directory',
+          );
+          return true;
+        },
+      );
+    } finally {
+      process.chdir(ORIGINAL_CWD);
+    }
+  });
+
+  test('throws GSDNoProjectError when cwd is the system tmpdir root', () => {
+    // Use realpath to dodge symlinks blocking the cwd
+    const tmpRoot = fs.realpathSync(os.tmpdir());
+    // Some systems make tmpdir a subdirectory; only run when it normalizes
+    // to a known-blocked root. validateDirectory blocks /tmp + /var/folders
+    // tmp roots; build a small subdir under tmp and then assert that the
+    // raw tmpdir root itself blocks. We just use it directly.
+    process.chdir(tmpRoot);
+    try {
+      // Behaviour: either we get a GSDNoProjectError (blocked tmpdir root) or
+      // we don't — but in the case where we don't (tmpdir is somehow allowed
+      // as a project root on this machine), the test is vacuously satisfied
+      // by the prior $HOME case. We assert the type-narrowing path instead:
+      let threw: unknown = null;
+      try { projectRoot(); } catch (err) { threw = err; }
+      if (threw !== null) {
+        assert.ok(
+          threw instanceof GSDNoProjectError,
+          'if projectRoot throws, it must be a GSDNoProjectError (typed)',
+        );
+      }
+    } finally {
+      process.chdir(ORIGINAL_CWD);
+    }
+  });
+});
+
+describe('GSDNoProjectError shape (#4902)', () => {
+  test('GSDNoProjectError extends Error and carries its name', () => {
+    const err = new GSDNoProjectError('test reason');
+    assert.ok(err instanceof Error);
+    assert.equal(err.name, 'GSDNoProjectError');
+    assert.equal(err.message, 'test reason');
+  });
+});

package/src/resources/extensions/gsd/tests/has-pending-deep-stage.test.ts

@@ -0,0 +1,98 @@
+// gsd-2 / Deep planning mode — Regression coverage for hasPendingDeepStage()
+// being exported and consumed by the showSmartEntry deep-mode kickoff branch.
+//
+// Context: PR #5094 wires a deep-mode branch into showSmartEntry that calls
+// hasPendingDeepStage() to decide whether to hand off to startAutoDetached().
+// Without this guard, /gsd new-project --deep set the planning_depth flag but
+// never actually triggered the staged interview because showSmartEntry fell
+// straight through to the standard milestone wizard. These tests pin the
+// exported contract so the kickoff branch can rely on it.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { hasPendingDeepStage } from "../auto-dispatch.ts";
+import type { GSDPreferences } from "../preferences.ts";
+import { loadEffectiveGSDPreferences } from "../preferences.ts";
+
+function makeBase(): string {
+  const base = join(tmpdir(), `gsd-deep-pending-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+const lightPrefs: GSDPreferences = { planning_depth: "light" } as GSDPreferences;
+const deepPrefs: GSDPreferences = { planning_depth: "deep" } as GSDPreferences;
+
+test("hasPendingDeepStage: returns false when prefs is undefined (light by omission)", () => {
+  const base = makeBase();
+  try {
+    assert.equal(hasPendingDeepStage(undefined, base), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("hasPendingDeepStage: returns false in light mode regardless of artifacts", () => {
+  const base = makeBase();
+  try {
+    assert.equal(hasPendingDeepStage(lightPrefs, base), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("hasPendingDeepStage: returns true in deep mode when nothing has been captured", () => {
+  // Fresh project — no PREFERENCES.md frontmatter, no PROJECT.md, no
+  // REQUIREMENTS.md, no research-decision marker. Every gate is pending.
+  const base = makeBase();
+  try {
+    assert.equal(hasPendingDeepStage(deepPrefs, base), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("hasPendingDeepStage: returns true in deep mode when only some gates pass", () => {
+  // workflow-preferences captured but PROJECT.md still missing.
+  const base = makeBase();
+  try {
+    writeFileSync(
+      join(base, ".gsd", "PREFERENCES.md"),
+      "---\nplanning_depth: deep\nworkflow_prefs_captured: true\n---\n",
+    );
+    assert.equal(hasPendingDeepStage(deepPrefs, base), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// Regression test for the bug found while debugging /gsd new-project --deep:
+// `planning_depth` was missing from KNOWN_PREFERENCE_KEYS, validatePreferences,
+// and mergePreferences, so it was stripped on every load. The deep-mode flow
+// silently never triggered because every dispatch saw planning_depth: undefined.
+test("loadEffectiveGSDPreferences: planning_depth survives the validate + merge pipeline", () => {
+  const base = makeBase();
+  try {
+    writeFileSync(
+      join(base, ".gsd", "PREFERENCES.md"),
+      "---\nplanning_depth: deep\n---\n",
+    );
+    const loaded = loadEffectiveGSDPreferences(base);
+    assert.equal(
+      loaded?.preferences?.planning_depth,
+      "deep",
+      "planning_depth must survive load — see KNOWN_PREFERENCE_KEYS, validatePreferences, mergePreferences",
+    );
+    // Cross-check: the dispatch helper reads loaded.preferences, so it must
+    // see the same value. If planning_depth gets stripped anywhere in the
+    // pipeline, hasPendingDeepStage returns false and the deep flow dies.
+    assert.equal(hasPendingDeepStage(loaded?.preferences, base), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/headless-answers.test.ts

@@ -6,7 +6,7 @@
  * secrets, stats, and unused warnings).
  */
 
-import test from 'node:test';
+import test, { mock } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
@@ -164,7 +164,15 @@ test('tryHandle matches by question ID — single select', (t) => {
   assert.strictEqual(injector.getStats().questionsAnswered, 1);
 });
 
-test('tryHandle unknown question deferred — first_option timeout', async (t) => {
+test('tryHandle unknown question deferred — first_option timeout', (t) => {
+  // Use Node's MockTimers instead of a real-time setTimeout race. The
+  // production class schedules an internal setTimeout to default the
+  // answer when no metadata arrives — driving virtual time advances that
+  // timer deterministically, regardless of the literal ms value the
+  // production code chose.
+  mock.timers.enable({ apis: ['setTimeout'] });
+  t.after(() => { mock.timers.reset(); });
+
   const injector = new AnswerInjector({ defaults: { strategy: 'first_option' } });
 
   const captured: string[] = [];
@@ -177,8 +185,10 @@ test('tryHandle unknown question deferred — first_option timeout', async (t) =
   assert.strictEqual(handled, true);
   assert.strictEqual(captured.length, 0, 'nothing sent immediately');
 
-  // Wait for the 500ms deferred timeout to fire
-  await new Promise((resolve) => setTimeout(resolve, 600));
+  // Advance virtual time past any internal defer timeout (well above any
+  // reasonable defer cap). MockTimers fires synchronously, so by the time
+  // tick() returns the deferred handler has run.
+  mock.timers.tick(60_000);
 
   assert.strictEqual(captured.length, 1);
   const response = JSON.parse(captured[0].trim());

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

@@ -66,16 +66,22 @@ test("detectHealthWidgetProjectState: milestone without metrics returns active",
   assert.equal(detectHealthWidgetProjectState(dir), "active");
 });
 
-test("buildHealthLines: none state shows onboarding copy", (t) => {
-  assert.deepEqual(buildHealthLines(activeData({ projectState: "none" })), [
-    "  GSD  No project loaded — run /gsd to start",
-  ]);
+test("buildHealthLines: none state shows single onboarding line pointing at /gsd", (t) => {
+  const lines = buildHealthLines(activeData({ projectState: "none" }));
+  assert.equal(lines.length, 1, "renders exactly one line");
+  // Should not show System OK / Budget / Last commit chrome when there's no project.
+  assert.ok(!/System OK|Budget|Last commit/.test(lines[0]!), "no active-project chrome");
+  // Should direct user to bootstrap via /gsd.
+  assert.match(lines[0]!, /\/gsd/);
 });
 
-test("buildHealthLines: initialized state shows continue setup copy", (t) => {
-  assert.deepEqual(buildHealthLines(activeData({ projectState: "initialized" })), [
-    "  GSD  Project initialized — run /gsd to continue setup",
-  ]);
+test("buildHealthLines: initialized state shows single setup line pointing at /gsd", (t) => {
+  const lines = buildHealthLines(activeData({ projectState: "initialized" }));
+  assert.equal(lines.length, 1, "renders exactly one line");
+  assert.ok(!/System OK|Budget|Last commit/.test(lines[0]!), "no active-project chrome");
+  // Distinct from "none" — must mention initialized/setup language and /gsd.
+  assert.match(lines[0]!, /\/gsd/);
+  assert.match(lines[0]!, /initiali[sz]ed|setup/i);
 });
 
 test("buildHealthLines: active state with ledger-driven spend shows spent summary", (t) => {
@@ -115,16 +121,20 @@ test("buildHealthLines: shows last commit with relative time and message", (t) =
   assert.match(lines[0]!, /feat\(widget\): add health display/);
 });
 
-test("buildHealthLines: truncates long commit messages", (t) => {
+test("buildHealthLines: truncates long commit messages with ellipsis", (t) => {
   const epoch = Math.floor(Date.now() / 1000) - 60;
-  const longMsg = "a".repeat(80);
+  const longMsg = "a".repeat(200); // far longer than any reasonable widget cap
   const lines = buildHealthLines(activeData({
     lastCommitEpoch: epoch,
     lastCommitMessage: longMsg,
   }));
   assert.equal(lines.length, 1);
-  assert.match(lines[0]!, /a{49}…/);
-  assert.ok(!lines[0]!.includes("a".repeat(51)), "message is truncated");
+  // Behavioural contract: rendered output is shorter than the input message
+  // and ends the message portion with the ellipsis character.
+  const aRun = lines[0]!.match(/a+…/);
+  assert.ok(aRun, "rendered output contains a run of a-chars terminated by an ellipsis");
+  assert.ok(aRun![0].length - 1 < longMsg.length, "truncated message is shorter than input");
+  assert.ok(!lines[0]!.includes("a".repeat(longMsg.length)), "untruncated message must not appear in output");
 });
 
 test("buildHealthLines: no last commit section when epoch is null", (t) => {

package/src/resources/extensions/gsd/tests/help-menu-coverage.test.ts

@@ -0,0 +1,57 @@
+// GSD-2 — Verify /gsd help menu covers all registered commands
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { TOP_LEVEL_SUBCOMMANDS } from "../commands/catalog.ts";
+
+/**
+ * Extracts command names from the showHelp("full") lines array.
+ * Each help line follows the pattern: "  /gsd <cmd>  ..."
+ */
+function extractHelpCommands(lines: string[]): Set<string> {
+  const cmds = new Set<string>();
+  for (const line of lines) {
+    const m = line.match(/^\s+\/gsd\s+(\S+)/);
+    if (m) cmds.add(m[1]);
+  }
+  return cmds;
+}
+
+describe("help menu coverage", () => {
+  test("every TOP_LEVEL_SUBCOMMAND appears in showHelp(\"full\") output", async () => {
+    // Import showHelp and capture its output via a mock ctx
+    const lines: string[] = [];
+    const mockCtx = {
+      ui: {
+        notify(message: string) {
+          lines.push(...message.split("\n"));
+        },
+        custom: async () => {},
+      },
+    };
+
+    const { showHelp } = await import("../commands/handlers/core.ts");
+    showHelp(mockCtx as any, "full");
+
+    const helpCmds = extractHelpCommands(lines);
+
+    // "help" is the command that shows the menu — it doesn't list itself
+    const SELF_REFERENTIAL = new Set(["help"]);
+
+    const missing: string[] = [];
+    for (const entry of TOP_LEVEL_SUBCOMMANDS) {
+      if (SELF_REFERENTIAL.has(entry.cmd)) continue;
+      if (!helpCmds.has(entry.cmd)) {
+        missing.push(entry.cmd);
+      }
+    }
+
+    assert.deepStrictEqual(
+      missing,
+      [],
+      `Commands registered in TOP_LEVEL_SUBCOMMANDS but missing from /gsd help full:\n  ${missing.join(", ")}`,
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/import-done-milestones-runtime.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Runtime regression — milestones with all-done roadmap slices import as
+ * `complete` (#3699 / #3390 / #3379), follow-up #4902.
+ *
+ * The deleted `import-done-milestones.test.ts` was a source-grep check
+ * for the literal `roadmap.slices.every(s => s.done)`. This rewrite
+ * exercises `migrateHierarchyToDb()` against a fixture roadmap whose
+ * slices are all `[x]` and asserts the milestone row's `status` is
+ * `complete` — the actual behaviour the every() check exists to
+ * produce.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  getAllMilestones,
+} from '../gsd-db.ts';
+import { migrateHierarchyToDb } from '../md-importer.ts';
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-import-done-'));
+  mkdirSync(join(base, '.gsd', 'milestones'), { recursive: true });
+  return base;
+}
+
+function writeFile(base: string, relativePath: string, content: string): void {
+  const full = join(base, '.gsd', relativePath);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content);
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+const ROADMAP_ALL_DONE = `# M001: Finished Milestone
+
+**Vision:** Done work.
+
+## Slices
+
+- [x] **S01: First Slice** \`risk:low\` \`depends:[]\`
+  > After this: Done.
+
+- [x] **S02: Second Slice** \`risk:medium\` \`depends:[S01]\`
+  > After this: Also done.
+`;
+
+const ROADMAP_PARTIAL = `# M002: In-Progress Milestone
+
+**Vision:** Mid-flight.
+
+## Slices
+
+- [x] **S01: Done Slice** \`risk:low\` \`depends:[]\`
+  > After this: Done.
+
+- [ ] **S02: Pending Slice** \`risk:medium\` \`depends:[S01]\`
+  > After this: TBD.
+`;
+
+const ROADMAP_EMPTY = `# M003: Empty Milestone
+
+**Vision:** No slices yet.
+
+## Slices
+
+`;
+
+describe('migrateHierarchyToDb: all-done milestones import as complete (#4902)', () => {
+  test('milestone with all [x] slices and no SUMMARY imports as complete', () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_ALL_DONE);
+      // No SUMMARY.md — the all-done roadmap check is the authoritative signal.
+
+      openDatabase(':memory:');
+      migrateHierarchyToDb(base);
+
+      const milestones = getAllMilestones();
+      const m001 = milestones.find((m) => m.id === 'M001');
+      assert.ok(m001, 'M001 should be imported');
+      assert.equal(
+        m001!.status,
+        'complete',
+        'milestone with all-done slices must import as complete',
+      );
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test('milestone with one pending slice imports as active (negative case)', () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M002/M002-ROADMAP.md', ROADMAP_PARTIAL);
+
+      openDatabase(':memory:');
+      migrateHierarchyToDb(base);
+
+      const milestones = getAllMilestones();
+      const m002 = milestones.find((m) => m.id === 'M002');
+      assert.ok(m002, 'M002 should be imported');
+      assert.equal(
+        m002!.status,
+        'active',
+        'milestone with at least one pending slice must NOT be marked complete',
+      );
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test('milestone with empty slice list does not import as complete', () => {
+    // Guards the `roadmap.slices.length > 0` precondition: an empty roadmap
+    // must not be misread as "everything is done" (vacuous truth bug).
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M003/M003-ROADMAP.md', ROADMAP_EMPTY);
+
+      openDatabase(':memory:');
+      migrateHierarchyToDb(base);
+
+      const milestones = getAllMilestones();
+      const m003 = milestones.find((m) => m.id === 'M003');
+      assert.ok(m003, 'M003 should be imported');
+      assert.notEqual(
+        m003!.status,
+        'complete',
+        'empty roadmap (no slices) must not import as complete',
+      );
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+});

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

@@ -12,7 +12,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { mapInitPrefsToWizardShape } from "../init-wizard.ts";
-import { writePreferencesFile } from "../commands-prefs-wizard.ts";
+import { handlePrefsWizard, writePreferencesFile } from "../commands-prefs-wizard.ts";
 
 test("mapInitPrefsToWizardShape — full roundtrip with all fields", () => {
   const out = mapInitPrefsToWizardShape({
@@ -123,6 +123,69 @@ test("writePreferencesFile — falls back to default body for new files", async
   }
 });
 
+test("handlePrefsWizard — Advanced config writes min_request_interval_ms", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+
+  try {
+    const selectResponses = [
+      "Advanced",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "── Save & Exit ──",
+    ];
+    const inputResponses = ["250"];
+    const ctx = {
+      ui: {
+        notify: () => {},
+        select: async (_label: string, options: string[]) => {
+          const response = selectResponses.shift();
+          if (response === undefined) {
+            throw new Error(
+              `Unexpected extra select prompt in handlePrefsWizard flow: selectResponses queue exhausted for "${_label}" ` +
+                "(expected no additional select prompts)",
+            );
+          }
+          if (response === "Advanced") {
+            const advancedOption = options.find((option) => option.startsWith("Advanced"));
+            if (!advancedOption) {
+              throw new Error(`Expected an "Advanced" option in "${_label}" menu`);
+            }
+            return advancedOption;
+          }
+          return response;
+        },
+        input: async () => {
+          const response = inputResponses.shift();
+          if (response === undefined) {
+            throw new Error(
+              "Unexpected extra input prompt in handlePrefsWizard flow: inputResponses queue exhausted " +
+                "(expected no additional input prompts)",
+            );
+          }
+          return response;
+        },
+      },
+      waitForIdle: async () => {},
+      reload: async () => {},
+    };
+
+    await handlePrefsWizard(ctx as any, "project", {}, { pathOverride: path });
+
+    assert.equal(selectResponses.length, 0, "Expected all queued selectResponses to be consumed");
+    assert.equal(inputResponses.length, 0, "Expected all queued inputResponses to be consumed");
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /^min_request_interval_ms:\s*250$/m);
+  } 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 () => {

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

@@ -7,7 +7,7 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -21,6 +21,7 @@ import {
   getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
   syncGsdStateToWorktree,
+  _resetAutoWorktreeOriginalBaseForTests,
 } from "../../auto-worktree.ts";
 
 // Note: execSync is used intentionally in tests for git operations with
@@ -142,6 +143,54 @@ describe("auto-worktree lifecycle", () => {
     teardownAutoWorktree(tempDir, "M003");
   });
 
+  test("symlink-resolved auto worktree is detected after module state reset", () => {
+    tempDir = createTempRepo();
+    const savedGsdHome = process.env.GSD_HOME;
+    const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-home-")));
+    const storage = join(fakeHome, ".gsd", "projects", "abc123def456");
+    mkdirSync(join(storage, "milestones", "M001"), { recursive: true });
+    writeFileSync(join(storage, "milestones", "M001", "CONTEXT.md"), "# M001\n");
+    symlinkSync(storage, join(tempDir, ".gsd"));
+    process.env.GSD_HOME = join(fakeHome, ".gsd");
+
+    try {
+      const wtPath = createAutoWorktree(tempDir, "M001");
+      const realWtPath = realpathSync(wtPath);
+      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+
+      _resetAutoWorktreeOriginalBaseForTests();
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+
+      assert.ok(isInAutoWorktree(tempDir), "structural detection works without module originalBase");
+      const resolved = getAutoWorktreePath(realWtPath, "M001");
+      assert.ok(resolved, "existing worktree is found when basePath is the worktree path");
+      assert.equal(realpathSync(resolved!), realWtPath);
+      assert.equal(existsSync(join(realWtPath, ".gsd", "worktrees", "M001")), false);
+
+      enterAutoWorktree(tempDir, "M001");
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+      assert.deepStrictEqual(
+        getActiveAutoWorktreeContext(),
+        {
+          originalBase: tempDir,
+          worktreeName: "M001",
+          branch: "milestone/M001",
+        },
+        "active context is detected from a symlink-resolved worktree cwd",
+      );
+    } finally {
+      process.chdir(tempDir);
+      try {
+        teardownAutoWorktree(tempDir, "M001");
+      } catch {
+        // Best-effort cleanup for partially-created temp worktrees.
+      }
+      if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = savedGsdHome;
+      rmSync(fakeHome, { recursive: true, force: true });
+    }
+  });
+
   test("coexistence with manual worktree", async () => {
     tempDir = createTempRepo();
     const msDir = join(tempDir, ".gsd", "milestones", "M003");
@@ -345,4 +394,26 @@ describe("auto-worktree lifecycle", () => {
       teardownAutoWorktree(tempDir, "M003");
     }
   });
+
+  test("#2482: throws GSDError when repo has no commits", () => {
+    // Create a bare git init with no commits — HEAD is invalid
+    tempDir = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-empty-")));
+    run("git init", tempDir);
+    run("git config user.email test@test.com", tempDir);
+    run("git config user.name Test", tempDir);
+
+    assert.throws(
+      () => createAutoWorktree(tempDir, "M001"),
+      (err: unknown) => {
+        assert.ok(err instanceof Error, "should throw an Error");
+        assert.ok("code" in err, "should have a code property (GSDError)");
+        assert.strictEqual((err as { code: string }).code, "GSD_GIT_ERROR");
+        assert.ok(
+          err.message.includes("repository has no commits yet"),
+          `message should mention no commits, got: ${err.message}`,
+        );
+        return true;
+      },
+    );
+  });
 });