gsd-pi 2.11.0 → 2.13.0

package/dist/resources/extensions/gsd/auto.ts

@@ -18,17 +18,18 @@ import type {
 
 import { deriveState, invalidateStateCache } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus } from "./files.js";
+import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus, clearParseCache } from "./files.js";
 export { inlinePriorMilestoneSummary };
 import type { UatType } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
-import { loadPrompt } from "./prompt-loader.js";
+import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
   resolveMilestonePath, resolveDir, resolveTasksDir, resolveTaskFiles, resolveTaskFile,
   relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relMilestonePath,
   milestonesDir, resolveGsdRootFile, relGsdRootFile,
   buildMilestoneFileName, buildSliceFileName, buildTaskFileName,
+  clearPathCache,
 } from "./paths.js";
 import { saveActivityLog } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
@@ -42,6 +43,18 @@ import {
 } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, resolveModelForUnit, resolveModelWithFallbacksForUnit, resolveSkillDiscoveryMode, loadEffectiveGSDPreferences } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
+import {
+  checkPostUnitHooks,
+  getActiveHook,
+  resetHookState,
+  isRetryPending,
+  consumeRetryTrigger,
+  runPreDispatchHooks,
+  persistHookState,
+  restoreHookState,
+  clearPersistedHookState,
+  formatHookStatus,
+} from "./post-unit-hooks.js";
 import {
   validatePlanBoundary,
   validateExecuteBoundary,
@@ -73,6 +86,19 @@ import {
 import { GitServiceImpl, runGit } from "./git-service.js";
 import { nativeCommitCountBetween } from "./native-git-bridge.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
+import { formatGitError } from "./git-self-heal.js";
+import {
+  createAutoWorktree,
+  enterAutoWorktree,
+  teardownAutoWorktree,
+  isInAutoWorktree,
+  getAutoWorktreePath,
+  getAutoWorktreeOriginalBase,
+  mergeSliceToMilestone,
+  mergeMilestoneToMain,
+  shouldUseWorktreeIsolation,
+  getMergeToMainMode,
+} from "./auto-worktree.js";
 import type { GitPreferences } from "./git-service.js";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/ui.js";
@@ -131,6 +157,7 @@ let stepMode = false;
 let verbose = false;
 let cmdCtx: ExtensionCommandContext | null = null;
 let basePath = "";
+let originalBasePath = "";
 let gitService: GitServiceImpl | null = null;
 
 /** Track total dispatches per unit to detect stuck loops (catches A→B→A→B patterns) */
@@ -138,6 +165,12 @@ const unitDispatchCount = new Map<string, number>();
 const MAX_UNIT_DISPATCHES = 3;
 /** Retry index at which a stub summary placeholder is written when the summary is still absent. */
 const STUB_RECOVERY_THRESHOLD = 2;
+/** Hard cap on total dispatches per unit across ALL reconciliation cycles.
+ *  unitDispatchCount can be reset by loop-recovery/self-repair paths, but this
+ *  counter is never reset — it catches infinite reconciliation loops where
+ *  artifacts exist but deriveState keeps returning the same unit. */
+const unitLifetimeDispatches = new Map<string, number>();
+const MAX_LIFETIME_DISPATCHES = 6;
 
 /** Tracks recovery attempt count per unit for backoff and diagnostics. */
 const unitRecoveryCount = new Map<string, number>();
@@ -330,6 +363,27 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
 
   // Remove SIGTERM handler registered at auto-mode start
   deregisterSigtermHandler();
+
+  // ── Auto-worktree: exit worktree and reset basePath on stop ──
+  if (currentMilestoneId && isInAutoWorktree(basePath)) {
+    try {
+      teardownAutoWorktree(originalBasePath, currentMilestoneId);
+      basePath = originalBasePath;
+      gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+      ctx?.ui.notify("Exited auto-worktree.", "info");
+    } catch (err) {
+      ctx?.ui.notify(
+        `Auto-worktree teardown failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+      // Force basePath back to original even if teardown failed
+      if (originalBasePath) {
+        basePath = originalBasePath;
+        try { process.chdir(basePath); } catch { /* best-effort */ }
+      }
+    }
+  }
+
   const ledger = getLedger();
   if (ledger && ledger.units.length > 0) {
     const totals = getProjectTotals(ledger.units);
@@ -347,13 +401,17 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   }
 
   resetMetrics();
+  resetHookState();
+  if (basePath) clearPersistedHookState(basePath);
   active = false;
   paused = false;
   stepMode = false;
   unitDispatchCount.clear();
   unitRecoveryCount.clear();
+  unitLifetimeDispatches.clear();
   currentUnit = null;
   currentMilestoneId = null;
+  originalBasePath = "";
   cachedSliceProgress = null;
   pendingCrashRecovery = null;
   _handlingAgentEnd = false;
@@ -503,10 +561,17 @@ async function mergeOrphanedSliceBranches(
       "info",
     );
     try {
-      switchToMain(base);
-      const mergeResult = mergeSliceToMain(
-        base, milestoneId, sliceId, sliceEntry.title || sliceId,
-      );
+      let mergeResult;
+      if (isInAutoWorktree(base) && getMergeToMainMode() !== "slice") {
+        mergeResult = mergeSliceToMilestone(
+          base, milestoneId, sliceId, sliceEntry.title || sliceId,
+        );
+      } else {
+        switchToMain(base);
+        mergeResult = mergeSliceToMain(
+          base, milestoneId, sliceId, sliceEntry.title || sliceId,
+        );
+      }
       ctx.ui.notify(
         `Merged orphaned branch ${mergeResult.branch} → ${mainBranch}.`,
         "info",
@@ -553,17 +618,44 @@ export async function startAuto(
     cmdCtx = ctx;
     basePath = base;
     unitDispatchCount.clear();
+    unitLifetimeDispatches.clear();
     // Re-initialize metrics in case ledger was lost during pause
     if (!getLedger()) initMetrics(base);
     // Ensure milestone ID is set on git service for integration branch resolution
     if (currentMilestoneId) setActiveMilestoneId(base, currentMilestoneId);
 
+    // ── Auto-worktree: re-enter worktree on resume if not already inside ──
+    if (currentMilestoneId && originalBasePath && !isInAutoWorktree(basePath) && shouldUseWorktreeIsolation(originalBasePath)) {
+      try {
+        const existingWtPath = getAutoWorktreePath(originalBasePath, currentMilestoneId);
+        if (existingWtPath) {
+          const wtPath = enterAutoWorktree(originalBasePath, currentMilestoneId);
+          basePath = wtPath;
+          gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          ctx.ui.notify(`Re-entered auto-worktree at ${wtPath}`, "info");
+        } else {
+          // Worktree was deleted while paused — recreate it.
+          const wtPath = createAutoWorktree(originalBasePath, currentMilestoneId);
+          basePath = wtPath;
+          gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          ctx.ui.notify(`Recreated auto-worktree at ${wtPath}`, "info");
+        }
+      } catch (err) {
+        ctx.ui.notify(
+          `Auto-worktree re-entry failed: ${err instanceof Error ? err.message : String(err)}. Continuing at current path.`,
+          "warning",
+        );
+      }
+    }
+
     // Re-register SIGTERM handler for the resumed session
-    registerSigtermHandler(base);
+    registerSigtermHandler(basePath);
 
     ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
     ctx.ui.setFooter(hideFooter);
     ctx.ui.notify(stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
+    // Restore hook state from disk in case session was interrupted
+    restoreHookState(base);
     // Rebuild disk state before resuming — user interaction during pause may have changed files
     try { await rebuildState(base); } catch { /* non-fatal */ }
     try {
@@ -575,6 +667,8 @@ export async function startAuto(
     // Self-heal: clear stale runtime records where artifacts already exist
     await selfHealRuntimeRecords(base, ctx);
     invalidateStateCache();
+    clearParseCache();
+    clearPathCache();
     await dispatchNextUnit(ctx, pi);
     return;
   }
@@ -668,8 +762,11 @@ export async function startAuto(
   basePath = base;
   unitDispatchCount.clear();
   unitRecoveryCount.clear();
+  unitLifetimeDispatches.clear();
   completedKeySet.clear();
   loadPersistedKeys(base, completedKeySet);
+  resetHookState();
+  restoreHookState(base);
   autoStartTime = Date.now();
   completedUnits = [];
   currentUnit = null;
@@ -689,6 +786,36 @@ export async function startAuto(
     setActiveMilestoneId(base, currentMilestoneId);
   }
 
+  // ── Auto-worktree: create or enter worktree for the active milestone ──
+  // Store the original project root before any chdir so we can restore on stop.
+  originalBasePath = base;
+  if (currentMilestoneId && shouldUseWorktreeIsolation(base)) {
+    try {
+      const existingWtPath = getAutoWorktreePath(base, currentMilestoneId);
+      if (existingWtPath) {
+        // Worktree already exists (e.g., previous session created it) — enter it.
+        const wtPath = enterAutoWorktree(base, currentMilestoneId);
+        basePath = wtPath;
+        gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        ctx.ui.notify(`Entered auto-worktree at ${wtPath}`, "info");
+      } else {
+        // Fresh start — create worktree and enter it.
+        const wtPath = createAutoWorktree(base, currentMilestoneId);
+        basePath = wtPath;
+        gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        ctx.ui.notify(`Created auto-worktree at ${wtPath}`, "info");
+      }
+      // Re-register SIGTERM handler with the new basePath
+      registerSigtermHandler(basePath);
+    } catch (err) {
+      // Worktree creation is non-fatal — continue in the project root.
+      ctx.ui.notify(
+        `Auto-worktree setup failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
+        "warning",
+      );
+    }
+  }
+
   // Initialize metrics — loads existing ledger from disk
   initMetrics(base);
 
@@ -767,6 +894,8 @@ export async function handleAgentEnd(
   // Invalidate deriveState() cache — the unit just completed and may have
   // written planning files (task summaries, roadmap checkboxes, etc.)
   invalidateStateCache();
+  clearParseCache();
+  clearPathCache();
 
   // Small delay to let files settle (git commits, file writes)
   await new Promise(r => setTimeout(r, 500));
@@ -804,6 +933,97 @@ export async function handleAgentEnd(
     } catch {
       // Non-fatal
     }
+
+    // ── Path A fix: verify artifact and persist completion before re-entering dispatch ──
+    // After doctor + rebuildState, check whether the just-completed unit actually
+    // produced its expected artifact. If so, persist the completion key now so the
+    // idempotency check at the top of dispatchNextUnit() skips it — even if
+    // deriveState() still returns this unit as active (e.g. branch mismatch).
+    try {
+      if (verifyExpectedArtifact(currentUnit.type, currentUnit.id, basePath)) {
+        const completionKey = `${currentUnit.type}/${currentUnit.id}`;
+        if (!completedKeySet.has(completionKey)) {
+          persistCompletedKey(basePath, completionKey);
+          completedKeySet.add(completionKey);
+        }
+        invalidateStateCache();
+      }
+    } catch {
+      // Non-fatal — worst case we fall through to normal dispatch which has its own checks
+    }
+  }
+
+  // ── Post-unit hooks: check if a configured hook should run before normal dispatch ──
+  if (currentUnit && !stepMode) {
+    const hookUnit = checkPostUnitHooks(currentUnit.type, currentUnit.id, basePath);
+    if (hookUnit) {
+      // Dispatch the hook unit instead of normal flow
+      const hookStartedAt = Date.now();
+      if (currentUnit) {
+        const modelId = ctx.model?.id ?? "unknown";
+        snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+        saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
+      }
+      currentUnit = { type: hookUnit.unitType, id: hookUnit.unitId, startedAt: hookStartedAt };
+      writeUnitRuntimeRecord(basePath, hookUnit.unitType, hookUnit.unitId, hookStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: hookStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+      });
+
+      const state = await deriveState(basePath);
+      updateProgressWidget(ctx, hookUnit.unitType, hookUnit.unitId, state);
+      const hookState = getActiveHook();
+      ctx.ui.notify(
+        `Running post-unit hook: ${hookUnit.hookName} (cycle ${hookState?.cycle ?? 1})`,
+        "info",
+      );
+
+      // Switch model if the hook specifies one
+      if (hookUnit.model) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const match = availableModels.find(m =>
+          m.id === hookUnit.model || `${m.provider}/${m.id}` === hookUnit.model,
+        );
+        if (match) {
+          try {
+            await pi.setModel(match);
+          } catch { /* non-fatal — use current model */ }
+        }
+      }
+
+      const result = await cmdCtx!.newSession();
+      if (result.cancelled) {
+        resetHookState();
+        await stopAuto(ctx, pi);
+        return;
+      }
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      writeLock(basePath, hookUnit.unitType, hookUnit.unitId, completedUnits.length, sessionFile);
+      // Persist hook state so cycle counts survive crashes
+      persistHookState(basePath);
+      pi.sendMessage(
+        { customType: "gsd-auto", content: hookUnit.prompt, display: verbose },
+        { triggerTurn: true },
+      );
+      return; // handleAgentEnd will fire again when hook session completes
+    }
+
+    // Check if a hook requested a retry of the trigger unit
+    if (isRetryPending()) {
+      const trigger = consumeRetryTrigger();
+      if (trigger) {
+        ctx.ui.notify(
+          `Hook requested retry of ${trigger.unitType} ${trigger.unitId}.`,
+          "info",
+        );
+        // Fall through to normal dispatchNextUnit — state derivation will
+        // re-select the same unit since it hasn't been marked complete
+      }
+    }
   }
 
   // In step mode, pause and show a wizard instead of immediately dispatching
