gsd-pi 2.79.0 → 2.80.0-dev.4ea7d80e7

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

@@ -0,0 +1,161 @@
+import type { AutoAdvanceResult, AutoOrchestrationModule, AutoOrchestratorDeps, AutoSessionContext, AutoStatus } from "./contracts.js";
+
+function now(): number {
+  return Date.now();
+}
+
+export class AutoOrchestrator implements AutoOrchestrationModule {
+  private status: AutoStatus = {
+    phase: "idle",
+    transitionCount: 0,
+  };
+  private readonly deps: AutoOrchestratorDeps;
+  private lastAdvanceKey: string | null = null;
+
+  public constructor(deps: AutoOrchestratorDeps) {
+    this.deps = deps;
+  }
+
+  public async start(_sessionContext: AutoSessionContext): Promise<AutoAdvanceResult> {
+    this.lastAdvanceKey = null;
+    this.status.phase = "running";
+    this.bumpTransition();
+    await this.deps.runtime.journalTransition({ name: "start" });
+    await this.deps.notifications.notifyLifecycle({ name: "start" });
+    return this.advance();
+  }
+
+  public async advance(): Promise<AutoAdvanceResult> {
+    try {
+      await this.deps.runtime.ensureLockOwnership();
+      const gate = await this.deps.health.preAdvanceGate();
+      if (!gate.allow) {
+        const blocked: AutoAdvanceResult = { kind: "blocked", reason: gate.reason ?? "health gate blocked" };
+        await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+        await this.deps.health.postAdvanceRecord(blocked);
+        return blocked;
+      }
+
+      const decision = await this.deps.dispatch.decideNextUnit();
+      if (!decision) {
+        const stopped: AutoAdvanceResult = { kind: "stopped", reason: "no remaining units" };
+        this.status.phase = "stopped";
+        this.status.activeUnit = undefined;
+        this.lastAdvanceKey = null;
+        this.bumpTransition();
+        await this.deps.runtime.journalTransition({ name: "advance-stopped", reason: stopped.reason });
+        await this.deps.health.postAdvanceRecord(stopped);
+        return stopped;
+      }
+
+      const nextKey = `${decision.unitType}:${decision.unitId}`;
+      if (this.lastAdvanceKey === nextKey) {
+        const blocked: AutoAdvanceResult = { kind: "blocked", reason: "idempotent advance: unit already active" };
+        await this.deps.runtime.journalTransition({
+          name: "advance-blocked",
+          reason: blocked.reason,
+          unitType: decision.unitType,
+          unitId: decision.unitId,
+        });
+        await this.deps.health.postAdvanceRecord(blocked);
+        return blocked;
+      }
+
+      this.status.activeUnit = { unitType: decision.unitType, unitId: decision.unitId };
+      this.status.phase = "running";
+      this.lastAdvanceKey = nextKey;
+      this.bumpTransition();
+
+      await this.deps.runtime.journalTransition({
+        name: "advance",
+        reason: decision.reason,
+        unitType: decision.unitType,
+        unitId: decision.unitId,
+      });
+      await this.deps.worktree.prepareForUnit(decision.unitType, decision.unitId);
+      await this.deps.worktree.syncAfterUnit(decision.unitType, decision.unitId);
+
+      const advanced: AutoAdvanceResult = { kind: "advanced" };
+      await this.deps.health.postAdvanceRecord(advanced);
+      return advanced;
+    } catch (error) {
+      const recovery = await this.deps.recovery.classifyAndRecover({
+        error,
+        unitType: this.status.activeUnit?.unitType,
+        unitId: this.status.activeUnit?.unitId,
+      });
+      const result: AutoAdvanceResult = recovery.action === "retry"
+        ? { kind: "paused", reason: recovery.reason }
+        : recovery.action === "escalate"
+          ? { kind: "error", reason: recovery.reason }
+          : { kind: "stopped", reason: recovery.reason };
+
+      if (result.kind === "paused") {
+        this.status.phase = "paused";
+      } else if (result.kind === "stopped") {
+        this.status.phase = "stopped";
+      } else {
+        this.status.phase = "error";
+      }
+
+      if (result.kind === "stopped") {
+        this.lastAdvanceKey = null;
+        this.status.activeUnit = undefined;
+      }
+      this.bumpTransition();
+
+      const journalName = result.kind === "paused"
+        ? "advance-paused"
+        : result.kind === "stopped"
+          ? "advance-stopped"
+          : "advance-error";
+      await this.deps.runtime.journalTransition({ name: journalName, reason: recovery.reason });
+
+      if (result.kind === "paused") {
+        await this.deps.notifications.notifyLifecycle({ name: "pause", detail: recovery.reason });
+      } else if (result.kind === "stopped") {
+        await this.deps.notifications.notifyLifecycle({ name: "stopped", detail: recovery.reason });
+      } else if (result.kind === "error") {
+        await this.deps.notifications.notifyLifecycle({ name: "error", detail: recovery.reason });
+      }
+      await this.deps.health.postAdvanceRecord(result);
+      return result;
+    }
+  }
+
+  public async resume(): Promise<AutoAdvanceResult> {
+    this.lastAdvanceKey = null;
+    this.status.phase = "running";
+    this.bumpTransition();
+    await this.deps.runtime.journalTransition({ name: "resume" });
+    await this.deps.notifications.notifyLifecycle({ name: "resume" });
+    return this.advance();
+  }
+
+  public async stop(reason: string): Promise<AutoAdvanceResult> {
+    if (this.status.phase === "stopped") {
+      return { kind: "stopped", reason };
+    }
+    await this.deps.worktree.cleanupOnStop(reason);
+    this.status.phase = "stopped";
+    this.status.activeUnit = undefined;
+    this.lastAdvanceKey = null;
+    this.bumpTransition();
+    await this.deps.runtime.journalTransition({ name: "stop", reason });
+    await this.deps.notifications.notifyLifecycle({ name: "stop", detail: reason });
+    return { kind: "stopped", reason };
+  }
+
+  public getStatus(): AutoStatus {
+    return { ...this.status, activeUnit: this.status.activeUnit ? { ...this.status.activeUnit } : undefined };
+  }
+
+  private bumpTransition(): void {
+    this.status.transitionCount += 1;
+    this.status.lastTransitionAt = now();
+  }
+}
+
+export function createAutoOrchestrator(deps: AutoOrchestratorDeps): AutoOrchestrationModule {
+  return new AutoOrchestrator(deps);
+}

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

