@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -15,8 +15,11 @@ import {
   upsertRequirement,
   getAllMilestones,
 } from "../gsd-db.ts";
+import { registerAutoWorker } from "../db/auto-workers.ts";
+import { claimMilestoneLease, getMilestoneLease } from "../db/milestone-leases.ts";
 import { deriveState, invalidateStateCache } from "../state.ts";
 import { autoSession } from "../auto-runtime-state.ts";
+import { normalizeRealPath } from "../paths.ts";
 import { markApprovalGateVerified, markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot, setPendingGate } from "../bootstrap/write-gate.ts";
 import {
   executeCompleteMilestone,
@@ -94,6 +97,28 @@ function seedMilestone(milestoneId: string, title: string, status = "active"): v
   ).run(milestoneId, title, status, new Date().toISOString());
 }
 
+function validMilestonePlan(milestoneId = "M001"): Parameters<typeof executePlanMilestone>[0] {
+  return {
+    milestoneId,
+    title: "Workflow MCP planning",
+    vision: "Plan milestone over shared executors.",
+    slices: [
+      {
+        sliceId: "S01",
+        title: "Bridge planning",
+        risk: "medium",
+        depends: [],
+        demo: "Milestone plan persists through MCP.",
+        goal: "Persist roadmap state.",
+        successCriteria: "ROADMAP.md renders from DB.",
+        proofLevel: "integration",
+        integrationClosure: "Prompts and MCP call the same handler.",
+        observabilityImpact: "Executor tests cover output paths.",
+      },
+    ],
+  };
+}
+
 function seedSlice(milestoneId: string, sliceId: string, status: string): void {
   const db = _getAdapter();
   if (!db) throw new Error("DB not open");
@@ -461,25 +486,7 @@ test("executePlanMilestone writes roadmap state and rendered roadmap path", asyn
   try {
     openTestDb(base);
 
-    const result = await inProjectDir(base, () => executePlanMilestone({
-      milestoneId: "M001",
-      title: "Workflow MCP planning",
-      vision: "Plan milestone over shared executors.",
-      slices: [
-        {
-          sliceId: "S01",
-          title: "Bridge planning",
-          risk: "medium",
-          depends: [],
-          demo: "Milestone plan persists through MCP.",
-          goal: "Persist roadmap state.",
-          successCriteria: "ROADMAP.md renders from DB.",
-          proofLevel: "integration",
-          integrationClosure: "Prompts and MCP call the same handler.",
-          observabilityImpact: "Executor tests cover output paths.",
-        },
-      ],
-    }, base));
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan(), base));
 
     assert.equal(result.details.operation, "plan_milestone");
     assert.equal(result.details.milestoneId, "M001");
@@ -492,29 +499,257 @@ test("executePlanMilestone writes roadmap state and rendered roadmap path", asyn
   }
 });
 
