@opengsd/gsd-pi 1.2.0-dev.0b870afa → 1.2.0-dev.23d85b63

package/dist/resources/extensions/gsd/auto-direct-dispatch.js

@@ -11,9 +11,21 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { pauseAuto } from "./auto.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
-export async function dispatchDirectPhase(ctx, pi, phase, base) {
+export function parseDirectDispatchPhase(raw) {
+    const tokens = raw.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return { phase: "" };
+    const phase = tokens[0].toLowerCase();
+    const milestoneToken = tokens.find((token, index) => index > 0 && /^M\d/i.test(token));
+    return {
+        phase,
+        milestoneId: milestoneToken?.replace(/[.,;:!?]+$/, ""),
+    };
+}
+export async function dispatchDirectPhase(ctx, pi, phase, base, opts = {}) {
+    const parsed = parseDirectDispatchPhase(phase);
     const state = await deriveState(base);
-    const mid = state.activeMilestone?.id;
+    const mid = opts.milestoneId ?? parsed.milestoneId ?? state.activeMilestone?.id;
     const midTitle = state.activeMilestone?.title ?? "";
     if (!mid) {
         ctx.ui.notify("Cannot dispatch: no active milestone.", "warning");
@@ -25,7 +37,7 @@ export async function dispatchDirectPhase(ctx, pi, phase, base) {
     // build prompts and create a session anchored to the project root even
     // though the milestone's actual code lives in the worktree.
     const dispatchBase = resolveCanonicalMilestoneRoot(base, mid);
-    const normalized = phase.toLowerCase();
+    const normalized = parsed.phase;
     let unitType;
     let unitId;
     let prompt;

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

@@ -48,6 +48,22 @@ function resolveExistingExpectedArtifact(unitType, unitId, basePath) {
 }
 let reassessmentChecker = checkNeedsReassessment;
 let researchProjectPromptBuilder = buildResearchProjectPrompt;
+/**
+ * Optional override for the reactive graph derivation step inside the
+ * "executing → reactive-execute" rule. Production leaves this null so the rule
+ * uses the real loadSliceTaskIO + deriveTaskGraph; tests inject a throwing
+ * function to deterministically exercise the best-effort failure path
+ * (auto-dispatch.ts:1494). The catch is otherwise unreachable because every
+ * operation it wraps (loadSliceTaskIO, deriveTaskGraph, saveReactiveState) is
+ * internally defensive.
+ * @internal
+ */
+let _reactiveGraphDeriveFn = null;
+export function setReactiveGraphDeriveFnForTest(fn) {
+    const previous = _reactiveGraphDeriveFn;
+    _reactiveGraphDeriveFn = fn;
+    return () => { _reactiveGraphDeriveFn = previous; };
+}
 function shouldBypassMilestoneDepthGateInAuto(prefs) {
     return isAutoActive() && prefs?.planning_depth !== "deep";
 }
@@ -1155,7 +1171,9 @@ export const DISPATCH_RULES = [
                 return null;
             try {
                 const { loadSliceTaskIO, deriveTaskGraph, isGraphAmbiguous, getReadyTasks, chooseNonConflictingSubset, graphMetrics, } = await import("./reactive-graph.js");
-                const taskIO = await loadSliceTaskIO(basePath, mid, sid);
+                const taskIO = _reactiveGraphDeriveFn
+                    ? await _reactiveGraphDeriveFn(basePath, mid, sid)
+                    : await loadSliceTaskIO(basePath, mid, sid);
                 if (taskIO.length < 2)
                     return null; // single task, no point
                 const graph = deriveTaskGraph(taskIO);

package/dist/resources/extensions/gsd/auto-model-selection.js

@@ -12,6 +12,7 @@ import { unitPhaseLabel } from "./auto-dashboard.js";
 import { getSessionModelOverride } from "./session-model-override.js";
 import { logWarning } from "./workflow-logger.js";
 import { resolveUokFlags } from "./uok/flags.js";
+import { modelIdsForProfileResolution, resolveProfileAnchorProvider, resolveDisabledModelProvidersFromPreferences } from "./preferences.js";
 import { applyModelPolicyFilter } from "./uok/model-policy.js";
 import { isModelBlocked, isModelTemporarilyUnavailable } from "./blocked-models.js";
 import { getRequiredWorkflowToolsForAutoUnit, isWorkflowMcpSurfaceTool } from "./workflow-mcp.js";
@@ -324,8 +325,8 @@ export function floorThinkingLevelForUnit(unitType, level) {
     }
     return EXECUTE_TASK_MIN_THINKING_LEVEL;
 }
-export function resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode = true) {
-    const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
+export function resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode = true, basePath, availableModelIds) {
+    const explicitConfig = resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds);
     if (explicitConfig) {
         return {
             ...explicitConfig,
@@ -380,7 +381,9 @@ autoModeStartThinkingLevel) {
     // With no explicit level, fall back to the auto-start session level and raise
     // the code-writing floor — preserving prior behavior exactly. Recomputed per
     // dispatch so neither the floor nor a phase override leaks to other units.
-    const explicitThinkingLevel = resolveThinkingLevelForUnit(unitType);
+    const anchorProvider = resolveProfileAnchorProvider(ctx.model?.provider, autoModeStartModel?.provider);
+    const profileResolutionIds = modelIdsForProfileResolution(ctx.modelRegistry, anchorProvider, resolveDisabledModelProvidersFromPreferences());
+    const explicitThinkingLevel = resolveThinkingLevelForUnit(unitType, basePath, profileResolutionIds);
     const desiredThinkingLevel = explicitThinkingLevel
         ?? floorThinkingLevelForUnit(unitType, autoModeStartThinkingLevel);
     if (explicitThinkingLevel) {
@@ -415,7 +418,7 @@ autoModeStartThinkingLevel) {
     }
     const modelConfig = effectiveSessionModelOverride
         ? undefined
-        : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
+        : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode, basePath, profileResolutionIds);
     let routing = null;
     let appliedModel = null;
     // ── Restore active-tool baseline before policy evaluation (#4959, #4681, #4850) ──
@@ -860,16 +863,16 @@ export function resolveModelId(modelId, availableModels, currentProvider) {
  *
  * Order rationale:
  * - openai-codex before github-copilot: ChatGPT-native for shared GPT IDs
- * - google-gemini-cli before github-copilot: first-party Gemini CLI
+ * - google-antigravity before google-gemini-cli: Antigravity replaced Gemini CLI for individuals
  * - anthropic before github-copilot: first-party Claude API/OAuth over Copilot
  * - github-copilot before openai/google: Copilot OAuth over platform API keys
  */
 export const BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE = [
     "openai-codex",
+    "google-antigravity",
     "google-gemini-cli",
     "anthropic",
     "github-copilot",
-    "google-antigravity",
 ];
 /**
  * Flat-rate providers charge the same per request regardless of model.

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -1766,11 +1766,11 @@ export async function postUnitPreVerification(pctx, opts) {
                         return "dispatched";
                     }
                     if (getUnitCostSpikeAction(unitCostUsd, rollingAvgUsd, resolveUnitCostSpikeMultiplier(prefs)) === "pause") {
-                        s.pendingVerificationRetry = null;
-                        s.verificationRetryCount.delete(retryKey);
-                        s.verificationRetryFailureHashes.delete(retryKey);
                         const advancedPastUnit = await hasArtifactCostGuardAdvancedPastUnit(s, ctx, s.currentUnit.type, s.currentUnit.id, prefs);
                         if (advancedPastUnit) {
+                            s.pendingVerificationRetry = null;
+                            s.verificationRetryCount.delete(retryKey);
+                            s.verificationRetryFailureHashes.delete(retryKey);
                             debugLog("postUnit", {
                                 phase: "artifact-cost-spike-continue-after-advance",
                                 unitType: s.currentUnit.type,
@@ -1782,11 +1782,15 @@ export async function postUnitPreVerification(pctx, opts) {
                             return "continue";
                         }
                         const parallelBlocker = maybeWriteParallelResearchCostSpikeBlocker(s.currentUnit.type, s.currentUnit.id, verificationBasePath, unitCostUsd, rollingAvgUsd);
-                        ctx.ui.notify(parallelBlocker
-                            ? `Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) — wrote parallel blocker and pausing auto-mode.`
-                            : `Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) — pausing auto-mode.`, "error");
-                        await pauseAuto(ctx, pi);
-                        return "dispatched";
+                        if (parallelBlocker) {
+                            s.pendingVerificationRetry = null;
+                            s.verificationRetryCount.delete(retryKey);
+                            s.verificationRetryFailureHashes.delete(retryKey);
+                            ctx.ui.notify(`Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) — wrote parallel blocker and pausing auto-mode.`, "error");
+                            await pauseAuto(ctx, pi);
+                            return "dispatched";
+                        }
+                        ctx.ui.notify(`Unit ${s.currentUnit.id} cost spike detected (${unitCostUsd.toFixed(2)} vs avg ${rollingAvgUsd.toFixed(2)}) during artifact verification retry; keeping verification failure as the authoritative blocker.`, "warning");
                     }
                     const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1;
                     const failureDetails = describeArtifactVerificationFailure(s.currentUnit.type, s.currentUnit.id, verificationBasePath, s.lastUnitAgentEndMessages);

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

@@ -3372,7 +3372,11 @@ opts) {
         const taskPrompt = [
             `## UNIT: Execute Task ${tid} ("${tTitle}")`,
             "",
-            "Work only in the repository root.",
+            "## Working Directory",
+            "",
+            `Your working directory is \`${base}\`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT \`cd\` to any other directory.`,
+            `If any inlined plan names an absolute path outside \`${base}\`, treat it as stale — use the equivalent path under \`${base}\` before reading, writing, or executing.`,
+            "",
             "Implement from the inlined task plan below. Verify changes, then call `gsd_task_complete`.",
             "Do not run git commands.",
             "",

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

@@ -38,6 +38,45 @@ import { proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
 export { classifyMilestoneSummaryContent, } from "./milestone-summary-classifier.js";
 export { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
+/**
+ * Optional override for the legacy roadmap parser used by verifyExpectedArtifact.
+ * Production leaves this null so the real parseLegacyRoadmap runs; tests inject
+ * a throwing function to deterministically exercise the parse-failure catches
+ * (auto-recovery.ts:515 plan-milestone and :622 complete-slice). Those catches
+ * are otherwise unreachable because parseLegacyRoadmap is internally defensive
+ * against every malformed input.
+ * @internal
+ */
+let _roadmapParserFn = null;
+/**
+ * Inject an override for the legacy roadmap parser, returning a function that
+ * restores the default (real parser) behavior. No production caller.
+ * @internal
+ */
+export function _setRoadmapParserFnForTests(fn) {
+    const previous = _roadmapParserFn;
+    _roadmapParserFn = fn;
+    return () => { _roadmapParserFn = previous; };
+}
+function parseRoadmapForRecovery(content) {
+    if (_roadmapParserFn)
+        return _roadmapParserFn(content);
+    return parseLegacyRoadmap(content);
+}
+/**
+ * Optional override for the detached GitHub milestone finalize invoked after DB
+ * closeout in refreshRecoveryDbForArtifact. Production leaves this null so the
+ * real finalizeMilestoneGitHubSync runs; tests inject a throwing function to
+ * deterministically exercise the best-effort catch (auto-recovery.ts:232),
+ * which otherwise needs a real GitHub remote + network failure.
+ * @internal
+ */
+let _githubFinalizeFn = null;
+export function _setGithubFinalizeFnForTests(fn) {
+    const previous = _githubFinalizeFn;
+    _githubFinalizeFn = fn;
+    return () => { _githubFinalizeFn = previous; };
+}
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 export function diagnoseWorktreeIntegrityFailure(basePath) {
     if (!isGsdWorktreePath(basePath))
@@ -139,9 +178,16 @@ export function refreshRecoveryDbForArtifact(unitType, unitId, basePath) {
             };
         }
         updateMilestoneStatus(mid, "complete", new Date().toISOString());
-        void import("../github-sync/sync.js")
-            .then(({ finalizeMilestoneGitHubSync }) => finalizeMilestoneGitHubSync(basePath, mid))
-            .catch((err) => {
+        // Detached GitHub sync — best-effort. Test seam: when
+        // _githubFinalizeFn is injected, route through it so the catch
+        // (:232) is deterministically reachable (otherwise it needs a real
+        // GitHub remote + network failure). Production leaves it null. The
+        // seam is wrapped so a synchronous throw becomes a rejected promise,
+        // matching the real import-then-call deferred semantics.
+        const finalizePromise = _githubFinalizeFn
+            ? new Promise((resolve) => { resolve(_githubFinalizeFn(basePath, mid)); })
+            : import("../github-sync/sync.js").then(({ finalizeMilestoneGitHubSync }) => finalizeMilestoneGitHubSync(basePath, mid));
+        void finalizePromise.catch((err) => {
             logWarning("recovery", `GitHub milestone finalize failed after DB closeout: ${getErrorMessage(err)}`);
         });
         return { ok: true };
@@ -369,7 +415,7 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
             return false;
         }
         try {
-            const roadmap = parseLegacyRoadmap(readFileSync(roadmapFile, "utf-8"));
+            const roadmap = parseRoadmapForRecovery(readFileSync(roadmapFile, "utf-8"));
             const milestoneResearchFile = resolveExpectedArtifactPath("research-milestone", mid, base);
             const hasMilestoneResearch = !!milestoneResearchFile && existsSync(milestoneResearchFile);
             for (const slice of roadmap.slices) {
@@ -429,7 +475,7 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
     }
     if (unitType === "plan-milestone") {
         try {
-            const roadmap = parseLegacyRoadmap(readFileSync(absPath, "utf-8"));
+            const roadmap = parseRoadmapForRecovery(readFileSync(absPath, "utf-8"));
             if (roadmap.slices.length === 0) {
                 logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${absPath}`);
                 return false;
@@ -542,7 +588,7 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
                 if (roadmapFile && existsSync(roadmapFile)) {
                     try {
                         const roadmapContent = readFileSync(roadmapFile, "utf-8");
-                        const roadmap = parseLegacyRoadmap(roadmapContent);
+                        const roadmap = parseRoadmapForRecovery(roadmapContent);
                         const slice = roadmap.slices.find((s) => s.id === sid);
                         if (slice && !slice.done)
                             return false;

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

@@ -13,7 +13,7 @@
 import { deriveState } from "./state.js";
 import { findWorktreeSegment, isGsdWorktreePath } from "./worktree-root.js";
 import { loadFile, getManifestStatus } from "./files.js";
-import { loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, getIsolationMode, } from "./preferences.js";
+import { loadEffectiveGSDPreferences, loadEffectiveGSDPreferencesWithRegistry, modelIdsForProfileResolution, resolveProfileAnchorProvider, resolveDisabledModelProvidersFromPreferences, resolveSkillDiscoveryMode, getIsolationMode, } from "./preferences.js";
 import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-identity.js";
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
@@ -759,9 +759,10 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     // run /login" before pausing and resetting to claude-code/claude-sonnet-4-6.
     const manualSessionOverride = getSessionModelOverride(ctx.sessionManager.getSessionId());
     const sessionProviderIsCustom = isCustomProvider(ctx.model?.provider);
+    const profileModelIds = modelIdsForProfileResolution(ctx.modelRegistry, resolveProfileAnchorProvider(ctx.model?.provider), resolveDisabledModelProvidersFromPreferences());
     const preferredModel = sessionProviderIsCustom
         ? null
-        : resolveDefaultSessionModel(ctx.model?.provider, base);
+        : resolveDefaultSessionModel(ctx.model?.provider, base, profileModelIds);
     // 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
@@ -976,9 +977,26 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 state = await deriveState(wtPath);
             }
         }
-        const blockingStrandedRecoveryAction = state.activeMilestone
-            ? strandedRecoveryActions.find((action) => action.milestoneId !== state.activeMilestone?.id) ?? strandedRecoveryAction
-            : strandedRecoveryAction;
+        const requestedMilestoneLock = process.env.GSD_MILESTONE_LOCK?.trim() || null;
+        const lockedActiveMilestone = requestedMilestoneLock && state.activeMilestone?.id === requestedMilestoneLock;
+        let blockingStrandedRecoveryAction;
+        if (lockedActiveMilestone) {
+            // Parallel worker or explicit `/gsd auto Mxxx`: sibling milestones'
+            // stranded work must not block this milestone's resumption, and the
+            // downstream `strandedRecoveryAction` (used for currentMilestoneId,
+            // setActiveMilestoneId, and adoptStrandedMilestone) must be scoped to
+            // the locked milestone only. Falling back to the first sibling action
+            // would mis-target adoption (#742).
+            const lockMatch = strandedRecoveryActions.find((action) => action.milestoneId === requestedMilestoneLock) ?? null;
+            blockingStrandedRecoveryAction = lockMatch;
+            strandedRecoveryAction = lockMatch;
+        }
+        else if (state.activeMilestone) {
+            blockingStrandedRecoveryAction = strandedRecoveryActions.find((action) => action.milestoneId !== state.activeMilestone?.id) ?? strandedRecoveryAction;
+        }
+        else {
+            blockingStrandedRecoveryAction = strandedRecoveryAction;
+        }
         if (blockingStrandedRecoveryAction) {
             if (!state.activeMilestone) {
                 ctx.ui.notify(formatStrandedWorkBlockerMessage(blockingStrandedRecoveryAction, null), "error");
@@ -991,6 +1009,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             strandedRecoveryAction = blockingStrandedRecoveryAction;
             ctx.ui.notify(formatStrandedWorkRecoveryMessage(strandedRecoveryAction), "info");
         }
+        else if (lockedActiveMilestone) {
+            strandedRecoveryAction = null;
+        }
         if (process.env.GSD_HEADLESS === "1" &&
             orphanAuditRecovered &&
             !state.activeMilestone &&
@@ -1104,7 +1125,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 state = await deriveState(base);
             }
         }
-        const effectivePrefs = loadEffectiveGSDPreferences(base)?.preferences;
+        const effectivePrefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, base, resolveProfileAnchorProvider(ctx.model?.provider, startModelSnapshot?.provider))?.preferences;
         const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
         const deepProjectStagePending = shouldRunDeepProjectSetup(state, effectivePrefs, base, { hasSurvivorBranch });
         if (deepProjectStagePending && !strandedRecoveryAction) {
@@ -1388,7 +1409,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 = loadEffectiveGSDPreferences(base)?.preferences;
+        const bannerPrefs = loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, base, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider))?.preferences;
         const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
         const effectivelyEnabled = routingConfig.enabled
             && (routingConfig.allow_flat_rate_providers

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

@@ -141,6 +141,16 @@ function stripGsdDisplayPrefix(value, id) {
 // ─── Module State ──────────────────────────────────────────────────────────
 /** Active workspace registry — replaces the legacy `originalBase` singleton. */
 let activeWorkspace = null;
+/**
+ * Optional override for the shelter restore copy step (milestone merge #2505).
+ * Production leaves this null so restoreShelter uses the real cpSync; tests
+ * inject a throwing function to deterministically exercise the best-effort
+ * failure path (auto-worktree.ts:1809) and the shelter-retention guarantee,
+ * which is otherwise unreachable because shelter and restore run synchronously
+ * in one mergeMilestoneToMain call (the filesystem cannot change between them).
+ * @internal
+ */
+let _restoreEntryFn = null;
 function setActiveWorkspace(ws) {
     activeWorkspace = ws;
 }
@@ -800,6 +810,14 @@ function _resolveIntegrationBranchForReuse(basePath, milestoneId) {
         return null;
     }
 }
+function safeCwd(fallback) {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * When reusing an existing milestone branch, fast-forward it onto the
  * integration branch when that's safe (branch is a strict ancestor of
@@ -949,7 +967,7 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
     originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false, preserveWorktree = false } = opts;
-    const previousCwd = process.cwd();
+    const previousCwd = safeCwd(originalBasePath);
     // Wrap the entire teardown body in a single try/finally so activeWorkspace
     // is ALWAYS cleared — even if process.chdir throws (e.g. originalBasePath
     // was deleted before teardown ran). Previously the finally only covered
@@ -1033,7 +1051,7 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath) {
-    const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+    const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
     if (!isGsdWorktreePath(targetPath))
         return false;
     const storedBase = getAutoWorktreeOriginalBase();
@@ -1140,6 +1158,19 @@ export function getAutoWorktreeOriginalBase() {
 export function _resetAutoWorktreeOriginalBaseForTests() {
     setActiveWorkspace(null);
 }
+/**
+ * Inject an override for the shelter restore copy step, returning a function
+ * that restores the default (real cpSync) behavior. Used by tests to
+ * deterministically exercise the best-effort restore-failure path
+ * (auto-worktree.ts:1809) and the #2505 shelter-retention guarantee — which is
+ * otherwise unreachable because shelter + restore run synchronously in one
+ * mergeMilestoneToMain call. No production caller.
+ * @internal
+ */
+export function _setRestoreEntryFnForTests(fn) {
+    _restoreEntryFn = fn;
+    return () => { _restoreEntryFn = null; };
+}
 export function getActiveAutoWorktreeContext() {
     const ws = getActiveWorkspace();
     if (!ws)
@@ -1505,7 +1536,16 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             }
             try {
                 mkdirSync(milestonesDir, { recursive: true });
-                cpSync(src, join(milestonesDir, dirName), { recursive: true, force: 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);
+                if (_restoreEntryFn) {
+                    _restoreEntryFn(src, dest);
+                }
+                else {
+                    cpSync(src, dest, { recursive: true, force: true });
+                }
             }
             catch (err) { /* best-effort */
                 restoreFailed = true;
@@ -1901,6 +1941,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
         catch (err) {
             logWarning("worktree", `chdir to project root after merge failed: ${err instanceof Error ? err.message : String(err)}`);
+            debugLog("mergeMilestoneToMain", {
+                phase: "post-merge-chdir-failed",
+                target: originalBasePath_,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     };
     let shouldCleanup = false;