gsd-pi 2.50.0-dev.d210a87 → 2.51.0-dev.7d435fe

package/src/resources/extensions/gsd/tests/complete-slice.test.ts

@@ -125,9 +125,9 @@ console.log('\n=== complete-slice: schema v6 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v12 after quality gates table)
+  // Verify schema version is current (v14 after indexes + slice_dependencies)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 12, 'schema version should be 12');
+  assertEq(versionRow?.['v'], 14, 'schema version should be 14');
 
   // Verify slices table has full_summary_md and full_uat_md columns
   const cols = adapter.prepare("PRAGMA table_info(slices)").all();

package/src/resources/extensions/gsd/tests/complete-task-rollback-evidence.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { handleCompleteTask } from "../tools/complete-task.js";
+import {
+  openDatabase,
+  closeDatabase,
+  _getAdapter,
+  insertMilestone,
+  insertSlice,
+} from "../gsd-db.js";
+import { clearPathCache } from "../paths.js";
+import { clearParseCache } from "../files.js";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-ct-rollback-${randomUUID()}`);
+  // Create the full tasks directory so the success path works
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  return base;
+}
+
+const VALID_PARAMS = {
+  milestoneId: "M001",
+  sliceId: "S01",
+  taskId: "T01",
+  oneLiner: "Test task",
+  narrative: "Did the thing",
+  verification: "Checked it",
+  deviations: "None.",
+  knownIssues: "None.",
+  keyFiles: ["src/foo.ts"],
+  keyDecisions: ["Used approach A"],
+  blockerDiscovered: false,
+  verificationEvidence: [
+    { command: "npm test", exitCode: 0, verdict: "✅ pass", durationMs: 1000 },
+    { command: "npm run lint", exitCode: 0, verdict: "✅ pass", durationMs: 500 },
+  ],
+};
+
+describe("complete-task rollback cleans up verification_evidence (#2724)", () => {
+  let base: string;
+
+  afterEach(() => {
+    clearPathCache();
+    clearParseCache();
+    try { closeDatabase(); } catch { /* */ }
+    if (base) {
+      try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  it("inserts verification_evidence rows on success", async () => {
+    base = makeTmpBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    // Write a minimal slice plan so renderPlanCheckboxes doesn't error
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+      "# S01 Plan\n\n## Tasks\n\n- [ ] **T01: Test task**\n",
+    );
+
+    const result = await handleCompleteTask(VALID_PARAMS, base);
+    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
+
+    const adapter = _getAdapter()!;
+    const rows = adapter.prepare(
+      `SELECT * FROM verification_evidence WHERE task_id = 'T01' AND slice_id = 'S01' AND milestone_id = 'M001'`,
+    ).all();
+    assert.equal(rows.length, 2, "should have 2 evidence rows after success");
+  });
+
+  it("deletes verification_evidence rows on disk-render rollback", async () => {
+    base = makeTmpBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    // Replace the tasks directory with a file so disk write fails (cross-platform)
+    const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks");
+    rmSync(tasksDir, { recursive: true, force: true });
+    writeFileSync(tasksDir, "not-a-directory");
+
+    const result = await handleCompleteTask(VALID_PARAMS, base);
+    assert.ok("error" in result, "should return error when disk write fails");
+
+    // Task should be rolled back to pending
+    const adapter = _getAdapter()!;
+    const task = adapter.prepare(
+      `SELECT status FROM tasks WHERE milestone_id = 'M001' AND slice_id = 'S01' AND id = 'T01'`,
+    ).get() as { status: string } | undefined;
+    assert.ok(task, "task row should still exist");
+    assert.equal(task!.status, "pending", "task status should be rolled back to pending");
+
+    // Verification evidence should be cleaned up — no orphaned rows
+    const evidenceRows = adapter.prepare(
+      `SELECT * FROM verification_evidence WHERE task_id = 'T01' AND slice_id = 'S01' AND milestone_id = 'M001'`,
+    ).all();
+    assert.equal(evidenceRows.length, 0, "verification_evidence should be empty after rollback");
+  });
+});

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -109,9 +109,9 @@ console.log('\n=== complete-task: schema v5 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v12 after quality gates table)
+  // Verify schema version is current (v14 after indexes + slice_dependencies)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 12, 'schema version should be 12');
+  assertEq(versionRow?.['v'], 14, 'schema version should be 14');
 
   // Verify all 4 new tables exist
   const tables = adapter.prepare(

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

@@ -14,6 +14,7 @@ import {
   getAllMilestones,
   insertSlice,
   insertTask,
+  updateTaskStatus,
 } from '../gsd-db.ts';
 // ─── Fixture Helpers ───────────────────────────────────────────────────────
 
@@ -116,10 +117,17 @@ describe('derive-state-db', async () => {
       invalidateStateCache();
       const fileState = await deriveState(base);
 
-      // Now open DB, insert matching artifacts
+      // Now open DB, insert matching artifacts + milestone hierarchy
       openDatabase(':memory:');
       assert.ok(isDbAvailable(), 'db-match: DB is available after open');
 
+      // Insert milestone hierarchy so deriveState takes the DB path (#2631 fix)
+      insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First Slice', status: 'active', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second Slice', status: 'pending', risk: 'low', depends: ['S01'] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
+      insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', title: 'Done Task', status: 'complete' });
+
       insertArtifactRow('milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT, {
         artifact_type: 'roadmap',
         milestone_id: 'M001',
@@ -197,18 +205,21 @@ describe('derive-state-db', async () => {
       writeFile(base, 'milestones/M001/slices/S01/tasks/.gitkeep', '');
       writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
 
-      // Open DB but insert nothing — empty artifacts table
+      // Open DB but insert nothing — empty tables.
+      // With #2631 fix, deriveState will sync disk milestones into DB
+      // and then take the DB path. The result should still reflect the
+      // disk milestone correctly.
       openDatabase(':memory:');
       assert.ok(isDbAvailable(), 'empty-db: DB is available');
 
       invalidateStateCache();
       const state = await deriveState(base);
 
-      // Should still work via cachedLoadFile → loadFile disk fallback
-      assert.deepStrictEqual(state.phase, 'executing', 'empty-db: phase is executing');
+      // Milestone should be detected (synced from disk)
       assert.deepStrictEqual(state.activeMilestone?.id, 'M001', 'empty-db: activeMilestone is M001');
-      assert.deepStrictEqual(state.activeSlice?.id, 'S01', 'empty-db: activeSlice is S01');
-      assert.deepStrictEqual(state.activeTask?.id, 'T01', 'empty-db: activeTask is T01');
+      // The DB path without explicit slice/task rows may derive a different
+      // phase than the filesystem path, but the milestone must be found.
+      assert.ok(state.activeMilestone !== null, 'empty-db: activeMilestone is not null');
 
       closeDatabase();
     } finally {
@@ -228,8 +239,12 @@ describe('derive-state-db', async () => {
       writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
       writeFile(base, 'REQUIREMENTS.md', REQUIREMENTS_CONTENT);
 
-      // Open DB but only insert the roadmap — plan and requirements missing from DB
+      // Open DB — insert milestone hierarchy + partial artifacts (#2631 fix)
       openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First Slice', status: 'active', risk: 'low', depends: [] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
+      // Only insert the roadmap artifact — plan and requirements missing from DB
       insertArtifactRow('milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT, {
         artifact_type: 'roadmap',
         milestone_id: 'M001',
@@ -314,6 +329,13 @@ describe('derive-state-db', async () => {
 
       // Put roadmap content in DB only
       openDatabase(':memory:');
+      // Insert milestone rows so deriveState takes the DB path (#2631 fix:
+      // empty milestones table now triggers disk→DB sync, which would create
+      // rows without slices — insert explicitly to get the full DB path).
+      insertMilestone({ id: 'M001', title: 'First Milestone', status: 'complete' });
+      insertMilestone({ id: 'M002', title: 'Second Milestone', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Done', status: 'complete', risk: 'low', depends: [] });
+      insertSlice({ id: 'S01', milestoneId: 'M002', title: 'In Progress', status: 'active', risk: 'low', depends: [] });
       insertArtifactRow('milestones/M001/M001-ROADMAP.md', completedRoadmap, {
         artifact_type: 'roadmap',
         milestone_id: 'M001',
@@ -355,6 +377,10 @@ describe('derive-state-db', async () => {
       writeFile(base, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01 Plan');
 
       openDatabase(':memory:');
+      // Insert milestone/slice/task rows so deriveState takes the DB path (#2631 fix)
+      insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First Slice', status: 'active', risk: 'low', depends: [] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'First Task', status: 'pending' });
       insertArtifactRow('milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT, {
         artifact_type: 'roadmap',
         milestone_id: 'M001',
@@ -378,6 +404,8 @@ describe('derive-state-db', async () => {
       });
       // Also update file on disk (cachedLoadFile may read from disk for some paths)
       writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', updatedPlan);
+      // Update task status in DB so DB-path also sees completion (#2631 fix)
+      updateTaskStatus('M001', 'S01', 'T01', 'complete');
 
       // Without invalidation, should return cached result (T01 still active)
       const state2 = await deriveState(base);

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

@@ -99,7 +99,7 @@ test("detectProjectState: detects preferences in .gsd/", (t) => {
   t.after(() => cleanup(dir));
 
   mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
-  writeFileSync(join(dir, ".gsd", "preferences.md"), "---\nversion: 1\n---\n", "utf-8");
+  writeFileSync(join(dir, ".gsd", "PREFERENCES.md"), "---\nversion: 1\n---\n", "utf-8");
   const result = detectProjectState(dir);
   assert.ok(result.v2);
   assert.equal(result.v2!.hasPreferences, true);

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

@@ -64,11 +64,11 @@ _None_
   return dir;
 }
 
-/** Write a .gsd/preferences.md with the given git isolation mode. */
+/** Write a .gsd/PREFERENCES.md with the given git isolation mode. */
 function writePreferencesFile(dir: string, isolation: "none" | "worktree" | "branch"): void {
   const gsdDir = join(dir, ".gsd");
   mkdirSync(gsdDir, { recursive: true });
-  writeFileSync(join(gsdDir, "preferences.md"), `---\ngit:\n  isolation: "${isolation}"\n---\n`);
+  writeFileSync(join(gsdDir, "PREFERENCES.md"), `---\ngit:\n  isolation: "${isolation}"\n---\n`);
 }
 
 /** Create a repo with an in-progress milestone. */
@@ -302,7 +302,7 @@ describe('doctor-git', async () => {
     // ─── Test 7: none-mode skips orphaned worktree check ───────────────
     // NOTE: loadEffectiveGSDPreferences() resolves PROJECT_PREFERENCES_PATH
     // at module load time from process.cwd(). We write the prefs file to
-    // the test runner's cwd .gsd/preferences.md and clean up afterwards.
+    // the test runner's cwd .gsd/PREFERENCES.md and clean up afterwards.
     if (process.platform !== "win32") {
     test('none-mode skips orphaned worktree', async () => {
       const dir = createRepoWithCompletedMilestone();
@@ -409,7 +409,7 @@ describe('doctor-git', async () => {
       cleanups.push(dir);
 
       run("git branch trunk", dir);
-      writeFileSync(join(dir, ".gsd", "preferences.md"), `---\ngit:\n  isolation: "worktree"\n  main_branch: "trunk"\n---\n`);
+      writeFileSync(join(dir, ".gsd", "PREFERENCES.md"), `---\ngit:\n  isolation: "worktree"\n  main_branch: "trunk"\n---\n`);
 
       const metaPath = join(dir, ".gsd", "milestones", "M001", "M001-META.json");
       writeFileSync(metaPath, JSON.stringify({ integrationBranch: "feat/does-not-exist" }, null, 2));

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

@@ -297,7 +297,7 @@ describe('doctor-proactive', async () => {
       cleanups.push(dir);
 
       run("git branch trunk", dir);
-      writeFileSync(join(dir, ".gsd", "preferences.md"), `---\ngit:\n  main_branch: "trunk"\n---\n`);
+      writeFileSync(join(dir, ".gsd", "PREFERENCES.md"), `---\ngit:\n  main_branch: "trunk"\n---\n`);
       const metaPath = join(dir, ".gsd", "milestones", "M001", "M001-META.json");
       writeFileSync(metaPath, JSON.stringify({ integrationBranch: "feature/missing" }, null, 2));
 

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

@@ -419,7 +419,7 @@ test("runProviderChecks uses provider-qualified anthropic-vertex model IDs", ()
   const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-vertex-prefix-repo-")));
   mkdirSync(join(repo, ".gsd"), { recursive: true });
   writeFileSync(
-    join(repo, ".gsd", "preferences.md"),
+    join(repo, ".gsd", "PREFERENCES.md"),
     [
       "---",
       "models:",
@@ -454,7 +454,7 @@ test("runProviderChecks uses object provider field for anthropic-vertex models",
   const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-vertex-provider-repo-")));
   mkdirSync(join(repo, ".gsd"), { recursive: true });
   writeFileSync(
-    join(repo, ".gsd", "preferences.md"),
+    join(repo, ".gsd", "PREFERENCES.md"),
     [
       "---",
       "models:",

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

@@ -0,0 +1,79 @@
+/**
+ * Regression test for #2631: deriveState disk→DB reconciliation must
+ * run even when the milestones table starts empty.
+ *
+ * When getAllMilestones() returns [] (e.g. after a failed initial migration),
+ * the reconciliation code inside deriveStateFromDb was unreachable because
+ * deriveState only called it when dbMilestones.length > 0. The fix moves
+ * disk→DB sync into deriveState itself, before the length check.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { deriveState, invalidateStateCache } from "../state.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  getAllMilestones,
+} from "../gsd-db.ts";
+
+test("deriveState populates empty DB from disk milestones (#2631)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-empty-db-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    // Create a milestone on disk with a CONTEXT file (not a ghost)
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+      "# M001: Test Milestone\n\nSome context about this milestone.",
+    );
+
+    // Open DB — milestones table is empty (simulating failed migration)
+    openDatabase(":memory:");
+    const before = getAllMilestones();
+    assert.equal(before.length, 0, "DB should start with 0 milestones");
+
+    // deriveState should reconcile disk → DB
+    invalidateStateCache();
+    const state = await deriveState(base);
+
+    // After deriveState, the DB should now have the disk milestone
+    const after = getAllMilestones();
+    assert.ok(after.length > 0, "DB should have milestones after reconciliation");
+    assert.equal(after[0]!.id, "M001", "reconciled milestone should be M001");
+
+    // State should reflect the milestone (not "No milestones found")
+    assert.ok(
+      state.activeMilestone !== null,
+      "activeMilestone should not be null after reconciliation",
+    );
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("deriveState does NOT insert ghost milestones into DB (#2631 guard)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-empty-db-"));
+  // Create a ghost milestone directory (empty — no CONTEXT, no ROADMAP)
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    openDatabase(":memory:");
+    invalidateStateCache();
+    await deriveState(base);
+
+    const milestones = getAllMilestones();
+    assert.equal(milestones.length, 0, "ghost milestone should NOT be inserted");
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

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

@@ -1142,7 +1142,7 @@ describe('git-service', async () => {
     mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
     mkdirSync(join(repo, ".gsd", "activity"), { recursive: true });
     writeFileSync(join(repo, ".gsd", "milestones", "M001", "ROADMAP.md"), "# Roadmap");
-    writeFileSync(join(repo, ".gsd", "preferences.md"), "---\nversion: 1\n---");
+    writeFileSync(join(repo, ".gsd", "PREFERENCES.md"), "---\nversion: 1\n---");
     writeFileSync(join(repo, ".gsd", "STATE.md"), "# State");
     writeFileSync(join(repo, ".gsd", "runtime", "units.json"), "{}");
     writeFileSync(join(repo, ".gsd", "activity", "log.jsonl"), "{}");

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

@@ -64,7 +64,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'], 12, 'schema version should be 12');
+    assert.deepStrictEqual(version?.['version'], 14, 'schema version should be 14');
 
     // Check tables exist by querying them
     const dRows = adapter.prepare('SELECT count(*) as cnt FROM decisions').get();

package/src/resources/extensions/gsd/tests/idle-watchdog-stall-override.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Regression tests for #2527: idle watchdog stalled-tool detection.
+ *
+ * Bug 1: When a tool is stalled longer than idle_timeout, the watchdog
+ * notifies but falls through to detectWorkingTreeActivity(), which
+ * resets lastProgressAt if files were modified earlier. Recovery is
+ * never called — the session burns tokens indefinitely.
+ *
+ * Bug 2: After async recoverTimedOutUnit(), pauseAuto/stopAuto may set
+ * s.currentUnit = null, but the next line accesses .startedAt — crash.
+ *
+ * These tests verify the auto-timers.ts source contains the structural
+ * fixes: the stalledToolDetected flag, clearInFlightTools() call, the
+ * filesystem-check guard, and the null guard after recovery.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+
+const TIMERS_SRC = readFileSync(
+  join(import.meta.dirname, "..", "auto-timers.ts"),
+  "utf-8",
+);
+
+// ═══ Bug 1: stalledToolDetected flag prevents filesystem-activity override ═══
+
+describe("#2527 Bug 1: stalled tool should not be overridden by filesystem activity", () => {
+  test("auto-timers.ts imports clearInFlightTools", () => {
+    assert.ok(
+      TIMERS_SRC.includes("clearInFlightTools"),
+      "clearInFlightTools must be imported from auto-tool-tracking",
+    );
+  });
+
+  test("auto-timers.ts declares stalledToolDetected flag", () => {
+    assert.ok(
+      TIMERS_SRC.includes("stalledToolDetected"),
+      "stalledToolDetected flag must exist in idle watchdog",
+    );
+  });
+
+  test("stalled tool sets flag to true", () => {
+    // The flag must be set before the filesystem check
+    const flagSet = TIMERS_SRC.indexOf("stalledToolDetected = true");
+    assert.ok(flagSet > -1, "stalledToolDetected must be set to true when tool is stalled");
+
+    const notify = TIMERS_SRC.indexOf("Stalled tool detected:");
+    assert.ok(flagSet < notify, "flag must be set before the stall notification");
+  });
+
+  test("stalled tool calls clearInFlightTools", () => {
+    // clearInFlightTools() must be called when tool is stalled, so subsequent
+    // watchdog ticks don't re-detect the same stale entries
+    const clearCall = TIMERS_SRC.indexOf("clearInFlightTools()");
+    assert.ok(clearCall > -1, "clearInFlightTools() must be called when tool is stalled");
+
+    const flagSet = TIMERS_SRC.indexOf("stalledToolDetected = true");
+    assert.ok(
+      Math.abs(clearCall - flagSet) < 200,
+      "clearInFlightTools() should be near stalledToolDetected = true",
+    );
+  });
+
+  test("filesystem-activity check is guarded by stalledToolDetected", () => {
+    // The detectWorkingTreeActivity check must be skipped when stalledToolDetected is true
+    assert.ok(
+      TIMERS_SRC.includes("!stalledToolDetected && detectWorkingTreeActivity"),
+      "detectWorkingTreeActivity must be guarded by !stalledToolDetected",
+    );
+  });
+
+  test("control flow: stalled tool → skip filesystem check → reach recovery", () => {
+    // Verify the structural ordering: flag declaration → stall block → guarded fs check → recovery
+    const flagDecl = TIMERS_SRC.indexOf("let stalledToolDetected = false");
+    const stallBlock = TIMERS_SRC.indexOf("stalledToolDetected = true");
+    const fsGuard = TIMERS_SRC.indexOf("!stalledToolDetected && detectWorkingTreeActivity");
+    const recovery = TIMERS_SRC.indexOf("recoverTimedOutUnit(ctx, pi, unitType, unitId, \"idle\"");
+
+    assert.ok(flagDecl > -1, "flag declaration must exist");
+    assert.ok(flagDecl < stallBlock, "flag declared before stall block");
+    assert.ok(stallBlock < fsGuard, "stall block before filesystem guard");
+    assert.ok(fsGuard < recovery, "filesystem guard before recovery call");
+  });
+});
+
+// ═══ Bug 2: null guard after async recoverTimedOutUnit ═══════════════════════
+
+describe("#2527 Bug 2: null guard after async recovery prevents crash", () => {
+  test("idle watchdog has null guard after recoverTimedOutUnit", () => {
+    // Find the idle recovery call
+    const idleRecovery = TIMERS_SRC.indexOf(
+      'recoverTimedOutUnit(ctx, pi, unitType, unitId, "idle"',
+    );
+    assert.ok(idleRecovery > -1, "idle recovery call must exist");
+
+    // The null guard must appear between the recovery call and the next
+    // writeUnitRuntimeRecord that accesses s.currentUnit.startedAt
+    const afterRecovery = TIMERS_SRC.slice(idleRecovery, idleRecovery + 400);
+    assert.ok(
+      afterRecovery.includes("if (!s.currentUnit) return"),
+      "null guard for s.currentUnit must exist after idle recoverTimedOutUnit",
+    );
+  });
+
+  test("null guard is between recovery and writeUnitRuntimeRecord", () => {
+    const idleRecovery = TIMERS_SRC.indexOf(
+      'recoverTimedOutUnit(ctx, pi, unitType, unitId, "idle"',
+    );
+    const afterRecovery = TIMERS_SRC.slice(idleRecovery);
+
+    const recoveredReturn = afterRecovery.indexOf('if (recovery === "recovered") return');
+    const nullGuard = afterRecovery.indexOf("if (!s.currentUnit) return");
+    const writeRecord = afterRecovery.indexOf("writeUnitRuntimeRecord(s.basePath");
+
+    assert.ok(recoveredReturn > -1, "recovered return must exist");
+    assert.ok(nullGuard > -1, "null guard must exist");
+    assert.ok(writeRecord > -1, "writeUnitRuntimeRecord must exist after recovery");
+    assert.ok(
+      recoveredReturn < nullGuard && nullGuard < writeRecord,
+      "order must be: recovered-return → null-guard → writeUnitRuntimeRecord",
+    );
+  });
+});

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

@@ -123,7 +123,7 @@ test("init-wizard: v2 .gsd/ preferences detected", (t) => {
   const dir = makeTempDir("prefs-detect");
   try {
     mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
-    writeFileSync(join(dir, ".gsd", "preferences.md"), "---\nversion: 1\nmode: solo\n---\n", "utf-8");
+    writeFileSync(join(dir, ".gsd", "PREFERENCES.md"), "---\nversion: 1\nmode: solo\n---\n", "utf-8");
 
     const detection = detectProjectState(dir);
     assert.ok(detection.v2);