gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/extensions/gsd/auto-stuck-detection.ts

@@ -0,0 +1,220 @@
+/**
+ * Stuck detection and loop recovery for auto-mode unit dispatch.
+ *
+ * Tracks dispatch counts per unit, enforces lifetime caps, and attempts
+ * stub/artifact recovery before stopping.
+ *
+ * Extracted from dispatchNextUnit() in auto.ts. Returns action values
+ * instead of calling stopAuto/dispatchNextUnit — the caller handles
+ * control flow.
+ */
+
+import type { ExtensionContext } from "@gsd/pi-coding-agent";
+import {
+  inspectExecuteTaskDurability,
+} from "./unit-runtime.js";
+import {
+  verifyExpectedArtifact,
+  diagnoseExpectedArtifact,
+  skipExecuteTask,
+  persistCompletedKey,
+  buildLoopRemediationSteps,
+} from "./auto-recovery.js";
+import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
+import { saveActivityLog } from "./activity-log.js";
+import { invalidateAllCaches } from "./cache.js";
+import { sendDesktopNotification } from "./notifications.js";
+import { debugLog } from "./debug-logger.js";
+import {
+  resolveMilestonePath,
+  resolveSlicePath,
+  resolveTasksDir,
+  buildTaskFileName,
+} from "./paths.js";
+import {
+  MAX_UNIT_DISPATCHES,
+  STUB_RECOVERY_THRESHOLD,
+  MAX_LIFETIME_DISPATCHES,
+} from "./auto/session.js";
+import type { AutoSession } from "./auto/session.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface StuckContext {
+  s: AutoSession;
+  ctx: ExtensionContext;
+  unitType: string;
+  unitId: string;
+  basePath: string;
+  buildSnapshotOpts: () => CloseoutOptions & Record<string, unknown>;
+}
+
+export type StuckResult =
+  | { action: "proceed" }
+  | { action: "recovered"; dispatchAgain: true }
+  | { action: "stop"; reason: string; notifyMessage?: string };
+
+/**
+ * Check dispatch counts, enforce lifetime cap and MAX_UNIT_DISPATCHES,
+ * attempt stub/artifact recovery. Returns an action for the caller.
+ */
+export async function checkStuckAndRecover(sctx: StuckContext): Promise<StuckResult> {
+  const { s, ctx, unitType, unitId, basePath, buildSnapshotOpts } = sctx;
+  const dispatchKey = `${unitType}/${unitId}`;
+  const prevCount = s.unitDispatchCount.get(dispatchKey) ?? 0;
+
+  // Real dispatch reached — clear the consecutive-skip counter for this unit.
+  s.unitConsecutiveSkips.delete(dispatchKey);
+
+  debugLog("dispatch-unit", {
+    type: unitType,
+    id: unitId,
+    cycle: prevCount + 1,
+    lifetime: (s.unitLifetimeDispatches.get(dispatchKey) ?? 0) + 1,
+  });
+
+  // Hard lifetime cap — survives counter resets from loop-recovery/self-repair.
+  const lifetimeCount = (s.unitLifetimeDispatches.get(dispatchKey) ?? 0) + 1;
+  s.unitLifetimeDispatches.set(dispatchKey, lifetimeCount);
+  if (lifetimeCount > MAX_LIFETIME_DISPATCHES) {
+    if (s.currentUnit) {
+      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts());
+    } else {
+      saveActivityLog(ctx, s.basePath, unitType, unitId);
+    }
+    const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
+    return {
+      action: "stop",
+      reason: `Hard loop: ${unitType} ${unitId}`,
+      notifyMessage: `Hard loop detected: ${unitType} ${unitId} dispatched ${lifetimeCount} times total (across reconciliation cycles).${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.`,
+    };
+  }
+
+  if (prevCount >= MAX_UNIT_DISPATCHES) {
+    if (s.currentUnit) {
+      await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts());
+    } else {
+      saveActivityLog(ctx, s.basePath, unitType, unitId);
+    }
+
+    // Final reconciliation pass for execute-task
+    if (unitType === "execute-task") {
+      const [mid, sid, tid] = unitId.split("/");
+      if (mid && sid && tid) {
+        const status = await inspectExecuteTaskDurability(basePath, unitId);
+        if (status) {
+          const reconciled = skipExecuteTask(basePath, mid, sid, tid, status, "loop-recovery", prevCount);
+          if (reconciled && verifyExpectedArtifact(unitType, unitId, basePath)) {
+            ctx.ui.notify(
+              `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",
+            );
+            const reconciledKey = `${unitType}/${unitId}`;
+            persistCompletedKey(basePath, reconciledKey);
+            s.completedKeySet.add(reconciledKey);
+            s.unitDispatchCount.delete(dispatchKey);
+            invalidateAllCaches();
+            return { action: "recovered", dispatchAgain: true };
+          }
+        }
+      }
+    }
+
+    // General reconciliation: artifact appeared on last attempt
+    if (verifyExpectedArtifact(unitType, unitId, basePath)) {
+      ctx.ui.notify(
+        `Loop recovery: ${unitType} ${unitId} — artifact verified after ${prevCount + 1} dispatches. Advancing.`,
+        "info",
+      );
+      persistCompletedKey(basePath, dispatchKey);
+      s.completedKeySet.add(dispatchKey);
+      s.unitDispatchCount.delete(dispatchKey);
+      invalidateAllCaches();
+      return { action: "recovered", dispatchAgain: true };
+    }
+
+    // Last resort for complete-milestone: generate stub summary
+    if (unitType === "complete-milestone") {
+      try {
+        const mPath = resolveMilestonePath(basePath, unitId);
+        if (mPath) {
+          const stubPath = join(mPath, `${unitId}-SUMMARY.md`);
+          if (!existsSync(stubPath)) {
+            writeFileSync(stubPath, `# ${unitId} Summary\n\nAuto-generated stub — milestone tasks completed but summary generation failed after ${prevCount + 1} attempts.\nReview and replace this stub with a proper summary.\n`);
+            ctx.ui.notify(`Generated stub summary for ${unitId} to unblock pipeline. Review later.`, "warning");
+            persistCompletedKey(basePath, dispatchKey);
+            s.completedKeySet.add(dispatchKey);
+            s.unitDispatchCount.delete(dispatchKey);
+            invalidateAllCaches();
+            return { action: "recovered", dispatchAgain: true };
+          }
+        }
+      } catch { /* non-fatal — fall through to normal stop */ }
+    }
+
+    const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
+    const remediation = buildLoopRemediationSteps(unitType, unitId, basePath);
+    sendDesktopNotification("GSD", `Loop detected: ${unitType} ${unitId}`, "error", "error");
+    return {
+      action: "stop",
+      reason: `Loop: ${unitType} ${unitId}`,
+      notifyMessage: `Loop detected: ${unitType} ${unitId} dispatched ${prevCount + 1} times total. Expected artifact not found.${expected ? `\n   Expected: ${expected}` : ""}${remediation ? `\n\n   Remediation steps:\n${remediation}` : "\n   Check branch state and .gsd/ artifacts."}`,
+    };
+  }
+
+  s.unitDispatchCount.set(dispatchKey, prevCount + 1);
+
+  if (prevCount > 0) {
+    // Adaptive self-repair: each retry attempts a different remediation step.
+    if (unitType === "execute-task") {
+      const status = await inspectExecuteTaskDurability(basePath, unitId);
+      const [mid, sid, tid] = unitId.split("/");
+      if (status && mid && sid && tid) {
+        if (status.summaryExists && !status.taskChecked) {
+          const repaired = skipExecuteTask(basePath, mid, sid, tid, status, "self-repair", 0);
+          if (repaired && verifyExpectedArtifact(unitType, unitId, basePath)) {
+            ctx.ui.notify(
+              `Self-repaired ${unitId}: summary existed but checkbox was unmarked. Marked [x] and advancing.`,
+              "warning",
+            );
+            const repairedKey = `${unitType}/${unitId}`;
+            persistCompletedKey(basePath, repairedKey);
+            s.completedKeySet.add(repairedKey);
+            s.unitDispatchCount.delete(dispatchKey);
+            invalidateAllCaches();
+            return { action: "recovered", dispatchAgain: true };
+          }
+        } else if (prevCount >= STUB_RECOVERY_THRESHOLD && !status.summaryExists) {
+          const tasksDir = resolveTasksDir(basePath, mid, sid);
+          const sDir = resolveSlicePath(basePath, mid, sid);
+          const targetDir = tasksDir ?? (sDir ? join(sDir, "tasks") : null);
+          if (targetDir) {
+            if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+            const summaryPath = join(targetDir, buildTaskFileName(tid, "SUMMARY"));
+            if (!existsSync(summaryPath)) {
+              const stubContent = [
+                `# PARTIAL RECOVERY — attempt ${prevCount + 1} of ${MAX_UNIT_DISPATCHES}`,
+                ``,
+                `Task \`${tid}\` in slice \`${sid}\` (milestone \`${mid}\`) has not yet produced a real summary.`,
+                `This placeholder was written by auto-mode after ${prevCount} dispatch attempts.`,
+                ``,
+                `The next agent session will retry this task. Replace this file with real work when done.`,
+              ].join("\n");
+              writeFileSync(summaryPath, stubContent, "utf-8");
+              ctx.ui.notify(
+                `Stub recovery (attempt ${prevCount + 1}/${MAX_UNIT_DISPATCHES}): ${unitId} stub summary placeholder written. Retrying with recovery context.`,
+                "warning",
+              );
+            }
+          }
+        }
+      }
+    }
+    ctx.ui.notify(
+      `${unitType} ${unitId} didn't produce expected artifact. Retrying (${prevCount + 1}/${MAX_UNIT_DISPATCHES}).`,
+      "warning",
+    );
+  }
+
+  return { action: "proceed" };
+}

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

