gsd-pi 2.34.0 → 2.35.0-dev.30eec3f

package/src/resources/extensions/gsd/paths.ts

@@ -10,7 +10,8 @@
  */
 
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, normalize } from "node:path";
+import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 
@@ -277,15 +278,80 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   KNOWLEDGE: "knowledge.md",
 };
 
+// ─── GSD Root Discovery ───────────────────────────────────────────────────────
+
+const gsdRootCache = new Map<string, string>();
+
+/** Exported for tests only — do not call in production code. */
+export function _clearGsdRootCache(): void {
+  gsdRootCache.clear();
+}
+
+/**
+ * Resolve the `.gsd` directory for a given project base path.
+ *
+ * Probe order:
+ *   1. basePath/.gsd         — fast path (common case)
+ *   2. git rev-parse root    — handles cwd-is-a-subdirectory
+ *   3. Walk up from basePath — handles moved .gsd in an ancestor (bounded by git root)
+ *   4. basePath/.gsd         — creation fallback (init scenario)
+ *
+ * Result is cached per basePath for the process lifetime.
+ */
 export function gsdRoot(basePath: string): string {
-  const local = join(basePath, ".gsd");
-  try {
-    const resolved = realpathSync(local);
-    if (resolved !== local) return resolved; // symlink resolved
-  } catch { /* doesn't exist yet — fall through */ }
-  return local; // backwards compat: unmigrated projects
+  const cached = gsdRootCache.get(basePath);
+  if (cached) return cached;
+
+  const result = probeGsdRoot(basePath);
+  gsdRootCache.set(basePath, result);
+  return result;
 }
 
+function probeGsdRoot(rawBasePath: string): string {
+  // 1. Fast path — check the input path directly
+  const local = join(rawBasePath, ".gsd");
+  if (existsSync(local)) return local;
+
+  // Resolve symlinks so path comparisons work correctly across platforms
+  // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable.
+  let basePath: string;
+  try { basePath = realpathSync.native(rawBasePath); } catch { basePath = rawBasePath; }
+
+  // 2. Git root anchor — used as both probe target and walk-up boundary
+  //    Only walk if we're inside a git project — prevents escaping into
+  //    unrelated filesystem territory when running outside any repo.
+  let gitRoot: string | null = null;
+  try {
+    const out = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: basePath,
+      encoding: "utf-8",
+    });
+    if (out.status === 0) {
+      const r = out.stdout.trim();
+      if (r) gitRoot = normalize(r);
+    }
+  } catch { /* git not available */ }
+
+  if (gitRoot) {
+    const candidate = join(gitRoot, ".gsd");
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. Walk up from basePath to the git root (only if we are in a subdirectory)
+  if (gitRoot && basePath !== gitRoot) {
+    let cur = dirname(basePath);
+    while (cur !== basePath) {
+      const candidate = join(cur, ".gsd");
+      if (existsSync(candidate)) return candidate;
+      if (cur === gitRoot) break;
+      basePath = cur;
+      cur = dirname(cur);
+    }
+  }
+
+  // 4. Fallback for init/creation
+  return local;
+}
 export function milestonesDir(basePath: string): string {
   return join(gsdRoot(basePath), "milestones");
 }

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -149,11 +149,15 @@ function dequeueNextHook(basePath: string): HookDispatchResult | null {
 
     // Build the prompt with variable substitution
     const [mid, sid, tid] = triggerUnitId.split("/");
-    const prompt = config.prompt
+    let prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
       .replace(/\{sliceId\}/g, sid ?? "")
       .replace(/\{taskId\}/g, tid ?? "");
 
+    // Inject browser safety instruction for hooks that may use browser tools (#1345).
+    // Vite HMR and other persistent connections prevent networkidle from resolving.
+    prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
+
     return {
       hookName: config.name,
       prompt,

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -33,9 +33,24 @@ export function validatePreferences(preferences: GSDPreferences): {
   const validated: GSDPreferences = {};
 
   // ─── Unknown Key Detection ──────────────────────────────────────────
+  // Common key migration hints for pi-level settings that don't map to GSD prefs
+  const KEY_MIGRATION_HINTS: Record<string, string> = {
+    taskIsolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    task_isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    manage_gitignore: 'use "git.manage_gitignore" instead',
+    auto_push: 'use "git.auto_push" instead',
+    main_branch: 'use "git.main_branch" instead',
+  };
+
   for (const key of Object.keys(preferences)) {
     if (!KNOWN_PREFERENCE_KEYS.has(key)) {
-      warnings.push(`unknown preference key "${key}" — ignored`);
+      const hint = KEY_MIGRATION_HINTS[key];
+      if (hint) {
+        warnings.push(`unknown preference key "${key}" — ${hint}`);
+      } else {
+        warnings.push(`unknown preference key "${key}" — ignored`);
+      }
     }
   }
 
@@ -586,5 +601,43 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Auto Visualize ─────────────────────────────────────────────────
+  if (preferences.auto_visualize !== undefined) {
+    if (typeof preferences.auto_visualize === "boolean") {
+      validated.auto_visualize = preferences.auto_visualize;
+    } else {
+      errors.push("auto_visualize must be a boolean");
+    }
+  }
+
+  // ─── Auto Report ────────────────────────────────────────────────────
+  if (preferences.auto_report !== undefined) {
+    if (typeof preferences.auto_report === "boolean") {
+      validated.auto_report = preferences.auto_report;
+    } else {
+      errors.push("auto_report must be a boolean");
+    }
+  }
+
+  // ─── Compression Strategy ───────────────────────────────────────────
+  if (preferences.compression_strategy !== undefined) {
+    const validStrategies = new Set(["truncate", "compress"]);
+    if (typeof preferences.compression_strategy === "string" && validStrategies.has(preferences.compression_strategy)) {
+      validated.compression_strategy = preferences.compression_strategy as GSDPreferences["compression_strategy"];
+    } else {
+      errors.push(`compression_strategy must be one of: truncate, compress`);
+    }
+  }
+
+  // ─── Context Selection ──────────────────────────────────────────────
+  if (preferences.context_selection !== undefined) {
+    const validModes = new Set(["full", "smart"]);
+    if (typeof preferences.context_selection === "string" && validModes.has(preferences.context_selection)) {
+      validated.context_selection = preferences.context_selection as GSDPreferences["context_selection"];
+    } else {
+      errors.push(`context_selection must be one of: full, smart`);
+    }
+  }
+
   return { preferences: validated, errors, warnings };
 }

package/src/resources/extensions/gsd/preferences.ts

@@ -252,6 +252,8 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     search_provider: override.search_provider ?? base.search_provider,
     compression_strategy: override.compression_strategy ?? base.compression_strategy,
     context_selection: override.context_selection ?? base.context_selection,
+    auto_visualize: override.auto_visualize ?? base.auto_visualize,
+    auto_report: override.auto_report ?? base.auto_report,
   };
 }
 

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -28,6 +28,8 @@ Then:
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
 
 When done, say: "Milestone {{milestoneId}} complete."

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -67,4 +67,6 @@ If verdict is `needs-remediation`:
 
 **You MUST write `{{validationPath}}` before finishing.**
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/src/resources/extensions/gsd/roadmap-mutations.ts