+test("executePlanMilestone refuses a same-milestone lease conflict", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Existing holder");
+    const holder = registerAutoWorker({ projectRootRealpath: join(base, "other-project") });
+    const lease = claimMilestoneLease(holder, "M001");
+    assert.equal(lease.ok, true);
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M001"), base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.operation, "plan_milestone");
+    assert.equal(result.details.error, "milestone_lease_conflict");
+    assert.match(result.content[0].text, /Milestone M001 is currently leased/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone releases its one-shot milestone lease after planning", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Existing milestone");
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M001"), base));
+
+    assert.equal(result.isError, undefined);
+    const lease = getMilestoneLease("M001");
+    assert.ok(lease, "planning should participate in milestone lease coordination");
+    assert.equal(lease.status, "released");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone creates a fresh milestone without a one-shot lease", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M042"), base));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.operation, "plan_milestone");
+    assert.equal(result.details.milestoneId, "M042");
+    assert.equal(getMilestoneLease("M042"), null,
+      "fresh milestone creation must pass through without creating a lease row");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone does not create a placeholder when fresh planning validation fails", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    // handlePlanMilestone rejects empty slice arrays during validation. Fresh
+    // milestone creation must pass through without pre-inserting a leaseable
+    // placeholder row.
+    const invalid = { ...validMilestonePlan("M042"), slices: [] };
+    const result = await inProjectDir(base, () => executePlanMilestone(invalid, base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.operation, "plan_milestone");
+    const milestones = getAllMilestones();
+    assert.equal(milestones.find(m => m.id === "M042"), undefined,
+      "failed fresh planning must not leave a milestone row behind");
+    assert.equal(getMilestoneLease("M042"), null,
+      "failed fresh planning must not create a lease row");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone does not delete a peer worker's milestone row on lease conflict", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    // Simulate a peer worker (different project_root) that has already
+    // created the milestone row and taken its lease. The one-shot executor
+    // must observe the active lease and refuse — without removing the peer's
+    // milestone row or lease. The pre-rollback bug was that
+    // INSERT OR IGNORE's silent no-op was treated as proof of authorship and
+    // the cleanup path then deleted the peer's row.
+    const peer = registerAutoWorker({ projectRootRealpath: join(base, "peer-project") });
+    seedMilestone("M050", "Peer-owned milestone");
+    const peerLease = claimMilestoneLease(peer, "M050");
+    assert.equal(peerLease.ok, true);
+    const peerLeaseToken = peerLease.ok ? peerLease.token : -1;
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M050"), base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.error, "milestone_lease_conflict");
+    const peerMilestone = getAllMilestones().find(m => m.id === "M050");
+    assert.ok(peerMilestone, "peer milestone row must survive the one-shot conflict path");
+    assert.equal(peerMilestone?.title, "Peer-owned milestone",
+      "peer milestone row must not be clobbered or recreated");
+    const surviving = getMilestoneLease("M050");
+    assert.ok(surviving, "peer lease row must survive");
+    assert.equal(surviving.status, "held", "peer must still hold the lease");
+    assert.equal(surviving.worker_id, peer);
+    assert.equal(surviving.fencing_token, peerLeaseToken,
+      "peer's fencing token must not be incremented by the rejected one-shot");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone refuses when a foreign active worker holds the lease even while in-process auto is active", async () => {
+  const base = makeTmpBase();
+  autoSession.reset();
+  try {
+    openTestDb(base);
+    seedMilestone("M060", "Foreign-held milestone");
+
+    // In-process auto must still reject a lease held by another worker.
+    const foreign = registerAutoWorker({ projectRootRealpath: join(base, "foreign-project") });
+    const foreignLease = claimMilestoneLease(foreign, "M060");
+    assert.equal(foreignLease.ok, true);
+    const foreignToken = foreignLease.ok ? foreignLease.token : -1;
+
+    const ownAutoWorker = registerAutoWorker({ projectRootRealpath: normalizeRealPath(base) });
+    autoSession.active = true;
+    autoSession.workerId = ownAutoWorker;
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M060"), base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.error, "milestone_lease_conflict",
+      "in-process auto must NOT skip lease checks when the lease is held by a different active worker");
+    const surviving = getMilestoneLease("M060");
+    assert.ok(surviving);
+    assert.equal(surviving.status, "held");
+    assert.equal(surviving.worker_id, foreign);
+    assert.equal(surviving.fencing_token, foreignToken,
+      "foreign worker's fencing token must not be incremented by the rejected call");
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone proceeds without re-claiming when in-process auto holds the lease itself", async () => {
+  const base = makeTmpBase();
+  autoSession.reset();
+  try {
+    openTestDb(base);
+    seedMilestone("M070", "Auto-held milestone");
+
+    // In-process auto should not re-claim its own lease and bump its token.
+    const ownAutoWorker = registerAutoWorker({ projectRootRealpath: normalizeRealPath(base) });
+    const heldLease = claimMilestoneLease(ownAutoWorker, "M070");
+    assert.equal(heldLease.ok, true);
+    const heldToken = heldLease.ok ? heldLease.token : -1;
+    autoSession.active = true;
+    autoSession.workerId = ownAutoWorker;
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M070"), base));
+
+    assert.equal(result.isError, undefined, `auto's own plan-milestone call should succeed: ${result.content?.[0]?.text}`);
+    const surviving = getMilestoneLease("M070");
+    assert.ok(surviving);
+    assert.equal(surviving.status, "held", "auto's lease must still be held after the planning call");
+    assert.equal(surviving.worker_id, ownAutoWorker);
+    assert.equal(surviving.fencing_token, heldToken,
+      "auto's fencing token must not be incremented by an in-process plan call");
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone refuses a same-process holder when active auto does not own it", async () => {
+  const base = makeTmpBase();
+  autoSession.reset();
+  try {
+    openTestDb(base);
+    seedMilestone("M080", "Same-process holder");
+    const staleWorker = registerAutoWorker({ projectRootRealpath: normalizeRealPath(base) });
+    const heldLease = claimMilestoneLease(staleWorker, "M080");
+    assert.equal(heldLease.ok, true);
+    const heldToken = heldLease.ok ? heldLease.token : -1;
+
+    autoSession.active = true;
+    autoSession.workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(base) });
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M080"), base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details?.error, "milestone_lease_conflict");
+    const surviving = getMilestoneLease("M080");
+    assert.ok(surviving, "same-process holder lease must remain after conflict");
+    assert.equal(surviving.worker_id, staleWorker);
+    assert.equal(surviving.fencing_token, heldToken);
+    assert.equal(surviving.status, "held");
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executePlanMilestone takes over a stale same-process lease via reentry instead of waiting for TTL", async () => {
+  const base = makeTmpBase();
+  autoSession.reset();
+  try {
+    openTestDb(base);
+    seedMilestone("M080", "Stale-locked milestone");
+
+    // One-shot planning should reach claimMilestoneLease so its same-process
+    // reentry clause can recover stale worker rows.
+    const staleWorker = registerAutoWorker({ projectRootRealpath: normalizeRealPath(base) });
+    const staleLease = claimMilestoneLease(staleWorker, "M080");
+    assert.equal(staleLease.ok, true);
+    const staleToken = staleLease.ok ? staleLease.token : -1;
+
+    const result = await inProjectDir(base, () => executePlanMilestone(validMilestonePlan("M080"), base));
+
+    assert.equal(result.isError, undefined,
+      `same-process reentry takeover must succeed, not return milestone_lease_conflict: ${result.content?.[0]?.text}`);
+    const after = getMilestoneLease("M080");
+    assert.ok(after, "lease row must remain after takeover + release");
+    assert.equal(after.status, "released", "the executor releases its own claim before returning");
+    assert.notEqual(after.worker_id, staleWorker,
+      "lease must be owned by the new worker after takeover");
+    assert.ok(after.fencing_token > staleToken,
+      `fencing token must monotonically advance on takeover (was ${staleToken}, now ${after.fencing_token})`);
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executePlanSlice writes task planning state and rendered plan artifacts", async () => {
   const base = makeTmpBase();
   try {
     openTestDb(base);
-    await inProjectDir(base, () => executePlanMilestone({
-      milestoneId: "M001",
-      title: "Workflow MCP planning",
-      vision: "Plan milestone over shared executors.",
-      slices: [
-        {
-          sliceId: "S01",
-          title: "Bridge planning",
-          risk: "medium",
-          depends: [],
-          demo: "Milestone plan persists through MCP.",
-          goal: "Persist roadmap state.",
-          successCriteria: "ROADMAP.md renders from DB.",
-          proofLevel: "integration",
-          integrationClosure: "Prompts and MCP call the same handler.",
-          observabilityImpact: "Executor tests cover output paths.",
-        },
-      ],
-    }, base));
+    await inProjectDir(base, () => executePlanMilestone(validMilestonePlan(), base));
 
     const result = await inProjectDir(base, () => executePlanSlice({
       milestoneId: "M001",
@@ -528,8 +763,8 @@ test("executePlanSlice writes task planning state and rendered plan artifacts",
           estimate: "15m",
           files: ["src/resources/extensions/gsd/tools/workflow-tool-executors.ts"],
           verify: "node --test",
-          inputs: [".gsd/milestones/M001/M001-ROADMAP.md"],
-          expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"],
+          inputs: [],
+          expectedOutput: ["src/bridge-status.md"],
         },
       ],
     }, base));

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

@@ -109,6 +109,21 @@ test("ensureWorkspaceGitReadyForPath blocks product file conflicts", async () =>
   }
 });
 
