@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

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

@@ -0,0 +1,66 @@
+// gsd-pi — DB writability probe regression tests (#1234).
+//
+// Auto-start's DB gate only checked that the provider opened, not that the
+// handle can actually write. A schema-current DB does zero writes during open,
+// so a read-only / DBMOVED handle passed the open-only check and failed much
+// later at the first authoritative write with an opaque "readonly database"
+// error. `probeDbWritable` forces a real page write so that failure class is
+// caught at the natural checkpoint.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { openDatabase, closeDatabase, probeDbWritable, _getAdapter } from "../gsd-db.ts";
+import type { DbAdapter } from "../db-adapter.ts";
+
+function makeBase(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-db-writable-probe-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+test("probeDbWritable succeeds against a freshly opened writable database", () => {
+  const base = makeBase();
+  assert.equal(openDatabase(join(base, ".gsd", "gsd.db")), true);
+  try {
+    assert.deepEqual(probeDbWritable(), { ok: true });
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("probeDbWritable reports not-ok with detail when no database is open", () => {
+  closeDatabase();
+  const result = probeDbWritable();
+  assert.equal(result.ok, false);
+  assert.match(result.detail ?? "", /No database is open/u);
+});
+
+test("probeDbWritable reports not-ok when the page write fails (simulating a read-only handle)", () => {
+  const base = makeBase();
+  assert.equal(openDatabase(join(base, ".gsd", "gsd.db")), true);
+  const adapter = _getAdapter() as DbAdapter;
+  assert.ok(adapter);
+
+  // The read (prepare/get) still works; only the page-dirtying write throws,
+  // mirroring SQLITE_READONLY_DBMOVED which fails once a page is dirtied.
+  const origExec = adapter.exec.bind(adapter);
+  adapter.exec = (sql: string): void => {
+    if (sql.includes("user_version =")) throw new Error("attempt to write a readonly database");
+    return origExec(sql);
+  };
+
+  try {
+    const result = probeDbWritable();
+    assert.equal(result.ok, false);
+    assert.match(result.detail ?? "", /readonly database/u);
+  } finally {
+    adapter.exec = origExec;
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/flat-phase-migration.test.ts

@@ -109,6 +109,33 @@ test("migrateToFlatPhase creates a backup", async () => {
   assert.ok(backups.length >= 1, "at least one migrate-* backup dir should exist");
 });
 
+test("failed migration rolls back without leaking a .gsd-backups/migrate-* dir", async (t) => {
+  const base = makeTmp();
+  const milestonesPath = join(base, ".gsd", "milestones");
+  const phasesPath = join(base, ".gsd", "phases");
+
+  // Fail the pre-render clear of phases/ to drive the rollback path, which by
+  // this point has already created the .gsd-backups/migrate-<ts>/ backup.
+  const restoreFsOps = _setFlatPhaseMigrationFsOpsForTest({
+    rmSync(target, opts) {
+      if (target === phasesPath) {
+        throw Object.assign(new Error("simulated locked phases/"), { code: "EPERM" });
+      }
+      return rmSync(target, opts as never);
+    },
+  });
+  t.after(restoreFsOps);
+
+  await assert.rejects(migrateToFlatPhase(base), /simulated locked/);
+
+  assert.ok(existsSync(milestonesPath), "legacy milestones/ should be restored on rollback");
+  const backupRoot = join(base, ".gsd-backups");
+  const leaked = existsSync(backupRoot)
+    ? readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"))
+    : [];
+  assert.equal(leaked.length, 0, "rollback must delete the migrate-* backup it created");
+});
+
 test("migrateToFlatPhase preserves milestone/slice/task counts in DB", async () => {
   const base = makeTmp();
   const msBefore = getAllMilestones().length;

package/src/resources/extensions/gsd/tests/flat-phase-renderer.test.ts

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
-import { renderPlanFromDb, renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.ts";
+import { renderPlanFromDb, renderRoadmapFromDb, renderAssessmentFromDb, renderReplanFromDb } from "../markdown-renderer.ts";
 import { clearPathCache } from "../paths.ts";
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
 
@@ -83,6 +83,27 @@ test("renderPlanFromDb does NOT write per-task plan files", async () => {
   assert.equal(result.taskPlanPaths.length, 0);
 });
 
+
+// Replan uses the same slice-level target rules as assessment: flat-phase
+// writes must stay at the phase root even if an old slices/SID/ dir exists.
+test("renderReplanFromDb writes to the phase root even when a stray slices/SID/ dir exists", async () => {
+  const base = makeTmp();
+  const plan = await renderPlanFromDb(base, "M001", "S01");
+  const phaseDir = plan.planPath.slice(0, plan.planPath.lastIndexOf("01-01-PLAN.md"));
+  mkdirSync(join(phaseDir, "slices", "S01"), { recursive: true });
+  clearPathCache();
+
+  const result = await renderReplanFromDb(base, "M001", "S01", {
+    blockerTaskId: "T01",
+    blockerDescription: "Need a better path target.",
+    whatChanged: "Centralized slice writer path resolution.",
+  });
+
+  assert.match(result.replanPath, /phases[/\\]01-[^/\\]+[/\\]01-01-REPLAN\.md$/);
+  assert.ok(!result.replanPath.includes(join("slices", "S01")), "must not write under slices/S01/");
+  assert.ok(existsSync(result.replanPath), "replan file should exist at the phase root");
+});
+
 // Regression for #1190: a stray slices/SID/ subdir inside a flat-phase milestone
 // must not divert the ASSESSMENT write into slices/SID/ (a hybrid path that
 // auto-mode verification cannot find). It must land at the phase root.

package/src/resources/extensions/gsd/tests/flat-phase-validation-path.test.ts

@@ -9,7 +9,7 @@ import { join } from "node:path";
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { relMilestoneFile, resolveMilestoneFile } from "../paths.ts";
+import { normalizeRealPath, relMilestoneFile, relSliceFile, resolveMilestoneFile, targetMilestoneFile } from "../paths.ts";
 
 function makeFlatPhaseFixture(): { basePath: string; cleanup: () => void } {
   const basePath = mkdtempSync(join(tmpdir(), "flat-phase-validation-"));
@@ -33,42 +33,82 @@ function makeFlatPhaseFixture(): { basePath: string; cleanup: () => void } {
   return { basePath, cleanup: () => rmSync(basePath, { recursive: true, force: true }) };
 }
 
-test("flat-phase: relMilestoneFile resolves to the layout-aware path", () => {
+test("flat-phase: relMilestoneFile resolves to the layout-aware path", (t) => {
   const { basePath, cleanup } = makeFlatPhaseFixture();
-  try {
-    const rel = relMilestoneFile(basePath, "M001", "VALIDATION");
-    assert.equal(rel, ".gsd/phases/01-foo/01-VALIDATION.md");
-    const abs = join(basePath, rel);
-    assert.equal(existsSync(abs), true);
-  } finally {
-    cleanup();
-  }
+  t.after(cleanup);
+
+  const rel = relMilestoneFile(basePath, "M001", "VALIDATION");
+  assert.equal(rel, ".gsd/phases/01-foo/01-VALIDATION.md");
+  const abs = join(basePath, rel);
+  assert.equal(existsSync(abs), true);
+});
+
+test("flat-phase: relMilestoneFile fallback uses the milestone title when no directory exists", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "flat-phase-missing-dir-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+
+  const rel = relMilestoneFile(basePath, "M001", "ROADMAP", "Milestone");
+  assert.equal(rel, ".gsd/phases/01-milestone/01-ROADMAP.md");
 });
 
-test("flat-phase: resolveMilestoneFile finds the on-disk file", () => {
+test("legacy layout: relMilestoneFile fallback stays in milestones when the target dir is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "legacy-missing-dir-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  const existingLegacyDir = join(basePath, ".gsd", "milestones", "M002");
+  mkdirSync(existingLegacyDir, { recursive: true });
+  writeFileSync(join(existingLegacyDir, "M002-ROADMAP.md"), "# existing legacy roadmap\n");
+
+  const rel = relMilestoneFile(basePath, "M001", "ROADMAP", "Milestone");
+
+  assert.equal(rel, ".gsd/milestones/M001/M001-ROADMAP.md");
+});
+
+test("legacy layout: relSliceFile fallback uses slices directory when target milestone is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "legacy-missing-slice-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  const existingLegacyDir = join(basePath, ".gsd", "milestones", "M002");
+  mkdirSync(existingLegacyDir, { recursive: true });
+  writeFileSync(join(existingLegacyDir, "M002-ROADMAP.md"), "# existing legacy roadmap\n");
+
+  const rel = relSliceFile(basePath, "M001", "S01", "PLAN", "Milestone");
+
+  assert.equal(rel, ".gsd/milestones/M001/slices/S01/S01-PLAN.md");
+});
+
+test("flat-phase: targetMilestoneFile ignores legacy-named compatibility files when writing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "flat-phase-legacy-named-file-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  const phaseDir = join(basePath, ".gsd", "phases", "01-foo");
+  mkdirSync(phaseDir, { recursive: true });
+  writeFileSync(join(phaseDir, "M001-ROADMAP.md"), "# legacy named roadmap\n");
+
+  assert.equal(
+    targetMilestoneFile(basePath, "M001", "ROADMAP", "Foo"),
+    join(normalizeRealPath(phaseDir), "01-ROADMAP.md"),
+  );
+  assert.equal(relMilestoneFile(basePath, "M001", "ROADMAP", "Foo"), ".gsd/phases/01-foo/M001-ROADMAP.md");
+});
+
+test("flat-phase: resolveMilestoneFile finds the on-disk file", (t) => {
   const { basePath, cleanup } = makeFlatPhaseFixture();
-  try {
-    const abs = resolveMilestoneFile(basePath, "M001", "VALIDATION");
-    assert.ok(abs, "resolveMilestoneFile must return a path for the flat-phase fixture");
-    assert.equal(abs!.endsWith("/.gsd/phases/01-foo/01-VALIDATION.md"), true);
-    assert.equal(existsSync(abs!), true);
-  } finally {
-    cleanup();
-  }
+  t.after(cleanup);
+
+  const abs = resolveMilestoneFile(basePath, "M001", "VALIDATION");
+  assert.ok(abs, "resolveMilestoneFile must return a path for the flat-phase fixture");
+  assert.equal(abs!.endsWith("/.gsd/phases/01-foo/01-VALIDATION.md"), true);
+  assert.equal(existsSync(abs!), true);
 });
 
-test("flat-phase: the legacy hardcoded path does NOT resolve (regression for #876)", () => {
+test("flat-phase: the legacy hardcoded path does NOT resolve (regression for #876)", (t) => {
   const { basePath, cleanup } = makeFlatPhaseFixture();
-  try {
-    // This is the path that auto-verification.ts:264-270 used to construct.
-    // It must NOT exist on a flat-phase project — that's the whole bug.
-    const legacyHardcoded = join(basePath, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
-    assert.equal(
-      existsSync(legacyHardcoded),
-      false,
-      "legacy hardcoded path must not exist in flat-phase fixture — if it does, the test fixture is wrong",
-    );
-  } finally {
-    cleanup();
-  }
+  t.after(cleanup);
+
+  // This is the path that auto-verification.ts:264-270 used to construct.
+  // It must NOT exist on a flat-phase project — that's the whole bug.
+  const legacyHardcoded = join(basePath, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+  assert.equal(
+    existsSync(legacyHardcoded),
+    false,
+    "legacy hardcoded path must not exist in flat-phase fixture — if it does, the test fixture is wrong",
+  );
 });

package/src/resources/extensions/gsd/tests/import-completion-lost-update.test.ts

@@ -0,0 +1,196 @@
+// Project/App: gsd-pi
+// File Purpose: Regression for #1222 — a re-import must not silently downgrade
+// a completed flat-phase task back to pending when its SUMMARY.md attests the
+// completion. gsd_task_complete succeeds and writes TID-SUMMARY.md, but a stale
+// plan checkbox re-imported into the DB would revert the task to pending,
+// hard-stopping auto-mode on its "state did not advance" guard.
+
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, mkdtempSync, rmSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import { openDatabase, closeDatabase, getAllMilestones, getMilestoneSlices, getSliceTasks, repairTaskCompletionFromSummary } from "../gsd-db.ts";
+import { migrateHierarchyToDb } from "../md-importer.ts";
+import { invalidateStateCache } from "../state.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_ROOT = join(__dirname, "__fixtures__", "flat-phase");
+// The flat-phase fixture parses to M001/S01/T01 (phase 01, plan 01, task T01).
+const PHASE_DIR = join(".gsd", "phases", "01-foundation");
+const SUMMARY_REL = join(PHASE_DIR, "T01-SUMMARY.md");
+
+const tmpDirs: string[] = [];
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+function copyFixture(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-lostupdate-${randomUUID()}`));
+  cpSync(FIXTURE_ROOT, base, { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+function taskStatus(base: string): string | undefined {
+  return t01Row()?.status;
+}
+
+function t01Row() {
+  const ms = getAllMilestones();
+  if (ms.length === 0) return undefined;
+  const slices = getMilestoneSlices(ms[0]!.id);
+  if (slices.length === 0) return undefined;
+  const tasks = getSliceTasks(ms[0]!.id, slices[0]!.id);
+  return tasks.find((t) => t.id === "T01");
+}
+
+function t01Ids() {
+  const ms = getAllMilestones();
+  const slices = getMilestoneSlices(ms[0]!.id);
+  return { milestoneId: ms[0]!.id, sliceId: slices[0]!.id };
+}
+
+test("re-import keeps a flat-phase task complete when its SUMMARY.md is present (#1222)", () => {
+  const base = copyFixture();
+  // The fixture plan leaves T01 unchecked ([ ]). Simulate a completed task: the
+  // durable SUMMARY.md exists even though the plan checkbox is stale-unchecked.
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  assert.equal(
+    taskStatus(base),
+    "complete",
+    "task with SUMMARY.md on disk must import as complete, not revert to pending",
+  );
+});
+
+test("re-import leaves an unchecked flat-phase task pending when no SUMMARY.md exists (#1222)", () => {
+  const base = copyFixture();
+  // No SUMMARY.md — the unchecked checkbox is the authoritative signal.
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  assert.equal(
+    taskStatus(base),
+    "pending",
+    "unchecked task without a SUMMARY.md must stay pending",
+  );
+});
+
+test("re-import keeps a flat-phase task complete even when an auxiliary tasks/ subdir exists (#1222)", () => {
+  const base = copyFixture();
+  // Flat-phase may keep a tasks/ subdir for gate artifacts (e.g. T01-VERIFY.json)
+  // while gsd_task_complete still writes TID-SUMMARY.md at the phase root. The
+  // tasks/ subdir must NOT shadow that real summary and downgrade the task.
+  mkdirSync(join(base, PHASE_DIR, "tasks"), { recursive: true });
+  writeFileSync(join(base, PHASE_DIR, "tasks", "T01-VERIFY.json"), "{}\n");
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  assert.equal(
+    taskStatus(base),
+    "complete",
+    "a phase-root SUMMARY.md must win even when a tasks/ subdir exists (no shadowing)",
+  );
+});
+
+test("re-import preserves execution metadata and completed_at of an attested-complete task (#1222)", () => {
+  const base = copyFixture();
+  // T01 is completed on disk (SUMMARY present) but its plan checkbox is stale-unchecked.
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  // Simulate the row gsd_task_complete leaves behind: real execution prose plus
+  // a completion timestamp from when the task actually finished.
+  const OLD_COMPLETED_AT = "2026-07-01T00:00:00.000Z";
+  const REAL_ONE_LINER = "Implemented the widget frobnicator end-to-end";
+  const REAL_SUMMARY = "# T01 full summary\n\nEverything about how T01 was done.";
+  const REAL_VERIFICATION = "all 12 checks passed";
+  const { milestoneId, sliceId } = t01Ids();
+  repairTaskCompletionFromSummary({
+    milestoneId,
+    sliceId,
+    taskId: "T01",
+    oneLiner: REAL_ONE_LINER,
+    verificationResult: REAL_VERIFICATION,
+    completedAt: OLD_COMPLETED_AT,
+    fullSummaryMd: REAL_SUMMARY,
+  });
+  invalidateStateCache();
+
+  const before = t01Row()!;
+  assert.equal(before.status, "complete", "precondition: T01 is complete");
+  assert.equal(before.one_liner, REAL_ONE_LINER, "precondition: one_liner set");
+  assert.equal(before.completed_at, OLD_COMPLETED_AT, "precondition: completed_at set");
+
+  // The pre-dispatch reconcile re-imports the whole tree (plan checkbox still [ ]).
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+
+  const after = t01Row()!;
+  assert.equal(after.status, "complete", "status must survive re-import");
+  assert.equal(after.one_liner, REAL_ONE_LINER, "one_liner must survive re-import");
+  assert.equal(after.full_summary_md, REAL_SUMMARY, "full_summary_md must survive re-import");
+  assert.equal(after.verification_result, REAL_VERIFICATION, "verification_result must survive re-import");
+  assert.equal(after.completed_at, OLD_COMPLETED_AT, "completed_at must not be refreshed by re-import");
+});
+
+test("removing the SUMMARY.md (reopen) lets a re-import return the task to pending and clears completion metadata (#1222)", () => {
+  const base = copyFixture();
+  writeFileSync(join(base, SUMMARY_REL), "# T01 SUMMARY\n\nDone.\n");
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  assert.equal(taskStatus(base), "complete", "precondition: task imports complete with SUMMARY present");
+
+  // Simulate the durable completion row gsd_task_complete leaves behind.
+  const { milestoneId, sliceId } = t01Ids();
+  repairTaskCompletionFromSummary({
+    milestoneId,
+    sliceId,
+    taskId: "T01",
+    oneLiner: "Implemented the widget frobnicator end-to-end",
+    verificationResult: "all 12 checks passed",
+    completedAt: "2026-07-01T00:00:00.000Z",
+    fullSummaryMd: "# T01 full summary\n\nEverything about how T01 was done.",
+  });
+  invalidateStateCache();
+  const before = t01Row()!;
+  assert.equal(before.status, "complete", "precondition: T01 is complete");
+  assert.equal(before.completed_at, "2026-07-01T00:00:00.000Z", "precondition: completed_at set");
+
+  // reopen-task deletes the flat-phase SUMMARY; the next re-import must respect it.
+  unlinkSync(join(base, SUMMARY_REL));
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  const after = t01Row()!;
+  assert.equal(
+    after.status,
+    "pending",
+    "after the SUMMARY is removed, a re-import must return the unchecked task to pending",
+  );
+  // A pending re-import must not preserve stale completion metadata (#1228 thread):
+  // preserveCompletionMetadata only applies to complete/done imports.
+  assert.ok(!after.completed_at, "completed_at must be cleared when the task reverts to pending");
+  assert.ok(!after.one_liner, "one_liner must be cleared when the task reverts to pending");
+  assert.ok(!after.full_summary_md, "full_summary_md must be cleared when the task reverts to pending");
+  assert.ok(!after.verification_result, "verification_result must be cleared when the task reverts to pending");
+});

package/src/resources/extensions/gsd/tests/integration/paths.test.ts

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, realpathSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
@@ -9,6 +9,7 @@ import {
   gsdProjectionRoot,
   gsdRoot,
   milestonesDir,
+  resolveGsdPathContract,
   resolveSliceFile,
   resolveTaskFile,
   _clearGsdRootCache,
@@ -166,4 +167,90 @@ describe('paths', () => {
       cleanup(root);
     }
   });
+
+  test('Case 9: flat-phase task SUMMARY resolves at phase root despite a stray slices/SID/ dir', () => {
+    const root = tmp();
+    try {
+      // Hybrid flat-phase milestone: phase dir holds flat TID-SUMMARY.md, but a
+      // stray slices/S01/ folder also exists on disk. resolveSlicePath then points
+      // under slices/, so layout (phases/ vs milestones/) — not slicePath===phaseDir
+      // — must decide the flat-phase task summary location.
+      const phaseDir = join(root, ".gsd", "phases", "01-foo");
+      mkdirSync(join(phaseDir, "slices", "S01"), { recursive: true });
+      const flatSummary = join(phaseDir, "T01-SUMMARY.md");
+      writeFileSync(flatSummary, "# task summary\n");
+
+      _clearGsdRootCache();
+
+      assert.deepStrictEqual(
+        resolveTaskFile(root, "M001", "S01", "T01", "SUMMARY"),
+        flatSummary,
+        "flat-phase TID-SUMMARY.md at phase root is found even when slices/S01/ exists",
+      );
+    } finally { cleanup(root); }
+  });
+
+  test('Case 10: resolveGsdPathContract canonicalizes a symlinked .gsd root (regression #1239)', () => {
+    // WSL / external-state shape: `<projectRoot>/.gsd` is a symlink pointing at a
+    // real directory on another volume. Before #1239 the DB path was built from
+    // the unresolved symlink, so the workflow SQLite handle opened through a
+    // move-prone path and could pick the wrong journal mode / SQLITE_READONLY_DBMOVED.
+    const root = tmp();
+    try {
+      const realState = join(root, "real-state"); // canonical symlink target
+      mkdirSync(join(realState, "milestones"), { recursive: true });
+      const projectRoot = join(root, "project");
+      mkdirSync(projectRoot, { recursive: true });
+      symlinkSync(realState, join(projectRoot, ".gsd"), "dir");
+
+      _clearGsdRootCache();
+      const contract = resolveGsdPathContract(projectRoot);
+
+      const canonicalGsd = realpathSync.native(join(projectRoot, ".gsd"));
+      assert.deepStrictEqual(contract.projectGsd, canonicalGsd,
+        "projectGsd is the realpath'd target, not the unresolved .gsd symlink");
+      assert.deepStrictEqual(contract.projectDb, join(canonicalGsd, "gsd.db"),
+        "projectDb is built from the canonical .gsd root");
+      assert.deepStrictEqual(contract.projectGsd, gsdProjectionRoot(projectRoot),
+        "projectGsd agrees with gsdProjectionRoot on the canonical root");
+      assert.notStrictEqual(contract.projectDb, join(projectRoot, ".gsd", "gsd.db"),
+        "regression #1239: DB must not open through the unresolved .gsd symlink");
+    } finally { cleanup(root); }
+  });
+
+  test('Case 11: resolveGsdPathContract canonicalizes the external-state worktree DB path through a symlinked store (regression #1239)', () => {
+    const root = tmp();
+    const originalStateDir = process.env.GSD_STATE_DIR;
+    try {
+      const stateDir = join(root, "state");
+      process.env.GSD_STATE_DIR = stateDir;
+
+      // The external-state project store `<state>/projects/<hash>` is itself a
+      // symlink to a real directory on another volume (the WSL `.gsd` shape).
+      const realProjectGsd = join(root, "real-projects", "abc123");
+      mkdirSync(realProjectGsd, { recursive: true });
+      mkdirSync(join(stateDir, "projects"), { recursive: true });
+      const storeSymlink = join(stateDir, "projects", "abc123");
+      symlinkSync(realProjectGsd, storeSymlink, "dir");
+
+      const wtRoot = join(storeSymlink, "worktrees", "M002");
+      mkdirSync(join(wtRoot, ".gsd"), { recursive: true });
+
+      _clearGsdRootCache();
+      const contract = resolveGsdPathContract(wtRoot);
+
+      const canonicalStore = realpathSync.native(storeSymlink);
+      assert.ok(contract.isWorktree, "recognized as an external-state worktree layout");
+      assert.deepStrictEqual(contract.projectGsd, canonicalStore,
+        "projectGsd is the realpath'd project store, not the unresolved symlink");
+      assert.deepStrictEqual(contract.projectDb, join(canonicalStore, "gsd.db"),
+        "projectDb is built from the canonical project store");
+      assert.notStrictEqual(contract.projectDb, join(storeSymlink, "gsd.db"),
+        "regression #1239: DB must not open through the unresolved external-state symlink");
+    } finally {
+      if (originalStateDir === undefined) delete process.env.GSD_STATE_DIR;
+      else process.env.GSD_STATE_DIR = originalStateDir;
+      cleanup(root);
+    }
+  });
 });

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

@@ -40,6 +40,7 @@ import { readUnitRuntimeRecord } from "../unit-runtime.js";
 import { ModelPolicyDispatchBlockedError } from "../auto-model-selection.js";
 import {
   closeDatabase,
+  getTask,
   insertMilestone,
   insertSlice,
   insertTask,
@@ -445,7 +446,7 @@ test("runDispatch retries when complete-milestone summary exists on disk and stu
   assert.equal(stopCalls, 0, "artifact-based recovery should not hard-stop the loop");
 });
 
-test("runDispatch pauses when execute-task artifacts exist but DB status is still open", async (t) => {
+test("runDispatch promotes execute-task DB status when artifacts exist but DB status is still open (#1204)", async (t) => {
   const capture = createEventCapture();
   let pauseCalls = 0;
   let stopCalls = 0;
@@ -522,16 +523,16 @@ test("runDispatch pauses when execute-task artifacts exist but DB status is stil
 
   const result = await runDispatch(ic, preData, loopState);
 
-  assert.equal(result.action, "break");
-  assert.equal((result as any).reason, "execute-task-artifact-db-mismatch");
-  assert.equal(pauseCalls, 1, "execute-task disk/db mismatch should pause auto-mode");
-  assert.equal(stopCalls, 0, "execute-task disk/db mismatch should not hard-stop the loop");
-  assert.equal(invalidateCalls, 0, "mismatch should not clear caches and continue toward redispatch");
-  assert.equal(loopState.recentUnits.length, 3, "mismatch should keep the stuck window intact");
-  assert.equal(loopState.stuckRecoveryAttempts, 1, "mismatch should not reset the recovery counter");
+  assert.equal(result.action, "continue");
+  assert.equal(pauseCalls, 0, "disk-verified promotion should not pause auto-mode");
+  assert.equal(stopCalls, 0, "disk-verified promotion should not hard-stop the loop");
+  assert.equal(invalidateCalls, 1, "successful promotion should invalidate caches before retrying");
+  assert.equal(loopState.recentUnits.length, 0, "successful promotion should clear the stuck window");
+  assert.equal(loopState.stuckRecoveryAttempts, 1, "Level 1 recovery increments the attempt counter");
+  assert.equal(getTask("M001", "S01", "T01")?.status, "complete", "the open DB task should be promoted to complete");
 });
 
-test("runDispatch pauses at Level 2 when execute-task artifacts exist but DB status is still open", async (t) => {
+test("runDispatch promotes execute-task DB status at Level 2 when artifacts exist but DB status is still open (#1204)", async (t) => {
   const capture = createEventCapture();
   let pauseCalls = 0;
   let stopCalls = 0;
@@ -601,13 +602,13 @@ test("runDispatch pauses at Level 2 when execute-task artifacts exist but DB sta
 
   const result = await runDispatch(ic, preData, loopState);
 
-  assert.equal(result.action, "break");
-  assert.equal((result as any).reason, "execute-task-artifact-db-mismatch");
-  assert.equal(pauseCalls, 1, "Level 2 execute-task disk/db mismatch should pause auto-mode");
-  assert.equal(stopCalls, 0, "Level 2 execute-task disk/db mismatch should not hard-stop the loop");
+  assert.equal(result.action, "continue");
+  assert.equal(pauseCalls, 0, "Level 2 disk-verified promotion should not pause auto-mode");
+  assert.equal(stopCalls, 0, "Level 2 disk-verified promotion should not hard-stop the loop");
   assert.equal(invalidateCalls, 1, "Level 2 should invalidate caches before the final artifact recheck");
-  assert.equal(loopState.recentUnits.length, 3, "Level 2 mismatch should keep the stuck window intact");
-  assert.equal(loopState.stuckRecoveryAttempts, 1, "Level 2 mismatch should not reset the recovery counter");
+  assert.equal(loopState.recentUnits.length, 0, "Level 2 successful promotion should clear the stuck window");
+  assert.equal(loopState.stuckRecoveryAttempts, 1, "Level 2 does not reset the recovery counter");
+  assert.equal(getTask("M001", "S01", "T01")?.status, "complete", "the open DB task should be promoted to complete");
 });
 
 test("runDispatch clears execute-task stuck state when artifacts and DB status are complete", async (t) => {