gsd-pi 2.77.0-dev.1d17f366c → 2.77.0-dev.58d3d4d6c

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

@@ -59,3 +59,143 @@ export function createTestContext() {
 
   return { assertEq, assertTrue, assertMatch, assertNoMatch, report };
 }
+
+// ─── Source-inspection helpers ────────────────────────────────────────────────
+//
+// Replace brittle fixed-byte slice patterns like `src.slice(idx, idx + 6000)`
+// with structural boundary detection. See #4773, #4774.
+
+/**
+ * Extract a region of source between a start anchor and either an explicit
+ * end anchor or, if none is given, a set of reasonable structural
+ * terminators (next `private `/`export `/`function `/`class `/`interface `/
+ * `//` section separator). Falls back to end-of-source if none match.
+ *
+ * Use this instead of `src.slice(startIdx, startIdx + N)` when searching
+ * for patterns within a specific method or region — the start anchor is
+ * what the caller already has, and the end is determined by structure,
+ * not by a magic byte count that breaks under refactors.
+ *
+ * @param src        The source text.
+ * @param startAnchor Literal substring that marks the start of the region.
+ *                   Typically a function name, a section header comment, or
+ *                   a distinctive statement.
+ * @param endAnchor  Optional. Either a literal substring that marks the end,
+ *                   or `{ fromIdx: number }` to find the *next* occurrence
+ *                   of `startAnchor` at or after `fromIdx` (useful when the
+ *                   anchor appears multiple times and a positional search
+ *                   is required). When omitted, structural terminators are
+ *                   used.
+ *
+ * Returns the extracted region (including the start anchor), or an empty
+ * string if `startAnchor` is not found.
+ */
+export function extractSourceRegion(
+  src: string,
+  startAnchor: string,
+  endAnchor?: string | { fromIdx: number },
+): string {
+  const fromIdx = typeof endAnchor === "object" && endAnchor !== null
+    ? endAnchor.fromIdx
+    : 0;
+  const endLiteral = typeof endAnchor === "string" ? endAnchor : undefined;
+
+  const startIdx = src.indexOf(startAnchor, fromIdx);
+  if (startIdx < 0) return "";
+
+  if (endLiteral) {
+    const endIdx = src.indexOf(endLiteral, startIdx + startAnchor.length);
+    return endIdx > 0 ? src.slice(startIdx, endIdx) : src.slice(startIdx);
+  }
+
+  // Heuristic terminators — the next sibling declaration/section.
+  const terminators = [
+    "\n  private ",
+    "\n  public ",
+    "\n  protected ",
+    "\n  static ",
+    "\nexport function ",
+    "\nexport async function ",
+    "\nfunction ",
+    "\nasync function ",
+    "\nexport class ",
+    "\nclass ",
+    "\nexport interface ",
+    "\ninterface ",
+    "\n// ─", // section separator comments
+    "\n/** ", // next docblock
+  ];
+
+  let earliestEnd = -1;
+  for (const t of terminators) {
+    const idx = src.indexOf(t, startIdx + startAnchor.length);
+    if (idx > 0 && (earliestEnd < 0 || idx < earliestEnd)) earliestEnd = idx;
+  }
+
+  return earliestEnd > 0 ? src.slice(startIdx, earliestEnd) : src.slice(startIdx);
+}
+
+/**
+ * Poll `condition()` until it returns truthy or `timeoutMs` elapses.
+ * Returns the truthy value from `condition()`, or throws on timeout.
+ *
+ * Use this instead of `await new Promise(r => setTimeout(r, <magic-ms>))`
+ * when waiting for a state change that tests produce. The fixed-sleep
+ * pattern is flaky: too short → race; too long → slow tests.
+ *
+ * @param condition  Predicate. Returns truthy when done. May be async.
+ * @param opts.timeoutMs  Max total wait. Defaults to 2000ms.
+ * @param opts.intervalMs Poll interval. Defaults to 10ms.
+ * @param opts.description Included in the timeout error for debuggability.
+ */
+export async function waitForCondition<T>(
+  condition: () => T | Promise<T>,
+  opts: { timeoutMs?: number; intervalMs?: number; description?: string } = {},
+): Promise<T> {
+  const timeoutMs = opts.timeoutMs ?? 2000;
+  const intervalMs = opts.intervalMs ?? 10;
+  const deadline = Date.now() + timeoutMs;
+  let lastErr: unknown;
+  while (Date.now() < deadline) {
+    try {
+      const result = await condition();
+      if (result) return result;
+    } catch (e) {
+      lastErr = e;
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  const desc = opts.description ?? "condition";
+  const errSuffix = lastErr instanceof Error ? ` (last error: ${lastErr.message})` : "";
+  throw new Error(`waitForCondition timed out after ${timeoutMs}ms waiting for ${desc}${errSuffix}`);
+}
+
+/**
+ * Find the first line in rendered output that matches a predicate. Returns
+ * the line's index and text, or throws if no line matches.
+ *
+ * Use this instead of `lines[N]` indexing when the N is positional and
+ * could shift under formatting changes.
+ */
+export function findLine(
+  output: string,
+  predicate: RegExp | ((line: string) => boolean),
+): { index: number; text: string } {
+  const lines = output.split("\n");
+  const fn = predicate instanceof RegExp
+    ? (l: string) => {
+        // RegExp.test is stateful when the pattern has /g or /y flags
+        // (maintains lastIndex across calls). Reset before each test so
+        // matches on different lines don't silently skip.
+        if (predicate.global || predicate.sticky) predicate.lastIndex = 0;
+        return predicate.test(l);
+      }
+    : predicate;
+  for (let i = 0; i < lines.length; i++) {
+    if (fn(lines[i]!)) return { index: i, text: lines[i]! };
+  }
+  const preview = lines.slice(0, 10).join("\n");
+  throw new Error(
+    `findLine: no line matched. First 10 lines were:\n${preview}`,
+  );
+}

package/src/resources/extensions/gsd/tests/token-profile.test.ts

@@ -14,6 +14,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -127,7 +128,13 @@ test("profile: balanced profile skips research, reassess, and slice research (AD
 
 test("profile: quality profile skips research, slice research, and reassess (ADR-003)", () => {
   const qualityIdx = preferencesSrc.indexOf('case "quality":');
-  const qualityBlock = preferencesSrc.slice(qualityIdx, qualityIdx + 300);
+  // preferencesSrc is concatenated from multiple modules — bound the region
+  // with the next case marker so the assertion stays tightly scoped.
+  const qualityBlock = extractSourceRegion(
+    preferencesSrc,
+    'case "quality":',
+    'case "burn-max":',
+  );
   assert.ok(qualityBlock.includes("skip_research: true"), "quality should skip research");
   assert.ok(qualityBlock.includes("skip_slice_research: true"), "quality should skip slice research");
   assert.ok(qualityBlock.includes("skip_reassess: true"), "quality should skip reassess");

package/src/resources/extensions/gsd/tests/verify-artifact-tightened.test.ts

@@ -15,6 +15,7 @@ import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const src = readFileSync(
   resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'auto-recovery.ts'),
@@ -28,7 +29,7 @@ describe('verifyExpectedArtifact legacy branch tightened (#3607)', () => {
     assert.ok(legacyIdx !== -1, 'LEGACY comment must exist')
 
     // Check the code within a reasonable window after the LEGACY comment
-    const legacyBlock = src.slice(legacyIdx, legacyIdx + 600)
+    const legacyBlock = extractSourceRegion(src, 'LEGACY: Pre-migration fallback')
 
     assert.ok(
       !legacyBlock.includes('hdRe'),
@@ -40,7 +41,7 @@ describe('verifyExpectedArtifact legacy branch tightened (#3607)', () => {
     const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback')
     assert.ok(legacyIdx !== -1)
 
-    const legacyBlock = src.slice(legacyIdx, legacyIdx + 600)
+    const legacyBlock = extractSourceRegion(src, 'LEGACY: Pre-migration fallback')
 
     assert.ok(
       legacyBlock.includes('cbRe'),
@@ -58,7 +59,7 @@ describe('verifyExpectedArtifact legacy branch tightened (#3607)', () => {
     const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback')
     assert.ok(legacyIdx !== -1)
 
-    const legacyBlock = src.slice(legacyIdx, legacyIdx + 1000)
+    const legacyBlock = extractSourceRegion(src, 'LEGACY: Pre-migration fallback')
 
     // The else branch: no plan file means cannot verify
     assert.ok(
@@ -71,7 +72,7 @@ describe('verifyExpectedArtifact legacy branch tightened (#3607)', () => {
     const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback')
     assert.ok(legacyIdx !== -1)
 
-    const legacyBlock = src.slice(legacyIdx, legacyIdx + 1000)
+    const legacyBlock = extractSourceRegion(src, 'LEGACY: Pre-migration fallback')
 
     assert.ok(
       legacyBlock.includes('DB available but task row not found'),
@@ -80,7 +81,7 @@ describe('verifyExpectedArtifact legacy branch tightened (#3607)', () => {
 
     // The comment should be followed by a return false
     const commentIdx = legacyBlock.indexOf('DB available but task row not found')
-    const afterComment = legacyBlock.slice(commentIdx, commentIdx + 200)
+    const afterComment = extractSourceRegion(legacyBlock, 'DB available but task row not found')
     assert.ok(
       afterComment.includes('return false'),
       'missing task row when DB available must return false',

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

@@ -8,7 +8,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -22,7 +22,7 @@ console.log("\n=== #2347: Worktree health check supports monorepos ===");
 const healthCheckIdx = src.indexOf("Worktree health check");
 assertTrue(healthCheckIdx > 0, "auto/phases.ts has worktree health check section");
 
-const healthCheckRegion = src.slice(healthCheckIdx, healthCheckIdx + 2000);
+const healthCheckRegion = extractSourceRegion(src, "Worktree health check");
 
 // ── Test 2: The check walks parent directories for project markers ──────
 

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

@@ -13,7 +13,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -27,7 +27,7 @@ console.log("\n=== #2616: Worktree cleanup detects nested .git directories ===")
 const removeWorktreeIdx = src.indexOf("export function removeWorktree");
 assertTrue(removeWorktreeIdx > 0, "worktree-manager.ts exports removeWorktree");
 
-const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 5000);
+const fnBody = extractSourceRegion(src, "export function removeWorktree");
 
 const detectsNestedGit =
   fnBody.includes("nested") && fnBody.includes(".git") ||

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

@@ -8,7 +8,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -22,7 +22,7 @@ console.log("\n=== #2337: Worktree teardown preserves submodule state ===");
 const removeWorktreeIdx = src.indexOf("export function removeWorktree");
 assertTrue(removeWorktreeIdx > 0, "worktree-manager.ts exports removeWorktree");
 
-const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 6000);
+const fnBody = extractSourceRegion(src, "export function removeWorktree");
 
 // ── Test 2: The function checks for submodules before force removal ─────
 

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

@@ -0,0 +1,210 @@
+/**
+ * Tests for worktree telemetry — #4764.
+ *
+ * Covers emit helpers (writing to the journal) and the aggregator
+ * (summarizeWorktreeTelemetry).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import {
+  emitWorktreeCreated,
+  emitWorktreeMerged,
+  emitWorktreeOrphaned,
+  emitAutoExit,
+  emitCanonicalRootRedirect,
+  summarizeWorktreeTelemetry,
+  percentile,
+} from "../worktree-telemetry.ts";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.ts";
+import { queryJournal } from "../journal.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-tel-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+test("emitWorktreeCreated writes a worktree-created journal event", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeCreated(base, "M001", { reason: "create-milestone" });
+    const entries = queryJournal(base, { eventType: "worktree-created" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M001");
+    assert.equal(entries[0].data?.reason, "create-milestone");
+    assert.ok(typeof entries[0].data?.startedAt === "string");
+  } finally { cleanup(base); }
+});
+
+test("emitWorktreeMerged records duration and conflict fields", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeMerged(base, "M001", {
+      reason: "milestone-complete",
+      durationMs: 1234,
+      sliceCount: 3,
+      taskCount: 9,
+      conflict: false,
+    });
+    const entries = queryJournal(base, { eventType: "worktree-merged" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M001");
+    assert.equal(entries[0].data?.durationMs, 1234);
+    assert.equal(entries[0].data?.sliceCount, 3);
+    assert.equal(entries[0].data?.conflict, false);
+  } finally { cleanup(base); }
+});
+
+test("emitWorktreeOrphaned captures reason and commits-ahead", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeOrphaned(base, "M002", {
+      reason: "in-progress-unmerged",
+      commitsAhead: 4,
+      worktreeDirExists: true,
+    });
+    const entries = queryJournal(base, { eventType: "worktree-orphaned" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M002");
+    assert.equal(entries[0].data?.reason, "in-progress-unmerged");
+    assert.equal(entries[0].data?.commitsAhead, 4);
+    assert.equal(entries[0].data?.worktreeDirExists, true);
+  } finally { cleanup(base); }
+});
+
+test("emitAutoExit records reason and unmerged-work signal", () => {
+  const base = makeTmpBase();
+  try {
+    emitAutoExit(base, {
+      reason: "pause",
+      milestoneId: "M003",
+      milestoneMerged: false,
+    });
+    const entries = queryJournal(base, { eventType: "auto-exit" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.reason, "pause");
+    assert.equal(entries[0].data?.milestoneMerged, false);
+  } finally { cleanup(base); }
+});
+
+test("summarizeWorktreeTelemetry aggregates events correctly", () => {
+  const base = makeTmpBase();
+  try {
+    // Two created, one merged, two orphans (different reasons), three exits,
+    // two of which left work unmerged.
+    emitWorktreeCreated(base, "M001");
+    emitWorktreeCreated(base, "M002");
+
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", durationMs: 500, conflict: false });
+
+    emitWorktreeOrphaned(base, "M002", { reason: "in-progress-unmerged", commitsAhead: 2 });
+    emitWorktreeOrphaned(base, "M003", { reason: "complete-unmerged" });
+
+    emitAutoExit(base, { reason: "pause", milestoneId: "M002", milestoneMerged: false });
+    emitAutoExit(base, { reason: "stop", milestoneId: "M002", milestoneMerged: false });
+    emitAutoExit(base, { reason: "all-complete", milestoneId: "M001", milestoneMerged: true });
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.worktreesCreated, 2);
+    assert.equal(summary.worktreesMerged, 1);
+    assert.equal(summary.orphansDetected, 2);
+    assert.deepStrictEqual(summary.orphansByReason, {
+      "in-progress-unmerged": 1,
+      "complete-unmerged": 1,
+    });
+    assert.deepStrictEqual(summary.mergeDurationsMs, [500]);
+    assert.equal(summary.mergeConflicts, 0);
+    assert.deepStrictEqual(summary.exitsByReason, {
+      "pause": 1,
+      "stop": 1,
+      "all-complete": 1,
+    });
+    assert.equal(summary.exitsWithUnmergedWork, 2, "pause and stop each left work unmerged");
+  } finally { cleanup(base); }
+});
+
+test("summarizeWorktreeTelemetry counts merge conflicts", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", durationMs: 100, conflict: false });
+    emitWorktreeMerged(base, "M002", { reason: "milestone-complete", durationMs: 200, conflict: true, conflictedFiles: 3 });
+    emitWorktreeMerged(base, "M003", { reason: "milestone-complete", durationMs: 150, conflict: false });
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.worktreesMerged, 3);
+    assert.equal(summary.mergeConflicts, 1);
+    // Durations are sorted
+    assert.deepStrictEqual(summary.mergeDurationsMs, [100, 150, 200]);
+  } finally { cleanup(base); }
+});
+
+test("resolveCanonicalMilestoneRoot emits canonical-root-redirect on redirect", () => {
+  const base = makeTmpBase();
+  try {
+    // Create the live-worktree shape the resolver looks for
+    const wtDir = join(base, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(base, ".git", "worktrees", "M001")}\n`);
+
+    const result = resolveCanonicalMilestoneRoot(base, "M001");
+    assert.equal(result, wtDir);
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.canonicalRedirects, 1, "redirect should emit exactly one event");
+  } finally { cleanup(base); }
+});
+
+test("resolveCanonicalMilestoneRoot emits nothing when it doesn't redirect", () => {
+  const base = makeTmpBase();
+  try {
+    const result = resolveCanonicalMilestoneRoot(base, "M999");
+    assert.equal(result, base);
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.canonicalRedirects, 0, "no worktree → no redirect event");
+  } finally { cleanup(base); }
+});
+
+test("percentile helper returns quantiles of a sorted array (nearest-rank)", () => {
+  assert.equal(percentile([], 0.5), null);
+  assert.equal(percentile([10], 0.5), 10);
+  // Boundary behavior
+  assert.equal(percentile([10, 20, 30, 40], 0), 10);
+  assert.equal(percentile([10, 20, 30, 40], 1), 40);
+  // Nearest-rank: idx = ceil(q*n) - 1
+  // q=0.5, n=4 → idx = 2-1 = 1 → 20
+  assert.equal(percentile([10, 20, 30, 40], 0.5), 20);
+  // p95 on 20 values = idx ceil(0.95*20)-1 = 19-1 = 18 → value at index 18 (19th sample)
+  const twenty = Array.from({ length: 20 }, (_, i) => (i + 1) * 10); // [10..200]
+  assert.equal(percentile(twenty, 0.95), 190, "p95 should be the 19th of 20 sorted values, not the max");
+});
+
+test("summarizeWorktreeTelemetry supports time-window filtering", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeCreated(base, "M001");
+    const midpoint = new Date().toISOString();
+    // Brief delay to ensure the next event has a later ts
+    const start = Date.now();
+    while (Date.now() - start < 10) { /* spin */ }
+    emitWorktreeCreated(base, "M002");
+
+    const beforeOnly = summarizeWorktreeTelemetry(base, { before: midpoint });
+    const afterOnly = summarizeWorktreeTelemetry(base, { after: midpoint });
+    // The sum of the two partitions covers all events (may overlap by 1 at
+    // exact-ts boundary — assert each partition is a proper subset).
+    assert.ok(beforeOnly.worktreesCreated >= 1);
+    assert.ok(afterOnly.worktreesCreated >= 1);
+    assert.ok(beforeOnly.worktreesCreated + afterOnly.worktreesCreated >= 2);
+  } finally { cleanup(base); }
+});

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

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
 
@@ -26,7 +26,7 @@ assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry");
 
 // Extract the region between showSmartEntry and the first showProjectInit call
 // This is where the init wizard gate lives.
-const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : "";
+const afterSmartEntry = smartEntryIdx >= 0 ? extractSourceRegion(guidedFlowSrc, "export async function showSmartEntry(") : "";
 
 // The gate must NOT be a bare `!existsSync(gsdRoot(basePath))` check.
 // It must also verify that bootstrap artifacts (PREFERENCES.md or milestones/) exist.
@@ -48,7 +48,7 @@ assertTrue(
 // Find the specific init wizard gate pattern — the detection preamble block.
 const detectionPreambleIdx = afterSmartEntry.indexOf("Detection preamble");
 const detectionRegion = detectionPreambleIdx >= 0
-  ? afterSmartEntry.slice(detectionPreambleIdx, detectionPreambleIdx + 600)
+  ? extractSourceRegion(afterSmartEntry, "Detection preamble")
   : afterSmartEntry.slice(0, 1500);
 
 // The gate condition must reference PREFERENCES.md or milestones (bootstrap artifacts)

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -18,6 +18,7 @@ import {
   getMilestoneSlices,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -100,14 +101,19 @@ export async function handleValidateMilestone(
   }
 
   // ── Resolve paths and render markdown ────────────────────────────────
+  // #4761: route through the canonical-root resolver so that when a live
+  // worktree exists for this milestone, validation reads/writes the
+  // worktree's artifacts instead of stale project-root state.
   const validationMd = renderValidationMarkdown(params);
 
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
+
   let validationPath: string;
-  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
   if (milestoneDir) {
     validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
   } else {
-    const gsdDir = join(basePath, ".gsd");
+    const gsdDir = join(canonicalBase, ".gsd");
     const manualDir = join(gsdDir, "milestones", params.milestoneId);
     validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
   }

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

@@ -37,6 +37,7 @@ import {
   nativeWorktreePrune,
   nativeWorktreeRemove,
 } from "./native-git-bridge.js";
+import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -132,6 +133,58 @@ export function isInsideWorktreesDir(basePath: string, targetPath: string): bool
   return resolved === wtDir || resolved.startsWith(wtDir + sep);
 }
 
+/**
+ * Return the canonical path from which a milestone's artifacts should be read.
+ *
+ * If a live git worktree exists for this milestone at `.gsd/worktrees/<MID>/`
+ * (directory present AND a `.git` file indicating a registered worktree),
+ * returns that worktree path. Otherwise returns `basePath` unchanged.
+ *
+ * Readers that cross the session/worktree boundary (validators, the bootstrap
+ * audit, cross-session state queries) should route through this helper so they
+ * don't silently read stale project-root state while live work sits in the
+ * worktree. Writers and tools whose contract is "operate on the path I was
+ * given" should NOT use this helper — they preserve the legacy behavior.
+ *
+ * A stale worktree directory (no `.git` file) is treated as absent. The
+ * createWorktree() path already cleans these up, but readers must not trust
+ * them in the window before cleanup runs.
+ *
+ * Fixes #4761. Used by the #4762 audit for the pre-completion orphan case.
+ */
+export function resolveCanonicalMilestoneRoot(
+  basePath: string,
+  milestoneId: string,
+): string {
+  if (!milestoneId || /[\/\\]|\.\./.test(milestoneId)) return basePath;
+
+  const wtPath = worktreePath(basePath, milestoneId);
+  if (!existsSync(wtPath)) return basePath;
+
+  // A registered git worktree has a .git *file* (not directory) containing
+  // "gitdir: <path>". A standalone .git directory indicates a copied repo
+  // or nested standalone repo — not a worktree registered with this project —
+  // and must not be treated as the canonical root.
+  const gitPath = join(wtPath, ".git");
+  if (!existsSync(gitPath)) return basePath;
+  try {
+    const stat = lstatSync(gitPath);
+    if (!stat.isFile()) return basePath;
+  } catch {
+    return basePath;
+  }
+
+  // #4764 — record the redirect so we can measure how often the #4761 fix
+  // would have mattered. Best-effort; emit is silent on any failure.
+  try {
+    emitCanonicalRootRedirect(basePath, milestoneId, wtPath);
+  } catch (err) {
+    logWarning("worktree", `canonical-root-redirect telemetry failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return wtPath;
+}
+
 // ─── Core Operations ───────────────────────────────────────────────────────
 
 /**