gsd-pi 2.80.0 → 2.81.0-dev.72a81bdf3

package/src/resources/extensions/gsd/state-reconciliation/drift/project-md.ts

@@ -0,0 +1,69 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 unregistered-milestone drift handler. Detects
+// milestones whose on-disk directory has meaningful content (ROADMAP/
+// CONTEXT/SUMMARY) but no DB row, then runs the markdown importer to
+// reconcile. PROJECT.md is the human-facing index — the importer's source
+// of truth is the .gsd/milestones/ directory tree.
+
+import { existsSync } from "node:fs";
+
+import { getMilestone, isDbAvailable } from "../../gsd-db.js";
+import { migrateHierarchyToDb } from "../../md-importer.js";
+import { findMilestoneIds } from "../../milestone-ids.js";
+import { resolveMilestoneFile } from "../../paths.js";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type UnregisteredMilestoneDrift = Extract<
+  DriftRecord,
+  { kind: "unregistered-milestone" }
+>;
+
+function milestoneHasContent(basePath: string, milestoneId: string): boolean {
+  const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  const context = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+  const summary = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+  return (
+    (roadmap !== null && existsSync(roadmap)) ||
+    (context !== null && existsSync(context)) ||
+    (summary !== null && existsSync(summary))
+  );
+}
+
+export function detectUnregisteredMilestoneDrift(
+  _state: GSDState,
+  ctx: DriftContext,
+): UnregisteredMilestoneDrift[] {
+  if (!isDbAvailable()) return [];
+
+  const drifts: UnregisteredMilestoneDrift[] = [];
+  for (const milestoneId of findMilestoneIds(ctx.basePath)) {
+    if (getMilestone(milestoneId)) continue;
+    if (!milestoneHasContent(ctx.basePath, milestoneId)) continue;
+    drifts.push({ kind: "unregistered-milestone", milestoneId });
+  }
+  return drifts;
+}
+
+/**
+ * Repair: invoke the markdown importer. migrateHierarchyToDb walks the same
+ * findMilestoneIds list the detector uses and INSERTs OR IGNOREs every
+ * missing milestone (and its slices/tasks) — idempotent under cap=2 retry.
+ *
+ * Note: even though we receive one record at a time, the importer is a
+ * project-wide operation. Repeated invocation across multiple drift records
+ * in the same pass is wasteful but safe; a future optimization could
+ * coalesce by checking whether the importer has already run this pass.
+ */
+export function repairUnregisteredMilestone(
+  _record: UnregisteredMilestoneDrift,
+  ctx: DriftContext,
+): void {
+  migrateHierarchyToDb(ctx.basePath);
+}
+
+export const unregisteredMilestoneHandler: DriftHandler<UnregisteredMilestoneDrift> = {
+  kind: "unregistered-milestone",
+  detect: detectUnregisteredMilestoneDrift,
+  repair: repairUnregisteredMilestone,
+};

package/src/resources/extensions/gsd/state-reconciliation/drift/roadmap.ts

