@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/auto/closeout.ts

@@ -0,0 +1,309 @@
+// Project/App: gsd-pi
+// File Purpose: Auto-loop closeout, milestone report, and merge helpers.
+
+import { importExtensionModule, type ExtensionAPI, type ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { join, basename } from "node:path";
+import { existsSync, cpSync } from "node:fs";
+import type { AutoSession } from "./session.js";
+import type { LoopDeps } from "./loop-deps.js";
+import type { GSDState } from "../types.js";
+import type { IterationContext } from "./types.js";
+import type { PostflightResult, PreflightResult } from "../clean-root-preflight.js";
+import { MergeConflictError } from "../git-service.js";
+import { findUnmergedCompletedMilestones } from "../unmerged-milestone-guard.js";
+import { getIsolationMode } from "../preferences.js";
+import { isDbAvailable, getMilestone } from "../gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
+import { isClosedStatus } from "../status-guards.js";
+import { gsdRoot } from "../paths.js";
+import { atomicWriteSync } from "../atomic-write.js";
+import { logWarning, logError } from "../workflow-logger.js";
+import { debugLog } from "../debug-logger.js";
+import { _resolveReportBasePath } from "./phase-helpers.js";
+
+/**
+ * If a unit is in-flight, close it out, then stop auto-mode.
+ */
+export async function closeoutAndStop(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  s: AutoSession,
+  deps: LoopDeps,
+  reason: string,
+): Promise<void> {
+  if (s.currentUnit) {
+    await deps.closeoutUnit(
+      ctx,
+      s.basePath,
+      s.currentUnit.type,
+      s.currentUnit.id,
+      s.currentUnit.startedAt,
+      deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id),
+    );
+    s.clearCurrentUnit();
+  }
+  await deps.stopAuto(ctx, pi, reason);
+}
+
+export async function stopOnPostflightRecoveryNeeded(
+  ic: IterationContext,
+  result: PostflightResult,
+  milestoneId: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  if (!result.needsManualRecovery) return null;
+  const { ctx, pi, deps } = ic;
+  const reason = `Post-merge stash restore failed for milestone ${milestoneId}`;
+  ctx.ui.notify(
+    `${reason}. Resolve the working tree before resuming auto-mode. ${result.message}`,
+    "error",
+  );
+  await deps.stopAuto(ctx, pi, reason);
+  return { action: "break", reason: "postflight-stash-restore-failed" };
+}
+
+export async function restorePreflightStashOrStop(
+  ic: IterationContext,
+  preflight: PreflightResult,
+  milestoneId: string,
+): Promise<{ action: "break"; reason: string } | null> {
+  if (!preflight.stashPushed) return null;
+  const { s, deps } = ic;
+  const result = deps.postflightPopStash(
+    s.originalBasePath || s.basePath,
+    milestoneId,
+    preflight.stashMarker,
+    ic.ctx.ui.notify.bind(ic.ctx.ui),
+  );
+  return stopOnPostflightRecoveryNeeded(ic, result, milestoneId);
+}
+
+/**
+ * Run a milestone merge surrounded by preflight stash + always-on postflight
+ * pop. The previous code popped the stash only after a successful merge, which
+ * leaked `gsd-preflight-stash:M00x:*` entries whenever `mergeAndExit` threw —
+ * leaving the user's pre-merge working tree silently stashed away after a
+ * merge-conflict or other merge error. This helper restores the stash on
+ * every exit path, then surfaces the merge or stash failure (in priority
+ * order) as the loop's stop reason.
+ *
+ * Returns a `break` action when auto-mode must stop, or `null` when the merge
+ * succeeded and the stash (if any) was restored cleanly.
+ */
+export async function _runMilestoneMergeWithStashRestore(
+  ic: IterationContext,
+  milestoneId: string,
+  options: { preserveCloseoutTranscript?: boolean } = {},
+): Promise<{ action: "break"; reason: string } | null> {
+  const { ctx, pi, s, deps } = ic;
+
+  const preflight = deps.preflightCleanRoot(
+    s.originalBasePath || s.basePath,
+    milestoneId,
+    ctx.ui.notify.bind(ctx.ui),
+  );
+  if (preflight.blocked) {
+    const reason = preflight.blockedReason === "unmerged-conflicts"
+      ? `Pre-merge unresolved Git conflicts block milestone ${milestoneId}`
+      : `Pre-merge dirty working tree overlaps milestone ${milestoneId}`;
+    await deps.stopAuto(ctx, pi, reason, {
+      preserveCompletedMilestoneBranch: true,
+      preserveCloseoutTranscript: options.preserveCloseoutTranscript,
+    });
+    return {
+      action: "break",
+      reason: preflight.blockedReason === "unmerged-conflicts"
+        ? "preflight-unmerged-conflicts"
+        : "preflight-dirty-overlap",
+    };
+  }
+
+  let mergeError: unknown = null;
+  const exitResult = deps.lifecycle.exitMilestone(
+    milestoneId,
+    { merge: true },
+    ctx.ui,
+  );
+  if (exitResult.ok) {
+    s.milestoneMergedInPhases = true;
+    try {
+      const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+      const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+      await rebuildMarkdownProjectionsFromDb(projectRoot);
+    } catch (err) {
+      logWarning(
+        "engine",
+        `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  } else {
+    mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+  }
+
+  // Always attempt to restore the stashed working tree, even on merge error.
+  // postflightPopStash itself does not throw; failures surface via the
+  // PostflightResult.needsManualRecovery flag.
+  let stashResult: PostflightResult | null = null;
+  if (preflight.stashPushed) {
+    stashResult = deps.postflightPopStash(
+      s.originalBasePath || s.basePath,
+      milestoneId,
+      preflight.stashMarker,
+      ctx.ui.notify.bind(ctx.ui),
+    );
+  }
+
+  // Merge failure takes priority over stash recovery — the merge is the
+  // authoritative gate. If the stash also needed manual recovery, the user
+  // already saw the postflightPopStash notify above.
+  if (mergeError) {
+    if (mergeError instanceof MergeConflictError) {
+      // A merge conflict is a recoverable human checkpoint, not an
+      // infrastructure failure — the user resolves the conflict and runs
+      // `/gsd auto` to resume. Pause (don't stop): stopAuto tears down the
+      // session and, because `milestoneMergedInPhases` stays false here,
+      // re-runs the already-failed worktree merge in its cleanup step
+      // (#2645), then drops the user out of the interactive TUI onto a
+      // "stopped" surface.
+      const conflictReason = `Merge conflict on milestone ${milestoneId}: ${mergeError.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`;
+      ctx.ui.notify(conflictReason, "error");
+      await deps.pauseAuto(ctx, pi, {
+        message: conflictReason,
+        category: "unknown",
+      });
+      return { action: "break", reason: "merge-conflict" };
+    }
+    logError("engine", "Milestone merge failed with non-conflict error", {
+      milestone: milestoneId,
+      error: String(mergeError),
+    });
+    // Like a merge conflict, a non-conflict merge failure (index lock,
+    // network, permissions) is recoverable — the user fixes the cause and
+    // runs `/gsd auto` to resume. Pause (don't stop) so the session stays
+    // resumable and stopAuto's teardown does not re-run the failed merge.
+    const mergeFailReason = `Merge error on milestone ${milestoneId}: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}. Resolve and run /gsd auto to resume.`;
+    ctx.ui.notify(mergeFailReason, "error");
+    await deps.pauseAuto(ctx, pi, {
+      message: mergeFailReason,
+      category: "unknown",
+    });
+    return { action: "break", reason: "merge-failed" };
+  }
+
+  if (stashResult) {
+    return stopOnPostflightRecoveryNeeded(ic, stashResult, milestoneId);
+  }
+  return null;
+}
+
+export async function _runMilestoneMergeOnceWithStashRestore(
+  ic: IterationContext,
+  milestoneId: string,
+  options: { preserveCloseoutTranscript?: boolean } = {},
+): Promise<{ action: "break"; reason: string } | null> {
+  if (ic.s.milestoneMergedInPhases) {
+    debugLog("autoLoop", {
+      phase: "milestone-merge-skip",
+      reason: "already-merged-in-phases",
+      milestoneId,
+    });
+    return null;
+  }
+  return _runMilestoneMergeWithStashRestore(ic, milestoneId, options);
+}
+
+export async function shouldSkipTerminalMilestoneCloseout(
+  s: AutoSession,
+  state: Pick<GSDState, "phase" | "lastCompletedMilestone" | "activeMilestone">,
+  mid?: string | null,
+): Promise<{ skip: boolean; milestoneId?: string }> {
+  const closeoutMilestoneId = mid ?? s.currentMilestoneId ?? state.lastCompletedMilestone?.id;
+  if (s.completionStopInProgress) {
+    return { skip: true, milestoneId: closeoutMilestoneId };
+  }
+  if (!closeoutMilestoneId) {
+    return { skip: false };
+  }
+  if (isDbAvailable()) refreshWorkflowDatabaseFromDisk();
+  const closeoutBasePath = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+  let closeoutMergePending = false;
+  if (getIsolationMode(closeoutBasePath) !== "none") {
+    try {
+      const blockers = await findUnmergedCompletedMilestones(closeoutBasePath);
+      closeoutMergePending = blockers.some((blocker) => blocker.milestoneId === closeoutMilestoneId);
+    } catch {
+      // Fail open: without git/DB inspection we cannot safely treat closeout as done.
+      closeoutMergePending = true;
+    }
+  }
+  const milestoneAlreadyClosedOut = isDbAvailable()
+    && isClosedStatus(getMilestone(closeoutMilestoneId)?.status ?? "")
+    && !closeoutMergePending;
+  if (milestoneAlreadyClosedOut) {
+    return { skip: true, milestoneId: closeoutMilestoneId };
+  }
+  return { skip: false, milestoneId: closeoutMilestoneId };
+}
+
+/**
+ * Generate and write an HTML milestone report snapshot.
+ */
+export async function generateMilestoneReport(
+  s: AutoSession,
+  ctx: ExtensionContext,
+  milestoneId: string,
+): Promise<void> {
+  const { loadVisualizerData } = await importExtensionModule<typeof import("../visualizer-data.js")>(import.meta.url, "../visualizer-data.js");
+  const { generateHtmlReport } = await importExtensionModule<typeof import("../export-html.js")>(import.meta.url, "../export-html.js");
+  const { writeReportSnapshot } = await importExtensionModule<typeof import("../reports.js")>(import.meta.url, "../reports.js");
+  const { basename } = await import("node:path");
+
+  const reportBasePath = _resolveReportBasePath(s);
+
+  const snapData = await loadVisualizerData(reportBasePath);
+  const completedMs = snapData.milestones.find(
+    (m: { id: string }) => m.id === milestoneId,
+  );
+  const msTitle = completedMs?.title ?? milestoneId;
+  const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
+  const projName = basename(reportBasePath);
+  const doneSlices = snapData.milestones.reduce(
+    (acc: number, m: { slices: { done: boolean }[] }) =>
+      acc + m.slices.filter((sl: { done: boolean }) => sl.done).length,
+    0,
+  );
+  const totalSlices = snapData.milestones.reduce(
+    (acc: number, m: { slices: unknown[] }) => acc + m.slices.length,
+    0,
+  );
+  const outPath = writeReportSnapshot({
+    basePath: reportBasePath,
+    html: generateHtmlReport(snapData, {
+      projectName: projName,
+      projectPath: reportBasePath,
+      gsdVersion,
+      milestoneId,
+      indexRelPath: "index.html",
+    }),
+    milestoneId,
+    milestoneTitle: msTitle,
+    kind: "milestone",
+    projectName: projName,
+    projectPath: reportBasePath,
+    gsdVersion,
+    totalCost: snapData.totals?.cost ?? 0,
+    totalTokens: snapData.totals?.tokens.total ?? 0,
+    totalDuration: snapData.totals?.duration ?? 0,
+    doneSlices,
+    totalSlices,
+    doneMilestones: snapData.milestones.filter(
+      (m: { status: string }) => m.status === "complete",
+    ).length,
+    totalMilestones: snapData.milestones.length,
+    phase: snapData.phase,
+  });
+  ctx.ui.notify(
+    `Report saved: .gsd/reports/${basename(outPath)} — open index.html to browse progression.`,
+    "info",
+  );
+}

package/src/resources/extensions/gsd/auto/contracts.ts

@@ -27,13 +27,43 @@ export interface AutoStatus {
   transitionCount: number;
 }
 
+export type AutoTerminalOutcome =
+  | {
+      code: "all-complete";
+      displayReason: string;
+      allMilestonesComplete: true;
+    }
+  | {
+      code: "no-remaining-units";
+      displayReason: string;
+      allMilestonesComplete: false;
+    }
+  | {
+      code: "settlement-blocked";
+      displayReason: string;
+      nextAction: string;
+      milestoneId: string;
+      allMilestonesComplete: false;
+    };
+
 export type AutoAdvanceResult =
   | { kind: "started" }
   | { kind: "resumed" }
   | { kind: "advanced"; unit: UnitRef; stateSnapshot: GSDState }
   | { kind: "skipped"; reason: string; stateSnapshot?: GSDState }
-  | { kind: "blocked"; reason: string; action: "pause" | "stop"; stateSnapshot?: GSDState }
-  | { kind: "stopped"; reason: string; stateSnapshot?: GSDState }
+  | {
+      kind: "blocked";
+      reason: string;
+      action: "pause" | "stop";
+      stateSnapshot?: GSDState;
+      terminalOutcome?: AutoTerminalOutcome;
+    }
+  | {
+      kind: "stopped";
+      reason: string;
+      stateSnapshot?: GSDState;
+      terminalOutcome?: AutoTerminalOutcome;
+    }
   | { kind: "paused"; reason: string }
   | { kind: "error"; reason: string };
 

package/src/resources/extensions/gsd/auto/custom-verify-retry-store.ts

@@ -7,12 +7,21 @@ import { atomicWriteSync } from "../atomic-write.js";
 import { gsdRoot } from "../paths.js";
 import type { AutoSession } from "./session.js";
 
-type RetrySession = Pick<AutoSession, "activeRunDir" | "basePath" | "verificationRetryCount">;
+type RetrySession = Pick<AutoSession, "activeRunDir" | "basePath" | "verificationRetryCount"> & {
+  exhaustedVerificationUnits?: Set<string>;
+};
 
 interface RetryStoreLogDeps {
   logFailure: (err: unknown) => void;
 }
 
+function ensureExhaustedVerificationUnits(s: RetrySession): Set<string> {
+  if (!s.exhaustedVerificationUnits) {
+    s.exhaustedVerificationUnits = new Set<string>();
+  }
+  return s.exhaustedVerificationUnits;
+}
+
 export function customVerifyRetryStateDir(s: Pick<AutoSession, "activeRunDir" | "basePath">): string {
   return s.activeRunDir ? join(s.activeRunDir, "runtime") : join(gsdRoot(s.basePath), "runtime");
 }
@@ -25,7 +34,8 @@ export function hydrateCustomVerifyRetryCounts(
   s: RetrySession,
   deps: RetryStoreLogDeps,
 ): Map<string, number> {
-  if (s.verificationRetryCount.size > 0) {
+  const exhaustedUnits = ensureExhaustedVerificationUnits(s);
+  if (s.verificationRetryCount.size > 0 || exhaustedUnits.size > 0) {
     return s.verificationRetryCount;
   }
 
@@ -39,6 +49,12 @@ export function hydrateCustomVerifyRetryCounts(
         s.verificationRetryCount.set(key, Math.floor(value));
       }
     }
+    const exhausted = raw && typeof raw === "object" && Array.isArray(raw.exhausted) ? raw.exhausted : [];
+    for (const key of exhausted) {
+      if (typeof key === "string" && key.length > 0) {
+        exhaustedUnits.add(key);
+      }
+    }
   } catch (err) {
     deps.logFailure(err);
   }
@@ -51,16 +67,18 @@ export function saveCustomVerifyRetryCounts(
   deps: RetryStoreLogDeps,
 ): void {
   const retryCounts = s.verificationRetryCount;
+  const exhaustedUnits = ensureExhaustedVerificationUnits(s);
   const filePath = customVerifyRetryStatePath(s);
 
   try {
-    if (!retryCounts || retryCounts.size === 0) {
+    if ((!retryCounts || retryCounts.size === 0) && (!exhaustedUnits || exhaustedUnits.size === 0)) {
       unlinkSync(filePath);
       return;
     }
     mkdirSync(customVerifyRetryStateDir(s), { recursive: true });
     atomicWriteSync(filePath, JSON.stringify({
       counts: Object.fromEntries(retryCounts),
+      exhausted: [...exhaustedUnits],
       updatedAt: new Date().toISOString(),
     }) + "\n");
   } catch (err) {

package/src/resources/extensions/gsd/auto/detect-stuck.ts

@@ -5,6 +5,7 @@
  */
 
 import type { WindowEntry } from "./types.js";
+import { parseDispatchKey } from "./dispatch-key.js";
 import { summarizeLogs } from "../workflow-logger.js";
 import { getLatestForUnit } from "../db/unit-dispatches.js";
 
@@ -15,6 +16,15 @@ import { getLatestForUnit } from "../db/unit-dispatches.js";
  */
 const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
 
+function rowInsideRetryBudget(row: ReturnType<typeof getLatestForUnit>): boolean {
+  if (!row) return false;
+  if (row.attempt_n >= row.max_attempts) return false;
+  if (!row.next_run_at) return false;
+  const nextRun = Date.parse(row.next_run_at);
+  if (!Number.isFinite(nextRun)) return false;
+  return nextRun > Date.now();
+}
+
 /**
  * Phase B / codex review MEDIUM B3 — retry coupling.
  *
@@ -24,19 +34,26 @@ const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
  * waiting on its own backoff. Suppress the stuck verdict in that case so
  * the retry budget can fully drain before we declare stuck.
  *
+ * Window keys are compound (`unitType:unitId`, legacy `unitType/unitId`)
+ * while the production dispatch ledger keys rows by the bare unit id with
+ * the unit type in its own column. Look the bare unit id up first (with a
+ * unit_type match — the production shape), then fall back to the full
+ * compound key (test fixtures / legacy rows).
+ *
  * Returns true if the dispatch ledger says we should suppress the stuck
  * signal; false (no suppression) when the ledger is unavailable or has
  * no opinion.
  */
 function retryBudgetSuppresses(unitKey: string): boolean {
   try {
-    const latest = getLatestForUnit(unitKey);
-    if (!latest) return false;
-    if (latest.attempt_n >= latest.max_attempts) return false;
-    if (!latest.next_run_at) return false;
-    const nextRun = Date.parse(latest.next_run_at);
-    if (!Number.isFinite(nextRun)) return false;
-    return nextRun > Date.now();
+    const parsed = parseDispatchKey(unitKey);
+    if (parsed) {
+      const bare = getLatestForUnit(parsed.unitId);
+      if (bare && bare.unit_type === parsed.unitType && rowInsideRetryBudget(bare)) {
+        return true;
+      }
+    }
+    return rowInsideRetryBudget(getLatestForUnit(unitKey));
   } catch {
     return false;
   }
@@ -71,6 +88,12 @@ export function detectStuck(
   const last = window[window.length - 1];
   const prev = window[window.length - 2];
 
+  // Rules 2 and 2b share one retry-budget verdict for `last.key` — compute it
+  // at most once per invocation (it hits the dispatch ledger).
+  let suppressionVerdict: boolean | undefined;
+  const suppressed = (): boolean =>
+    (suppressionVerdict ??= retryBudgetSuppresses(last.key));
+
   // Rule 1: Same error repeated consecutively
   if (last.error && prev.error && last.error === prev.error) {
     return {
@@ -83,7 +106,7 @@ export function detectStuck(
   // says we're inside the retry-backoff window (codex MEDIUM B3).
   if (window.length >= 3) {
     const lastThree = window.slice(-3);
-    if (lastThree.every((u) => u.key === last.key) && !retryBudgetSuppresses(last.key)) {
+    if (lastThree.every((u) => u.key === last.key) && !suppressed()) {
       return {
         stuck: true,
         reason: `${last.key} derived 3 consecutive times without progress${suffix}`,
@@ -94,7 +117,7 @@ export function detectStuck(
   // Rule 2b: Same unit key 3+ times anywhere in the active window — same
   // retry-budget suppression as Rule 2.
   const countInWindow = window.filter((entry) => entry.key === last.key).length;
-  if (countInWindow >= 3 && !retryBudgetSuppresses(last.key)) {
+  if (countInWindow >= 3 && !suppressed()) {
     return {
       stuck: true,
       reason: `${last.key} derived ${countInWindow} times in last ${window.length} attempts without progress${suffix}`,

package/src/resources/extensions/gsd/auto/dispatch-history.ts

@@ -0,0 +1,168 @@
+// Project/App: gsd-pi
+// File Purpose: Dispatch History module — the single home for the auto
+// orchestrator's dispatch-decision window, cross-session rehydration, and
+// stuck detection (#482 / #442 deepening).
+/**
+ * auto/dispatch-history.ts — Dispatch History module.
+ *
+ * Owns the sliding window of recent dispatch decisions that the Auto
+ * Orchestration module consults for idempotency and stuck-loop detection.
+ *
+ * Before this module existed the orchestrator kept a private in-memory
+ * `dispatchKeyWindow: string[]` that was reset to `[]` in start()/resume().
+ * Because a fresh orchestrator is constructed per session, the window never
+ * saw dispatches from a previous session — a unit could be re-dispatched
+ * across session restarts indefinitely (issue #482: 146 re-dispatches of the
+ * same unit). This module rehydrates the window from the DB dispatch ledger
+ * (`unit_dispatches`, via getRecentUnitKeysForProjectRoot) so stuck detection
+ * survives process restarts, and it delegates the verdict to the full
+ * detect-stuck rule set (repeat-error / consecutive / oscillation / ENOENT,
+ * with retry-budget suppression) instead of the bare saturation count.
+ *
+ * Key format: the canonical dispatch key is `${unitType}:${unitId}`
+ * (e.g. "execute-task:M001/S01/T01"). The legacy auto/phases.ts path and the
+ * DB rehydration helper use `${unitType}/${unitId}`; normalizeDispatchKey
+ * converts those on rehydrate so one format lives in the window. The key
+ * grammar itself lives in auto/dispatch-key.ts and is re-exported here for
+ * import stability.
+ */
+
+import type { WindowEntry } from "./types.js";
+import { buildDispatchKey, normalizeDispatchKey, parseDispatchKey } from "./dispatch-key.js";
+import { detectStuck } from "./detect-stuck.js";
+import {
+  getLatestForUnit,
+  getRecentUnitKeysForProjectRoot,
+} from "../db/unit-dispatches.js";
+import { debugLog } from "../debug-logger.js";
+
+export { buildDispatchKey, normalizeDispatchKey, parseDispatchKey } from "./dispatch-key.js";
+
+/**
+ * Size of the dispatch-decision ring buffer. Mirrors the legacy
+ * `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is preserved across the
+ * cutover (issue #5791).
+ */
+export const STUCK_WINDOW_SIZE = 6;
+
+export interface DispatchHistory {
+  /**
+   * Record a dispatch decision in the window (evicting oldest-first past the
+   * window size). When the window already holds an entry for the same unit,
+   * attaches the latest ledger error summary so the repeat-error and ENOENT
+   * stuck rules can fire; first-time dispatches (the common case) skip the
+   * ledger lookup entirely. Returns the canonical key.
+   */
+  recordDispatch(unitType: string, unitId: string): string;
+  /** Read-only view of the current window, oldest-first. */
+  getRecentWindow(): readonly WindowEntry[];
+  /** Number of window entries matching the given canonical key. */
+  countMatching(key: string): number;
+  /**
+   * Run the full detect-stuck rule set over the window (all four rules plus
+   * retry-budget suppression via the dispatch ledger).
+   */
+  detectStuck(): { stuck: true; reason: string } | null;
+  /**
+   * Seed the window from the DB dispatch ledger (cross-session continuity,
+   * #482). Legacy `${unitType}/${unitId}` keys are normalized. Degrades to a
+   * no-op when the ledger is unavailable. Returns the number of entries
+   * rehydrated.
+   */
+  rehydrate(): number;
+  /** Clear the window after a successful stuck recovery (or hard stop). */
+  clearOnRecovery(): void;
+}
+
+export interface DispatchHistoryOptions {
+  /**
+   * Stable project scope used to rehydrate from the dispatch ledger. Resolved
+   * lazily so worktree adoption after construction is respected. Return
+   * null/empty to skip rehydration.
+   */
+  resolveScopeId: () => string | null;
+  windowSize?: number;
+}
+
+/**
+ * Fetch the latest dispatch ledger error for a unit, the single canonical
+ * lookup shared by the DispatchHistory window and the legacy
+ * `loopState.recentUnits` path in dispatch.ts. The ledger keys rows by the
+ * bare unit id with the unit type in its own column, so the lookup must use
+ * the bare id and require a unit_type match (a compound `type/id` key would
+ * miss the row, and another unit type's error on the same id must never be
+ * attached — it would trip the repeat-error rule spuriously).
+ */
+export function lookupLatestLedgerError(unitType: string, unitId: string): string | undefined {
+  try {
+    const row = getLatestForUnit(unitId);
+    if (!row || row.unit_type !== unitType) return undefined;
+    return row.error_summary ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createDispatchHistory(options: DispatchHistoryOptions): DispatchHistory {
+  const windowSize = options.windowSize ?? STUCK_WINDOW_SIZE;
+  let window: WindowEntry[] = [];
+
+  return {
+    recordDispatch(unitType: string, unitId: string): string {
+      const key = buildDispatchKey(unitType, unitId);
+      // Ledger errors only feed the repeat-error/ENOENT rules, which need a
+      // prior occurrence of the same unit in the window — first-dispatch
+      // advances (the common case) pay zero DB cost.
+      const error = window.some((entry) => entry.key === key)
+        ? lookupLatestLedgerError(unitType, unitId)
+        : undefined;
+      window.push({ key, error });
+      while (window.length > windowSize) window.shift();
+      return key;
+    },
+
+    getRecentWindow(): readonly WindowEntry[] {
+      return window;
+    },
+
+    countMatching(key: string): number {
+      return window.filter((entry) => entry.key === key).length;
+    },
+
+    detectStuck(): { stuck: true; reason: string } | null {
+      return detectStuck(window);
+    },
+
+    rehydrate(): number {
+      const scopeId = options.resolveScopeId();
+      if (!scopeId) return 0;
+      try {
+        const persisted = getRecentUnitKeysForProjectRoot(scopeId, windowSize);
+        if (persisted.length === 0) return 0;
+        const rebuilt: WindowEntry[] = [];
+        for (const { key } of persisted) {
+          const normalized = normalizeDispatchKey(key);
+          const parsed = parseDispatchKey(normalized);
+          const error =
+            parsed && rebuilt.some((entry) => entry.key === normalized)
+              ? lookupLatestLedgerError(parsed.unitType, parsed.unitId)
+              : undefined;
+          rebuilt.push({ key: normalized, error });
+        }
+        window = rebuilt;
+        while (window.length > windowSize) window.shift();
+        return window.length;
+      } catch (err) {
+        debugLog("dispatchHistory", {
+          phase: "rehydrate-failed",
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return 0;
+      }
+    },
+
+    clearOnRecovery(): void {
+      window = [];
+    },
+  };
+}