+test("ensureWorkspaceGitReadyForPath does not block on staged files with trailing whitespace", async () => {
+  // Regression test for #599: git diff --check exits non-zero for whitespace
+  // errors as well as conflict markers. Staged files from auto-generated code
+  // often have trailing whitespace; these must not trigger the conflict gate.
+  const base = makeTempRepo("gsd-ws-git-whitespace-");
+  try {
+    writeFileSync(join(base, "app.ts"), "const x = 1;   \n"); // trailing whitespace
+    git(base, "add", "app.ts");
+    const ready = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(ready.ok, true, "trailing whitespace in staged files must not block");
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("isWorkspaceGitAllowedCommand allowlists doctor, closeout, and dispatch complete-milestone", () => {
   assert.equal(isWorkspaceGitAllowedCommand("doctor"), true);
   assert.equal(isWorkspaceGitAllowedCommand("doctor fix"), true);

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

@@ -15,7 +15,7 @@ import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 
 import { PROJECT_FILES, classifyProject } from "../detection.js";
-import { _shouldProceedWithInvalidRepoClassificationForTest } from "../auto/phases.ts";
+import { _shouldProceedWithInvalidRepoClassificationForTest } from "../auto/unit-phase.ts";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 

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

@@ -161,13 +161,13 @@ test("enterMilestone returns ok:true mode:worktree on successful create", (t) =>
   if (result.ok) {
     assert.equal(result.mode, "worktree");
     assert.ok(
-      result.path.endsWith("/.gsd/worktrees/M001"),
-      `expected path to end with /.gsd/worktrees/M001, got ${result.path}`,
+      result.path.endsWith("/.gsd-worktrees/M001"),
+      `expected path to end with /.gsd-worktrees/M001, got ${result.path}`,
     );
   }
   assert.ok(
-    s.basePath.endsWith("/.gsd/worktrees/M001"),
-    `expected s.basePath to end with /.gsd/worktrees/M001, got ${s.basePath}`,
+    s.basePath.endsWith("/.gsd-worktrees/M001"),
+    `expected s.basePath to end with /.gsd-worktrees/M001, got ${s.basePath}`,
   );
   // After C3 (#5626) `invalidateAllCaches` is inlined; assertion against
   // `deps.calls` for cache invalidation is no longer possible.
@@ -240,6 +240,43 @@ test("adoptStrandedMilestone forces branch recovery even when normal preferences
   assert.equal(currentBranch, "milestone/M001");
 });
 
+test("enterMilestone honors stranded branch recovery instead of recreating the worktree", (t) => {
+  // Regression: after adoptStrandedMilestone checks out milestone/M001 in
+  // the project root, a plain enterMilestone under isolation:worktree used
+  // to attempt `git worktree add`, which git refuses ("branch is already in
+  // use by another worktree" — the root checkout IS the conflicting
+  // worktree), tripping a creation-failed warning and degrading isolation.
+  // The recovery override must keep re-entries in branch mode.
+  const previousCwd = process.cwd();
+  const base = makeGitRepoBase({ isolation: "worktree" });
+  t.after(() => cleanupRepoBase(base, previousCwd));
+
+  const s = makeSession({ basePath: base, originalBasePath: base });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const adopted = lifecycle.adoptStrandedMilestone("M001", base, ctx, {
+    mode: "branch",
+  });
+  assert.equal(adopted.ok, true, `expected adopt ok:true, got: ${JSON.stringify(adopted)}`);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true, `expected ok:true, got: ${JSON.stringify(result)}`);
+  if (result.ok) {
+    assert.equal(result.mode, "branch");
+    assert.equal(result.path, base);
+  }
+  assert.equal(s.basePath, base);
+  assert.equal(s.isolationDegraded, false, "intentional branch adoption must not degrade isolation");
+  assert.equal(
+    ctx.messages.some((m) => m.msg.includes("creation for M001 failed")),
+    false,
+    "re-entry must not attempt (and fail) canonical worktree creation",
+  );
+});
+
 test("enterMilestone returns ok:false reason:isolation-degraded when session degraded", () => {
   const s = makeSession({ isolationDegraded: true });
   const deps = makeDeps({ getIsolationMode: () => "branch" });

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

@@ -121,6 +121,48 @@ describe("createWorktree", () => {
     run("git rev-parse --git-dir", info.path);
     assert.ok(!existsSync(join(info.path, "orphan.txt")), "stale file removed by recovery");
   });
+
+  test("removes stale worktree directory with .git file not registered with git and recreates", () => {
+    // Simulate the scenario from issue #590: removeWorktree() failed to delete
+    // the directory (e.g. EPERM on Windows) but git worktree prune cleaned up
+    // the registry — leaving an orphaned directory with a .git *file* (not
+    // directory) that git no longer knows about.
+    const staleDir = worktreePath(base, "M010");
+    mkdirSync(staleDir, { recursive: true });
+    // Write a .git file (worktree gitdir pointer) — not a directory
+    writeFileSync(join(staleDir, ".git"), "gitdir: ../../../../.git/worktrees/M010\n", "utf-8");
+    writeFileSync(join(staleDir, "orphan.txt"), "stale leftover\n", "utf-8");
+
+    // createWorktree must detect the orphan (not in git worktree list), clean it
+    // up, and succeed — not throw GSD_STALE_STATE as if it were a live conflict.
+    const info = createWorktree(base, "M010");
+    assert.strictEqual(info.name, "M010");
+    assert.ok(existsSync(info.path));
+    assert.ok(existsSync(join(info.path, ".git")), "recovered worktree has .git marker");
+    run("git rev-parse --git-dir", info.path);
+    assert.ok(!existsSync(join(info.path, "orphan.txt")), "stale file removed by recovery");
+  });
+
+  test("removes stale canonical directory when legacy orphan is cleaned and canonical target is stale", () => {
+    // Scenario: a stale .gsd-worktrees/M020 directory (no .git — aborted prior
+    // creation) coexists with an orphaned .gsd/worktrees/M020 dir (.git file not
+    // registered with git). worktreePathFor returns the legacy path (canonical has
+    // no .git marker), so only the legacy path was previously cleaned — the stale
+    // canonical blocked git worktree add. The fix ensures createWorktree also
+    // removes the stale canonical before calling git worktree add.
+    const canonicalDir = join(base, ".gsd-worktrees", "M020");
+    const legacyDir = join(base, ".gsd", "worktrees", "M020");
+
+    mkdirSync(canonicalDir, { recursive: true });  // stale canonical: exists, no .git
+    mkdirSync(legacyDir, { recursive: true });
+    writeFileSync(join(legacyDir, ".git"), "gitdir: ../../../../.git/worktrees/M020\n", "utf-8");
+
+    const info = createWorktree(base, "M020");
+    assert.strictEqual(info.name, "M020");
+    assert.ok(existsSync(info.path), "worktree path should exist after creation");
+    assert.ok(existsSync(join(info.path, ".git")), "new worktree has .git marker");
+    run("git rev-parse --git-dir", info.path);
+  });
 });
 
 describe("createWorktree — duplicate rejection", () => {
@@ -159,7 +201,7 @@ describe("createWorktree — branch cleanup on add failure", () => {
 
     // Make the worktrees parent directory non-writable so `git worktree add`
     // fails after the branch has already been force-reset.
-    const parentDir = join(base, ".gsd", "worktrees");
+    const parentDir = join(base, ".gsd-worktrees");
     mkdirSync(parentDir, { recursive: true });
     run(`chmod 555 "${parentDir}"`, base);
 

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

@@ -0,0 +1,113 @@
+/**
+ * Tests for worktreePathFor — the forward seam (project + name → path).
+ *
+ * Key invariant: a stale canonical directory (no .git marker) must NOT
+ * shadow a live legacy worktree (.gsd/worktrees/<name> with .git).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { worktreePathFor, canonicalWorktreesDir, legacyWorktreesDir } from "../worktree-placement.ts";
+
+function makeTmpRoot(): string {
+  const root = join(tmpdir(), `gsd-placement-test-${randomUUID()}`);
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function cleanup(root: string): void {
+  try { rmSync(root, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function makeCanonicalDir(root: string, name: string): string {
+  const p = join(canonicalWorktreesDir(root), name);
+  mkdirSync(p, { recursive: true });
+  return p;
+}
+
+function makeLiveCanonical(root: string, name: string): string {
+  const p = makeCanonicalDir(root, name);
+  writeFileSync(join(p, ".git"), `gitdir: ${join(root, ".git", "worktrees", name)}\n`);
+  return p;
+}
+
+function makeLiveLegacy(root: string, name: string): string {
+  const p = join(legacyWorktreesDir(root), name);
+  mkdirSync(p, { recursive: true });
+  writeFileSync(join(p, ".git"), `gitdir: ${join(root, ".git", "worktrees", name)}\n`);
+  return p;
+}
+
+test("returns canonical path when canonical has .git marker", () => {
+  const root = makeTmpRoot();
+  try {
+    const canonical = makeLiveCanonical(root, "M001");
+    assert.equal(worktreePathFor(root, "M001"), canonical);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("returns legacy path when only legacy exists with .git marker", () => {
+  const root = makeTmpRoot();
+  try {
+    const legacy = makeLiveLegacy(root, "M001");
+    assert.equal(worktreePathFor(root, "M001"), legacy);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("returns legacy path when canonical dir exists but has no .git (stale canonical)", () => {
+  const root = makeTmpRoot();
+  try {
+    makeCanonicalDir(root, "M001"); // stale: dir exists, no .git
+    const legacy = makeLiveLegacy(root, "M001");
+    assert.equal(
+      worktreePathFor(root, "M001"),
+      legacy,
+      "stale canonical must not shadow live legacy worktree",
+    );
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("returns canonical path for new-worktree creation when neither path exists", () => {
+  const root = makeTmpRoot();
+  try {
+    const expected = join(canonicalWorktreesDir(root), "M001");
+    assert.equal(worktreePathFor(root, "M001"), expected);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("prefers live canonical over live legacy when both exist", () => {
+  const root = makeTmpRoot();
+  try {
+    const canonical = makeLiveCanonical(root, "M001");
+    makeLiveLegacy(root, "M001");
+    assert.equal(worktreePathFor(root, "M001"), canonical);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("returns legacy when canonical is stale and legacy has no .git (both stale)", () => {
+  const root = makeTmpRoot();
+  try {
+    makeCanonicalDir(root, "M001"); // stale canonical
+    const legacy = join(legacyWorktreesDir(root), "M001");
+    mkdirSync(legacy, { recursive: true }); // stale legacy (no .git)
+    // Falls through to legacy existsSync since canonical has no .git
+    assert.equal(worktreePathFor(root, "M001"), legacy);
+  } finally {
+    cleanup(root);
+  }
+});

package/src/resources/extensions/gsd/tests/worktree-project-root-degrade.test.ts

@@ -3,7 +3,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
-import { shouldDegradeEmptyWorktreeToProjectRoot } from "../auto/phases.ts";
+import { shouldDegradeEmptyWorktreeToProjectRoot } from "../auto/worktree-safety-phase.ts";
 import type { ProjectClassification } from "../detection.ts";
 
 function classification(kind: ProjectClassification["kind"]): ProjectClassification {

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

@@ -171,7 +171,7 @@ test("validate-milestone invoked from the project root writes VALIDATION under t
   const projectProjection = join(projectRoot, ".gsd", "milestones", MID, "M001-VALIDATION.md");
   assert.equal(result.validationPath, expected);
   assert.equal(existsSync(expected), true);
-  assert.equal(existsSync(projectProjection), false);
+  assert.equal(existsSync(projectProjection), true, "VALIDATION should mirror to project root for consistent reads");
 });
 
 test("complete-milestone writes SUMMARY under the active worktree projection", async (t) => {

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

@@ -65,7 +65,7 @@ describe("reenterActiveWorktreeIfNeeded", () => {
     const entered = await reenterActiveWorktreeIfNeeded(dir);
     assert.ok(entered, "re-entry returned a worktree path");
     assert.strictEqual(realpathSync(process.cwd()), realpathSync(entered!), "cwd moved into the worktree");
-    assert.strictEqual(entered, join(dir, ".gsd", "worktrees", "M001"));
+    assert.strictEqual(entered, join(dir, ".gsd-worktrees", "M001"));
   });
 
   test("no-op when already inside a worktree", async (t) => {