gsd-pi 2.80.0 → 2.81.0

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

@@ -22,6 +22,16 @@ import { logWarning } from "./workflow-logger.js";
 import { nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+function deleteBranchIfPresent(basePath, branch, warningPrefix) {
+    try {
+        if (!nativeBranchExists(basePath, branch))
+            return;
+        nativeBranchDelete(basePath, branch, true);
+    }
+    catch (e) {
+        logWarning("worktree", `${warningPrefix}: ${e.message}`);
+    }
+}
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -311,7 +321,7 @@ export function listWorktrees(basePath) {
 // of their object database, causing permanent silent data loss.
 /** Directories to skip when scanning for nested .git dirs. */
 const NESTED_GIT_SKIP_DIRS = new Set([
-    ".git", ".gsd", "node_modules", ".next", ".nuxt", "dist", "build",
+    ".git", ".gsd", ".bg-shell", "node_modules", ".next", ".nuxt", "dist", "build",
     "__pycache__", ".tox", ".venv", "venv", "target", "vendor",
 ]);
 /**
@@ -364,7 +374,9 @@ export function findNestedGitDirs(rootPath) {
                 }
             }
             catch (e) {
-                logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${e.message}`);
+                if (e.code !== "ENOENT") {
+                    logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${e.message}`);
+                }
             }
             walk(fullPath, depth + 1);
         }
@@ -430,12 +442,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     if (!existsSync(wtPath)) {
         nativeWorktreePrune(basePath);
         if (deleteBranch) {
-            try {
-                nativeBranchDelete(basePath, branch, true);
-            }
-            catch (e) {
-                logWarning("worktree", `nativeBranchDelete failed: ${e.message}`);
-            }
+            deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
         }
         return;
     }
@@ -549,12 +556,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     // Prune stale entries so git knows the worktree is gone
     nativeWorktreePrune(basePath);
     if (deleteBranch) {
-        try {
-            nativeBranchDelete(basePath, branch, true);
-        }
-        catch (e) {
-            logWarning("worktree", `final branch delete failed: ${e.message}`);
-        }
+        deleteBranchIfPresent(basePath, branch, "final branch delete failed");
     }
 }
 /**

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

@@ -0,0 +1,119 @@
+// Project/App: GSD-2
+// File Purpose: Worktree Safety module contract for validating source-writing Unit roots.
+import { existsSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { normalizeWorktreePathForCompare } from "./worktree-root.js";
+import { listWorktrees } from "./worktree-manager.js";
+import { getCurrentBranch } from "./worktree.js";
+const fsOnlyDeps = {
+    existsSync,
+    lstatSync,
+};
+const defaultDeps = {
+    ...fsOnlyDeps,
+    listRegisteredWorktrees(projectRoot) {
+        return listWorktrees(projectRoot).map((worktree) => ({
+            path: worktree.path,
+            branch: worktree.branch,
+        }));
+    },
+    getCurrentBranch,
+};
+function isValidMilestoneId(milestoneId) {
+    return milestoneId.length > 0 && !/[\/\\]|\.\./.test(milestoneId);
+}
+function samePath(a, b) {
+    return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
+}
+function failure(kind, reason, remediation, details) {
+    return { ok: false, kind, reason, remediation, details };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createWorktreeSafetyModule(deps = defaultDeps) {
+    return {
+        validateUnitRoot(input) {
+            if (input.writeScope === "planning-only") {
+                return {
+                    ok: true,
+                    kind: "not-required",
+                    reason: "planning-only Units may write GSD artifacts without a source worktree",
+                };
+            }
+            const milestoneId = input.milestoneId?.trim();
+            if (!milestoneId) {
+                return failure("milestone-id-missing", `Source-writing Unit ${input.unitType} ${input.unitId} has no milestone id.`, "Resolve the Unit milestone before preparing a worktree root.");
+            }
+            if (!isValidMilestoneId(milestoneId)) {
+                return failure("milestone-id-invalid", `Milestone id "${milestoneId}" is not safe for worktree path resolution.`, "Use a milestone id without path separators or traversal segments.", { milestoneId });
+            }
+            const projectRoot = resolve(input.projectRoot);
+            const unitRoot = resolve(input.unitRoot);
+            const expectedRoot = join(projectRoot, ".gsd", "worktrees", milestoneId);
+            if (!samePath(unitRoot, expectedRoot)) {
+                return failure("invalid-root", `Unit root ${unitRoot} is not the expected worktree root for ${milestoneId}.`, "Prepare the Unit in its canonical milestone worktree before allowing source writes.", { expectedRoot, unitRoot });
+            }
+            if (!deps.existsSync(unitRoot)) {
+                return failure("worktree-missing", `Worktree root ${unitRoot} does not exist.`, "Create or recover the milestone worktree before dispatching the source-writing Unit.", { unitRoot });
+            }
+            const gitMarker = join(unitRoot, ".git");
+            if (!deps.existsSync(gitMarker)) {
+                return failure("worktree-git-marker-missing", `Worktree root ${unitRoot} has no .git marker.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { gitMarker });
+            }
+            let gitMarkerStat;
+            try {
+                gitMarkerStat = deps.lstatSync(gitMarker);
+            }
+            catch (error) {
+                return failure("worktree-git-probe-failed", `Unable to inspect .git marker for worktree root ${unitRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { gitMarker, error: errorMessage(error) });
+            }
+            if (!gitMarkerStat.isFile()) {
+                return failure("worktree-git-marker-not-file", `Worktree root ${unitRoot} has a .git directory, not a registered worktree .git file.`, "Use a registered GSD worktree instead of a copied or nested repository.", { gitMarker });
+            }
+            let registered;
+            try {
+                registered = deps.listRegisteredWorktrees?.(projectRoot);
+            }
+            catch (error) {
+                return failure("worktree-git-probe-failed", `Unable to list registered worktrees for project root ${projectRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, error: errorMessage(error) });
+            }
+            if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
+                return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, "Recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot });
+            }
+            if (input.emptyWorktreeWithProjectContent) {
+                return failure("empty-worktree-with-project-content", `Worktree root ${unitRoot} has no project content, but the project root does.`, "Resolve untracked project-root content or recreate the worktree so source writes stay isolated.", { unitRoot, projectRoot });
+            }
+            const expectedBranch = input.expectedBranch?.trim();
+            let branch;
+            if (expectedBranch) {
+                if (!deps.getCurrentBranch) {
+                    return failure("worktree-git-probe-failed", `Branch verification requested for ${unitRoot} but no getCurrentBranch dependency is configured.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { unitRoot, expectedBranch, error: "getCurrentBranch dep not provided" });
+                }
+                try {
+                    branch = deps.getCurrentBranch(unitRoot);
+                }
+                catch (error) {
+                    return failure("worktree-git-probe-failed", `Unable to resolve current branch for worktree root ${unitRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { unitRoot, expectedBranch, error: errorMessage(error) });
+                }
+                if (branch !== expectedBranch) {
+                    return failure("branch-mismatch", `Worktree root ${unitRoot} is on branch ${branch}, expected ${expectedBranch}.`, "Switch to the expected milestone branch or recover the worktree before dispatching the Unit.", { branch, expectedBranch });
+                }
+            }
+            if (input.lease?.required && !input.lease.held) {
+                return failure("lease-lost", `Milestone lease for ${milestoneId} is not held by the current worker.`, "Reclaim the milestone lease before dispatching the source-writing Unit.", { owner: input.lease.owner ?? null });
+            }
+            return {
+                ok: true,
+                kind: "safe",
+                projectRoot,
+                unitRoot,
+                milestoneId,
+                branch,
+            };
+        },
+    };
+}
+export function createFsOnlyWorktreeSafetyModule() {
+    return createWorktreeSafetyModule(fsOnlyDeps);
+}

package/dist/resources/extensions/gsd/worktree-state-projection.js

@@ -0,0 +1,317 @@
+// GSD-2 — Worktree State Projection module: directional state-flow rules between project root and auto-worktree.
+/**
+ * Worktree State Projection module — first-class Module for directional
+ * state-file flow between the project root and the auto-worktree.
+ *
+ * Per ADR-016, this Module owns:
+ *   - The direction-and-rules of state file flow (project-root authoritative
+ *     for some classes, worktree authoritative for others)
+ *   - The bug-hardened invariants encoded in `syncProjectRootToWorktree` /
+ *     `syncStateToProjectRoot` (additive milestone copy #1886, ASSESSMENT
+ *     verdict overwrite #2821, completed-units forward-sync, WAL/SHM
+ *     cleanup #2478, .gsd symlink edge case #2184)
+ *
+ * Slice 7 (#5591): the bodies of the three projection verbs and their
+ * private helpers (`isSamePath`, `forceOverwriteAssessmentsWithVerdict`,
+ * `ROOT_DIAGNOSTIC_FILES`) live here. The legacy `syncProjectRootToWorktree`,
+ * `syncStateToProjectRoot`, `syncWorktreeStateBack` exports in
+ * `auto-worktree.ts` are thin wrappers around the `_*Impl` exports below
+ * until the legacy-helper cleanup step retires them.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+import { reconcileWorktreeDb } from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
+import { logError, logWarning } from "./workflow-logger.js";
+// ─── Private helpers ──────────────────────────────────────────────────────
+/**
+ * Check if two filesystem paths resolve to the same real location.
+ * Returns false if either path cannot be resolved (e.g. doesn't exist).
+ *
+ * Detects the .gsd-as-symlink case (#2184) where the worktree's `.gsd`
+ * resolves to the same physical directory as the project root's `.gsd` —
+ * a `cpSync` over those would fail with `ERR_FS_CP_EINVAL`.
+ */
+function isSamePath(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return false;
+        logWarning("worktree", `isSamePath failed: ${e.message}`);
+        return false;
+    }
+}
+/** Regex matching YAML frontmatter `verdict:` field. */
+const VERDICT_RE = /verdict:\s*[\w-]+/i;
+/**
+ * Walk a milestone directory and force-overwrite ASSESSMENT files in the
+ * destination when the source copy contains a `verdict:` field.
+ *
+ * Targeted fix for the UAT stuck-loop (#2821): the main `safeCopyRecursive`
+ * uses `force:false` to protect worktree-local projection files (#1886),
+ * but ASSESSMENT files written by run-uat must be forward-synced when the
+ * project root has a verdict. Without this, the worktree retains a stale
+ * FAIL or missing ASSESSMENT and `checkNeedsRunUat` re-dispatches run-uat
+ * indefinitely.
+ *
+ * Only overwrites when the source has a verdict — never clobbers a
+ * worktree ASSESSMENT with a verdictless project-root copy.
+ */
+function forceOverwriteAssessmentsWithVerdict(srcMilestoneDir, dstMilestoneDir) {
+    if (!existsSync(srcMilestoneDir))
+        return;
+    const slicesDir = join(srcMilestoneDir, "slices");
+    if (!existsSync(slicesDir))
+        return;
+    try {
+        for (const sliceEntry of readdirSync(slicesDir, { withFileTypes: true })) {
+            if (!sliceEntry.isDirectory())
+                continue;
+            const srcSliceDir = join(slicesDir, sliceEntry.name);
+            const dstSliceDir = join(dstMilestoneDir, "slices", sliceEntry.name);
+            try {
+                for (const fileEntry of readdirSync(srcSliceDir, { withFileTypes: true })) {
+                    if (!fileEntry.isFile())
+                        continue;
+                    if (!fileEntry.name.endsWith("-ASSESSMENT.md"))
+                        continue;
+                    const srcFile = join(srcSliceDir, fileEntry.name);
+                    try {
+                        const srcContent = readFileSync(srcFile, "utf-8");
+                        if (!VERDICT_RE.test(srcContent))
+                            continue;
+                        mkdirSync(dstSliceDir, { recursive: true });
+                        safeCopy(srcFile, join(dstSliceDir, fileEntry.name), { force: true });
+                    }
+                    catch (err) {
+                        logWarning("worktree", `assessment force-copy failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+            catch (err) {
+                logWarning("worktree", `assessment slice scan failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `assessment sync failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Root-level .gsd/ files copied from worktree back to project root for
+ * post-merge diagnostics. Markdown projections are NOT in this list — DB
+ * remains authoritative.
+ */
+const ROOT_DIAGNOSTIC_FILES = [
+    "completed-units.json",
+    "metrics.json",
+];
+// ─── Implementation cores ────────────────────────────────────────────────
+//
+// The `_*Impl` exports take raw paths so the deprecated path-string
+// wrappers in `auto-worktree.ts` can delegate to them during the slice-7
+// migration window. They will be inlined into the class methods and made
+// non-exported once the legacy wrappers retire.
+/**
+ * Project state from project root onto the auto-worktree (raw-path body).
+ *
+ * Owns the rules: identity-key safety check (#2184 .gsd symlink), additive
+ * milestone copy preserving worktree-local files (#1886), ASSESSMENT
+ * verdict force-overwrite (#2821), forward-sync of `completed-units.json`,
+ * WAL/SHM cleanup on legacy worktree-local DB (#2478).
+ */
+export function _projectRootToWorktreeImpl(projectRoot, worktreePath_, milestoneId) {
+    if (!worktreePath_ || !projectRoot || worktreePath_ === projectRoot)
+        return;
+    if (!milestoneId)
+        return;
+    const contract = resolveGsdPathContract(worktreePath_, projectRoot);
+    const prGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
+    // When .gsd is a symlink to the same external directory in both locations,
+    // cpSync rejects the copy because source === destination (ERR_FS_CP_EINVAL).
+    // Compare realpaths and skip when they resolve to the same physical path (#2184).
+    if (isSamePath(prGsd, wtGsd))
+        return;
+    // Copy milestone directory from project root to worktree — additive only.
+    // force:false prevents cpSync from overwriting existing worktree files.
+    // Without this, worktree-local files (e.g. VALIDATION.md written
+    // by validate-milestone) get clobbered by stale project root copies,
+    // causing an infinite re-validation loop (#1886).
+    safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId), { force: false });
+    // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
+    // The additive-only copy above preserves worktree-local files, but
+    // ASSESSMENT files are special: after run-uat writes a verdict and post-unit
+    // syncs it to the project root, the worktree may retain a stale copy (e.g.
+    // verdict:fail while the project root has verdict:pass from a retry). On
+    // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT
+    // persists, checkNeedsRunUat finds no passing verdict → re-dispatches
+    // run-uat indefinitely (stuck-loop ×9).
+    forceOverwriteAssessmentsWithVerdict(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId));
+    // Forward-sync completed-units.json from project root to worktree.
+    // Project root is authoritative for completion state after crash recovery;
+    // without this, the worktree re-dispatches already-completed units (#1886).
+    safeCopy(join(prGsd, "completed-units.json"), join(wtGsd, "completed-units.json"), { force: true });
+    // Delete a legacy worktree-local gsd.db ONLY if it is empty (0 bytes).
+    // Runtime opens contract.projectDb; this cleanup only removes corrupt
+    // pre-upgrade local DB projections.
+    try {
+        const wtDb = join(wtGsd, "gsd.db");
+        let deleteSidecars = false;
+        if (existsSync(wtDb)) {
+            const size = statSync(wtDb).size;
+            if (size === 0) {
+                unlinkSync(wtDb);
+                deleteSidecars = true;
+            }
+        }
+        else {
+            // Main DB already missing — sidecars are orphaned from a previous
+            // partial cleanup and must still be removed.
+            deleteSidecars = true;
+        }
+        // Always clean up WAL/SHM sidecar files when the main DB was deleted
+        // or is already missing. Orphaned WAL/SHM files cause SQLite WAL
+        // recovery on next open, which triggers a CPU spin on Node 24's
+        // node:sqlite DatabaseSync implementation (#2478).
+        if (deleteSidecars) {
+            for (const suffix of ["-wal", "-shm"]) {
+                const f = wtDb + suffix;
+                if (existsSync(f)) {
+                    unlinkSync(f);
+                }
+            }
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `worktree DB cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Project state from auto-worktree back onto project root (raw-path body).
+ *
+ * Owns the rules: project-root authoritative for diagnostics; markdown
+ * projections do NOT flow back; non-fatal — sync failure must not block
+ * the caller.
+ */
+export function _projectWorktreeToRootImpl(worktreePath_, projectRoot, milestoneId) {
+    if (!worktreePath_ || !projectRoot || worktreePath_ === projectRoot)
+        return;
+    if (!milestoneId)
+        return;
+    const contract = resolveGsdPathContract(worktreePath_, projectRoot);
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
+    const prGsd = contract.projectGsd;
+    // When .gsd is a symlink to the same external directory in both locations,
+    // cpSync rejects the copy because source === destination (ERR_FS_CP_EINVAL).
+    // Compare realpaths and skip when they resolve to the same physical path (#2184).
+    if (isSamePath(wtGsd, prGsd))
+        return;
+    // metrics.json — session cost/token tracking (#2313).
+    // Without this, metrics accumulated in the worktree are invisible from the
+    // project root and never appear in the dashboard or skill-health reports.
+    safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
+    // completed-units.json — runtime completion diagnostics used to avoid
+    // re-dispatching work already completed in an isolated worktree.
+    safeCopy(join(wtGsd, "completed-units.json"), join(prGsd, "completed-units.json"), { force: true });
+    // Runtime records — unit dispatch diagnostics used by selfHealRuntimeRecords().
+    // Without this, a crash during a unit leaves the runtime record only in the
+    // worktree. If the next session resolves basePath before worktree re-entry,
+    // selfHeal can't find or clear the stale record (#769).
+    safeCopyRecursive(join(wtGsd, "runtime", "units"), join(prGsd, "runtime", "units"), { force: true });
+}
+/**
+ * Final projection from auto-worktree to project root before teardown
+ * (raw-path body).
+ *
+ * Owns the rules: pre-upgrade DB reconciliation, root-level diagnostic
+ * file copy. DB/project-root state remains authoritative; markdown
+ * milestone directories are NOT copied back.
+ */
+export function _finalizeProjectionForMergeImpl(mainBasePath, worktreePath, milestoneId) {
+    const contract = resolveGsdPathContract(worktreePath, mainBasePath);
+    const mainGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath, ".gsd");
+    const synced = [];
+    // If both resolve to the same directory (symlink), no sync needed
+    if (isSamePath(mainGsd, wtGsd))
+        return { synced };
+    if (!existsSync(wtGsd) || !existsSync(mainGsd))
+        return { synced };
+    // ── 0. Pre-upgrade worktree DB reconciliation ────────────────────────
+    // If the worktree has its own gsd.db (copied before the WAL transition),
+    // reconcile its hierarchy data into the project root DB before syncing
+    // files. This handles in-flight worktrees that were created before the
+    // upgrade to shared WAL mode.
+    const wtLocalDb = join(wtGsd, "gsd.db");
+    const mainDb = contract.projectDb;
+    if (existsSync(wtLocalDb) && existsSync(mainDb)) {
+        try {
+            reconcileWorktreeDb(mainDb, wtLocalDb);
+            synced.push("gsd.db (pre-upgrade reconcile)");
+        }
+        catch (err) {
+            // Non-fatal — file sync below is the fallback
+            logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── 1. Sync root-level diagnostic files back ─────────────────────────
+    // Markdown/JSON state projections remain project-root/DB authoritative.
+    // These diagnostic files are copied for observability only.
+    for (const f of ROOT_DIAGNOSTIC_FILES) {
+        const src = join(wtGsd, f);
+        const dst = join(mainGsd, f);
+        if (existsSync(src)) {
+            try {
+                cpSync(src, dst, { force: true });
+                synced.push(f);
+            }
+            catch (err) {
+                logWarning("worktree", `state file copy-back failed (${f}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return { synced };
+}
+// ─── Module class ────────────────────────────────────────────────────────
+/**
+ * Worktree State Projection Module instance.
+ *
+ * Stateless — methods are pure functions of their `MilestoneScope` input.
+ * The class form is retained for testability and to keep the Interface
+ * shape consistent with `WorktreeLifecycle`.
+ */
+export class WorktreeStateProjection {
+    /**
+     * Project state from the project root onto the auto-worktree for the scope
+     * pair. `worktreeScope` may be omitted only for project-only/same-path
+     * callers where the helper intentionally fast-paths to a no-op.
+     * Called by Lifecycle's enter path after a successful create/enter, before
+     * any Unit dispatches.
+     */
+    projectRootToWorktree(scope) {
+        _projectRootToWorktreeImpl(scope.workspace.projectRoot, scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.milestoneId);
+    }
+    /**
+     * Project state from the auto-worktree back onto the project root for `scope`.
+     * Called by the post-unit pipeline between Units.
+     */
+    projectWorktreeToRoot(scope) {
+        _projectWorktreeToRootImpl(scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.workspace.projectRoot, scope.milestoneId);
+    }
+    /**
+     * Final projection from the auto-worktree to the project root before
+     * teardown. Called by Lifecycle's exit path after a successful merge,
+     * before the worktree directory is removed.
+     *
+     * Returns `{ synced }` describing which file classes were captured —
+     * mirrors the pre-deepening contract for callers that want post-merge
+     * telemetry on what crossed the boundary.
+     */
+    finalizeProjectionForMerge(scope) {
+        return _finalizeProjectionForMergeImpl(scope.workspace.projectRoot, scope.workspace.worktreeRoot ?? scope.workspace.projectRoot, scope.milestoneId);
+    }
+}