gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.2e8b124f7

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

@@ -23,6 +23,7 @@ import { join } from "node:path";
 
 import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
 import { emitJournalEvent } from "./journal.js";
 import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
 import {
@@ -76,6 +77,13 @@ import {
   teardownAutoWorktree,
 } from "./auto-worktree.js";
 
+const recentWorktreeMergeFailures = new Map<string, number>();
+const MERGE_FAILURE_DEDUPE_MS = 60_000;
+
+export function resetRecentWorktreeMergeFailuresForTest(): void {
+  recentWorktreeMergeFailures.clear();
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────
 
 export interface NotifyCtx {
@@ -513,19 +521,9 @@ export function _enterMilestoneCore(
     };
   }
 
-  if (s.isolationDegraded) {
-    debugLog("WorktreeLifecycle", {
-      action: "enterMilestone",
-      milestoneId,
-      skipped: true,
-      reason: "isolation-degraded",
-    });
-    return { ok: false, reason: "isolation-degraded" };
-  }
-
   // Phase B: claim a milestone lease before any worktree mutation. Two
   // workers cannot enter the same milestone concurrently. Best-effort:
-  // skip if no worker registered (single-worker fallback) or DB
+  // warn if no worker registered (single-worker fallback) or skip if DB
   // unavailable; reuse existing lease if we already hold it on this
   // milestone (re-entry within the same session).
   if (s.workerId) {
@@ -618,6 +616,11 @@ export function _enterMilestoneCore(
         });
       }
     }
+  } else {
+    logWarning(
+      "worktree",
+      `enterMilestone(${milestoneId}) ran before auto worker registration; milestone lease was not claimed.`,
+    );
   }
 
   // Resolve the project root for worktree operations via shared helper.