@@ -55,7 +55,7 @@ import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, refreshOpenDatabaseFromDisk } from "../gsd-db.js";
 import type { MinimalModelRegistry } from "../context-budget.js";
 import { ensurePlanV2Graph, isEmptyPlanV2GraphResult, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
@@ -76,6 +76,12 @@ function isSamePathLocal(a: string, b: string): boolean {
   return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
 
+function refreshPlanSliceRecoveryDbIfNeeded(unitType: string): boolean {
+  if (unitType !== "plan-slice") return true;
+  if (!isDbAvailable()) return true;
+  return refreshOpenDatabaseFromDisk();
+}
+
 // ─── Session timeout auto-resume state ────────────────────────────────────────
 
 let consecutiveSessionTimeouts = 0;
@@ -232,6 +238,33 @@ async function emitCancelledUnitEnd(
   });
 }
 
+export function _buildCancelledUnitStopReason(
+  unitType: string,
+  unitId: string,
+  errorContext?: { message: string; category: string },
+): {
+  notifyMessage: string;
+  stopReason: string;
+  loopReason: "session-failed" | "unit-aborted";
+} {
+  const cancellationMessage = errorContext?.message ?? "unknown";
+  const isSessionCreationFailure = errorContext?.category === "session-failed";
+
+  if (isSessionCreationFailure) {
+    return {
+      notifyMessage: `Session creation failed for ${unitType} ${unitId}: ${cancellationMessage}. Stopping auto-mode.`,
+      stopReason: `Session creation failed: ${cancellationMessage}`,
+      loopReason: "session-failed",
+    };
+  }
+
+  return {
+    notifyMessage: `Unit ${unitType} ${unitId} aborted after dispatch: ${cancellationMessage}. Stopping auto-mode.`,
+    stopReason: `Unit aborted: ${cancellationMessage}`,
+    loopReason: "unit-aborted",
+  };
+}
+
 async function failClosedOnFinalizeTimeout(
   ic: IterationContext,
   iterData: IterationData,
@@ -994,7 +1027,10 @@ export async function runDispatch(
     // See: https://github.com/gsd-build/gsd-2/issues/2474
     if (dispatchResult.level === "warning") {
       ctx.ui.notify(dispatchResult.reason, "warning");
-      await deps.pauseAuto(ctx, pi);
+      await deps.pauseAuto(ctx, pi, {
+        message: dispatchResult.reason,
+        category: "unknown",
+      });
     } else {
       await closeoutAndStop(ctx, pi, s, deps, dispatchResult.reason);
     }
@@ -1065,7 +1101,16 @@ export async function runDispatch(
             `Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`,
             "info",
           );
+          if (!refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+            ctx.ui.notify(
+              `Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Keeping stuck state for retry.`,
+              "warning",
+            );
+            return { action: "continue" };
+          }
           deps.invalidateAllCaches();
+          loopState.recentUnits.length = 0;
+          loopState.stuckRecoveryAttempts = 0;
           return { action: "continue" };
         }
         ctx.ui.notify(
@@ -1075,6 +1120,32 @@ export async function runDispatch(
         deps.invalidateAllCaches();
       } else {
         // Level 2: hard stop — genuinely stuck
+        deps.invalidateAllCaches();
+        const artifactExists = verifyExpectedArtifact(
+          unitType,
+          unitId,
+          s.basePath,
+        );
+        if (artifactExists && unitType !== "complete-milestone") {
+          debugLog("autoLoop", {
+            phase: "stuck-recovery",
+            level: 2,
+            action: "artifact-found",
+          });
+          ctx.ui.notify(
+            `Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`,
+            "info",
+          );
+          if (refreshPlanSliceRecoveryDbIfNeeded(unitType)) {
+            loopState.recentUnits.length = 0;
+            loopState.stuckRecoveryAttempts = 0;
+            return { action: "continue" };
+          }
+          ctx.ui.notify(
+            `Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed. Stopping for manual recovery.`,
+            "warning",
+          );
+        }
         debugLog("autoLoop", {
           phase: "stuck-detected",
           unitType,
@@ -1470,7 +1541,12 @@ export async function runUnitPhase(
   s.lastGitActionFailure = null;
   s.lastGitActionStatus = null;
   s.lastUnitAgentEndMessages = null;
-  setCurrentPhase(unitType);
+  setCurrentPhase(unitType, {
+    basePath: s.basePath,
+    traceId: ic.flowId,
+    turnId: `iter-${ic.iteration}`,
+    causedBy: "unit-start",
+  });
   s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
   const unitStartSeq = ic.nextSeq();
   deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
@@ -1866,13 +1942,16 @@ export async function runUnitPhase(
     }
     await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
     await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
-    ctx.ui.notify(
-      `Session creation failed for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Stopping auto-mode.`,
-      "warning",
+
+    const cancelledStop = _buildCancelledUnitStopReason(
+      unitType,
+      unitId,
+      unitResult.errorContext,
     );
-    await deps.stopAuto(ctx, pi, `Session creation failed: ${unitResult.errorContext?.message ?? "unknown"}`);
-    debugLog("autoLoop", { phase: "exit", reason: "session-failed" });
-    return { action: "break", reason: "session-failed" };
+    ctx.ui.notify(cancelledStop.notifyMessage, "warning");
+    await deps.stopAuto(ctx, pi, cancelledStop.stopReason);
+    debugLog("autoLoop", { phase: "exit", reason: cancelledStop.loopReason });
+    return { action: "break", reason: cancelledStop.loopReason };
   }
 
   // ── Immediate unit closeout (metrics, activity log, memory) ────────

package/src/resources/extensions/gsd/auto/run-unit.ts

@@ -1,3 +1,5 @@
+// GSD-2 + src/resources/extensions/gsd/auto/run-unit.ts - Runs one GSD auto-mode unit from session creation through agent completion.
+
 /**
  * auto/run-unit.ts — Single unit execution: session create → prompt → await agent_end.
  *
@@ -17,6 +19,7 @@ import {
 import { debugLog } from "../debug-logger.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { resolveAutoSupervisorConfig } from "../preferences.js";
+import { formatAutoUnitWorkingMessage } from "../working-output-messages.js";
 
 // Tracks the latest session-switch attempt so a late timeout settlement from an
 // older runUnit() call cannot clear the guard for a newer one.
@@ -184,30 +187,37 @@ export async function runUnit(
   debugLog("runUnit", { phase: "send-message", unitType, unitId });
 
   const requestDispatchedAt = Date.now();
-  pi.sendMessage(
-    { customType: "gsd-auto", content: prompt, display: s.verbose },
-    { triggerTurn: true },
-  );
+  ctx.ui.setWorkingMessage?.(formatAutoUnitWorkingMessage(unitType, unitId));
 
   // ── Await agent_end with absolute timeout (H4 fix) ──
   // If supervision fails to resolve unitPromise within 30s, treat as cancelled.
   // Without this, a crashed agent that never emits agent_end hangs the loop (#3161).
-  debugLog("runUnit", { phase: "awaiting-agent-end", unitType, unitId });
   const supervisor = resolveAutoSupervisorConfig();
   const UNIT_HARD_TIMEOUT_MS = Math.max(
     30_000,
     ((supervisor.hard_timeout_minutes ?? 30) * 60 * 1000) + 30_000,
   );
   let unitTimeoutHandle: ReturnType<typeof setTimeout> | undefined;
-  const timeoutResult = new Promise<UnitResult>((resolve) => {
-    unitTimeoutHandle = setTimeout(() => {
-      resolve({ status: "cancelled", errorContext: { message: "Unit hard timeout — supervision may have failed", category: "timeout", isTransient: true } });
-    }, UNIT_HARD_TIMEOUT_MS);
-  });
-  const result = await runWithTurnGeneration(capturedTurnGen, () =>
-    Promise.race([unitPromise, timeoutResult]),
-  );
-  if (unitTimeoutHandle) clearTimeout(unitTimeoutHandle);
+  let result: UnitResult;
+  try {
+    pi.sendMessage(
+      { customType: "gsd-auto", content: prompt, display: s.verbose },
+      { triggerTurn: true },
+    );
+
+    debugLog("runUnit", { phase: "awaiting-agent-end", unitType, unitId });
+    const timeoutResult = new Promise<UnitResult>((resolve) => {
+      unitTimeoutHandle = setTimeout(() => {
+        resolve({ status: "cancelled", errorContext: { message: "Unit hard timeout — supervision may have failed", category: "timeout", isTransient: true } });
+      }, UNIT_HARD_TIMEOUT_MS);
+    });
+    result = await runWithTurnGeneration(capturedTurnGen, () =>
+      Promise.race([unitPromise, timeoutResult]),
+    );
+  } finally {
+    if (unitTimeoutHandle) clearTimeout(unitTimeoutHandle);
+    ctx.ui.setWorkingMessage?.(undefined);
+  }
   debugLog("runUnit", {
     phase: "agent-end-received",
     unitType,

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

@@ -21,6 +21,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import type { GitServiceImpl } from "../git-service.js";
 import type { CaptureEntry } from "../captures.js";
 import type { BudgetAlertLevel } from "../auto-budget.js";
+import type { AutoOrchestrationModule } from "./contracts.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { normalizeRealPath } from "../paths.js";
 import type { MilestoneScope } from "../workspace.js";
@@ -229,6 +230,9 @@ export class AutoSession {
   /** Cleanup function returned by startCommandPolling(); null when not running. */
   commandPollingCleanup: (() => void) | null = null;
 
+  // ── Orchestration seam ───────────────────────────────────────────────────
+  orchestration: AutoOrchestrationModule | null = null;
+
   // ── Loop promise state ──────────────────────────────────────────────────
   // Per-unit resolve function and session-switch guard live at module level
   // in auto-loop.ts (_currentResolve, _sessionSwitchInFlight).
@@ -354,10 +358,14 @@ export class AutoSession {
     // Remote command polling — cleanup must be called before reset (auto.ts stopAuto)
     this.commandPollingCleanup = null;
 
+    // Orchestration seam
+    this.orchestration = null;
+
     // Loop promise state lives in auto-loop.ts module scope
   }
 
   toJSON(): Record<string, unknown> {
+    const orchestrationStatus = this.orchestration?.getStatus();
     return {
       active: this.active,
       paused: this.paused,
@@ -367,6 +375,9 @@ export class AutoSession {
       activeRunDir: this.activeRunDir,
       currentMilestoneId: this.currentMilestoneId,
       currentUnit: this.currentUnit,
+      orchestrationPhase: orchestrationStatus?.phase,
+      orchestrationTransitionCount: orchestrationStatus?.transitionCount,
+      orchestrationLastTransitionAt: orchestrationStatus?.lastTransitionAt,
       unitDispatchCount: Object.fromEntries(this.unitDispatchCount),
     };
   }

package/src/resources/extensions/gsd/auto/workflow-custom-engine-dispatch-outcome.ts

@@ -0,0 +1,28 @@
+// Project/App: GSD-2
+// File Purpose: Applies custom-engine dispatch decisions to auto-mode loop side effects.
+
+import type { EngineDispatchDecision } from "./workflow-kernel.js";
+
+export interface HandleCustomEngineDispatchOutcomeDeps {
+  stopAuto: (reason: string) => Promise<void>;
+}
+
+export type CustomEngineDispatchFlow =
+  | { action: "break" }
+  | { action: "continue" }
+  | { action: "dispatch" };
+
+export async function handleCustomEngineDispatchOutcome(input: {
+  decision: EngineDispatchDecision;
+  deps: HandleCustomEngineDispatchOutcomeDeps;
+}): Promise<CustomEngineDispatchFlow> {
+  if (input.decision.action === "stop") {
+    await input.deps.stopAuto(input.decision.reason);
+    return { action: "break" };
+  }
+  if (input.decision.action === "skip") {
+    return { action: "continue" };
+  }
+
+  return { action: "dispatch" };
+}

package/src/resources/extensions/gsd/auto/workflow-custom-engine-iteration.ts

@@ -0,0 +1,52 @@
+// Project/App: GSD-2
+// File Purpose: Custom-engine iteration-data adapter for auto-mode loop.
+
+import type { GSDState } from "../types.js";
+import type { IterationData } from "./types.js";
+
+export interface CustomEngineStep {
+  unitType: string;
+  unitId: string;
+  prompt: string;
+}
+
+export interface BuildCustomEngineIterationDataInput {
+  step: CustomEngineStep;
+  basePath: string;
+  canonicalProjectRoot: string;
+  currentMilestoneId?: string | null;
+  deriveState: (basePath: string) => Promise<GSDState>;
+  logPostDerive: (details: {
+    site: "custom-engine-gsd-state";
+    basePath: string;
+    canonicalProjectRoot: string;
+    derivedPhase: GSDState["phase"];
+    activeUnit: string | undefined;
+  }) => void;
+}
+
+export async function buildCustomEngineIterationData(
+  input: BuildCustomEngineIterationDataInput,
+): Promise<IterationData> {
+  const gsdState = await input.deriveState(input.canonicalProjectRoot);
+  input.logPostDerive({
+    site: "custom-engine-gsd-state",
+    basePath: input.basePath,
+    canonicalProjectRoot: input.canonicalProjectRoot,
+    derivedPhase: gsdState.phase,
+    activeUnit: gsdState.activeTask?.id ?? gsdState.activeSlice?.id ?? gsdState.activeMilestone?.id,
+  });
+
+  return {
+    unitType: input.step.unitType,
+    unitId: input.step.unitId,
+    prompt: input.step.prompt,
+    finalPrompt: input.step.prompt,
+    pauseAfterUatDispatch: false,
+    state: gsdState,
+    mid: input.currentMilestoneId ?? "workflow",
+    midTitle: "Workflow",
+    isRetry: false,
+    previousTier: undefined,
+  };
+}

package/src/resources/extensions/gsd/auto/workflow-custom-engine-reconcile-outcome.ts

@@ -0,0 +1,58 @@
+// Project/App: GSD-2
+// File Purpose: Applies custom-engine reconcile outcomes to auto-mode loop side effects.
+
+import type { CustomEngineReconcileOutcome } from "./workflow-custom-engine-reconcile.js";
+
+export interface HandleCustomEngineReconcileOutcomeDeps {
+  stopAuto: (reason: string) => Promise<void>;
+  pauseAuto: () => Promise<void>;
+  report: (
+    action: "milestone-complete" | "pause" | "stop" | "continue",
+    details: { unitType: string; unitId: string; reason?: string },
+  ) => void;
+  finishTurn: (
+    status: "completed" | "paused" | "stopped",
+    failureClass?: "manual-attention",
+    error?: string,
+  ) => void;
+}
+
+export type CustomEngineReconcileFlow = { action: "break" } | { action: "continue" };
+
+export async function handleCustomEngineReconcileOutcome(input: {
+  outcome: CustomEngineReconcileOutcome;
+  unitType: string;
+  unitId: string;
+  deps: HandleCustomEngineReconcileOutcomeDeps;
+}): Promise<CustomEngineReconcileFlow> {
+  const details = {
+    unitType: input.unitType,
+    unitId: input.unitId,
+  };
+  const decision = input.outcome.decision;
+  if (decision.action === "complete-workflow") {
+    await input.deps.stopAuto(decision.stopReason);
+    input.deps.report("milestone-complete", details);
+    input.deps.finishTurn("completed");
+    return { action: "break" };
+  }
+  if (decision.action === "pause") {
+    await input.deps.pauseAuto();
+    input.deps.report("pause", details);
+    input.deps.finishTurn("paused", "manual-attention");
+    return { action: "break" };
+  }
+  if (decision.action === "stop") {
+    await input.deps.stopAuto(decision.reason);
+    input.deps.report("stop", {
+      ...details,
+      reason: input.outcome.reason,
+    });
+    input.deps.finishTurn("stopped", "manual-attention", input.outcome.reason);
+    return { action: "break" };
+  }
+
+  input.deps.report("continue", details);
+  input.deps.finishTurn("completed");
+  return { action: "continue" };
+}

package/src/resources/extensions/gsd/auto/workflow-custom-engine-reconcile.ts

@@ -0,0 +1,71 @@
+// Project/App: GSD-2
+// File Purpose: Custom-engine successful verification reconcile adapter for auto-mode loop.
+
+import type { EngineState, ReconcileResult } from "../engine-types.js";
+import type { IterationData } from "./types.js";
+import {
+  decideEngineReconcile,
+  type EngineReconcileDecision,
+} from "./workflow-kernel.js";
+
+export interface CustomEngineReconcileSession {
+  currentUnit?: { startedAt: number } | null;
+  verificationRetryCount?: Map<string, number>;
+}
+
+export interface HandleCustomEngineReconcileDeps {
+  saveRetryCounts: () => void;
+  logReconcile: (details: { iteration: number; unitId: string }) => void;
+  reconcile: (
+    state: EngineState,
+    completedStep: {
+      unitType: string;
+      unitId: string;
+      startedAt: number;
+      finishedAt: number;
+    },
+  ) => Promise<ReconcileResult>;
+  now: () => number;
+  clearUnitTimeout: () => void;
+  completeIteration: () => void;
+}
+
+export interface CustomEngineReconcileOutcome {
+  decision: EngineReconcileDecision;
+  reason?: string;
+}
+
+export async function handleCustomEngineReconcile(input: {
+  session: CustomEngineReconcileSession;
+  engineState: EngineState;
+  iterData: IterationData;
+  iteration: number;
+  deps: HandleCustomEngineReconcileDeps;
+}): Promise<CustomEngineReconcileOutcome> {
+  input.session.verificationRetryCount?.delete(`${input.iterData.unitType}/${input.iterData.unitId}`);
+  input.deps.saveRetryCounts();
+  input.deps.logReconcile({
+    iteration: input.iteration,
+    unitId: input.iterData.unitId,
+  });
+
+  const finishedAt = input.deps.now();
+  const reconcileResult = await input.deps.reconcile(input.engineState, {
+    unitType: input.iterData.unitType,
+    unitId: input.iterData.unitId,
+    startedAt: input.session.currentUnit?.startedAt ?? finishedAt,
+    finishedAt,
+  });
+
+  input.deps.clearUnitTimeout();
+  input.deps.completeIteration();
+
+  return {
+    decision: decideEngineReconcile(
+      reconcileResult.outcome === "stop"
+        ? { outcome: "stop", reason: reconcileResult.reason }
+        : { outcome: reconcileResult.outcome },
+    ),
+    reason: reconcileResult.reason,
+  };
+}