@dev-loops/core 1.0.2 → 1.0.3

package/src/loop/finding-cluster.mjs

@@ -0,0 +1,277 @@
+/**
+ * finding-cluster.mjs — deterministic fan-in finding clustering for the
+ * gate-review sub-loop. Collapses duplicate findings (the SAME root cause
+ * reported by more than one reviewer/angle) into one cluster so the judge's
+ * relevance disposition and the fixer's act list both reason about root
+ * causes, not raw finding count.
+ *
+ * Pure and offline: no file reads, no network, no state held across calls.
+ * Every function deep-clones before enriching and never mutates a caller's
+ * array/objects.
+ */
+
+import { resolveFindingFile } from "./gate-fanin.mjs";
+
+// NUL separates the three key components so a value inside one component
+// (e.g. a recommendation that happens to contain a colon or digits matching
+// another component) can never be misread as spanning a boundary.
+const ROOT_CAUSE_KEY_SEPARATOR = "\u0000";
+
+/** @param {unknown} value @returns {boolean} */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * The canonical root-cause key for a finding: `(reviewed head, primary
+ * location "file:line", normalized remediation target)`. A finding missing
+ * ANY of the three components is UNKEYABLE and returns null — it is never
+ * grouped with another finding, keyable or not.
+ *
+ * @param {{file?: unknown, files?: unknown, line?: unknown, recommendation?: unknown}} finding
+ * @param {{headSha?: unknown}} [options] — the round's reviewed head; a
+ *   finding never carries its own head, so this is always caller-supplied.
+ * @returns {string|null}
+ */
+export function computeRootCauseKey(finding, { headSha } = {}) {
+  if (!finding || typeof finding !== "object") return null;
+  if (!isNonEmptyString(headSha)) return null;
+  const file = resolveFindingFile(finding);
+  if (!isNonEmptyString(file)) return null;
+  const line = finding.line;
+  if (!Number.isInteger(line) || line < 1) return null;
+  const recommendation = finding.recommendation;
+  if (!isNonEmptyString(recommendation)) return null;
+
+  const normalizedRecommendation = recommendation.trim().toLowerCase().replace(/\s+/g, " ");
+  return [headSha.trim(), `${file}:${line}`, normalizedRecommendation].join(ROOT_CAUSE_KEY_SEPARATOR);
+}
+
+/**
+ * Group findings by EXACT root-cause key match. Every UNKEYABLE finding
+ * (see {@link computeRootCauseKey}) is its own singleton cluster, never
+ * grouped with another unkeyable finding. Deterministic: clusters are
+ * ordered by `representativeIndex` ascending (first appearance), and a
+ * cluster's `memberIndices` are ascending.
+ *
+ * FAIL-OPEN: a non-array `findings`, a missing/empty/non-string `headSha`,
+ * or any internal error returns `{ ok: false, reason, clusters }` where
+ * `clusters` is one singleton (`keyable: false`) per ORIGINAL finding in
+ * input order — so a caller passes every original finding through to the
+ * judge unchanged. Never throws.
+ *
+ * @param {unknown} findings
+ * @param {{headSha?: unknown}} [options]
+ * @returns {{ ok: true, clusters: Array<{key: string|null, keyable: boolean, memberIndices: number[], representativeIndex: number}> }
+ *   | { ok: false, reason: string, clusters: Array<{key: null, keyable: false, memberIndices: number[], representativeIndex: number}> }}
+ */
+export function clusterFindings(findings, options = {}) {
+  try {
+    if (!Array.isArray(findings)) {
+      throw new Error("clusterFindings requires findings to be an array");
+    }
+    if (!isNonEmptyString(options?.headSha)) {
+      throw new Error("clusterFindings requires a non-empty options.headSha");
+    }
+    const headSha = options.headSha;
+    // A Map preserves insertion order, and every finding is visited index
+    // ascending below, so the FIRST index to create a cluster entry is
+    // always that cluster's smallest (representative) member — clusters is
+    // therefore already representativeIndex-ascending with no extra sort.
+    const byKey = new Map();
+    const clusters = [];
+    findings.forEach((finding, index) => {
+      const key = computeRootCauseKey(finding, { headSha });
+      if (key === null) {
+        clusters.push({ key: null, keyable: false, memberIndices: [index], representativeIndex: index });
+        return;
+      }
+      let cluster = byKey.get(key);
+      if (!cluster) {
+        cluster = { key, keyable: true, memberIndices: [], representativeIndex: index };
+        byKey.set(key, cluster);
+        clusters.push(cluster);
+      }
+      cluster.memberIndices.push(index);
+    });
+    return { ok: true, clusters };
+  } catch (err) {
+    const list = Array.isArray(findings) ? findings : [];
+    return {
+      ok: false,
+      reason: err instanceof Error ? err.message : String(err),
+      clusters: list.map((_finding, index) => ({ key: null, keyable: false, memberIndices: [index], representativeIndex: index })),
+    };
+  }
+}
+
+/**
+ * Reconstruct the clusters array from findings a producer already stamped
+ * with `clusterId` — the LOSSLESS identity consolidate-fanin.mjs computes
+ * (via {@link clusterFindings}) on pre-truncation finding text and stamps
+ * onto each ledger finding as `finding.clusterId = cluster.representativeIndex`.
+ * A consumer reading the ledger back (e.g. judge-pass.mjs) must group by this
+ * stamp rather than re-running {@link clusterFindings} on the ledger's own
+ * `recommendation`/`file` text, which the ledger pipeline TRUNCATES after
+ * clustering — re-deriving from truncated text can merge findings that only
+ * share a long truncated prefix, silently discarding the lossless grouping.
+ *
+ * Every finding must carry an integer `clusterId` (fails closed otherwise —
+ * a caller unsure every finding is stamped should fall back to
+ * {@link clusterFindings} instead of calling this). Deterministic: clusters
+ * are ordered by `representativeIndex` ascending, and each cluster's
+ * `memberIndices` are ascending (findings are visited index-ascending).
+ *
+ * @param {Array<{clusterId?: unknown}>} findings
+ * @returns {Array<{key: null, keyable: true, memberIndices: number[], representativeIndex: number}>}
+ */
+export function clustersFromStampedIds(findings) {
+  if (!Array.isArray(findings)) {
+    throw new TypeError("clustersFromStampedIds requires findings to be an array");
+  }
+  const byClusterId = new Map();
+  findings.forEach((finding, index) => {
+    const clusterId = finding?.clusterId;
+    if (!Number.isInteger(clusterId)) {
+      throw new TypeError(`clustersFromStampedIds requires every finding to carry an integer clusterId (index ${index} does not)`);
+    }
+    let cluster = byClusterId.get(clusterId);
+    if (!cluster) {
+      cluster = { key: null, keyable: true, memberIndices: [], representativeIndex: clusterId };
+      byClusterId.set(clusterId, cluster);
+    }
+    cluster.memberIndices.push(index);
+  });
+  return [...byClusterId.values()].sort((a, b) => a.representativeIndex - b.representativeIndex);
+}
+
+/**
+ * Project every multi-member cluster's REPRESENTATIVE judge disposition
+ * (`judgeDisposition`/`judgeRationale`/`judgeCriterion`/`followUpDraft`) onto
+ * every member of that cluster — one judge decision per root cause, applied
+ * to every finding reporting it. Singleton clusters are unchanged. Pure:
+ * deep-clones before enriching, never mutates `enrichedFindings`.
+ *
+ * Fails closed (throws) when a cluster is malformed or its
+ * `memberIndices`/`representativeIndex` reference an out-of-range position.
+ *
+ * @param {Array<object>} enrichedFindings
+ * @param {Array<{memberIndices: number[], representativeIndex: number}>} clusters
+ * @returns {Array<object>} a new, deep-cloned array.
+ */
+export function projectClusterDisposition(enrichedFindings, clusters) {
+  if (!Array.isArray(enrichedFindings)) {
+    throw new TypeError("projectClusterDisposition requires enrichedFindings to be an array");
+  }
+  if (!Array.isArray(clusters)) {
+    throw new TypeError("projectClusterDisposition requires clusters to be an array");
+  }
+  const result = enrichedFindings.map((finding) => structuredClone(finding));
+  for (const cluster of clusters) {
+    if (!cluster || !Array.isArray(cluster.memberIndices) || !Number.isInteger(cluster.representativeIndex)) {
+      throw new TypeError("projectClusterDisposition requires every cluster to carry memberIndices[] and a representativeIndex");
+    }
+    if (cluster.representativeIndex < 0 || cluster.representativeIndex >= result.length) {
+      throw new RangeError(`projectClusterDisposition: cluster representativeIndex ${cluster.representativeIndex} is out of range (${result.length} findings)`);
+    }
+    for (const memberIndex of cluster.memberIndices) {
+      if (!Number.isInteger(memberIndex) || memberIndex < 0 || memberIndex >= result.length) {
+        throw new RangeError(`projectClusterDisposition: cluster memberIndices references out-of-range index ${memberIndex} (${result.length} findings)`);
+      }
+    }
+    if (cluster.memberIndices.length === 0) {
+      throw new RangeError("projectClusterDisposition: a cluster must have at least one member (memberIndices is empty)");
+    }
+    if (!cluster.memberIndices.includes(cluster.representativeIndex)) {
+      throw new RangeError(
+        `projectClusterDisposition: cluster representativeIndex ${cluster.representativeIndex} is not one of its own memberIndices [${cluster.memberIndices.join(", ")}]`
+      );
+    }
+    if (cluster.memberIndices.length <= 1) continue; // singleton: shape validated above, nothing to project.
+    const representative = result[cluster.representativeIndex];
+    for (const memberIndex of cluster.memberIndices) {
+      const target = result[memberIndex];
+      target.judgeDisposition = representative.judgeDisposition;
+      target.judgeRationale = representative.judgeRationale;
+      if (representative.judgeCriterion !== undefined) target.judgeCriterion = representative.judgeCriterion;
+      else delete target.judgeCriterion;
+      if (representative.followUpDraft !== undefined) target.followUpDraft = representative.followUpDraft;
+      else delete target.followUpDraft;
+    }
+  }
+  return result;
+}
+
+/**
+ * Reduce an ACT list to at most one finding per acted cluster — the fixer's
+ * one-remediation-per-root-cause input. `allFindings` is the SAME array
+ * `clusters` was computed against; each act finding is matched back to its
+ * original position in it by reference, then to that position's cluster.
+ *
+ * A cluster's `representativeIndex` is by construction its smallest member
+ * index (see {@link clusterFindings}), so — given `actFindings` preserves
+ * the round's original relative order, which every producer in this
+ * pipeline does — the first member of a cluster encountered here is always
+ * either the representative itself, or, when the representative was not
+ * itself act-disposed, the earliest-index act member of that cluster: the
+ * exact preference rule this function implements, with no extra bookkeeping.
+ *
+ * A finding whose cluster cannot be resolved (absent from `allFindings`, or
+ * no cluster covers its position) passes through unchanged — fail-open,
+ * never silently dropped.
+ *
+ * @param {Array<object>} actFindings
+ * @param {Array<{memberIndices: number[], representativeIndex: number}>} clusters
+ * @param {Array<object>} allFindings
+ * @returns {Array<object>}
+ */
+export function dedupeActListByCluster(actFindings, clusters, allFindings) {
+  if (!Array.isArray(actFindings)) {
+    throw new TypeError("dedupeActListByCluster requires actFindings to be an array");
+  }
+  const clusterList = Array.isArray(clusters) ? clusters : [];
+  const findingsList = Array.isArray(allFindings) ? allFindings : [];
+
+  const representativeIndexByPosition = new Map();
+  for (const cluster of clusterList) {
+    if (!cluster || !Array.isArray(cluster.memberIndices) || !Number.isInteger(cluster.representativeIndex)) continue;
+    for (const memberIndex of cluster.memberIndices) {
+      representativeIndexByPosition.set(memberIndex, cluster.representativeIndex);
+    }
+  }
+
+  const seenClusters = new Set();
+  const kept = [];
+  for (const finding of actFindings) {
+    const position = findingsList.indexOf(finding);
+    const representativeIndex = position === -1 ? undefined : representativeIndexByPosition.get(position);
+    if (representativeIndex === undefined) {
+      kept.push(finding); // Fail-open: unresolvable membership always passes through.
+      continue;
+    }
+    if (seenClusters.has(representativeIndex)) continue;
+    seenClusters.add(representativeIndex);
+    kept.push(finding);
+  }
+  return kept;
+}
+
+/**
+ * A "clean" verdict is invalid the moment any finding was acted on — an
+ * acted finding is, by definition, unresolved work. Throws a clear Error on
+ * `overallVerdict === "clean" && actCount > 0`; returns `overallVerdict`
+ * unchanged otherwise.
+ *
+ * @param {unknown} overallVerdict
+ * @param {number} actCount — non-negative integer; fails closed otherwise.
+ * @returns {unknown} `overallVerdict`, unchanged.
+ */
+export function assertCleanImpliesNoAct(overallVerdict, actCount) {
+  if (!Number.isInteger(actCount) || actCount < 0) {
+    throw new TypeError("assertCleanImpliesNoAct requires actCount to be a non-negative integer");
+  }
+  if (overallVerdict === "clean" && actCount > 0) {
+    throw new Error("clean verdict is invalid with a nonzero act count: any acted finding prevents clean");
+  }
+  return overallVerdict;
+}

