gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

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

@@ -33,6 +33,7 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "gsd_journal_query",
   "gsd_milestone_complete",
   "gsd_milestone_generate_id",
+  "gsd_milestone_reopen",
   "gsd_checkpoint_db",
   "gsd_milestone_status",
   "gsd_milestone_validate",
@@ -41,6 +42,9 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "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",
@@ -50,9 +54,11 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
   "gsd_skip_slice",
   "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_validate_milestone",
 ]);

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

@@ -30,6 +30,7 @@ import {
   nativeDiffNameStatus,
   nativeDiffNumstat,
   nativeGetCurrentBranch,
+  nativeIsAncestor,
   nativeLogOneline,
   nativeMergeSquash,
   nativeWorktreeAdd,
@@ -37,6 +38,7 @@ import {
   nativeWorktreePrune,
   nativeWorktreeRemove,
 } from "./native-git-bridge.js";
+import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -132,6 +134,58 @@ export function isInsideWorktreesDir(basePath: string, targetPath: string): bool
   return resolved === wtDir || resolved.startsWith(wtDir + sep);
 }
 
+/**
+ * Return the canonical path from which a milestone's artifacts should be read.
+ *
+ * If a live git worktree exists for this milestone at `.gsd/worktrees/<MID>/`
+ * (directory present AND a `.git` file indicating a registered worktree),
+ * returns that worktree path. Otherwise returns `basePath` unchanged.
+ *
+ * Readers that cross the session/worktree boundary (validators, the bootstrap
+ * audit, cross-session state queries) should route through this helper so they
+ * don't silently read stale project-root state while live work sits in the
+ * worktree. Writers and tools whose contract is "operate on the path I was
+ * given" should NOT use this helper — they preserve the legacy behavior.
+ *
+ * A stale worktree directory (no `.git` file) is treated as absent. The
+ * createWorktree() path already cleans these up, but readers must not trust
+ * them in the window before cleanup runs.
+ *
+ * Fixes #4761. Used by the #4762 audit for the pre-completion orphan case.
+ */
+export function resolveCanonicalMilestoneRoot(
+  basePath: string,
+  milestoneId: string,
+): string {
+  if (!milestoneId || /[\/\\]|\.\./.test(milestoneId)) return basePath;
+
+  const wtPath = worktreePath(basePath, milestoneId);
+  if (!existsSync(wtPath)) return basePath;
+
+  // A registered git worktree has a .git *file* (not directory) containing
+  // "gitdir: <path>". A standalone .git directory indicates a copied repo
+  // or nested standalone repo — not a worktree registered with this project —
+  // and must not be treated as the canonical root.
+  const gitPath = join(wtPath, ".git");
+  if (!existsSync(gitPath)) return basePath;
+  try {
+    const stat = lstatSync(gitPath);
+    if (!stat.isFile()) return basePath;
+  } catch {
+    return basePath;
+  }
+
+  // #4764 — record the redirect so we can measure how often the #4761 fix
+  // would have mattered. Best-effort; emit is silent on any failure.
+  try {
+    emitCanonicalRootRedirect(basePath, milestoneId, wtPath);
+  } catch (err) {
+    logWarning("worktree", `canonical-root-redirect telemetry failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return wtPath;
+}
+
 // ─── Core Operations ───────────────────────────────────────────────────────
 
 /**
@@ -174,6 +228,17 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
   // otherwise fall back to the repo's detected main branch.
   const startPoint = opts.startPoint ?? nativeDetectMainBranch(basePath);
 
+  // Reject early if startPoint resolves to an empty/invalid ref. On an
+  // unborn branch (zero-commit repo) nativeDetectMainBranch returns "",
+  // which would flow into `git worktree add ... ""` and crash with
+  // `fatal: not a valid object name`. (Issue #4980 HIGH-9)
+  if (!startPoint || startPoint.length === 0) {
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      "Repository has no commits yet (unborn branch). Make an initial commit before creating worktrees.",
+    );
+  }
+
   // Check if the branch already exists (leftover from a previous worktree)
   const branchAlreadyExists = nativeBranchExists(basePath, branch);
 
@@ -196,6 +261,21 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
       // from prior sessions that must not be reset.
       nativeWorktreeAdd(basePath, wtPath, branch);
     } else {
+      // Ancestry guard: refuse to force-reset a branch that has commits not
+      // reachable from startPoint. A crash-then-resume cycle that didn't
+      // write the resume file would silently orphan prior-session commits
+      // (recoverable from reflog for 90d, then gone — branch is also
+      // deleted at teardown). (Issue #4980 HIGH-3)
+      const branchIsAncestor = nativeIsAncestor(basePath, branch, startPoint);
+      if (!branchIsAncestor) {
+        throw new GSDError(
+          GSD_GIT_ERROR,
+          `Branch "${branch}" already exists with commits not reachable from "${startPoint}". ` +
+          `Refusing to force-reset — would orphan prior work. ` +
+          `If you intend to keep those commits, retry with reuseExistingBranch=true. ` +
+          `If you intend to discard, run \`git branch -D ${branch}\` manually first.`,
+        );
+      }
       // Reset the stale branch to the start point, then attach worktree to it
       nativeBranchForceReset(basePath, branch, startPoint);
       nativeWorktreeAdd(basePath, wtPath, branch);
@@ -451,17 +531,38 @@ export function removeWorktree(
         (line: string) => line.startsWith("+") || line.startsWith("-"),
       );
       if (hasSubmoduleChanges) {
-        // Stash submodule changes so they are not lost during force removal.
-        // The stash is created in the worktree before it's torn down.
+        // Save submodule changes to a labeled rescue branch instead of the
+        // shared stash list. Stash is per-repo (not per-worktree), so an
+        // entry created here would appear in the user's main-tree stash
+        // list and reference paths that disappear after worktree removal.
+        // A branch persists in the shared .git refs after worktree removal
+        // and is discoverable via `git branch --list 'gsd/submodule-rescue/*'`.
+        // (Issue #4980 HIGH-11)
+        const rescueBranch = `gsd/submodule-rescue/${name}-${Date.now()}`;
         try {
           execFileSync(
-            "git", ["stash", "push", "-m", "gsd: auto-stash submodule changes before worktree teardown"],
+            "git", ["add", "-A"],
+            { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+          );
+          execFileSync(
+            "git", ["commit", "-m", `gsd: rescue submodule changes from worktree ${name}`, "--allow-empty"],
             { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
           );
-          logWarning("reconcile", `Stashed uncommitted submodule changes before worktree teardown`, { worktree: name, path: resolvedWtPath });
-        } catch {
-          // Stash failed — warn the user that submodule changes may be lost
-          logWarning("reconcile", `Submodule changes detected — stash failed, changes may be lost during force removal`, { worktree: name, path: resolvedWtPath });
+          execFileSync(
+            "git", ["branch", rescueBranch, "HEAD"],
+            { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+          );
+          logWarning(
+            "reconcile",
+            `Saved uncommitted submodule changes to rescue branch ${rescueBranch}`,
+            { worktree: name, path: resolvedWtPath, rescueBranch },
+          );
+        } catch (err) {
+          logWarning(
+            "reconcile",
+            `Submodule rescue branch creation failed — changes may be lost during force removal: ${err instanceof Error ? err.message : String(err)}`,
+            { worktree: name, path: resolvedWtPath },
+          );
         }
       }
     } catch (e) {
@@ -559,6 +660,7 @@ const SKIP_PATHS = [
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/parallel/",
   ".gsd/journal/",

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

@@ -20,6 +20,9 @@ import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
 import { MergeConflictError } from "./git-service.js";
 import { emitJournalEvent } from "./journal.js";
+import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
+import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain } from "./slice-cadence.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 // ─── Dependency Interface ──────────────────────────────────────────────────
 
@@ -79,6 +82,35 @@ export interface NotifyCtx {
   ) => void;
 }
 
+// ─── Path Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Worktree marker segment — present in any path produced by worktreePath().
+ * Used to strip the worktree suffix and recover the project root (#3729).
+ */
+const WORKTREE_MARKER = "/.gsd/worktrees/";
+
+/**
+ * Resolve the project root from session path state.
+ *
+ * Prefers `originalBasePath` (always the project root when set), but falls
+ * back to `basePath` when `originalBasePath` is falsy (e.g. fresh AutoSession
+ * with default empty string). If `basePath` itself is inside a worktree
+ * directory (contains `/.gsd/worktrees/`), strip that suffix to recover the
+ * actual project root — preventing double-nested worktree paths (#3729).
+ */
+export function resolveProjectRoot(
+  originalBasePath: string,
+  basePath: string,
+): string {
+  let resolved = originalBasePath || basePath;
+  const markerIdx = resolved.indexOf(WORKTREE_MARKER);
+  if (markerIdx !== -1) {
+    resolved = resolved.slice(0, markerIdx);
+  }
+  return resolved;
+}
+
 // ─── WorktreeResolver ──────────────────────────────────────────────────────
 
 export class WorktreeResolver {
@@ -99,12 +131,12 @@ export class WorktreeResolver {
 
   /** Original project root — always the non-worktree path. */
   get projectRoot(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   /** Path for auto.lock file — same as the old lockBase(). */
   get lockPath(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   // ── Private Helpers ────────────────────────────────────────────────────
@@ -182,7 +214,10 @@ export class WorktreeResolver {
       return;
     }
 
-    const basePath = this.s.originalBasePath || this.s.basePath;
+    // Resolve the project root for worktree operations via shared helper.
+    // Handles the case where originalBasePath is falsy and basePath is itself
+    // a worktree path — prevents double-nested worktree paths (#3729).
+    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
@@ -258,6 +293,19 @@ export class WorktreeResolver {
         eventType: "worktree-enter",
         data: { milestoneId, wtPath, created: !existingPath },
       });
+      // #4764 — record creation/enter as a lifecycle event so the telemetry
+      // aggregator can pair it with the eventual worktree-merged event.
+      try {
+        emitWorktreeCreated(this.s.originalBasePath || this.s.basePath, milestoneId, {
+          reason: existingPath ? "enter-milestone" : "create-milestone",
+        });
+      } catch (telemetryErr) {
+        debugLog("WorktreeResolver", {
+          action: "enterMilestone",
+          phase: "telemetry-emit",
+          error: telemetryErr instanceof Error ? telemetryErr.message : String(telemetryErr),
+        });
+      }
       ctx.notify(`Entered worktree for ${milestoneId} at ${wtPath}`, "info");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -366,6 +414,10 @@ export class WorktreeResolver {
   mergeAndExit(milestoneId: string, ctx: NotifyCtx): void {
     this.validateMilestoneId(milestoneId);
 
+    // #4764 — telemetry: record start timestamp so we can emit merge duration.
+    const mergeStartedAt = new Date().toISOString();
+    const mergeStartMs = Date.now();
+
     // If worktree creation failed earlier, skip merge — work is on current branch (#2483)
     if (this.s.isolationDegraded) {
       debugLog("WorktreeResolver", {
@@ -412,17 +464,79 @@ export class WorktreeResolver {
       return;
     }
 
+    let actuallyMerged = false;
     if (
       mode === "worktree" || inWorktree
     ) {
-      this._mergeWorktreeMode(milestoneId, ctx);
+      actuallyMerged = this._mergeWorktreeMode(milestoneId, ctx);
     } else if (mode === "branch") {
-      this._mergeBranchMode(milestoneId, ctx);
+      actuallyMerged = this._mergeBranchMode(milestoneId, ctx);
+    }
+
+    // The remainder of this function emits telemetry and runs re-squash.
+    // Both are gated on actuallyMerged — if the _merge* helper took a
+    // no-merge path (missing originalBase, no roadmap, wrong branch) the
+    // milestone branch was intentionally left unmerged and we must not
+    // emit a worktree-merged event or collapse commits on main.
+    if (!actuallyMerged) {
+      // Always clear the start-SHA tracker to avoid leaking across sessions.
+      this.s.milestoneStartShas.delete(milestoneId);
+      return;
+    }
+
+    // #4765 — when collapse_cadence=slice AND milestone_resquash=true, the
+    // N per-slice commits on main should be collapsed into one milestone
+    // commit. Done AFTER the primary merge-and-teardown so the branch and
+    // worktree are already cleaned up; we operate on main directly.
+    try {
+      const startSha = this.s.milestoneStartShas.get(milestoneId);
+      if (startSha) {
+        const prefs = loadEffectiveGSDPreferences(this.s.originalBasePath || this.s.basePath)?.preferences;
+        if (getCollapseCadence(prefs) === "slice" && getMilestoneResquash(prefs)) {
+          const result = resquashMilestoneOnMain(
+            this.s.originalBasePath || this.s.basePath,
+            milestoneId,
+            startSha,
+          );
+          if (result.resquashed) {
+            ctx.notify(
+              `slice-cadence: re-squashed slice commits for ${milestoneId} into a single milestone commit.`,
+              "info",
+            );
+          }
+        }
+        this.s.milestoneStartShas.delete(milestoneId);
+      }
+    } catch (err) {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        phase: "resquash",
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    // #4764 — record merge completion. Only reaches here when an actual
+    // merge ran; failure paths throw out of _merge* before this point and
+    // no-merge paths returned above.
+    try {
+      emitWorktreeMerged(this.s.originalBasePath || this.s.basePath, milestoneId, {
+        reason: "milestone-complete",
+        startedAt: mergeStartedAt,
+        durationMs: Date.now() - mergeStartMs,
+      });
+    } catch (telemetryErr) {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        phase: "telemetry-emit",
+        error: telemetryErr instanceof Error ? telemetryErr.message : String(telemetryErr),
+      });
     }
   }
 
-  /** Worktree-mode merge: read roadmap, merge, teardown, reset paths. */
-  private _mergeWorktreeMode(milestoneId: string, ctx: NotifyCtx): void {
+  /** Worktree-mode merge: read roadmap, merge, teardown, reset paths.
+   *  Returns true when a squash-merge actually ran (false on skip paths). */
+  private _mergeWorktreeMode(milestoneId: string, ctx: NotifyCtx): boolean {
     const originalBase = this.s.originalBasePath;
     if (!originalBase) {
       debugLog("WorktreeResolver", {
@@ -432,9 +546,10 @@ export class WorktreeResolver {
         skipped: true,
         reason: "missing-original-base",
       });
-      return;
+      return false;
     }
 
+    let merged = false;
     try {
       const { synced } = this.deps.syncWorktreeStateBack(
         originalBase,
@@ -483,6 +598,7 @@ export class WorktreeResolver {
           milestoneId,
           roadmapContent,
         );
+        merged = true;
 
         // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
         // cleanup internally (step 12), but it can silently fail on Windows
@@ -569,11 +685,13 @@ export class WorktreeResolver {
         }
       }
 
-      // Re-throw MergeConflictError so the auto loop can detect real code
-      // conflicts and stop instead of retrying forever (#2330).
-      if (err instanceof MergeConflictError) {
-        throw err;
-      }
+      // Restore state before re-throwing so callers always get a consistent
+      // session (#4380).
+      this.restoreToProjectRoot();
+      // Re-throw: MergeConflictError stops the auto loop (#2330); non-conflict
+      // errors (permission denied, filesystem failures) must also propagate so
+      // broken states are diagnosable (#4380).
+      throw err;
     }
 
     // Always restore basePath and rebuild — whether merge succeeded or failed
@@ -584,10 +702,12 @@ export class WorktreeResolver {
       result: "done",
       basePath: this.s.basePath,
     });
+    return merged;
   }
 
-  /** Branch-mode merge: check current branch, merge if on milestone branch. */
-  private _mergeBranchMode(milestoneId: string, ctx: NotifyCtx): void {
+  /** Branch-mode merge: check current branch, merge if on milestone branch.
+   *  Returns true when a merge actually ran (false on skip paths). */
+  private _mergeBranchMode(milestoneId: string, ctx: NotifyCtx): boolean {
     try {
       const currentBranch = this.deps.getCurrentBranch(this.s.basePath);
       const milestoneBranch = this.deps.autoWorktreeBranch(milestoneId);
@@ -602,7 +722,7 @@ export class WorktreeResolver {
           currentBranch,
           milestoneBranch,
         });
-        return;
+        return false;
       }
 
       const roadmapPath = this.deps.resolveMilestoneFile(
@@ -618,7 +738,7 @@ export class WorktreeResolver {
           skipped: true,
           reason: "no-roadmap",
         });
-        return;
+        return false;
       }
 
       const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
@@ -649,6 +769,7 @@ export class WorktreeResolver {
         mode: "branch",
         result: "success",
       });
+      return true;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       debugLog("WorktreeResolver", {
@@ -659,6 +780,8 @@ export class WorktreeResolver {
         error: msg,
       });
       ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      // Re-throw all errors so callers can apply their own recovery logic (#4380).
+      throw err;
     }
   }
 
@@ -681,7 +804,16 @@ export class WorktreeResolver {
       currentMilestoneId,
       nextMilestoneId,
     });
-    this.mergeAndExit(currentMilestoneId, ctx);
+    try {
+      this.mergeAndExit(currentMilestoneId, ctx);
+    } catch (err) {
+      // mergeAndExit emits a warning and restores state when it fails during
+      // merge/cleanup. But if it throws before recovery runs (e.g., in
+      // validateMilestoneId or emitJournalEvent), basePath won't be restored
+      // to projectRoot — re-throw so we don't enter the next milestone with
+      // the current one unmerged.
+      if (this.s.basePath !== this.projectRoot) throw err;
+    }
     this.enterMilestone(nextMilestoneId, ctx);
   }
 }