gsd-pi 2.29.0 → 2.30.0-dev.7e1bbce

package/src/resources/extensions/gsd/session-lock.ts

@@ -17,7 +17,7 @@
  */
 
 import { createRequire } from "node:module";
-import { existsSync, readFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, unlinkSync, rmSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -92,11 +92,12 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     return acquireFallbackLock(basePath, lp, lockData);
   }
 
+  const gsdDir = gsdRoot(basePath);
+
   try {
     // Try to acquire an exclusive OS-level lock on the lock file.
     // We lock the directory (gsdRoot) since proper-lockfile works best
     // on directories, and the lock file itself may not exist yet.
-    const gsdDir = gsdRoot(basePath);
     mkdirSync(gsdDir, { recursive: true });
 
     const release = lockfile.lockSync(gsdDir, {
@@ -109,16 +110,53 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     _lockedPath = basePath;
     _lockPid = process.pid;
 
+    // Safety net: clean up lock dir on process exit if _releaseFunction
+    // wasn't called (e.g., normal exit after clean completion) (#1245).
+    const lockDirForCleanup = join(gsdDir + ".lock");
+    process.once("exit", () => {
+      try {
+        if (_releaseFunction) { _releaseFunction(); _releaseFunction = null; }
+      } catch { /* best-effort */ }
+      try {
+        if (existsSync(lockDirForCleanup)) rmSync(lockDirForCleanup, { recursive: true, force: true });
+      } catch { /* best-effort */ }
+    });
+
     // Write the informational lock data
     atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
 
     return { acquired: true };
   } catch (err) {
-    // Lock is held by another process
+    // Lock is held by another process — or the .gsd.lock/ directory is stranded.
+    // Check: if auto.lock is gone and no process is alive, the lock dir is stale.
     const existingData = readExistingLockData(lp);
     const existingPid = existingData?.pid;
+
+    // If no lock file or no alive process, try to clean up and re-acquire (#1245)
+    if (!existingData || (existingPid && !isPidAlive(existingPid))) {
+      try {
+        const lockDir = join(gsdDir + ".lock");
+        if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+        if (existsSync(lp)) unlinkSync(lp);
+
+        // Retry acquisition after cleanup
+        const release = lockfile.lockSync(gsdDir, {
+          realpath: false,
+          stale: 300_000,
+          update: 10_000,
+        });
+        _releaseFunction = release;
+        _lockedPath = basePath;
+        _lockPid = process.pid;
+        atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
+        return { acquired: true };
+      } catch {
+        // Retry also failed — fall through to the error path
+      }
+    }
+
     const reason = existingPid
-      ? `Another auto-mode session (PID ${existingPid}) is already running on this project.`
+      ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
       : `Another auto-mode session is already running on this project.`;
 
     return { acquired: false, reason, existingPid };
@@ -233,6 +271,17 @@ export function releaseSessionLock(basePath: string): void {
     // Non-fatal
   }
 
+  // Remove the proper-lockfile directory (.gsd.lock/) if it exists.
+  // proper-lockfile creates this directory as the OS-level lock mechanism.
+  // If the process exits without calling _releaseFunction (SIGKILL, crash),
+  // this directory is stranded and blocks the next session (#1245).
+  try {
+    const lockDir = join(gsdRoot(basePath) + ".lock");
+    if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    // Non-fatal
+  }
+
   _lockedPath = null;
   _lockPid = 0;
 }

package/src/resources/extensions/gsd/session-status-io.ts

@@ -11,9 +11,6 @@
  */
 
 import {
-  writeFileSync,
-  readFileSync,
-  renameSync,
   unlinkSync,
   readdirSync,
   mkdirSync,
@@ -21,6 +18,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { loadJsonFileOrNull, writeJsonFileAtomic } from "./json-persistence.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -49,9 +47,16 @@ export interface SignalMessage {
 const PARALLEL_DIR = "parallel";
 const STATUS_SUFFIX = ".status.json";
 const SIGNAL_SUFFIX = ".signal.json";
-const TMP_SUFFIX = ".tmp";
 const DEFAULT_STALE_TIMEOUT_MS = 30_000;
 
+function isSessionStatus(data: unknown): data is SessionStatus {
+  return data !== null && typeof data === "object" && "milestoneId" in data && "pid" in data;
+}
+
+function isSignalMessage(data: unknown): data is SignalMessage {
+  return data !== null && typeof data === "object" && "signal" in data && "sentAt" in data;
+}
+
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 function parallelDir(basePath: string): string {
@@ -86,25 +91,13 @@ function isPidAlive(pid: number): boolean {
 
 /** Write session status atomically (write to .tmp, then rename). */
 export function writeSessionStatus(basePath: string, status: SessionStatus): void {
-  try {
-    ensureParallelDir(basePath);
-    const dest = statusPath(basePath, status.milestoneId);
-    const tmp = dest + TMP_SUFFIX;
-    writeFileSync(tmp, JSON.stringify(status, null, 2), "utf-8");
-    renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  ensureParallelDir(basePath);
+  writeJsonFileAtomic(statusPath(basePath, status.milestoneId), status);
 }
 
 /** Read a specific milestone's session status. */
 export function readSessionStatus(basePath: string, milestoneId: string): SessionStatus | null {
-  try {
-    const p = statusPath(basePath, milestoneId);
-    if (!existsSync(p)) return null;
-    const raw = readFileSync(p, "utf-8");
-    return JSON.parse(raw) as SessionStatus;
-  } catch {
-    return null;
-  }
+  return loadJsonFileOrNull(statusPath(basePath, milestoneId), isSessionStatus);
 }
 
 /** Read all session status files from .gsd/parallel/. */
@@ -114,13 +107,10 @@ export function readAllSessionStatuses(basePath: string): SessionStatus[] {
 
   const results: SessionStatus[] = [];
   try {
-    const entries = readdirSync(dir);
-    for (const entry of entries) {
+    for (const entry of readdirSync(dir)) {
       if (!entry.endsWith(STATUS_SUFFIX)) continue;
-      try {
-        const raw = readFileSync(join(dir, entry), "utf-8");
-        results.push(JSON.parse(raw) as SessionStatus);
-      } catch { /* skip corrupt files */ }
+      const status = loadJsonFileOrNull(join(dir, entry), isSessionStatus);
+      if (status) results.push(status);
     }
   } catch { /* non-fatal */ }
   return results;
@@ -138,27 +128,19 @@ export function removeSessionStatus(basePath: string, milestoneId: string): void
 
 /** Write a signal file for a worker to consume. */
 export function sendSignal(basePath: string, milestoneId: string, signal: SessionSignal): void {
-  try {
-    ensureParallelDir(basePath);
-    const dest = signalPath(basePath, milestoneId);
-    const tmp = dest + TMP_SUFFIX;
-    const msg: SignalMessage = { signal, sentAt: Date.now(), from: "coordinator" };
-    writeFileSync(tmp, JSON.stringify(msg, null, 2), "utf-8");
-    renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  ensureParallelDir(basePath);
+  const msg: SignalMessage = { signal, sentAt: Date.now(), from: "coordinator" };
+  writeJsonFileAtomic(signalPath(basePath, milestoneId), msg);
 }
 
 /** Read and delete a signal file (atomic consume). Returns null if no signal pending. */
 export function consumeSignal(basePath: string, milestoneId: string): SignalMessage | null {
-  try {
-    const p = signalPath(basePath, milestoneId);
-    if (!existsSync(p)) return null;
-    const raw = readFileSync(p, "utf-8");
-    unlinkSync(p);
-    return JSON.parse(raw) as SignalMessage;
-  } catch {
-    return null;
+  const p = signalPath(basePath, milestoneId);
+  const msg = loadJsonFileOrNull(p, isSignalMessage);
+  if (msg) {
+    try { unlinkSync(p); } catch { /* non-fatal */ }
   }
+  return msg;
 }
 
 // ─── Stale Detection ───────────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/activity-log.test.ts

@@ -6,7 +6,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, utimesSync, writeFileSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, realpathSync, rmSync, utimesSync, writeFileSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -18,7 +18,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function createTmpDir(): string {
-  return mkdtempSync(join(tmpdir(), "gsd-activity-test-"));
+  return realpathSync(mkdtempSync(join(tmpdir(), "gsd-activity-test-")));
 }
 
 function writeActivityFile(dir: string, seq: string, name: string): string {

package/src/resources/extensions/gsd/tests/auto-budget-alerts.test.ts

@@ -5,7 +5,7 @@ import {
   getBudgetAlertLevel,
   getBudgetEnforcementAction,
   getNewBudgetAlertLevel,
-} from "../auto.js";
+} from "../auto-budget.js";
 
 test("getBudgetAlertLevel returns the expected threshold bucket", () => {
   assert.equal(getBudgetAlertLevel(0.10), 0);

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

@@ -308,8 +308,8 @@ test("loadPersistedKeys unions keys from project root and worktree", () => {
 });
 
 test("completed-units.json set-union merge produces correct result", () => {
-  // Verify that a manual set-union merge (as done in syncStateToProjectRoot)
-  // correctly merges two JSON arrays of keys.
+  // Verify that a manual set-union merge correctly merges two JSON arrays
+  // of completed-unit keys.
   const projectRoot = makeTmpBase();
   const worktree = makeTmpBase();
   try {
@@ -320,7 +320,7 @@ test("completed-units.json set-union merge produces correct result", () => {
     writeFileSync(prKeysFile, JSON.stringify(["a", "b"]));
     writeFileSync(wtKeysFile, JSON.stringify(["b", "c", "d"]));
 
-    // Perform the same merge logic used in syncStateToProjectRoot
+    // Perform a set-union merge of two JSON key arrays
     const srcKeys: string[] = JSON.parse(readFileSync(wtKeysFile, "utf8"));
     let dstKeys: string[] = [];
     if (existsSync(prKeysFile)) {

package/src/resources/extensions/gsd/tests/auto-skip-loop.test.ts

@@ -17,8 +17,8 @@ import { tmpdir } from "node:os";
 import {
   _getUnitConsecutiveSkips,
   _resetUnitConsecutiveSkips,
-  MAX_CONSECUTIVE_SKIPS,
 } from "../auto.ts";
+import { MAX_CONSECUTIVE_SKIPS } from "../auto/session.ts";
 import { persistCompletedKey, removePersistedKey, loadPersistedKeys } from "../auto-recovery.ts";
 import { createTestContext } from "./test-helpers.ts";
 

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

@@ -153,64 +153,6 @@ async function main(): Promise<void> {
     // After teardown, originalBase should be null
     assertEq(getAutoWorktreeOriginalBase(), null, "no split-brain: originalBase cleared");
 
-    // ─── #778: reconcile plan checkboxes on re-attach ─────────────────
-    console.log("\n=== #778: reconcile plan checkboxes on re-attach ===");
-    {
-      // Simulate: T01 [x] was committed to milestone branch, T02 [x] was
-      // written to project root by syncStateToProjectRoot() but the
-      // auto-commit crashed before it fired. On restart the worktree is
-      // re-created from the milestone branch HEAD (T02 still [ ]).
-      // reconcilePlanCheckboxes should forward-apply T02 [x] from the root.
-
-      const planRelPath = join(".gsd", "milestones", "M004", "slices", "S01", "S01-PLAN.md");
-      const planDir = join(tempDir, ".gsd", "milestones", "M004", "slices", "S01");
-      const { mkdirSync: mkdir, writeFileSync: write, readFileSync: read } = await import("node:fs");
-
-      // Plan on integration branch (project root): T01 [x], T02 [x]
-      mkdir(planDir, { recursive: true });
-      write(
-        join(tempDir, planRelPath),
-        "# S01 Plan\n- [x] **T01:** task one\n- [x] **T02:** task two\n- [ ] **T03:** task three\n",
-      );
-
-      // Write integration-branch plan to git so milestone branch starts from it
-      run(`git add .`, tempDir);
-      run(`git commit -m "add plan with T01 and T02 checked" --allow-empty`, tempDir);
-
-      // Create milestone branch with only T01 [x] (simulating crash before T02 commit)
-      const milestoneBranch = "milestone/M004";
-      run(`git checkout -b ${milestoneBranch}`, tempDir);
-      mkdir(planDir, { recursive: true });
-      write(
-        join(tempDir, planRelPath),
-        "# S01 Plan\n- [x] **T01:** task one\n- [ ] **T02:** task two\n- [ ] **T03:** task three\n",
-      );
-      run(`git add .`, tempDir);
-      run(`git commit -m "milestone: only T01 checked"`, tempDir);
-      run(`git checkout main`, tempDir);
-
-      // Restore project root plan (T01+T02 [x]) — simulates syncStateToProjectRoot
-      write(
-        join(tempDir, planRelPath),
-        "# S01 Plan\n- [x] **T01:** task one\n- [x] **T02:** task two\n- [ ] **T03:** task three\n",
-      );
-
-      // Create worktree re-attached to existing milestone branch (T02 still [ ] in branch)
-      const wtPath = createAutoWorktree(tempDir, "M004");
-
-      try {
-        const wtPlanPath = join(wtPath, planRelPath);
-        assertTrue(existsSync(wtPlanPath), "plan file exists in worktree after re-attach");
-
-        const wtPlan = read(wtPlanPath, "utf-8");
-        assertTrue(wtPlan.includes("- [x] **T02:"), "T02 should be [x] after reconciliation (was [ ] on branch)");
-        assertTrue(wtPlan.includes("- [x] **T01:"), "T01 stays [x]");
-        assertTrue(wtPlan.includes("- [ ] **T03:"), "T03 stays [ ] (not in root either)");
-      } finally {
-        teardownAutoWorktree(tempDir, "M004");
-      }
-    }
-
   } finally {
     // Always restore cwd and clean up
     process.chdir(savedCwd);

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

@@ -231,15 +231,14 @@ None
       const detect = await runGSDDoctor(dir);
       const gitignoreIssues = detect.issues.filter(i => i.code === "gitignore_missing_patterns");
       assertTrue(gitignoreIssues.length > 0, "detects missing gitignore patterns");
-      assertTrue(gitignoreIssues[0]?.message.includes(".gsd/activity/"), "message lists missing patterns");
+      assertTrue(gitignoreIssues[0]?.message.includes(".gsd"), "message lists missing .gsd pattern");
 
       const fixed = await runGSDDoctor(dir, { fix: true });
       assertTrue(fixed.fixesApplied.some(f => f.includes("added missing GSD runtime patterns")), "fix adds patterns");
 
-      // Verify patterns were added
+      // Verify .gsd entry was added (external state symlink)
       const content = readFileSync(join(dir, ".gitignore"), "utf-8");
-      assertTrue(content.includes(".gsd/activity/"), "gitignore now has activity pattern");
-      assertTrue(content.includes(".gsd/auto.lock"), "gitignore now has auto.lock pattern");
+      assertTrue(content.includes(".gsd"), "gitignore now has .gsd entry");
     }
     } else {
       console.log("\n=== gitignore_missing_patterns (skipped on Windows) ===");

package/src/resources/extensions/gsd/tests/extension-selector-separator.test.ts

@@ -1,4 +1,6 @@
-// Tests for the SEPARATOR_PREFIX convention used by ExtensionSelectorComponent.
+// Tests for the SEPARATOR_PREFIX convention used by ExtensionSelectorComponent
+// and the two-step provider→model picker in configureModels.
+//
 // We cannot import the component directly in node:test because its transitive
 // dependency (countdown-timer.ts) uses TypeScript parameter properties which
 // are unsupported under --experimental-strip-types. Instead we duplicate the
@@ -69,16 +71,17 @@ describe("separator detection", () => {
 	});
 });
 
-describe("model grouping", () => {
-	test("groups models by provider with separator headers", () => {
-		// Simulate the grouping logic from configureModels
-		const availableModels = [
-			{ id: "claude-opus-4-6", provider: "anthropic" },
-			{ id: "gpt-4o", provider: "openai" },
-			{ id: "claude-sonnet-4-5", provider: "anthropic" },
-			{ id: "o3-mini", provider: "openai" },
-		];
+describe("two-step provider→model picker", () => {
+	// Simulate the grouping logic from configureModels
+	const availableModels = [
+		{ id: "claude-opus-4-6", provider: "anthropic" },
+		{ id: "gpt-4o", provider: "openai" },
+		{ id: "claude-sonnet-4-5", provider: "anthropic" },
+		{ id: "o3-mini", provider: "openai" },
+		{ id: "claude-haiku-4-5", provider: "anthropic" },
+	];
 
+	function buildProviderGroups() {
 		const byProvider = new Map<string, typeof availableModels>();
 		for (const m of availableModels) {
 			let group = byProvider.get(m.provider);
@@ -89,34 +92,53 @@ describe("model grouping", () => {
 			group.push(m);
 		}
 		const providers = Array.from(byProvider.keys()).sort((a, b) => a.localeCompare(b));
-
-		const modelOptions: string[] = [];
-		for (const provider of providers) {
-			const group = byProvider.get(provider)!;
-			modelOptions.push(`${SEPARATOR_PREFIX} ${provider} (${group.length}) ${SEPARATOR_PREFIX}`);
-			for (const m of group) {
-				modelOptions.push(`${m.id} · ${m.provider}`);
-			}
+		for (const group of byProvider.values()) {
+			group.sort((a, b) => a.id.localeCompare(b.id));
 		}
-		modelOptions.push("(keep current)", "(clear)");
-
-		// Verify structure
-		assert.strictEqual(modelOptions[0], `${SEPARATOR_PREFIX} anthropic (2) ${SEPARATOR_PREFIX}`);
-		assert.strictEqual(modelOptions[1], "claude-opus-4-6 · anthropic");
-		assert.strictEqual(modelOptions[2], "claude-sonnet-4-5 · anthropic");
-		assert.strictEqual(modelOptions[3], `${SEPARATOR_PREFIX} openai (2) ${SEPARATOR_PREFIX}`);
-		assert.strictEqual(modelOptions[4], "gpt-4o · openai");
-		assert.strictEqual(modelOptions[5], "o3-mini · openai");
-		assert.strictEqual(modelOptions[6], "(keep current)");
-		assert.strictEqual(modelOptions[7], "(clear)");
-
-		// Verify separators are correctly detected
-		assert.ok(isSeparator(modelOptions, 0));
-		assert.ok(!isSeparator(modelOptions, 1));
-		assert.ok(isSeparator(modelOptions, 3));
-		assert.ok(!isSeparator(modelOptions, 6));
-
-		// Verify first selectable is index 1, not the separator at 0
-		assert.strictEqual(nextSelectable(modelOptions, 0, 1), 1);
+		return { byProvider, providers };
+	}
+
+	test("provider menu lists providers with model counts", () => {
+		const { providers, byProvider } = buildProviderGroups();
+		const providerOptions = providers.map(p => {
+			const count = byProvider.get(p)!.length;
+			return `${p} (${count} models)`;
+		});
+		providerOptions.push("(keep current)", "(clear)", "(type manually)");
+
+		assert.strictEqual(providerOptions[0], "anthropic (3 models)");
+		assert.strictEqual(providerOptions[1], "openai (2 models)");
+		assert.strictEqual(providerOptions[2], "(keep current)");
+		assert.strictEqual(providerOptions[3], "(clear)");
+		assert.strictEqual(providerOptions[4], "(type manually)");
+	});
+
+	test("model menu for a provider is sorted alphabetically", () => {
+		const { byProvider } = buildProviderGroups();
+		const anthropicModels = byProvider.get("anthropic")!;
+		const modelOptions = anthropicModels.map(m => m.id);
+
+		assert.strictEqual(modelOptions[0], "claude-haiku-4-5");
+		assert.strictEqual(modelOptions[1], "claude-opus-4-6");
+		assert.strictEqual(modelOptions[2], "claude-sonnet-4-5");
+	});
+
+	test("provider name is extracted correctly from choice string", () => {
+		const choice = "anthropic (3 models)";
+		const providerName = choice.replace(/ \(\d+ models?\)$/, "");
+		assert.strictEqual(providerName, "anthropic");
+
+		const singleChoice = "ollama (1 model)";
+		const singleProvider = singleChoice.replace(/ \(\d+ models?\)$/, "");
+		assert.strictEqual(singleProvider, "ollama");
+	});
+
+	test("openai models are sorted within their group", () => {
+		const { byProvider } = buildProviderGroups();
+		const openaiModels = byProvider.get("openai")!;
+		const modelOptions = openaiModels.map(m => m.id);
+
+		assert.strictEqual(modelOptions[0], "gpt-4o");
+		assert.strictEqual(modelOptions[1], "o3-mini");
 	});
 });

package/src/resources/extensions/gsd/tests/feature-branch-lifecycle-integration.test.ts

@@ -311,7 +311,7 @@ async function main(): Promise<void> {
     // Test 2: Uncommitted .gsd/ planning files are available in worktree
     //
     // When auto-mode starts, .gsd/ files may be untracked/uncommitted.
-    // copyPlanningArtifacts should carry them into the worktree even if
+    // Planning artifacts should be carried into the worktree even if
     // they weren't committed on the feature branch.
     // ================================================================
     console.log("\n=== Untracked planning files copied to worktree ===");
@@ -341,23 +341,10 @@ async function main(): Promise<void> {
       const wtPath = createAutoWorktree(repo, milestoneId);
       tempDirs.push(wtPath);
 
-      // Planning files should exist in the worktree (via copyPlanningArtifacts)
-      assertTrue(
-        existsSync(join(wtPath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`)),
-        "ROADMAP.md copied to worktree",
-      );
-      assertTrue(
-        existsSync(join(wtPath, ".gsd", "milestones", milestoneId, "slices", "S01", "S01-PLAN.md")),
-        "S01-PLAN.md copied to worktree",
-      );
-      assertTrue(
-        existsSync(join(wtPath, ".gsd", "PROJECT.md")),
-        "PROJECT.md copied to worktree",
-      );
-      assertTrue(
-        existsSync(join(wtPath, ".gsd", "DECISIONS.md")),
-        "DECISIONS.md copied to worktree",
-      );
+      // With external state, worktree .gsd is a symlink to shared state.
+      // Verify symlink was created (planning files are shared, not copied).
+      const wtGsd = join(wtPath, ".gsd");
+      assertTrue(existsSync(wtGsd), "worktree .gsd exists (symlink or dir)");
 
       // Clean up: chdir back before teardown
       process.chdir(savedCwd);

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

@@ -1167,53 +1167,26 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
-  // ─── ensureGitignore: commit_docs false adds blanket .gsd/ ──────────
+  // ─── ensureGitignore: always adds .gsd to gitignore ──────────────────
 
-  console.log("\n=== ensureGitignore: commit_docs false ===");
+  console.log("\n=== ensureGitignore: adds .gsd entry ===");
 
   {
     const { ensureGitignore } = await import("../gitignore.ts");
-    const repo = mkdtempSync(join(tmpdir(), "gsd-gitignore-commit-docs-"));
+    const repo = mkdtempSync(join(tmpdir(), "gsd-gitignore-external-state-"));
 
-    // When commit_docs is false, should add blanket .gsd/ to gitignore
-    const modified = ensureGitignore(repo, { commitDocs: false });
-    assertTrue(modified, "commit_docs=false: gitignore was modified");
+    // Should add .gsd to gitignore (external state dir is a symlink)
+    const modified = ensureGitignore(repo);
+    assertTrue(modified, "ensureGitignore: gitignore was modified");
 
     const { readFileSync } = await import("node:fs");
     const content = readFileSync(join(repo, ".gitignore"), "utf-8");
-    assertTrue(content.includes(".gsd/"), "commit_docs=false: .gitignore contains blanket .gsd/");
-    assertTrue(content.includes("commit_docs: false"), "commit_docs=false: .gitignore contains explanatory comment");
-
-    // Should NOT contain individual runtime patterns (those are subsumed by blanket .gsd/)
-    // But it's OK if it does — the blanket .gsd/ covers everything
+    const lines = content.split("\n").map(l => l.trim()).filter(l => l && !l.startsWith("#"));
+    assertTrue(lines.includes(".gsd"), "ensureGitignore: .gitignore contains .gsd");
 
     // Idempotent — calling again doesn't add duplicates
-    const modified2 = ensureGitignore(repo, { commitDocs: false });
-    assertTrue(!modified2, "commit_docs=false: second call is idempotent");
-
-    rmSync(repo, { recursive: true, force: true });
-  }
-
-  // ─── ensureGitignore: commit_docs true removes blanket .gsd/ ────────
-
-  console.log("\n=== ensureGitignore: commit_docs true self-heals ===");
-
-  {
-    const { ensureGitignore } = await import("../gitignore.ts");
-    const repo = mkdtempSync(join(tmpdir(), "gsd-gitignore-selfheal-"));
-
-    // Start with a gitignore that has a blanket .gsd/ (e.g., user switched setting)
-    writeFileSync(join(repo, ".gitignore"), ".gsd/\n");
-
-    const modified = ensureGitignore(repo, { commitDocs: true });
-    assertTrue(modified, "commit_docs=true: gitignore was modified");
-
-    const { readFileSync } = await import("node:fs");
-    const content = readFileSync(join(repo, ".gitignore"), "utf-8");
-    // Blanket .gsd/ should be removed
-    const lines = content.split("\n").map(l => l.trim()).filter(l => l && !l.startsWith("#"));
-    assertTrue(!lines.includes(".gsd/"), "commit_docs=true: blanket .gsd/ was removed");
-    assertTrue(!lines.includes(".gsd"), "commit_docs=true: blanket .gsd was removed");
+    const modified2 = ensureGitignore(repo);
+    assertTrue(!modified2, "ensureGitignore: second call is idempotent");
 
     rmSync(repo, { recursive: true, force: true });
   }

package/src/resources/extensions/gsd/tests/knowledge.test.ts

@@ -10,7 +10,7 @@
 
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { GSD_ROOT_FILES, resolveGsdRootFile } from '../paths.ts';
@@ -27,7 +27,7 @@ test('knowledge: KNOWLEDGE key exists in GSD_ROOT_FILES', () => {
 // ─── resolveGsdRootFile resolves KNOWLEDGE.md ───────────────────────────────
 
 test('knowledge: resolveGsdRootFile returns canonical path when KNOWLEDGE.md exists', () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-knowledge-')));
   const gsdDir = join(tmp, '.gsd');
   mkdirSync(gsdDir, { recursive: true });
   writeFileSync(join(gsdDir, 'KNOWLEDGE.md'), '# Project Knowledge\n');
@@ -39,7 +39,7 @@ test('knowledge: resolveGsdRootFile returns canonical path when KNOWLEDGE.md exi
 });
 
 test('knowledge: resolveGsdRootFile resolves when legacy knowledge.md exists', () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-knowledge-')));
   const gsdDir = join(tmp, '.gsd');
   mkdirSync(gsdDir, { recursive: true });
   writeFileSync(join(gsdDir, 'knowledge.md'), '# Project Knowledge\n');
@@ -58,7 +58,7 @@ test('knowledge: resolveGsdRootFile resolves when legacy knowledge.md exists', (
 });
 
 test('knowledge: resolveGsdRootFile returns canonical path when file does not exist', () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-knowledge-')));
   const gsdDir = join(tmp, '.gsd');
   mkdirSync(gsdDir, { recursive: true });