@@ -626,6 +629,38 @@ export function _enterMilestoneCore(
   const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
   const mode = getIsolationMode(basePath);
 
+  if (s.isolationDegraded) {
+    if (mode === "worktree") {
+      try {
+        lifecycleEnterBranchMode(deps, basePath, milestoneId);
+        s.basePath = basePath;
+        rebuildGitService(s, deps);
+        invalidateAllCaches();
+        ctx.notify(
+          `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+          "warning",
+        );
+        return { ok: true, mode: "branch", path: basePath };
+      } catch (err) {
+        debugLog("WorktreeLifecycle", {
+          action: "enterMilestone",
+          milestoneId,
+          skipped: true,
+          reason: "isolation-degraded",
+          fallback: "branch-failed",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    debugLog("WorktreeLifecycle", {
+      action: "enterMilestone",
+      milestoneId,
+      skipped: true,
+      reason: "isolation-degraded",
+    });
+    return { ok: false, reason: "isolation-degraded" };
+  }
+
   if (mode === "none") {
     debugLog("WorktreeLifecycle", {
       action: "enterMilestone",
@@ -836,6 +871,32 @@ function rebuildGitService(
   s.gitService = deps.gitServiceFactory(s.basePath);
 }
 
+function emitWorktreeMergeFailedOnce(
+  basePath: string,
+  milestoneId: string,
+  err: unknown,
+): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  const errorCategory = err instanceof Error ? err.name : "Error";
+  const now = Date.now();
+  const key = `${basePath}\0${milestoneId}\0${errorCategory}`;
+  const previous = recentWorktreeMergeFailures.get(key);
+  if (previous && now - previous < MERGE_FAILURE_DEDUPE_MS) return;
+  for (const [candidate, ts] of recentWorktreeMergeFailures) {
+    if (now - ts >= MERGE_FAILURE_DEDUPE_MS) {
+      recentWorktreeMergeFailures.delete(candidate);
+    }
+  }
+  emitJournalEvent(basePath, {
+    ts: new Date().toISOString(),
+    flowId: randomUUID(),
+    seq: 0,
+    eventType: "worktree-merge-failed",
+    data: { milestoneId, error: msg },
+  });
+  recentWorktreeMergeFailures.set(key, now);
+}
+
 // ─── Session-less merge entry (ADR-016 phase 2 / A1) ─────────────────────
 
 /**
@@ -985,13 +1046,7 @@ function _mergeWorktreeModeImpl(
       error: msg,
       fallback: "chdir-to-project-root",
     });
-    emitJournalEvent(originalBasePath || worktreeBasePath, {
-      ts: new Date().toISOString(),
-      flowId: randomUUID(),
-      seq: 0,
-      eventType: "worktree-merge-failed",
-      data: { milestoneId, error: msg },
-    });
+    emitWorktreeMergeFailedOnce(originalBasePath || worktreeBasePath, milestoneId, err);
     // Surface a clear, actionable error. Worktree and milestone branch
     // are intentionally preserved — nothing has been deleted. User can
     // retry /gsd dispatch complete-milestone or merge manually once the
@@ -1702,16 +1757,34 @@ export class WorktreeLifecycle {
   }
 
   /**
-   * Restore `s.basePath` to `s.originalBasePath` and rebuild `s.gitService`.
-   * No-op when `originalBasePath` is empty (fresh sessions).
+   * Restore `s.basePath` to `s.originalBasePath`, chdir process cwd, and
+   * rebuild `s.gitService`. No-op when `originalBasePath` is empty (fresh
+   * sessions).
    *
    * Used by error/cleanup paths that need the session to behave as if the
    * worktree was never entered. Does NOT teardown the worktree directory —
    * callers that need teardown go through `exitMilestone({ merge: false })`.
+   *
+   * ADR-016 phase 3 (#5693): chdir lives inside the verb so callers do not
+   * pair `restoreToProjectRoot()` with a redundant `process.chdir`. The
+   * chdir runs BEFORE the throwable work (`rebuildGitService`, cache
+   * invalidation) so that cleanup-path cwd is restored even if the
+   * downstream rebuild throws. The chdir itself is best-effort; failure is
+   * logged via debugLog and swallowed.
    */
   restoreToProjectRoot(): void {
     if (!this.s.originalBasePath) return;
     this.s.basePath = this.s.originalBasePath;
+    try {
+      process.chdir(this.s.basePath);
+    } catch (err) {
+      debugLog("WorktreeLifecycle", {
+        action: "restoreToProjectRoot",
+        result: "chdir-failed",
+        basePath: this.s.basePath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
     rebuildGitService(this.s, this.deps);
     invalidateAllCaches();
   }

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

@@ -241,7 +241,19 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
     const gitFilePath = join(wtPath, ".git");
     if (!existsSync(gitFilePath)) {
       logWarning("reconcile", `Removing stale worktree directory (no .git file): ${wtPath}`, { worktree: name });
-      rmSync(wtPath, { recursive: true, force: true });
+      try {
+        rmSync(wtPath, { recursive: true, force: true });
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException)?.code;
+        if (code === "EPERM" || code === "EBUSY") {
+          throw new GSDError(
+            GSD_GIT_ERROR,
+            `Cannot remove stale worktree directory at ${wtPath} (${code}: directory may be locked by another process). Close editors/antivirus/git tools using this path and retry.`,
+            { cause: error as Error },
+          );
+        }
+        throw error;
+      }
     } else {
       throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${wtPath}`);
     }
@@ -618,7 +630,7 @@ export function removeWorktree(
       try {
         rmSync(nestedGitPath, { recursive: true, force: true });
         logWarning("reconcile",
-          `Removed nested .git directory from scaffolded project to prevent data loss (#2616)`,
+          `Removed nested .git directory from scaffolded project to prevent data loss`,
           { worktree: name, nestedRepo: nestedDir },
         );
       } catch {

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

@@ -2,6 +2,7 @@
 // File Purpose: Worktree Safety module contract for validating source-writing Unit roots.
 
 import { existsSync, lstatSync, type Stats } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join, resolve } from "node:path";
 
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
@@ -70,6 +71,7 @@ export interface WorktreeSafetyDeps {
   existsSync(path: string): boolean;
   lstatSync(path: string): Pick<Stats, "isFile">;
   listRegisteredWorktrees?(projectRoot: string): readonly RegisteredWorktree[];
+  pruneRegisteredWorktrees?(projectRoot: string): void;
   getCurrentBranch?(unitRoot: string): string;
 }
 
@@ -90,6 +92,12 @@ const defaultDeps: WorktreeSafetyDeps = {
       branch: worktree.branch,
     }));
   },
+  pruneRegisteredWorktrees(projectRoot) {
+    execFileSync("git", ["worktree", "prune"], {
+      cwd: projectRoot,
+      stdio: "pipe",
+    });
+  },
   getCurrentBranch,
 };
 
