gsd-pi 2.81.0 → 2.82.0-dev.20138ae42

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;
+}

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

@@ -0,0 +1,27 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 drift handler registry. Single source of truth for
+// the catalog. Tests can override per-call via ReconciliationDeps.registry.
+
+import { completionTimestampHandler } from "./drift/completion.js";
+import { mergeStateHandler } from "./drift/merge-state.js";
+import { unregisteredMilestoneHandler } from "./drift/project-md.js";
+import { roadmapDivergenceHandler } from "./drift/roadmap.js";
+import { sketchFlagHandler } from "./drift/sketch-flag.js";
+import { staleRenderHandler } from "./drift/stale-render.js";
+import { staleWorkerHandler } from "./drift/stale-worker.js";
+import type { DriftHandler } from "./types.js";
+
+// Each handler is parameterized over its specific DriftRecord variant for
+// internal type safety. The registry stores them under DriftHandler<any> so
+// handlers with disjoint repair parameter types coexist; the lifecycle matches
+// by kind before invoking repair, so this is sound at runtime.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const DRIFT_REGISTRY: ReadonlyArray<DriftHandler<any>> = [
+  sketchFlagHandler,
+  mergeStateHandler,
+  staleRenderHandler,
+  staleWorkerHandler,
+  unregisteredMilestoneHandler,
+  roadmapDivergenceHandler,
+  completionTimestampHandler,
+];

package/src/resources/extensions/gsd/state-reconciliation/spawn-gate.ts