@@ -0,0 +1,109 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 roadmap-divergence drift handler. Detects mismatches
+// between ROADMAP.md (parsed slice sequence + depends declarations) and the
+// DB slice rows for that milestone, then reconciles via the markdown
+// importer plus an explicit junction-table sync.
+
+import { existsSync, readFileSync } from "node:fs";
+
+import {
+  getMilestone,
+  getMilestoneSlices,
+  isDbAvailable,
+  syncSliceDependencies,
+} from "../../gsd-db.js";
+import { migrateHierarchyToDb } from "../../md-importer.js";
+import { findMilestoneIds } from "../../milestone-ids.js";
+import { parseRoadmap } from "../../parsers-legacy.js";
+import { resolveMilestoneFile } from "../../paths.js";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type RoadmapDivergenceDrift = Extract<
+  DriftRecord,
+  { kind: "roadmap-divergence" }
+>;
+
+function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+function milestoneHasDivergence(
+  basePath: string,
+  milestoneId: string,
+): boolean {
+  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (!roadmapPath || !existsSync(roadmapPath)) return false;
+
+  let roadmap: ReturnType<typeof parseRoadmap>;
+  try {
+    roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+  } catch {
+    return false;
+  }
+
+  const dbSlices = getMilestoneSlices(milestoneId);
+  const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+
+  for (let i = 0; i < roadmap.slices.length; i++) {
+    const roadmapSlice = roadmap.slices[i]!;
+    const expectedSequence = i + 1;
+    const dbSlice = dbSliceMap.get(roadmapSlice.id);
+    if (!dbSlice) return true; // Roadmap has a slice the DB doesn't.
+    if (dbSlice.sequence !== expectedSequence) return true;
+    if (!arraysEqual(dbSlice.depends, roadmapSlice.depends)) return true;
+  }
+  return false;
+}
+
+export function detectRoadmapDivergenceDrift(
+  _state: GSDState,
+  ctx: DriftContext,
+): RoadmapDivergenceDrift[] {
+  if (!isDbAvailable()) return [];
+
+  const drifts: RoadmapDivergenceDrift[] = [];
+  for (const milestoneId of findMilestoneIds(ctx.basePath)) {
+    // Skip milestones that don't yet have a DB row — that's the
+    // unregistered-milestone drift handler's responsibility.
+    if (!getMilestone(milestoneId)) continue;
+    if (milestoneHasDivergence(ctx.basePath, milestoneId)) {
+      drifts.push({ kind: "roadmap-divergence", milestoneId });
+    }
+  }
+  return drifts;
+}
+
+/**
+ * Repair a milestone's roadmap divergence:
+ *   1. migrateHierarchyToDb upserts slice rows (sequence + depends JSON
+ *      update via ON CONFLICT DO UPDATE).
+ *   2. syncSliceDependencies updates the junction table per slice — the
+ *      importer only writes the JSON column, not the relational view.
+ */
+export function repairRoadmapDivergence(
+  record: RoadmapDivergenceDrift,
+  ctx: DriftContext,
+): void {
+  migrateHierarchyToDb(ctx.basePath);
+
+  const roadmapPath = resolveMilestoneFile(ctx.basePath, record.milestoneId, "ROADMAP");
+  if (!roadmapPath || !existsSync(roadmapPath)) return;
+
+  try {
+    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+    for (const slice of roadmap.slices) {
+      syncSliceDependencies(record.milestoneId, slice.id, slice.depends);
+    }
+  } catch {
+    /* parse failure: detector will fire again next pass */
+  }
+}
+
+export const roadmapDivergenceHandler: DriftHandler<RoadmapDivergenceDrift> = {
+  kind: "roadmap-divergence",
+  detect: detectRoadmapDivergenceDrift,
+  repair: repairRoadmapDivergence,
+};

package/src/resources/extensions/gsd/state-reconciliation/drift/sketch-flag.ts

