@opengsd/gsd-pi 1.4.0-dev.c18009cd → 1.5.0-dev.4fb2d460

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";

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

@@ -0,0 +1,120 @@
+// gsd-pi — Auto-worktree teardown module.
+//
+// Owns the teardown path for milestone worktrees: returning to the project
+// root, transient state cleanup, legacy DB reconciliation, worktree/branch
+// removal, fallback orphan-directory cleanup, and active workspace registry
+// clearing.
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { GSDError, GSD_IO_ERROR } from "./errors.js";
+import { reconcileWorktreeDb, isDbAvailable } from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { removeWorktree, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { autoWorktreeBranch } from "./auto-worktree-branch-lifecycle.js";
+import { setActiveWorkspace } from "./auto-worktree-session-registry.js";
+import { _shouldReconcileWorktreeDb, clearProjectRootStateFiles, } from "./auto-worktree-cleanup.js";
+import { logWarning, logError } from "./workflow-logger.js";
+function safeCwd(fallback) {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Teardown an auto-worktree: chdir back to original base, then remove
+ * the worktree and its branch.
+ */
+export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
+    originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
+    const branch = autoWorktreeBranch(milestoneId);
+    const { preserveBranch = false, preserveWorktree = false } = opts;
+    const previousCwd = safeCwd(originalBasePath);
+    let clearActiveWorkspace = true;
+    // Wrap the entire teardown body in a single try/finally so activeWorkspace
+    // is cleared on completion or irrecoverable failure — even if process.chdir
+    // throws (e.g. originalBasePath was deleted before teardown ran).
+    try {
+        try {
+            process.chdir(originalBasePath);
+        }
+        catch (err) {
+            throw new GSDError(GSD_IO_ERROR, `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Mirror cleanup steps from mergeMilestoneToMain abort path:
+        // 1. Remove transient state files (STATE.md, auto.lock, {MID}-META.json).
+        //    Non-fatal — must not block teardown.
+        try {
+            clearProjectRootStateFiles(originalBasePath, milestoneId);
+        }
+        catch (err) {
+            logWarning("worktree", `clearProjectRootStateFiles failed during teardown: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // 2. Reconcile worktree-local gsd.db into project root DB if both exist.
+        //    Non-fatal — handles legacy worktrees that have a local copy.
+        if (isDbAvailable()) {
+            try {
+                const contract = resolveGsdPathContract(previousCwd, originalBasePath);
+                const worktreeDbPath = join(contract.worktreeGsd ?? join(previousCwd, ".gsd"), "gsd.db");
+                const mainDbPath = contract.projectDb;
+                if (_shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
+                    reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+                }
+            }
+            catch (err) {
+                /* non-fatal */
+                logError("worktree", `DB reconciliation failed during teardown: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        nudgeGitBranchCache(previousCwd);
+        // 3. Remove the worktree unless this exit path explicitly preserves it
+        //    (slice-parallel dispatch stops the parent loop but keeps the parent
+        //    milestone worktree for restart/re-entry).
+        let worktreeRemoved = preserveWorktree;
+        if (!preserveWorktree) {
+            worktreeRemoved = removeWorktree(originalBasePath, milestoneId, {
+                branch,
+                deleteBranch: !preserveBranch,
+            });
+            if (!worktreeRemoved) {
+                logWarning("worktree", `Worktree removal aborted for ${milestoneId}; uncommitted work was preserved. ` +
+                    `Manual quarantine recovery may be needed before retrying teardown.`, { worktree: milestoneId });
+                clearActiveWorkspace = false;
+            }
+        }
+        // Verify cleanup succeeded — warn if the worktree directory is still on disk.
+        // On Windows, bash-based cleanup can silently fail when paths contain
+        // backslashes (#1436), leaving ~1 GB+ orphaned directories.
+        const wtDir = worktreePath(originalBasePath, milestoneId);
+        if (!preserveWorktree && worktreeRemoved && existsSync(wtDir)) {
+            logWarning("reconcile", `Worktree directory still exists after teardown: ${wtDir}. ` +
+                `This is likely an orphaned directory consuming disk space. ` +
+                `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`, { worktree: milestoneId });
+            // Attempt a direct filesystem removal as a fallback — but ONLY if the
+            // path is safely inside .gsd/worktrees/ to prevent #2365 data loss.
+            if (isInsideWorktreesDir(originalBasePath, wtDir)) {
+                try {
+                    rmSync(wtDir, { recursive: true, force: true });
+                }
+                catch (err) {
+                    // Non-fatal — the warning above tells the user how to clean up
+                    logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                console.error(`[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`);
+            }
+        }
+    }
+    finally {
+        // Clear module state when teardown completed or failed irrecoverably.
+        // When removeWorktree returns false (quarantine failure), preserve the
+        // registry so recovery logic still sees the active milestone worktree.
+        if (clearActiveWorkspace) {
+            setActiveWorkspace(null);
+        }
+    }
+}