gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -16,6 +16,7 @@ import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
@@ -228,6 +229,10 @@ export async function handleCompleteSlice(params, basePath) {
         }
         const slice = getSlice(params.milestoneId, params.sliceId);
         if (slice && isClosedStatus(slice.status)) {
+            if (isStaleWrite("complete-slice")) {
+                guardError = "__stale_duplicate__";
+                return;
+            }
             guardError = `slice ${params.sliceId} is already complete — use gsd_slice_reopen first if you need to redo it`;
             return;
         }
@@ -248,6 +253,22 @@ export async function handleCompleteSlice(params, basePath) {
         insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId });
         updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
     });
+    if (guardError === "__stale_duplicate__") {
+        // Stale duplicate from a turn superseded by timeout recovery. Return a
+        // non-mutating success so the orphaned LLM tool call unwinds quietly.
+        const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+        const staleSummaryPath = sliceDir
+            ? join(sliceDir, `${params.sliceId}-SUMMARY.md`)
+            : join(basePath, ".gsd", "milestones", params.milestoneId, "slices", params.sliceId, `${params.sliceId}-SUMMARY.md`);
+        return {
+            sliceId: params.sliceId,
+            milestoneId: params.milestoneId,
+            summaryPath: staleSummaryPath,
+            uatPath: staleSummaryPath.replace(/-SUMMARY\.md$/, "-UAT.md"),
+            duplicate: true,
+            stale: true,
+        };
+    }
     if (guardError) {
         return { error: guardError };
     }

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -21,6 +21,7 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose
@@ -167,6 +168,18 @@ export async function handleCompleteTask(params, basePath) {
         }
         const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
         if (existingTask && isClosedStatus(existingTask.status)) {
+            // Stale-turn path: a timed-out turn that was superseded by recovery
+            // can still reach this code when its LLM call eventually returns and
+            // invokes gsd_complete_task. Returning an error would produce noisy
+            // "already complete — use reopen first" logs in the orphaned turn.
+            // Instead, signal the duplicate via a non-mutating success shape that
+            // callers can detect via `duplicate: true` / `stale: true`.
+            if (isStaleWrite("complete-task")) {
+                // Sentinel handled below — outside the transaction — so we don't
+                // render SUMMARY.md or flip plan checkboxes for a stale duplicate.
+                guardError = "__stale_duplicate__";
+                return;
+            }
             guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
             return;
         }
@@ -201,6 +214,24 @@ export async function handleCompleteTask(params, basePath) {
             });
         }
     });
+    if (guardError === "__stale_duplicate__") {
+        // Orphaned-turn duplicate: the task is already complete from the
+        // superseded turn's earlier (real) call. Return a non-mutating success
+        // so the stale LLM tool call unwinds cleanly. summaryPath is synthesized
+        // from the existing on-disk layout; no file is written.
+        const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+        const staleSummaryPath = tasksDir
+            ? join(tasksDir, `${params.taskId}-SUMMARY.md`)
+            : join(basePath, ".gsd", "milestones", params.milestoneId, "slices", params.sliceId, "tasks", `${params.taskId}-SUMMARY.md`);
+        return {
+            taskId: params.taskId,
+            sliceId: params.sliceId,
+            milestoneId: params.milestoneId,
+            summaryPath: staleSummaryPath,
+            duplicate: true,
+            stale: true,
+        };
+    }
     if (guardError) {
         return { error: guardError };
     }

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -11,6 +11,7 @@
 import { join } from "node:path";
 import { transaction, insertAssessment, deleteAssessmentByScope, 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";
@@ -59,14 +60,18 @@ export async function handleValidateMilestone(params, basePath, opts) {
         return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
     }
     // ── 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;
-    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/dist/resources/extensions/gsd/uok/audit.js

@@ -1,6 +1,8 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isStaleWrite } from "../auto/turn-epoch.js";
+import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 function auditLogPath(basePath) {
@@ -22,9 +24,23 @@ export function buildAuditEnvelope(args) {
     };
 }
 export function emitUokAuditEvent(basePath, event) {
+    // Drop writes from a turn superseded by timeout recovery / cancellation.
+    if (isStaleWrite("uok-audit"))
+        return;
     try {
         ensureAuditDir(basePath);
-        appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+        const path = auditLogPath(basePath);
+        // proper-lockfile requires the target file to exist before locking.
+        // Touch it via open(O_APPEND|O_CREAT) so the first writer wins the race
+        // atomically at the kernel level.
+        if (!existsSync(path))
+            closeSync(openSync(path, "a"));
+        // onLocked: "skip" — audit writes are best-effort; under heavy contention
+        // POSIX O_APPEND atomicity still protects small line writes, so skipping
+        // the lock rather than stalling orchestration is the correct tradeoff.
+        withFileLockSync(path, () => {
+            appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        }, { onLocked: "skip" });
     }
     catch {
         // Best-effort: audit writes must never break orchestration.

package/dist/resources/extensions/gsd/uok/dispatch-envelope.js

@@ -0,0 +1,33 @@
+export function buildDispatchEnvelope(input) {
+    return {
+        action: input.action,
+        nodeKind: input.node?.kind,
+        unitType: input.unitType,
+        unitId: input.unitId,
+        prompt: input.prompt,
+        reason: {
+            reasonCode: input.reasonCode,
+            summary: input.summary,
+            evidence: input.evidence,
+            blockedBy: input.blockedBy,
+        },
+        gateVerdict: input.gateVerdict,
+        constraints: input.node
+            ? {
+                reads: input.node.reads,
+                writes: input.node.writes,
+                dependsOn: input.node.dependsOn,
+            }
+            : undefined,
+        trace: input.trace,
+    };
+}
+export function explainDispatch(envelope) {
+    const subject = envelope.unitType && envelope.unitId
+        ? `${envelope.unitType} ${envelope.unitId}`
+        : envelope.nodeKind ?? envelope.action;
+    const blocked = envelope.reason.blockedBy && envelope.reason.blockedBy.length > 0
+        ? ` Blocked by: ${envelope.reason.blockedBy.map((b) => `${b.kind}:${b.id}`).join(", ")}.`
+        : "";
+    return `[${envelope.reason.reasonCode}] ${subject}: ${envelope.reason.summary}.${blocked}`;
+}

package/dist/resources/extensions/gsd/uok/execution-graph.js

@@ -68,6 +68,16 @@ export function buildSidecarQueueNodes(queue) {
         metadata: { index },
     }));
 }
