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

package/src/resources/extensions/gsd/visualizer-views.ts

@@ -935,13 +935,20 @@ export function renderKnowledgeView(
 ): string[] {
   const lines: string[] = [];
   const knowledge = data.knowledge;
+  const memories = data.memories;
 
-  if (!knowledge.exists) {
+  if (!knowledge.exists && memories.entries.length === 0) {
     lines.push(th.fg("dim", "No KNOWLEDGE.md found"));
     return lines;
   }
 
-  if (knowledge.rules.length === 0 && knowledge.patterns.length === 0 && knowledge.lessons.length === 0) {
+  if (
+    knowledge.exists &&
+    knowledge.rules.length === 0 &&
+    knowledge.patterns.length === 0 &&
+    knowledge.lessons.length === 0 &&
+    memories.entries.length === 0
+  ) {
     lines.push(th.fg("dim", "KNOWLEDGE.md exists but is empty"));
     return lines;
   }
@@ -985,6 +992,24 @@ export function renderKnowledgeView(
     lines.push("");
   }
 
+  if (memories.entries.length > 0) {
+    const countLabel = memories.totalCount > memories.entries.length
+      ? `${memories.entries.length}/${memories.totalCount}`
+      : `${memories.totalCount}`;
+    lines.push(th.fg("accent", th.bold(`Memories (${countLabel})`)));
+    lines.push("");
+    for (const memory of memories.entries) {
+      const scope = memory.scope && memory.scope !== "project" ? ` ${th.fg("dim", `[${memory.scope}]`)}` : "";
+      const tags = memory.tags.length > 0 ? ` ${th.fg("dim", `#${memory.tags.join(" #")}`)}` : "";
+      lines.push(truncateToWidth(
+        `  ${th.fg("accent", memory.id)}  (${memory.category}, ${memory.confidence.toFixed(2)}, hits ${memory.hitCount})${scope}${tags}`,
+        width,
+      ));
+      lines.push(truncateToWidth(`    ${memory.content}`, width));
+    }
+    lines.push("");
+  }
+
   return lines;
 }
 

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

@@ -109,6 +109,11 @@ export function setStderrLoggingEnabled(enabled: boolean): boolean {
   return previous;
 }
 
+/** Whether GSD extension diagnostics may write directly to process.stderr. */
+export function isGsdExtensionStderrEnabled(): boolean {
+  return _stderrEnabled;
+}
+
 // ─── Public API ─────────────────────────────────────────────────────────
 
 /**

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

@@ -85,6 +85,8 @@ function lookupCommand(command: string, platform: NodeJS.Platform = process.plat
   }
 }
 
+const gsdPiRepoRootCache = new Map<string, string | null>();
+
 function findGsdPiRepoRoot(startPath: string): string | null {
   let current: string;
   try {
@@ -93,15 +95,24 @@ function findGsdPiRepoRoot(startPath: string): string | null {
     current = resolve(startPath);
   }
 
+  const cacheKey = current;
+  if (gsdPiRepoRootCache.has(cacheKey)) {
+    return gsdPiRepoRootCache.get(cacheKey) ?? null;
+  }
+
   while (true) {
     const distCli = resolve(current, "packages", "mcp-server", "dist", "cli.js");
-    if (existsSync(distCli)) return current;
+    if (existsSync(distCli)) {
+      gsdPiRepoRootCache.set(cacheKey, current);
+      return current;
+    }
 
     const parent = dirname(current);
     if (parent === current) break;
     current = parent;
   }
 
+  gsdPiRepoRootCache.set(cacheKey, null);
   return null;
 }
 

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

@@ -26,7 +26,7 @@ import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot } from "./paths.js";
+import { gsdRoot, resolveSliceFile, resolveMilestonePath, resolveSlicePath, gsdProjectionRoot } from "./paths.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
@@ -328,7 +328,23 @@ export function renderSummaryProjection(basePath: string, milestoneId: string, s
 
   const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
   const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
-  const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks");
+
+  // Layout-aware: avoid creating a milestones/ directory as a side effect for
+  // flat-phase projects. If milestonesDir() sees a freshly-created milestones/
+  // dir it treats the project as legacy, breaking all subsequent path resolution.
+  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+  const phaseDir = resolveMilestonePath(basePath, milestoneId);
+  let dir: string;
+  if (slicePath && phaseDir && slicePath !== phaseDir) {
+    // Legacy layout: slice has its own slices/SID/ subdir → tasks/ subdir
+    dir = join(slicePath, "tasks");
+  } else if (phaseDir) {
+    // Flat-phase: task summaries go in the phase dir (no tasks/ subdir needed)
+    dir = phaseDir;
+  } else {
+    // Fallback: legacy hardcoded path (milestone dir not on disk yet)
+    dir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+  }
   mkdirSync(dir, { recursive: true });
   atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
 }
@@ -509,7 +525,9 @@ export async function regenerateIfMissing(
 
   switch (fileType) {
     case "PLAN":
-      filePath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, `${sliceId}-PLAN.md`);
+      // Use resolveSliceFile so both flat-phase and legacy layouts are detected.
+      // Falls back to "" (non-existent) when the file hasn't been rendered yet.
+      filePath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? "";
       break;
     case "ROADMAP":
       filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
@@ -562,7 +580,9 @@ export async function regenerateIfMissing(
     switch (fileType) {
       case "PLAN":
         await renderPlanFromDb(basePath, milestoneId, sliceId);
-        return existsSync(filePath);
+        // Re-resolve after render: the rendered file may be at a different path
+        // from the pre-check (flat-phase vs legacy). resolveSliceFile finds it.
+        return !!(resolveSliceFile(basePath, milestoneId, sliceId, "PLAN"));
       case "ROADMAP":
         await renderRoadmapFromDb(basePath, milestoneId);
         return existsSync(filePath);

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

@@ -570,11 +570,11 @@ async function handleMerge(
     }
 
     // Gather merge context — full repo diff, not just .gsd/
-    const diffSummary = diffWorktreeAll(basePath, name);
-    const numstat = diffWorktreeNumstat(basePath, name);
-    const gsdDiff = getWorktreeGSDDiff(basePath, name);
-    const codeDiff = getWorktreeCodeDiff(basePath, name);
-    const commitLog = getWorktreeLog(basePath, name);
+    const diffSummary = diffWorktreeAll(basePath, name, undefined, mainBranch);
+    const numstat = diffWorktreeNumstat(basePath, name, undefined, mainBranch);
+    const gsdDiff = getWorktreeGSDDiff(basePath, name, mainBranch);
+    const codeDiff = getWorktreeCodeDiff(basePath, name, mainBranch);
+    const commitLog = getWorktreeLog(basePath, name, mainBranch);
 
     const totalChanges = diffSummary.added.length + diffSummary.modified.length + diffSummary.removed.length;
     if (totalChanges === 0 && !commitLog.trim()) {
@@ -662,7 +662,7 @@ async function handleMerge(
     }
 
     try {
-      mergeWorktreeToMain(basePath, name, commitMessage);
+      mergeWorktreeToMain(basePath, name, commitMessage, undefined, mainBranch);
       ctx.ui.notify(
         [
           `${CLR.ok("✓")} Merged ${CLR.name(name)} → ${CLR.branch(mainBranch)} ${CLR.muted("(deterministic squash)")}`,

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

@@ -54,14 +54,14 @@ const DEFAULT_STALE_DAYS = 14;
  * @param basePath — the main project root (not the worktree path)
  * @param wt — worktree info from listWorktrees()
  * @param staleDays — days without commits to consider stale (default: 14)
+ * @param mainBranch — pre-detected main branch for batched health checks
  */
 export function getWorktreeHealth(
   basePath: string,
   wt: WorktreeInfo,
   staleDays = DEFAULT_STALE_DAYS,
+  mainBranch = nativeDetectMainBranch(basePath),
 ): WorktreeHealthStatus {
-  const mainBranch = nativeDetectMainBranch(basePath);
-
   // Merge status: is the worktree branch fully contained in main?
   let mergedIntoMain = false;
   try {
@@ -131,7 +131,10 @@ export function getAllWorktreeHealth(
   staleDays = DEFAULT_STALE_DAYS,
 ): WorktreeHealthStatus[] {
   const worktrees = listWorktrees(basePath);
-  return worktrees.map(wt => getWorktreeHealth(basePath, wt, staleDays));
+  if (worktrees.length === 0) return [];
+
+  const mainBranch = nativeDetectMainBranch(basePath);
+  return worktrees.map(wt => getWorktreeHealth(basePath, wt, staleDays, mainBranch));
 }
 
 /**

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

@@ -19,7 +19,7 @@
  *   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";
@@ -49,6 +49,7 @@ import {
   normalizeWorktreePathForCompare,
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { canonicalWorktreesDir, worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
@@ -197,7 +198,96 @@ function isRegisteredGitWorktreeAtPath(basePath: string, wtPath: string): boolea
   }
 }
 
-function removeStaleWorktreeDirectory(wtPath: string, name: string): void {
+/** True when `wtPath` has a git worktree checkout marker (`.git` file with gitdir pointer). */
+export function isLiveGitWorktreeCheckout(wtPath: string): boolean {
+  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: string, wtPath: string): boolean {
+  return isRegisteredGitWorktreeAtPath(basePath, wtPath) || isLiveGitWorktreeCheckout(wtPath);
+}
+
+const EPHEMERAL_GHOST_WORKTREE_ENTRIES = new Set([".bg-shell", ".DS_Store"]);
+
+function isEphemeralGhostWorktreeContents(dirPath: string): boolean {
+  let entries: string[];
+  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: string): string[] {
+  const removed: string[] = [];
+  for (const container of allWorktreesDirs(basePath)) {
+    if (!existsSync(container)) continue;
+    let entries: string[];
+    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: string, name: string): void {
   logWarning(
     "reconcile",
     `Removing stale worktree directory (not registered with git): ${wtPath}`,
@@ -874,11 +964,11 @@ function parseDiffNameStatus(entries: { status: string; path: string }[]): Workt
  * 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: string, name: string): WorktreeDiffSummary {
+export function diffWorktreeGSD(basePath: string, name: string, mainBranchOverride?: string): WorktreeDiffSummary {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const entries = nativeDiffNameStatus(basePath, mainBranch, branch, ".gsd/", true);
 
@@ -891,11 +981,16 @@ export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSum
  * on main when the merge is applied. If both branches have identical
  * content, this correctly returns an empty diff.
  */
-export function diffWorktreeAll(basePath: string, name: string, branchOverride?: string): WorktreeDiffSummary {
+export function diffWorktreeAll(
+  basePath: string,
+  name: string,
+  branchOverride?: string,
+  mainBranchOverride?: string,
+): WorktreeDiffSummary {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = branchOverride ?? worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
 
@@ -906,11 +1001,16 @@ export function diffWorktreeAll(basePath: string, name: string, 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: string, name: string, branchOverride?: string): FileLineStat[] {
+export function diffWorktreeNumstat(
+  basePath: string,
+  name: string,
+  branchOverride?: string,
+  mainBranchOverride?: string,
+): FileLineStat[] {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = branchOverride ?? worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
 
@@ -926,11 +1026,11 @@ export function diffWorktreeNumstat(basePath: string, name: string, branchOverri
  * 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: string, name: string): string {
+export function getWorktreeGSDDiff(basePath: string, name: string, mainBranchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   return nativeDiffContent(basePath, mainBranch, branch, ".gsd/", undefined, true);
 }
@@ -939,11 +1039,11 @@ export function getWorktreeGSDDiff(basePath: string, name: string): string {
  * 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: string, name: string): string {
+export function getWorktreeCodeDiff(basePath: string, name: string, mainBranchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   return nativeDiffContent(basePath, mainBranch, branch, undefined, ".gsd/", true);
 }
@@ -951,11 +1051,11 @@ export function getWorktreeCodeDiff(basePath: string, name: string): string {
 /**
  * Get commit log for the worktree branch since it diverged from main.
  */
-export function getWorktreeLog(basePath: string, name: string): string {
+export function getWorktreeLog(basePath: string, name: string, mainBranchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
 
   const entries = nativeLogOneline(basePath, mainBranch, branch);
 
@@ -967,11 +1067,17 @@ export function getWorktreeLog(basePath: string, name: string): string {
  * Must be called from the main working tree (not the worktree itself).
  * Returns the merge commit message.
  */
-export function mergeWorktreeToMain(basePath: string, name: string, commitMessage: string, branchOverride?: string): string {
+export function mergeWorktreeToMain(
+  basePath: string,
+  name: string,
+  commitMessage: string,
+  branchOverride?: string,
+  mainBranchOverride?: string,
+): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   const branch = branchOverride ?? worktreeBranchName(name);
-  const mainBranch = nativeDetectMainBranch(basePath);
+  const mainBranch = mainBranchOverride ?? nativeDetectMainBranch(basePath);
   const current = nativeGetCurrentBranch(basePath);
 
   if (current !== mainBranch) {

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

@@ -7,7 +7,7 @@ import { join, resolve } from "node:path";
 
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
 import { worktreesDirs } from "./worktree-placement.js";
-import { listWorktrees } from "./worktree-manager.js";
+import { listWorktrees, removeStaleWorktreeDirectory } from "./worktree-manager.js";
 import { getCurrentBranch } from "./worktree.js";
 
 export type WorktreeSafetyWriteScope = "planning-only" | "source-writing";
@@ -74,6 +74,7 @@ export interface WorktreeSafetyDeps {
   lstatSync(path: string): Pick<Stats, "isFile">;
   listRegisteredWorktrees?(projectRoot: string): readonly RegisteredWorktree[];
   pruneRegisteredWorktrees?(projectRoot: string): void;
+  removeStaleWorktreeDirectory?(unitRoot: string, milestoneId: string): void;
   getCurrentBranch?(unitRoot: string): string;
 }
 
@@ -100,6 +101,7 @@ const defaultDeps: WorktreeSafetyDeps = {
       stdio: "pipe",
     });
   },
+  removeStaleWorktreeDirectory,
   getCurrentBranch,
 };
 
@@ -127,8 +129,6 @@ function errorMessage(error: unknown): string {
 export function createWorktreeSafetyModule(
   deps: WorktreeSafetyDeps = defaultDeps,
 ): WorktreeSafetyModule {
-  const unregisteredRecoveryFailed = new Set<string>();
-
   return {
     validateUnitRoot(input) {
       if (input.writeScope === "planning-only") {
@@ -230,22 +230,17 @@ export function createWorktreeSafetyModule(
           );
         }
         if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-          const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
           let attemptedPrune = false;
 
-          if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
+          if (deps.pruneRegisteredWorktrees) {
             attemptedPrune = true;
             try {
               deps.pruneRegisteredWorktrees(projectRoot);
               const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
               if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                unregisteredRecoveryFailed.delete(unitRoot);
                 registered = rechecked;
-              } else {
-                unregisteredRecoveryFailed.add(unitRoot);
               }
             } catch (error) {
-              unregisteredRecoveryFailed.add(unitRoot);
               return failure(
                 "worktree-git-probe-failed",
                 `Unable to recover unregistered worktree root ${unitRoot}.`,
@@ -256,13 +251,38 @@ export function createWorktreeSafetyModule(
           }
 
           if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
+            // The directory exists on disk with a .git marker but git no longer
+            // tracks it as a worktree (e.g. a prior removeWorktree crash left the
+            // directory while `git worktree prune` cleaned the registry). Remove
+            // the orphaned directory — the same cleanup createWorktree performs —
+            // so the next dispatch recreates the milestone worktree from scratch
+            // instead of looping forever on worktree-unregistered (#803, #590).
+            if (deps.removeStaleWorktreeDirectory) {
+              try {
+                deps.removeStaleWorktreeDirectory(unitRoot, milestoneId);
+                return failure(
+                  "worktree-missing",
+                  `Worktree root ${unitRoot} was not registered with git; removed the orphaned directory so it can be recreated.`,
+                  "Recreate the milestone worktree before dispatching the source-writing Unit. Auto-mode recreates it automatically on the next dispatch.",
+                  { unitRoot, attemptedPrune, removedStaleDirectory: true },
+                );
+              } catch (error) {
+                return failure(
+                  "worktree-unregistered",
+                  `Worktree root ${unitRoot} is not registered with git worktree list and the orphaned directory could not be removed.`,
+                  "Remove the orphaned worktree directory manually (it may be locked by another process), then recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+                  { unitRoot, attemptedPrune, removedStaleDirectory: false, error: errorMessage(error) },
+                );
+              }
+            }
+
             return failure(
               "worktree-unregistered",
               `Worktree root ${unitRoot} is not registered with git worktree list.`,
-              attemptedPrune || wasPreviouslyTracked
+              attemptedPrune
                 ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
                 : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
-              { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
+              { unitRoot, attemptedPrune },
             );
           }
         }

package/src/resources/extensions/gsd/worktree-shell-guard.ts

@@ -0,0 +1,123 @@
+// Project/App: gsd-pi
+// File Purpose: Detect shell commands that reference the project root from a milestone worktree.
+
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+import { projectRootFromWorktreePath } from "./worktree-root.js";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function normalizeScanPath(value: string): string {
+  const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized.startsWith("/private/var/")
+    ? normalized.slice("/private".length)
+    : normalized;
+}
+
+function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
+  const normalizedBase = normalizeScanPath(baseDir);
+  const originalRoot = projectRootFromWorktreePath(normalizedBase);
+  if (!originalRoot) return null;
+  return { originalRoot, worktreeRoot: normalizedBase };
+}
+
+function pathInside(parent: string, target: string): boolean {
+  const parentWithSep = parent.endsWith("/") ? parent : `${parent}/`;
+  return target === parent || target.startsWith(parentWithSep);
+}
+
+function comparablePathVariants(value: string): string[] {
+  const variants = new Set<string>();
+  const normalized = normalizeScanPath(path.resolve(value));
+  variants.add(normalized);
+  try {
+    variants.add(normalizeScanPath(realpathSync(normalized)));
+  } catch {
+    // Nonexistent paths are still compared lexically.
+  }
+  if (normalized.startsWith("/private/var/")) {
+    variants.add(normalized.replace(/^\/private\/var\//, "/var/"));
+  } else if (normalized.startsWith("/var/")) {
+    variants.add(`/private${normalized}`);
+  }
+  return [...variants];
+}
+
+function pathInsideAny(parents: readonly string[], targets: readonly string[]): boolean {
+  return targets.some((target) => parents.some((parent) => pathInside(parent, target)));
+}
+
+function stripWrappingQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if ((first === "'" || first === '"' || first === "`") && last === first) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function extractPathLikeValues(script: string): string[] {
+  const values: string[] = [];
+  const push = (candidate: string) => {
+    const cleaned = stripWrappingQuotes(candidate).trim();
+    if (!cleaned) return;
+    values.push(cleaned);
+  };
+  const pushQuotedLiterals = (source: string, depth = 0) => {
+    for (const match of source.matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)) {
+      push(match[2]);
+      if (depth < 2 && /["'`]/.test(match[2])) {
+        pushQuotedLiterals(match[2], depth + 1);
+      }
+    }
+  };
+
+  for (const match of script.matchAll(/(?:^|[;\n\r]|\&\&|\|\|)\s*cd\s+([^\n\r;|&]+)/g)) {
+    push(match[1]);
+  }
+  for (const match of script.matchAll(/process\.chdir\(\s*([^\n\r;]+?)\s*\)/g)) {
+    push(match[1]);
+    pushQuotedLiterals(match[1]);
+  }
+  pushQuotedLiterals(script);
+  return values;
+}
+
+export function resolvesToOriginalRootOutsideWorktree(script: string, baseDir: string): boolean {
+  const parsed = parseWorktreeBase(baseDir);
+  if (!parsed) return false;
+
+  const normalizedWorktree = normalizeScanPath(path.resolve(parsed.worktreeRoot));
+  const normalizedOriginalRoot = normalizeScanPath(path.resolve(parsed.originalRoot));
+  const worktreeRoots = comparablePathVariants(normalizedWorktree);
+  const originalRoots = comparablePathVariants(normalizedOriginalRoot);
+  for (const value of extractPathLikeValues(script)) {
+    const resolved = comparablePathVariants(path.resolve(normalizedWorktree, value));
+    if (pathInsideAny(originalRoots, resolved) && !pathInsideAny(worktreeRoots, resolved)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function scriptReferencesOriginalRootFromWorktree(script: string, baseDir: string): boolean {
+  const parsed = parseWorktreeBase(baseDir);
+  if (!parsed) return false;
+  const normalizedScript = script.replace(/\\/g, "/");
+  return comparablePathVariants(parsed.originalRoot).some((originalRoot) => {
+    const originalRootPattern = new RegExp(
+      `${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd(?:-worktrees|/worktrees)(?:/|$)))`,
+    );
+    return originalRootPattern.test(normalizedScript);
+  });
+}
+
+export function bashReferencesProjectRootOutsideWorktree(script: string, baseDir: string): boolean {
+  return resolvesToOriginalRootOutsideWorktree(script, baseDir)
+    || scriptReferencesOriginalRootFromWorktree(script, baseDir);
+}