mandrel 2.58.0 → 2.60.0

package/.agents/scripts/lib/gh-exec.js

@@ -587,4 +587,164 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
  */
 export const gh = createGh();
 
+/* ---------------------------------------------------------------------- */
+/* GraphQL reachability preflight (Story #5355)                            */
+/* ---------------------------------------------------------------------- */
+
+/**
+ * The `gh pr` subcommands the facade above reaches GitHub's pull-request
+ * surface through. `gh` routes **every one of them** through GitHub's
+ * GraphQL API, so they stand or fall together: where GraphQL answers HTTP
+ * 403 there is no PR operation left to attempt, not a degraded subset.
+ *
+ * Kept beside the `pr` facade it enumerates, and module-private, so the
+ * refusal text below cannot drift from the surface it claims to describe.
+ */
+const GH_PR_SUBCOMMANDS = Object.freeze([
+  'view',
+  'create',
+  'edit',
+  'merge',
+  'update-branch',
+  'list',
+]);
+
+/**
+ * The cheapest authenticated GraphQL read there is — "who am I". It touches
+ * no repository, needs no scope beyond the one `gh` already has, and costs a
+ * single API read, which is the whole budget the preflight is allowed.
+ */
+const GRAPHQL_PROBE_QUERY = 'query{viewer{login}}';
+
+/** Wall-clock ceiling for the probe. A hung probe must never hold a close. */
+const GRAPHQL_PROBE_TIMEOUT_MS = 15_000;
+
+/**
+ * Classify a failed probe into one of the two refusing verdicts, or back to
+ * `available` when the failure says nothing about GraphQL reachability.
+ *
+ * The fall-through is deliberate and it is **fail-open**: a timeout, a DNS
+ * blip or a novel `gh` error is not evidence that this session cannot reach
+ * GraphQL, and blocking a healthy close on an ambiguous probe would trade a
+ * rare late failure for a common early one. Such a probe reports `available`
+ * with `reason: 'probe-inconclusive'`, so the log still shows it happened.
+ *
+ * A **rate limit is that same fail-open case wearing a 403** (Story #5362).
+ * GitHub answers both its primary and its secondary rate limits with HTTP
+ * 403, and a throttled session says nothing about whether GraphQL is
+ * reachable from here — so the rate-limit test runs *before* the bare status
+ * match, and it accepts either shape the evidence arrives in: the typed
+ * {@link GhRateLimitError} the shared classifier already produces, or
+ * rate-limit text riding on an otherwise untyped 403. Classifying it
+ * `unavailable` would block the Story behind a remedy that cannot work —
+ * "re-run from a local session" is an instruction to go reproduce the same
+ * throttle. A 403 with no rate-limit evidence is still the web-session shape
+ * this preflight was built for and still refuses.
+ *
+ * @param {unknown} err The rejection `gh.api` produced.
+ * @returns {{ verdict: 'available'|'unavailable'|'auth-failed', reason: string }}
+ */
+function classifyGraphqlProbeFailure(err) {
+  const haystack = `${err?.stderr ?? ''}\n${err?.message ?? ''}`.toLowerCase();
+  const authShaped =
+    err instanceof GhAuthError ||
+    err instanceof GhScopeError ||
+    /http 401|bad credentials|requires authentication|not logged into|gh auth login/.test(
+      haystack,
+    );
+  if (authShaped) return { verdict: 'auth-failed', reason: 'auth' };
+  const rateLimited =
+    err instanceof GhRateLimitError || /rate[ -]?limit/.test(haystack);
+  if (rateLimited)
+    return { verdict: 'available', reason: 'rate-limited-inconclusive' };
+  if (/http 403|403 forbidden/.test(haystack))
+    return { verdict: 'unavailable', reason: 'http-403' };
+  return { verdict: 'available', reason: 'probe-inconclusive' };
+}
+
+/**
+ * Probe whether GitHub's GraphQL API is reachable from this session.
+ *
+ * One `gh api graphql` read, three verdicts:
+ *
+ *   - `available`    — GraphQL answered (or the probe failed in a way that
+ *                      says nothing about reachability — an ambiguous error
+ *                      or a rate limit; see the fail-open note on
+ *                      {@link classifyGraphqlProbeFailure}).
+ *   - `unavailable`  — GraphQL answered HTTP 403. This is the Claude Code
+ *                      web-session shape: the token is fine, the endpoint
+ *                      is simply not reachable from here, so the entire
+ *                      `gh pr` surface is gated.
+ *   - `auth-failed`  — `gh` has no usable token (missing, expired or
+ *                      under-scoped). A different fault with a different
+ *                      remedy, deliberately NOT flattened into the one
+ *                      above: telling an unauthenticated operator to "run
+ *                      this somewhere else" sends them to reproduce it.
+ *
+ * Never throws — a preflight that can fail a close is worse than no
+ * preflight at all.
+ *
+ * @param {{ ghFacade?: { api: Function } }} [opts]
+ *   `ghFacade` is the injection seam; production passes nothing.
+ * @returns {Promise<{ verdict: string, available: boolean, reason: string,
+ *   detail: string|null }>}
+ */
+export async function probeGraphqlAvailability({ ghFacade = gh } = {}) {
+  try {
+    await ghFacade.api({
+      method: 'POST',
+      endpoint: 'graphql',
+      body: { query: GRAPHQL_PROBE_QUERY },
+      execOpts: { timeoutMs: GRAPHQL_PROBE_TIMEOUT_MS },
+    });
+    return {
+      verdict: 'available',
+      available: true,
+      reason: 'ok',
+      detail: null,
+    };
+  } catch (err) {
+    const { verdict, reason } = classifyGraphqlProbeFailure(err);
+    return {
+      verdict,
+      available: verdict === 'available',
+      reason,
+      detail: describeGhFailure(err),
+    };
+  }
+}
+
+/**
+ * Render a refusing probe verdict as the operator-facing blocker.
+ *
+ * The two refusals get two messages because they have two remedies. The
+ * unavailable text names all three things the operator needs — that GraphQL
+ * is unavailable *in this session*, the whole `gh pr` surface that gates, and
+ * that the fix is to run the close from a local session rather than to retry
+ * here.
+ *
+ * @param {{ verdict?: string, detail?: string|null }} probe
+ * @returns {string}
+ */
+export function describeGraphqlPreflight({ verdict, detail } = {}) {
+  const suffix = detail ? ` (gh said: ${detail})` : '';
+  if (verdict === 'auth-failed') {
+    return (
+      'GitHub authentication failed: `gh` has no usable token (missing, expired, or missing a ' +
+      'required scope), so no GitHub call this close makes can succeed. This is NOT the ' +
+      'GraphQL-unavailable condition and moving sessions will not fix it — re-authenticate ' +
+      '(`gh auth login`, or export a valid token) and re-run close where you are.' +
+      suffix
+    );
+  }
+  const subcommands = GH_PR_SUBCOMMANDS.map((s) => `\`gh pr ${s}\``).join(', ');
+  return (
+    'GitHub GraphQL is unavailable in this session (HTTP 403). `gh` routes the entire pull-request ' +
+    `surface through GraphQL — ${subcommands} — so this close can neither open, inspect, nor merge ` +
+    'a pull request, and every later phase would fail the same way. Retrying here will not help: ' +
+    're-run the close from a local session, where GraphQL is reachable.' +
+    suffix
+  );
+}
+
 export default exec;