@@ -0,0 +1,68 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-sketch-flag drift handler. Relocated from
+// gsd-db.ts where autoHealSketchFlags previously lived with zero callers.
+//
+// Recovers from two scenarios (per ADR-011):
+//   1. Crash between gsd_plan_slice's PLAN.md write and the sketch flag flip.
+//   2. Flag-OFF downgrade: when progressive_planning is off, dispatch routes
+//      sketch slices to plan-slice, which writes PLAN.md but leaves
+//      is_sketch=1 — the next reconciliation pass clears it.
+
+import { existsSync } from "node:fs";
+
+import {
+  getSketchedSliceIds,
+  isDbAvailable,
+  setSliceSketchFlag,
+} from "../../gsd-db.js";
+import { resolveSliceFile } from "../../paths.js";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type SketchFlagDrift = Extract<DriftRecord, { kind: "stale-sketch-flag" }>;
+
+export function detectStaleSketchFlags(
+  state: GSDState,
+  ctx: DriftContext,
+): SketchFlagDrift[] {
+  if (!isDbAvailable()) return [];
+  const mid = state.activeMilestone?.id;
+  if (!mid) return [];
+
+  const sliceIds = getSketchedSliceIds(mid);
+  return sliceIds
+    .filter((sid) => {
+      const planPath = resolveSliceFile(ctx.basePath, mid, sid, "PLAN");
+      return planPath !== null && existsSync(planPath);
+    })
+    .map((sid) => ({ kind: "stale-sketch-flag" as const, mid, sid }));
+}
+
+export function repairStaleSketchFlag(record: SketchFlagDrift): void {
+  setSliceSketchFlag(record.mid, record.sid, false);
+}
+
+export const sketchFlagHandler: DriftHandler<SketchFlagDrift> = {
+  kind: "stale-sketch-flag",
+  detect: detectStaleSketchFlags,
+  repair: (record) => {
+    repairStaleSketchFlag(record);
+  },
+};
+
+/**
+ * Legacy entry point preserved for callers that supply a custom hasPlanFile
+ * predicate. Prefer the drift handler (sketchFlagHandler) for new code.
+ */
+export function autoHealSketchFlags(
+  milestoneId: string,
+  hasPlanFile: (sliceId: string) => boolean,
+): void {
+  if (!isDbAvailable()) return;
+  const sliceIds = getSketchedSliceIds(milestoneId);
+  for (const sid of sliceIds) {
+    if (hasPlanFile(sid)) {
+      setSliceSketchFlag(milestoneId, sid, false);
+    }
+  }
+}

package/src/resources/extensions/gsd/state-reconciliation/drift/stale-render.ts

