@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

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

@@ -47,11 +47,15 @@ import { createWorkspace, scopeMilestone } from "./workspace.js";
 // adding type churn without enabling any test variation.
 import { autoCommitCurrentBranch, getCurrentBranch, } from "./worktree.js";
 import { nativeCheckoutBranch } from "./native-git-bridge.js";
-// ADR-016 phase 2 / C2 (#5625): worktree-manager helpers inlined from
-// `./auto-worktree.js`. These seven functions are not real seams — Lifecycle
-// is the only Module that calls them, and they live alongside the Module's
-// other primitives in `auto-worktree.ts`.
-import { autoWorktreeBranch, createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, getAutoWorktreePath, isInAutoWorktree, teardownAutoWorktree, } from "./auto-worktree.js";
+// ADR-016 phase 2 / C2 (#5625): lifecycle uses focused auto-worktree
+// modules instead of the legacy compatibility barrel. Branch, entry/path,
+// creation, and teardown primitives are still implementation-level seams for
+// Lifecycle; tests vary them through `WorktreeLifecycleTestOverrides` below.
+import { autoWorktreeBranch, enterBranchModeForMilestone, } from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import { enterAutoWorktree, isInAutoWorktree, } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
+import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 import { resolveRoadmapForMilestoneMerge } from "./milestone-merge-roadmap.js";
 const recentWorktreeMergeFailures = new Map();
 const MERGE_FAILURE_DEDUPE_MS = 60_000;
@@ -102,6 +106,51 @@ class UserNotifiedError extends Error {
 function isSamePathPhysical(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
+function preflightBlockedMergeReason(blockedReason) {
+    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) {
+    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 = null;
+    const exitResult = merge();
+    if (!exitResult.ok) {
+        mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+    }
+    let postflight;
+    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;
+}
 // ─── Validation ──────────────────────────────────────────────────────────
 function isValidMilestoneId(milestoneId) {
     return !/[\/\\]|\.\./.test(milestoneId);
@@ -645,7 +694,7 @@ function _mergeWorktreeModeImpl(deps, mctx) {
                 pushed: false,
             };
         }
-        const mergeResult = deps.mergeMilestoneToMain(originalBasePath, milestoneId, roadmapResolution.content);
+        const mergeResult = deps.mergeMilestone(originalBasePath, milestoneId, roadmapResolution.content);
         // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
         // cleanup internally (step 12), but it can silently fail on Windows
         // or when the worktree directory is locked. Perform a secondary
@@ -780,7 +829,7 @@ function _mergeBranchModeImpl(deps, mctx) {
                 pushed: false,
             };
         }
-        const mergeResult = deps.mergeMilestoneToMain(worktreeBasePath, milestoneId, roadmapResolution.content);
+        const mergeResult = deps.mergeMilestone(worktreeBasePath, milestoneId, roadmapResolution.content);
         if (mergeResult.codeFilesChanged) {
             notify(`Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
         }
@@ -829,8 +878,9 @@ function _mergeBranchModeImpl(deps, mctx) {
  * **CWD anchor**: anchors `process.cwd()` at `originalBasePath` before
  * non-worktree merge paths to mirror the single-loop guard against ENOENT
  * after teardown (de73fb43d). Worktree-mode merge paths keep the real
- * worktree as cwd because `mergeMilestoneToMain()` infers source worktree
- * state from `process.cwd()`. Best-effort; silent on failure.
+ * worktree as cwd because the default milestone merge transaction delegates
+ * to the legacy merge primitive, which infers source worktree state from
+ * `process.cwd()`. Best-effort; silent on failure.
  *
  * **Failure handling**: `MergeConflictError` and other unrecoverable errors
  * propagate to the caller. The caller is responsible for any state restore
@@ -918,8 +968,8 @@ export function mergeMilestoneStandalone(deps, mctx) {
     }
     // Set cwd to the correct anchor before dispatching to mode implementations.
     // Worktree mode / in-worktree override must run from the live worktree so
-    // mergeMilestoneToMain can find worktree-local state; branch mode runs from
-    // the original project root. Best-effort for synthetic test paths.
+    // The default merge transaction can find worktree-local state; branch mode
+    // runs from the original project root. Best-effort for synthetic test paths.
     const targetCwd = mode === "worktree" || inWorktree
         ? worktreeBasePath
         : originalBasePath;
@@ -983,14 +1033,31 @@ 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, opts, ctx) {
+        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/dist/resources/extensions/gsd/worktree-manager.js

@@ -17,7 +17,7 @@
  *   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, 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";
@@ -163,6 +163,76 @@ function isRegisteredGitWorktreeAtPath(basePath, wtPath) {
         return false;
     }
 }
+function inspectUncommittedWorktreeState(wtPath) {
+    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() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function uniqueQuarantinePath(basePath, name) {
+    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, name, branch, wtPath, status) {
+    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) {
     const gitPath = join(wtPath, ".git");
@@ -610,6 +680,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     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
     // external state directory — git resolves symlinks at worktree creation
@@ -664,10 +735,10 @@ export function removeWorktree(basePath, name, opts = {}) {
     }
     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
     // before force-removing the worktree. Force removal destroys all uncommitted
@@ -721,6 +792,27 @@ export function removeWorktree(basePath, name, opts = {}) {
             }
         }
     }
+    // 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,
@@ -778,9 +870,10 @@ export function removeWorktree(basePath, name, opts = {}) {
     }
     // 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;
 }
 /**
  * Paths to skip in all worktree diffs (internal/runtime artifacts).

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

@@ -6,7 +6,8 @@
 // back into the worktree. The worktree path is fully derivable from state, so we
 // resolve and chdir into it directly instead.
 import { readdirSync } from "node:fs";
-import { enterAutoWorktree, getAutoWorktreePath } from "./auto-worktree.js";
+import { enterAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { getIsolationMode } from "./preferences.js";
 import { allWorktreesDirs } from "./worktree-manager.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";