@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/dist/resources/extensions/gsd/auto-worktree-milestone-shelter.js

@@ -0,0 +1,119 @@
+// gsd-pi — Milestone directory shelter for auto-worktree merge closeout.
+//
+// Owns the #2505 queued-milestone directory protection step that runs before
+// merge stash handling. This keeps queued CONTEXT files out of the stash and
+// restores them after merge closeout without hiding restore failures.
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { canonicalPhaseDirName, gsdRoot, milestonesDir, resolveMilestonePath, } from "./paths.js";
+import { logError, logWarning } from "./workflow-logger.js";
+/**
+ * Optional override for the shelter restore copy step (milestone merge #2505).
+ * Production leaves this null so restore uses the real cpSync; tests inject a
+ * throwing function to deterministically exercise the best-effort failure path
+ * and the shelter-retention guarantee.
+ * @internal
+ */
+let restoreEntryFn = null;
+/** @internal */
+export function _setRestoreEntryFnForTests(fn) {
+    restoreEntryFn = fn;
+    return () => { restoreEntryFn = null; };
+}
+export function createMilestoneDirectoryShelter(originalBasePath, milestoneId, milestoneTitle) {
+    const planningDir = milestonesDir(originalBasePath);
+    const shelterDir = join(gsdRoot(originalBasePath), ".milestone-shelter");
+    const shelteredDirs = [];
+    const mergeDirNames = milestoneDirectoryNames(originalBasePath, milestoneId, milestoneTitle);
+    let restored = false;
+    try {
+        if (existsSync(planningDir)) {
+            const entries = readdirSync(planningDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (mergeDirNames.has(entry.name))
+                    continue;
+                shelterMilestoneDirectory(planningDir, shelterDir, entry.name, shelteredDirs);
+            }
+        }
+    }
+    catch (err) {
+        // Non-fatal — proceed with merge; untracked files may block it.
+        logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            restoreShelteredDirectories(planningDir, shelterDir, shelteredDirs);
+        },
+    };
+}
+function milestoneDirectoryNames(originalBasePath, milestoneId, milestoneTitle) {
+    const mergeDirNames = new Set([milestoneId]);
+    const resolvedMergeDir = resolveMilestonePath(originalBasePath, milestoneId);
+    if (resolvedMergeDir) {
+        mergeDirNames.add(basename(resolvedMergeDir));
+    }
+    else {
+        mergeDirNames.add(canonicalPhaseDirName(milestoneId, milestoneTitle));
+    }
+    return mergeDirNames;
+}
+function shelterMilestoneDirectory(planningDir, shelterDir, dirName, shelteredDirs) {
+    const srcDir = join(planningDir, dirName);
+    const dstDir = join(shelterDir, dirName);
+    try {
+        mkdirSync(shelterDir, { recursive: true });
+        cpSync(srcDir, dstDir, { recursive: true, force: true });
+        rmSync(srcDir, { recursive: true, force: true });
+        shelteredDirs.push(dirName);
+    }
+    catch (err) {
+        // Non-fatal — if shelter fails, the merge may still succeed.
+        logWarning("worktree", `milestone shelter failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function restoreShelteredDirectories(planningDir, shelterDir, shelteredDirs) {
+    if (shelteredDirs.length === 0)
+        return;
+    let restoreFailed = false;
+    for (const dirName of shelteredDirs) {
+        const src = join(shelterDir, dirName);
+        if (!existsSync(src)) {
+            logWarning("worktree", `shelter source missing for ${dirName}; skipping restore (shelter already cleaned or entry never staged)`);
+            continue;
+        }
+        try {
+            mkdirSync(planningDir, { recursive: true });
+            const dest = join(planningDir, dirName);
+            if (restoreEntryFn) {
+                restoreEntryFn(src, dest);
+            }
+            else {
+                cpSync(src, dest, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            restoreFailed = true;
+            logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Preserve the shelter if any per-entry restore failed — it is the only
+    // surviving copy of the queued milestone dirs (sources were deleted during
+    // shelter). Deleting it here would permanently lose those files (#2505).
+    if (restoreFailed) {
+        logWarning("worktree", `shelter retained at ${shelterDir} — manual recovery required for unrestored entries`);
+        return;
+    }
+    if (existsSync(shelterDir)) {
+        try {
+            rmSync(shelterDir, { recursive: true, force: true });
+        }
+        catch (err) {
+            logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/resources/extensions/gsd/auto-worktree-path-resolution.js

@@ -0,0 +1,5 @@
+// gsd-pi — Auto-worktree path resolution seam.
+//
+// Keeps callers that only resolve existing auto-worktree paths on the focused
+// entry/path module instead of the legacy auto-worktree compatibility barrel.
+export { getAutoWorktreePath } from "./auto-worktree-entry.js";

package/dist/resources/extensions/gsd/auto-worktree-path-utils.js

@@ -0,0 +1,5 @@
+// gsd-pi — Narrow auto-worktree path utility seam.
+//
+// Keeps path comparison, pathspec, and expected-warning callers off the legacy
+// auto-worktree compatibility barrel while extraction continues.
+export { _gitPathspecForWorktreePath, _isExpectedWorktreeUnlinkError, _isSamePath, } from "./auto-worktree-cleanup.js";

package/dist/resources/extensions/gsd/auto-worktree-resource-version.js

@@ -0,0 +1,41 @@
+// gsd-pi — Auto-worktree resource version module.
+//
+// Owns managed-resource freshness checks for long-running auto sessions.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdHome } from "./gsd-home.js";
+import { logWarning } from "./workflow-logger.js";
+/**
+ * Read the resource version (semver) from the managed-resources manifest.
+ * Uses gsdVersion instead of syncedAt so that launching a second session
+ * doesn't falsely trigger staleness (#804).
+ */
+export function readResourceVersion() {
+    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
+    const manifestPath = join(agentDir, "managed-resources.json");
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return typeof manifest?.gsdVersion === "string"
+            ? manifest.gsdVersion
+            : null;
+    }
+    catch (e) {
+        logWarning("worktree", `readResourceVersion failed: ${e.message}`);
+        return null;
+    }
+}
+/**
+ * Check if managed resources have been updated since session start.
+ * Returns a warning message if stale, null otherwise.
+ */
+export function checkResourcesStale(versionOnStart) {
+    if (versionOnStart === null)
+        return null;
+    const current = readResourceVersion();
+    if (current === null)
+        return null;
+    if (current !== versionOnStart) {
+        return "GSD resources were updated since this session started. Restart gsd to load the new code.";
+    }
+    return null;
+}

package/dist/resources/extensions/gsd/auto-worktree-runtime-cleanup.js

@@ -0,0 +1,99 @@
+// gsd-pi — Auto-worktree runtime cleanup module.
+//
+// Owns stale worktree cwd escape and runtime unit cleanup during auto startup.
+import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { gsdHome } from "./gsd-home.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
+import { normalizeWorktreePathForCompare, projectRootFromWorktreePath, } from "./worktree-root.js";
+import { logWarning } from "./workflow-logger.js";
+const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
+    "workflow-preferences-WORKFLOW-PREFS.json",
+    "discuss-project-PROJECT.json",
+    "discuss-requirements-REQUIREMENTS.json",
+    "research-decision-RESEARCH-DECISION.json",
+    "research-project-RESEARCH-PROJECT.json",
+]);
+/**
+ * Detect and escape a stale worktree cwd (#608).
+ *
+ * After milestone completion + merge, the worktree directory is removed but
+ * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
+ * When a new session starts, `process.cwd()` is passed as `base` to startAuto
+ * and all subsequent writes land in the wrong directory. This function detects
+ * that scenario and chdir back to the project root.
+ *
+ * Returns the corrected base path.
+ */
+export function escapeStaleWorktree(base) {
+    const projectRoot = projectRootFromWorktreePath(base);
+    if (projectRoot === null)
+        return base;
+    // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
+    // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
+    // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
+    // resolved through the symlink. Returning ~ would be catastrophic (#1676).
+    const candidateGsd = normalizeWorktreePathForCompare(join(projectRoot, ".gsd"));
+    const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
+    if (candidateGsd === gsdHomeNorm || candidateGsd.startsWith(gsdHomeNorm + "/")) {
+        // Don't chdir to home — return base unchanged.
+        // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
+        // and will be called by the caller (startAuto → projectRoot()).
+        return base;
+    }
+    try {
+        process.chdir(projectRoot);
+    }
+    catch (e) {
+        // If chdir fails, return the original — caller will handle errors downstream
+        logWarning("worktree", `escapeStaleWorktree chdir failed: ${e.message}`);
+        return base;
+    }
+    return projectRoot;
+}
+/**
+ * Clean stale runtime unit files for completed milestones.
+ *
+ * After restart, stale runtime/units/*.json from prior milestones can
+ * cause deriveState to resume the wrong milestone (#887). Removes files
+ * for milestones that have a SUMMARY (fully complete).
+ */
+export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
+    const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
+    if (!existsSync(runtimeUnitsDir))
+        return 0;
+    let cleaned = 0;
+    try {
+        for (const file of readdirSync(runtimeUnitsDir)) {
+            if (!file.endsWith(".json"))
+                continue;
+            if (shouldRemoveRuntimeUnit(file, hasMilestoneSummary)) {
+                cleaned += unlinkRuntimeUnit(runtimeUnitsDir, file);
+            }
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `stale runtime unit cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return cleaned;
+}
+function shouldRemoveRuntimeUnit(file, hasMilestoneSummary) {
+    if (LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES.has(file))
+        return true;
+    const staleDiscussMatch = file.match(/^discuss-milestone-(.+)\.json$/);
+    if (staleDiscussMatch && !MILESTONE_ID_RE.test(staleDiscussMatch[1])) {
+        return true;
+    }
+    const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
+    return Boolean(midMatch && hasMilestoneSummary(midMatch[1]));
+}
+function unlinkRuntimeUnit(runtimeUnitsDir, file) {
+    try {
+        unlinkSync(join(runtimeUnitsDir, file));
+        return 1;
+    }
+    catch (err) {
+        logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+        return 0;
+    }
+}

package/dist/resources/extensions/gsd/auto-worktree-session-registry.js

@@ -0,0 +1,57 @@
+// gsd-pi — Auto-worktree active session registry.
+//
+// Owns the process-local active workspace state used by auto-worktree create,
+// enter, teardown, and merge paths. Keeping this state behind a focused module
+// gives registry tests the same interface production uses instead of reaching
+// through the legacy auto-worktree compatibility barrel.
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+import { detectWorktreeName } from "./worktree.js";
+/** Active workspace registry — replaces the legacy `originalBase` singleton. */
+let activeWorkspace = null;
+export function setActiveWorkspace(ws) {
+    activeWorkspace = ws;
+}
+export function getActiveWorkspace() {
+    return activeWorkspace;
+}
+/**
+ * Get the original project root stored when entering an auto-worktree.
+ * Returns null if not currently in an auto-worktree.
+ */
+export function getAutoWorktreeOriginalBase() {
+    return getActiveWorkspace()?.projectRoot ?? null;
+}
+/**
+ * Test-only — resets the module-level `activeWorkspace` registry between
+ * runs. Production code never clears the registry directly; tests call this
+ * in `beforeEach`/`afterEach` to isolate registry-mutating cases.
+ */
+export function _resetAutoWorktreeOriginalBaseForTests() {
+    setActiveWorkspace(null);
+}
+export function getActiveAutoWorktreeContext() {
+    const ws = getActiveWorkspace();
+    if (!ws)
+        return null;
+    const originalBase = ws.projectRoot;
+    const cwd = process.cwd();
+    if (!isGsdWorktreePath(cwd))
+        return null;
+    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+    if (normalizeWorktreePathForCompare(cwdProjectRoot) !==
+        normalizeWorktreePathForCompare(originalBase)) {
+        return null;
+    }
+    const worktreeName = detectWorktreeName(cwd);
+    if (!worktreeName)
+        return null;
+    const branch = nativeGetCurrentBranch(cwd);
+    if (!branch.startsWith("milestone/"))
+        return null;
+    return {
+        originalBase,
+        worktreeName,
+        branch,
+    };
+}

package/dist/resources/extensions/gsd/auto-worktree-sync.js

@@ -0,0 +1,249 @@
+// gsd-pi — Auto-worktree state sync module.
+//
+// Owns project-root/worktree projection compatibility seams while the project DB
+// remains authoritative for workflow state.
+import { cpSync, existsSync, lstatSync as lstatSyncFn, mkdirSync, readdirSync, } from "node:fs";
+import { join } from "node:path";
+import { _isSamePath as isSamePath, } from "./auto-worktree-cleanup.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { WorktreeStateProjection } from "./worktree-state-projection.js";
+import { logWarning } from "./workflow-logger.js";
+const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
+const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
+/**
+ * Root-level .gsd/ projections copied from project root into worktrees for
+ * compatibility. Project root remains the canonical state/projection root.
+ */
+const ROOT_STATE_FILES = [
+    "DECISIONS.md",
+    "REQUIREMENTS.md",
+    "PROJECT.md",
+    "KNOWLEDGE.md",
+    "OVERRIDES.md",
+    "QUEUE.md",
+    "completed-units.json",
+    "metrics.json",
+    "mcp.json",
+    // NOTE: project preferences are intentionally NOT in ROOT_STATE_FILES.
+    // Forward-sync (main → worktree) is handled explicitly in syncGsdStateToWorktree().
+    // Back-sync (worktree → main) must NEVER overwrite the project root's copy
+    // because the project root is authoritative for preferences (#2684).
+];
+/**
+ * Path-string entry point to WorktreeStateProjection.projectRootToWorktree.
+ * Production code goes through the Module class; this delegator survives so
+ * the projection-invariant tests (#1886, #2184, #2478, #2821) can exercise
+ * the bodies with raw paths.
+ */
+export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneId) {
+    new WorktreeStateProjection().projectRootToWorktreePaths(projectRoot, worktreePath_, milestoneId);
+}
+/**
+ * Path-string entry point to WorktreeStateProjection.projectWorktreeToRoot.
+ * Production code goes through the Module class; this delegator survives so
+ * the projection-invariant tests can exercise the body with raw paths.
+ */
+export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId) {
+    new WorktreeStateProjection().projectWorktreeToRootPaths(worktreePath_, projectRoot, milestoneId);
+}
+/**
+ * Scope-typed variant of syncGsdStateToWorktree.
+ *
+ * Takes an explicit (rootScope, worktreeScope) pair. Note: milestoneId is not
+ * used by syncGsdStateToWorktree — this variant only requires workspace
+ * identity. Asserts both scopes belong to the same workspace identity to
+ * prevent silent mismatch bugs.
+ */
+export function syncGsdStateToWorktreeByScope(rootScope, worktreeScope) {
+    if (rootScope.workspace.identityKey !== worktreeScope.workspace.identityKey) {
+        throw new Error(`syncGsdStateToWorktreeByScope: scope identity mismatch — ` +
+            `rootScope.identityKey="${rootScope.workspace.identityKey}" ` +
+            `worktreeScope.identityKey="${worktreeScope.workspace.identityKey}"`);
+    }
+    const mainBasePath = rootScope.workspace.projectRoot;
+    const worktreePath = worktreeScope.workspace.worktreeRoot
+        ?? worktreeScope.workspace.projectRoot;
+    return syncGsdStateToWorktree(mainBasePath, worktreePath);
+}
+/**
+ * Sync .gsd/ state from the main repo into the worktree.
+ *
+ * When .gsd/ is a symlink to the external state directory, both the main
+ * repo and worktree share the same directory — no sync needed.
+ *
+ * When .gsd/ is a real directory (e.g., git-tracked or manage_gitignore:false),
+ * the worktree has its own copy that may be stale. This function copies
+ * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
+ * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
+ *
+ * Only adds missing content — never overwrites existing files in the worktree.
+ * Worktree files are compatibility projections; DB/project root remains
+ * authoritative for runtime state.
+ * @deprecated Use syncGsdStateToWorktreeByScope instead.
+ * TODO(C-future): remove once all callers migrated.
+ */
+export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
+    const contract = resolveGsdPathContract(worktreePath_, mainBasePath);
+    const mainGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
+    const synced = [];
+    if (isSamePath(mainGsd, wtGsd))
+        return { synced };
+    if (!existsSync(mainGsd))
+        return { synced };
+    mkdirSync(wtGsd, { recursive: true });
+    syncRootStateFiles(mainGsd, wtGsd, synced);
+    syncProjectPreferences(mainGsd, wtGsd, synced);
+    syncMilestoneLayouts(mainGsd, wtGsd, synced);
+    return { synced };
+}
+function syncRootStateFiles(mainGsd, wtGsd, synced) {
+    for (const file of ROOT_STATE_FILES) {
+        const src = join(mainGsd, file);
+        const dst = join(wtGsd, file);
+        if (!existsSync(src) || existsSync(dst))
+            continue;
+        try {
+            cpSync(src, dst);
+            synced.push(file);
+        }
+        catch (err) {
+            logWarning("worktree", `file copy failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function syncProjectPreferences(mainGsd, wtGsd, synced) {
+    const worktreeHasPreferences = existsSync(join(wtGsd, PROJECT_PREFERENCES_FILE))
+        || existsSync(join(wtGsd, LEGACY_PROJECT_PREFERENCES_FILE));
+    if (worktreeHasPreferences)
+        return;
+    for (const file of [PROJECT_PREFERENCES_FILE, LEGACY_PROJECT_PREFERENCES_FILE]) {
+        const src = join(mainGsd, file);
+        const dst = join(wtGsd, file);
+        if (!existsSync(src))
+            continue;
+        try {
+            cpSync(src, dst);
+            synced.push(file);
+        }
+        catch (err) {
+            logWarning("worktree", `preferences copy failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+}
+function syncMilestoneLayouts(mainGsd, wtGsd, synced) {
+    for (const layoutSegment of ["phases", "milestones"]) {
+        syncMilestoneLayout(mainGsd, wtGsd, layoutSegment, synced);
+    }
+}
+function syncMilestoneLayout(mainGsd, wtGsd, layoutSegment, synced) {
+    const mainMilestonesDir = join(mainGsd, layoutSegment);
+    const wtMilestonesDir = join(wtGsd, layoutSegment);
+    if (!existsSync(mainMilestonesDir))
+        return;
+    try {
+        mkdirSync(wtMilestonesDir, { recursive: true });
+        const mainMilestones = readdirSync(mainMilestonesDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        for (const milestoneId of mainMilestones) {
+            syncMilestoneDirectory(mainMilestonesDir, wtMilestonesDir, milestoneId, synced);
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function syncMilestoneDirectory(mainMilestonesDir, wtMilestonesDir, milestoneId, synced) {
+    const srcDir = join(mainMilestonesDir, milestoneId);
+    const dstDir = join(wtMilestonesDir, milestoneId);
+    if (!existsSync(dstDir)) {
+        try {
+            cpSync(srcDir, dstDir, { recursive: true });
+            // Preserve the legacy telemetry string used before this extraction. The
+            // actual layout may be `phases/`; callers only consumed this as a coarse
+            // "milestone projection copied" marker.
+            synced.push(`milestones/${milestoneId}/`);
+        }
+        catch (err) {
+            logWarning("worktree", `milestone copy failed (${milestoneId}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    try {
+        syncMilestoneTopLevelFiles(srcDir, dstDir, milestoneId, synced);
+        syncSlicesDirectory(srcDir, dstDir, milestoneId, synced);
+    }
+    catch (err) {
+        logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function syncMilestoneTopLevelFiles(srcDir, dstDir, milestoneId, synced) {
+    const srcFiles = readdirSync(srcDir).filter((file) => file.endsWith(".md") || file.endsWith(".json"));
+    for (const file of srcFiles) {
+        const srcFile = join(srcDir, file);
+        const dstFile = join(dstDir, file);
+        if (existsSync(dstFile))
+            continue;
+        try {
+            const srcStat = lstatSyncFn(srcFile);
+            if (!srcStat.isFile())
+                continue;
+            cpSync(srcFile, dstFile);
+            synced.push(`milestones/${milestoneId}/${file}`);
+        }
+        catch (err) {
+            logWarning("worktree", `milestone file copy failed (${milestoneId}/${file}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function syncSlicesDirectory(srcDir, dstDir, milestoneId, synced) {
+    const srcSlicesDir = join(srcDir, "slices");
+    const dstSlicesDir = join(dstDir, "slices");
+    if (!existsSync(srcSlicesDir))
+        return;
+    if (!existsSync(dstSlicesDir)) {
+        try {
+            cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+            synced.push(`milestones/${milestoneId}/slices/`);
+        }
+        catch (err) {
+            logWarning("worktree", `slices copy failed (${milestoneId}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const srcSlices = readdirSync(srcSlicesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    for (const sliceId of srcSlices) {
+        const srcSlice = join(srcSlicesDir, sliceId);
+        const dstSlice = join(dstSlicesDir, sliceId);
+        if (existsSync(dstSlice))
+            continue;
+        try {
+            cpSync(srcSlice, dstSlice, { recursive: true });
+            synced.push(`milestones/${milestoneId}/slices/${sliceId}/`);
+        }
+        catch (err) {
+            logWarning("worktree", `slice copy failed (${milestoneId}/${sliceId}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Sync compatibility artifacts from worktree back to the main external state
+ * directory. Canonical workflow state lives in the project DB; worktree .gsd
+ * content is legacy projection/diagnostic data only.
+ *
+ * Syncs:
+ *   1. Legacy worktree DBs are reconciled into the canonical project DB.
+ *   2. Runtime diagnostic files may be copied for operator visibility.
+ *
+ * Markdown milestone directories are projections and are not copied from
+ * worktrees into the project root. Current workflow state must arrive through
+ * the shared project DB or the pre-upgrade DB reconciliation path above.
+ */
+export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
+    return new WorktreeStateProjection().finalizeProjectionForMergePaths(mainBasePath, worktreePath, milestoneId);
+}
+export { _shouldReconcileWorktreeDb } from "./auto-worktree-cleanup.js";