gsd-pi 2.78.1-dev.d8826a445 → 2.78.1-dev.eccf86e27

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

@@ -182,7 +182,7 @@ function openRawDb(path: string): unknown {
   return new Database(path);
 }
 
-export const SCHEMA_VERSION = 23;
+export const SCHEMA_VERSION = 25;
 
 function indexExists(db: DbAdapter, name: string): boolean {
   return !!db.prepare(
@@ -190,6 +190,137 @@ function indexExists(db: DbAdapter, name: string): boolean {
   ).get(name);
 }
 
+/**
+ * Create the v24 coordination tables (workers, milestone_leases,
+ * unit_dispatches, cancellation_requests, command_queue) and their indexes.
+ *
+ * Idempotent — uses IF NOT EXISTS throughout. Called from both the
+ * fresh-install path and the v24 migration block in migrateSchema().
+ *
+ * Single-host invariant: these tables coordinate concurrent auto-mode
+ * workers via shared SQLite WAL on local disk only. NFS / network
+ * filesystems break the coordination semantics — multi-host execution
+ * needs a real coordinator (etcd, Postgres) and is out of scope.
+ */
+function createCoordinationTablesV24(db: DbAdapter): void {
+  const ddl = [
+    `CREATE TABLE IF NOT EXISTS workers (
+      worker_id TEXT PRIMARY KEY,
+      host TEXT NOT NULL,
+      pid INTEGER NOT NULL,
+      started_at TEXT NOT NULL,
+      version TEXT NOT NULL,
+      last_heartbeat_at TEXT NOT NULL,
+      status TEXT NOT NULL,
+      project_root_realpath TEXT NOT NULL
+    )`,
+    `CREATE TABLE IF NOT EXISTS milestone_leases (
+      milestone_id TEXT PRIMARY KEY,
+      worker_id TEXT NOT NULL,
+      fencing_token INTEGER NOT NULL,
+      acquired_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      status TEXT NOT NULL,
+      FOREIGN KEY (worker_id) REFERENCES workers(worker_id),
+      FOREIGN KEY (milestone_id) REFERENCES milestones(id)
+    )`,
+    `CREATE TABLE IF NOT EXISTS unit_dispatches (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      trace_id TEXT NOT NULL,
+      turn_id TEXT,
+      worker_id TEXT NOT NULL,
+      milestone_lease_token INTEGER NOT NULL,
+      milestone_id TEXT NOT NULL,
+      slice_id TEXT,
+      task_id TEXT,
+      unit_type TEXT NOT NULL,
+      unit_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      attempt_n INTEGER NOT NULL DEFAULT 1,
+      started_at TEXT NOT NULL,
+      ended_at TEXT,
+      exit_reason TEXT,
+      error_summary TEXT,
+      verification_evidence_id INTEGER,
+      next_run_at TEXT,
+      retry_after_ms INTEGER,
+      max_attempts INTEGER NOT NULL DEFAULT 3,
+      last_error_code TEXT,
+      last_error_at TEXT,
+      FOREIGN KEY (worker_id) REFERENCES workers(worker_id),
+      FOREIGN KEY (verification_evidence_id) REFERENCES verification_evidence(id)
+    )`,
+    `CREATE TABLE IF NOT EXISTS cancellation_requests (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      requested_at TEXT NOT NULL,
+      requested_by TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      scope_id TEXT NOT NULL,
+      dispatch_id INTEGER,
+      reason TEXT NOT NULL,
+      status TEXT NOT NULL,
+      acked_at TEXT,
+      acked_worker_id TEXT,
+      FOREIGN KEY (dispatch_id) REFERENCES unit_dispatches(id),
+      FOREIGN KEY (acked_worker_id) REFERENCES workers(worker_id)
+    )`,
+    `CREATE TABLE IF NOT EXISTS command_queue (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      target_worker TEXT,
+      command TEXT NOT NULL,
+      args_json TEXT NOT NULL DEFAULT '{}',
+      enqueued_at TEXT NOT NULL,
+      claimed_at TEXT,
+      claimed_by TEXT,
+      completed_at TEXT,
+      result_json TEXT
+    )`,
+  ];
+  for (const stmt of ddl) db.exec(stmt);
+
+  // Indexes — created here so both fresh-install and v24-migration paths
+  // produce identical structure.
+  db.exec("CREATE INDEX IF NOT EXISTS idx_unit_dispatches_active ON unit_dispatches(milestone_id, status)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_unit_dispatches_trace ON unit_dispatches(trace_id, turn_id)");
+  // Partial unique index — prevents two workers from claiming the same
+  // unit concurrently. Codex review MEDIUM B2: enforces double-claim guard
+  // at the DB level.
+  db.exec(
+    "CREATE UNIQUE INDEX IF NOT EXISTS idx_unit_dispatches_active_per_unit "
+    + "ON unit_dispatches(unit_id) WHERE status IN ('claimed','running')",
+  );
+  // command_queue index — SQLite indexes NULLs in B-trees, so this single
+  // index serves both targeted (target_worker = ?) and broadcast
+  // (target_worker IS NULL) queries. Codex review LOW B4 documented.
+  db.exec("CREATE INDEX IF NOT EXISTS idx_command_queue_pending ON command_queue(target_worker, claimed_at)");
+}
+
+/**
+ * Create the v25 runtime_kv table. Idempotent — uses IF NOT EXISTS.
+ *
+ * STRICT INVARIANT: runtime_kv is NON-CORRECTNESS-CRITICAL. UI cursors,
+ * dashboard caches, last-seen-version markers, resume cursors, and other
+ * "soft" state are OK. Anything that drives auto-mode control flow gets
+ * typed columns in unit_dispatches / workers / milestone_leases — never
+ * a bag of JSON in runtime_kv.
+ *
+ * Scope partitioning: ('global', '', key) for project-wide values;
+ * ('worker', worker_id, key) for per-worker state (resume cursors);
+ * ('milestone', milestone_id, key) for per-milestone soft state.
+ */
+function createRuntimeKvTableV25(db: DbAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS runtime_kv (
+      scope TEXT NOT NULL,
+      scope_id TEXT NOT NULL DEFAULT '',
+      key TEXT NOT NULL,
+      value_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (scope, scope_id, key)
+    )
+  `);
+}
+
 function dedupeVerificationEvidenceRows(db: DbAdapter): void {
   db.exec(`
     DELETE FROM verification_evidence
@@ -586,6 +717,9 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
 
     const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
     if (existing && (existing["cnt"] as number) === 0) {
+      createCoordinationTablesV24(db);
+      createRuntimeKvTableV25(db);
+
       // Fresh install — all tables are created above with the full current schema,
       // so it is safe to create all migration-specific indexes here.  For existing
       // databases these indexes are created inside the individual migration guards
@@ -1246,6 +1380,28 @@ function migrateSchema(db: DbAdapter): void {
       });
     }
 
+    if (currentVersion < 24) {
+      // v24: auto-mode coordination tables. See createCoordinationTablesV24
+      // for full schema + invariants. No-op for fresh installs (the same
+      // helper runs in the fresh-install path); for upgraded DBs this is
+      // the only place these tables get created.
+      createCoordinationTablesV24(db);
+      db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+        ":version": 24,
+        ":applied_at": new Date().toISOString(),
+      });
+    }
+
+    if (currentVersion < 25) {
+      // v25: runtime_kv non-correctness-critical key-value storage. See
+      // createRuntimeKvTableV25 for the full schema + invariants.
+      createRuntimeKvTableV25(db);
+      db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+        ":version": 25,
+        ":applied_at": new Date().toISOString(),
+      });
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -3301,6 +3457,9 @@ export function deleteMilestone(milestoneId: string): void {
     currentDb!.prepare(
       `DELETE FROM artifacts WHERE milestone_id = :mid`,
     ).run({ ":mid": milestoneId });
+    currentDb!.prepare(
+      `DELETE FROM milestone_leases WHERE milestone_id = :mid`,
+    ).run({ ":mid": milestoneId });
     currentDb!.prepare(
       `DELETE FROM milestones WHERE id = :mid`,
     ).run({ ":mid": milestoneId });
@@ -3723,14 +3882,20 @@ export function deleteArtifactByPath(path: string): void {
 }
 
 /**
- * Drop all rows from tasks/slices/milestones in dependency order inside a
- * transaction. Used by `gsd recover` to rebuild engine state from markdown.
+ * Drop hierarchy rows in dependency order inside a transaction. Used by
+ * `gsd recover` to rebuild engine state from markdown.
  */
 export function clearEngineHierarchy(): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
   transaction(() => {
+    currentDb!.exec("DELETE FROM verification_evidence");
+    currentDb!.exec("DELETE FROM quality_gates");
+    currentDb!.exec("DELETE FROM slice_dependencies");
+    currentDb!.exec("DELETE FROM assessments");
+    currentDb!.exec("DELETE FROM replan_history");
     currentDb!.exec("DELETE FROM tasks");
     currentDb!.exec("DELETE FROM slices");
+    currentDb!.exec("DELETE FROM milestone_leases");
     currentDb!.exec("DELETE FROM milestones");
   });
 }