+export function buildExecutionGraphSnapshot(nodes, phase) {
+    const sorted = topologicalSort(nodes);
+    return {
+        capturedAt: new Date().toISOString(),
+        phase,
+        nodes: sorted,
+        order: sorted.map((node) => node.id),
+        conflicts: detectFileConflicts(nodes),
+    };
+}
 export async function scheduleSidecarQueue(queue) {
     if (queue.length <= 1)
         return [...queue];

package/dist/resources/extensions/gsd/uok/gitops.js

@@ -32,7 +32,7 @@ export function writeTurnGitTransaction(args) {
         },
     }));
 }
-export function writeTurnCloseoutGitRecord(basePath, record) {
+export function writeTurnCloseoutGitRecord(basePath, record, metadata) {
     writeTurnGitTransaction({
         basePath,
         traceId: record.traceId,
@@ -45,6 +45,7 @@ export function writeTurnCloseoutGitRecord(basePath, record) {
         status: record.failureClass === "git" ? "failed" : "ok",
         error: record.failureClass === "git" ? "git closeout failure" : undefined,
         metadata: {
+            ...(metadata ?? {}),
             turnStatus: record.status,
             finishedAt: record.finishedAt,
             activityFile: record.activityFile,

package/dist/resources/extensions/gsd/uok/loop-adapter.js

@@ -1,12 +1,35 @@
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
 export function createTurnObserver(options) {
     let current = null;
+    let writerToken = null;
     const phaseResults = [];
+    function nextSequenceMetadata(category, operation, metadata) {
+        if (!writerToken)
+            return metadata ?? {};
+        const record = nextWriteRecord({
+            basePath: options.basePath,
+            token: writerToken,
+            category,
+            operation,
+            metadata,
+        });
+        return {
+            ...(metadata ?? {}),
+            writeSequence: record.sequence.sequence,
+            writerTokenId: record.writerToken.tokenId,
+        };
+    }
     return {
         onTurnStart(contract) {
             current = contract;
             phaseResults.length = 0;
+            writerToken = acquireWriterToken({
+                basePath: options.basePath,
+                traceId: contract.traceId,
+                turnId: contract.turnId,
+            });
             if (options.enableGitops) {
                 writeTurnGitTransaction({
                     basePath: options.basePath,
@@ -18,10 +41,10 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: {
+                    metadata: nextSequenceMetadata("gitops", "insert", {
                         iteration: contract.iteration,
                         sidecarKind: contract.sidecarKind,
-                    },
+                    }),
                 });
             }
             if (options.enableAudit) {
@@ -30,12 +53,12 @@ export function createTurnObserver(options) {
                     turnId: contract.turnId,
                     category: "orchestration",
                     type: "turn-start",
-                    payload: {
+                    payload: nextSequenceMetadata("audit", "append", {
                         iteration: contract.iteration,
                         unitType: contract.unitType,
                         unitId: contract.unitId,
                         sidecarKind: contract.sidecarKind,
-                    },
+                    }),
                 }));
             }
         },
@@ -59,7 +82,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
             if (phase === "unit") {
@@ -73,7 +96,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
             if (phase === "finalize") {
@@ -87,7 +110,7 @@ export function createTurnObserver(options) {
                     action: options.gitAction,
                     push: options.gitPush,
                     status: "ok",
-                    metadata: { action },
+                    metadata: nextSequenceMetadata("gitops", "update", { action }),
                 });
             }
         },
@@ -102,14 +125,14 @@ export function createTurnObserver(options) {
                     turnId: merged.turnId,
                     category: "orchestration",
                     type: "turn-result",
-                    payload: {
+                    payload: nextSequenceMetadata("audit", "append", {
                         unitType: merged.unitType,
                         unitId: merged.unitId,
                         status: merged.status,
                         failureClass: merged.failureClass,
                         error: merged.error,
                         phaseCount: merged.phaseResults.length,
-                    },
+                    }),
                 }));
             }
             if (options.enableGitops) {
@@ -124,8 +147,12 @@ export function createTurnObserver(options) {
                     gitPushed: options.gitPush,
                     finishedAt: merged.finishedAt,
                 };
-                writeTurnCloseoutGitRecord(options.basePath, closeout);
+                writeTurnCloseoutGitRecord(options.basePath, closeout, nextSequenceMetadata("gitops", "update", { action: "record" }));
+            }
+            if (writerToken) {
+                releaseWriterToken(options.basePath, writerToken);
             }
+            writerToken = null;
             current = null;
             phaseResults.length = 0;
         },

package/dist/resources/extensions/gsd/uok/parity-report.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "../paths.js";
+function parityLogPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+function reportPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-parity-report.json");
+}
+function increment(bucket, key) {
+    const normalized = key && key.trim().length > 0 ? key : "unknown";
+    bucket[normalized] = (bucket[normalized] ?? 0) + 1;
+}
+export function parseParityEvents(raw) {
+    return raw
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return { status: "error", error: "invalid parity json line" };
+        }
+    });
+}
+export function buildParityReport(events, sourcePath) {
+    const paths = {};
+    const statuses = {};
+    const criticalMismatches = [];
+    let fallbackInvocations = 0;
+    for (const event of events) {
+        increment(paths, event.path);
+        increment(statuses, event.status);
+        if (event.path === "legacy-fallback")
+            fallbackInvocations += 1;
+        if (event.status === "error") {
+            criticalMismatches.push(event.error ?? "parity event reported error");
+        }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        sourcePath,
+        totalEvents: events.length,
+        paths,
+        statuses,
+        criticalMismatches,
+        fallbackInvocations,
+    };
+}
+export function writeParityReport(basePath) {
+    const sourcePath = parityLogPath(basePath);
+    const raw = existsSync(sourcePath) ? readFileSync(sourcePath, "utf-8") : "";
+    const report = buildParityReport(parseParityEvents(raw), sourcePath);
+    mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+    writeFileSync(reportPath(basePath), JSON.stringify(report, null, 2) + "\n", "utf-8");
+    return report;
+}

