@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.d6c5343c

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,152 @@
+// 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 } 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;
+}
+
+function lookupLatestLedgerError(unitType: string, unitId: string): string | undefined {
+  try {
+    const row = getLatestForUnit(unitId);
+    // The ledger keys rows by bare unit id; require a unit_type match so
+    // another unit type's error on the same id is never attached (it would
+    // trip the repeat-error rule spuriously).
+    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;
+        window = persisted.map(({ key }) => ({ key: normalizeDispatchKey(key) }));
+        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 = [];
+    },
+  };
+}

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

@@ -0,0 +1,39 @@
+// Project/App: gsd-pi
+// File Purpose: Dispatch-key grammar — the single home for building, parsing,
+// and normalizing the auto orchestrator's dispatch keys.
+/**
+ * auto/dispatch-key.ts — Dispatch-key grammar.
+ *
+ * Canonical key: `${unitType}:${unitId}` (e.g. "execute-task:M001/S01/T01").
+ * Legacy key: `${unitType}/${unitId}` (auto/phases.ts, DB rehydration). Unit
+ * ids themselves contain "/" (M001/S01/T01) — the first segment is the unit
+ * type.
+ *
+ * Leaf node in the import DAG: both dispatch-history.ts and detect-stuck.ts
+ * consume this grammar, so it lives below them.
+ */
+
+/** Build the canonical dispatch key for a unit. One format, one home. */
+export function buildDispatchKey(unitType: string, unitId: string): string {
+  return `${unitType}:${unitId}`;
+}
+
+/** Split a canonical or legacy dispatch key into its unit type and id. */
+export function parseDispatchKey(key: string): { unitType: string; unitId: string } | null {
+  const colon = key.indexOf(":");
+  if (colon > 0) {
+    return { unitType: key.slice(0, colon), unitId: key.slice(colon + 1) };
+  }
+  const slash = key.indexOf("/");
+  if (slash > 0) {
+    return { unitType: key.slice(0, slash), unitId: key.slice(slash + 1) };
+  }
+  return null;
+}
+
+/** Normalize a legacy `${unitType}/${unitId}` key to the canonical format. */
+export function normalizeDispatchKey(key: string): string {
+  if (key.includes(":")) return key;
+  const parsed = parseDispatchKey(key);
+  return parsed ? buildDispatchKey(parsed.unitType, parsed.unitId) : key;
+}

package/src/resources/extensions/gsd/auto/loop-deps.ts

@@ -143,7 +143,7 @@ export interface LoopDeps {
     basePath: string,
     mid: string,
   ) => void;
-  getIsolationMode: (basePath?: string) => string;
+  getIsolationMode: (basePath?: string) => "none" | "worktree" | "branch";
   getCurrentBranch: (basePath: string) => string;
   autoWorktreeBranch: (milestoneId: string) => string;
   resolveMilestoneFile: (

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

@@ -25,7 +25,8 @@ import {
   type IterationData,
 } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
-import { runGuards, runFinalize, STUCK_WINDOW_SIZE } from "./phases.js";
+import { runGuards, runFinalize } from "./phases.js";
+import { STUCK_WINDOW_SIZE } from "./dispatch-history.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { ModelPolicyDispatchBlockedError } from "../auto-model-selection.js";
@@ -389,6 +390,8 @@ export async function autoLoop(
   const unitDispatchDeps = createExecutionGraphUnitDispatchDeps();
   // Load persisted stuck state so counters survive session restarts (#3704)
   const persisted = loadStuckState(s);
+  // Load persisted verification retry state so the exhausted-unit guard fires on restart (#651)
+  hydrateCustomVerifyRetryCounts(s, { logFailure: logCustomVerifyRetryLoadFailure });
   const loopState: LoopState = {
     recentUnits: persisted.recentUnits,
     stuckRecoveryAttempts: persisted.stuckRecoveryAttempts,