@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

package/src/resources/extensions/gsd/workspace.ts

@@ -1,7 +1,17 @@
 // gsd-pi + Workspace handle: single source of truth for path resolution per milestone
 
-import { join, resolve } from "node:path";
-import { type GsdPathContract, resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildMilestoneFileName,
+  canonicalPhaseDirName,
+  isLegacyMilestonesLayout,
+  milestonesDir,
+  type GsdPathContract,
+  resolveGsdPathContract,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  normalizeRealPath,
+} from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 export type GsdWorkspaceMode = "project" | "worktree";
@@ -31,6 +41,29 @@ function tryRealpath(p: string): string {
   return normalizeRealPath(p);
 }
 
+function isLegacyMilestoneDirectory(dir: string): boolean {
+  const parent = dirname(dir);
+  return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
+}
+
+function scopeMilestoneDir(basePath: string, milestoneId: string): string {
+  return resolveMilestonePath(basePath, milestoneId) ?? join(
+    milestonesDir(basePath),
+    isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId),
+  );
+}
+
+function scopeMilestoneFile(basePath: string, milestoneId: string, suffix: string): string {
+  const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
+  if (existing) return existing;
+
+  const dir = scopeMilestoneDir(basePath, milestoneId);
+  const filename = isLegacyMilestoneDirectory(dir)
+    ? `${milestoneId}-${suffix}.md`
+    : buildMilestoneFileName(milestoneId, suffix);
+  return join(dir, filename);
+}
+
 /**
  * Create an immutable GsdWorkspace handle from a raw base path.
  * Resolves both the project root and (when applicable) the worktree root,
@@ -73,22 +106,23 @@ export function createWorkspace(rawBasePath: string): GsdWorkspace {
  * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
  * with path-returning closures for DB-authoritative project state.
  *
- * These scope paths intentionally route to contract.projectGsd. In-flight
- * markdown artifact readers outside this scope use the projection-aware
- * resolvers in paths.ts so worktree units can see worktree-local projections.
+ * DB paths route to contract.projectGsd. Milestone artifact paths resolve from
+ * the pinned project root with the layout-aware resolvers, so flat-phase and
+ * legacy projects use the same scope surface.
  */
 export function scopeMilestone(workspace: GsdWorkspace, milestoneId: string): MilestoneScope {
   const { contract } = workspace;
   const gsd = contract.projectGsd;
+  const basePath = workspace.projectRoot;
 
   const scope: MilestoneScope = Object.freeze({
     workspace,
     milestoneId,
-    contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
-    roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+    contextFile: () => scopeMilestoneFile(basePath, milestoneId, "CONTEXT"),
+    roadmapFile: () => scopeMilestoneFile(basePath, milestoneId, "ROADMAP"),
     stateFile: () => join(gsd, "STATE.md"),
     dbPath: () => contract.projectDb,
-    milestoneDir: () => join(gsd, "milestones", milestoneId),
+    milestoneDir: () => scopeMilestoneDir(basePath, milestoneId),
     metaJson: () => join(gsd, `${milestoneId}-META.json`),
   });
 

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

@@ -13,7 +13,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { loadPrompt } from "./prompt-loader.js";
 import { autoCommitCurrentBranch, getMainBranch, resolveGitHeadPath, nudgeGitBranchCache } from "./worktree.js";
-import { runWorktreePostCreateHook } from "./auto-worktree.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { showConfirm } from "../shared/tui.js";
 import { gsdRoot, milestonesDir, resolveGsdPathContract } from "./paths.js";
 import {

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";
@@ -66,19 +68,21 @@ import {
   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`.
+// 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,
-  createAutoWorktree,
-  enterAutoWorktree,
   enterBranchModeForMilestone,
-  getAutoWorktreePath,
+} from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import {
+  enterAutoWorktree,
   isInAutoWorktree,
-  teardownAutoWorktree,
-} from "./auto-worktree.js";
+} 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";
 import type { MilestoneMergeTransactionRunner } from "./milestone-merge-transaction.js";
 
@@ -153,11 +157,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 +242,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
@@ -252,7 +355,7 @@ export interface MergeContext {
   originalBasePath: string;
   /**
    * Current worktree path or project root when in branch mode. Used as the
-   * cwd anchor for `mergeMilestoneToMain` and the source for
+   * cwd anchor for the milestone merge transaction and the source for
    * `Projection.finalizeProjectionForMerge`.
    */
   worktreeBasePath: string;
@@ -280,7 +383,8 @@ export interface MergeStandaloneResult {
   pushed: boolean;
   /**
    * Commit message produced by the squash merge, if available. Forwarded
-   * from `mergeMilestoneToMain`. Only populated when `merged === true`.
+   * from the milestone merge transaction. Only populated when
+   * `merged === true`.
    */
   commitMessage?: string;
 }
@@ -1046,7 +1150,7 @@ function _mergeWorktreeModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       originalBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1213,7 +1317,7 @@ function _mergeBranchModeImpl(
       };
     }
 
-    const mergeResult = deps.mergeMilestoneToMain(
+    const mergeResult = deps.mergeMilestone(
       worktreeBasePath,
       milestoneId,
       roadmapResolution.content,
@@ -1272,8 +1376,9 @@ function _mergeBranchModeImpl(
  * **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
@@ -1374,8 +1479,8 @@ export function mergeMilestoneStandalone(
 
   // 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;
@@ -1444,18 +1549,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;
 }
 
 /**

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

@@ -8,7 +8,8 @@
 
 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";