@@ -0,0 +1,223 @@
+/**
+ * Unit supervision timers — soft timeout warning, idle watchdog,
+ * hard timeout, and context-pressure monitor.
+ *
+ * Extracted from dispatchNextUnit() in auto.ts. All timers are set up
+ * via startUnitSupervision() and torn down by the caller via clearUnitTimeout().
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "./unit-runtime.js";
+import { resolveAutoSupervisorConfig } from "./preferences.js";
+import type { GSDPreferences } from "./preferences.js";
+import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
+import {
+  getInFlightToolCount,
+  getOldestInFlightToolStart,
+} from "./auto-tool-tracking.js";
+import { detectWorkingTreeActivity } from "./auto-supervisor.js";
+import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
+import { saveActivityLog } from "./activity-log.js";
+import { recoverTimedOutUnit, type RecoveryContext } from "./auto-timeout-recovery.js";
+import type { AutoSession } from "./auto/session.js";
+
+export interface SupervisionContext {
+  s: AutoSession;
+  ctx: ExtensionContext;
+  pi: ExtensionAPI;
+  unitType: string;
+  unitId: string;
+  prefs: GSDPreferences | undefined;
+  buildSnapshotOpts: () => CloseoutOptions & Record<string, unknown>;
+  buildRecoveryContext: () => RecoveryContext;
+  pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>;
+}
+
+/**
+ * Set up all four supervision timers for the current unit:
+ * 1. Soft timeout warning (wrapup)
+ * 2. Idle watchdog (progress polling, stuck tool detection)
+ * 3. Hard timeout (pause + recovery)
+ * 4. Context-pressure monitor (continue-here)
+ */
+export function startUnitSupervision(sctx: SupervisionContext): void {
+  const { s, ctx, pi, unitType, unitId, prefs, buildSnapshotOpts, buildRecoveryContext, pauseAuto } = sctx;
+
+  const supervisor = resolveAutoSupervisorConfig();
+  const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000;
+  const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;
+  const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000;
+
+  // ── 1. Soft timeout warning ──
+  s.wrapupWarningHandle = setTimeout(() => {
+    s.wrapupWarningHandle = null;
+    if (!s.active || !s.currentUnit) return;
+    writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+      phase: "wrapup-warning-sent",
+      wrapupWarningSent: true,
+    });
+    pi.sendMessage(
+      {
+        customType: "gsd-auto-wrapup",
+        display: s.verbose,
+        content: [
+          "**TIME BUDGET WARNING — keep going only if progress is real.**",
+          "This unit crossed the soft time budget.",
+          "If you are making progress, continue. If not, switch to wrap-up mode now:",
+          "1. rerun the minimal required verification",
+          "2. write or update the required durable artifacts",
+          "3. mark task or slice state on disk correctly",
+          "4. leave precise resume notes if anything remains unfinished",
+        ].join("\n"),
+      },
+      { triggerTurn: true },
+    );
+  }, softTimeoutMs);
+
+  // ── 2. Idle watchdog ──
+  s.idleWatchdogHandle = setInterval(async () => {
+    try {
+      if (!s.active || !s.currentUnit) return;
+      const runtime = readUnitRuntimeRecord(s.basePath, unitType, unitId);
+      if (!runtime) return;
+      if (Date.now() - runtime.lastProgressAt < idleTimeoutMs) return;
+
+      // Agent has tool calls currently executing — not idle, just waiting.
+      // But only suppress recovery if the tool started recently.
+      if (getInFlightToolCount() > 0) {
+        const oldestStart = getOldestInFlightToolStart()!;
+        const toolAgeMs = Date.now() - oldestStart;
+        if (toolAgeMs < idleTimeoutMs) {
+          writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+            lastProgressAt: Date.now(),
+            lastProgressKind: "tool-in-flight",
+          });
+          return;
+        }
+        ctx.ui.notify(
+          `Stalled tool detected: a tool has been in-flight for ${Math.round(toolAgeMs / 60000)}min. Treating as hung — attempting idle recovery.`,
+          "warning",
+        );
+      }
+
+      // Check if the agent is producing work on disk.
+      if (detectWorkingTreeActivity(s.basePath)) {
+        writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+          lastProgressAt: Date.now(),
+          lastProgressKind: "filesystem-activity",
+        });
+        return;
+      }
+
+      if (s.currentUnit) {
+        await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts());
+      } else {
+        saveActivityLog(ctx, s.basePath, unitType, unitId);
+      }
+
+      const recovery = await recoverTimedOutUnit(ctx, pi, unitType, unitId, "idle", buildRecoveryContext());
+      if (recovery === "recovered") return;
+
+      writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+        phase: "paused",
+      });
+      ctx.ui.notify(
+        `Unit ${unitType} ${unitId} made no meaningful progress for ${supervisor.idle_timeout_minutes}min. Pausing auto-mode.`,
+        "warning",
+      );
+      await pauseAuto(ctx, pi);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[idle-watchdog] Unhandled error: ${message}`);
+      try {
+        ctx.ui.notify(`Idle watchdog error: ${message}`, "warning");
+      } catch { /* best effort */ }
+    }
+  }, 15000);
+
+  // ── 3. Hard timeout ──
+  s.unitTimeoutHandle = setTimeout(async () => {
+    try {
+      s.unitTimeoutHandle = null;
+      if (!s.active) return;
+      if (s.currentUnit) {
+        writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+          phase: "timeout",
+          timeoutAt: Date.now(),
+        });
+        await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts());
+      } else {
+        saveActivityLog(ctx, s.basePath, unitType, unitId);
+      }
+
+      const recovery = await recoverTimedOutUnit(ctx, pi, unitType, unitId, "hard", buildRecoveryContext());
+      if (recovery === "recovered") return;
+
+      ctx.ui.notify(
+        `Unit ${unitType} ${unitId} exceeded ${supervisor.hard_timeout_minutes}min hard timeout. Pausing auto-mode.`,
+        "warning",
+      );
+      await pauseAuto(ctx, pi);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[hard-timeout] Unhandled error: ${message}`);
+      try {
+        ctx.ui.notify(`Hard timeout error: ${message}`, "warning");
+      } catch { /* best effort */ }
+    }
+  }, hardTimeoutMs);
+
+  // ── 4. Context-pressure continue-here monitor ──
+  if (s.continueHereHandle) {
+    clearInterval(s.continueHereHandle);
+    s.continueHereHandle = null;
+  }
+  const executorContextWindow = resolveExecutorContextWindow(
+    ctx.modelRegistry as Parameters<typeof resolveExecutorContextWindow>[0],
+    prefs as Parameters<typeof resolveExecutorContextWindow>[1],
+    ctx.model?.contextWindow,
+  );
+  const continueHereThreshold = computeBudgets(executorContextWindow).continueThresholdPercent;
+  s.continueHereHandle = setInterval(() => {
+    if (!s.active || !s.currentUnit || !s.cmdCtx) return;
+    const runtime = readUnitRuntimeRecord(s.basePath, unitType, unitId);
+    if (runtime?.continueHereFired) return;
+
+    const contextUsage = s.cmdCtx.getContextUsage();
+    if (!contextUsage || contextUsage.percent == null || contextUsage.percent < continueHereThreshold) return;
+
+    writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit!.startedAt, {
+      continueHereFired: true,
+    });
+
+    if (s.verbose) {
+      ctx.ui.notify(
+        `Context at ${contextUsage.percent}% (threshold: ${continueHereThreshold}%) — sending wrap-up signal.`,
+        "info",
+      );
+    }
+
+    pi.sendMessage(
+      {
+        customType: "gsd-auto-wrapup",
+        display: s.verbose,
+        content: [
+          "**CONTEXT BUDGET WARNING — wrap up this unit now.**",
+          `Context window is at ${contextUsage.percent}% (threshold: ${continueHereThreshold}%).`,
+          "The next unit needs a fresh context to work effectively. Wrap up now:",
+          "1. Finish any in-progress file writes",
+          "2. Write or update the required durable artifacts (summary, checkboxes)",
+          "3. Mark task state on disk correctly",
+          "4. Leave precise resume notes if anything remains unfinished",
+          "Do NOT start new sub-tasks or investigations.",
+        ].join("\n"),
+      },
+      { triggerTurn: true },
+    );
+
+    if (s.continueHereHandle) {
+      clearInterval(s.continueHereHandle);
+      s.continueHereHandle = null;
+    }
+  }, 15_000);
+}

