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

package/src/resources/extensions/gsd/auto-direct-dispatch.ts

@@ -33,14 +33,27 @@ import { pauseAuto } from "./auto.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 
+export function parseDirectDispatchPhase(raw: string): { phase: string; milestoneId?: string } {
+  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: ExtensionCommandContext,
   pi: ExtensionAPI,
   phase: string,
   base: string,
+  opts: { milestoneId?: string } = {},
 ): Promise<void> {
+  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) {
@@ -56,7 +69,7 @@ export async function dispatchDirectPhase(
   // 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: string;
   let unitId: string;
   let prompt: string;

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -12,7 +12,7 @@
  * without modifying orchestration code.
  */
 
-import type { GSDState } from "./types.js";
+import type { GSDState, TaskIO } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
 import type { MinimalModelRegistry } from "./context-budget.js";
 import { loadFile, extractUatType, loadActiveOverrides } from "./files.js";
@@ -179,6 +179,26 @@ type ResearchProjectPromptBuilder = typeof buildResearchProjectPrompt;
 let reassessmentChecker: ReassessmentChecker = checkNeedsReassessment;
 let researchProjectPromptBuilder: 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: ((basePath: string, mid: string, sid: string) => Promise<TaskIO[]>) | null = null;
+
+export function setReactiveGraphDeriveFnForTest(
+  fn: ((basePath: string, mid: string, sid: string) => Promise<TaskIO[]>) | null,
+): () => void {
+  const previous = _reactiveGraphDeriveFn;
+  _reactiveGraphDeriveFn = fn;
+  return () => { _reactiveGraphDeriveFn = previous; };
+}
+
 function shouldBypassMilestoneDepthGateInAuto(prefs: GSDPreferences | undefined): boolean {
   return isAutoActive() && prefs?.planning_depth !== "deep";
 }
@@ -1421,7 +1441,9 @@ export const DISPATCH_RULES: DispatchRule[] = [
           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/src/resources/extensions/gsd/auto-model-selection.ts

@@ -17,6 +17,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";
@@ -404,8 +405,10 @@ export function resolvePreferredModelConfig(
   unitType: string,
   autoModeStartModel: { provider: string; id: string; flatRateCtx?: FlatRateContext } | null,
   isAutoMode = true,
+  basePath?: string,
+  availableModelIds?: string[],
 ): PreferredModelConfig | undefined {
-  const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
+  const explicitConfig = resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds);
   if (explicitConfig) {
     return {
       ...explicitConfig,
@@ -475,8 +478,14 @@ export async function selectAndApplyModel(
   // 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 anchorProvider = resolveProfileAnchorProvider(ctx.model?.provider, autoModeStartModel?.provider);
+  const profileResolutionIds = modelIdsForProfileResolution(
+    ctx.modelRegistry,
+    anchorProvider,
+    resolveDisabledModelProvidersFromPreferences(),
+  );
   const explicitThinkingLevel =
-    resolveThinkingLevelForUnit(unitType) as ReturnType<ExtensionAPI["getThinkingLevel"]> | undefined;
+    resolveThinkingLevelForUnit(unitType, basePath, profileResolutionIds) as ReturnType<ExtensionAPI["getThinkingLevel"]> | undefined;
   const desiredThinkingLevel = explicitThinkingLevel
     ?? floorThinkingLevelForUnit(unitType, autoModeStartThinkingLevel);
   if (explicitThinkingLevel) {
@@ -520,7 +529,13 @@ export async function selectAndApplyModel(
   }
   const modelConfig = effectiveSessionModelOverride
     ? undefined
-    : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
+    : resolvePreferredModelConfig(
+      unitType,
+      autoModeStartModel,
+      isAutoMode,
+      basePath,
+      profileResolutionIds,
+    );
   let routing: { tier: string; modelDowngraded: boolean } | null = null;
   let appliedModel: Model<Api> | null = null;
 
@@ -1068,16 +1083,16 @@ export function resolveModelId<T extends { id: string; provider: string }>(
  *
  * 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",
 ] as const;
 
 /**

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -2100,9 +2100,6 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
             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,
@@ -2111,6 +2108,9 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
               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,
@@ -2131,14 +2131,21 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
               unitCostUsd,
               rollingAvgUsd,
             );
+            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(
-              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",
+              `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",
             );
-            await pauseAuto(ctx, pi);
-            return "dispatched";
           }
           const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1;
           const failureDetails = describeArtifactVerificationFailure(

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -3891,7 +3891,11 @@ export async function buildReactiveExecutePrompt(
     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/src/resources/extensions/gsd/auto-recovery.ts

@@ -83,6 +83,53 @@ export {
 } 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: ((content: string) => { slices: Array<{ id: string; done: boolean; depends?: string[] }> }) | null = 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: ((content: string) => { slices: Array<{ id: string; done: boolean; depends?: string[] }> }) | null,
+): () => void {
+  const previous = _roadmapParserFn;
+  _roadmapParserFn = fn;
+  return () => { _roadmapParserFn = previous; };
+}
+
+function parseRoadmapForRecovery(content: string): ReturnType<NonNullable<typeof _roadmapParserFn>> {
+  if (_roadmapParserFn) return _roadmapParserFn(content);
+  return parseLegacyRoadmap(content) as unknown as ReturnType<NonNullable<typeof _roadmapParserFn>>;
+}
+
+/**
+ * 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: ((basePath: string, mid: string) => void | Promise<void>) | null = null;
+
+export function _setGithubFinalizeFnForTests(
+  fn: ((basePath: string, mid: string) => void | Promise<void>) | null,
+): () => void {
+  const previous = _githubFinalizeFn;
+  _githubFinalizeFn = fn;
+  return () => { _githubFinalizeFn = previous; };
+}
+
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
 export function diagnoseWorktreeIntegrityFailure(basePath: string): string | null {
@@ -197,11 +244,18 @@ export function refreshRecoveryDbForArtifact(
     }
 
     updateMilestoneStatus(mid, "complete", new Date().toISOString());
-    void import("../github-sync/sync.js")
-      .then(({ finalizeMilestoneGitHubSync }) => finalizeMilestoneGitHubSync(basePath, mid))
-      .catch((err) => {
-        logWarning("recovery", `GitHub milestone finalize failed after DB closeout: ${getErrorMessage(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<void>((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 };
   }
 
@@ -446,7 +500,7 @@ export function verifyExpectedArtifact(
       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) {
@@ -506,7 +560,7 @@ export function verifyExpectedArtifact(
 
   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;
@@ -615,7 +669,7 @@ export function verifyExpectedArtifact(
         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;
           } catch (e) {

package/src/resources/extensions/gsd/auto-start.ts

@@ -21,6 +21,10 @@ import { loadFile, getManifestStatus } from "./files.js";
 import type { InterruptedSessionAssessment } from "./interrupted-session.js";
 import {
   loadEffectiveGSDPreferences,
+  loadEffectiveGSDPreferencesWithRegistry,
+  modelIdsForProfileResolution,
+  resolveProfileAnchorProvider,
+  resolveDisabledModelProvidersFromPreferences,
   resolveSkillDiscoveryMode,
   getIsolationMode,
 } from "./preferences.js";
@@ -1012,9 +1016,14 @@ export async function bootstrapAutoSession(
   // 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
@@ -1271,11 +1280,29 @@ export async function bootstrapAutoSession(
       }
     }
 
-    const blockingStrandedRecoveryAction = state.activeMilestone
-      ? strandedRecoveryActions.find(
+    const requestedMilestoneLock = process.env.GSD_MILESTONE_LOCK?.trim() || null;
+    const lockedActiveMilestone =
+      requestedMilestoneLock && state.activeMilestone?.id === requestedMilestoneLock;
+    let blockingStrandedRecoveryAction: OrphanAuditAction | null;
+    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
-      : strandedRecoveryAction;
+      ) ?? strandedRecoveryAction;
+    } else {
+      blockingStrandedRecoveryAction = strandedRecoveryAction;
+    }
 
     if (blockingStrandedRecoveryAction) {
       if (!state.activeMilestone) {
@@ -1297,6 +1324,8 @@ export async function bootstrapAutoSession(
         formatStrandedWorkRecoveryMessage(strandedRecoveryAction),
         "info",
       );
+    } else if (lockedActiveMilestone) {
+      strandedRecoveryAction = null;
     }
 
     if (
@@ -1436,7 +1465,11 @@ export async function bootstrapAutoSession(
       }
     }
 
-    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,
@@ -1788,7 +1821,11 @@ export async function bootstrapAutoSession(
     // 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/src/resources/extensions/gsd/auto-worktree.ts

@@ -242,6 +242,17 @@ function stripGsdDisplayPrefix(value: string | undefined | null, id: string): st
 /** Active workspace registry — replaces the legacy `originalBase` singleton. */
 let activeWorkspace: GsdWorkspace | null = 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: ((src: string, dest: string) => void) | null = null;
+
 function setActiveWorkspace(ws: GsdWorkspace | null): void {
   activeWorkspace = ws;
 }
@@ -972,6 +983,14 @@ function _resolveIntegrationBranchForReuse(
   }
 }
 
+function safeCwd(fallback: string): string {
+  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
@@ -1155,7 +1174,7 @@ export function teardownAutoWorktree(
 
   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
@@ -1250,7 +1269,7 @@ export function teardownAutoWorktree(
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath: string): boolean {
-  const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+  const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
   if (!isGsdWorktreePath(targetPath)) return false;
 
   const storedBase = getAutoWorktreeOriginalBase();
@@ -1386,6 +1405,22 @@ export function _resetAutoWorktreeOriginalBaseForTests(): void {
   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: ((src: string, dest: string) => void) | null,
+): () => void {
+  _restoreEntryFn = fn;
+  return () => { _restoreEntryFn = null; };
+}
+
 export function getActiveAutoWorktreeContext(): {
   originalBase: string;
   worktreeName: string;
@@ -1795,7 +1830,15 @@ export function mergeMilestoneToMain(
       }
       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;
         logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
@@ -2229,6 +2272,11 @@ export function mergeMilestoneToMain(
       process.chdir(originalBasePath_);
     } 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),
+      });
     }
   };