@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/src/resources/extensions/gsd/artifact-projection.ts

@@ -0,0 +1,31 @@
+// Project/App: gsd-pi
+// File Purpose: Resolves closeout artifact projection roots across project and milestone worktrees.
+
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+
+export interface CloseoutArtifactProjectionInput {
+  milestoneId: string;
+  basePath: string;
+  originalBasePath?: string;
+}
+
+export interface CloseoutArtifactProjection {
+  projectRoot: string;
+  canonicalMilestoneRoot: string;
+  summaryArtifactBasePath: string;
+  gateEvidenceBasePath: string;
+}
+
+export function resolveCloseoutArtifactProjection(
+  input: CloseoutArtifactProjectionInput,
+): CloseoutArtifactProjection {
+  const projectRoot = resolveWorktreeProjectRoot(input.basePath, input.originalBasePath);
+  const canonicalMilestoneRoot = resolveCanonicalMilestoneRoot(projectRoot, input.milestoneId);
+  return {
+    projectRoot,
+    canonicalMilestoneRoot,
+    summaryArtifactBasePath: canonicalMilestoneRoot,
+    gateEvidenceBasePath: canonicalMilestoneRoot,
+  };
+}

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

@@ -1,9 +1,14 @@
 // Project/App: gsd-pi
-// File Purpose: Auto Orchestration module interfaces and ADR-015 invariant adapter contracts.
+// File Purpose: Auto Orchestration module public contract types.
+//
+// Phase 2 of #442 collapsed the nine single-implementation adapter interfaces
+// (DispatchAdapter, RecoveryAdapter, StateReconciliationAdapter,
+// ToolContractAdapter, WorktreeAdapter, HealthAdapter, UokGateAdapter,
+// RuntimePersistenceAdapter, NotificationAdapter) and AutoOrchestratorDeps
+// into AutoOrchestrator itself (auto/orchestrator.ts). Only the public result
+// and lifecycle-interface types remain here.
 
 import type { GSDState } from "../types.js";
-import type { MinimalModelRegistry } from "../context-budget.js";
-import type { AutoSession } from "./session.js";
 
 export interface AutoSessionContext {
   basePath: string;
@@ -22,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 };
 
@@ -41,119 +76,3 @@ export interface AutoOrchestrationModule {
   stop(reason: string): Promise<AutoAdvanceResult>;
   getStatus(): AutoStatus;
 }
-
-export interface DispatchAdapter {
-  decideNextUnit(input: {
-    stateSnapshot: GSDState;
-    /** Optional live session context, forwarded to dispatch rules that need session-derived state. */
-    session?: AutoSession;
-    /** Mirrors `DispatchContext.structuredQuestionsAvailable` — "true"/"false" string per the dispatch contract. */
-    structuredQuestionsAvailable?: "true" | "false";
-    /** Session model context window in tokens, forwarded to the budget engine. */
-    sessionContextWindow?: number;
-    /** Session model provider, used for provider-specific effective context windows. */
-    sessionProvider?: string;
-    /** Model registry for executor-model lookups inside the budget engine. */
-    modelRegistry?: MinimalModelRegistry;
-  }): Promise<
-    | {
-        kind: "blocked";
-        reason: string;
-        action: "pause" | "stop";
-      }
-    | {
-        kind: "skipped";
-        reason: string;
-      }
-    | {
-        unitType: string;
-        unitId: string;
-        reason: string;
-        preconditions: string[];
-      }
-    | null
-  >;
-}
-
-export interface RecoveryAdapter {
-  classifyAndRecover(input: {
-    error: unknown;
-    unitType?: string;
-    unitId?: string;
-  }): Promise<{
-    action: "retry" | "escalate" | "stop";
-    reason: string;
-  }>;
-}
-
-export type InvariantAdapterResult =
-  | { ok: true; reason?: string; stateSnapshot?: GSDState }
-  | { ok: false; reason: string; stateSnapshot?: GSDState };
-
-export interface StateReconciliationAdapter {
-  reconcileBeforeDispatch(): Promise<InvariantAdapterResult & { stateSnapshot?: GSDState }>;
-}
-
-export interface ToolContractAdapter {
-  compileUnitToolContract(unitType: string, unitId: string): Promise<InvariantAdapterResult>;
-}
-
-export interface WorktreeAdapter {
-  prepareForUnit(unitType: string, unitId: string): Promise<InvariantAdapterResult>;
-  syncAfterUnit(unitType: string, unitId: string): Promise<void>;
-  cleanupOnStop(reason: string): Promise<void>;
-}
-
-export type HealthGateResult =
-  | { kind: "pass"; fixesApplied?: readonly string[] }
-  | { kind: "fail"; reason: string; action?: "pause" | "stop" }
-  | { kind: "threw"; error: unknown };
-
-export interface HealthAdapter {
-  checkResourcesStale(): string | null;
-  preAdvanceGate(): Promise<HealthGateResult>;
-  postAdvanceRecord(result: AutoAdvanceResult): Promise<void>;
-}
-
-export interface UokGateInput {
-  gateId: string;
-  gateType: "policy" | "execution";
-  outcome: "pass" | "fail" | "manual-attention";
-  failureClass: "none" | "policy" | "manual-attention";
-  rationale: string;
-  findings?: string;
-  milestoneId?: string;
-}
-
-export interface UokGateAdapter {
-  emit(input: UokGateInput): Promise<void>;
-}
-
-export interface RuntimePersistenceAdapter {
-  ensureLockOwnership(): Promise<void>;
-  journalTransition(event: {
-    name: string;
-    reason?: string;
-    unitType?: string;
-    unitId?: string;
-  }): Promise<void>;
-}
-
-export interface NotificationAdapter {
-  notifyLifecycle(event: {
-    name: string;
-    detail?: string;
-  }): Promise<void>;
-}
-
-export interface AutoOrchestratorDeps {
-  stateReconciliation: StateReconciliationAdapter;
-  dispatch: DispatchAdapter;
-  toolContract: ToolContractAdapter;
-  recovery: RecoveryAdapter;
-  worktree: WorktreeAdapter;
-  health: HealthAdapter;
-  runtime: RuntimePersistenceAdapter;
-  notifications: NotificationAdapter;
-  uokGate: UokGateAdapter;
-}

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

@@ -7,6 +7,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import type { AutoSession } from "./session.js";
+import type { AutoTerminalOutcome } from "./contracts.js";
 import type { ErrorContext } from "./types.js";
 import type { GSDPreferences } from "../preferences.js";
 import type { GSDState } from "../types.js";
@@ -33,6 +34,7 @@ export interface StopAutoOptions {
     milestoneTitle?: string | null;
     allMilestonesComplete?: boolean;
   };
+  terminalOutcome?: AutoTerminalOutcome;
   /**
    * Foreground closeout-boundary stops already have the useful final surface in
    * the transcript. Preserve it instead of installing a replacement widget.
@@ -141,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: (