@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.955e4da0

package/src/resources/extensions/gsd/tests/register-hooks-depth-verification.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -13,7 +13,9 @@ import { closeDatabase, getMilestone } from "../gsd-db.ts";
 import { deriveState, invalidateStateCache } from "../state.ts";
 import {
   getPendingGate,
+  loadWriteGateSnapshot,
   resetWriteGateState,
+  setPendingGate,
   shouldBlockContextArtifactSave,
 } from "../bootstrap/write-gate.ts";
 import { classifyCommand } from "../safety/destructive-guard.ts";
@@ -802,3 +804,91 @@ test("register-hooks message_update does NOT pause while an interactive elicitat
     "prose-only approval with no elicitation in flight must still arm the pause notice",
   );
 });
+
+test("register-hooks agent_end does not re-arm deferred gate after workflow MCP verified write-gate on disk", async (t) => {
+  const dir = makeTempDir("mcp-disk-sync");
+  const originalCwd = process.cwd();
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+  process.chdir(dir);
+  resetWriteGateState(dir);
+  clearPendingAutoStart(dir);
+  process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+
+  const gateId = "depth_verification_M005_confirm";
+  const statePath = join(dir, ".gsd", "runtime", "write-gate-state.json");
+
+  t.after(() => {
+    try {
+      resetWriteGateState(dir);
+      clearPendingAutoStart(dir);
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+      }
+      process.chdir(originalCwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  } as any;
+
+  const ctx = {
+    cwd: dir,
+    ui: { notify: () => undefined },
+  } as any;
+
+  registerHooks(pi, []);
+
+  setPendingAutoStart(dir, {
+    basePath: dir,
+    milestoneId: "M005",
+    ctx,
+    pi: { sendMessage: () => undefined } as any,
+  });
+
+  const approvalMessage = {
+    role: "assistant",
+    content: [
+      { type: "text", text: "Did I capture the depth right?" },
+    ],
+  };
+
+  for (const handler of handlers.get("message_update") ?? []) {
+    await handler({ message: approvalMessage }, ctx);
+  }
+
+  setPendingGate(gateId, dir);
+  mkdirSync(join(dir, ".gsd", "runtime"), { recursive: true });
+  writeFileSync(statePath, JSON.stringify({
+    verifiedDepthMilestones: ["M005"],
+    verifiedApprovalGates: [gateId],
+    activeQueuePhase: false,
+    pendingGateId: null,
+  }, null, 2), "utf-8");
+
+  for (const handler of handlers.get("agent_end") ?? []) {
+    await handler({ messages: [] }, ctx);
+  }
+
+  assert.equal(getPendingGate(dir), null, "agent_end must not re-arm a gate the MCP subprocess already verified");
+  assert.equal(
+    shouldBlockContextArtifactSave("CONTEXT", "M005", null, dir).block,
+    false,
+    "verified milestone context writes must stay unlocked after agent_end",
+  );
+  assert.deepEqual(loadWriteGateSnapshot(dir), {
+    verifiedDepthMilestones: ["M005"],
+    verifiedApprovalGates: [gateId],
+    activeQueuePhase: false,
+    pendingGateId: null,
+  });
+});

package/src/resources/extensions/gsd/tests/safety-harness-false-positives.test.ts

@@ -266,3 +266,41 @@ test("safety-harness: planned changed file avoids unexpected-file warning", (t)
   assert.deepEqual(audit!.unexpectedFiles, [], "planned index.html must not be unexpected");
   assert.deepEqual(audit!.missingFiles, [], "planned index.html must not be missing");
 });
+
+// ─── External engine evidence (claude-code-cli pre-executed tools) ──────────
+// External engines skip beforeToolCall/tool_call, so register-hooks.ts records
+// evidence at tool_execution_start instead. These tests lock the collector
+// semantics that wiring relies on: idempotent recording by toolCallId, and
+// capitalized external tool names (Bash/Write/Edit) being recognized.
+
+test("safety-harness: recordToolCall is idempotent by toolCallId", () => {
+  resetEvidence();
+
+  // Native tools fire tool_execution_start AND tool_call — both record.
+  recordToolCall("tc-dup-1", "bash", { command: "npm test" });
+  recordToolCall("tc-dup-1", "bash", { command: "npm test" });
+
+  assert.equal(getEvidence().length, 1, "same toolCallId must not duplicate");
+});
+
+test("safety-harness: external capitalized Bash call records and resolves evidence", () => {
+  resetEvidence();
+
+  // tool_execution_start with Claude Code's native tool name
+  recordToolCall("ext-bash-1", "Bash", { command: "node /tmp/t01-verify.mjs" });
+  const entries = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(entries.length, 1, "capitalized Bash must be recognized as execution tool");
+  assert.equal(entries[0]!.command, "node /tmp/t01-verify.mjs");
+
+  // tool_execution_end fills the result
+  recordToolResult("ext-bash-1", "Bash", { content: [{ type: "text", text: "13 checks passed" }] }, false);
+  assert.equal(entries[0]!.exitCode, 0, "non-error external result resolves to exitCode 0");
+});
+
+test("safety-harness: external Write call records file evidence", () => {
+  resetEvidence();
+
+  recordToolCall("ext-write-1", "Write", { file_path: "/tmp/app/index.html" });
+  const writes = getEvidence().filter((e) => e.kind === "write");
+  assert.equal(writes.length, 1, "capitalized Write must record file evidence");
+});

package/src/resources/extensions/gsd/tests/session-switch-clears-pending-autostart.test.ts

@@ -0,0 +1,108 @@
+// gsd-pi — A fresh conversation (/clear, /new) must clear pending auto-start.
+//
+// The discuss→auto handoff entry lives in-memory and is consumed on agent_end
+// of the live interview. Once the milestone CONTEXT artifact is saved, the
+// guided-flow staleness heuristic (which requires the CONTEXT file to be
+// absent) can never fire — so a discussion interrupted by /clear left an
+// immortal entry and every subsequent /gsd dead-ended on "Discussion already
+// in progress — answer the question above" with no question above.
+//
+// session_switch with reason "new" means the conversation that contained the
+// interview is gone; the entry must go with it. Reason "resume" restores the
+// interview transcript, so the entry must survive.
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import {
+  setPendingAutoStart,
+  clearPendingAutoStart,
+  _getPendingAutoStart,
+} from "../pending-auto-start.ts";
+
+function makeProjectDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-switch-pas-"));
+  const milestoneDir = join(dir, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  // The post-CONTEXT state that made the entry immortal before the fix.
+  writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# M001 Context\n");
+  return dir;
+}
+
+function fakeCtx(base: string): any {
+  return {
+    cwd: base,
+    ui: {
+      notify: () => undefined,
+      setWidget: () => undefined,
+      setStatus: () => undefined,
+    },
+  };
+}
+
+function armPendingAutoStart(base: string): void {
+  setPendingAutoStart(base, {
+    basePath: base,
+    milestoneId: "M001",
+    ctx: { ui: { notify: () => undefined } } as any,
+    pi: { sendMessage: () => undefined } as any,
+  });
+}
+
+describe("session_switch clears pending auto-start on conversation reset", () => {
+  let base: string;
+  const handlers = new Map<string, Function>();
+
+  beforeEach(() => {
+    clearPendingAutoStart();
+    base = makeProjectDir();
+    handlers.clear();
+    registerHooks({ on(event: string, handler: Function) { handlers.set(event, handler); } } as any, []);
+  });
+
+  afterEach(() => {
+    clearPendingAutoStart();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  async function fireSessionSwitch(reason: "new" | "resume"): Promise<void> {
+    const handler = handlers.get("session_switch");
+    assert.ok(handler, "session_switch handler should be registered");
+    try {
+      await handler({ type: "session_switch", reason, previousSessionFile: undefined }, fakeCtx(base));
+    } catch {
+      // The handler also performs session plumbing (MCP prep, service tier
+      // sync) that may throw against the minimal fake ctx. Pending auto-start
+      // is cleared before that plumbing runs, so the assertions below remain
+      // valid either way.
+    }
+  }
+
+  it('reason "new" (/clear, /new) drops the entry even after CONTEXT was saved', async () => {
+    armPendingAutoStart(base);
+    assert.ok(_getPendingAutoStart(base), "entry should be armed");
+
+    await fireSessionSwitch("new");
+
+    assert.equal(
+      _getPendingAutoStart(base),
+      null,
+      "a fresh conversation destroyed the interview — the handoff entry must not outlive it",
+    );
+  });
+
+  it('reason "resume" keeps the entry (the interview transcript is restored)', async () => {
+    armPendingAutoStart(base);
+
+    await fireSessionSwitch("resume");
+
+    assert.ok(
+      _getPendingAutoStart(base),
+      "resuming restores the interview — the in-flight handoff must survive",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/single-writer-invariant.test.ts

@@ -24,10 +24,24 @@ import { join, relative } from "node:path";
 
 const gsdDir = join(process.cwd(), "src/resources/extensions/gsd");
 
-const ALLOWLIST = new Set([
-  "gsd-db.ts",
-  "unit-ownership.ts",
-]);
+// The single-writer invariant is enforced on a directory layer, not a single
+// filename. Write SQL may live only in:
+//   - db/engine.ts — connection lifecycle, schema/migrations (DDL), and the
+//     BEGIN/COMMIT transaction primitives. The shared handle every writer reads.
+//   - db/writers/**.ts — the Single Writer Layer: one cohesive write subsystem
+//     per file (hierarchy, memory, gates, escalation, reconcile, manifest,
+//     legacy-import, cascades).
+//   - gsd-db.ts — the barrel that re-exports the layer (still holds wrappers
+//     mid-migration).
+//   - unit-ownership.ts — a separate .gsd/unit-claims.db, intentionally outside.
+// db/queries.ts is explicitly NOT allowed write SQL (asserted separately below).
+function isSingleWriterFile(rel: string): boolean {
+  const norm = rel.split("\\").join("/");
+  if (norm === "gsd-db.ts" || norm === "unit-ownership.ts") return true;
+  if (norm === "db/engine.ts") return true;
+  if (norm.startsWith("db/writers/") && norm.endsWith(".ts")) return true;
+  return false;
+}
 
 /** Walk the gsd extension dir and return all .ts files outside tests/. */
 function walkTsFiles(root: string): string[] {
@@ -106,8 +120,7 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
 
   for (const abs of files) {
     const rel = relative(gsdDir, abs);
-    const base = rel.split("/").pop()!;
-    if (ALLOWLIST.has(base)) continue;
+    if (isSingleWriterFile(rel)) continue;
 
     let content: string;
     try {
@@ -154,6 +167,30 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
   }
 });
 
+test("db/queries.ts (the Query Module) is read-only — contains no write SQL", () => {
+  // The read seam is separate from the single-writer layer. queries.ts holds
+  // SELECT-only wrappers so read-only callers depend on a read seam, not the
+  // write surface. (test 1 above also forbids this, since queries.ts is not in
+  // db/writers/ — this is the explicit, positive statement of intent.)
+  const queriesPath = join(gsdDir, "db", "queries.ts");
+  const content = readFileSync(queriesPath, "utf-8");
+  const lines = content.split("\n");
+  const violations: Violation[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = PREPARE_WRITE_RE.exec(line) ?? EXEC_WRITE_RE.exec(line);
+    if (m) {
+      violations.push({ file: "db/queries.ts", line: i + 1, snippet: line.trim(), kind: m[1].toUpperCase() });
+    }
+  }
+  assert.equal(
+    violations.length,
+    0,
+    `db/queries.ts must contain no write SQL — move write wrappers to db/writers/:\n` +
+      violations.map((v) => `  db/queries.ts:${v.line} [${v.kind}] — ${v.snippet}`).join("\n"),
+  );
+});
+
 test("gsd-db.ts exports the expected single-writer wrappers", async () => {
   // Positive assertion — fail loudly if the module layout changes so this
   // structural test can't silently become a no-op.

package/src/resources/extensions/gsd/tests/state-transition-matrix.test.ts

@@ -5,6 +5,8 @@ import {
   STATE_TRANSITION_MATRIX,
   findTransition,
   validateTransitionMatrix,
+  isLegalEdge,
+  IllegalPhaseTransitionError,
 } from "../state-transition-matrix.ts";
 
 test("state transition matrix covers required swarm hardening events", () => {
@@ -42,3 +44,37 @@ test("state transition matrix entries all have guard and reason codes", () => {
     assert.ok(entry.reasonCode.length > 0, `${entry.event} must include reason code`);
   }
 });
+
+// ─── ADR-030: Phase Transition Invariant ───────────────────────────────────
+
+test("isLegalEdge treats a self-edge as trivially legal", () => {
+  assert.equal(isLegalEdge("executing", "executing"), true);
+  assert.equal(isLegalEdge("planning", "planning"), true);
+});
+
+test("isLegalEdge accepts edges enumerated in the matrix", () => {
+  assert.equal(isLegalEdge("planning", "executing"), true);
+  assert.equal(isLegalEdge("executing", "summarizing"), true);
+  assert.equal(isLegalEdge("summarizing", "validating-milestone"), true);
+  assert.equal(isLegalEdge("completing-milestone", "complete"), true);
+});
+
+test("isLegalEdge honors the * wildcard rows (any -> blocked, any -> executing)", () => {
+  assert.equal(isLegalEdge("planning", "blocked"), true);
+  assert.equal(isLegalEdge("summarizing", "executing"), true);
+});
+
+test("isLegalEdge rejects an edge no matrix entry permits", () => {
+  // executing -> complete skips validation — exactly the illegal jump the
+  // invariant exists to catch.
+  assert.equal(isLegalEdge("executing", "complete"), false);
+  assert.equal(isLegalEdge("planning", "summarizing"), false);
+});
+
+test("IllegalPhaseTransitionError carries both endpoints and a descriptive message", () => {
+  const err = new IllegalPhaseTransitionError("executing", "complete");
+  assert.equal(err.from, "executing");
+  assert.equal(err.to, "complete");
+  assert.equal(err.name, "IllegalPhaseTransitionError");
+  assert.match(err.message, /executing -> complete/);
+});

package/src/resources/extensions/gsd/tests/status-guards.test.ts

@@ -9,7 +9,10 @@ import {
   isDeferredStatus,
   isInactiveStatus,
   isSkippedForDispatch,
+  toStatus,
+  RAW_CLOSED_STATUSES,
 } from '../status-guards.ts';
+import { TERMINAL_STATUS_SQL } from '../db/sql-constants.ts';
 
 test('isClosedStatus: "complete" returns true', () => {
   assert.equal(isClosedStatus('complete'), true);
@@ -95,3 +98,38 @@ test('isSkippedForDispatch does NOT skip pending/active/planned', () => {
     assert.equal(isSkippedForDispatch(s), false, `${s} should block dispatch ordering`);
   }
 });
+
+// ─── ADR-030: canonical Status vocabulary + normalization ──────────────────
+
+test('toStatus passes canonical values through unchanged', () => {
+  for (const s of ['pending', 'queued', 'active', 'parked', 'in_progress', 'blocked', 'complete', 'skipped', 'deferred']) {
+    assert.equal(toStatus(s), s, `${s} is canonical and should be returned verbatim`);
+  }
+});
+
+test('toStatus maps known aliases to canonical', () => {
+  assert.equal(toStatus('done'), 'complete');
+  assert.equal(toStatus('closed'), 'complete');
+  assert.equal(toStatus('planned'), 'pending');
+  assert.equal(toStatus('in-progress'), 'in_progress');
+});
+
+test('toStatus trims surrounding whitespace before matching', () => {
+  assert.equal(toStatus('  complete  '), 'complete');
+  assert.equal(toStatus(' done '), 'complete');
+});
+
+test('toStatus quarantines unknown values verbatim (tolerant read, no throw)', () => {
+  assert.equal(toStatus('weird-legacy-value'), 'weird-legacy-value');
+});
+
+test('RAW_CLOSED_STATUSES is the single source: every member is closed', () => {
+  for (const s of RAW_CLOSED_STATUSES) {
+    assert.equal(isClosedStatus(s), true, `${s} is in RAW_CLOSED_STATUSES so must be closed`);
+  }
+});
+
+test('TERMINAL_STATUS_SQL is derived from RAW_CLOSED_STATUSES and renders identically', () => {
+  assert.equal(TERMINAL_STATUS_SQL, "'complete', 'done', 'skipped', 'closed'");
+  assert.equal(TERMINAL_STATUS_SQL, RAW_CLOSED_STATUSES.map((s) => `'${s}'`).join(', '));
+});

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

@@ -142,6 +142,27 @@ 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 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", () => {
@@ -180,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-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) => {

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

@@ -126,7 +126,9 @@ describe("Worktree Safety module", () => {
     assert.equal(result.ok, false);
     assert.equal(result.kind, "invalid-root");
     assert.equal(result.details?.unitRoot, outsideRoot);
-    assert.equal(result.details?.expectedRoot, unitRoot);
+    // The reported expected root is the canonical container; the legacy
+    // .gsd/worktrees/ location is also accepted but not surfaced here.
+    assert.equal(result.details?.expectedRoot, join(projectRoot, ".gsd-worktrees", "M001"));
   });
 
   test("accepts project root for source-writing Unit when isolation mode is none", () => {