package/dist/resources/extensions/gsd/uok/plan-v2.js

@@ -3,12 +3,15 @@ import { join } from "node:path";
 import { gsdRoot, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;
-const EXECUTION_ENTRY_PHASES = new Set([
+export const EXECUTION_ENTRY_PHASES = new Set([
     "executing",
     "summarizing",
     "validating-milestone",
     "completing-milestone",
 ]);
+export function isExecutionEntryPhase(phase) {
+    return EXECUTION_ENTRY_PHASES.has(phase);
+}
 function graphOutputPath(basePath) {
     return join(gsdRoot(basePath), "runtime", "uok-plan-v2-graph.json");
 }
@@ -39,6 +42,12 @@ function hasMilestoneFileContent(basePath, milestoneId, suffix) {
     }
     return false;
 }
+export function hasFinalizedMilestoneContext(basePath, milestoneId) {
+    return hasMilestoneFileContent(basePath, milestoneId, "CONTEXT");
+}
+export function isMissingFinalizedContextResult(result) {
+    return !result.ok && result.finalizedContextIncluded === false;
+}
 function countSliceResearchArtifacts(basePath, milestoneId, slices) {
     let count = 0;
     for (const slice of slices) {
@@ -48,9 +57,6 @@ function countSliceResearchArtifacts(basePath, milestoneId, slices) {
     }
     return count;
 }
-function isExecutionEntryPhase(phase) {
-    return EXECUTION_ENTRY_PHASES.has(phase);
-}
 export function compileUnitGraphFromState(basePath, state) {
     const mid = state.activeMilestone?.id;
     if (!mid)

package/dist/resources/extensions/gsd/uok/writer.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { atomicWriteSync } from "../atomic-write.js";
+import { gsdRoot } from "../paths.js";
+const activeTokens = new Map();
+function tokenKey(basePath, turnId) {
+    return `${basePath}:${turnId}`;
+}
+function sequencePath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "uok-writer-sequence.json");
+}
+function readSequenceState(basePath) {
+    const path = sequencePath(basePath);
+    if (!existsSync(path)) {
+        return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        return {
+            lastSequence: Number.isInteger(parsed.lastSequence) ? Number(parsed.lastSequence) : 0,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+    }
+}
+function writeSequenceState(basePath, state) {
+    atomicWriteSync(sequencePath(basePath), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+export function acquireWriterToken(args) {
+    const key = tokenKey(args.basePath, args.turnId);
+    const existing = activeTokens.get(key);
+    if (existing) {
+        throw new Error(`Writer token already active for turn ${args.turnId}`);
+    }
+    const token = {
+        tokenId: randomUUID(),
+        traceId: args.traceId,
+        turnId: args.turnId,
+        acquiredAt: new Date().toISOString(),
+        owner: args.owner ?? "uok",
+    };
+    activeTokens.set(key, token);
+    return token;
+}
+export function releaseWriterToken(basePath, token) {
+    const key = tokenKey(basePath, token.turnId);
+    const current = activeTokens.get(key);
+    if (current?.tokenId === token.tokenId) {
+        activeTokens.delete(key);
+    }
+}
+export function hasActiveWriterToken(basePath, turnId) {
+    return activeTokens.has(tokenKey(basePath, turnId));
+}
+export function nextWriteRecord(args) {
+    if (!hasActiveWriterToken(args.basePath, args.token.turnId)) {
+        throw new Error(`Writer token is not active for turn ${args.token.turnId}`);
+    }
+    const state = readSequenceState(args.basePath);
+    const sequence = state.lastSequence + 1;
+    const updatedAt = new Date().toISOString();
+    writeSequenceState(args.basePath, { lastSequence: sequence, updatedAt });
+    return {
+        writerToken: args.token,
+        sequence: {
+            traceId: args.token.traceId,
+            turnId: args.token.turnId,
+            sequence,
+        },
+        category: args.category,
+        operation: args.operation,
+        path: args.path,
+        ts: updatedAt,
+        metadata: args.metadata,
+    };
+}
+export function resetWriterTokensForTests() {
+    activeTokens.clear();
+}

package/dist/resources/extensions/gsd/workflow-logger.js

@@ -15,8 +15,9 @@
 // a process. The auto-loop must call _resetLogs() (or drainAndSummarize()) at
 // the start of each unit to prevent log bleed between units running in the same
 // Node process.
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, } from "node:fs";
 import { join } from "node:path";
+import { withFileLockSync } from "./file-lock.js";
 import { appendNotification } from "./notification-store.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -231,8 +232,15 @@ function _push(severity, component, message, context) {
         try {
             const auditDir = join(_auditBasePath, ".gsd");
             mkdirSync(auditDir, { recursive: true });
+            const auditPath = join(auditDir, "audit-log.jsonl");
             const sanitized = _sanitizeForAudit(entry);
-            appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(sanitized) + "\n", "utf-8");
+            // Ensure file exists so proper-lockfile can acquire a lock against it.
+            if (!existsSync(auditPath))
+                closeSync(openSync(auditPath, "a"));
+            // onLocked: "skip" — never block error logging on lock contention.
+            withFileLockSync(auditPath, () => {
+                appendFileSync(auditPath, JSON.stringify(sanitized) + "\n", "utf-8");
+            }, { onLocked: "skip" });
         }
         catch (auditErr) {
             // Best-effort — never let audit write failures bubble up

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -20,6 +20,7 @@ import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
+import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -84,6 +85,56 @@ export function isInsideWorktreesDir(basePath, targetPath) {
     // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
     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, milestoneId) {
+    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 ───────────────────────────────────────────────────────
 /**
  * Create a new git worktree under .gsd/worktrees/<name>/ with branch worktree/<name>.
@@ -479,6 +530,7 @@ const SKIP_PATHS = [
     ".gsd/worktrees/",
     ".gsd/runtime/",
     ".gsd/activity/",
+    ".gsd/audit/",
     ".gsd/forensics/",
     ".gsd/parallel/",
     ".gsd/journal/",