package/src/loop/fixer-disposition.mjs

@@ -0,0 +1,200 @@
+// GATE-EXEC-FIXER-DISPOSITION-BOUNDARY (skills/docs/gate-review-sub-loop-contract.md):
+// fail closed when a fixer push leaves the review threads it claims to have
+// tackled incomplete (missing evidence, uncontained commit, unreplied, or
+// unresolved). This module is a PURE evaluator — every GitHub/git fact
+// (live thread state, commit containment) is injected as data, never fetched
+// here, so the same decision is shared verbatim across every harness.
+
+/** Disposition values a handoff entry may carry. Only "tackled" entries are
+ * auto-disposed by evaluateFixerDisposition; every other value keeps its
+ * existing judgment path untouched (see the boundary rule's scope note). */
+export const FIXER_DISPOSITION_KIND = Object.freeze({
+  TACKLED: "tackled",
+  DEFERRED: "deferred",
+  REJECTED: "rejected",
+});
+
+export const FIXER_DISPOSITION_FAILED_STEP = Object.freeze({
+  MISSING_FROM_HANDOFF: "missing_from_handoff",
+  COMMIT_NOT_CONTAINED: "commit_not_contained",
+  REPLY_MISSING: "reply_missing",
+  NOT_RESOLVED: "not_resolved",
+});
+
+// The only legal next action while disposition is incomplete. Kept as a plain
+// literal (not imported from pr-gate-coordination.mjs) so this module stays a
+// dependency-free leaf; pr-gate-coordination.mjs's own PR_CHECKPOINT_ACTION
+// token for this action is asserted (by test) to equal this same string.
+export const COMPLETE_FIXER_DISPOSITION_ACTION = "complete_fixer_disposition";
+
+// Broader than pr-gate-coordination's postDraftForbidden: the failure this
+// boundary closes is the NEXT review/gate round opening over a dirty review
+// surface, so every review-(re)request and gate-dispatch token is forbidden
+// too, not just the draft/merge transition tokens. Literal tokens (not
+// imported) for the same dependency-free-leaf reason as above.
+export const FIXER_DISPOSITION_FORBIDDEN_ACTIONS = Object.freeze([
+  "run_draft_gate",
+  "reconcile_draft_gate",
+  "mark_ready_for_review",
+  "request_copilot_review",
+  "rerequest_copilot_review",
+  "run_pre_approval_gate",
+  "await_final_human_approval",
+  "declare_merge_ready",
+]);
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Validate + normalize a raw fixer-disposition handoff. Throws on any
+ * structural gap the evaluator must never silently tolerate: a missing
+ * headSha, a non-array dispositions field, a missing
+ * threadId/fixingCommitSha/disposition on any entry, an unrecognized
+ * disposition value, or a duplicate threadId/fingerprint across entries.
+ *
+ * @param {object} raw
+ * @returns {{ headSha: string, dispositions: Array<{ threadId: string, fingerprint: string|null, fixingCommitSha: string, disposition: string, validation: string|null }> }}
+ */
+export function normalizeFixerDispositionHandoff(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Fixer disposition handoff must be an object");
+  }
+  if (!isNonEmptyString(raw.headSha)) {
+    throw new Error("Fixer disposition handoff is missing headSha");
+  }
+  if (raw.dispositions !== undefined && !Array.isArray(raw.dispositions)) {
+    throw new Error("Fixer disposition handoff dispositions must be an array");
+  }
+  const rawDispositions = raw.dispositions ?? [];
+  const seenThreadIds = new Set();
+  const seenFingerprints = new Set();
+  const dispositions = rawDispositions.map((entry, index) => {
+    if (!entry || typeof entry !== "object") {
+      throw new Error(`Fixer disposition handoff entry ${index} must be an object`);
+    }
+    if (!isNonEmptyString(entry.threadId)) {
+      throw new Error(`Fixer disposition handoff entry ${index} is missing threadId`);
+    }
+    const threadId = entry.threadId.trim();
+    if (seenThreadIds.has(threadId)) {
+      throw new Error(`Fixer disposition handoff has a duplicate threadId: ${threadId}`);
+    }
+    seenThreadIds.add(threadId);
+    if (!isNonEmptyString(entry.fixingCommitSha)) {
+      throw new Error(`Fixer disposition handoff entry for thread ${threadId} is missing fixingCommitSha`);
+    }
+    if (!isNonEmptyString(entry.disposition)) {
+      throw new Error(`Fixer disposition handoff entry for thread ${threadId} is missing disposition`);
+    }
+    const fingerprint = isNonEmptyString(entry.fingerprint) ? entry.fingerprint.trim() : null;
+    if (fingerprint !== null) {
+      if (seenFingerprints.has(fingerprint)) {
+        throw new Error(`Fixer disposition handoff has a duplicate fingerprint: ${fingerprint}`);
+      }
+      seenFingerprints.add(fingerprint);
+    }
+    const disposition = entry.disposition.trim().toLowerCase();
+    if (!Object.values(FIXER_DISPOSITION_KIND).includes(disposition)) {
+      throw new Error(`Fixer disposition handoff entry for thread ${threadId} has an unrecognized disposition: ${disposition}`);
+    }
+    return {
+      threadId,
+      fingerprint,
+      fixingCommitSha: entry.fixingCommitSha.trim(),
+      disposition,
+      validation: isNonEmptyString(entry.validation) ? entry.validation.trim() : null,
+    };
+  });
+  return {
+    headSha: raw.headSha.trim(),
+    dispositions,
+  };
+}
+
+function formatIncompleteReason(incomplete) {
+  const parts = incomplete.map((entry) => (
+    `thread ${entry.threadId} (expected commit ${entry.expectedCommit ?? "unknown"}, failed step: ${entry.failedStep})`
+  ));
+  return `Fixer disposition is incomplete for ${incomplete.length} tackled thread(s): ${parts.join("; ")}. `
+    + `The only legal next action is ${COMPLETE_FIXER_DISPOSITION_ACTION}.`;
+}
+
+/**
+ * PURE evaluator: given a normalized handoff, the live thread state, and an
+ * injected commit-containment fact table, decide whether every thread the
+ * fixer claims to have tackled is fully disposed (commit contained, replied
+ * with that commit's evidence, and resolved). No I/O — every fact the
+ * decision needs is a plain argument, which is what keeps this seam shared
+ * verbatim across harnesses.
+ *
+ * @param {object} params
+ * @param {{ headSha: string, dispositions: Array<object> }} params.handoff - raw or already-normalized; ALWAYS re-validated via normalizeFixerDispositionHandoff (idempotent on already-normalized input), so a malformed array-bearing handoff can never bypass schema+enum validation just by already carrying an array
+ * @param {Array<{ threadId: string, isResolved: boolean, replyBodies?: string[], claimedTackled?: boolean }>} [params.liveThreads]
+ * @param {Record<string, boolean>} [params.containment] - fixingCommitSha -> true when the observed PR head contains it
+ * @returns {{ ok: boolean, incomplete: Array<{ threadId: string, expectedCommit: string|null, failedStep: string }>, forbiddenActions: string[], nextAction: string|null, reason: string|null }}
+ */
+export function evaluateFixerDisposition({ handoff, liveThreads = [], containment = {} } = {}) {
+  const normalizedHandoff = normalizeFixerDispositionHandoff(handoff ?? {});
+  const handoffByThreadId = new Map(normalizedHandoff.dispositions.map((entry) => [entry.threadId, entry]));
+  const liveByThreadId = new Map(
+    (Array.isArray(liveThreads) ? liveThreads : [])
+      .filter((entry) => entry && typeof entry.threadId === "string")
+      .map((entry) => [entry.threadId, entry]),
+  );
+
+  // The must-check set: every handoff entry explicitly marked "tackled", plus
+  // any live thread independently flagged claimedTackled (e.g. a fixer's own
+  // claim the CLI cross-referenced against live GitHub state) that has no
+  // handoff counterpart at all — that gap is exactly missing_from_handoff.
+  const tackledThreadIds = new Set();
+  for (const entry of normalizedHandoff.dispositions) {
+    if (entry.disposition === FIXER_DISPOSITION_KIND.TACKLED) {
+      tackledThreadIds.add(entry.threadId);
+    }
+  }
+  for (const liveThread of liveByThreadId.values()) {
+    if (liveThread.claimedTackled === true) {
+      tackledThreadIds.add(liveThread.threadId);
+    }
+  }
+
+  const incomplete = [];
+  for (const threadId of tackledThreadIds) {
+    const handoffEntry = handoffByThreadId.get(threadId) ?? null;
+    if (!handoffEntry) {
+      incomplete.push({ threadId, expectedCommit: null, failedStep: FIXER_DISPOSITION_FAILED_STEP.MISSING_FROM_HANDOFF });
+      continue;
+    }
+    const expectedCommit = handoffEntry.fixingCommitSha;
+    // Non-goal enforcement: a SHA alone is never evidence. Only an injected
+    // containment[sha] === true (the observed PR head provably contains the
+    // commit) can authorize the reply/resolve steps below.
+    if (containment?.[expectedCommit] !== true) {
+      incomplete.push({ threadId, expectedCommit, failedStep: FIXER_DISPOSITION_FAILED_STEP.COMMIT_NOT_CONTAINED });
+      continue;
+    }
+    const liveThread = liveByThreadId.get(threadId) ?? null;
+    const replyBodies = Array.isArray(liveThread?.replyBodies) ? liveThread.replyBodies : [];
+    const hasEvidencedReply = replyBodies.some((body) => (
+      typeof body === "string" && body.toLowerCase().includes(expectedCommit.toLowerCase())
+    ));
+    if (!hasEvidencedReply) {
+      incomplete.push({ threadId, expectedCommit, failedStep: FIXER_DISPOSITION_FAILED_STEP.REPLY_MISSING });
+      continue;
+    }
+    if (liveThread?.isResolved !== true) {
+      incomplete.push({ threadId, expectedCommit, failedStep: FIXER_DISPOSITION_FAILED_STEP.NOT_RESOLVED });
+    }
+  }
+
+  const ok = incomplete.length === 0;
+  return {
+    ok,
+    incomplete,
+    forbiddenActions: ok ? [] : [...FIXER_DISPOSITION_FORBIDDEN_ACTIONS],
+    nextAction: ok ? null : COMPLETE_FIXER_DISPOSITION_ACTION,
+    reason: ok ? null : formatIncompleteReason(incomplete),
+  };
+}