package/dist/resources/extensions/gsd/auto-unit-closeout.ts

@@ -37,7 +37,9 @@ export async function closeoutUnit(
       const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import('./memory-extractor.js');
       const llmCallFn = buildMemoryLLMCall(ctx);
       if (llmCallFn) {
-        extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn).catch(() => {});
+        extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn).catch((err) => {
+          if (process.env.GSD_DEBUG) console.error(`[gsd] memory extraction failed for ${unitType}/${unitId}:`, err);
+        });
       }
     } catch { /* non-fatal */ }
   }

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

@@ -0,0 +1,229 @@
+/**
+ * Post-unit verification gate for auto-mode.
+ *
+ * Runs typecheck/lint/test checks, captures runtime errors, performs
+ * dependency audits, handles auto-fix retry logic, and writes
+ * verification evidence JSON.
+ *
+ * Extracted from handleAgentEnd() in auto.ts. Returns a sentinel
+ * value instead of calling return/pauseAuto directly — the caller
+ * checks the result and handles control flow.
+ */
+
+import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
+import { loadFile, parsePlan } from "./files.js";
+import { resolveSliceFile, resolveSlicePath } from "./paths.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import {
+  runVerificationGate,
+  formatFailureContext,
+  captureRuntimeErrors,
+  runDependencyAudit,
+} from "./verification-gate.js";
+import { writeVerificationJSON } from "./verification-evidence.js";
+import { removePersistedKey } from "./auto-recovery.js";
+import type { AutoSession, PendingVerificationRetry } from "./auto/session.js";
+import { join } from "node:path";
+
+export interface VerificationContext {
+  s: AutoSession;
+  ctx: ExtensionContext;
+  pi: ExtensionAPI;
+}
+
+export type VerificationResult = "continue" | "retry" | "pause";
+
+/**
+ * Run the verification gate for the current execute-task unit.
+ * Returns:
+ * - "continue" — gate passed (or no checks configured), proceed normally
+ * - "retry" — gate failed with retries remaining, dispatchNextUnit already called
+ * - "pause" — gate failed with retries exhausted, pauseAuto already called
+ */
+export async function runPostUnitVerification(
+  vctx: VerificationContext,
+  dispatchNextUnit: (ctx: ExtensionContext, pi: ExtensionAPI) => Promise<void>,
+  startDispatchGapWatchdog: (ctx: ExtensionContext, pi: ExtensionAPI) => void,
+  pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>,
+): Promise<VerificationResult> {
+  const { s, ctx, pi } = vctx;
+
+  if (!s.currentUnit || s.currentUnit.type !== "execute-task") {
+    return "continue";
+  }
+
+  try {
+    const effectivePrefs = loadEffectiveGSDPreferences();
+    const prefs = effectivePrefs?.preferences;
+
+    // Read task plan verify field
+    const parts = s.currentUnit.id.split("/");
+    let taskPlanVerify: string | undefined;
+    if (parts.length >= 3) {
+      const [mid, sid, tid] = parts;
+      const planFile = resolveSliceFile(s.basePath, mid, sid, "PLAN");
+      if (planFile) {
+        const planContent = await loadFile(planFile);
+        if (planContent) {
+          const slicePlan = parsePlan(planContent);
+          const taskEntry = slicePlan?.tasks?.find(t => t.id === tid);
+          taskPlanVerify = taskEntry?.verify;
+        }
+      }
+    }
+
+    const result = runVerificationGate({
+      basePath: s.basePath,
+      unitId: s.currentUnit.id,
+      cwd: s.basePath,
+      preferenceCommands: prefs?.verification_commands,
+      taskPlanVerify,
+    });
+
+    // Capture runtime errors
+    const runtimeErrors = await captureRuntimeErrors();
+    if (runtimeErrors.length > 0) {
+      result.runtimeErrors = runtimeErrors;
+      if (runtimeErrors.some(e => e.blocking)) {
+        result.passed = false;
+      }
+    }
+
+    // Dependency audit
+    const auditWarnings = runDependencyAudit(s.basePath);
+    if (auditWarnings.length > 0) {
+      result.auditWarnings = auditWarnings;
+      process.stderr.write(`verification-gate: ${auditWarnings.length} audit warning(s)\n`);
+      for (const w of auditWarnings) {
+        process.stderr.write(`  [${w.severity}] ${w.name}: ${w.title}\n`);
+      }
+    }
+
+    // Auto-fix retry preferences
+    const autoFixEnabled = prefs?.verification_auto_fix !== false;
+    const maxRetries = typeof prefs?.verification_max_retries === "number" ? prefs.verification_max_retries : 2;
+    const completionKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
+
+    if (result.checks.length > 0) {
+      const blockingChecks = result.checks.filter(c => c.blocking);
+      const advisoryChecks = result.checks.filter(c => !c.blocking);
+      const blockingPassCount = blockingChecks.filter(c => c.exitCode === 0).length;
+      const advisoryFailCount = advisoryChecks.filter(c => c.exitCode !== 0).length;
+
+      if (result.passed) {
+        let msg = blockingChecks.length > 0
+          ? `Verification gate: ${blockingPassCount}/${blockingChecks.length} blocking checks passed`
+          : `Verification gate: passed (no blocking checks)`;
+        if (advisoryFailCount > 0) {
+          msg += ` (${advisoryFailCount} advisory warning${advisoryFailCount > 1 ? "s" : ""})`;
+        }
+        ctx.ui.notify(msg);
+        // Log advisory warnings to stderr for visibility
+        if (advisoryFailCount > 0) {
+          const advisoryFailures = advisoryChecks.filter(c => c.exitCode !== 0);
+          process.stderr.write(`verification-gate: ${advisoryFailCount} advisory (non-blocking) failure(s)\n`);
+          for (const f of advisoryFailures) {
+            process.stderr.write(`  [advisory] ${f.command} exited ${f.exitCode}\n`);
+          }
+        }
+      } else {
+        const blockingFailures = blockingChecks.filter(c => c.exitCode !== 0);
+        const failNames = blockingFailures.map(f => f.command).join(", ");
+        ctx.ui.notify(`Verification gate: FAILED — ${failNames}`);
+        process.stderr.write(`verification-gate: ${blockingFailures.length}/${blockingChecks.length} blocking checks failed\n`);
+        for (const f of blockingFailures) {
+          process.stderr.write(`  ${f.command} exited ${f.exitCode}\n`);
+          if (f.stderr) process.stderr.write(`  stderr: ${f.stderr.slice(0, 500)}\n`);
+        }
+        if (advisoryFailCount > 0) {
+          process.stderr.write(`verification-gate: ${advisoryFailCount} additional advisory (non-blocking) failure(s)\n`);
+        }
+      }
+    }
+
+    // Log blocking runtime errors
+    if (result.runtimeErrors?.some(e => e.blocking)) {
+      const blockingErrors = result.runtimeErrors.filter(e => e.blocking);
+      process.stderr.write(`verification-gate: ${blockingErrors.length} blocking runtime error(s) detected\n`);
+      for (const err of blockingErrors) {
+        process.stderr.write(`  [${err.source}] ${err.severity}: ${err.message.slice(0, 200)}\n`);
+      }
+    }
+
+    // Write verification evidence JSON
+    const attempt = s.verificationRetryCount.get(s.currentUnit.id) ?? 0;
+    if (parts.length >= 3) {
+      try {
+        const [mid, sid, tid] = parts;
+        const sDir = resolveSlicePath(s.basePath, mid, sid);
+        if (sDir) {
+          const tasksDir = join(sDir, "tasks");
+          if (result.passed) {
+            writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id);
+          } else {
+            const nextAttempt = attempt + 1;
+            writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, nextAttempt, maxRetries);
+          }
+        }
+      } catch (evidenceErr) {
+        process.stderr.write(`verification-evidence: write error — ${(evidenceErr as Error).message}\n`);
+      }
+    }
+
+    // ── Auto-fix retry logic ──
+    if (result.passed) {
+      s.verificationRetryCount.delete(s.currentUnit.id);
+      s.pendingVerificationRetry = null;
+      return "continue";
+    } else if (result.discoverySource === "package-json") {
+      // Auto-discovered checks from package.json may fail on pre-existing errors
+      // that the current task didn't introduce. Don't trigger the retry loop —
+      // log a warning and let the task proceed (#1186).
+      process.stderr.write(
+        `verification-gate: auto-discovered checks failed (source: package-json) — treating as advisory, not blocking\n`,
+      );
+      ctx.ui.notify(
+        `Verification: auto-discovered checks failed (pre-existing errors likely). Continuing without retry.`,
+        "warning",
+      );
+      s.verificationRetryCount.delete(s.currentUnit.id);
+      s.pendingVerificationRetry = null;
+      return "continue";
+    } else if (autoFixEnabled && attempt + 1 <= maxRetries) {
+      const nextAttempt = attempt + 1;
+      s.verificationRetryCount.set(s.currentUnit.id, nextAttempt);
+      s.pendingVerificationRetry = {
+        unitId: s.currentUnit.id,
+        failureContext: formatFailureContext(result),
+        attempt: nextAttempt,
+      };
+      ctx.ui.notify(`Verification failed — auto-fix attempt ${nextAttempt}/${maxRetries}`, "warning");
+      s.completedKeySet.delete(completionKey);
+      removePersistedKey(s.basePath, completionKey);
+      // Dispatch retry immediately
+      try {
+        await dispatchNextUnit(ctx, pi);
+      } catch (retryDispatchErr) {
+        const msg = retryDispatchErr instanceof Error ? retryDispatchErr.message : String(retryDispatchErr);
+        ctx.ui.notify(`Verification retry dispatch error: ${msg}`, "error");
+        startDispatchGapWatchdog(ctx, pi);
+      }
+      return "retry";
+    } else {
+      // Gate failed, retries exhausted
+      const exhaustedAttempt = attempt + 1;
+      s.verificationRetryCount.delete(s.currentUnit.id);
+      s.pendingVerificationRetry = null;
+      ctx.ui.notify(
+        `Verification gate FAILED after ${exhaustedAttempt > maxRetries ? exhaustedAttempt - 1 : exhaustedAttempt} retries — pausing for human review`,
+        "error",
+      );
+      await pauseAuto(ctx, pi);
+      return "pause";
+    }
+  } catch (err) {
+    // Gate errors are non-fatal
+    process.stderr.write(`verification-gate: error — ${(err as Error).message}\n`);
+    return "continue";
+  }
+}