@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

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,12 +12,12 @@
  * 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
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
@@ -24,6 +25,8 @@ 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 { MILESTONE_ID_RE } from "./milestone-ids.js";
+import { canonicalWorktreesDir, worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 function deleteBranchIfPresent(basePath, branch, warningPrefix) {
     try {
         if (!nativeBranchExists(basePath, branch))
@@ -81,30 +84,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 {
@@ -121,7 +133,99 @@ function isRegisteredGitWorktreeAtPath(basePath, wtPath) {
         return false;
     }
 }
-function removeStaleWorktreeDirectory(wtPath, name) {
+/** True when `wtPath` has a git worktree checkout marker (`.git` file with gitdir pointer). */
+export function isLiveGitWorktreeCheckout(wtPath) {
+    const gitPath = join(wtPath, ".git");
+    if (!existsSync(gitPath))
+        return false;
+    try {
+        return lstatSync(gitPath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a worktree directory should count toward idle milestone residue detection. */
+export function isMilestoneWorktreeResidueCandidate(basePath, wtPath) {
+    return isRegisteredGitWorktreeAtPath(basePath, wtPath) || isLiveGitWorktreeCheckout(wtPath);
+}
+const EPHEMERAL_GHOST_WORKTREE_ENTRIES = new Set([".bg-shell", ".DS_Store"]);
+function isEphemeralGhostWorktreeContents(dirPath) {
+    let entries;
+    try {
+        entries = readdirSync(dirPath);
+    }
+    catch {
+        return false;
+    }
+    if (entries.length === 0)
+        return true;
+    for (const entry of entries) {
+        if (EPHEMERAL_GHOST_WORKTREE_ENTRIES.has(entry))
+            continue;
+        if (entry === ".gsd") {
+            try {
+                const gsdEntries = readdirSync(join(dirPath, ".gsd"));
+                if (gsdEntries.length <= 1 && gsdEntries.every((e) => e === "doctor-history.jsonl")) {
+                    continue;
+                }
+            }
+            catch {
+                return false;
+            }
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+/**
+ * Remove milestone worktree directories that are not registered with git and
+ * contain only ephemeral runtime content (e.g. bg-shell manifests recreated
+ * after teardown). Returns removed directory paths.
+ */
+export function pruneEphemeralGhostWorktreeDirectories(basePath) {
+    const removed = [];
+    for (const container of allWorktreesDirs(basePath)) {
+        if (!existsSync(container))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(container);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!MILESTONE_ID_RE.test(entry))
+                continue;
+            const fullPath = join(container, entry);
+            try {
+                if (!statSync(fullPath).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (isRegisteredGitWorktreeAtPath(basePath, fullPath))
+                continue;
+            if (isLiveGitWorktreeCheckout(fullPath))
+                continue;
+            if (!isEphemeralGhostWorktreeContents(fullPath))
+                continue;
+            try {
+                rmSync(fullPath, { recursive: true, force: true });
+                logWarning("reconcile", `Removed ephemeral ghost worktree directory (not registered with git): ${fullPath}`, { worktree: entry });
+                removed.push(fullPath);
+            }
+            catch (err) {
+                logWarning("worktree", `ghost worktree directory removal failed for ${fullPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return removed;
+}
+export function removeStaleWorktreeDirectory(wtPath, name) {
     logWarning("reconcile", `Removing stale worktree directory (not registered with git): ${wtPath}`, { worktree: name });
     try {
         rmSync(wtPath, { recursive: true, force: true });
@@ -200,11 +304,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 +328,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 +417,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 +428,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;
@@ -512,7 +621,13 @@ export function removeWorktree(basePath, name, opts = {}) {
     // inside .gsd/worktrees/ — a symlink inside the directory could point out.
     const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
     // If we're inside the worktree, move out first — git can't remove an in-use directory
-    const cwd = process.cwd();
+    let cwd;
+    try {
+        cwd = process.cwd();
+    }
+    catch {
+        cwd = basePath;
+    }
     const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
     if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
         process.chdir(basePath);
@@ -645,6 +760,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/",
@@ -705,10 +821,10 @@ function parseDiffNameStatus(entries) {
  * Diff the .gsd/ directory between the worktree branch and main branch.
  * Returns a summary of added, modified, and removed GSD artifacts.
  */
-export function diffWorktreeGSD(basePath, name) {
+export function diffWorktreeGSD(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch, ".gsd/", true);
     return parseDiffNameStatus(entries);
 }
@@ -718,10 +834,10 @@ export function diffWorktreeGSD(basePath, name) {
  * on main when the merge is applied. If both branches have identical
  * content, this correctly returns an empty diff.
  */
-export function diffWorktreeAll(basePath, name, branchOverride) {
+export function diffWorktreeAll(basePath, name, branchOverride, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = branchOverride ?? worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
     return parseDiffNameStatus(entries);
 }
@@ -729,10 +845,10 @@ export function diffWorktreeAll(basePath, name, branchOverride) {
  * Get per-file line addition/deletion stats for what will change on main.
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
-export function diffWorktreeNumstat(basePath, name, branchOverride) {
+export function diffWorktreeNumstat(basePath, name, branchOverride, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = branchOverride ?? worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
     const stats = [];
     for (const entry of rawStats) {
@@ -746,29 +862,29 @@ export function diffWorktreeNumstat(basePath, name, branchOverride) {
  * Get the full diff content for .gsd/ between the worktree branch and main.
  * Returns the raw unified diff for LLM consumption.
  */
-export function getWorktreeGSDDiff(basePath, name) {
+export function getWorktreeGSDDiff(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     return nativeDiffContent(basePath, mainBranch, branch, ".gsd/", undefined, true);
 }
 /**
  * Get the full diff content for non-.gsd/ files between the worktree branch and main.
  * Returns the raw unified diff for LLM consumption.
  */
-export function getWorktreeCodeDiff(basePath, name) {
+export function getWorktreeCodeDiff(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     return nativeDiffContent(basePath, mainBranch, branch, undefined, ".gsd/", true);
 }
 /**
  * Get commit log for the worktree branch since it diverged from main.
  */
-export function getWorktreeLog(basePath, name) {
+export function getWorktreeLog(basePath, name, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const entries = nativeLogOneline(basePath, mainBranch, branch);
     return entries.map(e => `${e.sha} ${e.message}`).join("\n");
 }
@@ -777,10 +893,10 @@ export function getWorktreeLog(basePath, name) {
  * Must be called from the main working tree (not the worktree itself).
  * Returns the merge commit message.
  */
-export function mergeWorktreeToMain(basePath, name, commitMessage, branchOverride) {
+export function mergeWorktreeToMain(basePath, name, commitMessage, branchOverride, mainBranchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = branchOverride ?? worktreeBranchName(name);
-    const mainBranch = nativeDetectMainBranch(basePath);
+    const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
     const current = nativeGetCurrentBranch(basePath);
     if (current !== mainBranch) {
         throw new GSDError(GSD_GIT_ERROR, `Must be on ${mainBranch} to merge. Currently on ${current}.`);

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) {

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

@@ -14,10 +14,16 @@ export function normalizeWorktreePathForCompare(path) {
     return process.platform === "win32" ? (trimmed || "/").toLowerCase() : (trimmed || "/");
 }
 /**
- * Find the GSD worktree segment in both direct project layout and the
- * symlink-resolved external-state layout used by ~/.gsd/projects/<hash>.
+ * Find the GSD worktree segment in the canonical layout (.gsd-worktrees/),
+ * the legacy direct layout (.gsd/worktrees/), and the symlink-resolved
+ * external-state layout used by ~/.gsd/projects/<hash>.
  */
 export function findWorktreeSegment(normalizedPath) {
+    const canonicalMarker = "/.gsd-worktrees/";
+    const canonicalIdx = normalizedPath.indexOf(canonicalMarker);
+    if (canonicalIdx !== -1) {
+        return { gsdIdx: canonicalIdx, afterWorktrees: canonicalIdx + canonicalMarker.length };
+    }
     const directMarker = "/.gsd/worktrees/";
     const directIdx = normalizedPath.indexOf(directMarker);
     if (directIdx !== -1) {
@@ -51,6 +57,17 @@ export function findWorktreeSegment(normalizedPath) {
 export function isGsdWorktreePath(path) {
     return findWorktreeSegment(path.replaceAll("\\", "/")) !== null;
 }
+/**
+ * Project-root prefix of a GSD worktree path, or null when the path is not
+ * inside a recognized worktree layout. Pure string split — no env handling,
+ * HOME guard, or filesystem fallbacks (resolveWorktreeProjectRoot adds
+ * those). Separator normalization is 1:1 on characters, so the prefix is
+ * sliced from the ORIGINAL string and keeps its separators.
+ */
+export function projectRootFromWorktreePath(path) {
+    const segment = findWorktreeSegment(path.replaceAll("\\", "/"));
+    return segment ? path.slice(0, segment.gsdIdx) : null;
+}
 /**
  * When a milestone worktree lives under the external-state layout
  * (`<gsdHome>/projects/<hash>/worktrees/<MID>/`, or the `GSD_STATE_DIR`
@@ -60,7 +77,9 @@ export function isGsdWorktreePath(path) {
  */
 export function resolveExternalStateProjectGsdFromWorktreePath(projectPath) {
     const normalized = resolve(projectPath).replaceAll("\\", "/");
-    // Direct layout — parent state is resolved via repoIdentity(git root).
+    // Canonical/direct layouts — parent state is resolved via repoIdentity(git root).
+    if (normalized.includes("/.gsd-worktrees/"))
+        return null;
     if (normalized.includes("/.gsd/worktrees/") && !normalized.includes("/.gsd/projects/")) {
         return null;
     }
@@ -117,12 +136,15 @@ function resolveProjectRootFromPath(path) {
     if (!segment) {
         return resolveNearestBootstrappedGsdRoot(path) ?? resolveGitWorkingTreeRoot(path) ?? path;
     }
+    // Slice at the first `.gsd` boundary, but never past the worktree segment:
+    // in the canonical layout (`<root>/.gsd-worktrees/<MID>/.gsd/...`) the first
+    // `/.gsd/` occurrence is the worktree-local projection dir, not the project
+    // root's state dir.
     const sepChar = path.includes("\\") ? "\\" : "/";
     const gsdMarker = `${sepChar}.gsd${sepChar}`;
     const markerIdx = path.indexOf(gsdMarker);
-    const candidate = markerIdx !== -1
-        ? path.slice(0, markerIdx)
-        : path.slice(0, segment.gsdIdx);
+    const sliceIdx = markerIdx !== -1 ? Math.min(markerIdx, segment.gsdIdx) : segment.gsdIdx;
+    const candidate = path.slice(0, sliceIdx);
     const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
     const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));
     if (candidateGsdPath === gsdHomeNorm || candidateGsdPath.startsWith(`${gsdHomeNorm}/`)) {