@@ -0,0 +1,185 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-render drift handler. Relocated from
+// markdown-renderer.ts as part of issue #5702. detectStaleRenders stays in
+// markdown-renderer.ts (it's a useful diagnostic primitive on its own); only
+// the detect+repair composition moves here. The previous repairStaleRenders
+// had zero callers in production code — wiring it through
+// reconcileBeforeDispatch closes that gap.
+
+import {
+  detectStaleRenders,
+  renderPlanCheckboxes,
+  renderRoadmapCheckboxes,
+  renderSliceSummary,
+  renderTaskSummary,
+} from "../../markdown-renderer.js";
+import type { GSDState } from "../../types.js";
+import { logWarning } from "../../workflow-logger.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type StaleRenderDrift = Extract<DriftRecord, { kind: "stale-render" }>;
+
+// ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
+
+function detectStaleRenderDriftFromBasePath(basePath: string): StaleRenderDrift[] {
+  const entries = detectStaleRenders(basePath);
+  if (entries.length === 0) return [];
+
+  // detectStaleRenders may emit multiple entries for the same path (one per
+  // mismatched checkbox). Dedupe by path; the repair re-renders the whole
+  // file in a single call. Prefer a reason the repair dispatcher can handle.
+  const seen = new Map<string, string>();
+  for (const entry of entries) {
+    const currentReason = seen.get(entry.path);
+    if (
+      currentReason === undefined ||
+      (!isRepairableStaleRenderReason(currentReason) && isRepairableStaleRenderReason(entry.reason))
+    ) {
+      seen.set(entry.path, entry.reason);
+    }
+  }
+
+  return Array.from(seen.entries()).map(([renderPath, reason]) => ({
+    kind: "stale-render" as const,
+    renderPath,
+    reason,
+  }));
+}
+
+function isRepairableStaleRenderReason(reason: string): boolean {
+  return (
+    reason.includes("in roadmap") ||
+    reason.includes("in plan") ||
+    (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) ||
+    (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
+    reason.includes("UAT.md missing")
+  );
+}
+
+async function repairStaleRenderFromBasePath(
+  record: StaleRenderDrift,
+  basePath: string,
+): Promise<void> {
+  const normPath = record.renderPath.replace(/\\/g, "/");
+  const reason = record.reason;
+
+  if (reason.includes("in roadmap")) {
+    const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+    if (!milestoneMatch) {
+      throw new Error(
+        `stale-render drift: roadmap path missing milestone segment: ${record.renderPath}`,
+      );
+    }
+    await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
+    return;
+  }
+
+  if (reason.includes("in plan")) {
+    const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+    if (!pathMatch) {
+      throw new Error(
+        `stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`,
+      );
+    }
+    await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
+    return;
+  }
+
+  if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
+    const pathMatch = normPath.match(
+      /milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//,
+    );
+    const taskMatch = reason.match(/^(T\d+)/);
+    if (!pathMatch || !taskMatch) {
+      throw new Error(
+        `stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`,
+      );
+    }
+    await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
+    return;
+  }
+
+  if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
+    const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+    if (!pathMatch) {
+      throw new Error(
+        `stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`,
+      );
+    }
+    await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+    return;
+  }
+
+  if (reason.includes("UAT.md missing")) {
+    const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+    if (!pathMatch) {
+      throw new Error(
+        `stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`,
+      );
+    }
+    // renderSliceSummary handles both SUMMARY and UAT.
+    await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+    return;
+  }
+
+  throw new Error(
+    `stale-render drift: detector emitted unknown reason "${reason}" for ${record.renderPath}`,
+  );
+}
+
+// ─── Drift Handler API ───────────────────────────────────────────────────────
+
+export function detectStaleRenderDrift(
+  _state: GSDState,
+  ctx: DriftContext,
+): StaleRenderDrift[] {
+  return detectStaleRenderDriftFromBasePath(ctx.basePath);
+}
+
+export async function repairStaleRender(
+  record: StaleRenderDrift,
+  ctx: DriftContext,
+): Promise<void> {
+  await repairStaleRenderFromBasePath(record, ctx.basePath);
+}
+
+export const staleRenderHandler: DriftHandler<StaleRenderDrift> = {
+  kind: "stale-render",
+  detect: detectStaleRenderDrift,
+  repair: repairStaleRender,
+};
+
+// ─── Legacy entry point ──────────────────────────────────────────────────────
+
+/**
+ * Legacy bulk entry preserved for existing tests
+ * (tests/markdown-renderer.test.ts, tests/integration/integration-proof.test.ts).
+ * New code prefers the drift handler via `reconcileBeforeDispatch`. Matches the
+ * pre-ADR-017 behavior: silent per-entry error handling, returns the count of
+ * successful repairs.
+ */
+export async function repairStaleRenders(basePath: string): Promise<number> {
+  const drifts = detectStaleRenderDriftFromBasePath(basePath);
+  if (drifts.length === 0) return 0;
+
+  let repaired = 0;
+  for (const drift of drifts) {
+    try {
+      await repairStaleRenderFromBasePath(drift, basePath);
+      repaired++;
+    } catch (err) {
+      logWarning(
+        "renderer",
+        `repair failed for ${drift.renderPath}: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  if (repaired > 0) {
+    process.stderr.write(
+      `markdown-renderer: repaired ${repaired} stale render(s)\n`,
+    );
+  }
+
+  return repaired;
+}

package/src/resources/extensions/gsd/state-reconciliation/drift/stale-worker.ts

@@ -0,0 +1,46 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-worker drift handler. Detects session-lock
+// artifacts whose owning PID is no longer alive (typical after SIGKILL or
+// laptop sleep where the heartbeat wasn't released cleanly), and clears them
+// before the next dispatch attempts to acquire the lock.
+
+import {
+  effectiveLockFile,
+  isSessionLockProcessAlive,
+  readSessionLockData,
+  removeStaleSessionLock,
+} from "../../session-lock.js";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type StaleWorkerDrift = Extract<DriftRecord, { kind: "stale-worker" }>;
+
+export function detectStaleWorkerDrift(
+  _state: GSDState,
+  ctx: DriftContext,
+): StaleWorkerDrift[] {
+  const data = readSessionLockData(ctx.basePath);
+  if (!data) return [];
+  if (typeof data.pid !== "number") return [];
+  if (isSessionLockProcessAlive(data)) return [];
+
+  return [
+    {
+      kind: "stale-worker",
+      lockPath: effectiveLockFile(),
+      pid: data.pid,
+    },
+  ];
+}
+
+export function repairStaleWorker(_record: StaleWorkerDrift, ctx: DriftContext): void {
+  // removeStaleSessionLock is idempotent: it re-reads lock state and is a
+  // no-op when the lock is held by an alive process. Safe under cap=2 retry.
+  removeStaleSessionLock(ctx.basePath);
+}
+
+export const staleWorkerHandler: DriftHandler<StaleWorkerDrift> = {
+  kind: "stale-worker",
+  detect: detectStaleWorkerDrift,
+  repair: repairStaleWorker,
+};

package/src/resources/extensions/gsd/state-reconciliation/errors.ts

@@ -0,0 +1,67 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 typed reconciliation failure for Recovery Classification.
+
+import type { DriftRecord } from "./types.js";
+
+export interface ReconciliationFailureDetail {
+  drift: DriftRecord;
+  cause: unknown;
+}
+
+export interface ReconciliationDetectionFailureDetail {
+  handlerKind: string;
+  phase: "detect";
+  basePath: string;
+  statePhase?: string;
+  activeMilestoneId?: string;
+  cause: unknown;
+}
+
+export interface ReconciliationFailedErrorOptions {
+  failures?: ReadonlyArray<ReconciliationFailureDetail>;
+  detectionFailures?: ReadonlyArray<ReconciliationDetectionFailureDetail>;
+  persistentDrift?: ReadonlyArray<DriftRecord>;
+  pass?: number;
+}
+
+/**
+ * Thrown by reconcileBeforeDispatch when:
+ *   - one or more repair functions throw within a pass (`failures` populated), or
+ *   - drift persists after the cap=2 lifecycle (`persistentDrift` populated).
+ *
+ * Recovery Classification recognizes this error via instanceof and maps it to
+ * failureKind "reconciliation-drift" with action "escalate".
+ */
+export class ReconciliationFailedError extends Error {
+  readonly failures: ReadonlyArray<ReconciliationFailureDetail>;
+  readonly detectionFailures: ReadonlyArray<ReconciliationDetectionFailureDetail>;
+  readonly persistentDrift: ReadonlyArray<DriftRecord>;
+  readonly pass?: number;
+
+  constructor(opts: ReconciliationFailedErrorOptions) {
+    super(formatMessage(opts));
+    this.name = "ReconciliationFailedError";
+    this.failures = opts.failures ?? [];
+    this.detectionFailures = opts.detectionFailures ?? [];
+    this.persistentDrift = opts.persistentDrift ?? [];
+    this.pass = opts.pass;
+  }
+}
+
+function formatMessage(opts: ReconciliationFailedErrorOptions): string {
+  if (opts.detectionFailures && opts.detectionFailures.length > 0) {
+    const kinds = opts.detectionFailures.map((f) => f.handlerKind).join(", ");
+    const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+    return `Reconciliation detect failed${passSuffix} for handlers: ${kinds}`;
+  }
+  if (opts.failures && opts.failures.length > 0) {
+    const kinds = opts.failures.map((f) => f.drift.kind).join(", ");
+    const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+    return `Reconciliation repair failed${passSuffix} for drift kinds: ${kinds}`;
+  }
+  if (opts.persistentDrift && opts.persistentDrift.length > 0) {
+    const kinds = opts.persistentDrift.map((d) => d.kind).join(", ");
+    return `Reconciliation drift persisted after cap=2 passes: ${kinds}`;
+  }
+  return "Reconciliation failed";
+}

package/src/resources/extensions/gsd/state-reconciliation/index.ts

@@ -0,0 +1,142 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 drift-driven State Reconciliation Module entry point.
+// reconcileBeforeDispatch runs before every Dispatch decision and worker spawn.
+
+import {
+  deriveState as defaultDeriveState,
+  invalidateStateCache as defaultInvalidate,
+} from "../state.js";
+import type { GSDState } from "../types.js";
+
+import {
+  ReconciliationFailedError,
+  type ReconciliationFailureDetail,
+} from "./errors.js";
+import { DRIFT_REGISTRY } from "./registry.js";
+import type {
+  DriftContext,
+  DriftHandler,
+  DriftRecord,
+  ReconciliationDeps,
+  ReconciliationResult,
+} from "./types.js";
+
+export type {
+  DriftContext,
+  DriftHandler,
+  DriftRecord,
+  ReconciliationDeps,
+  ReconciliationResult,
+} from "./types.js";
+export { ReconciliationFailedError } from "./errors.js";
+export type { ReconciliationFailureDetail } from "./errors.js";
+export { DRIFT_REGISTRY } from "./registry.js";
+
+const MAX_PASSES = 2;
+
+const defaultDeps: ReconciliationDeps = {
+  invalidateStateCache: defaultInvalidate,
+  deriveState: defaultDeriveState,
+};
+
+/**
+ * Drift-driven pre-dispatch reconciliation per ADR-017.
+ *
+ * Lifecycle: derive → detect drift → apply repairs → re-derive. Capped at
+ * MAX_PASSES (=2) cycles. The loop runs only when the prior pass fully
+ * succeeded but re-derive surfaces NEW drift (cascading repairs — e.g.
+ * fixing milestone registration uncovers a downstream completion-timestamp
+ * drift).
+ *
+ * Returns ok=true with `repaired` and terminal `blockers` populated.
+ * Throws ReconciliationFailedError when:
+ *   - any repair function throws within a pass, or
+ *   - drift persists after the cap.
+ */
+export async function reconcileBeforeDispatch(
+  basePath: string,
+  deps: ReconciliationDeps = defaultDeps,
+): Promise<ReconciliationResult> {
+  const registry = deps.registry ?? DRIFT_REGISTRY;
+  const repaired: DriftRecord[] = [];
+
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    deps.invalidateStateCache();
+    const stateSnapshot = await deps.deriveState(basePath, deps.deriveStateOptions);
+    const ctx: DriftContext = { basePath, state: stateSnapshot };
+
+    const drift = await detectAllDrift(stateSnapshot, ctx, registry, pass);
+    if (drift.length === 0) {
+      return {
+        ok: true,
+        stateSnapshot,
+        repaired,
+        blockers: stateSnapshot.blockers ?? [],
+      };
+    }
+
+    const failures: ReconciliationFailureDetail[] = [];
+    for (const record of drift) {
+      const handler = registry.find((h) => h.kind === record.kind);
+      if (!handler) {
+        failures.push({
+          drift: record,
+          cause: new Error(
+            `No drift handler registered for kind "${record.kind}"`,
+          ),
+        });
+        continue;
+      }
+      try {
+        await handler.repair(record, ctx);
+        repaired.push(record);
+      } catch (cause) {
+        failures.push({ drift: record, cause });
+      }
+    }
+
+    if (failures.length > 0) {
+      throw new ReconciliationFailedError({ failures, pass });
+    }
+    // Pass fully succeeded; loop runs again to detect cascading drift.
+  }
+
+  // After MAX_PASSES, one more derive+detect to verify nothing persists.
+  deps.invalidateStateCache();
+  const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
+  const finalCtx: DriftContext = { basePath, state: finalState };
+  const persistent = await detectAllDrift(finalState, finalCtx, registry);
+
+  if (persistent.length > 0) {
+    throw new ReconciliationFailedError({ persistentDrift: persistent });
+  }
+
+  return {
+    ok: true,
+    stateSnapshot: finalState,
+    repaired,
+    blockers: finalState.blockers ?? [],
+  };
+}
+
+async function detectAllDrift(
+  state: GSDState,
+  ctx: DriftContext,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registry: ReadonlyArray<DriftHandler<any>>,
+  pass?: number,
+): Promise<DriftRecord[]> {
+  const collected: DriftRecord[] = [];
+  for (const handler of registry) {
+    try {
+      const detected = await handler.detect(state, ctx);
+      collected.push(...detected);
+    } catch (cause) {
+      throw new ReconciliationFailedError({
+        failures: [{ drift: { kind: handler.kind } as DriftRecord, cause }],
+        pass,
+      });
+    }
+  }
+  return collected;
+}