package/.agents/scripts/lib/maintainability-engine.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
-import escomplex from 'typhonjs-escomplex';
 import { install as installAstCompat } from './escomplex-ast-compat.js';
+import { analyzeModule } from './escomplex-kernel.js';
 import { transpileIfNeeded } from './transpile.js';
 
 /**
@@ -45,7 +45,7 @@ const UNSCORABLE = 0;
  */
 export function scoreSource(sourceCode) {
   try {
-    const score = escomplex.analyzeModule(sourceCode)?.maintainability;
+    const score = analyzeModule(sourceCode)?.maintainability;
     return Number.isFinite(score)
       ? { score, unscorable: false, reason: null }
       : unscorable(`kernel returned a non-finite index (${String(score)})`);
@@ -141,7 +141,7 @@ export function scoreFile(filePath) {
  */
 export function calculateReport(sourceCode) {
   try {
-    const result = escomplex.analyzeModule(sourceCode);
+    const result = analyzeModule(sourceCode);
     const methods = (result.methods ?? []).map((m) => ({
       name: m.name,
       maintainability:

package/.agents/scripts/lib/observability/source-classifier.js

@@ -112,6 +112,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'coverage-capture.js',
   'deliver-light.js',
   'deliver-recover.js',
+  'deliver-run.js',
   'diagnose-friction.js',
   'diagnose.js',
   'drain-pending-cleanup.js',

package/.agents/scripts/lib/orchestration/ceremony-routing.js

@@ -1,84 +1,61 @@
 /**
- * lib/orchestration/ceremony-routing.js — ceremony-profile + derived-level
- * acceptance ceremony resolver.
- *
- * The sibling of `review-depth.js#resolveDepth`: it folds the operator ceremony
- * profile and the **derived** change level into a per-cluster ceremony decision
- * for the single-delivery acceptance critic — **fresh-context spawn** vs the
- * contract-identical **inline** critic. It does NOT invent a new risk score and
- * it does NOT own clustering.
- *
- * ## One derived source, two decisions (Story #4542)
- *
- * `derivedLevel` comes from `review-depth.js#deriveChangeLevel` — the same call
- * that feeds review depth — so both ceremony decisions read one observable
- * signal: does the change set touch a sensitive path registered in
- * `audit-rules.json`? Previously this consumed the planner's own risk verdict,
- * which meant a confident all-low self-assertion bought *less* independent
- * checking than authoring nothing at all. A derived level cannot be talked down.
- *
- * ## Ceremony profiles (`delivery.routing.ceremonyProfile`)
- *
- *   - `minimal`  — always `inline` (no fresh critic spawn).
- *                  Use for tiny N=1 Stories the operator trusts.
- *   - `standard` — level-routed (default). Low → inline; high or
- *                  underivable → fresh.
- *   - `strict`   — always `fresh` regardless of the derived level.
- *
- * ## The load-bearing invariant (M4-B acceptance floor — DO NOT VIOLATE)
- *
- * Risk-routing chooses fresh-vs-inline **PER CLUSTER**. It NEVER changes the
- * cluster COUNT — the caller owns clustering and hands this module a cluster
- * index. A low-risk Story still gets one verdict per cluster — just possibly
- * authored inline instead of by a fresh sub-agent. This module takes the
- * cluster index as an INPUT and returns a decision for that one cluster; it
- * has no way to add or remove clusters.
- *
- * ## One verdict-owner per cluster (Story #4723)
- *
- * The resolved decision names the cluster's **single verdict owner** via
+ * lib/orchestration/ceremony-routing.js — ceremony-profile acceptance
+ * ceremony resolver.
+ *
+ * The sibling of `review-depth.js#resolveDepth`: it folds the operator
+ * ceremony profile into a per-Story ceremony decision for the acceptance
+ * verdict — **fresh-context spawn** vs the contract-identical **inline**
+ * self-eval. It does NOT invent a risk score, and it no longer routes off
+ * anything the diff says.
+ *
+ * ## The profile is the whole decision (Story #5343)
+ *
+ *   - `minimal`  — `inline`.
+ *   - `standard` — `inline` (the **default**).
+ *   - `strict`   — `fresh`.
+ *
+ * A frontier-model worker scoring its own `acceptance[]` items against the
+ * `verify[]` output it just produced is the default the delivery diet settled
+ * on: the fresh critic's isolation bought a second full-context boot per
+ * Story and, measured across the run, changed no verdict the inline pass did
+ * not already reach. `strict` keeps the fresh-context critic for
+ * high-assurance surfaces, and is the one profile that spawns one.
+ *
+ * **The derived change level is not an input here (Story #5366).** It is
+ * still derived and still printed by `ceremony-derive.js`, because **review
+ * depth** reads it — `review-depth.js#resolveDepth` continues to resolve
+ * `deep` for any sensitive class, and that is untouched. What changed with
+ * #5343 is which of the two decisions the level feeds: review depth, not the
+ * verdict owner. Story #5366 finished the job by removing it (and the
+ * per-cluster index beside it) from this function's signature: a decision
+ * function that accepts what it ignores reads, to every caller and every
+ * reviewer, as though the input still mattered. An unenumerable diff is
+ * therefore not a fail-safe escalation here at all; it escalates review
+ * depth instead, where the evidence it withholds actually matters.
+ *
+ * ## One verdict-owner per Story (Story #4723, narrowed by #5343)
+ *
+ * The resolved decision names the Story's **single verdict owner** via
  * `verdictOwner`: `'fresh-critic'` when the mode is `fresh`,
  * `'inline-self-eval'` when the mode is `inline`. Exactly one pass authors
- * the cluster's verdict — the fresh maker-blind critic OR the
+ * the Story's verdict — the fresh maker-blind critic OR the
  * contract-identical inline self-eval, never both, and never an additional
  * pre-pass self-assessment before the owner runs. `acceptance-eval.js` is
  * the deterministic SCORER of that one authored verdict (schema validation,
  * round cap, proceed/redraft/block) — it is not a third pass over the
- * criteria. This removes a redundant pass only; it never removes a
- * cluster's verdict (the M4-B floor above holds).
- *
- * ## Tier rules (per cluster, `standard` profile)
- *
- *   - `high` level       → `fresh`   (a sensitive path was touched — a
- *                                     fresh-context maker-blind spawn).
- *   - `low` level        → `inline`  (the contract-identical inline critic).
- *   - missing / unknown  → `fresh`   (fail-safe: the diff could not be
- *                                     enumerated, so there is no evidence the
- *                                     change is unremarkable; treat it as
- *                                     needing the full fresh-context ceremony,
- *                                     exactly as `resolveDepth` degrades to
- *                                     `standard` on the same signal).
- *
- * ## No sampling floor (Story #5313)
- *
- * The maker-checker sampling floor (`delivery.routing.freshCriticSampleRate`,
- * `sampledFresh`) bounded independent checking by a cluster-index stride —
- * a count, not a risk signal — and was retired with the delivery diet. The
- * standard profile now routes purely off the derived level, so the decision
- * carries no `sampled` field and `clusterIndex` is accepted only for call-site
- * compatibility (it never changes the outcome).
+ * criteria. The verdict is **one file per Story**, scored in one gate call;
+ * the cluster protocol that used to split it was retired with #5343.
  *
  * Pure and total: inputs in, decision out. No I/O, no throws. `null` /
- * `undefined` / malformed inputs degrade to `fresh` + `full` ceremony.
+ * `undefined` / malformed inputs degrade to the default profile.
  *
  * @typedef {'fresh'|'inline'} CeremonyMode
  * @typedef {'fresh-critic'|'inline-self-eval'} VerdictOwner
- * @typedef {import('./review-depth.js').ChangeLevel} ChangeLevel
  * @typedef {(typeof CEREMONY_PROFILES)[number]} CeremonyProfile
  */
 
 /**
- * Map a resolved ceremony mode to the cluster's single verdict owner
+ * Map a resolved ceremony mode to the Story's single verdict owner
  * (Story #4723). Total: any non-`fresh` value maps to the inline
  * self-eval owner, mirroring how the mode itself degrades.
  *
@@ -102,6 +79,28 @@ const CEREMONY_PROFILES = Object.freeze(['minimal', 'standard', 'strict']);
 /** The profile an absent or unrecognized value degrades to. */
 const DEFAULT_CEREMONY_PROFILE = 'standard';
 
+/**
+ * The one routing table: profile → mode + the reason the decision carries.
+ * `strict` is the only profile that spawns a fresh critic.
+ *
+ * @type {Readonly<Record<CeremonyProfile, { mode: CeremonyMode, reason: string }>>}
+ */
+const PROFILE_DECISIONS = Object.freeze({
+  minimal: {
+    mode: 'inline',
+    reason: 'ceremonyProfile=minimal: inline self-eval (no fresh spawn)',
+  },
+  standard: {
+    mode: 'inline',
+    reason:
+      'ceremonyProfile=standard: inline self-eval authors the Story verdict',
+  },
+  strict: {
+    mode: 'fresh',
+    reason: 'ceremonyProfile=strict: fresh-context critic',
+  },
+});
+
 /**
  * Normalize an operator/config ceremony profile. Unknown values degrade to
  * `standard` (fail toward the documented default, not toward less ceremony).
@@ -116,16 +115,13 @@ function normalizeCeremonyProfile(value) {
 }
 
 /**
- * Resolve the acceptance ceremony for one cluster from the ceremony profile
- * and the derived change level. See the module header for the tier rules and
- * the untouchable cluster-count invariant.
+ * Resolve the acceptance ceremony for one Story from the ceremony profile —
+ * its one and only input. See the module header for the profile table and why
+ * the derived change level is not among them.
  *
  * @param {{
- *   derivedLevel?: (ChangeLevel|string|null|undefined),
- *   clusterIndex?: (number|null|undefined),
  *   ceremonyProfile?: (CeremonyProfile|string|null|undefined),
- * }} [input] `clusterIndex` is accepted for call-site compatibility only
- *   (Story #5313 retired the sampling floor that read it).
+ * }} [input]
  * @returns {{
  *   mode: CeremonyMode,
  *   reason: string,
@@ -134,64 +130,10 @@ function normalizeCeremonyProfile(value) {
  * }}
  */
 export function resolveCeremonyForRisk(input = {}) {
-  const decision = resolveCeremonyDecision(input);
-  return { ...decision, verdictOwner: verdictOwnerForMode(decision.mode) };
-}
-
-/**
- * Internal mode/reason resolution — the tier rules. `resolveCeremonyForRisk`
- * decorates the result with the single `verdictOwner` derived from the mode
- * (Story #4723).
- *
- * @param {Parameters<typeof resolveCeremonyForRisk>[0]} [input]
- * @returns {{
- *   mode: CeremonyMode,
- *   reason: string,
- *   profile: CeremonyProfile,
- * }}
- */
-function resolveCeremonyDecision(input = {}) {
-  const derivedLevel =
-    input && typeof input === 'object' ? input.derivedLevel : undefined;
-  const profile = normalizeCeremonyProfile(
-    input && typeof input === 'object' ? input.ceremonyProfile : undefined,
-  );
-
-  if (profile === 'minimal') {
-    return {
-      mode: 'inline',
-      reason: 'ceremonyProfile=minimal: inline critic (no fresh spawn)',
-      profile,
-    };
-  }
-  if (profile === 'strict') {
-    return {
-      mode: 'fresh',
-      reason: 'ceremonyProfile=strict: fresh-context critic',
-      profile,
-    };
-  }
-
-  if (derivedLevel === 'high') {
-    return {
-      mode: 'fresh',
-      reason: 'sensitive path touched: fresh-context critic',
-      profile,
-    };
-  }
-  if (derivedLevel === 'low') {
-    return {
-      mode: 'inline',
-      reason: 'no sensitive path touched: contract-identical inline critic',
-      profile,
-    };
-  }
-  // Missing / unknown / malformed level → fail-safe fresh + full ceremony,
-  // matching how resolveDepth degrades to `standard` on the same signal.
-  return {
-    mode: 'fresh',
-    reason:
-      'change level underivable: fail-safe fresh-context critic + full ceremony',
-    profile,
-  };
+  // Optional chaining rather than a typeof guard: `normalizeCeremonyProfile`
+  // is already total over anything that is not one of the three names, so a
+  // non-object input degrades to `standard` through the same door.
+  const profile = normalizeCeremonyProfile(input?.ceremonyProfile);
+  const { mode, reason } = PROFILE_DECISIONS[profile];
+  return { mode, reason, profile, verdictOwner: verdictOwnerForMode(mode) };
 }

package/.agents/scripts/lib/orchestration/ci-rerun-guard.js

@@ -24,6 +24,19 @@
  * (`file-ci-gap.js`, carrying the run link and failure signature the digest
  * already holds) is required before it can proceed.
  *
+ * **One rerun after a recorded verdict (Story #5343).** The single exception,
+ * and it is evidence-gated rather than discretionary: once `file-ci-gap.js`
+ * has filed a `capacity` or `unreproducible-tier` verdict **for the current
+ * head SHA**, it stamps a `rerunAllowance` on the digest, and exactly one
+ * same-SHA green is then admitted — the digest is retired and the delivery
+ * proceeds. This closes the one shape where the rule stranded a correct
+ * delivery: a runner that ran out of something has no fix at source to make,
+ * so the branch could never move its head SHA and the block needed a human to
+ * clear. Every other same-SHA green is still a violation, the allowance is
+ * spent the moment it is honoured (it dies with the digest), and a second red
+ * after the rerun is real: it writes a fresh digest with no allowance, so it
+ * routes to Option 1 like any other red.
+ *
  * **Fail closed on an unverifiable green.** A digest whose head SHA is
  * missing, or a current head SHA that `gh` could not resolve, leaves no
  * evidence that the red was fixed at source. An unresolved red plus no
@@ -53,6 +66,20 @@ import {
 /** How many superseded unresolved reds a digest carries before the oldest is dropped. */
 const MAX_PRIOR_REDS = 10;
 
+/**
+ * The verdicts that earn the one same-SHA rerun (Story #5343). Both mean the
+ * failure is a property of the *environment*, proven — so no commit on the
+ * branch can move the head SHA to clear it. `pre-existing` is deliberately
+ * excluded: it reproduces on `main`, which is a real defect someone owns and
+ * a rerun cannot make go away.
+ *
+ * @type {readonly ['capacity', 'unreproducible-tier']}
+ */
+export const RERUN_ALLOWANCE_VERDICTS = Object.freeze([
+  'capacity',
+  'unreproducible-tier',
+]);
+
 /**
  * Resolve which ticket the digest is keyed to. Story #4539: the digest used
  * to be Epic-scoped by filename and returned `null` without an epic id — so
@@ -332,7 +359,9 @@ function renderDigestMarkdown(digest, failures) {
     '',
     'A green on THIS head SHA is a re-run of a failed job and is forbidden',
     '(`.agents/rules/ci-remediation.md` § Verifier). Fix at source and push a',
-    'new commit — the head SHA moving is what clears this digest.',
+    'new commit — the head SHA moving is what clears this digest. The one',
+    'exception: `file-ci-gap.js --verdict capacity|unreproducible-tier` records',
+    'an allowance for this head SHA, and exactly one rerun is then admitted.',
     '',
     '## `gh run view --log-failed` tail',
     '',
@@ -408,16 +437,89 @@ export function writeCiDigest({
   return { jsonPath: paths.jsonPath, mdPath: paths.mdPath };
 }
 
+/**
+ * Stamp the one-rerun allowance on the scope's digest (Story #5343).
+ *
+ * Called by `file-ci-gap.js` after it has filed the intake issue, so the
+ * allowance exists only where the evidence the filing carries does. It is
+ * keyed on the digest's own head SHA — the head the red was recorded
+ * against — so an allowance can never be honoured on a later head it was not
+ * earned for.
+ *
+ * Best-effort and non-throwing: a digest that cannot be re-read or re-written
+ * simply records no allowance, and the guard keeps blocking. Returns the
+ * recorded allowance, or `null` when none was written (no digest, an
+ * ineligible verdict, or an unresolved head SHA).
+ *
+ * @param {{
+ *   storyId?: number|string|null,
+ *   verdict: string,
+ *   tempRoot: string,
+ *   cwd: string,
+ *   now?: () => Date,
+ * }} opts
+ * @returns {{ verdict: string, headSha: string, recordedAt: string } | null}
+ */
+export function recordRerunAllowance({
+  storyId = null,
+  verdict,
+  tempRoot,
+  cwd,
+  now = () => new Date(),
+}) {
+  if (!RERUN_ALLOWANCE_VERDICTS.includes(verdict)) return null;
+  const paths = ciDigestPaths({ storyId, tempRoot, cwd });
+  const digest = readCiDigest({ storyId, tempRoot, cwd });
+  if (!paths || !digest?.headSha) return null;
+  const allowance = {
+    verdict,
+    headSha: digest.headSha,
+    recordedAt: now().toISOString(),
+  };
+  try {
+    writeFileSync(
+      paths.jsonPath,
+      `${JSON.stringify({ ...digest, rerunAllowance: allowance }, null, 2)}\n`,
+    );
+  } catch {
+    return null;
+  }
+  return allowance;
+}
+
+/**
+ * The allowance a digest carries for `headSha`, or `null`. An allowance
+ * recorded against a different head is not one: the red it was filed for is
+ * not the red being adjudicated.
+ *
+ * @param {object|null} digest
+ * @param {string|null} headSha
+ * @returns {{ verdict: string, headSha: string } | null}
+ */
+function allowanceFor(digest, headSha) {
+  const allowance = digest?.rerunAllowance;
+  return allowance &&
+    typeof allowance === 'object' &&
+    headSha &&
+    allowance.headSha === headSha &&
+    RERUN_ALLOWANCE_VERDICTS.includes(allowance.verdict)
+    ? allowance
+    : null;
+}
+
 /**
  * Adjudicate an all-green watch against any digest recorded for the scope.
  *
  * @param {{ digest: object|null, headSha: string|null }} opts
- * @returns {{ verdict: 'clean'|'fix-at-source'|'rerun'|'unverifiable', reason: string }}
- *   - `clean`         — no digest: this delivery never went red.
- *   - `fix-at-source` — the head SHA moved since the red; legal.
- *   - `rerun`         — green on the SAME head SHA; forbidden.
- *   - `unverifiable`  — an unresolved red with no head-SHA evidence either
- *                       side; fail closed and treat it as a rerun.
+ * @returns {{ verdict: 'clean'|'fix-at-source'|'rerun-permitted'|'rerun'|'unverifiable', reason: string }}
+ *   - `clean`           — no digest: this delivery never went red.
+ *   - `fix-at-source`   — the head SHA moved since the red; legal.
+ *   - `rerun-permitted` — same head SHA, but `file-ci-gap.js` recorded a
+ *                         `capacity` / `unreproducible-tier` verdict for it;
+ *                         the one sanctioned rerun (Story #5343).
+ *   - `rerun`           — green on the SAME head SHA; forbidden.
+ *   - `unverifiable`    — an unresolved red with no head-SHA evidence either
+ *                         side; fail closed and treat it as a rerun.
  */
 export function classifyGreenVerdict({ digest, headSha }) {
   if (!digest) return { verdict: 'clean', reason: 'no digest for this scope' };
@@ -429,10 +531,16 @@ export function classifyGreenVerdict({ digest, headSha }) {
     };
   }
   if (recorded === headSha) {
-    return {
-      verdict: 'rerun',
-      reason: `green on the SAME head SHA the red was recorded against (${headSha})`,
-    };
+    const allowance = allowanceFor(digest, headSha);
+    return allowance
+      ? {
+          verdict: 'rerun-permitted',
+          reason: `one rerun admitted: \`${allowance.verdict}\` verdict recorded for this head SHA (${headSha})`,
+        }
+      : {
+          verdict: 'rerun',
+          reason: `green on the SAME head SHA the red was recorded against (${headSha})`,
+        };
   }
   return {
     verdict: 'fix-at-source',
@@ -487,7 +595,10 @@ export function formatRerunViolation({ digest, headSha, prNumber, reason }) {
     '   <consumer|framework|platform> --evidence "<proof reading>"` — then',
     '   resume. It carries the run link and signature above, routes the filing',
     '   to whoever owns the fault, and updates the existing ticket when this',
-    '   signature has been seen before.',
+    '   signature has been seen before. A `capacity` or `unreproducible-tier`',
+    '   verdict also records the one-rerun allowance for this head SHA, so a',
+    '   single rerun of the failed job is then admitted; `pre-existing` does',
+    '   not, because it names a real defect a rerun cannot remove.',
   ].join('\n');
 }