gsd-pi 2.28.0 → 2.29.0-dev.23d50d0

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

@@ -11,6 +11,7 @@ import type { GSDState } from "./types.js";
 import { getCurrentBranch } from "./worktree.js";
 import { getActiveHook } from "./post-unit-hooks.js";
 import { getLedger, getProjectTotals, formatCost, formatTokenCount, formatTierSavings } from "./metrics.js";
+import { getHealthTrend, getConsecutiveErrorUnits } from "./doctor-proactive.js";
 import {
   resolveMilestoneFile,
   resolveSliceFile,
@@ -18,7 +19,7 @@ import {
 import { parseRoadmap, parsePlan } from "./files.js";
 import { readFileSync, existsSync } from "node:fs";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
-import { makeUI, GLYPH, INDENT } from "../shared/ui.js";
+import { makeUI, GLYPH, INDENT } from "../shared/mod.js";
 
 // ─── Dashboard Data ───────────────────────────────────────────────────────────
 
@@ -204,6 +205,13 @@ export function estimateTimeRemaining(): string | null {
 
 // ─── Slice Progress Cache ─────────────────────────────────────────────────────
 
+/** Cached task detail for the widget task checklist */
+interface CachedTaskDetail {
+  id: string;
+  title: string;
+  done: boolean;
+}
+
 /** Cached slice progress for the widget — avoid async in render */
 let cachedSliceProgress: {
   done: number;
@@ -211,6 +219,8 @@ let cachedSliceProgress: {
   milestoneId: string;
   /** Real task progress for the active slice, if its plan file exists */
   activeSliceTasks: { done: number; total: number } | null;
+  /** Full task list for the active slice checklist */
+  taskDetails: CachedTaskDetail[] | null;
 } | null = null;
 
 export function updateSliceProgressCache(base: string, mid: string, activeSid?: string): void {
@@ -221,6 +231,7 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?:
     const roadmap = parseRoadmap(content);
 
     let activeSliceTasks: { done: number; total: number } | null = null;
+    let taskDetails: CachedTaskDetail[] | null = null;
     if (activeSid) {
       try {
         const planFile = resolveSliceFile(base, mid, activeSid, "PLAN");
@@ -231,6 +242,7 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?:
             done: plan.tasks.filter(t => t.done).length,
             total: plan.tasks.length,
           };
+          taskDetails = plan.tasks.map(t => ({ id: t.id, title: t.title, done: t.done }));
         }
       } catch {
         // Non-fatal — just omit task count
@@ -242,13 +254,19 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?:
       total: roadmap.slices.length,
       milestoneId: mid,
       activeSliceTasks,
+      taskDetails,
     };
   } catch {
     // Non-fatal — widget just won't show progress bar
   }
 }
 
-export function getRoadmapSlicesSync(): { done: number; total: number; activeSliceTasks: { done: number; total: number } | null } | null {
+export function getRoadmapSlicesSync(): {
+  done: number;
+  total: number;
+  activeSliceTasks: { done: number; total: number } | null;
+  taskDetails: CachedTaskDetail[] | null;
+} | null {
   return cachedSliceProgress;
 }
 
@@ -309,6 +327,16 @@ export function updateProgressWidget(
   }
   if (cachedBranch) widgetPwd = `${widgetPwd} (${cachedBranch})`;
 
+  // Set a string-array fallback first — this is the only version RPC mode will
+  // see, since the factory widget set below is not supported in RPC mode.
+  const progressText = buildProgressTextLines(
+    verb, phaseLabel, unitId, mid, slice, task, next,
+    accessors, tierBadge, widgetPwd,
+  );
+  ctx.ui.setWidget("gsd-progress", progressText);
+
+  // Set the factory-based widget — in TUI mode this replaces the string-array
+  // version with a dynamic, animated widget. In RPC mode this call is a no-op.
   ctx.ui.setWidget("gsd-progress", (tui, theme) => {
     let pulseBright = true;
     let cachedLines: string[] | undefined;
@@ -339,81 +367,84 @@ export function updateProgressWidget(
         const lines: string[] = [];
         const pad = INDENT.base;
 
-        // ── Line 1: Top bar ───────────────────────────────────────────────
+        // ── Top bar ─────────────────────────────────────────────────────
         lines.push(...ui.bar());
 
+        // ── Header: GSD AUTO ... elapsed ────────────────────────────────
         const dot = pulseBright
           ? theme.fg("accent", GLYPH.statusActive)
           : theme.fg("dim", GLYPH.statusPending);
         const elapsed = formatAutoElapsed(accessors.getAutoStartTime());
         const modeTag = accessors.isStepMode() ? "NEXT" : "AUTO";
-        const headerLeft = `${pad}${dot} ${theme.fg("accent", theme.bold("GSD"))}  ${theme.fg("success", modeTag)}`;
+        const headerLeft = `${pad}${dot} ${theme.fg("accent", theme.bold("GSD"))} ${theme.fg("success", modeTag)}`;
         const headerRight = elapsed ? theme.fg("dim", elapsed) : "";
         lines.push(rightAlign(headerLeft, headerRight, width));
 
-        lines.push("");
-
-        if (mid) {
-          lines.push(truncateToWidth(`${pad}${theme.fg("dim", mid.title)}`, width));
-        }
-
+        // ── Context: project · slice · action (merged into one line) ────
+        const contextParts: string[] = [];
+        if (mid) contextParts.push(theme.fg("dim", mid.title));
         if (slice && unitType !== "research-milestone" && unitType !== "plan-milestone") {
-          lines.push(truncateToWidth(
-            `${pad}${theme.fg("text", theme.bold(`${slice.id}: ${slice.title}`))}`,
-            width,
-          ));
+          contextParts.push(theme.fg("text", theme.bold(`${slice.id}: ${slice.title}`)));
         }
+        const isHook = unitType.startsWith("hook/");
+        const target = isHook
+          ? (unitId.split("/").pop() ?? unitId)
+          : (task ? `${task.id}: ${task.title}` : unitId);
+        contextParts.push(`${theme.fg("accent", "▸")} ${theme.fg("accent", verb)} ${theme.fg("text", target)}`);
 
-        lines.push("");
-
-        const target = task ? `${task.id}: ${task.title}` : unitId;
-        const actionLeft = `${pad}${theme.fg("accent", "▸")} ${theme.fg("accent", verb)}  ${theme.fg("text", target)}`;
         const tierTag = tierBadge ? theme.fg("dim", `[${tierBadge}] `) : "";
         const phaseBadge = `${tierTag}${theme.fg("dim", phaseLabel)}`;
-        lines.push(rightAlign(actionLeft, phaseBadge, width));
-        lines.push("");
-
-        if (mid) {
-          const roadmapSlices = getRoadmapSlicesSync();
-          if (roadmapSlices) {
-            const { done, total, activeSliceTasks } = roadmapSlices;
-            const barWidth = Math.max(8, Math.min(24, Math.floor(width * 0.3)));
-            const pct = total > 0 ? done / total : 0;
-            const filled = Math.round(pct * barWidth);
-            const bar = theme.fg("success", "█".repeat(filled))
-              + theme.fg("dim", "░".repeat(barWidth - filled));
-
-            let meta = theme.fg("dim", `${done}/${total} slices`);
-
-            if (activeSliceTasks && activeSliceTasks.total > 0) {
-              const taskNum = Math.min(activeSliceTasks.done + 1, activeSliceTasks.total);
-              meta += theme.fg("dim", `  ·  task ${taskNum}/${activeSliceTasks.total}`);
-            }
-
-            // ETA estimate
-            const eta = estimateTimeRemaining();
-            if (eta) {
-              meta += theme.fg("dim", `  ·  ${eta}`);
-            }
+        const contextLine = contextParts.join(theme.fg("dim", " · "));
+        lines.push(rightAlign(`${pad}${contextLine}`, phaseBadge, width));
+
+        // ── Two-column body ─────────────────────────────────────────────
+        // Left: progress, ETA, next, stats (fixed)  |  Right: task checklist (fixed, adjacent)
+        // Both columns sit left-to-center; empty space is on the right.
+        const divider = theme.fg("dim", "│");
+        const minTwoColWidth = 100;
+        const rightColFixed = 44;
+        const colGap = 5; // breathing room between columns
+        // Left column takes remaining space — no truncation on wide terminals
+        const useTwoCol = width >= minTwoColWidth;
+        const rightColWidth = useTwoCol ? rightColFixed : 0;
+        const leftColWidth = useTwoCol ? width - rightColWidth - colGap : width;
+
+        const roadmapSlices = mid ? getRoadmapSlicesSync() : null;
+
+        // Build left column: progress bar, ETA, next step, token stats
+        const leftLines: string[] = [];
+
+        if (roadmapSlices) {
+          const { done, total, activeSliceTasks } = roadmapSlices;
+          const barWidth = Math.max(6, Math.min(18, Math.floor(leftColWidth * 0.4)));
+          const pct = total > 0 ? done / total : 0;
+          const filled = Math.round(pct * barWidth);
+          const bar = theme.fg("success", "█".repeat(filled))
+            + theme.fg("dim", "░".repeat(barWidth - filled));
+
+          let meta = theme.fg("dim", `${done}/${total} slices`);
+          if (activeSliceTasks && activeSliceTasks.total > 0) {
+            const taskNum = isHook
+              ? Math.max(activeSliceTasks.done, 1)
+              : Math.min(activeSliceTasks.done + 1, activeSliceTasks.total);
+            meta += theme.fg("dim", ` · task ${taskNum}/${activeSliceTasks.total}`);
+          }
+          leftLines.push(truncateToWidth(`${pad}${bar} ${meta}`, leftColWidth));
 
-            lines.push(truncateToWidth(`${pad}${bar}  ${meta}`, width));
+          const eta = estimateTimeRemaining();
+          if (eta) {
+            leftLines.push(truncateToWidth(`${pad}${theme.fg("dim", eta)}`, leftColWidth));
           }
         }
 
-        lines.push("");
-
         if (next) {
-          lines.push(truncateToWidth(
+          leftLines.push(truncateToWidth(
             `${pad}${theme.fg("dim", "→")} ${theme.fg("dim", `then ${next}`)}`,
-            width,
+            leftColWidth,
           ));
         }
 
-        // ── Footer info (pwd, tokens, cost, context, model) ──────────────
-        lines.push("");
-        lines.push(truncateToWidth(theme.fg("dim", `${pad}${widgetPwd}`), width, theme.fg("dim", "…")));
-
-        // Token stats from current unit session + cumulative cost from metrics
+        // Token stats
         {
           const cmdCtx = accessors.getCmdCtx();
           let totalInput = 0, totalOutput = 0;
@@ -448,7 +479,12 @@ export function updateProgressWidget(
           if (totalOutput) sp.push(`↓${formatWidgetTokens(totalOutput)}`);
           if (totalCacheRead) sp.push(`R${formatWidgetTokens(totalCacheRead)}`);
           if (totalCacheWrite) sp.push(`W${formatWidgetTokens(totalCacheWrite)}`);
+          if (totalCacheRead + totalInput > 0) {
+            const hitRate = Math.round((totalCacheRead / (totalCacheRead + totalInput)) * 100);
+            sp.push(`\u26A1${hitRate}%`);
+          }
           if (cumulativeCost) sp.push(`$${cumulativeCost.toFixed(3)}`);
+          else if (autoTotals?.apiRequests) sp.push(`${autoTotals.apiRequests} reqs`);
 
           const cxDisplay = cxPct === "?"
             ? `?/${formatWidgetTokens(cxWindow)}`
@@ -461,33 +497,134 @@ export function updateProgressWidget(
             sp.push(cxDisplay);
           }
 
-          const sLeft = sp.map(p => p.includes("\x1b[") ? p : theme.fg("dim", p))
+          const tokenLine = sp.map(p => p.includes("\x1b[") ? p : theme.fg("dim", p))
             .join(theme.fg("dim", " "));
+          leftLines.push(truncateToWidth(`${pad}${tokenLine}`, leftColWidth));
 
           const modelId = cmdCtx?.model?.id ?? "";
           const modelProvider = cmdCtx?.model?.provider ?? "";
-          const modelPhase = phaseLabel ? theme.fg("dim", `[${phaseLabel}] `) : "";
           const modelDisplay = modelProvider && modelId
             ? `${modelProvider}/${modelId}`
             : modelId;
-          const sRight = modelDisplay
-            ? `${modelPhase}${theme.fg("dim", modelDisplay)}`
-            : "";
-          lines.push(rightAlign(`${pad}${sLeft}`, sRight, width));
+          if (modelDisplay) {
+            leftLines.push(truncateToWidth(`${pad}${theme.fg("dim", modelDisplay)}`, leftColWidth));
+          }
 
-          // Dynamic routing savings summary
+          // Dynamic routing savings
           if (mLedger && mLedger.units.some(u => u.tier)) {
             const savings = formatTierSavings(mLedger.units);
             if (savings) {
-              lines.push(truncateToWidth(theme.fg("dim", `${pad}${savings}`), width));
+              leftLines.push(truncateToWidth(`${pad}${theme.fg("dim", savings)}`, leftColWidth));
+            }
+          }
+        }
+
+        // Build right column: task checklist (pegged to right edge)
+        const rightLines: string[] = [];
+        const taskDetails = roadmapSlices?.taskDetails ?? null;
+        const maxVisibleTasks = 8;
+        const rpad = " ";
+
+        if (useTwoCol) {
+          if (taskDetails && taskDetails.length > 0) {
+            const visibleTasks = taskDetails.slice(0, maxVisibleTasks);
+            for (const t of visibleTasks) {
+              const isCurrent = task && t.id === task.id;
+              const glyph = t.done
+                ? theme.fg("success", GLYPH.statusDone)
+                : isCurrent
+                  ? theme.fg("accent", "▸")
+                  : theme.fg("dim", " ");
+              const label = isCurrent
+                ? theme.fg("text", `${t.id}: ${t.title}`)
+                : t.done
+                  ? theme.fg("dim", `${t.id}: ${t.title}`)
+                  : theme.fg("text", `${t.id}: ${t.title}`);
+              rightLines.push(truncateToWidth(`${rpad}${glyph} ${label}`, rightColWidth));
+            }
+            if (taskDetails.length > maxVisibleTasks) {
+              rightLines.push(truncateToWidth(
+                `${rpad}${theme.fg("dim", `  …+${taskDetails.length - maxVisibleTasks} more`)}`,
+                rightColWidth,
+              ));
+            }
+          } else if (roadmapSlices?.activeSliceTasks) {
+            const { done: tDone, total: tTotal } = roadmapSlices.activeSliceTasks;
+            rightLines.push(`${rpad}${theme.fg("dim", `${tDone}/${tTotal} tasks`)}`);
+          }
+        } else {
+          // Narrow single-column: task list goes into left column
+          if (taskDetails && taskDetails.length > 0) {
+            for (const t of taskDetails.slice(0, maxVisibleTasks)) {
+              const isCurrent = task && t.id === task.id;
+              const glyph = t.done
+                ? theme.fg("success", GLYPH.statusDone)
+                : isCurrent
+                  ? theme.fg("accent", "▸")
+                  : theme.fg("dim", " ");
+              const label = isCurrent
+                ? theme.fg("text", `${t.id}: ${t.title}`)
+                : t.done
+                  ? theme.fg("dim", `${t.id}: ${t.title}`)
+                  : theme.fg("text", `${t.id}: ${t.title}`);
+              leftLines.push(truncateToWidth(`${pad}${glyph} ${label}`, leftColWidth));
+            }
+          }
+          // Add progress bar inline
+          if (roadmapSlices) {
+            const { done, total, activeSliceTasks } = roadmapSlices;
+            const barWidth = Math.max(6, Math.min(18, Math.floor(leftColWidth * 0.4)));
+            const pct = total > 0 ? done / total : 0;
+            const filled = Math.round(pct * barWidth);
+            const bar = theme.fg("success", "█".repeat(filled))
+              + theme.fg("dim", "░".repeat(barWidth - filled));
+            let meta = theme.fg("dim", `${done}/${total} slices`);
+            if (activeSliceTasks && activeSliceTasks.total > 0) {
+              const taskNum = isHook
+                ? Math.max(activeSliceTasks.done, 1)
+                : Math.min(activeSliceTasks.done + 1, activeSliceTasks.total);
+              meta += theme.fg("dim", ` · task ${taskNum}/${activeSliceTasks.total}`);
             }
+            const eta = estimateTimeRemaining();
+            if (eta) meta += theme.fg("dim", ` · ${eta}`);
+            leftLines.push(truncateToWidth(`${pad}${bar} ${meta}`, leftColWidth));
+          }
+          if (next) {
+            leftLines.push(truncateToWidth(
+              `${pad}${theme.fg("dim", "→")} ${theme.fg("dim", `then ${next}`)}`,
+              leftColWidth,
+            ));
           }
         }
 
+        // Compose columns
+        if (useTwoCol) {
+          const maxRows = Math.max(leftLines.length, rightLines.length);
+          if (maxRows > 0) {
+            lines.push(""); // spacer before columns
+            for (let i = 0; i < maxRows; i++) {
+              const left = padToWidth(leftLines[i] ?? "", leftColWidth);
+              const gap = " ".repeat(colGap - 2); // colGap minus divider and its trailing space
+              const right = rightLines[i] ?? "";
+              lines.push(truncateToWidth(`${left}${gap}${divider} ${right}`, width));
+            }
+          }
+        } else {
+          // Narrow single-column: just stack
+          if (leftLines.length > 0) {
+            lines.push("");
+            for (const l of leftLines) lines.push(l);
+          }
+        }
+
+        // ── Footer: pwd + hints ─────────────────────────────────────────
+        lines.push("");
         const hintParts: string[] = [];
         hintParts.push("esc pause");
         hintParts.push(process.platform === "darwin" ? "⌃⌥G dashboard" : "Ctrl+Alt+G dashboard");
-        lines.push(...ui.hints(hintParts));
+        const hintStr = theme.fg("dim", hintParts.join(" | "));
+        const pwdStr = theme.fg("dim", widgetPwd);
+        lines.push(rightAlign(`${pad}${pwdStr}`, hintStr, width));
 
         lines.push(...ui.bar());
 
@@ -507,6 +644,95 @@ export function updateProgressWidget(
   });
 }
 
+// ─── Text Fallback for RPC Mode ───────────────────────────────────────────
+
+/**
+ * Build a compact string-array representation of the progress widget.
+ * Used as a fallback when the factory-based widget cannot render (RPC mode).
+ */
+// ─── Model Health Indicator ───────────────────────────────────────────────────
+
+/**
+ * Compute a traffic-light health indicator from observable signals.
+ * 🟢 progressing well — no errors, trend stable/improving
+ * 🟡 struggling — some errors or degrading trend
+ * 🔴 stuck — consecutive errors, likely needs attention
+ */
+export function getModelHealthIndicator(): { emoji: string; label: string } {
+  const trend = getHealthTrend();
+  const consecutiveErrors = getConsecutiveErrorUnits();
+
+  if (consecutiveErrors >= 3) {
+    return { emoji: "🔴", label: "stuck" };
+  }
+  if (consecutiveErrors >= 1 || trend === "degrading") {
+    return { emoji: "🟡", label: "struggling" };
+  }
+  if (trend === "improving") {
+    return { emoji: "🟢", label: "progressing well" };
+  }
+  // stable or unknown
+  return { emoji: "🟢", label: "progressing" };
+}
+
+function buildProgressTextLines(
+  verb: string,
+  phaseLabel: string,
+  unitId: string,
+  mid: { id: string; title: string } | null,
+  slice: { id: string; title: string } | null,
+  task: { id: string; title: string } | null,
+  next: string,
+  accessors: WidgetStateAccessors,
+  tierBadge: string | undefined,
+  widgetPwd: string,
+): string[] {
+  const mode = accessors.isStepMode() ? "step" : "auto";
+  const elapsed = formatAutoElapsed(accessors.getAutoStartTime());
+  const tierStr = tierBadge ? ` [${tierBadge}]` : "";
+
+  const lines: string[] = [];
+  lines.push(`[GSD ${mode}] ${verb} ${unitId}${tierStr}${elapsed ? ` — ${elapsed}` : ""}`);
+
+  if (mid) lines.push(`  Milestone: ${mid.id} — ${mid.title}`);
+  if (slice) lines.push(`  Slice: ${slice.id} — ${slice.title}`);
+  if (task) lines.push(`  Task: ${task.id} — ${task.title}`);
+
+  // Progress bar
+  const sp = cachedSliceProgress;
+  if (sp && sp.total > 0) {
+    const pct = Math.round((sp.done / sp.total) * 100);
+    const taskInfo = sp.activeSliceTasks
+      ? ` (tasks: ${sp.activeSliceTasks.done}/${sp.activeSliceTasks.total})`
+      : "";
+    lines.push(`  Progress: ${sp.done}/${sp.total} slices (${pct}%)${taskInfo}`);
+  }
+
+  // Cost / tokens
+  const ledger = getLedger();
+  const totals = ledger ? getProjectTotals(ledger.units) : null;
+  if (totals) {
+    const parts: string[] = [];
+    if (totals.tokens.input || totals.tokens.output) {
+      parts.push(`tokens: ${formatWidgetTokens(totals.tokens.input)}↑ ${formatWidgetTokens(totals.tokens.output)}↓`);
+    }
+    if (totals.cost > 0) {
+      parts.push(`cost: ${formatCost(totals.cost)}`);
+    }
+    if (parts.length > 0) lines.push(`  ${parts.join(" — ")}`);
+  }
+
+  if (next) lines.push(`  Next: ${next}`);
+
+  // Model health indicator
+  const health = getModelHealthIndicator();
+  lines.push(`  Health: ${health.emoji} ${health.label}`);
+
+  lines.push(`  ${widgetPwd}`);
+
+  return lines;
+}
+
 // ─── Right-align Helper ───────────────────────────────────────────────────────
 
 /** Right-align helper: build a line with left content and right content. */
@@ -516,3 +742,10 @@ function rightAlign(left: string, right: string, width: number): string {
   const gap = Math.max(1, width - leftVis - rightVis);
   return truncateToWidth(left + " ".repeat(gap) + right, width);
 }
+
+/** Pad a string with trailing spaces to fill exactly `colWidth` (ANSI-aware). */
+function padToWidth(s: string, colWidth: number): string {
+  const vis = visibleWidth(s);
+  if (vis >= colWidth) return truncateToWidth(s, colWidth);
+  return s + " ".repeat(colWidth - vis);
+}

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

@@ -126,8 +126,8 @@ const DISPATCH_RULES: DispatchRule[] = [
   {
     name: "reassess-roadmap (post-completion)",
     match: async ({ state, mid, midTitle, basePath, prefs }) => {
-      // Phase skip: skip reassess when preference or profile says so
-      if (prefs?.phases?.skip_reassess) return null;
+      // Reassess is opt-in: only fire when explicitly enabled
+      if (!prefs?.phases?.reassess_after_slice) return null;
       const needsReassess = await checkNeedsReassessment(basePath, mid, state);
       if (!needsReassess) return null;
       return {

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

@@ -0,0 +1,150 @@
+/**
+ * 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 type { AutoSession } from "./auto/session.js";
+
+export interface IdempotencyContext {
+  s: AutoSession;
+  unitType: string;
+  unitId: string;
+  basePath: string;
+  /** Notification callback */
+  notify: (message: string, level: "info" | "warning" | "error") => void;
+}
+
+export type IdempotencyResult =
+  | { action: "skip"; reason: string }
+  | { action: "rerun"; reason: string }
+  | { action: "proceed" }
+  | { action: "stop"; reason: string };
+
+/**
+ * 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: IdempotencyContext): IdempotencyResult {
+  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 = unitId.split("/")[0];
+        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 = unitId.split("/")[0];
+      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" };
+}