@@ -117,6 +125,8 @@ 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") {
@@ -208,12 +218,41 @@ export function createWorktreeSafetyModule(
         );
       }
       if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-        return failure(
-          "worktree-unregistered",
-          `Worktree root ${unitRoot} is not registered with git worktree list.`,
-          "Recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
-          { unitRoot },
-        );
+        const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
+        let attemptedPrune = false;
+
+        if (!wasPreviouslyTracked && 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}.`,
+              "Run 'git worktree prune', then recreate the milestone worktree before dispatching the source-writing Unit.",
+              { projectRoot, unitRoot, error: errorMessage(error) },
+            );
+          }
+        }
+
+        if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
+          return failure(
+            "worktree-unregistered",
+            `Worktree root ${unitRoot} is not registered with git worktree list.`,
+            attemptedPrune || wasPreviouslyTracked
+              ? "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) },
+          );
+        }
       }
 
       if (input.emptyWorktreeWithProjectContent) {

package/src/resources/extensions/gsd/worktree-state-projection.ts

@@ -123,6 +123,45 @@ function forceOverwriteAssessmentsWithVerdict(
   }
 }
 
+function syncTopLevelMilestoneArtifacts(
+  srcMilestonesDir: string,
+  dstMilestonesDir: string,
+): void {
+  if (!existsSync(srcMilestonesDir)) return;
+
+  try {
+    for (const milestoneEntry of readdirSync(srcMilestonesDir, { withFileTypes: true })) {
+      if (!milestoneEntry.isDirectory()) continue;
+      const srcMilestoneDir = join(srcMilestonesDir, milestoneEntry.name);
+      const dstMilestoneDir = join(dstMilestonesDir, milestoneEntry.name);
+
+      try {
+        mkdirSync(dstMilestoneDir, { recursive: true });
+        for (const fileEntry of readdirSync(srcMilestoneDir, { withFileTypes: true })) {
+          if (!fileEntry.isFile()) continue;
+          if (!fileEntry.name.endsWith(".md") && !fileEntry.name.endsWith(".json")) continue;
+
+          safeCopy(
+            join(srcMilestoneDir, fileEntry.name),
+            join(dstMilestoneDir, fileEntry.name),
+            { force: false },
+          );
+        }
+      } catch (err) {
+        logWarning(
+          "worktree",
+          `milestone top-level artifact sync failed (${milestoneEntry.name}): ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `milestone artifact scan failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 /**
  * Root-level .gsd/ files copied from worktree back to project root for
  * post-merge diagnostics. Markdown projections are NOT in this list — DB
@@ -176,6 +215,10 @@ export function _projectRootToWorktreeImpl(
     { force: false },
   );
 
+  // Additively project missing top-level milestone files for all milestones
+  // so worktree-bound units can verify future-milestone context artifacts.
+  syncTopLevelMilestoneArtifacts(join(prGsd, "milestones"), join(wtGsd, "milestones"));
+
   // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
   // The additive-only copy above preserves worktree-local files, but
   // ASSESSMENT files are special: after run-uat writes a verdict and post-unit