agentic-toolkit/src/modules/failure-handler.ts

import type { FailureAction, FailureContext, FailureKind } from "../types.js";

const MAX_RETRIES = 1;

/**
 * Decide what to do when a ticket execution fails. Pure state machine.
 *
 * Rules:
 * - First failure (any kind, any variant): retry once.
 * - Second failure on per-ticket variant: skip this ticket, continue with peers
 *   in the same phase. The phase gate naturally blocks advance until the human
 *   resolves the failed issue.
 * - Second failure on single-pr variant: halt. The shared branch is corrupted
 *   and continuing would compound the damage.
 */
export function decide(
  failure: FailureKind,
  ctx: FailureContext,
): FailureAction {
  if (ctx.retryCount < MAX_RETRIES) {
    return { kind: "retry" };
  }

  const reason = `Ticket failed after ${ctx.retryCount + 1} attempt(s) with: ${failure}`;

  if (ctx.variant === "per-ticket") {
    return { kind: "skip", reason };
  }
  return { kind: "halt", reason };
}