@@ -0,0 +1,66 @@
+/**
+ * Roadmap Mutations — shared utilities for modifying roadmap checkbox state.
+ *
+ * Extracts the duplicated "flip slice checkbox" pattern that existed in
+ * doctor.ts, mechanical-completion.ts, and auto-recovery.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { clearParseCache } from "./files.js";
+
+/**
+ * Mark a slice as done ([x]) in the milestone roadmap.
+ * Idempotent — no-op if already checked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceDoneInRoadmap(basePath: string, mid: string, sid: string): boolean {
+  const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  if (!roadmapFile) return false;
+
+  let content: string;
+  try {
+    content = readFileSync(roadmapFile, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[x] **${sid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(roadmapFile, updated);
+  clearParseCache();
+  return true;
+}
+
+/**
+ * Mark a task as done ([x]) in the slice plan.
+ * Idempotent — no-op if already checked or if the task isn't found.
+ *
+ * @returns true if the plan was modified, false if no change was needed
+ */
+export function markTaskDoneInPlan(basePath: string, planPath: string, tid: string): boolean {
+  let content: string;
+  try {
+    content = readFileSync(planPath, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"),
+    `$1[x] **${tid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(planPath, updated);
+  clearParseCache();
+  return true;
+}

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

@@ -57,9 +57,19 @@ let _lockCompromised: boolean = false;
 /** Whether we've already registered a process.on('exit') handler. */
 let _exitHandlerRegistered: boolean = false;
 
+/** Snapshotted lock file path — captured at acquireSessionLock time to avoid
+ *  gsdRoot() resolving differently in worktree vs project root contexts (#1363). */
+let _snapshotLockPath: string | null = null;
+
+/** Timestamp when the session lock was acquired — used to detect false-positive
+ *  onCompromised events from event loop stalls within the stale window (#1362). */
+let _lockAcquiredAt: number = 0;
+
 const LOCK_FILE = "auto.lock";
 
 function lockPath(basePath: string): string {
+  // If we have a snapshotted path from acquisition, use it for consistency
+  if (_snapshotLockPath) return _snapshotLockPath;
   return join(gsdRoot(basePath), LOCK_FILE);
 }
 
@@ -198,8 +208,19 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
       onCompromised: () => {
         // proper-lockfile detected mtime drift (system sleep, event loop stall, etc.).
         // Default handler throws inside setTimeout — an uncaught exception that crashes
-        // or corrupts process state. Instead, set a flag so validateSessionLock() can
-        // detect the compromise gracefully on the next dispatch cycle.
+        // or corrupts process state.
+        //
+        // False-positive suppression (#1362): If we're still within the stale window
+        // (30 min since acquisition), the mtime mismatch is from an event loop stall
+        // during a long LLM call — not a real takeover. Log and continue.
+        const elapsed = Date.now() - _lockAcquiredAt;
+        if (elapsed < 1_800_000) {
+          process.stderr.write(
+            `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`,
+          );
+          return; // Suppress false positive
+        }
+        // Past the stale window — this is a real compromise
         _lockCompromised = true;
         _releaseFunction = null;
       },
@@ -209,6 +230,8 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     _lockedPath = basePath;
     _lockPid = process.pid;
     _lockCompromised = false;
+    _lockAcquiredAt = Date.now();
+    _snapshotLockPath = lp; // Snapshot the resolved path for consistent access (#1363)
 
     // Safety net: clean up lock dir on process exit if _releaseFunction
     // wasn't called (e.g., normal exit after clean completion) (#1245).
@@ -245,6 +268,8 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
         _lockedPath = basePath;
         _lockPid = process.pid;
         _lockCompromised = false;
+        _lockAcquiredAt = Date.now();
+        _snapshotLockPath = lp; // Snapshot for retry path too (#1363)
 
         // Safety net — uses centralized handler to avoid double-registration
         ensureExitHandler(gsdDir);
@@ -394,6 +419,8 @@ export function releaseSessionLock(basePath: string): void {
   _lockedPath = null;
   _lockPid = 0;
   _lockCompromised = false;
+  _lockAcquiredAt = 0;
+  _snapshotLockPath = null;
 }
 
 /**

package/src/resources/extensions/gsd/templates/plan.md

@@ -113,6 +113,14 @@
   - Tasks execute sequentially in order (T01, T02, T03, ...)
   - est: is informational (e.g. 30m, 1h, 2h) and optional
 
+  Verify field rules:
+  - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
+  - For content/document tasks: verify file existence, section count, YAML validity, or word count
+    NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
+  - If no command can verify the output, write: "Manual review — file exists and is non-empty"
+  - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
+  - GOOD: `grep -c "^## " doc.md` returns >= 4 (4+ sections), `! grep -q "TBD\|TODO" doc.md`
+
   Integration closure rule:
   - At least one slice in any multi-boundary milestone should perform real composition/wiring, not just contract hardening
   - For the final assembly slice, verification must exercise the real entrypoint or runtime path

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

@@ -0,0 +1,46 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+import { handleInspect } from "../commands-inspect.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
+
+test("/gsd inspect opens existing database when it was not yet opened in session", async () => {
+  closeDatabase();
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-inspect-db-"));
+  const prevCwd = process.cwd();
+
+  try {
+    const gsdDir = path.join(tmp, ".gsd");
+    fs.mkdirSync(gsdDir, { recursive: true });
+    const dbPath = path.join(gsdDir, "gsd.db");
+
+    assert.equal(openDatabase(dbPath), true);
+    closeDatabase();
+
+    process.chdir(tmp);
+
+    const notifications: Array<{ message: string; level: string }> = [];
+    const ctx = {
+      ui: {
+        notify(message: string, level: string) {
+          notifications.push({ message, level });
+        },
+      },
+    } as any;
+
+    await handleInspect(ctx);
+
+    assert.equal(notifications.length, 1);
+    assert.equal(notifications[0].level, "info");
+    assert.match(notifications[0].message, /=== GSD Database Inspect ===/);
+    assert.doesNotMatch(notifications[0].message, /No GSD database available/);
+  } finally {
+    process.chdir(prevCwd);
+    closeDatabase();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

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

@@ -2,9 +2,10 @@
  * doctor-git.test.ts — Integration tests for doctor git health checks.
  *
  * Creates real temp git repos with deliberate broken state, runs runGSDDoctor,
- * and asserts correct detection and fixing of all 4 git issue codes:
+ * and asserts correct detection and fixing of git issue codes:
  *   orphaned_auto_worktree, stale_milestone_branch,
- *   corrupt_merge_state, tracked_runtime_files
+ *   corrupt_merge_state, tracked_runtime_files,
+ *   integration_branch_missing, worktree_directory_orphaned
  */
 
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
@@ -299,6 +300,101 @@ async function main(): Promise<void> {
       console.log("\n=== none-mode skips stale branch (skipped on Windows) ===");
     }
 
+    // ─── Test: Integration branch missing ──────────────────────────────
+    if (process.platform !== "win32") {
+    console.log("\n=== integration_branch_missing ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Write integration branch metadata for M001 pointing to a non-existent branch
+      const metaPath = join(dir, ".gsd", "milestones", "M001", "M001-META.json");
+      writeFileSync(metaPath, JSON.stringify({ integrationBranch: "feat/does-not-exist" }, null, 2));
+
+      const detect = await runGSDDoctor(dir);
+      const missingBranchIssues = detect.issues.filter(i => i.code === "integration_branch_missing");
+      assertTrue(missingBranchIssues.length > 0, "detects missing integration branch");
+      assertTrue(
+        missingBranchIssues[0]?.message.includes("feat/does-not-exist"),
+        "message includes the missing branch name",
+      );
+      assertEq(missingBranchIssues[0]?.fixable, false, "integration_branch_missing is not auto-fixable");
+      assertEq(missingBranchIssues[0]?.severity, "error", "severity is error");
+    }
+    } else {
+      console.log("\n=== integration_branch_missing (skipped on Windows) ===");
+    }
+
+    // ─── Test: Integration branch present — no false positive ──────────
+    if (process.platform !== "win32") {
+    console.log("\n=== integration_branch_missing (no false positive) ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Write integration branch metadata for M001 pointing to "main" (which exists)
+      const metaPath = join(dir, ".gsd", "milestones", "M001", "M001-META.json");
+      writeFileSync(metaPath, JSON.stringify({ integrationBranch: "main" }, null, 2));
+
+      const detect = await runGSDDoctor(dir);
+      const missingBranchIssues = detect.issues.filter(i => i.code === "integration_branch_missing");
+      assertEq(missingBranchIssues.length, 0, "existing integration branch NOT flagged");
+    }
+    } else {
+      console.log("\n=== integration_branch_missing (no false positive — skipped on Windows) ===");
+    }
+
+    // ─── Test: Orphaned worktree directory ─────────────────────────────
+    if (process.platform !== "win32") {
+    console.log("\n=== worktree_directory_orphaned ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Create a worktrees/ dir with an entry that is NOT in git worktree list
+      const orphanDir = join(dir, ".gsd", "worktrees", "orphan-feature");
+      mkdirSync(orphanDir, { recursive: true });
+      writeFileSync(join(orphanDir, "some-file.txt"), "leftover content\n");
+
+      const detect = await runGSDDoctor(dir);
+      const orphanDirIssues = detect.issues.filter(i => i.code === "worktree_directory_orphaned");
+      assertTrue(orphanDirIssues.length > 0, "detects orphaned worktree directory");
+      assertTrue(
+        orphanDirIssues[0]?.message.includes("orphan-feature"),
+        "message includes the orphaned directory name",
+      );
+      assertTrue(orphanDirIssues[0]?.fixable === true, "worktree_directory_orphaned is fixable");
+
+      const fixed = await runGSDDoctor(dir, { fix: true });
+      assertTrue(
+        fixed.fixesApplied.some(f => f.includes("removed orphaned worktree directory")),
+        "fix removes orphaned worktree directory",
+      );
+      assertTrue(!existsSync(orphanDir), "orphaned directory removed after fix");
+    }
+    } else {
+      console.log("\n=== worktree_directory_orphaned (skipped on Windows) ===");
+    }
+
+    // ─── Test: Registered worktree NOT flagged as orphaned ─────────────
+    if (process.platform !== "win32") {
+    console.log("\n=== worktree_directory_orphaned (registered worktree not flagged) ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Create a real registered worktree under .gsd/worktrees/
+      mkdirSync(join(dir, ".gsd", "worktrees"), { recursive: true });
+      run("git worktree add -b worktree/feature-1 .gsd/worktrees/feature-1", dir);
+
+      const detect = await runGSDDoctor(dir);
+      const orphanDirIssues = detect.issues.filter(i => i.code === "worktree_directory_orphaned");
+      assertEq(orphanDirIssues.length, 0, "registered worktree NOT flagged as orphaned");
+    }
+    } else {
+      console.log("\n=== worktree_directory_orphaned (registered worktree not flagged — skipped on Windows) ===");
+    }
+
     // ─── Test 9: none-mode still detects corrupt merge state ───────────
     console.log("\n=== none-mode keeps corrupt merge state ===");
     {

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

@@ -2,9 +2,9 @@
  * doctor-runtime.test.ts — Tests for doctor runtime health checks.
  *
  * Tests detection and auto-fix of:
- *   stale_crash_lock, orphaned_completed_units, stale_hook_state,
- *   activity_log_bloat, state_file_missing, state_file_stale,
- *   gitignore_missing_patterns
+ *   stale_crash_lock, stranded_lock_directory, orphaned_completed_units,
+ *   stale_hook_state, activity_log_bloat, state_file_missing,
+ *   state_file_stale, gitignore_missing_patterns
  */
 
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync, realpathSync } from "node:fs";
@@ -290,6 +290,62 @@ node_modules/
       assertEq(content.length, 0, "all orphaned keys removed");
     }
 
+    // ─── Test: Stranded lock directory detection & fix ────────────────
+    // Skip on Windows: proper-lockfile uses advisory file locking on Windows,
+    // not the directory-based mechanism. The .gsd.lock/ directory pattern is
+    // a POSIX-specific lockfile implementation detail.
+    if (process.platform !== "win32") {
+    console.log("\n=== stranded_lock_directory ===");
+    {
+      const dir = createMinimalProject();
+      cleanups.push(dir);
+
+      // Create the proper-lockfile lock directory without a live lock holder.
+      // The lock dir sits at <parent of .gsd>/.gsd.lock (i.e., <basePath>/.gsd.lock).
+      const lockDir = join(dir, ".gsd.lock");
+      mkdirSync(lockDir, { recursive: true });
+
+      const detect = await runGSDDoctor(dir);
+      const strandedIssues = detect.issues.filter(i => i.code === "stranded_lock_directory");
+      assertTrue(strandedIssues.length > 0, "detects stranded lock directory");
+      assertTrue(strandedIssues[0]?.message.includes("lock directory"), "message describes stranded lock directory");
+      assertTrue(strandedIssues[0]?.fixable === true, "stranded lock dir is fixable");
+
+      const fixed = await runGSDDoctor(dir, { fix: true });
+      assertTrue(
+        fixed.fixesApplied.some(f => f.includes("removed stranded lock directory")),
+        "fix removes stranded lock directory",
+      );
+      assertTrue(!existsSync(lockDir), "lock directory removed after fix");
+    }
+
+    // ─── Test: Stranded lock dir with live lock holder — NOT flagged ───
+    console.log("\n=== stranded_lock_directory (live holder not flagged) ===");
+    {
+      const dir = createMinimalProject();
+      cleanups.push(dir);
+
+      // Create lock dir + auto.lock with PID 1 (init/launchd — always alive, never our own PID)
+      const lockDir = join(dir, ".gsd.lock");
+      mkdirSync(lockDir, { recursive: true });
+      const liveLockData = {
+        pid: 1,
+        startedAt: new Date().toISOString(),
+        unitType: "execute-task",
+        unitId: "M001/S01/T01",
+        unitStartedAt: new Date().toISOString(),
+        completedUnits: 1,
+      };
+      writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(liveLockData, null, 2));
+
+      const detect = await runGSDDoctor(dir);
+      const strandedIssues = detect.issues.filter(i => i.code === "stranded_lock_directory");
+      assertEq(strandedIssues.length, 0, "live lock holder: stranded_lock_directory NOT detected");
+    }
+    } else {
+      console.log("\n=== stranded_lock_directory (skipped on Windows) ===");
+    }
+
   } finally {
     for (const dir of cleanups) {
       try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }

package/src/resources/extensions/gsd/tests/files-loadfile-eisdir.test.ts

@@ -0,0 +1,20 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+import { loadFile } from "../files.ts";
+
+test("loadFile returns null for directory paths instead of throwing EISDIR", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-loadfile-eisdir-"));
+  const dirPath = path.join(tmp, "tasks");
+  fs.mkdirSync(dirPath);
+
+  try {
+    const result = await loadFile(dirPath);
+    assert.equal(result, null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});