@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/dist/resources/extensions/gsd/web-app-uat.js

@@ -0,0 +1,117 @@
+// Project/App: gsd-pi
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution } from "../browser-tools/engine/selection.js";
+import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES } from "./uat-policy.js";
+export { detectWebApp };
+function readPackageJson(projectRoot) {
+    const packageJsonPath = resolve(projectRoot, "package.json");
+    if (!existsSync(packageJsonPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasPlaywrightTestDependency(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    if (!pkg)
+        return false;
+    const names = [
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+    ];
+    return names.some((name) => name === "playwright" || name === "@playwright/test");
+}
+export function findPlaywrightTestScript(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    if (!pkg?.scripts)
+        return null;
+    for (const [name, value] of Object.entries(pkg.scripts)) {
+        if (typeof value !== "string")
+            continue;
+        if (/\bplaywright\s+test\b/.test(value)) {
+            return `npm run ${name}`;
+        }
+    }
+    return null;
+}
+function describeBrowserToolBacking(engineResolution) {
+    switch (engineResolution.engine) {
+        case "gsd-browser":
+            return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+        case "legacy":
+            return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+        case "off":
+            return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+    }
+}
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE = [
+    {
+        mode: "browser-executable",
+        bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+    },
+    {
+        mode: "runtime-executable",
+        bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+    },
+    {
+        mode: "mixed",
+        bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    },
+];
+/**
+ * Markdown block injected into plan/complete-slice prompts when the project
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
+ */
+export function buildWebAppUatGuidanceBlock(projectRoot, engineResolution) {
+    if (!detectWebApp(projectRoot))
+        return null;
+    const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+    const browserToolsAvailable = resolvedEngine.engine !== "off";
+    const playwrightScript = findPlaywrightTestScript(projectRoot);
+    const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
+    const lines = [
+        "### Web App UAT (detected)",
+        "",
+        describeBrowserToolBacking(resolvedEngine),
+        "",
+        "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
+        ...UAT_MODE_GUIDANCE
+            .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+            .map(({ bullet }) => bullet),
+        "",
+        "**Planning / closeout rules:**",
+        "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
+        "- Slice Verification and UAT test cases must not say \"open in browser\" under `artifact-driven` — complete-slice rejects that",
+        "- Milestone `Verification Classes` → UAT row must describe browser-observable acceptance, not \"manual spot check\" alone",
+    ];
+    if (hasPlaywright) {
+        lines.push("", "**Playwright:** dependency detected.");
+        if (playwrightScript) {
+            lines.push(`- Prefer slice verification and runtime-executable UAT referencing \`${playwrightScript}\` or a focused \`npx playwright test <spec>\` command`);
+        }
+        else {
+            lines.push("- Prefer runtime-executable UAT with `npx playwright test` (or a focused spec path) when UI behavior is covered by specs");
+        }
+        lines.push("- Name concrete spec paths in slice Verification (for example `e2e/smoke.spec.ts`)");
+    }
+    else {
+        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command");
+        if (browserToolsAvailable) {
+            lines.push("- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -1,8 +1,12 @@
 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 };
 /** Session cwd may be a milestone worktree; MCP config and server discovery use the project root. */
 export function resolveWorkflowMcpProjectRoot(sessionCwd) {
     let resolved;
@@ -19,72 +23,9 @@ export function resolveWorkflowMcpProjectRoot(sessionCwd) {
     }
     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) {
-    return MCP_WORKFLOW_TOOL_SURFACE.has(toolName);
+    return isWorkflowToolSurfaceName(toolName);
 }
 function parseLookupOutput(output) {
     return output
@@ -239,8 +180,12 @@ function getBundledWorkflowWriteGateModulePath() {
 }
 function getResolveTsHookPath() {
     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))),
@@ -355,45 +300,13 @@ export function getRequiredWorkflowToolsForGuidedUnit(unitType) {
 export function getRequiredWorkflowToolsForAutoUnit(unitType) {
     return getRequiredWorkflowToolsForUnit(unitType);
 }
-export function usesWorkflowMcpTransport(authMode, baseUrl) {
-    return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
-}
-function hasAskUserQuestionsTool(activeTools) {
-    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, activeTools) {
     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 = process.env) {
-    const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
-    return value === "1" || value === "true";
-}
-export function supportsStructuredQuestions(activeTools, options = {}) {
-    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, requiredTools, options = {}) {
     if (!provider || requiredTools.length === 0)
         return null;
@@ -410,12 +323,12 @@ export function getWorkflowTransportSupportError(provider, requiredTools, option
     }
     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/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -2,7 +2,8 @@ import { join } from "node:path";
 import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
-import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, openDatabase, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
+import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, 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";
@@ -415,7 +416,7 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
     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
     try {
@@ -548,7 +549,7 @@ pick) {
     const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
     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/dist/resources/extensions/gsd/workflow-tool-surface.js

@@ -0,0 +1,46 @@
+// 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 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 = WORKFLOW_TOOL_CONTRACTS.flatMap((tool) => tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })));
+export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL = Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
+export 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",
+];
+export const WORKFLOW_TOOL_SURFACE_NAMES = [
+    ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
+    ...DB_WORKFLOW_TOOL_NAMES,
+];
+const WORKFLOW_TOOL_SURFACE_NAME_SET = new Set(WORKFLOW_TOOL_SURFACE_NAMES);
+export { stripMcpToolPrefix } from "./mcp-tool-name.js";
+export function canonicalWorkflowSurfaceToolName(toolName) {
+    const baseName = stripMcpToolPrefix(toolName);
+    return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+}
+export function isWorkflowSurfaceAliasTool(toolName) {
+    const baseName = stripMcpToolPrefix(toolName);
+    return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] !== undefined;
+}
+export function isWorkflowToolSurfaceName(toolName) {
+    return WORKFLOW_TOOL_SURFACE_NAME_SET.has(stripMcpToolPrefix(toolName));
+}
+export function aliasesForWorkflowTool(canonicalName) {
+    return WORKFLOW_TOOL_CONTRACTS.find((tool) => tool.canonicalName === canonicalName)?.aliases ?? [];
+}

package/dist/resources/extensions/gsd/workspace-git-guard.js

@@ -12,6 +12,8 @@ export function isWorkspaceGitAllowedCommand(trimmed) {
     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") {

package/dist/resources/extensions/gsd/worktree-git-recovery.js

@@ -0,0 +1,293 @@
+// 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 untracked files
+ *     (force-checkout + targeted stash drop; #645 broadened it beyond `.gsd/`,
+ *     guarded by "no non-.gsd unmerged entries remain").
+ *   - `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, stashMarker) {
+    let popArg = 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.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) {
+    if (!err || typeof err !== "object")
+        return null;
+    const stashRef = err.stashRef;
+    return typeof stashRef === "string" && stashRef.length > 0 ? stashRef : null;
+}
+export function stashAlreadyExistsFilesFromError(err) {
+    if (!err || typeof err !== "object")
+        return [];
+    const stderr = err.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();
+    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) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return content.includes("<<<<<<<") && content.includes("=======") && content.includes(">>>>>>>");
+    }
+    catch {
+        return false;
+    }
+}
+export function gsdJsonlFilesWithConflictMarkers(basePath) {
+    return nativeLsFiles(basePath, ".gsd/*.jsonl").filter((f) => hasConflictMarkers(join(basePath, f)));
+}
+export function removeMergeStateFiles(basePath, contextLabel) {
+    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) {
+    // 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, branch, reason) {
+    let stashMarker = 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.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 isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+            const stashRefForDrop = stashRefFromError(popErr);
+            const allConflictFiles = nativeConflictFiles(basePath);
+            const nonGsdUnmerged = allConflictFiles.filter((f) => !f.startsWith(".gsd/"));
+            const gsdUnmerged = allConflictFiles.filter((f) => f.startsWith(".gsd/"));
+            const gsdContentConflicts = isUntrackedRestoreFailure
+                ? gsdJsonlFilesWithConflictMarkers(basePath)
+                : [];
+            // Resolve ALL untracked-collision files by accepting HEAD — files in
+            // alreadyExists were untracked on the source branch by definition of the
+            // "already exists, no checkout" failure, so target HEAD is authoritative.
+            // gsdUnmerged: .gsd/ index conflicts left by the partial stash pop are
+            // also resolved via HEAD — .gsd/ runtime state is always authoritative
+            // on the target branch, so accepting HEAD is safe here too.
+            const resolvable = [...new Set([...alreadyExists, ...gsdContentConflicts, ...gsdUnmerged])];
+            if (isUntrackedRestoreFailure &&
+                resolvable.length > 0 &&
+                nonGsdUnmerged.length === 0) {
+                for (const f of resolvable) {
+                    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.stashRef = stashRefForDrop;
+            throw wrapped;
+        }
+    }
+}