package/src/loop/gate-fanin.mjs

@@ -68,6 +68,51 @@ export function backoffMaxConcurrent(maxConcurrent) {
   return Math.max(1, Math.floor(cap / 2));
 }
 
+/** 30s/60s/120s same-unit retry schedule (`GATE-EXEC-DISPATCH-RETRY-BACKOFF`). */
+const DISPATCH_RETRY_BACKOFF_SCHEDULE_MS = Object.freeze([30_000, 60_000, 120_000]);
+
+/**
+ * True when `errorClass` names a transient provider error (429 rate-limit or
+ * any 5xx), the class `GATE-EXEC-DISPATCH-RETRY-BACKOFF` retries — as opposed
+ * to a hard 4xx (e.g. `402`), which never is.
+ * @param {string|number} errorClass
+ * @returns {boolean}
+ */
+function isTransientDispatchErrorClass(errorClass) {
+  const s = String(errorClass ?? "").trim();
+  return s === "429" || /^5\d\d$/.test(s) || s.toLowerCase() === "5xx";
+}
+
+/**
+ * Pure retry-decision policy for `GATE-EXEC-DISPATCH-RETRY-BACKOFF`: whether a
+ * failed dispatch retries the SAME unit, and when a batch reduction is due.
+ *
+ * A transient failure (429 / 5xx) always retries — the round is never aborted
+ * on a transient error, safe because a retry overwrites the same idempotent
+ * per-angle findings artifact path (`GATE-EXEC-COLLECTABLE-DISPATCH`), never
+ * minting a second one. `delayMs` follows the 30s/60s/120s schedule (holding
+ * at 120s past the 3rd attempt); `reduceConcurrency` flips true starting at
+ * the 3rd exhausted attempt (`attempt` index 2), signaling the caller to halve
+ * the active batch via `backoffMaxConcurrent` — this function only signals
+ * WHEN, the halving itself stays `backoffMaxConcurrent`'s job.
+ *
+ * A hard 4xx (e.g. `402 Insufficient Balance`) is never transient: it escalates
+ * to the supervisor/operator immediately instead of retrying into the same wall.
+ *
+ * @param {number} attempt — 0-based count of prior failed attempts on this unit
+ * @param {string|number} errorClass — e.g. `"429"`, `"500"`, `"5xx"`, `"402"`
+ * @returns {{ retry: true, delayMs: number, reduceConcurrency: boolean } | { retry: false, escalate: true }}
+ */
+export function planDispatchRetry(attempt, errorClass) {
+  if (!isTransientDispatchErrorClass(errorClass)) {
+    return { retry: false, escalate: true };
+  }
+  const n = Number.isInteger(attempt) && attempt >= 0 ? attempt : 0;
+  const lastIndex = DISPATCH_RETRY_BACKOFF_SCHEDULE_MS.length - 1;
+  const delayMs = DISPATCH_RETRY_BACKOFF_SCHEDULE_MS[Math.min(n, lastIndex)];
+  return { retry: true, delayMs, reduceConcurrency: n >= lastIndex };
+}
+
 /**
  * Reviewer-budget preflight for a gate fan-out.
  *