@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.fb12b103

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

@@ -1,8 +1,10 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// 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");
@@ -39,24 +41,56 @@ export function findPlaywrightTestScript(projectRoot) {
     }
     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.
+ * 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) {
+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)",
         "",
-        "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+        describeBrowserToolBacking(resolvedEngine),
         "",
         "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
-        "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
-        "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
-        "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+        ...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`)",
@@ -74,7 +108,10 @@ export function buildWebAppUatGuidanceBlock(projectRoot) {
         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", "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        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-tool-surface.js

@@ -8,7 +8,7 @@ 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]));
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
     "gsd_cancel",
     "gsd_captures",
     "ask_user_questions",

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;
+        }
+    }
+}

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

@@ -327,7 +327,15 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
     // 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") {
             try {

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

@@ -3,7 +3,8 @@
 /**
  * GSD Worktree Manager
  *
- * Creates and manages git worktrees under .gsd/worktrees/<name>/.
+ * Creates and manages git worktrees under .gsd-worktrees/<name>/ (canonical;
+ * legacy .gsd/worktrees/<name>/ stays recognized — see worktree-placement.ts).
  * Each worktree gets its own branch (worktree/<name>) and a full
  * working copy of the project, enabling parallel work streams.
  *
@@ -11,7 +12,7 @@
  * the main branch, then dispatches an LLM-guided merge flow.
  *
  * Flow:
- *   1. create()  — git worktree add .gsd/worktrees/<name> -b worktree/<name>
+ *   1. create()  — git worktree add .gsd-worktrees/<name> -b worktree/<name>
  *   2. user works in the worktree (new plans, milestones, etc.)
  *   3. merge()   — LLM-guided reconciliation of .gsd/ artifacts back to main
  *   4. remove()  — git worktree remove + branch cleanup
@@ -24,6 +25,7 @@ import { logWarning } from "./workflow-logger.js";
 import { nativeBranchList, nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+import { canonicalWorktreesDir, worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 function deleteBranchIfPresent(basePath, branch, warningPrefix) {
     try {
         if (!nativeBranchExists(basePath, branch))
@@ -81,30 +83,39 @@ export function resolveGitDir(basePath) {
     }
     return gitPath;
 }
+/** Canonical container for new worktrees. For scans that must also see legacy
+ *  worktrees, use allWorktreesDirs(). */
 export function worktreesDir(basePath) {
-    return join(resolveWorktreeProjectRoot(basePath), ".gsd", "worktrees");
+    return canonicalWorktreesDir(resolveWorktreeProjectRoot(basePath));
 }
+/** Every container a GSD worktree may live in (canonical + legacy), canonical first. */
+export function allWorktreesDirs(basePath) {
+    return worktreesDirs(resolveWorktreeProjectRoot(basePath));
+}
+/** Path for worktree `name` — an existing legacy worktree keeps its location. */
 export function worktreePath(basePath, name) {
-    return join(worktreesDir(basePath), name);
+    return worktreePathFor(resolveWorktreeProjectRoot(basePath), name);
 }
 export function worktreeBranchName(name) {
     return `worktree/${name}`;
 }
 /**
- * Validate that a path is inside the .gsd/worktrees/ directory.
- * Resolves symlinks and normalizes ".." traversals before comparison
- * so that a symlink-resolved or crafted path cannot escape containment.
+ * Validate that a path is inside a GSD worktrees container (canonical
+ * .gsd-worktrees/ or legacy .gsd/worktrees/). Resolves symlinks and
+ * normalizes ".." traversals before comparison so that a symlink-resolved
+ * or crafted path cannot escape containment.
  *
  * Used as a safety gate before any destructive operation (rmSync,
  * nativeWorktreeRemove --force) to prevent #2365-style data loss.
  */
 export function isInsideWorktreesDir(basePath, targetPath) {
-    const wtDirPath = worktreesDir(basePath);
-    const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
     const resolved = existsSync(targetPath) ? realpathSync(targetPath) : resolve(targetPath);
-    // The resolved path must start with the worktrees dir followed by a separator,
-    // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
-    return resolved === wtDir || resolved.startsWith(wtDir + sep);
+    return allWorktreesDirs(basePath).some((wtDirPath) => {
+        const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
+        // The resolved path must start with the worktrees dir followed by a separator,
+        // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
+        return resolved === wtDir || resolved.startsWith(wtDir + sep);
+    });
 }
 function isRegisteredGitWorktreeAtPath(basePath, wtPath) {
     try {
@@ -200,11 +211,11 @@ export function buildManualValidationGuidance(basePath, milestoneId, opts = {})
     if (!milestoneId)
         return null;
     const validationRoot = resolveCanonicalMilestoneRoot(basePath, milestoneId);
-    const inWorktree = validationRoot.includes(`${sep}.gsd${sep}worktrees${sep}`);
+    const inWorktree = isGsdWorktreePath(validationRoot);
     const lines = [`Validate the work here: ${validationRoot}`];
     if (inWorktree) {
-        lines.push("This milestone runs in a git worktree, so the code lives under the hidden " +
-            `\`.gsd/worktrees/\` path. Open it with: cd "${validationRoot}"`);
+        lines.push("This milestone runs in a git worktree, so the code lives under the " +
+            `GSD worktrees directory. Open it with: cd "${validationRoot}"`);
     }
     if (opts.uatPath) {
         lines.push(`Follow the UAT checklist at: ${opts.uatPath}`);
@@ -224,21 +235,29 @@ export function createWorktree(basePath, name, opts = {}) {
     if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
         throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
     }
-    const wtPath = worktreePath(basePath, name);
+    const existingPath = worktreePath(basePath, name);
     const branch = opts.branch ?? worktreeBranchName(name);
-    if (existsSync(wtPath)) {
+    if (existsSync(existingPath)) {
         // A valid git worktree is registered in `git worktree list` and has a .git
         // *file* with a gitdir: pointer. Leftover directories (no .git, a standalone
         // .git directory from accidental `git init`, or an orphan pointer) block
         // creation unless removed.
-        if (isRegisteredGitWorktreeAtPath(basePath, wtPath)) {
-            throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${wtPath}`);
+        if (isRegisteredGitWorktreeAtPath(basePath, existingPath)) {
+            throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${existingPath}`);
         }
-        removeStaleWorktreeDirectory(wtPath, name);
+        removeStaleWorktreeDirectory(existingPath, name);
     }
-    // Ensure the .gsd/worktrees/ directory exists
+    // New worktrees always land in the canonical container, even when a stale
+    // legacy directory was just cleaned up.
     const wtDir = worktreesDir(basePath);
+    const wtPath = join(wtDir, name);
     mkdirSync(wtDir, { recursive: true });
+    // When existingPath resolved to a legacy location, the canonical target may
+    // still hold a stale directory from a prior aborted creation (no .git marker).
+    // Remove it so git worktree add does not fail with "path already exists".
+    if (existingPath !== wtPath && existsSync(wtPath) && !isRegisteredGitWorktreeAtPath(basePath, wtPath)) {
+        removeStaleWorktreeDirectory(wtPath, name);
+    }
     // Prune any stale worktree entries from a previous removal
     nativeWorktreePrune(basePath);
     // Use the explicit start point (e.g. integration branch) if provided,
@@ -305,7 +324,8 @@ export function createWorktree(basePath, name, opts = {}) {
 }
 /**
  * List all GSD-managed worktrees.
- * Uses native worktree list and filters to those under .gsd/worktrees/.
+ * Uses native worktree list and filters to those under a GSD worktrees
+ * container (canonical .gsd-worktrees/ or legacy .gsd/worktrees/).
  */
 export function listWorktrees(basePath) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
@@ -315,12 +335,8 @@ export function listWorktrees(basePath) {
     }
     const seenRoots = new Set();
     const worktreeRoots = baseVariants
-        .map(baseVariant => {
-        const path = join(baseVariant, ".gsd", "worktrees");
-        return {
-            normalized: normalizePathForComparison(path),
-        };
-    })
+        .flatMap(baseVariant => worktreesDirs(baseVariant))
+        .map(path => ({ normalized: normalizePathForComparison(path) }))
         .filter(root => {
         if (seenRoots.has(root.normalized))
             return false;
@@ -645,6 +661,7 @@ export function removeWorktree(basePath, name, opts = {}) {
  * This module uses a split representation (paths/exact/prefixes) for efficient matching.
  */
 const SKIP_PATHS = [
+    ".gsd-worktrees/",
     ".gsd/worktrees/",
     ".gsd/runtime/",
     ".gsd/activity/",

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

@@ -0,0 +1,59 @@
+/**
+ * Worktree Placement module — owns WHERE GSD worktrees physically live.
+ *
+ * Canonical placement: `<projectRoot>/.gsd-worktrees/<name>` — a real
+ * directory that never crosses the `.gsd` symlink managed by repo-identity.
+ * Under the external-state layout (`.gsd → ~/.gsd/projects/<hash>/`), the
+ * legacy `.gsd/worktrees/` location materialised worktrees inside the user's
+ * home directory behind an opaque hash path; the canonical sibling keeps the
+ * working copy at the project root regardless of where `.gsd` state lives.
+ *
+ * Legacy placement (`<projectRoot>/.gsd/worktrees/<name>`, possibly resolving
+ * through the symlink to `~/.gsd/projects/<hash>/worktrees/<name>`) stays
+ * recognized so in-flight milestones keep working across upgrades:
+ *   - creation always uses the canonical location;
+ *   - resolution prefers an existing legacy worktree for the same name;
+ *   - containment checks accept membership in either location.
+ *
+ * Path → project identification lives in worktree-root.ts; this module owns
+ * only the forward direction (project + name → physical path).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/** Directory name of the canonical worktrees container at the project root. */
+export const CANONICAL_WORKTREES_DIRNAME = ".gsd-worktrees";
+/** Canonical container for newly created worktrees. Never crosses the `.gsd` symlink. */
+export function canonicalWorktreesDir(projectRoot) {
+    return join(projectRoot, CANONICAL_WORKTREES_DIRNAME);
+}
+/** Legacy container (`.gsd/worktrees/`) — may resolve through the external-state symlink. */
+export function legacyWorktreesDir(projectRoot) {
+    return join(projectRoot, ".gsd", "worktrees");
+}
+/**
+ * All containers a GSD worktree may live in, canonical first.
+ * Use for listing, scanning, and containment checks.
+ */
+export function worktreesDirs(projectRoot) {
+    return [canonicalWorktreesDir(projectRoot), legacyWorktreesDir(projectRoot)];
+}
+/**
+ * Physical path for the worktree `name` under `projectRoot`.
+ *
+ * Canonical wins only when it has a `.git` marker (i.e. is a live worktree).
+ * A bare directory with no `.git` — a stale leftover from an aborted create
+ * or a partial cleanup — does not shadow an existing legacy worktree, so the
+ * legacy path is tried next. The legacy check remains a plain existsSync;
+ * callers that need a *registered* worktree validate the `.git` marker
+ * themselves (resolveCanonicalMilestoneRoot, getAutoWorktreePath).
+ * Falls back to canonical for new-worktree creation when neither path exists.
+ */
+export function worktreePathFor(projectRoot, name) {
+    const canonical = join(canonicalWorktreesDir(projectRoot), name);
+    if (existsSync(canonical) && existsSync(join(canonical, ".git")))
+        return canonical;
+    const legacy = join(legacyWorktreesDir(projectRoot), name);
+    if (existsSync(legacy))
+        return legacy;
+    return canonical;
+}

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

@@ -8,19 +8,23 @@
 import { readdirSync } from "node:fs";
 import { enterAutoWorktree, getAutoWorktreePath } from "./auto-worktree.js";
 import { getIsolationMode } from "./preferences.js";
-import { worktreesDir } from "./worktree-manager.js";
+import { allWorktreesDirs } from "./worktree-manager.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 /**
- * Enumerate the live (valid git) auto-worktrees under <projectRoot>/.gsd/worktrees/.
+ * Enumerate the live (valid git) auto-worktrees in the project's worktree
+ * containers (canonical .gsd-worktrees/ and legacy .gsd/worktrees/).
  * Reuses getAutoWorktreePath's validation so stray directories are ignored.
  */
 function liveMilestoneWorktrees(projectRoot) {
-    let names;
-    try {
-        names = readdirSync(worktreesDir(projectRoot));
-    }
-    catch {
-        return [];
+    const names = new Set();
+    for (const dir of allWorktreesDirs(projectRoot)) {
+        try {
+            for (const name of readdirSync(dir))
+                names.add(name);
+        }
+        catch {
+            // container absent — skip
+        }
     }
     const live = [];
     for (const id of names) {