@@ -0,0 +1,60 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 #5707 caller-closure helper. Parent processes that
+// spawn auto-loop workers must reconcile before spawn — otherwise each
+// worker independently detects+repairs the same drift, racing on shared
+// state. This helper centralises the reconcile+catch flow so the two
+// production spawn sites (commands/handlers/parallel.ts and auto/phases.ts
+// startSliceParallel) share one contract.
+
+import {
+  reconcileBeforeDispatch,
+  ReconciliationFailedError,
+  type ReconciliationDeps,
+} from "./index.js";
+
+export type SpawnGateResult =
+  | { ok: true; reason?: string }
+  | { ok: false; reason: string };
+
+export interface SpawnGateDeps extends Partial<ReconciliationDeps> {
+  reconcile?: typeof reconcileBeforeDispatch;
+}
+
+/**
+ * Run reconciliation before spawning workers. Returns ok=true when the run
+ * completed without throwing (blockers ride along but don't fail the gate —
+ * spawn callers can choose how to handle them). On
+ * ReconciliationFailedError, returns ok=false with the error message so the
+ * caller can surface it to the user without re-throwing.
+ *
+ * Other unexpected errors propagate; they are not part of the drift
+ * taxonomy.
+ */
+export async function reconcileBeforeSpawn(
+  basePath: string,
+  deps: SpawnGateDeps = {},
+): Promise<SpawnGateResult> {
+  const reconcileFn = deps.reconcile ?? reconcileBeforeDispatch;
+  try {
+    const result = await reconcileFn(basePath, deps as ReconciliationDeps);
+    if (result.blockers.length > 0) {
+      return {
+        ok: false,
+        reason: `Reconciliation blocker: ${result.blockers[0]}`,
+      };
+    }
+    const repairedKinds = result.repaired.map((d) => d.kind);
+    return {
+      ok: true,
+      reason:
+        repairedKinds.length > 0
+          ? `repaired before spawn: ${repairedKinds.join(", ")}`
+          : undefined,
+    };
+  } catch (err) {
+    if (err instanceof ReconciliationFailedError) {
+      return { ok: false, reason: err.message };
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,83 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 types for drift-driven state reconciliation.
+
+import type { DeriveStateOptions } from "../state.js";
+import type { GSDState } from "../types.js";
+
+/**
+ * Discriminated union over drift kinds the State Reconciliation Module
+ * recognizes. Each variant carries the identifiers its matching repair needs.
+ */
+export type DriftRecord =
+  | { kind: "stale-sketch-flag"; mid: string; sid: string }
+  | { kind: "unmerged-merge-state"; basePath: string }
+  | { kind: "stale-render"; renderPath: string; reason: string }
+  | { kind: "stale-worker"; lockPath: string; pid: number }
+  | { kind: "unregistered-milestone"; milestoneId: string }
+  | { kind: "roadmap-divergence"; milestoneId: string; sliceId?: string }
+  | {
+      kind: "missing-completion-timestamp";
+      entity: "task" | "slice" | "milestone";
+      ids: string[];
+    };
+
+/**
+ * Context threaded to detector and repair functions. Keeps handlers from
+ * re-deriving state for themselves.
+ */
+export interface DriftContext {
+  basePath: string;
+  state: GSDState;
+}
+
+/**
+ * One drift kind's detect+repair composition.
+ *
+ * Repairs MUST be idempotent: re-running yields the same outcome. This is
+ * load-bearing for the cap=2 lifecycle — the second pass may detect drift
+ * that the first pass already partially repaired.
+ */
+export interface DriftHandler<T extends DriftRecord = DriftRecord> {
+  kind: T["kind"];
+  detect: (state: GSDState, ctx: DriftContext) => T[] | Promise<T[]>;
+  repair: (record: T, ctx: DriftContext) => Promise<void> | void;
+}
+
+/**
+ * Result of a successful reconcileBeforeDispatch call.
+ *
+ * `blockers` are TERMINAL conditions (DB unavailable, slice lock invalid,
+ * dependency cycle) that reconciliation cannot resolve. The caller decides
+ * how to handle them; the orchestrator adapter at auto.ts maps non-empty
+ * blockers to ok=false for the orchestrator's InvariantAdapterResult.
+ *
+ * On repair failure or drift persisting past the cap, reconcileBeforeDispatch
+ * throws ReconciliationFailedError instead of returning.
+ */
+export interface ReconciliationResult {
+  ok: true;
+  stateSnapshot: GSDState;
+  repaired: readonly DriftRecord[];
+  blockers: readonly string[];
+}
+
+/**
+ * Dependencies for reconcileBeforeDispatch. Tests inject fakes for the
+ * registry and state derivation; production callers use defaults.
+ */
+export interface ReconciliationDeps {
+  invalidateStateCache: () => void;
+  deriveState: (
+    basePath: string,
+    opts?: DeriveStateOptions,
+  ) => Promise<GSDState>;
+  /**
+   * Override of the drift handler catalog. Defaults to DRIFT_REGISTRY. Each
+   * handler is parameterized over its own DriftRecord variant; the union of
+   * disjoint parameter types in repair forces the array element type to
+   * DriftHandler<any> here (see registry.ts comment).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registry?: ReadonlyArray<DriftHandler<any>>;
+  deriveStateOptions?: DeriveStateOptions;
+}

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

@@ -1,57 +1,25 @@
 // Project/App: GSD-2
-// File Purpose: ADR-015 State Reconciliation module for pre-dispatch runtime invariants.
+// File Purpose: ADR-017 State Reconciliation Module — public entry point.
+// Re-exports the drift-driven implementation from the state-reconciliation/
+// folder so existing import paths (./state-reconciliation.js) keep working.
 
-import { deriveState, invalidateStateCache, type DeriveStateOptions } from "./state.js";
-import type { GSDState } from "./types.js";
+export {
+  reconcileBeforeDispatch,
+  ReconciliationFailedError,
+  DRIFT_REGISTRY,
+} from "./state-reconciliation/index.js";
 
-export type StateReconciliationResult =
-  | {
-      ok: true;
-      stateSnapshot: GSDState;
-      repaired: readonly string[];
-      blockers: readonly string[];
-    }
-  | {
-      ok: false;
-      reason: string;
-      stateSnapshot?: GSDState;
-      repaired: readonly string[];
-      blockers: readonly string[];
-    };
+export type {
+  DriftContext,
+  DriftHandler,
+  DriftRecord,
+  ReconciliationDeps,
+  ReconciliationFailureDetail,
+  ReconciliationResult,
+} from "./state-reconciliation/index.js";
 
-export interface StateReconciliationDeps {
-  invalidateStateCache: () => void;
-  deriveState: (basePath: string, opts?: DeriveStateOptions) => Promise<GSDState>;
-}
-
-const defaultDeps: StateReconciliationDeps = {
-  invalidateStateCache,
-  deriveState,
-};
-
-export async function reconcileBeforeDispatch(
-  basePath: string,
-  deps: StateReconciliationDeps = defaultDeps,
-  opts?: DeriveStateOptions,
-): Promise<StateReconciliationResult> {
-  deps.invalidateStateCache();
-  const stateSnapshot = await deps.deriveState(basePath, opts);
-  const blockers = stateSnapshot.blockers ?? [];
-
-  if (blockers.length > 0 || stateSnapshot.phase === "blocked") {
-    return {
-      ok: false,
-      reason: blockers[0] ?? `State reconciliation blocked in phase ${stateSnapshot.phase}`,
-      stateSnapshot,
-      repaired: ["derive-state-cache-invalidated"],
-      blockers,
-    };
-  }
-
-  return {
-    ok: true,
-    stateSnapshot,
-    repaired: ["derive-state-cache-invalidated"],
-    blockers,
-  };
-}
+export { reconcileBeforeSpawn } from "./state-reconciliation/spawn-gate.js";
+export type {
+  SpawnGateDeps,
+  SpawnGateResult,
+} from "./state-reconciliation/spawn-gate.js";