@opengsd/gsd-pi 1.4.0 → 1.5.0

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

@@ -21,6 +21,8 @@ import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 
+import type { PreflightResult, PostflightResult } from "./clean-root-preflight.js";
+
 import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning } from "./workflow-logger.js";
@@ -153,11 +155,11 @@ export interface WorktreeLifecycleDeps {
   /**
    * Milestone Merge Transaction Module runner.
    *
-   * The field name is preserved for existing test fixtures, but production
-   * wiring now supplies the named transaction wrapper rather than the raw
-   * squash-merge primitive directly.
+   * The field name describes the lifecycle seam; production wiring supplies
+   * the named transaction wrapper rather than the raw legacy
+   * auto-worktree primitive directly.
    */
-  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
+  mergeMilestone: MilestoneMergeTransactionRunner;
 
   // ADR-016 phase 2 / C1 + C2 + C3 + C4 inlined the following fields as
   // direct imports — leaf primitives that did not vary across callers:
@@ -238,7 +240,106 @@ export interface StrandedMilestoneAdoptionOptions {
 
 export type ExitResult =
   | { ok: true; merged: boolean; codeFilesChanged: boolean }
-  | { ok: false; reason: "merge-conflict" | "teardown-failed"; cause?: unknown };
+  | {
+      ok: false;
+      reason:
+        | "merge-conflict"
+        | "teardown-failed"
+        | "preflight-dirty-overlap"
+        | "preflight-unmerged-conflicts"
+        | "merge-failed"
+        | "postflight-stash-restore-failed";
+      cause?: unknown;
+      postflight?: PostflightResult;
+    };
+
+export interface GuardedMilestoneMergeDeps {
+  preflightCleanRoot: (
+    basePath: string,
+    milestoneId: string,
+    notify: NotifyCtx["notify"],
+  ) => PreflightResult;
+  postflightPopStash: (
+    basePath: string,
+    milestoneId: string,
+    stashMarker: string | undefined,
+    notify: NotifyCtx["notify"],
+  ) => PostflightResult;
+}
+
+/**
+ * Optional `exitMilestone(..., { merge: true, guardedMerge })` contract for callers
+ * that need root-clean preflight and postflight stash restoration around the
+ * lifecycle-owned merge attempt. `projectRoot` is the workspace root whose
+ * user changes are protected by the supplied guard functions.
+ */
+export interface GuardedMilestoneMergeOptions extends GuardedMilestoneMergeDeps {
+  projectRoot: string;
+}
+
+type GuardedMilestoneMergeResult = ExitResult;
+
+function preflightBlockedMergeReason(
+  blockedReason: PreflightResult["blockedReason"],
+): Extract<ExitResult, { ok: false }>["reason"] {
+  if (blockedReason?.startsWith("unmerged-conflicts")) {
+    return "preflight-unmerged-conflicts";
+  }
+  return "preflight-dirty-overlap";
+}
+
+/**
+ * Run a milestone merge behind the Worktree Lifecycle seam with the root-clean
+ * stash guard that protects user changes around merge.
+ *
+ * The helper owns the invariant ordering (preflight -> merge callback ->
+ * postflight on every attempted merge path) and returns the same typed result
+ * shape as `exitMilestone`. Auto closeout remains responsible for translating
+ * that result into loop policy (pause vs. stop, visible transcript
+ * preservation, projection rebuild).
+ */
+function runGuardedMilestoneMerge(request: {
+  merge: () => ExitResult;
+  guard: GuardedMilestoneMergeOptions;
+  milestoneId: string;
+  notify: NotifyCtx["notify"];
+}): GuardedMilestoneMergeResult {
+  const { merge, guard, milestoneId, notify } = request;
+  const preflight = guard.preflightCleanRoot(guard.projectRoot, milestoneId, notify);
+  if (preflight.blocked) {
+    return {
+      ok: false,
+      reason: preflightBlockedMergeReason(preflight.blockedReason),
+    };
+  }
+
+  let mergeError: unknown = null;
+  const exitResult = merge();
+  if (!exitResult.ok) {
+    mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+  }
+
+  let postflight: PostflightResult | undefined;
+  if (preflight.stashPushed) {
+    postflight = guard.postflightPopStash(
+      guard.projectRoot,
+      milestoneId,
+      preflight.stashMarker,
+      notify,
+    );
+  }
+
+  if (mergeError instanceof MergeConflictError) {
+    return { ok: false, reason: "merge-conflict", cause: mergeError, postflight };
+  }
+  if (mergeError) {
+    return { ok: false, reason: "merge-failed", cause: mergeError, postflight };
+  }
+  if (postflight?.needsManualRecovery) {
+    return { ok: false, reason: "postflight-stash-restore-failed", postflight };
+  }
+  return exitResult;
+}
 
 /**
  * Session-less merge entry context. Per ADR-016 phase 2 / A1 (#5616), the
@@ -1046,7 +1147,7 @@ function _mergeWorktreeModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       originalBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1213,7 +1314,7 @@ function _mergeBranchModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       worktreeBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1444,18 +1545,41 @@ export class WorktreeLifecycle {
    * With `opts.merge === false`, runs auto-commit and teardown without
    * merging to main.
    *
+   * When `opts.guardedMerge` is present with `opts.merge === true`, the
+   * lifecycle verb also owns the root-clean guard around the merge: preflight
+   * runs before the inner merge, postflight stash restore runs after every
+   * attempted merge path, and guard failures are returned as typed
+   * `ExitResult` reasons.
+   *
    * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
    * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
-   * giving callers a typed branch for the expected failure path.
-   * Unexpected failures (filesystem, git permissions, etc.) are wrapped
-   * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
+   * giving callers a typed branch for the expected failure path. Guarded merge
+   * failures surface as `preflight-dirty-overlap`,
+   * `preflight-unmerged-conflicts`, `merge-failed`, or
+   * `postflight-stash-restore-failed`. Unexpected failures (filesystem, git
+   * permissions, etc.) are wrapped as
+   * `{ ok: false, reason: "teardown-failed", cause }` so callers always
    * receive a discriminated union — no exceptions for any expected outcome.
    */
   exitMilestone(
     milestoneId: string,
-    opts: { merge: boolean; preserveBranch?: boolean; preserveWorktree?: boolean },
+    opts: {
+      merge: boolean;
+      preserveBranch?: boolean;
+      preserveWorktree?: boolean;
+      guardedMerge?: GuardedMilestoneMergeOptions;
+    },
     ctx: NotifyCtx,
   ): ExitResult {
+    if (opts.merge && opts.guardedMerge) {
+      return runGuardedMilestoneMerge({
+        merge: () => this.exitMilestone(milestoneId, { merge: true }, ctx),
+        guard: opts.guardedMerge,
+        milestoneId,
+        notify: ctx.notify,
+      });
+    }
+
     if (opts.merge) {
       try {
         const merged = this._mergeAndExit(milestoneId, ctx);

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, statSync, unlinkSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } 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";
@@ -227,6 +227,113 @@ function isRegisteredGitWorktreeAtPath(basePath: string, wtPath: string): boolea
   }
 }
 
+function inspectUncommittedWorktreeState(wtPath: string): { dirty: boolean; status: string } {
+  try {
+    const status = execFileSync(
+      "git",
+      ["status", "--porcelain=v1", "--untracked-files=all"],
+      { cwd: wtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trimEnd();
+    return { dirty: status.length > 0, status };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logWarning(
+      "worktree",
+      `dirty worktree inspection failed for ${wtPath}: ${message}`,
+    );
+    // Fail closed: unknown state must quarantine rather than force-remove.
+    return { dirty: true, status: `git status failed: ${message}` };
+  }
+}
+
+function timestampForPath(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function uniqueQuarantinePath(basePath: string, name: string): string {
+  const root = join(basePath, ".gsd", "quarantine", "worktrees");
+  const baseName = `${name}-${timestampForPath()}`;
+  let candidate = join(root, baseName);
+  let suffix = 2;
+  while (existsSync(candidate)) {
+    candidate = join(root, `${baseName}-${suffix}`);
+    suffix++;
+  }
+  return candidate;
+}
+
+function quarantineDirtyWorktree(
+  basePath: string,
+  name: string,
+  branch: string,
+  wtPath: string,
+  status: string,
+): string | null {
+  const quarantinePath = uniqueQuarantinePath(basePath, name);
+  mkdirSync(join(basePath, ".gsd", "quarantine", "worktrees"), { recursive: true });
+
+  let moved = false;
+  try {
+    renameSync(wtPath, quarantinePath);
+    moved = true;
+  } catch (renameErr) {
+    logWarning(
+      "worktree",
+      `dirty worktree rename quarantine failed for ${name}: ${renameErr instanceof Error ? renameErr.message : String(renameErr)}; trying copy snapshot`,
+    );
+    try {
+      cpSync(wtPath, quarantinePath, { recursive: true, force: false, errorOnExist: true });
+    } catch (copyErr) {
+      logWarning(
+        "reconcile",
+        `Dirty worktree quarantine failed; preserving original worktree ${wtPath}: ${copyErr instanceof Error ? copyErr.message : String(copyErr)}`,
+        { worktree: name, path: wtPath },
+      );
+      return null;
+    }
+  }
+
+  try {
+    const gitFile = join(quarantinePath, ".git");
+    if (existsSync(gitFile) && lstatSync(gitFile).isFile()) {
+      unlinkSync(gitFile);
+    }
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `failed to remove quarantined worktree git pointer: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  try {
+    writeFileSync(
+      join(quarantinePath, ".gsd-quarantine.json"),
+      JSON.stringify({
+        kind: "dirty-worktree",
+        worktree: name,
+        branch,
+        originalPath: wtPath,
+        moved,
+        quarantinedAt: new Date().toISOString(),
+        status,
+      }, null, 2) + "\n",
+      "utf-8",
+    );
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `failed to write worktree quarantine metadata: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  logWarning(
+    "reconcile",
+    `Quarantined dirty worktree ${name} at ${quarantinePath} before removal. Branch ${branch} was preserved.`,
+    { worktree: name, path: quarantinePath, branch },
+  );
+  return quarantinePath;
+}
+
 /** 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");
@@ -730,12 +837,13 @@ export function removeWorktree(
   basePath: string,
   name: string,
   opts: { deleteBranch?: boolean; force?: boolean; branch?: string } = {},
-): void {
+): boolean {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
   let wtPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
   const { deleteBranch = true, force = true } = opts;
+  let deleteBranchAfterRemoval = deleteBranch;
 
   // Resolve the ACTUAL worktree path from git's worktree list.
   // The computed path may differ when .gsd/ is (or was) a symlink to an
@@ -788,10 +896,10 @@ export function removeWorktree(
 
   if (!existsSync(wtPath)) {
     nativeWorktreePrune(basePath);
-    if (deleteBranch) {
+    if (deleteBranchAfterRemoval) {
       deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
     }
-    return;
+    return true;
   }
 
   // Submodule safety (#2337): detect submodules with uncommitted changes
@@ -873,6 +981,35 @@ export function removeWorktree(
     }
   }
 
+  // Dirty-worktree quarantine (#2365): once submodule (#2337) and nested-.git
+  // (#2616) rescue have run — they commit/clean the tree first — quarantine any
+  // uncommitted state that remains instead of force-deleting it. Gate on a live
+  // git checkout so a stale local directory left behind by state-sync (which
+  // has no `.git` file and is not a registered worktree) is removed normally
+  // rather than quarantined; otherwise its branch would never be deleted and
+  // the worktree would never be unregistered (#1852).
+  if (force && resolvedPathSafe && isLiveGitWorktreeCheckout(resolvedWtPath)) {
+    const dirtyState = inspectUncommittedWorktreeState(resolvedWtPath);
+    if (dirtyState.dirty) {
+      const quarantinePath = quarantineDirtyWorktree(
+        basePath,
+        name,
+        branch,
+        resolvedWtPath,
+        dirtyState.status,
+      );
+      if (!quarantinePath) {
+        return false;
+      }
+
+      deleteBranchAfterRemoval = false;
+      if (!existsSync(resolvedWtPath)) {
+        nativeWorktreePrune(basePath);
+        return true;
+      }
+    }
+  }
+
   // Remove worktree — only use force/rmSync when the path is safely contained
   if (resolvedPathSafe) {
     // Remove worktree: try non-force first when submodules have changes,
@@ -923,9 +1060,10 @@ export function removeWorktree(
   // Prune stale entries so git knows the worktree is gone
   nativeWorktreePrune(basePath);
 
-  if (deleteBranch) {
+  if (deleteBranchAfterRemoval) {
     deleteBranchIfPresent(basePath, branch, "final branch delete failed");
   }
+  return true;
 }
 
 /**