gsd-pi 2.33.1-dev.ee47f1b → 2.34.0-dev.bbb5216

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

@@ -0,0 +1,485 @@
+/**
+ * WorktreeResolver — encapsulates worktree path state and merge/exit lifecycle.
+ *
+ * Replaces scattered `s.basePath`/`s.originalBasePath` mutation and 3 duplicated
+ * merge-or-teardown blocks in auto-loop.ts with single method calls. All
+ * `s.basePath` mutations (except session.reset() and initial setup) happen
+ * through this class.
+ *
+ * Design: Option A — mutates AutoSession fields directly so existing `s.basePath`
+ * reads continue to work everywhere without wiring changes.
+ *
+ * Key invariant: `createAutoWorktree()` and `enterAutoWorktree()` call
+ * `process.chdir()` internally — this class MUST NOT double-chdir.
+ */
+
+import type { AutoSession } from "./auto/session.js";
+import { debugLog } from "./debug-logger.js";
+
+// ─── Dependency Interface ──────────────────────────────────────────────────
+
+export interface WorktreeResolverDeps {
+  isInAutoWorktree: (basePath: string) => boolean;
+  shouldUseWorktreeIsolation: () => boolean;
+  getIsolationMode: () => "worktree" | "branch" | "none";
+  mergeMilestoneToMain: (
+    basePath: string,
+    milestoneId: string,
+    roadmapContent: string,
+  ) => { pushed: boolean };
+  syncWorktreeStateBack: (
+    mainBasePath: string,
+    worktreePath: string,
+    milestoneId: string,
+  ) => { synced: string[] };
+  teardownAutoWorktree: (
+    basePath: string,
+    milestoneId: string,
+    opts?: { preserveBranch?: boolean },
+  ) => void;
+  createAutoWorktree: (basePath: string, milestoneId: string) => string;
+  enterAutoWorktree: (basePath: string, milestoneId: string) => string;
+  getAutoWorktreePath: (basePath: string, milestoneId: string) => string | null;
+  autoCommitCurrentBranch: (
+    basePath: string,
+    reason: string,
+    milestoneId: string,
+  ) => void;
+  getCurrentBranch: (basePath: string) => string;
+  autoWorktreeBranch: (milestoneId: string) => string;
+  resolveMilestoneFile: (
+    basePath: string,
+    milestoneId: string,
+    fileType: string,
+  ) => string | null;
+  readFileSync: (path: string, encoding: string) => string;
+  GitServiceImpl: new (basePath: string, gitConfig: unknown) => unknown;
+  loadEffectiveGSDPreferences: () =>
+    | { preferences?: { git?: Record<string, unknown> } }
+    | undefined;
+  invalidateAllCaches: () => void;
+  captureIntegrationBranch: (
+    basePath: string,
+    mid: string,
+    opts?: { commitDocs?: boolean },
+  ) => void;
+}
+
+// ─── Notify Context ────────────────────────────────────────────────────────
+
+export interface NotifyCtx {
+  notify: (
+    msg: string,
+    level?: "info" | "warning" | "error" | "success",
+  ) => void;
+}
+
+// ─── WorktreeResolver ──────────────────────────────────────────────────────
+
+export class WorktreeResolver {
+  private readonly s: AutoSession;
+  private readonly deps: WorktreeResolverDeps;
+
+  constructor(session: AutoSession, deps: WorktreeResolverDeps) {
+    this.s = session;
+    this.deps = deps;
+  }
+
+  // ── Getters ────────────────────────────────────────────────────────────
+
+  /** Current working path — may be worktree or project root. */
+  get workPath(): string {
+    return this.s.basePath;
+  }
+
+  /** Original project root — always the non-worktree path. */
+  get projectRoot(): string {
+    return 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;
+  }
+
+  // ── Private Helpers ────────────────────────────────────────────────────
+
+  private rebuildGitService(): void {
+    const gitConfig =
+      this.deps.loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+    this.s.gitService = new this.deps.GitServiceImpl(
+      this.s.basePath,
+      gitConfig,
+    ) as AutoSession["gitService"];
+  }
+
+  /** Restore basePath to originalBasePath and rebuild GitService. */
+  private restoreToProjectRoot(): void {
+    if (!this.s.originalBasePath) return;
+    this.s.basePath = this.s.originalBasePath;
+    this.rebuildGitService();
+    this.deps.invalidateAllCaches();
+  }
+
+  // ── Validation ──────────────────────────────────────────────────────────
+
+  /** Validate milestoneId to prevent path traversal. */
+  private validateMilestoneId(milestoneId: string): void {
+    if (/[\/\\]|\.\./.test(milestoneId)) {
+      throw new Error(
+        `Invalid milestoneId: ${milestoneId} — contains path separators or traversal`,
+      );
+    }
+  }
+
+  // ── Enter Milestone ────────────────────────────────────────────────────
+
+  /**
+   * Enter or create a worktree for the given milestone.
+   *
+   * Only acts if `shouldUseWorktreeIsolation()` returns true.
+   * Delegates to `enterAutoWorktree` (existing) or `createAutoWorktree` (new).
+   * Those functions call `process.chdir()` internally — we do NOT double-chdir.
+   *
+   * Updates `s.basePath` and rebuilds GitService on success.
+   * On failure: notifies a warning and does NOT update `s.basePath`.
+   */
+  enterMilestone(milestoneId: string, ctx: NotifyCtx): void {
+    this.validateMilestoneId(milestoneId);
+    if (!this.deps.shouldUseWorktreeIsolation()) {
+      debugLog("WorktreeResolver", {
+        action: "enterMilestone",
+        milestoneId,
+        skipped: true,
+        reason: "isolation-disabled",
+      });
+      return;
+    }
+
+    const basePath = this.s.originalBasePath || this.s.basePath;
+    debugLog("WorktreeResolver", {
+      action: "enterMilestone",
+      milestoneId,
+      basePath,
+    });
+
+    try {
+      const existingPath = this.deps.getAutoWorktreePath(basePath, milestoneId);
+      let wtPath: string;
+
+      if (existingPath) {
+        wtPath = this.deps.enterAutoWorktree(basePath, milestoneId);
+      } else {
+        wtPath = this.deps.createAutoWorktree(basePath, milestoneId);
+      }
+
+      this.s.basePath = wtPath;
+      this.rebuildGitService();
+
+      debugLog("WorktreeResolver", {
+        action: "enterMilestone",
+        milestoneId,
+        result: "success",
+        wtPath,
+      });
+      ctx.notify(`Entered worktree for ${milestoneId} at ${wtPath}`, "info");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      debugLog("WorktreeResolver", {
+        action: "enterMilestone",
+        milestoneId,
+        result: "error",
+        error: msg,
+      });
+      ctx.notify(
+        `Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`,
+        "warning",
+      );
+      // Do NOT update s.basePath — stay in project root
+    }
+  }
+
+  // ── Exit Milestone ─────────────────────────────────────────────────────
+
+  /**
+   * Exit the current worktree: auto-commit, teardown, reset basePath.
+   *
+   * Only acts if currently in an auto-worktree (checked via `isInAutoWorktree`).
+   * Resets `s.basePath` to `s.originalBasePath` and rebuilds GitService.
+   */
+  exitMilestone(
+    milestoneId: string,
+    ctx: NotifyCtx,
+    opts?: { preserveBranch?: boolean },
+  ): void {
+    this.validateMilestoneId(milestoneId);
+    if (!this.deps.isInAutoWorktree(this.s.basePath)) {
+      debugLog("WorktreeResolver", {
+        action: "exitMilestone",
+        milestoneId,
+        skipped: true,
+        reason: "not-in-worktree",
+      });
+      return;
+    }
+
+    debugLog("WorktreeResolver", {
+      action: "exitMilestone",
+      milestoneId,
+      basePath: this.s.basePath,
+    });
+
+    try {
+      this.deps.autoCommitCurrentBranch(this.s.basePath, "stop", milestoneId);
+    } catch (err) {
+      debugLog("WorktreeResolver", {
+        action: "exitMilestone",
+        milestoneId,
+        phase: "auto-commit-failed",
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    try {
+      this.deps.teardownAutoWorktree(this.s.originalBasePath, milestoneId, {
+        preserveBranch: opts?.preserveBranch ?? false,
+      });
+    } catch (err) {
+      debugLog("WorktreeResolver", {
+        action: "exitMilestone",
+        milestoneId,
+        phase: "teardown-failed",
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    this.restoreToProjectRoot();
+    debugLog("WorktreeResolver", {
+      action: "exitMilestone",
+      milestoneId,
+      result: "done",
+      basePath: this.s.basePath,
+    });
+    ctx.notify(`Exited worktree for ${milestoneId}`, "info");
+  }
+
+  // ── Merge and Exit ─────────────────────────────────────────────────────
+
+  /**
+   * Merge the completed milestone branch back to main and exit the worktree.
+   *
+   * Handles all three isolation modes:
+   * - **worktree**: Read roadmap, merge, teardown worktree, reset paths.
+   *   Falls back to bare teardown if no roadmap exists.
+   * - **branch**: Check if on milestone branch, merge if so (no chdir/teardown).
+   * - **none**: No-op.
+   *
+   * Error recovery: on merge failure, always restore `s.basePath` to
+   * `s.originalBasePath` and `process.chdir(s.originalBasePath)`.
+   */
+  mergeAndExit(milestoneId: string, ctx: NotifyCtx): void {
+    this.validateMilestoneId(milestoneId);
+    const mode = this.deps.getIsolationMode();
+    debugLog("WorktreeResolver", {
+      action: "mergeAndExit",
+      milestoneId,
+      mode,
+      basePath: this.s.basePath,
+    });
+
+    if (mode === "none") {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        skipped: true,
+        reason: "mode-none",
+      });
+      return;
+    }
+
+    if (
+      mode === "worktree" ||
+      (this.deps.isInAutoWorktree(this.s.basePath) && this.s.originalBasePath)
+    ) {
+      this._mergeWorktreeMode(milestoneId, ctx);
+    } else if (mode === "branch") {
+      this._mergeBranchMode(milestoneId, ctx);
+    }
+  }
+
+  /** Worktree-mode merge: read roadmap, merge, teardown, reset paths. */
+  private _mergeWorktreeMode(milestoneId: string, ctx: NotifyCtx): void {
+    const originalBase = this.s.originalBasePath;
+    if (!originalBase) {
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        mode: "worktree",
+        skipped: true,
+        reason: "missing-original-base",
+      });
+      return;
+    }
+
+    try {
+      const { synced } = this.deps.syncWorktreeStateBack(
+        originalBase,
+        this.s.basePath,
+        milestoneId,
+      );
+      if (synced.length > 0) {
+        debugLog("WorktreeResolver", {
+          action: "mergeAndExit",
+          milestoneId,
+          phase: "reverse-sync",
+          synced: synced.length,
+        });
+      }
+
+      const roadmapPath = this.deps.resolveMilestoneFile(
+        originalBase,
+        milestoneId,
+        "ROADMAP",
+      );
+
+      if (roadmapPath) {
+        const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
+        const mergeResult = this.deps.mergeMilestoneToMain(
+          originalBase,
+          milestoneId,
+          roadmapContent,
+        );
+        ctx.notify(
+          `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
+          "info",
+        );
+      } else {
+        // No roadmap — fall back to bare teardown
+        this.deps.teardownAutoWorktree(originalBase, milestoneId);
+        ctx.notify(
+          `Exited worktree for ${milestoneId} (no roadmap for merge).`,
+          "info",
+        );
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        result: "error",
+        error: msg,
+        fallback: "chdir-to-project-root",
+      });
+      ctx.notify(`Milestone merge failed: ${msg}`, "warning");
+
+      // Error recovery: always restore to project root
+      if (originalBase) {
+        try {
+          process.chdir(originalBase);
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+
+    // Always restore basePath and rebuild — whether merge succeeded or failed
+    this.restoreToProjectRoot();
+    debugLog("WorktreeResolver", {
+      action: "mergeAndExit",
+      milestoneId,
+      result: "done",
+      basePath: this.s.basePath,
+    });
+  }
+
+  /** Branch-mode merge: check current branch, merge if on milestone branch. */
+  private _mergeBranchMode(milestoneId: string, ctx: NotifyCtx): void {
+    try {
+      const currentBranch = this.deps.getCurrentBranch(this.s.basePath);
+      const milestoneBranch = this.deps.autoWorktreeBranch(milestoneId);
+
+      if (currentBranch !== milestoneBranch) {
+        debugLog("WorktreeResolver", {
+          action: "mergeAndExit",
+          milestoneId,
+          mode: "branch",
+          skipped: true,
+          reason: "not-on-milestone-branch",
+          currentBranch,
+          milestoneBranch,
+        });
+        return;
+      }
+
+      const roadmapPath = this.deps.resolveMilestoneFile(
+        this.s.basePath,
+        milestoneId,
+        "ROADMAP",
+      );
+      if (!roadmapPath) {
+        debugLog("WorktreeResolver", {
+          action: "mergeAndExit",
+          milestoneId,
+          mode: "branch",
+          skipped: true,
+          reason: "no-roadmap",
+        });
+        return;
+      }
+
+      const roadmapContent = this.deps.readFileSync(roadmapPath, "utf-8");
+      const mergeResult = this.deps.mergeMilestoneToMain(
+        this.s.basePath,
+        milestoneId,
+        roadmapContent,
+      );
+
+      // Rebuild GitService after merge (branch HEAD changed)
+      this.rebuildGitService();
+
+      ctx.notify(
+        `Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
+        "info",
+      );
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        mode: "branch",
+        result: "success",
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      debugLog("WorktreeResolver", {
+        action: "mergeAndExit",
+        milestoneId,
+        mode: "branch",
+        result: "error",
+        error: msg,
+      });
+      ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+    }
+  }
+
+  // ── Merge and Enter Next ───────────────────────────────────────────────
+
+  /**
+   * Milestone transition: merge the current milestone, then enter the next one.
+   *
+   * This is the pattern used when the loop detects that the active milestone
+   * has changed (e.g., current completed, next one is now active). The caller
+   * is responsible for re-deriving state between the merge and the enter.
+   */
+  mergeAndEnterNext(
+    currentMilestoneId: string,
+    nextMilestoneId: string,
+    ctx: NotifyCtx,
+  ): void {
+    debugLog("WorktreeResolver", {
+      action: "mergeAndEnterNext",
+      currentMilestoneId,
+      nextMilestoneId,
+    });
+    this.mergeAndExit(currentMilestoneId, ctx);
+    this.enterMilestone(nextMilestoneId, ctx);
+  }
+}

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

@@ -12,7 +12,7 @@
  * SLICE_BRANCH_RE) remain for backwards compatibility with legacy branches.
  */
 
-import { existsSync, lstatSync, readFileSync, utimesSync } from "node:fs";
+import { existsSync, readFileSync, utimesSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 
 import { GitServiceImpl, writeIntegrationBranch, type TaskCommitContext } from "./git-service.js";
@@ -56,13 +56,13 @@ export function setActiveMilestoneId(basePath: string, milestoneId: string | nul
  * record when the user starts from a different branch (#300). Always a no-op
  * if on a GSD slice branch.
  */
-export function captureIntegrationBranch(basePath: string, milestoneId: string): void {
+export function captureIntegrationBranch(basePath: string, milestoneId: string, options?: { commitDocs?: boolean }): void {
   // In a worktree, the base branch is implicit (worktree/<name>).
   // Writing it to META.json would leave stale metadata after merge back to main.
   if (detectWorktreeName(basePath)) return;
   const svc = getService(basePath);
   const current = svc.getCurrentBranch();
-  writeIntegrationBranch(basePath, milestoneId, current);
+  writeIntegrationBranch(basePath, milestoneId, current, options);
 }
 
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
@@ -72,25 +72,6 @@ export function captureIntegrationBranch(basePath: string, milestoneId: string):
  * Returns null if not inside a GSD worktree (.gsd/worktrees/<name>/).
  */
 export function detectWorktreeName(basePath: string): string | null {
-  // Primary: use git metadata — .git file with gitdir: pointer
-  const gitPath = join(basePath, ".git");
-  try {
-    const stat = lstatSync(gitPath);
-    if (stat.isFile()) {
-      const content = readFileSync(gitPath, "utf-8").trim();
-      if (content.startsWith("gitdir:")) {
-        const gitdir = content.slice(7).trim();
-        // Git worktree gitdir format: <repo>/.git/worktrees/<name>
-        const parts = gitdir.replace(/\\/g, "/").split("/");
-        const wtIdx = parts.lastIndexOf("worktrees");
-        if (wtIdx !== -1 && wtIdx < parts.length - 1) {
-          return parts[wtIdx + 1] || null;
-        }
-      }
-    }
-  } catch { /* fall through */ }
-
-  // Fallback: path-based detection for legacy setups
   const normalizedPath = basePath.replaceAll("\\", "/");
   const marker = "/.gsd/worktrees/";
   const idx = normalizedPath.indexOf(marker);
@@ -109,32 +90,14 @@ export function detectWorktreeName(basePath: string): string | null {
  * operate against the real project root, not a worktree subdirectory.
  */
 export function resolveProjectRoot(basePath: string): string {
-  // Primary: use git metadata to resolve the main worktree root
-  const gitPath = join(basePath, ".git");
-  try {
-    const stat = lstatSync(gitPath);
-    if (stat.isFile()) {
-      const content = readFileSync(gitPath, "utf-8").trim();
-      if (content.startsWith("gitdir:")) {
-        const gitdir = resolve(basePath, content.slice(7).trim());
-        // Git worktree gitdir: <repo>/.git/worktrees/<name>
-        // Walk up to <repo>
-        const parts = gitdir.replace(/\\/g, "/").split("/");
-        const wtIdx = parts.lastIndexOf("worktrees");
-        if (wtIdx >= 2 && parts[wtIdx - 1] === ".git") {
-          return parts.slice(0, wtIdx - 1).join("/");
-        }
-      }
-    }
-  } catch { /* fall through */ }
-
-  // Fallback: legacy path-based detection
   const normalizedPath = basePath.replaceAll("\\", "/");
   const marker = "/.gsd/worktrees/";
   const idx = normalizedPath.indexOf(marker);
   if (idx === -1) return basePath;
-  const osSep = basePath.includes("\\") ? "\\" : "/";
-  const markerOs = `${osSep}.gsd${osSep}worktrees${osSep}`;
+  // Return the original path up to the .gsd/ marker (un-normalized)
+  // Account for potential OS-specific separators
+  const sep = basePath.includes("\\") ? "\\" : "/";
+  const markerOs = `${sep}.gsd${sep}worktrees${sep}`;
   const idxOs = basePath.indexOf(markerOs);
   if (idxOs !== -1) return basePath.slice(0, idxOs);
   return basePath.slice(0, idx);

package/dist/resources/extensions/gsd/auto-constants.js

@@ -1,5 +0,0 @@
-/**
- * Shared constants for auto-mode modules (auto.ts, auto-post-unit.ts, etc.).
- */
-/** Throttle STATE.md rebuilds — at most once per 30 seconds. */
-export const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;

package/dist/resources/extensions/gsd/auto-idempotency.js

@@ -1,106 +0,0 @@
-/**
- * Idempotency checks for auto-mode unit dispatch.
- *
- * Handles completed-key membership, artifact cross-validation,
- * consecutive skip counting, phantom skip loop detection, key eviction,
- * and fallback persistence.
- *
- * Extracted from dispatchNextUnit() in auto.ts. Pure decision logic
- * with set mutations — does NOT call dispatchNextUnit or stopAuto.
- */
-import { invalidateAllCaches } from "./cache.js";
-import { verifyExpectedArtifact, persistCompletedKey, removePersistedKey, } from "./auto-recovery.js";
-import { resolveMilestoneFile } from "./paths.js";
-import { MAX_CONSECUTIVE_SKIPS, MAX_LIFETIME_DISPATCHES } from "./auto/session.js";
-import { parseUnitId } from "./unit-id.js";
-/**
- * Check whether a unit should be skipped (already completed), rerun
- * (stale completion record), or dispatched normally.
- *
- * Mutates s.completedKeySet, s.unitConsecutiveSkips, s.unitLifetimeDispatches,
- * and s.recentlyEvictedKeys as needed.
- */
-export function checkIdempotency(ictx) {
-    const { s, unitType, unitId, basePath, notify } = ictx;
-    const idempotencyKey = `${unitType}/${unitId}`;
-    // ── Primary path: key exists in completed set ──
-    if (s.completedKeySet.has(idempotencyKey)) {
-        const artifactExists = verifyExpectedArtifact(unitType, unitId, basePath);
-        if (artifactExists) {
-            // Guard against infinite skip loops
-            const skipCount = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
-            s.unitConsecutiveSkips.set(idempotencyKey, skipCount);
-            if (skipCount > MAX_CONSECUTIVE_SKIPS) {
-                // Cross-check: verify the unit's milestone is still active (#790)
-                const skippedMid = parseUnitId(unitId).milestone;
-                const skippedMilestoneComplete = skippedMid
-                    ? !!resolveMilestoneFile(basePath, skippedMid, "SUMMARY")
-                    : false;
-                if (skippedMilestoneComplete) {
-                    s.unitConsecutiveSkips.delete(idempotencyKey);
-                    invalidateAllCaches();
-                    notify(`Phantom skip loop cleared: ${unitType} ${unitId} belongs to completed milestone ${skippedMid}. Re-dispatching from fresh state.`, "info");
-                    return { action: "skip", reason: "phantom-loop-cleared" };
-                }
-                s.unitConsecutiveSkips.delete(idempotencyKey);
-                s.completedKeySet.delete(idempotencyKey);
-                s.recentlyEvictedKeys.add(idempotencyKey);
-                removePersistedKey(basePath, idempotencyKey);
-                invalidateAllCaches();
-                notify(`Skip loop detected: ${unitType} ${unitId} skipped ${skipCount} times without advancing. Evicting completion record and forcing reconciliation.`, "warning");
-                return { action: "skip", reason: "evicted" };
-            }
-            // Count toward lifetime cap
-            const lifeSkip = (s.unitLifetimeDispatches.get(idempotencyKey) ?? 0) + 1;
-            s.unitLifetimeDispatches.set(idempotencyKey, lifeSkip);
-            if (lifeSkip > MAX_LIFETIME_DISPATCHES) {
-                return { action: "stop", reason: `Hard loop: ${unitType} ${unitId} (skip cycle)` };
-            }
-            notify(`Skipping ${unitType} ${unitId} — already completed in a prior session. Advancing.`, "info");
-            return { action: "skip", reason: "completed" };
-        }
-        else {
-            // Stale completion record — artifact missing. Remove and re-run.
-            s.completedKeySet.delete(idempotencyKey);
-            removePersistedKey(basePath, idempotencyKey);
-            notify(`Re-running ${unitType} ${unitId} — marked complete but expected artifact missing.`, "warning");
-            return { action: "rerun", reason: "stale-key" };
-        }
-    }
-    // ── Fallback: key missing but artifact exists ──
-    if (verifyExpectedArtifact(unitType, unitId, basePath) && !s.recentlyEvictedKeys.has(idempotencyKey)) {
-        persistCompletedKey(basePath, idempotencyKey);
-        s.completedKeySet.add(idempotencyKey);
-        invalidateAllCaches();
-        // Same consecutive-skip guard as the primary path
-        const skipCount2 = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
-        s.unitConsecutiveSkips.set(idempotencyKey, skipCount2);
-        if (skipCount2 > MAX_CONSECUTIVE_SKIPS) {
-            const skippedMid2 = parseUnitId(unitId).milestone;
-            const skippedMilestoneComplete2 = skippedMid2
-                ? !!resolveMilestoneFile(basePath, skippedMid2, "SUMMARY")
-                : false;
-            if (skippedMilestoneComplete2) {
-                s.unitConsecutiveSkips.delete(idempotencyKey);
-                invalidateAllCaches();
-                notify(`Phantom skip loop cleared: ${unitType} ${unitId} belongs to completed milestone ${skippedMid2}. Re-dispatching from fresh state.`, "info");
-                return { action: "skip", reason: "phantom-loop-cleared" };
-            }
-            s.unitConsecutiveSkips.delete(idempotencyKey);
-            s.completedKeySet.delete(idempotencyKey);
-            removePersistedKey(basePath, idempotencyKey);
-            invalidateAllCaches();
-            notify(`Skip loop detected: ${unitType} ${unitId} skipped ${skipCount2} times without advancing. Evicting completion record and forcing reconciliation.`, "warning");
-            return { action: "skip", reason: "evicted" };
-        }
-        // Count toward lifetime cap
-        const lifeSkip2 = (s.unitLifetimeDispatches.get(idempotencyKey) ?? 0) + 1;
-        s.unitLifetimeDispatches.set(idempotencyKey, lifeSkip2);
-        if (lifeSkip2 > MAX_LIFETIME_DISPATCHES) {
-            return { action: "stop", reason: `Hard loop: ${unitType} ${unitId} (skip cycle)` };
-        }
-        notify(`Skipping ${unitType} ${unitId} — artifact exists but completion key was missing. Repaired and advancing.`, "info");
-        return { action: "skip", reason: "fallback-persisted" };
-    }
-    return { action: "proceed" };
-}