@@ -949,6 +1169,7 @@ export function describeNextUnit(state: GSDState): { label: string; description:
 // ─── Progress Widget ──────────────────────────────────────────────────────
 
 function unitVerb(unitType: string): string {
+  if (unitType.startsWith("hook/")) return `hook: ${unitType.slice(5)}`;
   switch (unitType) {
     case "research-milestone":
     case "research-slice": return "researching";
@@ -965,6 +1186,7 @@ function unitVerb(unitType: string): string {
 }
 
 function unitPhaseLabel(unitType: string): string {
+  if (unitType.startsWith("hook/")) return "HOOK";
   switch (unitType) {
     case "research-milestone": return "RESEARCH";
     case "research-slice": return "RESEARCH";
@@ -981,7 +1203,14 @@ function unitPhaseLabel(unitType: string): string {
 }
 
 function peekNext(unitType: string, state: GSDState): string {
+  // Show active hook info in progress display
+  const activeHookState = getActiveHook();
+  if (activeHookState) {
+    return `hook: ${activeHookState.hookName} (cycle ${activeHookState.cycle})`;
+  }
+
   const sid = state.activeSlice?.id ?? "";
+  if (unitType.startsWith("hook/")) return `continue ${sid}`;
   switch (unitType) {
     case "research-milestone": return "plan milestone roadmap";
     case "plan-milestone": return "plan or execute first slice";
@@ -1275,6 +1504,12 @@ async function dispatchNextUnit(
     return;
   }
 
+  // Clear stale directory listing cache so deriveState sees fresh disk state (#431)
+  clearPathCache();
+  // Clear parsed roadmap/plan cache — doctor may have re-populated it with
+  // stale data between handleAgentEnd and this dispatch call (Path B fix).
+  clearParseCache();
+
   let state = await deriveState(basePath);
   let mid = state.activeMilestone?.id;
   let midTitle = state.activeMilestone?.title;
@@ -1288,8 +1523,9 @@ async function dispatchNextUnit(
     // Reset stuck detection for new milestone
     unitDispatchCount.clear();
     unitRecoveryCount.clear();
+    unitLifetimeDispatches.clear();
     // Capture integration branch for the new milestone and update git service
-    captureIntegrationBranch(basePath, mid);
+    captureIntegrationBranch(originalBasePath || basePath, mid);
   }
   if (mid) {
     currentMilestoneId = mid;
@@ -1338,6 +1574,8 @@ async function dispatchNextUnit(
         }
         // Re-derive state from the now-merged working tree
         invalidateStateCache();
+        clearParseCache();
+        clearPathCache();
         state = await deriveState(basePath);
         mid = state.activeMilestone?.id;
         midTitle = state.activeMilestone?.title;
@@ -1392,10 +1630,17 @@ async function dispatchNextUnit(
         if (sliceEntry?.done) {
           try {
             const sliceTitleForMerge = sliceEntry.title || branchSid;
-            switchToMain(basePath);
-            const mergeResult = mergeSliceToMain(
-              basePath, branchMid, branchSid, sliceTitleForMerge,
-            );
+            let mergeResult;
+            if (isInAutoWorktree(basePath) && getMergeToMainMode() !== "slice") {
+              mergeResult = mergeSliceToMilestone(
+                basePath, branchMid, branchSid, sliceTitleForMerge,
+              );
+            } else {
+              switchToMain(basePath);
+              mergeResult = mergeSliceToMain(
+                basePath, branchMid, branchSid, sliceTitleForMerge,
+              );
+            }
             const targetBranch = getMainBranch(basePath);
             ctx.ui.notify(
               `Merged ${mergeResult.branch} → ${targetBranch}.`,
@@ -1403,6 +1648,8 @@ async function dispatchNextUnit(
             );
             // Re-derive state from main so downstream logic sees merged state
             invalidateStateCache();
+            clearParseCache();
+            clearPathCache();
             state = await deriveState(basePath);
             mid = state.activeMilestone?.id;
             midTitle = state.activeMilestone?.title;
@@ -1457,7 +1704,7 @@ async function dispatchNextUnit(
             }
 
             // Non-conflict errors: reset and stop
-            const message = error instanceof Error ? error.message : String(error);
+            const message = formatGitError(error instanceof Error ? error : String(error));
             try {
               const status = runGit(basePath, ["status", "--porcelain"], { allowFailure: true });
               if (status && (status.includes("UU ") || status.includes("AA ") || status.includes("UD "))) {
@@ -1514,6 +1761,27 @@ async function dispatchNextUnit(
       if (existsSync(file)) writeFileSync(file, JSON.stringify([]), "utf-8");
       completedKeySet.clear();
     } catch { /* non-fatal */ }
+
+    // ── Milestone merge: squash-merge milestone branch to main before stopping ──
+    if (currentMilestoneId && isInAutoWorktree(basePath) && originalBasePath && getMergeToMainMode() === "milestone") {
+      try {
+        const roadmapPath = resolveMilestoneFile(originalBasePath, currentMilestoneId, "ROADMAP");
+        const roadmapContent = readFileSync(roadmapPath, "utf-8");
+        const mergeResult = mergeMilestoneToMain(originalBasePath, currentMilestoneId, roadmapContent);
+        basePath = originalBasePath;
+        gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        ctx.ui.notify(
+          `Milestone ${currentMilestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
+          "info",
+        );
+      } catch (err) {
+        ctx.ui.notify(
+          `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+          "warning",
+        );
+      }
+    }
+
     await stopAuto(ctx, pi);
     return;
   }
@@ -1715,6 +1983,28 @@ async function dispatchNextUnit(
     }
   }
 
+  // ── Pre-dispatch hooks: modify, skip, or replace the unit before dispatch ──
+  const preDispatchResult = runPreDispatchHooks(unitType, unitId, prompt, basePath);
+  if (preDispatchResult.firedHooks.length > 0) {
+    ctx.ui.notify(
+      `Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`,
+      "info",
+    );
+  }
+  if (preDispatchResult.action === "skip") {
+    ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
+    // Yield then re-dispatch to advance to next unit
+    await new Promise(r => setImmediate(r));
+    await dispatchNextUnit(ctx, pi);
+    return;
+  }
+  if (preDispatchResult.action === "replace") {
+    prompt = preDispatchResult.prompt ?? prompt;
+    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
+  } else if (preDispatchResult.prompt) {
+    prompt = preDispatchResult.prompt;
+  }
+
   const priorSliceBlocker = getPriorSliceCompletionBlocker(basePath, getMainBranch(basePath), unitType, unitId);
   if (priorSliceBlocker) {
     await stopAuto(ctx, pi);
@@ -1754,6 +2044,26 @@ async function dispatchNextUnit(
   // Pattern A→B→A→B would reset retryCount every time; this map catches it.
   const dispatchKey = `${unitType}/${unitId}`;
   const prevCount = unitDispatchCount.get(dispatchKey) ?? 0;
+
+  // Hard lifetime cap — survives counter resets from loop-recovery/self-repair.
+  // Catches the case where reconciliation "succeeds" (artifacts exist) but
+  // deriveState keeps returning the same unit, creating an infinite cycle.
+  const lifetimeCount = (unitLifetimeDispatches.get(dispatchKey) ?? 0) + 1;
+  unitLifetimeDispatches.set(dispatchKey, lifetimeCount);
+  if (lifetimeCount > MAX_LIFETIME_DISPATCHES) {
+    if (currentUnit) {
+      const modelId = ctx.model?.id ?? "unknown";
+      snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+    }
+    saveActivityLog(ctx, basePath, unitType, unitId);
+    const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
+    await stopAuto(ctx, pi);
+    ctx.ui.notify(
+      `Hard loop detected: ${unitType} ${unitId} dispatched ${lifetimeCount} times total (across reconciliation cycles). Stopping.${expected ? `\n   Expected artifact: ${expected}` : ""}\n   This may indicate deriveState() keeps returning the same unit despite artifacts existing.\n   Check .gsd/completed-units.json and the slice plan checkbox state.`,
+      "error",
+    );
+    return;
+  }
   if (prevCount >= MAX_UNIT_DISPATCHES) {
     if (currentUnit) {
       const modelId = ctx.model?.id ?? "unknown";
@@ -1778,7 +2088,13 @@ async function dispatchNextUnit(
               `Loop recovery: ${unitId} reconciled after ${prevCount + 1} dispatches — blocker artifacts written, pipeline advancing.\n   Review ${status.summaryPath} and replace the placeholder with real work.`,
               "warning",
             );
+            // Persist completion so idempotency check prevents re-dispatch
+            // if deriveState keeps returning this unit (#462).
+            const reconciledKey = `${unitType}/${unitId}`;
+            persistCompletedKey(basePath, reconciledKey);
+            completedKeySet.add(reconciledKey);
             unitDispatchCount.delete(dispatchKey);
+            invalidateStateCache();
             await new Promise(r => setImmediate(r));
             await dispatchNextUnit(ctx, pi);
             return;
@@ -1787,6 +2103,30 @@ async function dispatchNextUnit(
       }
     }
 
+    // General reconciliation: if the last attempt DID produce the expected
+    // artifact on disk, clear the counter and advance instead of stopping.
+    // The execute-task path above handles its special case (writing placeholder
+    // summaries). This catch-all covers complete-slice, plan-slice,
+    // research-slice, and all other unit types where the Nth attempt at the
+    // dispatch limit succeeded but the counter check fires before anyone
+    // verifies disk state. Without this, a successful final attempt is
+    // indistinguishable from a failed one.
+    if (verifyExpectedArtifact(unitType, unitId, basePath)) {
+      ctx.ui.notify(
+        `Loop recovery: ${unitType} ${unitId} — artifact verified after ${prevCount + 1} dispatches. Advancing.`,
+        "info",
+      );
+      // Persist completion so the idempotency check prevents re-dispatch
+      // if deriveState keeps returning this unit (see #462).
+      persistCompletedKey(basePath, dispatchKey);
+      completedKeySet.add(dispatchKey);
+      unitDispatchCount.delete(dispatchKey);
+      invalidateStateCache();
+      await new Promise(r => setImmediate(r));
+      await dispatchNextUnit(ctx, pi);
+      return;
+    }
+
     const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
     const remediation = buildLoopRemediationSteps(unitType, unitId, basePath);
     await stopAuto(ctx, pi);
@@ -1813,7 +2153,12 @@ async function dispatchNextUnit(
               `Self-repaired ${unitId}: summary existed but checkbox was unmarked. Marked [x] and advancing.`,
               "warning",
             );
+            // Persist completion so idempotency check prevents re-dispatch (#462).
+            const repairedKey = `${unitType}/${unitId}`;
+            persistCompletedKey(basePath, repairedKey);
+            completedKeySet.add(repairedKey);
             unitDispatchCount.delete(dispatchKey);
+            invalidateStateCache();
             await new Promise(r => setImmediate(r));
             await dispatchNextUnit(ctx, pi);
             return;
@@ -2285,6 +2630,7 @@ async function buildResearchMilestonePrompt(mid: string, midTitle: string, base:
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  inlined.push(inlineTemplate("research", "Research"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2317,6 +2663,11 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  inlined.push(inlineTemplate("roadmap", "Roadmap"));
+  inlined.push(inlineTemplate("decisions", "Decisions"));
+  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(inlineTemplate("task-plan", "Task Plan"));
+  inlined.push(inlineTemplate("secrets-manifest", "Secrets Manifest"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2353,6 +2704,7 @@ async function buildResearchSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  inlined.push(inlineTemplate("research", "Research"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
 
@@ -2388,6 +2740,8 @@ async function buildPlanSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(inlineTemplate("task-plan", "Task Plan"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
 
@@ -2449,6 +2803,10 @@ async function buildExecuteTaskPrompt(
   );
 
   const carryForwardSection = await buildCarryForwardSection(priorSummaries, base);
+  const inlinedTemplates = [
+    inlineTemplate("task-summary", "Task Summary"),
+    inlineTemplate("decisions", "Decisions"),
+  ].join("\n\n---\n\n");
 
   const taskSummaryPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-SUMMARY.md`;
 
@@ -2463,6 +2821,7 @@ async function buildExecuteTaskPrompt(
     resumeSection,
     priorTaskLines: priorLines,
     taskSummaryPath,
+    inlinedTemplates,
   });
 }
 
@@ -2495,6 +2854,8 @@ async function buildCompleteSlicePrompt(
       }
     }
   }
+  inlined.push(inlineTemplate("slice-summary", "Slice Summary"));
+  inlined.push(inlineTemplate("uat", "UAT"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2547,6 +2908,7 @@ async function buildCompleteMilestonePrompt(
   const contextRel = relMilestoneFile(base, mid, "CONTEXT");
   const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context");
   if (contextInline) inlined.push(contextInline);
+  inlined.push(inlineTemplate("milestone-summary", "Milestone Summary"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2993,6 +3355,9 @@ async function collectObservabilityWarnings(
   unitType: string,
   unitId: string,
 ): Promise<import("./observability-validator.ts").ValidationIssue[]> {
+  // Hook units have custom artifacts — skip standard observability checks
+  if (unitType.startsWith("hook/")) return [];
+
   const parts = unitId.split("/");
   const mid = parts[0];
   const sid = parts[1];
@@ -3404,6 +3769,9 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
  * skipped writing the UAT file (see #176).
  */
 export function verifyExpectedArtifact(unitType: string, unitId: string, base: string): boolean {
+  // Clear stale directory listing cache so artifact checks see fresh disk state (#431)
+  clearPathCache();
+
   // fix-merge has no file artifact — verify by checking git state
   if (unitType === "fix-merge") {
     const unmerged = runGit(base, ["diff", "--name-only", "--diff-filter=U"], { allowFailure: true });