@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

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/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.

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

@@ -3,7 +3,7 @@
 /**
  * auto/loop.ts — Main auto-mode execution loop.
  *
- * Iterates: derive → dispatch → guards → runUnit → finalize → repeat.
+ * Iterates: orchestration.advance → guards → runUnit → finalize → repeat.
  * Exits when s.active becomes false or a terminal condition is reached.
  *
  * Imports from: auto/types, auto/resolve, auto/phases
@@ -15,6 +15,7 @@ import { randomUUID } from "node:crypto";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { AutoSession } from "./session.js";
+import type { AutoTerminalOutcome } from "./contracts.js";
 import type { LoopDeps, StopAutoOptions } from "./loop-deps.js";
 import type { GSDState } from "../types.js";
 import {
@@ -24,13 +25,7 @@ import {
   type IterationData,
 } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
-import {
-  runPreDispatch,
-  runDispatch,
-  runGuards,
-  runFinalize,
-  STUCK_WINDOW_SIZE,
-} from "./phases.js";
+import { runGuards, runFinalize, STUCK_WINDOW_SIZE } from "./phases.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";
@@ -146,6 +141,25 @@ function resolveCompletionStopFromState(
   };
 }
 
+function resolveCompletionStopFromOutcome(
+  outcome: AutoTerminalOutcome | undefined,
+  stateSnapshot: GSDState | undefined,
+): { reason: string; options: StopAutoOptions } | null {
+  if (outcome?.code !== "all-complete") return null;
+  const completedMilestone = stateSnapshot?.lastCompletedMilestone ?? stateSnapshot?.activeMilestone;
+  return {
+    reason: outcome.displayReason,
+    options: {
+      completionWidget: {
+        milestoneId: completedMilestone?.id ?? null,
+        milestoneTitle: completedMilestone?.title ?? null,
+        allMilestonesComplete: true,
+      },
+      terminalOutcome: outcome,
+    },
+  };
+}
+
 // ── Stuck detection persistence (#3704) ──────────────────────────────────
 // Phase C migration: stuck-state.json deleted in favor of DB-backed
 // equivalents. recentUnits is rebuilt from unit_dispatches (Phase B
@@ -158,6 +172,8 @@ function resolveCompletionStopFromState(
 // tolerates — same behavior as a fresh session.
 const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
 const MAX_CONSECUTIVE_ALREADY_ACTIVE_SKIPS = 3;
+const ORCHESTRATION_MISSING_REASON =
+  "Auto Orchestration Module is not wired; cannot dispatch built-in GSD Unit.";
 
 function stableStuckStateScopeId(s: AutoSession): string {
   return normalizeRealPath(s.scope?.workspace.projectRoot ?? (s.originalBasePath || s.basePath));
@@ -353,9 +369,9 @@ function closeOutCrashedUnit(s: AutoSession, iterData: IterationData, err: unkno
 }
 
 /**
- * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
- * runUnit → finalize → repeat. Exits when s.active becomes false or a
- * terminal condition is reached.
+ * Main auto-mode execution loop. Iterates: orchestration.advance → guards →
+ * runUnit → finalize → repeat. Exits when s.active becomes false or a terminal
+ * condition is reached.
  *
  * This is the linear replacement for the recursive
  * dispatchNextUnit → resolveAgentEnd → dispatchNextUnit chain.
@@ -572,10 +588,9 @@ export async function autoLoop(
       let iterData: IterationData;
 
       // ── Custom engine path ──────────────────────────────────────────────
-      // When activeEngineId is a non-dev value, bypass runPreDispatch and
-      // runDispatch entirely — the custom engine drives its own state via
-      // GRAPH.yaml. Shares runGuards and runUnitPhase with the dev path.
-      // After unit execution, verifies then reconciles via the engine layer.
+      // When activeEngineId is a non-dev value, the custom engine drives its own
+      // state via GRAPH.yaml. It shares guards and Unit execution with the dev
+      // path, then verifies and reconciles via the engine layer.
       //
       // GSD_ENGINE_BYPASS=1 skips the engine layer entirely — falls through
       // to the dev path below.
@@ -656,7 +671,7 @@ export async function autoLoop(
         observedUnitType = iterData.unitType;
         observedUnitId = iterData.unitId;
 
-        // ── Progress widget (mirrors dev path in runDispatch) ──
+        // ── Progress widget (mirrors the dev path) ──
         deps.updateProgressWidget(ctx, iterData.unitType, iterData.unitId, iterData.state);
 
         // ── Guards (shared with dev path) ──
@@ -876,14 +891,22 @@ export async function autoLoop(
 
           if (orchestrationResult.kind === "blocked") {
             s.pendingOrchestrationDispatch = null;
+            const blockMessage = orchestrationResult.terminalOutcome?.code === "settlement-blocked"
+              ? [
+                  orchestrationResult.terminalOutcome.displayReason,
+                  `Next: ${orchestrationResult.terminalOutcome.nextAction}`,
+                ].join("\n")
+              : orchestrationResult.reason;
             if (orchestrationResult.action === "pause") {
               await deps.pauseAuto(ctx, pi, {
-                message: orchestrationResult.reason,
+                message: blockMessage,
                 category: "unknown",
+              }, {
+                expectedCurrentUnit: null,
               });
               finishTurn("paused", "manual-attention", "orchestration-blocked");
             } else {
-              await deps.stopAuto(ctx, pi, orchestrationResult.reason);
+              await deps.stopAuto(ctx, pi, blockMessage);
               finishTurn("stopped", "manual-attention", "orchestration-blocked");
             }
             finishIncompleteIteration({
@@ -894,8 +917,20 @@ export async function autoLoop(
             break;
           }
 
+          if (orchestrationResult.kind === "skipped") {
+            s.pendingOrchestrationDispatch = null;
+            emitIterationEnd({ skipped: true });
+            completeIteration();
+            finishTurn("skipped");
+            continue;
+          }
+
           if (orchestrationResult.kind === "paused") {
             s.pendingOrchestrationDispatch = null;
+            finishIncompleteIteration({
+              status: "paused",
+              reason: orchestrationResult.reason,
+            });
             finishTurn("skipped");
             continue;
           }
@@ -917,7 +952,11 @@ export async function autoLoop(
 
           if (orchestrationResult.kind === "stopped") {
             s.pendingOrchestrationDispatch = null;
-            const completionStop = resolveCompletionStopFromState(orchestrationResult.stateSnapshot);
+            let completionStop = resolveCompletionStopFromOutcome(
+              orchestrationResult.terminalOutcome,
+              orchestrationResult.stateSnapshot,
+            );
+            completionStop ??= resolveCompletionStopFromState(orchestrationResult.stateSnapshot);
             if (completionStop) {
               await deps.stopAuto(ctx, pi, completionStop.reason, completionStop.options);
             } else {
@@ -998,54 +1037,37 @@ export async function autoLoop(
           });
           observedUnitType = iterData.unitType;
           observedUnitId = iterData.unitId;
-        } else {
-          const preDispatchResult = await runPreDispatch(ic, loopState);
-          phaseReporter.report("pre-dispatch", preDispatchResult.action);
-          if (preDispatchResult.action === "break") {
-            finishTurn("stopped", "manual-attention", "pre-dispatch-break");
+
+          const guardMilestoneId = iterData.mid ?? s.currentMilestoneId ?? "workflow";
+          const guardsResult = await runGuards(ic, guardMilestoneId);
+          phaseReporter.report("guard", guardsResult.action, {
+            unitType: iterData.unitType,
+            unitId: iterData.unitId,
+          });
+          if (guardsResult.action === "break") {
+            finishTurn("stopped", "manual-attention", "guard-break");
             finishIncompleteIteration({
               status: "stopped",
-              reason: "pre-dispatch-break",
+              reason: "guard-break",
+              unitType: iterData.unitType,
+              unitId: iterData.unitId,
               failureClass: "manual-attention",
             });
             break;
           }
-          if (preDispatchResult.action === "continue") {
-            emitIterationEnd({ skipped: true });
-            completeIteration();
-            finishTurn("skipped");
-            continue;
-          }
-          if (preDispatchResult.action === "retry") {
-            finishTurn("retry", "execution", preDispatchResult.reason);
-            continue;
-          }
-          const preData = preDispatchResult.data;
-          const guardsResult = await runGuards(ic, preData.mid);
-          phaseReporter.report("guard", guardsResult.action);
-          if (guardsResult.action === "break") {
-            finishTurn("stopped", "manual-attention", "guard-break");
-            break;
-          }
-          const dispatchResult = await runDispatch(ic, preData, loopState);
-          phaseReporter.report("dispatch", dispatchResult.action);
-          if (dispatchResult.action === "break") {
-            finishTurn("stopped", "manual-attention", "dispatch-break");
-            break;
-          }
-          if (dispatchResult.action === "continue") {
-            emitIterationEnd({ skipped: true });
-            completeIteration();
-            finishTurn("skipped");
-            continue;
-          }
-          if (dispatchResult.action === "retry") {
-            finishTurn("retry", "execution", dispatchResult.reason);
-            continue;
-          }
-          iterData = dispatchResult.data;
-          observedUnitType = iterData.unitType;
-          observedUnitId = iterData.unitId;
+        } else {
+          s.pendingOrchestrationDispatch = null;
+          await deps.pauseAuto(ctx, pi, {
+            message: ORCHESTRATION_MISSING_REASON,
+            category: "unknown",
+          });
+          finishTurn("paused", "manual-attention", "orchestration-missing");
+          finishIncompleteIteration({
+            status: "paused",
+            reason: ORCHESTRATION_MISSING_REASON,
+            failureClass: "manual-attention",
+          });
+          break;
         }
       } else {
         iterData = await buildSidecarIterationData({