@@ -3844,6 +4009,7 @@ export function restoreManifest(manifest: StateManifest): void {
     db.exec("DELETE FROM verification_evidence");
     db.exec("DELETE FROM tasks");
     db.exec("DELETE FROM slices");
+    db.exec("DELETE FROM milestone_leases");
     db.exec("DELETE FROM milestones");
     db.exec("DELETE FROM decisions WHERE 1=1");
 
@@ -3982,6 +4148,7 @@ export function bulkInsertLegacyHierarchy(payload: {
   transaction(() => {
     db.prepare(`DELETE FROM tasks WHERE milestone_id IN (${placeholders})`).run(...clearMilestoneIds);
     db.prepare(`DELETE FROM slices WHERE milestone_id IN (${placeholders})`).run(...clearMilestoneIds);
+    db.prepare(`DELETE FROM milestone_leases WHERE milestone_id IN (${placeholders})`).run(...clearMilestoneIds);
     db.prepare(`DELETE FROM milestones WHERE id IN (${placeholders})`).run(...clearMilestoneIds);
 
     const insertMilestone = db.prepare(

package/src/resources/extensions/gsd/guided-flow.ts

@@ -83,6 +83,8 @@ export {
   buildExistingMilestonesContext,
 } from "./guided-flow-queue.js";
 import { logWarning } from "./workflow-logger.js";
+import { deleteRuntimeKv } from "./db/runtime-kv.js";
+import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
 
 // ─── Scope-based validator wrappers ──────────────────────────────────────────
 // These thin wrappers accept a MilestoneScope so callers that already hold a
@@ -1963,10 +1965,12 @@ export async function showSmartEntry(
   if (interrupted.classification === "stale") {
     clearLock(basePath);
     if (interrupted.pausedSession) {
+      // Phase C pt 2: paused-session.json migrated to runtime_kv
+      // (global scope, key PAUSED_SESSION_KV_KEY).
       try {
-        unlinkSync(join(gsdRoot(basePath), "runtime", "paused-session.json"));
+        deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
       } catch (e) {
-        logWarning("guided", `stale pause file cleanup failed: ${(e as Error).message}`, { file: "guided-flow.ts" });
+        logWarning("guided", `stale paused-session DB cleanup failed: ${(e as Error).message}`, { file: "guided-flow.ts" });
       }
     }
   } else if (interrupted.classification === "recoverable") {

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

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { verifyExpectedArtifact } from "./auto-recovery.js";
@@ -16,6 +16,7 @@ import {
 } from "./session-forensics.js";
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
+import { getRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 
 export type InterruptedSessionClassification =
   | "none"
@@ -82,22 +83,28 @@ function isStalePseudoMilestonePause(meta: PausedSessionMetadata): boolean {
     && LEGACY_DEEP_SETUP_UNITS.has(`${meta.unitType}:${meta.unitId}`);
 }
 
+/**
+ * runtime_kv key (global scope) that stores the most recent paused-session
+ * metadata. Phase C pt 2: replaces runtime/paused-session.json. The key is
+ * project-wide (not worker-scoped) because the paused state represents the
+ * last time auto-mode paused on this project — there is at most one paused
+ * session per project at a time.
+ */
+export const PAUSED_SESSION_KV_KEY = "paused_session";
+
 export function readPausedSessionMetadata(
   basePath: string,
 ): PausedSessionMetadata | null {
-  const pausedPath = join(gsdRoot(basePath), "runtime", "paused-session.json");
-  if (!existsSync(pausedPath)) return null;
-
-  try {
-    const meta = JSON.parse(readFileSync(pausedPath, "utf-8")) as PausedSessionMetadata;
-    if (isStalePseudoMilestonePause(meta)) {
-      try { unlinkSync(pausedPath); } catch { /* non-fatal */ }
-      return null;
-    }
-    return meta;
-  } catch {
+  // basePath is unused now (the DB is workspace-scoped via the connection
+  // openDatabase opened on it) but kept in the signature for callers.
+  void basePath;
+  const meta = getRuntimeKv<PausedSessionMetadata>("global", "", PAUSED_SESSION_KV_KEY);
+  if (!meta) return null;
+  if (isStalePseudoMilestonePause(meta)) {
+    deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
     return null;
   }
+  return meta;
 }
 
 export function isBootstrapCrashLock(lock: LockData | null): boolean {

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

@@ -270,6 +270,21 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
   return null;
 }
 
+/**
+ * Options for deriveState read-path routing.
+ *
+ * `projectRootForReads`: canonical project root (e.g. from
+ * `s.canonicalProjectRoot`) used for both the cache key and the artifact-read
+ * root in `_deriveStateImpl`. When omitted, behavior is identical to the
+ * single-arg signature (back-compat for all existing callers).
+ *
+ * Typed as an object literal (not `string | DeriveStateOptions`) so accidental
+ * `deriveState(path, "string")` is rejected at compile time.
+ */
+export interface DeriveStateOptions {
+  projectRootForReads?: string;
+}
+
 /**
  * Reconstruct GSD state from the authoritative DB.
  * STATE.md is a rendered cache of this output.
@@ -278,11 +293,22 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
  * Legacy filesystem parsing is available only through an explicit opt-in for
  * tests/recovery flows; runtime must not silently infer state from markdown.
  */
-export async function deriveState(basePath: string): Promise<GSDState> {
-  // Return cached result if within the TTL window for the same basePath
+export async function deriveState(
+  basePath: string,
+  opts?: DeriveStateOptions,
+): Promise<GSDState> {
+  // Use the canonical project root (when provided) as the cache key so that
+  // two calls with different basePath strings (e.g. worktree path vs project
+  // root) but the same canonical .gsd/ share a single cache entry. The same
+  // key is used for both the lookup AND the write below — keying lookup on
+  // canonical-root while writing on basePath would silently return stale
+  // results across path-form alternation.
+  const cacheKey = opts?.projectRootForReads ?? basePath;
+
+  // Return cached result if within the TTL window for the same cacheKey
   if (
     _stateCache &&
-    _stateCache.basePath === basePath &&
+    _stateCache.basePath === cacheKey &&
     Date.now() - _stateCache.timestamp < CACHE_TTL_MS
   ) {
     return _stateCache.result;
@@ -303,7 +329,7 @@ export async function deriveState(basePath: string): Promise<GSDState> {
     if (wasDbOpenAttempted()) {
       logWarning("state", "DB unavailable — using explicit legacy filesystem state derivation");
     }
-    result = await _deriveStateImpl(basePath);
+    result = await _deriveStateImpl(basePath, opts);
     _telemetry.markdownDeriveCount++;
   } else {
     if (wasDbOpenAttempted()) {
@@ -325,7 +351,7 @@ export async function deriveState(basePath: string): Promise<GSDState> {
 
   stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
   debugCount("deriveStateCalls");
-  _stateCache = { basePath, result, timestamp: Date.now() };
+  _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
   return result;
 }
 
@@ -838,7 +864,19 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
 // LEGACY: Filesystem-based state derivation for unmigrated projects.
 // DB-backed projects use deriveStateFromDb() above. Target: extract to
 // state-legacy.ts when all projects are DB-backed.
-export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
+export async function _deriveStateImpl(
+  basePath: string,
+  opts?: DeriveStateOptions,
+): Promise<GSDState> {
+  // When the caller supplies a canonical project root for reads (e.g.
+  // s.canonicalProjectRoot from auto-mode), route all artifact reads through
+  // it. This prevents the worktree-local empty `.gsd/` from being consulted
+  // when the canonical state lives at the project root (or via a `.gsd`
+  // symlink into the external state dir).
+  if (opts?.projectRootForReads) {
+    basePath = opts.projectRootForReads;
+  }
+
   const diskIds = findMilestoneIds(basePath);
   const customOrder = loadQueueOrder(basePath);
   const milestoneIds = sortByQueueOrder(diskIds, customOrder);

package/src/resources/extensions/gsd/tests/auto-loop-no-copy-artifacts.test.ts

@@ -0,0 +1,72 @@
+// gsd-2 + Phase C deletion regression: createAutoWorktree no longer copies .gsd/
+//
+// Verifies that createAutoWorktree on a project with a real (non-symlinked)
+// .gsd/ does NOT populate .gsd/milestones/ inside the worktree. Pre-Phase-C,
+// copyPlanningArtifacts would mirror the project-root .gsd/ into the
+// worktree-local .gsd/. Phase C deleted that helper because writers in
+// auto-mode now route through s.canonicalProjectRoot, so the worktree never
+// needs a parallel .gsd/ projection.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, realpathSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { createAutoWorktree, teardownAutoWorktree } from "../auto-worktree.ts";
+
+function git(args: string[], cwd: string): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+test("createAutoWorktree does NOT copy project-root .gsd/milestones into the worktree", (t) => {
+  const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-no-copy-")));
+
+  // Initialize a real git repo with a real .gsd/ directory containing some
+  // planning artifacts that the deleted copyPlanningArtifacts would have
+  // mirrored.
+  git(["init", "-b", "main"], base);
+  git(["config", "user.name", "Pi Test"], base);
+  git(["config", "user.email", "pi@example.com"], base);
+  writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
+  git(["add", "README.md"], base);
+  git(["commit", "-m", "chore: init"], base);
+
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+    "# M001 Context\n",
+    "utf-8",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001 Roadmap\n",
+    "utf-8",
+  );
+
+  const wtPath = createAutoWorktree(base, "M001");
+  t.after(() => {
+    try { teardownAutoWorktree(base, "M001"); } catch { /* noop */ }
+    try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  // Phase C invariant: the worktree's .gsd/milestones/M001 must NOT exist
+  // (no copyPlanningArtifacts), and the project-root version must still be
+  // intact (it was the source, not destination).
+  assert.equal(
+    existsSync(join(wtPath, ".gsd", "milestones", "M001", "M001-CONTEXT.md")),
+    false,
+    "worktree should NOT have a copy of M001-CONTEXT.md (copyPlanningArtifacts deleted)",
+  );
+  assert.equal(
+    existsSync(join(wtPath, ".gsd", "milestones", "M001", "M001-ROADMAP.md")),
+    false,
+    "worktree should NOT have a copy of M001-ROADMAP.md",
+  );
+  assert.equal(
+    existsSync(join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md")),
+    true,
+    "project-root .gsd/ retains the canonical CONTEXT.md",
+  );
+});

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

@@ -0,0 +1,190 @@
+// gsd-2 + Symlinked .gsd worktree-loop reproduction (Phase A pt 2 follow-up to PR #5236)
+//
+// Regression coverage for the auto-mode loop bug observed on projects whose
+// .gsd/ is a symlink into ~/.gsd/projects/<hash>/ (the external-state layout).
+//
+// Two assertions:
+//   1. deriveState's cache key is the canonical project root when callers
+//      opt into projectRootForReads — so two derive calls that should refer
+//      to the same canonical state share a single cache entry, regardless of
+//      whether the caller passed the worktree path or the project-root path.
+//   2. _deriveStateImpl's projectRootForReads option routes legacy markdown
+//      reads through the canonical project root, finding files that live in
+//      the symlink target rather than the worktree-local empty .gsd/.
+//
+// Per project rule #11: regression test using node:test + node:assert/strict,
+// no source-grep assertions. The first test would fail on main without the
+// cache-key fix in state.ts (lookup vs write keys would diverge across
+// path-form alternation, producing cache misses). The second test would
+// fail on main because _deriveStateImpl doesn't accept the option at all.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  deriveState,
+  _deriveStateImpl,
+  invalidateStateCache,
+  type DeriveStateOptions,
+} from "../state.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+} from "../gsd-db.ts";
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────
+
+interface SymlinkedFixture {
+  /** Project root containing .gsd as a symlink. */
+  projectRoot: string;
+  /** External state dir that .gsd points at (acts as the canonical .gsd/). */
+  externalState: string;
+  /** Worktree path under the external state's worktrees/ dir. */
+  worktreePath: string;
+}
+
+function makeSymlinkedFixture(prefix: string): SymlinkedFixture {
+  // Use realpathSync on tmpdir so that subsequent realpath comparisons are stable
+  // — macOS /var symlinks to /private/var, which would otherwise pollute the
+  // canonical-root assertions below.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), `gsd-${prefix}-`)));
+  const projectRoot = join(root, "project");
+  const externalState = join(root, "external-state", "projects", "abc123");
+
+  mkdirSync(projectRoot, { recursive: true });
+  mkdirSync(externalState, { recursive: true });
+
+  // .gsd → externalState (the layout that triggered the original bug)
+  symlinkSync(externalState, join(projectRoot, ".gsd"), "junction");
+
+  // Worktree path lives under the external state's worktrees/ dir, mirroring
+  // the canonicalProjectRoot resolution that resolveGsdPathContract performs
+  // for the external-state layout.
+  const worktreePath = join(externalState, "worktrees", "M001");
+  mkdirSync(worktreePath, { recursive: true });
+
+  return { projectRoot, externalState, worktreePath };
+}
+
+function cleanupFixture(fx: SymlinkedFixture): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  // The mkdtemp root is two levels above projectRoot.
+  try {
+    const root = join(fx.projectRoot, "..");
+    rmSync(root, { recursive: true, force: true });
+  } catch { /* noop */ }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test 1: cache-key invariance under projectRootForReads
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("deriveState: cache key is canonical when projectRootForReads is supplied", async (t) => {
+  const fx = makeSymlinkedFixture("symlink-cache");
+  t.after(() => cleanupFixture(fx));
+
+  // Open the DB at the canonical .gsd location (externalState).
+  openDatabase(join(fx.externalState, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Symlinked", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice" });
+  // No tasks → DB-derived state is "planning".
+
+  invalidateStateCache();
+
+  const optsCanonical: DeriveStateOptions = { projectRootForReads: fx.projectRoot };
+
+  // First call: seed the cache through the worktree-path form.
+  const stateA = await deriveState(fx.worktreePath, optsCanonical);
+  assert.equal(stateA.activeMilestone?.id, "M001");
+  assert.equal(stateA.activeSlice?.id, "S01");
+  assert.equal(stateA.phase, "planning");
+
+  // Second call: canonical project-root form must hit the same cache entry.
+  const stateB = await deriveState(fx.projectRoot);
+  assert.equal(stateB, stateA, "second call with same canonical key must return the cached object");
+
+  // Third call: worktree-path form with projectRootForReads must also hit the
+  // same cache entry, proving the cache key is symmetric across both call
+  // orders.
+  const stateC = await deriveState(fx.worktreePath, optsCanonical);
+  assert.equal(stateC, stateA, "third call with worktree path plus canonical reads must hit the same cache entry");
+
+  // Mutation invalidates: insert a task, clear cache, re-derive — must
+  // observe the new state via the canonical key path.
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Task", status: "active" });
+  invalidateStateCache();
+
+  const stateD = await deriveState(fx.worktreePath, optsCanonical);
+  assert.notEqual(stateD, stateA, "post-mutation derive must re-compute, not reuse the prior cached object");
+  assert.equal(stateD.activeTask?.id, "T01", "mutation must surface in the re-derived state");
+  assert.equal(stateD.phase, "executing");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test 2: _deriveStateImpl reads from canonical root via projectRootForReads
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("_deriveStateImpl: projectRootForReads routes legacy markdown reads to the canonical .gsd/", async (t) => {
+  const fx = makeSymlinkedFixture("symlink-md");
+  t.after(() => cleanupFixture(fx));
+  // No DB opened — exercise the markdown fallback.
+
+  // Seed the external state dir (the symlink target) with a roadmap so the
+  // legacy filesystem state derivation has a milestone to find.
+  const m1Dir = join(fx.externalState, "milestones", "M001");
+  mkdirSync(m1Dir, { recursive: true });
+  writeFileSync(
+    join(m1Dir, "M001-CONTEXT.md"),
+    "# M001: Symlinked legacy md test\n\nTest project.\n",
+    "utf-8",
+  );
+  writeFileSync(
+    join(m1Dir, "M001-ROADMAP.md"),
+    [
+      "# M001 Roadmap",
+      "",
+      "## Slices",
+      "",
+      "- [ ] **S01: First slice** — depends:",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  invalidateStateCache();
+
+  // Calling _deriveStateImpl with the worktree path AND projectRootForReads
+  // pointing at the project root must consult the canonical .gsd/ (via the
+  // symlink target externalState), find M001/S01, and report planning phase
+  // because no slice plan file exists yet.
+  const state = await _deriveStateImpl(fx.worktreePath, { projectRootForReads: fx.projectRoot });
+  assert.equal(state.activeMilestone?.id, "M001", "must find M001 via canonical .gsd/ reads");
+  assert.equal(state.activeSlice?.id, "S01", "must find S01 from the roadmap");
+  assert.equal(state.phase, "planning", "no slice PLAN.md yet → planning phase");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test 3: type-safety guard for the deriveState opts overload (compile-time)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// The DeriveStateOptions parameter is typed as an object literal so accidental
+// `deriveState(path, "string")` is a TypeScript compile error. The
+// expect-error directive verifies that this guard is in place — if the
+// overload were widened to `string | DeriveStateOptions`, the directive would
+// trigger TS2578 ("Unused '@ts-expect-error' directive") at build time.
+
+test("deriveState: opts param rejects non-object values at compile time", () => {
+  // The actual assertion is the TypeScript compile-time check below; the
+  // runtime body just confirms the test ran.
+  if (false) {
+    // @ts-expect-error — projectRootForReads must be a string
+    void deriveState("/nonexistent", { projectRootForReads: 123 });
+  }
+  assert.ok(true);
+});