@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -1,8 +1,19 @@
 import { execSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { basename, dirname, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import {
+  supportsStructuredQuestions,
+  usesWorkflowMcpTransport,
+} from "./question-transport.js";
+import {
+  WORKFLOW_TOOL_SURFACE_NAMES,
+  isWorkflowToolSurfaceName,
+} from "./workflow-tool-surface.js";
+
+export { supportsStructuredQuestions, usesWorkflowMcpTransport };
 
 type WorkflowExecutorsModule = typeof import("./tools/workflow-tool-executors.js");
 
@@ -42,73 +53,9 @@ export function resolveWorkflowMcpProjectRoot(sessionCwd: string): string {
   return resolved;
 }
 
-const MCP_WORKFLOW_TOOL_SURFACE = new Set([
-  "gsd_cancel",
-  "gsd_captures",
-  "ask_user_questions",
-  "gsd_capture_thought",
-  "gsd_doctor",
-  "gsd_execute",
-  "gsd_memory_query",
-  "gsd_memory_graph",
-  "gsd_decision_save",
-  "gsd_exec",
-  "gsd_exec_search",
-  "gsd_graph",
-  "gsd_history",
-  "gsd_knowledge",
-  "gsd_progress",
-  "gsd_query",
-  "gsd_resume",
-  "gsd_result",
-  "gsd_resolve_blocker",
-  "gsd_roadmap",
-  "gsd_status",
-  "gsd_complete_milestone",
-  "gsd_complete_task",
-  "gsd_complete_slice",
-  "gsd_generate_milestone_id",
-  "gsd_journal_query",
-  "gsd_milestone_complete",
-  "gsd_milestone_generate_id",
-  "gsd_milestone_reopen",
-  "gsd_checkpoint_db",
-  "gsd_milestone_plan",
-  "gsd_milestone_status",
-  "gsd_milestone_validate",
-  "gsd_plan_task",
-  "gsd_plan_milestone",
-  "gsd_plan_slice",
-  "gsd_replan_slice",
-  "gsd_reassess_roadmap",
-  "gsd_reopen_milestone",
-  "gsd_reopen_slice",
-  "gsd_reopen_task",
-  "gsd_requirement_save",
-  "gsd_requirement_update",
-  "gsd_roadmap_reassess",
-  "gsd_save_decision",
-  "gsd_save_gate_result",
-  "gsd_save_requirement",
-  "gsd_save_summary",
-  "gsd_skip_slice",
-  "gsd_slice_plan",
-  "gsd_slice_replan",
-  "gsd_slice_complete",
-  "gsd_slice_reopen",
-  "gsd_summary_save",
-  "gsd_task_plan",
-  "gsd_task_complete",
-  "gsd_task_reopen",
-  "gsd_update_requirement",
-  "gsd_uat_exec",
-  "gsd_uat_result_save",
-  "gsd_validate_milestone",
-]);
-
 /** Workflow MCP tools are validated by transport compatibility, not pi tool-compat profiles. */
 export function isWorkflowMcpSurfaceTool(toolName: string): boolean {
-  return MCP_WORKFLOW_TOOL_SURFACE.has(toolName);
+  return isWorkflowToolSurfaceName(toolName);
 }
 
 function parseLookupOutput(output: Buffer | string): string {
@@ -276,8 +223,12 @@ function getBundledWorkflowWriteGateModulePath(): string | null {
 
 function getResolveTsHookPath(): string | null {
   const repoRoot = findGsdPiRepoRoot(dirname(fileURLToPath(import.meta.url)));
+  const sourceRepoRoot = repoRoot && basename(repoRoot) === "dist-test" ? dirname(repoRoot) : repoRoot;
   return firstExistingPath([
-    ...(repoRoot
+    ...(sourceRepoRoot
+      ? [resolve(sourceRepoRoot, "src", "resources", "extensions", "gsd", "tests", "resolve-ts.mjs")]
+      : []),
+    ...(repoRoot && repoRoot !== sourceRepoRoot
       ? [resolve(repoRoot, "src", "resources", "extensions", "gsd", "tests", "resolve-ts.mjs")]
       : []),
     resolve(fileURLToPath(new URL("./tests/resolve-ts.mjs", import.meta.url))),
@@ -421,52 +372,13 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[]
   return getRequiredWorkflowToolsForUnit(unitType);
 }
 
-export function usesWorkflowMcpTransport(
-  authMode: WorkflowCapabilityOptions["authMode"],
-  baseUrl: string | undefined,
-): boolean {
-  return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
-}
-
-function hasAskUserQuestionsTool(activeTools: string[]): boolean {
-  return activeTools.some((toolName) => {
-    if (toolName === "ask_user_questions") return true;
-    if (!toolName.startsWith("mcp__")) return false;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === "ask_user_questions";
-  });
-}
-
 function hasRequiredTool(requiredTool: string, activeTools: string[]): boolean {
   return activeTools.some((toolName) => {
     if (toolName === requiredTool) return true;
-    if (!toolName.startsWith("mcp__")) return false;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === requiredTool;
+    return mcpToolMatchesBaseName(toolName, requiredTool);
   });
 }
 
-function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
-  const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
-  return value === "1" || value === "true";
-}
-
-export function supportsStructuredQuestions(
-  activeTools: string[],
-  options: Pick<WorkflowCapabilityOptions, "authMode" | "baseUrl" | "env"> = {},
-): boolean {
-  if (!hasAskUserQuestionsTool(activeTools)) return false;
-  if (usesWorkflowMcpTransport(options.authMode, options.baseUrl)) {
-    // Claude Code local workflow-MCP exposes ask_user_questions, but form
-    // elicitation can return an immediate cancel outside GSD's chat turn. Keep
-    // checkpoints in plain chat unless a caller deliberately opts into testing
-    // that transport.
-    return workflowMcpStructuredQuestionsOptIn(options.env);
-  }
-
-  return true;
-}
-
 export function getWorkflowTransportSupportError(
   provider: string | undefined,
   requiredTools: string[],
@@ -488,13 +400,13 @@ export function getWorkflowTransportSupportError(
 
   const uniqueRequired = [...new Set(requiredTools)];
   const missing = (options.activeTools && options.activeTools.length > 0)
-    ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
-    : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
+    ? uniqueRequired.filter((tool) => !isWorkflowToolSurfaceName(tool) && !hasRequiredTool(tool, options.activeTools!))
+    : uniqueRequired.filter((tool) => !isWorkflowToolSurfaceName(tool));
   if (missing.length === 0) return null;
 
   if (options.activeTools && options.activeTools.length > 0) {
     return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the active runtime toolset currently exposes only ${options.activeTools.slice().sort().join(", ")}.`;
   }
 
-  return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${Array.from(MCP_WORKFLOW_TOOL_SURFACE).sort().join(", ")}.`;
+  return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${[...WORKFLOW_TOOL_SURFACE_NAMES].sort().join(", ")}.`;
 }

package/src/resources/extensions/gsd/workflow-reconcile.ts

@@ -13,11 +13,11 @@ import {
   getMilestoneSlices,
   insertVerificationEvidence,
   upsertDecision,
-  openDatabase,
   setTaskBlockerDiscovered,
   insertOrIgnoreSlice,
   insertOrIgnoreTask,
 } from "./gsd-db.js";
+import { openWorkflowDatabasePath } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
 import { invalidateStateCache } from "./state.js";
 import { clearPathCache, resolveGsdPathContract } from "./paths.js";
@@ -500,7 +500,7 @@ function _reconcileWorktreeLogsInner(
   atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
 
   // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
-  openDatabase(resolveGsdPathContract(mainBasePath).projectDb);
+  openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
   replayEvents(merged);
 
   // Step 9: Write manifest
@@ -655,7 +655,7 @@ export function resolveConflict(
   writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
 
   // Replay resolved events through the DB (updates DB state)
-  openDatabase(resolveGsdPathContract(basePath).projectDb);
+  openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);
   replayEvents(eventsToReplay);
   invalidateStateCache();
   clearPathCache();

package/src/resources/extensions/gsd/workflow-tool-surface.ts

@@ -0,0 +1,73 @@
+// Project/App: gsd-pi
+// File Purpose: Adapts shared workflow tool contracts into the extension runtime surface.
+
+import {
+  CANONICAL_WORKFLOW_TOOL_NAMES as CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES,
+  WORKFLOW_TOOL_ALIAS_NAMES as CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES,
+  WORKFLOW_TOOL_CONTRACTS as CONTRACT_WORKFLOW_TOOL_CONTRACTS,
+  WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES,
+} from "@opengsd/contracts";
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+
+export interface WorkflowToolAliasPair {
+  canonical: string;
+  alias: string;
+}
+
+export const WORKFLOW_TOOL_CONTRACTS = CONTRACT_WORKFLOW_TOOL_CONTRACTS;
+
+export const CANONICAL_WORKFLOW_TOOL_NAMES = CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES;
+export const WORKFLOW_TOOL_ALIAS_NAMES = CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES;
+export const DB_WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
+
+export const WORKFLOW_TOOL_ALIAS_PAIRS: readonly WorkflowToolAliasPair[] =
+  WORKFLOW_TOOL_CONTRACTS.flatMap((tool) =>
+    tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })),
+  );
+
+export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL: Readonly<Record<string, string>> =
+  Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
+
+const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+  "gsd_cancel",
+  "gsd_captures",
+  "ask_user_questions",
+  "gsd_doctor",
+  "gsd_execute",
+  "gsd_graph",
+  "gsd_history",
+  "gsd_knowledge",
+  "gsd_progress",
+  "gsd_query",
+  "gsd_result",
+  "gsd_resolve_blocker",
+  "gsd_roadmap",
+  "gsd_status",
+] as const;
+
+export const WORKFLOW_TOOL_SURFACE_NAMES = [
+  ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
+  ...DB_WORKFLOW_TOOL_NAMES,
+] as readonly string[];
+
+const WORKFLOW_TOOL_SURFACE_NAME_SET = new Set(WORKFLOW_TOOL_SURFACE_NAMES);
+
+export { stripMcpToolPrefix } from "./mcp-tool-name.js";
+
+export function canonicalWorkflowSurfaceToolName(toolName: string): string {
+  const baseName = stripMcpToolPrefix(toolName);
+  return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+}
+
+export function isWorkflowSurfaceAliasTool(toolName: string): boolean {
+  const baseName = stripMcpToolPrefix(toolName);
+  return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] !== undefined;
+}
+
+export function isWorkflowToolSurfaceName(toolName: string): boolean {
+  return WORKFLOW_TOOL_SURFACE_NAME_SET.has(stripMcpToolPrefix(toolName));
+}
+
+export function aliasesForWorkflowTool(canonicalName: string): readonly string[] {
+  return WORKFLOW_TOOL_CONTRACTS.find((tool) => tool.canonicalName === canonicalName)?.aliases ?? [];
+}

package/src/resources/extensions/gsd/workspace-git-guard.ts

@@ -14,6 +14,7 @@ export function isWorkspaceGitAllowedCommand(trimmed: string): boolean {
 
   const [name, subcommand] = command.split(/\s+/, 2);
   if (name === "doctor") return true;
+  if (name === "forensics") return true;
   if (name === "closeout" || command.startsWith("closeout")) return true;
   if (name === "dispatch") {
     return subcommand === "complete" || subcommand === "complete-milestone";

package/src/resources/extensions/gsd/worktree-git-recovery.ts

@@ -0,0 +1,308 @@
+// Project/App: gsd-pi
+// File Purpose: Git checkout/stash/merge-state recovery primitives for worktree operations.
+
+/**
+ * Worktree Git Recovery — the recurring-bug hot spot, in one place.
+ *
+ * Owns the verbs that recover a repository from interrupted or conflicting
+ * git operations during worktree transitions:
+ *
+ *   - `checkoutBranchWithStashGuard` — branch switch with stash protection,
+ *     including the stash-pop EEXIST collision recovery for `.gsd/` runtime
+ *     files (force-checkout + targeted stash drop).
+ *   - `removeMergeStateFiles` — clears SQUASH_MSG / MERGE_HEAD / etc. left by
+ *     a failed merge so subsequent merges don't fail on stale state.
+ *   - `cleanupConflictState` — merge-abort + index reset + state-file cleanup
+ *     after a conflicted (including squash) merge.
+ *   - stash helpers (`popStashByRef`, `stashRefFromError`,
+ *     `stashAlreadyExistsFilesFromError`, `gsdJsonlFilesWithConflictMarkers`)
+ *     used by the merge pipeline in auto-worktree.ts.
+ *
+ * Extracted from auto-worktree.ts so recovery fixes land here instead of as
+ * embedded special cases in a 2,600-line orchestration module, and so the
+ * rules can be tested against scripted git states.
+ *
+ * The State Reconciliation drift repair (`state-reconciliation/drift/
+ * merge-state.ts`) keeps its own merge-state primitive by design — drift
+ * repairs own their raw primitives (see CONTEXT.md, Drift repair).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { debugLog } from "./debug-logger.js";
+import { logError, logWarning } from "./workflow-logger.js";
+import {
+  nativeAddPaths,
+  nativeCheckoutBranch,
+  nativeConflictFiles,
+  nativeLsFiles,
+  nativeMergeAbort,
+  nativeWorkingTreeStatus,
+} from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+
+/**
+ * Pop the stash entry created with `stashMarker` in its subject, resolving it
+ * to a concrete `stash@{n}` ref first so a concurrent stash push cannot make
+ * `git stash pop` grab the wrong entry.
+ *
+ * If `stashMarker` is null or no longer present in the stash list (e.g. a
+ * concurrent process popped/dropped it), leaves the stash list untouched and
+ * returns null.
+ *
+ * Throws on pop failure so callers can handle conflict cases the same way
+ * they would with the prior `git stash pop` form. When throwing after a
+ * targeted pop attempt, the error is annotated with the targeted stash ref.
+ *
+ * (Issue #4980 HIGH-6)
+ */
+export function popStashByRef(basePath: string, stashMarker: string | null): string | null {
+  let popArg: string | null = null;
+  if (stashMarker) {
+    try {
+      const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      }).trim().split("\n").filter(Boolean);
+      for (const entry of list) {
+        const [ref, subject] = entry.split("\0");
+        if (ref && subject?.includes(stashMarker)) {
+          popArg = ref;
+          break;
+        }
+      }
+    } catch (err) {
+      logWarning("worktree", `stash list lookup failed; leaving stash untouched: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (!popArg) {
+    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic pop");
+    return null;
+  }
+  try {
+    execFileSync("git", ["stash", "pop", popArg], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    if (err && typeof err === "object") {
+      (err as { stashRef?: string }).stashRef = popArg;
+    }
+    throw err;
+  }
+  return popArg;
+}
+
+/**
+ * Extract a stash ref annotation injected by popStashByRef() when git stash
+ * pop fails and we need to conditionally drop the exact stash entry later.
+ */
+export function stashRefFromError(err: unknown): string | null {
+  if (!err || typeof err !== "object") return null;
+  const stashRef = (err as { stashRef?: unknown }).stashRef;
+  return typeof stashRef === "string" && stashRef.length > 0 ? stashRef : null;
+}
+
+export function stashAlreadyExistsFilesFromError(err: unknown): string[] {
+  if (!err || typeof err !== "object") return [];
+  const stderr = (err as { stderr?: unknown }).stderr;
+  const stderrText = typeof stderr === "string"
+    ? stderr
+    : stderr instanceof Uint8Array
+      ? Buffer.from(stderr).toString("utf-8")
+      : "";
+  const message = err instanceof Error ? err.message : String(err);
+  const text = `${stderrText}\n${message}`;
+  const files = new Set<string>();
+  for (const line of text.split("\n")) {
+    const m = line.match(/^(.*?)\s+already exists, no checkout\s*$/i);
+    if (!m) continue;
+    const filePath = m[1]?.trim();
+    if (filePath) files.add(filePath);
+  }
+  return [...files];
+}
+
+/**
+ * Detect whether an on-disk file still contains unresolved merge conflict
+ * markers from a failed stash-pop or merge attempt.
+ *
+ * Returns false when the file cannot be read.
+ */
+export function hasConflictMarkers(filePath: string): boolean {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return content.includes("<<<<<<<") && content.includes("=======") && content.includes(">>>>>>>");
+  } catch {
+    return false;
+  }
+}
+
+export function gsdJsonlFilesWithConflictMarkers(basePath: string): string[] {
+  return nativeLsFiles(basePath, ".gsd/*.jsonl").filter((f) =>
+    hasConflictMarkers(join(basePath, f)),
+  );
+}
+
+export function removeMergeStateFiles(basePath: string, contextLabel: string): void {
+  try {
+    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
+      const rawPath = execFileSync("git", ["rev-parse", "--git-path", f], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      }).trim();
+      const p = rawPath.length > 0
+        ? (isAbsolute(rawPath) ? rawPath : resolve(basePath, rawPath))
+        : join(resolveGitDir(basePath), f);
+      if (existsSync(p)) unlinkSync(p);
+    }
+  } catch (err) {
+    logError("worktree", `${contextLabel} merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export function cleanupConflictState(basePath: string): void {
+  // Merge conflicts can leave unmerged index entries; merge-abort alone is not
+  // enough for squash merges (MERGE_HEAD is never written). Reset the merge
+  // index, then remove merge message files that native/libgit2 paths may have
+  // created.
+  try {
+    nativeMergeAbort(basePath);
+  } catch (err) {
+    // MERGE_HEAD absent (squash merge path) — abort is a no-op, which is fine.
+    debugLog("conflict-cleanup:merge-abort-skipped", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+  try {
+    execFileSync("git", ["reset", "--merge"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    logError("worktree", `git reset --merge failed after merge conflict: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  removeMergeStateFiles(basePath, "conflict");
+}
+
+export function checkoutBranchWithStashGuard(
+  basePath: string,
+  branch: string,
+  reason: string,
+): void {
+  let stashMarker: string | null = null;
+  let stashed = false;
+
+  const status = nativeWorkingTreeStatus(basePath).trim();
+  if (status.length > 0) {
+    stashMarker = `gsd-checkout-stash:${reason}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+    const stashListBefore = execFileSync("git", ["stash", "list"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    execFileSync(
+      "git",
+      ["stash", "push", "--include-untracked", "-m", `gsd: checkout stash [${stashMarker}]`],
+      {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      },
+    );
+    const stashListAfter = execFileSync("git", ["stash", "list"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    stashed = stashListAfter !== stashListBefore;
+  }
+
+  // Checkout and stash-restore are split so we can distinguish two failure
+  // modes: (a) checkout failed → HEAD did not move, restore stash and rethrow;
+  // (b) checkout succeeded but stash pop failed → HEAD moved to `branch` but
+  // the working-tree changes remain in the stash list. We surface a distinct
+  // error in case (b) so callers don't assume the branch switch was rolled back.
+  try {
+    nativeCheckoutBranch(basePath, branch);
+  } catch (checkoutErr) {
+    if (stashed) {
+      try {
+        popStashByRef(basePath, stashMarker);
+      } catch (restoreErr) {
+        logWarning("worktree", `git stash pop failed during checkout restore: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+      }
+    }
+    throw checkoutErr;
+  }
+
+  if (stashed) {
+    try {
+      popStashByRef(basePath, stashMarker);
+    } catch (popErr) {
+      const msg = popErr instanceof Error ? popErr.message : String(popErr);
+      const stderr = popErr && typeof popErr === "object"
+        ? (popErr as { stderr?: unknown }).stderr
+        : undefined;
+      const stderrText = typeof stderr === "string"
+        ? stderr
+        : stderr instanceof Uint8Array
+          ? Buffer.from(stderr).toString("utf-8")
+          : "";
+      const stashPopMessage = `${stderrText}\n${msg}`.trim();
+      const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
+      const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
+      const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
+      const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+      const stashRefForDrop = stashRefFromError(popErr);
+      const nonGsdUnmerged = nativeConflictFiles(basePath).filter((f) => !f.startsWith(".gsd/"));
+      const gsdContentConflicts = isUntrackedRestoreFailure
+        ? gsdJsonlFilesWithConflictMarkers(basePath)
+        : [];
+      const gsdConflictFiles = [...new Set([...gsdAlreadyExists, ...gsdContentConflicts])];
+
+      if (
+        isUntrackedRestoreFailure &&
+        gsdConflictFiles.length > 0 &&
+        nonGsdAlreadyExists.length === 0 &&
+        nonGsdUnmerged.length === 0
+      ) {
+        for (const f of gsdConflictFiles) {
+          execFileSync("git", ["checkout", "HEAD", "--", f], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+          });
+          nativeAddPaths(basePath, [f]);
+        }
+
+        if (stashRefForDrop) {
+          try {
+            execFileSync("git", ["stash", "drop", stashRefForDrop], {
+              cwd: basePath,
+              stdio: ["ignore", "pipe", "pipe"],
+              encoding: "utf-8",
+            });
+          } catch (err) { /* stash may already be consumed */
+            logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        } else {
+          logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
+        }
+        return;
+      }
+
+      const wrapped = new Error(
+        `checkout to '${branch}' succeeded but stash restore failed; working tree changes remain in the stash list. Original error: ${msg}`,
+      );
+      if (stashRefForDrop) (wrapped as { stashRef?: string }).stashRef = stashRefForDrop;
+      throw wrapped;
+    }
+  }
+}

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -79,6 +79,7 @@ import {
   teardownAutoWorktree,
 } from "./auto-worktree.js";
 import { resolveRoadmapForMilestoneMerge } from "./milestone-merge-roadmap.js";
+import type { MilestoneMergeTransactionRunner } from "./milestone-merge-transaction.js";
 
 const recentWorktreeMergeFailures = new Map<string, number>();
 const MERGE_FAILURE_DEDUPE_MS = 60_000;
@@ -147,25 +148,15 @@ export interface WorktreeLifecycleDeps {
    */
   worktreeProjection: WorktreeStateProjection;
 
-  // ── Merge primitive ──────────────────────────────────────────────────
+  // ── Merge transaction ────────────────────────────────────────────────
   /**
-   * Inner squash-merge primitive (`auto-worktree.ts:mergeMilestoneToMain`).
+   * Milestone Merge Transaction Module runner.
    *
-   * **Module-internal seam — do not construct your own.** Only the wiring
-   * factory `auto.ts:buildWorktreeLifecycleDeps()` is permitted to populate
-   * this field. The primitive is `@internal`; production callers reach the
-   * merge body through `WorktreeLifecycle.exitMilestone({ merge: true })`,
-   * never by calling this dep directly.
+   * The field name is preserved for existing test fixtures, but production
+   * wiring now supplies the named transaction wrapper rather than the raw
+   * squash-merge primitive directly.
    */
-  mergeMilestoneToMain: (
-    basePath: string,
-    milestoneId: string,
-    roadmapContent: string,
-  ) => {
-    pushed: boolean;
-    codeFilesChanged: boolean;
-    commitMessage?: string;
-  };
+  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
 
   // ADR-016 phase 2 / C1 + C2 + C3 + C4 inlined the following fields as
   // direct imports — leaf primitives that did not vary across callers:
@@ -684,7 +675,16 @@ export function _enterMilestoneCore(
   // Handles the case where originalBasePath is falsy and basePath is itself
   // a worktree path — prevents double-nested worktree paths (#3729).
   const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-  const mode = opts.modeOverride ?? getIsolationMode(basePath);
+  // A stranded-recovery session that adopted the milestone branch in the
+  // project root must keep re-entering in that mode: the root checkout holds
+  // the branch, so creating the canonical worktree would fail with "already
+  // in use by another worktree". The override clears when the recovered
+  // milestone merges (_mergeAndExit), restoring configured isolation for
+  // subsequent milestones.
+  const mode =
+    opts.modeOverride ??
+    s.strandedRecoveryIsolationMode ??
+    getIsolationMode(basePath);
 
   if (s.isolationDegraded) {
     if (mode === "worktree") {