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

package/src/resources/extensions/gsd/auto-worktree-merge-db-ready.ts

@@ -0,0 +1,112 @@
+// gsd-pi — Milestone merge DB readiness guard.
+//
+// Owns the invariant that, before leaving worktree context for a milestone
+// merge, the project DB is the active DB, worktree DB state is reconciled, and
+// canonical closeout state proves the milestone is safe to merge.
+
+import { join } from "node:path";
+
+import { CLOSEOUT_CONSISTENCY_BLOCKED_REASON } from "./closeout-consistency-gate.js";
+import {
+  closeWorkflowDatabase,
+  getWorkflowDatabasePath,
+  openWorkflowDatabasePath,
+} from "./db-workspace.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  isDbAvailable,
+  reconcileWorktreeDb,
+} from "./gsd-db.js";
+import {
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { _shouldReconcileWorktreeDb } from "./auto-worktree-cleanup.js";
+import { logError } from "./workflow-logger.js";
+
+export interface MilestoneDbReadyRequest {
+  milestoneId: string;
+  projectRoot: string;
+  worktreeCwd: string;
+}
+
+interface MergeDbReadyDeps {
+  closeWorkflowDatabase: typeof closeWorkflowDatabase;
+  formatCloseoutProofBlock: typeof formatCloseoutProofBlock;
+  getWorkflowDatabasePath: typeof getWorkflowDatabasePath;
+  isDbAvailable: typeof isDbAvailable;
+  logError: typeof logError;
+  openWorkflowDatabasePath: typeof openWorkflowDatabasePath;
+  proveMilestoneCloseout: typeof proveMilestoneCloseout;
+  reconcileWorktreeDb: typeof reconcileWorktreeDb;
+  resolveGsdPathContract: typeof resolveGsdPathContract;
+  shouldReconcileWorktreeDb: typeof _shouldReconcileWorktreeDb;
+}
+
+const defaultDeps: MergeDbReadyDeps = {
+  closeWorkflowDatabase,
+  formatCloseoutProofBlock,
+  getWorkflowDatabasePath,
+  isDbAvailable,
+  logError,
+  openWorkflowDatabasePath,
+  proveMilestoneCloseout,
+  reconcileWorktreeDb,
+  resolveGsdPathContract,
+  shouldReconcileWorktreeDb: _shouldReconcileWorktreeDb,
+};
+
+let deps: MergeDbReadyDeps = defaultDeps;
+
+export function _setMergeDbReadyDepsForTests(
+  overrides: Partial<MergeDbReadyDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMergeDbReadyDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+function reconcileWorktreeDatabase(request: MilestoneDbReadyRequest): void {
+  const { milestoneId, projectRoot, worktreeCwd } = request;
+  const contract = deps.resolveGsdPathContract(worktreeCwd, projectRoot);
+  const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
+  const mainDbPath = contract.projectDb;
+
+  try {
+    const activeDbPath = deps.getWorkflowDatabasePath();
+    if (activeDbPath && deps.shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
+      deps.closeWorkflowDatabase();
+      if (!deps.openWorkflowDatabasePath(mainDbPath)) {
+        throw new Error(`cannot open project DB at ${mainDbPath}`);
+      }
+    }
+    if (deps.shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
+      deps.reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+    }
+  } catch (err) {
+    const message = `DB reconciliation failed before milestone ${milestoneId} merge: ${err instanceof Error ? err.message : String(err)}`;
+    deps.logError("worktree", message);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`,
+    );
+  }
+}
+
+function assertCloseoutProof(milestoneId: string): void {
+  const closeoutProof = deps.proveMilestoneCloseout(milestoneId);
+  if (!closeoutProof.ok) {
+    throw new GSDError(GSD_GIT_ERROR, deps.formatCloseoutProofBlock(closeoutProof));
+  }
+}
+
+export function assertMilestoneDbReadyForMerge(
+  request: MilestoneDbReadyRequest,
+): void {
+  if (!deps.isDbAvailable()) return;
+  reconcileWorktreeDatabase(request);
+  assertCloseoutProof(request.milestoneId);
+}

package/src/resources/extensions/gsd/auto-worktree-merge-integration-branch.ts

@@ -0,0 +1,99 @@
+// gsd-pi — Milestone merge integration-branch preparation.
+//
+// Owns branch-selection safety before the merge transaction touches the project
+// root: resolve integration branch, fail closed on self-merge metadata, clear
+// transient milestone state, reject detached HEAD, and checkout when needed.
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  resolveMilestoneIntegrationBranch,
+} from "./git-service.js";
+import {
+  nativeCheckoutBranch,
+  nativeDetectMainBranch,
+  nativeGetCurrentBranch,
+} from "./native-git-bridge.js";
+import { clearProjectRootStateFiles } from "./auto-worktree-cleanup.js";
+
+export interface PrepareIntegrationBranchRequest {
+  milestoneBranch: string;
+  milestoneId: string;
+  prefs: Parameters<typeof resolveMilestoneIntegrationBranch>[2];
+  previousCwd: string;
+  projectRoot: string;
+}
+
+export interface PreparedIntegrationBranch {
+  mainBranch: string;
+}
+
+interface MergeIntegrationBranchDeps {
+  chdir: typeof process.chdir;
+  clearProjectRootStateFiles: typeof clearProjectRootStateFiles;
+  nativeCheckoutBranch: typeof nativeCheckoutBranch;
+  nativeDetectMainBranch: typeof nativeDetectMainBranch;
+  nativeGetCurrentBranch: typeof nativeGetCurrentBranch;
+  resolveMilestoneIntegrationBranch: typeof resolveMilestoneIntegrationBranch;
+}
+
+const defaultDeps: MergeIntegrationBranchDeps = {
+  chdir: process.chdir.bind(process),
+  clearProjectRootStateFiles,
+  nativeCheckoutBranch,
+  nativeDetectMainBranch,
+  nativeGetCurrentBranch,
+  resolveMilestoneIntegrationBranch,
+};
+
+let deps: MergeIntegrationBranchDeps = defaultDeps;
+
+export function _setMergeIntegrationBranchDepsForTests(
+  overrides: Partial<MergeIntegrationBranchDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMergeIntegrationBranchDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+function normalizeLocalBranchRef(branch: string): string {
+  return branch.startsWith("refs/heads/")
+    ? branch.slice("refs/heads/".length)
+    : branch;
+}
+
+export function prepareIntegrationBranchForMilestoneMerge(
+  request: PrepareIntegrationBranchRequest,
+): PreparedIntegrationBranch {
+  const { milestoneBranch, milestoneId, prefs, previousCwd, projectRoot } = request;
+  const branchResolution = deps.resolveMilestoneIntegrationBranch(projectRoot, milestoneId, prefs);
+  const mainBranch = branchResolution.effectiveBranch ?? deps.nativeDetectMainBranch(projectRoot);
+
+  if (normalizeLocalBranchRef(mainBranch) === milestoneBranch) {
+    deps.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Resolved integration branch "${mainBranch}" is the same ref as milestone branch ` +
+      `"${milestoneBranch}" — refusing to self-merge. ${branchResolution.reason}. ` +
+      `Repair milestone integration metadata before retrying milestone completion.`,
+    );
+  }
+
+  deps.clearProjectRootStateFiles(projectRoot, milestoneId);
+
+  const currentBranchAtBase = deps.nativeGetCurrentBranch(projectRoot);
+  if (!currentBranchAtBase || currentBranchAtBase.length === 0) {
+    deps.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Project root is in detached HEAD state — cannot perform milestone merge. ` +
+      `Checkout an integration branch (e.g. \`git checkout ${mainBranch}\`) before resuming.`,
+    );
+  }
+  if (currentBranchAtBase !== mainBranch) {
+    deps.nativeCheckoutBranch(projectRoot, mainBranch);
+  }
+
+  return { mainBranch };
+}

package/src/resources/extensions/gsd/auto-worktree-merge-message.ts

@@ -0,0 +1,166 @@
+// gsd-pi — Milestone merge commit-message construction.
+//
+// Owns the completed-slice/task summary and milestone title fallback policy used
+// by auto-worktree milestone merge commits and publication summaries.
+
+import {
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+} from "./gsd-db.js";
+
+interface CompletedTaskSummary {
+  id: string;
+  title: string;
+}
+
+interface CompletedSliceSummary {
+  id: string;
+  title: string;
+  tasks: CompletedTaskSummary[];
+}
+
+export interface MilestoneMergeMessageRequest {
+  milestoneId: string;
+  milestoneBranch: string;
+  roadmapContent: string;
+}
+
+export interface MilestoneMergeMessage {
+  commitMessage: string;
+  milestoneTitle: string;
+  sliceSummaries: string[];
+}
+
+interface MilestoneMergeMessageDeps {
+  isDbAvailable: typeof isDbAvailable;
+  getMilestone: typeof getMilestone;
+  getMilestoneSlices: typeof getMilestoneSlices;
+  getSliceTasks: typeof getSliceTasks;
+}
+
+const defaultDeps: MilestoneMergeMessageDeps = {
+  isDbAvailable,
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+};
+
+let deps: MilestoneMergeMessageDeps = defaultDeps;
+
+export function _setMilestoneMergeMessageDepsForTests(
+  overrides: Partial<MilestoneMergeMessageDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMilestoneMergeMessageDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+function stripGsdDisplayPrefix(value: string | undefined | null, id: string): string | undefined {
+  const raw = String(value ?? "").trim();
+  if (!raw) return undefined;
+
+  const lower = raw.toLowerCase();
+  const idLower = id.toLowerCase();
+  if (lower.startsWith(`${idLower}:`)) {
+    return raw.slice(id.length + 1).trim() || undefined;
+  }
+  return raw;
+}
+
+function getDbCompletedSlices(milestoneId: string): CompletedSliceSummary[] {
+  if (!deps.isDbAvailable()) return [];
+  return deps.getMilestoneSlices(milestoneId)
+    .filter((slice) => slice.status === "complete")
+    .map((slice) => ({
+      id: slice.id,
+      title: stripGsdDisplayPrefix(slice.title, slice.id) ?? slice.id,
+      tasks: deps.getSliceTasks(milestoneId, slice.id)
+        .filter((task) => task.status === "complete")
+        .map((task) => ({
+          id: task.id,
+          title: stripGsdDisplayPrefix(task.title, task.id) ?? task.id,
+        })),
+    }));
+}
+
+function getRoadmapCompletedSlices(roadmapContent: string): CompletedSliceSummary[] {
+  if (!roadmapContent) return [];
+
+  const completedSlices: CompletedSliceSummary[] = [];
+  const sliceRe = /- \[x\] \*\*(\w+):\s*(.+?)\*\*/gi;
+  let match: RegExpExecArray | null;
+  while ((match = sliceRe.exec(roadmapContent)) !== null) {
+    completedSlices.push({ id: match[1], title: match[2], tasks: [] });
+  }
+  return completedSlices;
+}
+
+function getCompletedSlices(
+  milestoneId: string,
+  roadmapContent: string,
+): CompletedSliceSummary[] {
+  const dbCompletedSlices = getDbCompletedSlices(milestoneId);
+  if (dbCompletedSlices.length > 0) return dbCompletedSlices;
+  return getRoadmapCompletedSlices(roadmapContent);
+}
+
+function getRoadmapMilestoneTitle(milestoneId: string, roadmapContent: string): string | undefined {
+  if (!roadmapContent) return undefined;
+  const titleMatch = roadmapContent.match(new RegExp(`^#\\s+${milestoneId}:\\s*(.+)`, "m"));
+  return titleMatch?.[1]?.trim() || undefined;
+}
+
+function getMilestoneTitle(milestoneId: string, roadmapContent: string): string {
+  const dbMilestone = deps.getMilestone(milestoneId);
+  const dbTitle = stripGsdDisplayPrefix(dbMilestone?.title, milestoneId);
+  return dbTitle ?? getRoadmapMilestoneTitle(milestoneId, roadmapContent) ?? milestoneId;
+}
+
+function buildCommitMessage(request: {
+  completedSlices: CompletedSliceSummary[];
+  milestoneBranch: string;
+  milestoneId: string;
+  milestoneTitle: string;
+}): string {
+  const { completedSlices, milestoneBranch, milestoneId, milestoneTitle } = request;
+  const subject = `feat: ${milestoneTitle}`;
+  const milestoneContext = milestoneTitle === milestoneId
+    ? `Milestone: ${milestoneId}`
+    : `Milestone: ${milestoneId} - ${milestoneTitle}`;
+
+  if (completedSlices.length === 0) {
+    return `${subject}\n\n${milestoneContext}\nGSD-Milestone: ${milestoneId}\nBranch: ${milestoneBranch}`;
+  }
+
+  const sliceLines = completedSlices
+    .map((slice) => `- ${slice.id}: ${slice.title}`)
+    .join("\n");
+  const taskLines = completedSlices
+    .flatMap((slice) => slice.tasks.map((task) => `- ${slice.id}/${task.id}: ${task.title}`))
+    .join("\n");
+  const taskBlock = taskLines ? `\n\nCompleted tasks:\n${taskLines}` : "";
+
+  return `${subject}\n\nCompleted slices:\n${sliceLines}${taskBlock}\n\n${milestoneContext}\nGSD-Milestone: ${milestoneId}\nBranch: ${milestoneBranch}`;
+}
+
+export function buildMilestoneMergeMessage(
+  request: MilestoneMergeMessageRequest,
+): MilestoneMergeMessage {
+  const { milestoneId, milestoneBranch, roadmapContent } = request;
+  const completedSlices = getCompletedSlices(milestoneId, roadmapContent);
+  const milestoneTitle = getMilestoneTitle(milestoneId, roadmapContent);
+  return {
+    commitMessage: buildCommitMessage({
+      completedSlices,
+      milestoneBranch,
+      milestoneId,
+      milestoneTitle,
+    }),
+    milestoneTitle,
+    sliceSummaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
+  };
+}

package/src/resources/extensions/gsd/auto-worktree-merge-pre-teardown.ts

@@ -0,0 +1,93 @@
+// gsd-pi — Milestone merge pre-teardown safety guard.
+//
+// Owns the final data-loss check before deleting a merged milestone worktree:
+// if the milestone worktree still has uncommitted work, abort teardown so the
+// milestone branch remains a recovery ref.
+
+import { existsSync } from "node:fs";
+
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  nativeGetCurrentBranch,
+  nativeWorkingTreeStatus,
+} from "./native-git-bridge.js";
+
+export interface PreTeardownSafetyRequest {
+  milestoneBranch: string;
+  previousCwd: string;
+  worktreeCwd: string;
+}
+
+interface PreTeardownSafetyDeps {
+  chdir: typeof process.chdir;
+  debugLog: typeof debugLog;
+  existsSync: typeof existsSync;
+  nativeGetCurrentBranch: typeof nativeGetCurrentBranch;
+  nativeWorkingTreeStatus: typeof nativeWorkingTreeStatus;
+}
+
+const defaultDeps: PreTeardownSafetyDeps = {
+  chdir: process.chdir.bind(process),
+  debugLog,
+  existsSync,
+  nativeGetCurrentBranch,
+  nativeWorkingTreeStatus,
+};
+
+let deps: PreTeardownSafetyDeps = defaultDeps;
+
+export function _setPreTeardownSafetyDepsForTests(
+  overrides: Partial<PreTeardownSafetyDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetPreTeardownSafetyDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+/**
+ * Abort teardown when the milestone worktree still has uncommitted changes.
+ *
+ * The guard is intentionally scoped to worktree paths that are still on the
+ * milestone branch. In branch-mode or parallel merge paths, `worktreeCwd` can
+ * point at the integration branch; blocking on that dirty state would conflate
+ * unrelated milestones and preserve the wrong recovery ref.
+ */
+export function assertMilestoneWorktreeCleanBeforeTeardown(
+  request: PreTeardownSafetyRequest,
+): void {
+  const { milestoneBranch, previousCwd, worktreeCwd } = request;
+  if (!deps.existsSync(worktreeCwd)) return;
+
+  let preTeardownBranch: string | null = null;
+  try {
+    preTeardownBranch = deps.nativeGetCurrentBranch(worktreeCwd);
+  } catch (err) {
+    deps.debugLog("mergeMilestoneToMain", {
+      phase: "pre-teardown-branch-detect-failed",
+      error: String(err),
+    });
+  }
+
+  if (preTeardownBranch !== milestoneBranch) return;
+
+  try {
+    const dirtyCheck = deps.nativeWorkingTreeStatus(worktreeCwd);
+    if (!dirtyCheck) return;
+
+    deps.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Milestone worktree still has uncommitted changes after squash merge. ` +
+        `Aborting teardown to preserve ${milestoneBranch}. Status:\n${dirtyCheck}`,
+    );
+  } catch (err) {
+    if (err instanceof GSDError) throw err;
+    deps.debugLog("mergeMilestoneToMain", {
+      phase: "pre-teardown-dirty-check-error",
+      error: String(err),
+    });
+  }
+}

package/src/resources/extensions/gsd/auto-worktree-merge-stash.ts

@@ -0,0 +1,213 @@
+// gsd-pi — Pre-merge stash handling for auto-worktree merge closeout.
+//
+// Owns the local-work protection around milestone merge: stash before merge,
+// DB handle cycling for Windows, restoring on merge failures, and post-commit
+// stash-pop conflict recovery.
+
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+import {
+  closeWorkflowDatabase,
+  getWorkflowDatabasePath,
+  openWorkflowDatabasePath,
+} from "./db-workspace.js";
+import {
+  nativeAddPaths,
+  nativeConflictFiles,
+  nativeLsFiles,
+  nativeRmForce,
+} from "./native-git-bridge.js";
+import {
+  gsdJsonlFilesWithConflictMarkers,
+  hasConflictMarkers,
+  popStashByRef,
+  stashAlreadyExistsFilesFromError,
+  stashRefFromError,
+} from "./worktree-git-recovery.js";
+import { logWarning } from "./workflow-logger.js";
+
+export interface PreMergeStash {
+  stash(): void;
+  reopenDbAfterMerge(): void;
+  restoreForMergeFailure(): void;
+  restoreAfterCommit(): void;
+}
+
+export function createPreMergeStash(
+  basePath: string,
+  milestoneId: string,
+  cycleDbHandles: boolean,
+): PreMergeStash {
+  let stashed = false;
+  let marker: string | null = null;
+  const dbPathToReopen = cycleDbHandles ? getWorkflowDatabasePath() : null;
+
+  return {
+    stash(): void {
+      closeDbBeforeStashIfNeeded(cycleDbHandles);
+      try {
+        const status = execFileSync("git", ["status", "--porcelain"], {
+          cwd: basePath,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        }).trim();
+        if (!status) return;
+
+        marker = createStashMarker(milestoneId);
+        execFileSync(
+          "git",
+          ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId} [${marker}]`],
+          { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+        );
+        stashed = true;
+      } catch (err) {
+        // Stash failure is non-fatal — proceed without stash and let the merge
+        // report the dirty tree if it fails.
+        logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+
+    reopenDbAfterMerge(): void {
+      if (!cycleDbHandles || !dbPathToReopen) return;
+      try {
+        openWorkflowDatabasePath(dbPathToReopen);
+      } catch (err) {
+        logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+
+    restoreForMergeFailure(): void {
+      if (!stashed) return;
+      try {
+        popStashByRef(basePath, marker);
+      } catch (err) {
+        logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+
+    restoreAfterCommit(): void {
+      if (!stashed) return;
+      restoreStashAfterCommit(basePath, marker);
+    },
+  };
+}
+
+function closeDbBeforeStashIfNeeded(cycleDbHandles: boolean): void {
+  if (!cycleDbHandles) return;
+  try {
+    closeWorkflowDatabase();
+  } catch (err) {
+    logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function createStashMarker(milestoneId: string): string {
+  return `gsd-pre-merge:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+}
+
+function restoreStashAfterCommit(basePath: string, marker: string | null): void {
+  let stashRefForDrop: string | null = null;
+  try {
+    stashRefForDrop = popStashByRef(basePath, marker);
+  } catch (e) {
+    stashRefForDrop = stashRefFromError(e);
+    logWarning("worktree", `git stash pop failed, attempting conflict resolution: ${(e as Error).message}`);
+    resolveStashPopConflict(basePath, e, stashRefForDrop);
+  }
+}
+
+function resolveStashPopConflict(basePath: string, error: unknown, stashRefForDrop: string | null): void {
+  const uu = nativeConflictFiles(basePath);
+  const gsdUU = uu.filter((f) => f.startsWith(".gsd/"));
+  const nonGsdUU = uu.filter((f) => !f.startsWith(".gsd/"));
+  const stashPopMessage = error instanceof Error ? error.message : String(error);
+  const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+  const gsdContentConflicts: string[] = [];
+  const alreadyExists = stashAlreadyExistsFilesFromError(error);
+
+  if (isUntrackedRestoreFailure) {
+    gsdContentConflicts.push(...gsdJsonlFilesWithConflictMarkers(basePath));
+  }
+
+  const gsdConflictFiles = [...new Set([...gsdUU, ...gsdContentConflicts])];
+  resolveGsdConflictFiles(basePath, gsdConflictFiles);
+
+  if (gsdConflictFiles.length > 0 && nonGsdUU.length === 0) {
+    dropStashIfNoNonGsdConflictsRemain(basePath, stashRefForDrop);
+    return;
+  }
+
+  if (gsdUU.length === 0 && nonGsdUU.length === 0 && alreadyExists.length > 0) {
+    dropRecordedStash(basePath, stashRefForDrop);
+    return;
+  }
+
+  if (nonGsdUU.length > 0) {
+    logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
+      files: nonGsdUU.join(", "),
+    });
+    return;
+  }
+
+  logWarning(
+    "worktree",
+    "git stash pop failed without resolvable conflict files; leaving stash for manual recovery",
+  );
+}
+
+function resolveGsdConflictFiles(basePath: string, conflictFiles: string[]): void {
+  for (const file of conflictFiles) {
+    try {
+      // Accept the committed (HEAD) version of the state file.
+      execFileSync("git", ["checkout", "HEAD", "--", file], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      });
+      nativeAddPaths(basePath, [file]);
+    } catch (err) {
+      // Last resort: remove the conflicted state file.
+      logWarning("worktree", `checkout HEAD failed for ${file}, removing: ${(err as Error).message}`);
+      nativeRmForce(basePath, [file]);
+    }
+  }
+}
+
+function dropStashIfNoNonGsdConflictsRemain(basePath: string, stashRefForDrop: string | null): void {
+  const remainingUnmerged = nativeConflictFiles(basePath);
+  const nonGsdUnmerged = remainingUnmerged.filter((f) => !f.startsWith(".gsd/"));
+  const markerCandidates = Array.from(new Set([
+    ...nonGsdUnmerged,
+    ...nativeLsFiles(basePath, "."),
+  ])).filter((f) => !f.startsWith(".gsd/"));
+  const nonGsdMarkerConflicts = markerCandidates.filter((f) =>
+    hasConflictMarkers(join(basePath, f)),
+  );
+  const hasRemainingNonGsdConflicts = nonGsdUnmerged.length > 0 || nonGsdMarkerConflicts.length > 0;
+  if (hasRemainingNonGsdConflicts) {
+    const files = Array.from(new Set([...nonGsdUnmerged, ...nonGsdMarkerConflicts]));
+    logWarning("reconcile", "Leaving stash because non-.gsd conflicts remain after auto-resolution", {
+      files: files.join(", "),
+    });
+    return;
+  }
+
+  dropRecordedStash(basePath, stashRefForDrop);
+}
+
+function dropRecordedStash(basePath: string, stashRefForDrop: string | null): void {
+  if (!stashRefForDrop) {
+    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
+    return;
+  }
+  try {
+    execFileSync("git", ["stash", "drop", stashRefForDrop], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}