@opengsd/gsd-pi 1.3.0 → 1.4.0

package/dist/resources/extensions/gsd/auto-start.js

@@ -18,6 +18,7 @@ import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-ide
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import { milestoneEntryBlockedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
@@ -46,7 +47,7 @@ import { auditOrphanedPreflightStashes } from "./orphan-stash-audit.js";
 import { parseProject } from "./schemas/parsers.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, } from "node:fs";
 import { join } from "node:path";
 import { validateDirectory } from "./validate-directory.js";
 import { isCustomProvider, resolveDefaultSessionModel, resolveDynamicRoutingConfig, } from "./preferences-models.js";
@@ -239,7 +240,7 @@ function formatStrandedWorkBlockerMessage(action, activeMilestoneId) {
         `3. Abandon it: run \`/gsd rethink\` and explicitly discard ${target}.`,
     ].join("\n");
 }
-export function auditOrphanedMilestoneBranches(basePath, _isolationMode, gitDeps = {}) {
+export function auditOrphanedMilestoneBranches(basePath, isolationMode, gitDeps = {}) {
     const recovered = [];
     const warnings = [];
     const actions = [];
@@ -286,6 +287,17 @@ export function auditOrphanedMilestoneBranches(basePath, _isolationMode, gitDeps
     catch {
         mergedBranches = new Set();
     }
+    // Detect the branch currently checked out at the project root once — it
+    // does not change across loop iterations and is used below to avoid
+    // requesting a worktree creation for a branch that git already considers
+    // "in use" by the main worktree.
+    let currentRootBranch = null;
+    try {
+        currentRootBranch = nativeGetCurrentBranch(basePath) || null;
+    }
+    catch {
+        currentRootBranch = null;
+    }
     for (const branch of milestoneBranches) {
         const milestoneId = branch.replace(/^milestone\//, "");
         const milestone = getMilestone(milestoneId);
@@ -313,7 +325,26 @@ export function auditOrphanedMilestoneBranches(basePath, _isolationMode, gitDeps
             }
             if ((isMerged || commitsAhead === 0) && !worktreeEvidence.dirty)
                 continue;
-            const recoveryMode = worktreeEvidence.path
+            // #812 — the worktree directory being absent on disk does NOT mean the
+            // project is branch-mode. getAutoWorktreePath() returns null whenever the
+            // directory is merely missing (transient/permanent loss after an
+            // interrupted session), which previously collapsed to recoveryMode:
+            // "branch" — silently checking out milestone/<id> in the project root with
+            // no worktree. When the project is *configured* for worktree isolation,
+            // recover as "worktree" so adoptStrandedMilestone re-materializes the
+            // worktree from the existing branch (createAutoWorktree with
+            // reuseExistingBranch) instead of degrading to branch-mode-in-root.
+            //
+            // Exception (#812-followup): if the milestone branch is already checked
+            // out at the project root (e.g. a leftover from the pre-fix #812 recovery
+            // that ran `git checkout milestone/<id>` in the root), git considers that
+            // branch "in use by another worktree" and will refuse `git worktree add`,
+            // causing bootstrap to abort. Degrade to "branch" in that case — the
+            // session resumes on the already-checked-out branch without worktree
+            // creation, same as pre-fix behavior, and the configured isolation is
+            // restored for subsequent milestones after merge/teardown.
+            const isBranchCheckedOutAtRoot = currentRootBranch === branch;
+            const recoveryMode = worktreeEvidence.path || (isolationMode === "worktree" && !isBranchCheckedOutAtRoot)
                 ? "worktree"
                 : "branch";
             const message = strandedWorkMessage({
@@ -762,7 +793,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     const profileModelIds = modelIdsForProfileResolution(ctx.modelRegistry, resolveProfileAnchorProvider(ctx.model?.provider), resolveDisabledModelProvidersFromPreferences());
     const preferredModel = sessionProviderIsCustom
         ? null
-        : resolveDefaultSessionModel(ctx.model?.provider, base, profileModelIds);
+        : resolveDefaultSessionModel(ctx.model?.provider, base, profileModelIds, ctx.model?.id);
     // Validate the preferred model against the live registry + provider auth so
     // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
     // start-model snapshot. Without this, every subsequent unit would try to
@@ -1125,7 +1156,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 state = await deriveState(base);
             }
         }
-        const effectivePrefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, base, resolveProfileAnchorProvider(ctx.model?.provider, startModelSnapshot?.provider))?.preferences;
+        const effectivePrefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, base, resolveProfileAnchorProvider(ctx.model?.provider, startModelSnapshot?.provider), startModelSnapshot ? `${startModelSnapshot.provider}/${startModelSnapshot.id}` : undefined)?.preferences;
         const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
         const deepProjectStagePending = shouldRunDeepProjectSetup(state, effectivePrefs, base, { hasSurvivorBranch });
         if (deepProjectStagePending && !strandedRecoveryAction) {
@@ -1409,7 +1440,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // FlatRateContext used by selectAndApplyModel so user-declared
         // flat-rate providers and externalCli auto-detection are respected.
         const { isFlatRateProvider, buildFlatRateContext } = await import("./auto-model-selection.js");
-        const bannerPrefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, base, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider))?.preferences;
+        const bannerPrefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, base, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider), s.autoModeStartModel ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}` : undefined)?.preferences;
         const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
         const effectivelyEnabled = routingConfig.enabled
             && (routingConfig.allow_flat_rate_providers
@@ -1450,31 +1481,26 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         }
         // Pre-flight: validate milestone queue
         try {
-            const msDir = join(base, ".gsd", "milestones");
-            if (existsSync(msDir)) {
-                const milestoneIds = readdirSync(msDir, { withFileTypes: true })
-                    .filter((d) => d.isDirectory() && /^M\d{3}/.test(d.name))
-                    .map((d) => d.name.match(/^(M\d{3})/)?.[1] ?? d.name);
-                if (milestoneIds.length > 1) {
-                    const issues = [];
-                    for (const id of milestoneIds) {
-                        // Skip completed/parked milestones — a leftover CONTEXT-DRAFT.md
-                        // on a finished milestone is harmless residue, not an actionable warning.
-                        if (isDbAvailable()) {
-                            const ms = getMilestone(id);
-                            if (ms?.status === "complete" || ms?.status === "parked")
-                                continue;
-                        }
-                        const draft = resolveMilestoneFile(base, id, "CONTEXT-DRAFT");
-                        if (draft)
-                            issues.push(`${id}: has CONTEXT-DRAFT.md (will pause for discussion)`);
-                    }
-                    if (issues.length > 0) {
-                        ctx.ui.notify(`Pre-flight: ${milestoneIds.length} milestones queued.\n${issues.map((i) => `  ⚠ ${i}`).join("\n")}`, "warning");
-                    }
-                    else {
-                        ctx.ui.notify(`Pre-flight: ${milestoneIds.length} milestones queued. All have full context.`, "info");
+            const milestoneIds = findMilestoneIds(base);
+            if (milestoneIds.length > 1) {
+                const issues = [];
+                for (const id of milestoneIds) {
+                    // Skip completed/parked milestones — a leftover CONTEXT-DRAFT.md
+                    // on a finished milestone is harmless residue, not an actionable warning.
+                    if (isDbAvailable()) {
+                        const ms = getMilestone(id);
+                        if (ms?.status === "complete" || ms?.status === "parked")
+                            continue;
                     }
+                    const draft = resolveMilestoneFile(base, id, "CONTEXT-DRAFT");
+                    if (draft)
+                        issues.push(`${id}: has CONTEXT-DRAFT.md (will pause for discussion)`);
+                }
+                if (issues.length > 0) {
+                    ctx.ui.notify(`Pre-flight: ${milestoneIds.length} milestones queued.\n${issues.map((i) => `  ⚠ ${i}`).join("\n")}`, "warning");
+                }
+                else {
+                    ctx.ui.notify(`Pre-flight: ${milestoneIds.length} milestones queued. All have full context.`, "info");
                 }
             }
         }

package/dist/resources/extensions/gsd/auto-timeout-recovery.js

@@ -4,7 +4,7 @@
  * and blocker placeholder generation.
  */
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord, formatExecuteTaskRecoveryStatus, inspectExecuteTaskDurability, } from "./unit-runtime.js";
-import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, writeBlockerPlaceholder, } from "./auto-recovery.js";
+import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, verifyExpectedArtifact, writeBlockerPlaceholder, } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
 import { bumpAndResolveSynthetic } from "./auto/resolve.js";
 import { finalizeProjectResearchTimeout } from "./project-research-policy.js";
@@ -128,10 +128,10 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
         return "recovered";
     }
-    // Check if the artifact already exists on disk — agent may have written it
+    // Check if the artifact is already valid on disk — agent may have written it
     // without signaling completion.
     const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
-    if (artifactPath && existsSync(artifactPath)) {
+    if (artifactPath && existsSync(artifactPath) && verifyExpectedArtifact(unitType, unitId, basePath)) {
         writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
             phase: "finalized",
             recoveryAttempts: recoveryAttempts + 1,

package/dist/resources/extensions/gsd/auto-verification.js

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Post-unit verification gate for GSD auto-mode units.
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { gsdProjectionRoot, resolveSlicePath } from "./paths.js";
+import { relMilestoneFile, resolveSlicePath } from "./paths.js";
 import { resolveMilestoneValidationVerdict } from "./milestone-validation-verdict.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { parseUnitId } from "./unit-id.js";
@@ -9,7 +9,7 @@ import { isDbAvailable, getTask, getSliceTasks, getMilestoneSlices } from "./gsd
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
-import { runVerificationGate, runVerificationGateForTargets, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
+import { runVerificationGate, runVerificationGateForTargets, formatFailureContext, formatFailureSignature, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
 import { runPostExecutionChecks } from "./post-execution-checks.js";
@@ -212,7 +212,10 @@ async function runValidateMilestonePostCheck(vctx, pauseAuto) {
         return incompleteSliceCount > 0 || hasAssessmentArtifact;
     };
     const validationBasePath = resolveCanonicalMilestoneRoot(s.basePath, mid);
-    const validationFile = join(gsdProjectionRoot(validationBasePath), "milestones", mid, `${mid}-VALIDATION.md`);
+    // Layout-aware: matches the writer at tools/validate-milestone.ts:167.
+    // Flat-phase resolves to phases/NN-slug/NN-VALIDATION.md; legacy resolves
+    // to milestones/MID/MID-VALIDATION.md. See open-gsd/gsd-pi#876.
+    const validationFile = join(validationBasePath, relMilestoneFile(validationBasePath, mid, "VALIDATION"));
     const validationContent = await loadFile(validationFile);
     if (validationContent !== null && validationContent.trim() === "") {
         if (await reassessmentInvalidatedValidation()) {
@@ -683,10 +686,13 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 ctx.ui.notify(`Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) during verification retry; keeping verification failure as the authoritative blocker.`, "warning");
             }
             const nextAttempt = attempt + 1;
+            const failureContext = verdict.failureContext || formatFailureContext(result);
+            const failureSignature = formatFailureSignature(result);
             s.verificationRetryCount.set(retryKey, nextAttempt);
             s.pendingVerificationRetry = {
                 unitId: s.currentUnit.id,
-                failureContext: verdict.failureContext || formatFailureContext(result),
+                failureContext,
+                ...(failureSignature ? { signature: failureSignature } : {}),
                 attempt: nextAttempt,
             };
             const failedCmds = result.checks

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

@@ -8,12 +8,12 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, getSliceTasks, } from "./gsd-db.js";
 import { closeWorkflowDatabase, getWorkflowDatabasePath, openWorkflowDatabasePath, } from "./db-workspace.js";
 import { execFileSync } from "node:child_process";
-import { gsdRoot, resolveGsdPathContract } from "./paths.js";
+import { canonicalPhaseDirName, gsdRoot, milestonesDir, resolveGsdPathContract, resolveMilestonePath, } from "./paths.js";
 import { createWorktree, removeWorktree, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { worktreePathFor } from "./worktree-placement.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
@@ -310,9 +310,24 @@ export const SAFE_AUTO_RESOLVE_PATTERNS = [
     /\/__pycache__\//,
     /\.DS_Store$/,
     /\.map$/,
+    // Regenerable dependency lockfiles. These are fully derivable from their
+    // manifests by the package manager, so accepting the merge side during
+    // auto-resolve clears the conflict markers without losing meaningful edits —
+    // and stops auto-mode from hard-pausing on a lockfile conflict (issue #828).
+    /(?:^|\/)pnpm-lock\.yaml$/,
+    /(?:^|\/)package-lock\.json$/,
+    /(?:^|\/)npm-shrinkwrap\.json$/,
+    /(?:^|\/)yarn\.lock$/,
+    /(?:^|\/)bun\.lockb?$/,
+    /(?:^|\/)Cargo\.lock$/,
+    /(?:^|\/)composer\.lock$/,
+    /(?:^|\/)Gemfile\.lock$/,
+    /(?:^|\/)Pipfile\.lock$/,
+    /(?:^|\/)poetry\.lock$/,
 ];
 /** Returns true if the file path is safe to auto-resolve during merge.
- * Covers `.gsd/` state files and common build artifacts. */
+ * Covers `.gsd/` state files, common build artifacts, and regenerable
+ * dependency lockfiles. */
 export const isSafeToAutoResolve = (filePath) => filePath.startsWith(".gsd/") ||
     SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
 // ─── Dispatch-Level Sync (project root ↔ worktree) ──────────────────────────
@@ -559,99 +574,102 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
             }
         }
     }
-    // Sync milestones: copy entire milestone directories that are missing
-    const mainMilestonesDir = join(mainGsd, "milestones");
-    const wtMilestonesDir = join(wtGsd, "milestones");
-    if (existsSync(mainMilestonesDir)) {
-        try {
-            mkdirSync(wtMilestonesDir, { recursive: true });
-            const mainMilestones = readdirSync(mainMilestonesDir, {
-                withFileTypes: true,
-            })
-                .filter((d) => d.isDirectory())
-                .map((d) => d.name);
-            for (const mid of mainMilestones) {
-                const srcDir = join(mainMilestonesDir, mid);
-                const dstDir = join(wtMilestonesDir, mid);
-                if (!existsSync(dstDir)) {
-                    // Entire milestone missing from worktree — copy it
-                    try {
-                        cpSync(srcDir, dstDir, { recursive: true });
-                        synced.push(`milestones/${mid}/`);
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
+    // Sync milestone/phase trees: copy entire directories that are missing.
+    // Support both flat-phase (phases/) and legacy (milestones/) layouts.
+    for (const layoutSegment of ["phases", "milestones"]) {
+        const mainMilestonesDir = join(mainGsd, layoutSegment);
+        const wtMilestonesDir = join(wtGsd, layoutSegment);
+        if (existsSync(mainMilestonesDir)) {
+            try {
+                mkdirSync(wtMilestonesDir, { recursive: true });
+                const mainMilestones = readdirSync(mainMilestonesDir, {
+                    withFileTypes: true,
+                })
+                    .filter((d) => d.isDirectory())
+                    .map((d) => d.name);
+                for (const mid of mainMilestones) {
+                    const srcDir = join(mainMilestonesDir, mid);
+                    const dstDir = join(wtMilestonesDir, mid);
+                    if (!existsSync(dstDir)) {
+                        // Entire milestone missing from worktree — copy it
+                        try {
+                            cpSync(srcDir, dstDir, { recursive: true });
+                            synced.push(`milestones/${mid}/`);
+                        }
+                        catch (err) {
+                            /* non-fatal */
+                            logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
-                }
-                else {
-                    // Milestone directory exists but may be missing files (stale snapshot).
-                    // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
-                    try {
-                        const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
-                        for (const f of srcFiles) {
-                            const srcFile = join(srcDir, f);
-                            const dstFile = join(dstDir, f);
-                            if (!existsSync(dstFile)) {
-                                try {
-                                    const srcStat = lstatSyncFn(srcFile);
-                                    if (srcStat.isFile()) {
-                                        cpSync(srcFile, dstFile);
-                                        synced.push(`milestones/${mid}/${f}`);
+                    else {
+                        // Milestone directory exists but may be missing files (stale snapshot).
+                        // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
+                        try {
+                            const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
+                            for (const f of srcFiles) {
+                                const srcFile = join(srcDir, f);
+                                const dstFile = join(dstDir, f);
+                                if (!existsSync(dstFile)) {
+                                    try {
+                                        const srcStat = lstatSyncFn(srcFile);
+                                        if (srcStat.isFile()) {
+                                            cpSync(srcFile, dstFile);
+                                            synced.push(`milestones/${mid}/${f}`);
+                                        }
                                     }
+                                    catch (err) {
+                                        /* non-fatal */
+                                        logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
+                                    }
+                                }
+                            }
+                            // Sync slices directory if it exists in main but not in worktree
+                            const srcSlicesDir = join(srcDir, "slices");
+                            const dstSlicesDir = join(dstDir, "slices");
+                            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
+                                try {
+                                    cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+                                    synced.push(`milestones/${mid}/slices/`);
                                 }
                                 catch (err) {
                                     /* non-fatal */
-                                    logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
+                                    logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
                                 }
                             }
-                        }
-                        // Sync slices directory if it exists in main but not in worktree
-                        const srcSlicesDir = join(srcDir, "slices");
-                        const dstSlicesDir = join(dstDir, "slices");
-                        if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
-                            try {
-                                cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
-                                synced.push(`milestones/${mid}/slices/`);
-                            }
-                            catch (err) {
-                                /* non-fatal */
-                                logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-                            }
-                        }
-                        else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
-                            // Both exist — sync missing slice directories
-                            const srcSlices = readdirSync(srcSlicesDir, {
-                                withFileTypes: true,
-                            })
-                                .filter((d) => d.isDirectory())
-                                .map((d) => d.name);
-                            for (const sid of srcSlices) {
-                                const srcSlice = join(srcSlicesDir, sid);
-                                const dstSlice = join(dstSlicesDir, sid);
-                                if (!existsSync(dstSlice)) {
-                                    try {
-                                        cpSync(srcSlice, dstSlice, { recursive: true });
-                                        synced.push(`milestones/${mid}/slices/${sid}/`);
-                                    }
-                                    catch (err) {
-                                        /* non-fatal */
-                                        logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
+                            else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
+                                // Both exist — sync missing slice directories
+                                const srcSlices = readdirSync(srcSlicesDir, {
+                                    withFileTypes: true,
+                                })
+                                    .filter((d) => d.isDirectory())
+                                    .map((d) => d.name);
+                                for (const sid of srcSlices) {
+                                    const srcSlice = join(srcSlicesDir, sid);
+                                    const dstSlice = join(dstSlicesDir, sid);
+                                    if (!existsSync(dstSlice)) {
+                                        try {
+                                            cpSync(srcSlice, dstSlice, { recursive: true });
+                                            synced.push(`milestones/${mid}/slices/${sid}/`);
+                                        }
+                                        catch (err) {
+                                            /* non-fatal */
+                                            logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
+                                        }
                                     }
                                 }
                             }
                         }
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                        catch (err) {
+                            /* non-fatal */
+                            logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
                 }
             }
-        }
-        catch (err) {
-            /* non-fatal */
-            logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            catch (err) {
+                /* non-fatal */
+                logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return { synced };
@@ -1507,10 +1525,18 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
     // does not sweep queued CONTEXT files into the stash. If stash pop later
     // fails, files trapped inside the stash are permanently lost (#2505).
-    const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
+    const planningDir = milestonesDir(originalBasePath_);
     const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
     const shelteredDirs = [];
     let shelterRestored = false;
+    const mergeDirNames = new Set([milestoneId]);
+    const resolvedMergeDir = resolveMilestonePath(originalBasePath_, milestoneId);
+    if (resolvedMergeDir) {
+        mergeDirNames.add(basename(resolvedMergeDir));
+    }
+    else {
+        mergeDirNames.add(canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+    }
     // Helper: restore sheltered milestone directories (#2505).
     // Called on both success and error paths to ensure queued CONTEXT files
     // are never permanently lost. Idempotent — the error path may fire after
@@ -1535,11 +1561,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 continue;
             }
             try {
-                mkdirSync(milestonesDir, { recursive: true });
+                mkdirSync(planningDir, { recursive: true });
                 // Test seam: when _restoreEntryFn is injected, route the copy through it
                 // so the best-effort failure path (and shelter-retention guarantee) can
                 // be exercised deterministically. Production leaves it null → real cpSync.
-                const dest = join(milestonesDir, dirName);
+                const dest = join(planningDir, dirName);
                 if (_restoreEntryFn) {
                     _restoreEntryFn(src, dest);
                 }
@@ -1569,15 +1595,15 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
     };
     try {
-        if (existsSync(milestonesDir)) {
-            const entries = readdirSync(milestonesDir, { withFileTypes: true });
+        if (existsSync(planningDir)) {
+            const entries = readdirSync(planningDir, { withFileTypes: true });
             for (const entry of entries) {
                 if (!entry.isDirectory())
                     continue;
                 // Only shelter directories that do NOT belong to the milestone being merged
-                if (entry.name === milestoneId)
+                if (mergeDirNames.has(entry.name))
                     continue;
-                const srcDir = join(milestonesDir, entry.name);
+                const srcDir = join(planningDir, entry.name);
                 const dstDir = join(shelterDir, entry.name);
                 try {
                     mkdirSync(shelterDir, { recursive: true });
@@ -1602,8 +1628,8 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     //     branch. Passing NO pathspec lets git skip gitignored paths silently;
     //     adding an explicit pathspec trips a `git add`-style fatal on ignored
     //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
-    //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
-    //     in step 7 above, so they won't be swept into the stash.
+    //     Queued CONTEXT files under `.gsd/phases/*` (or legacy milestones/*)
+    //     are already sheltered in step 7 above, so they won't be swept into the stash.
     // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
     // sidecars while the connection is open. `git stash --include-untracked`
     // walks those files and fails with EBUSY (#4704). Close the DB before