mandrel 2.59.0 → 2.61.0

package/.agents/scripts/diagnose-friction.js

@@ -2,36 +2,10 @@
 /* node:coverage ignore file */
 
 /**
- * diagnose-friction.js — v5 Diagnostic Interceptor & Friction Signal Detector
- *
- * Wraps a shell command with telemetry capture. On failure:
- *   1. Prints static diagnostic suggestions to stdout.
- *   2. Appends a structured `friction` record to the per-Story
- *      `signals.ndjson` stream via `signals-writer.appendSignal` (when
- *      both `--story` and `--epic` can be resolved).
- *
- * In v5 (Epic #1030), friction is a **local NDJSON signal**, not a GitHub
- * comment. The detector posts no comments; the analyzer reads the NDJSON
- * stream out-of-band. See Tech Spec #1032 §observability.
- *
- * Usage:
- *   node diagnose-friction.js [--story <STORY_ID>] \
- *     [--epic <EPIC_ID>] --cmd <cmd> <args...>
- *
- * `--cmd` consumes the remaining argv as separate words and spawns them with
- * no shell. Quoting the whole command as one string is a usage error, not
- * friction — it is refused loudly and writes no ledger row.
- *
- * Story/Epic resolution order:
- *   1. CLI flags (--story, --epic).
- *   2. Environment vars (STORY_ID, EPIC_ID / SPRINT_ID).
- *
- * If neither story nor epic can be resolved, the script still prints
- * diagnostic suggestions but skips the signal write (a missing signal is
- * preferable to a halted runner — see signals-writer best-effort contract).
- *
- * @see docs/v5-implementation-plan.md Sprint 3E
- * @see .agents/scripts/lib/observability/signals-writer.js
+ * Diagnostic interceptor: runs a command (argv words, no shell) and on
+ * failure prints remediation and appends a local `friction` NDJSON signal —
+ * never a ticket comment. With no resolvable Story the write is skipped: a
+ * missing signal beats a halted runner.
  */
 import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
@@ -41,10 +15,6 @@ import { getLimits, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 function parseArguments(args) {
   let storyId = null;
   let epicId = null;
@@ -63,10 +33,7 @@ function parseArguments(args) {
 }
 
 /**
- * Ordered classification rules. The first rule whose `markers` are found
- * (any-match) wins. Table-driven so adding a new pattern doesn't grow the
- * cyclomatic complexity of `classifyFrictionCategory`.
- *
+ * First rule with any matching marker wins.
  * @type {ReadonlyArray<{markers: string[], category: string, remediation: string}>}
  */
 const FRICTION_RULES = [
@@ -104,51 +71,28 @@ function classifyFrictionCategory(errorOutput) {
 }
 
 /**
- * `spawnSync`'s own `timeout` option kills the child with `SIGTERM`, so a
- * SIGTERM observed here almost always means the interceptor's configured
- * `executionTimeoutMs` bound fired. Any other signal — a `SIGKILL` from the
- * OOM killer, an operator `kill -9` — originated outside this process.
- *
+ * `spawnSync`'s timeout kills with SIGTERM; any other signal came from outside.
  * @type {string}
  */
 const INTERCEPTOR_TIMEOUT_SIGNAL = 'SIGTERM';
 
 /**
- * A `maxBuffer` overflow presents identically to a timeout — `status: null`,
- * `signal: 'SIGTERM'` — because Node kills the child the same way. The only
- * discriminator is `result.error.code`, so a SIGTERM carrying this code is a
- * buffer overflow and must never be reported as a timeout (Story #4915).
- *
+ * A maxBuffer overflow is also a SIGTERM; only this error code tells it
+ * apart from a timeout.
  * @type {string}
  */
 const OVERFLOW_ERROR_CODE = 'ENOBUFS';
 
-/** Shell convention for "the process died by signal N": exit `128 + N`. */
 const SIGNAL_EXIT_BASE = 128;
 
 /**
- * Describe a child that never exited normally — `status === null`, Node's
- * documented representation of "did not exit normally". The raw status must
- * never reach `process.exit`, because `process.exit(null)` exits **0**: the
- * interceptor would report success for a command it just watched get killed
- * (Story #4851).
- *
- * Which signal fired is the diagnostic value: SIGTERM points at one of the
- * interceptor's own bounds, anything else at the host. A SIGTERM splits again
- * on `error.code`: `ENOBUFS` means the output blew past `executionMaxBuffer`,
- * anything else means `executionTimeoutMs` fired. Recording that plus the
- * bound itself is what makes the row actionable to a consumer who cannot edit
- * the materialized framework tree.
- *
- * Deliberately module-local and pure — exporting it for tests would fail the
- * `--production` dead-exports ratchet, and folding it into `main` would spend
- * the file's per-file maintainability-delta headroom. The CLI contract is the
- * seam the unit tests drive.
- *
+ * For a `null` status, which must never reach `process.exit` (null exits 0).
+ * SIGTERM + ENOBUFS = buffer overflow, SIGTERM otherwise = timeout, any other
+ * signal = the host. Kept module-local: exporting it for tests would trip the
+ * `--production` dead-exports gate.
  * @param {{signal: (string|null), error?: {message?: string, code?: string}}}
- *   result A `spawnSync` result whose `status` is `null`.
- * @param {{executionTimeoutMs: number, executionMaxBuffer: number}} bounds The
- *   resolved interceptor bounds — the timeout in ms, the buffer in bytes.
+ *   result
+ * @param {{executionTimeoutMs: number, executionMaxBuffer: number}} bounds
  * @returns {{category: string, remediation: string, details: object,
  *   preview: string, exitCode: number}}
  */
@@ -244,14 +188,10 @@ function buildFrictionSignal({
     ts: new Date().toISOString(),
     epicId: epicId ?? null,
     storyId: storyId ?? null,
-    // 2-tier hierarchy (Epic #3163): no Task tier, so friction signals
-    // carry no Task id. The field is retained for schema compatibility
-    // and always null.
+    // No Task tier; kept for schema compatibility.
     taskId: null,
     category,
-    // `emitter.command` is what `classifySignalSource` step 1 scans, so the
-    // command-scan stays authoritative for `source`: a consumer command killed
-    // by its own host remains consumer-actionable (Story #4851).
+    // `classifySignalSource` scans `emitter.command` first to attribute source.
     emitter: {
       tool: 'diagnose-friction.js',
       command: commandStr,
@@ -260,10 +200,6 @@ function buildFrictionSignal({
   };
 }
 
-// ---------------------------------------------------------------------------
-// Main Execution
-// ---------------------------------------------------------------------------
-
 export async function main(args = process.argv.slice(2)) {
   const { storyId, epicId, cmdArgs } = parseArguments(args);
 
@@ -273,16 +209,9 @@ export async function main(args = process.argv.slice(2)) {
     );
   }
 
-  // Story #4915 — the interceptor spawns `cmdArgs[0]` directly, with no shell.
-  // A single argument containing whitespace therefore names an executable that
-  // cannot exist, and the resulting ENOENT is a usage error in the
-  // interceptor's OWN invocation, not friction in the wrapped command. It must
-  // be reported as one and MUST NOT reach the ledger — otherwise the real
-  // friction is discarded and the roll-up eventually auto-files a framework-gap
-  // ticket about the framework's own instrumentation being misused. The
-  // discriminator is this argv shape, never the ENOENT result: a correctly
-  // split command whose binary is genuinely absent yields the identical
-  // `spawnSync` result and stays real friction.
+  // No shell, so one whitespace-bearing arg is a usage error that must not
+  // reach the ledger. Discriminate on argv shape, not ENOENT: a genuinely
+  // absent binary yields the same spawn result and is real friction.
   if (cmdArgs.length === 1 && /\s/.test(cmdArgs[0])) {
     throw new Error(
       `Usage: --cmd takes the command as separate argv words, not one quoted string. Received a single quoted argument: "${cmdArgs[0]}". Drop the quotes so each word is its own argv entry — \`--cmd ${cmdArgs[0]}\`. No friction signal was recorded.`,
@@ -290,13 +219,9 @@ export async function main(args = process.argv.slice(2)) {
   }
 
   const config = resolveConfig();
-  const limits = getLimits(config);
-  const executionTimeoutMs = limits.executionTimeoutMs;
-  // The interceptor's bound is deliberately *below* the framework-wide
-  // `MAX_BUFFER_BYTES` ceiling: it is a reported policy bound whose value the
-  // emitted friction row carries (`details.executionMaxBuffer`), not an
-  // overflow guard. Story #5009 moved its definition to the shared
-  // child-process surface so it is no longer a hand-copied literal here.
+  const { executionTimeoutMs } = getLimits();
+  // Deliberately below `MAX_BUFFER_BYTES`: a reported policy bound, not an
+  // overflow guard.
   const executionMaxBuffer = INTERCEPTOR_MAX_BUFFER_BYTES;
 
   const commandStr = cmdArgs.join(' ');
@@ -313,8 +238,6 @@ export async function main(args = process.argv.slice(2)) {
   if (result.stderr) process.stderr.write(result.stderr);
 
   if (result.status !== 0) {
-    // A `null` status means the child never exited normally; the cause lives in
-    // `result.signal`, not in the status.
     const abnormal =
       result.status === null
         ? describeAbnormalExit(result, {
@@ -322,9 +245,6 @@ export async function main(args = process.argv.slice(2)) {
             executionMaxBuffer,
           })
         : null;
-    // With both streams empty an abnormal termination names its signal; the
-    // `Unknown exit code` fallback is therefore reachable only with a real
-    // numeric status, never as `Unknown exit code null`.
     const noOutputFallback = abnormal
       ? abnormal.preview
       : `Unknown exit code ${result.status}`;
@@ -340,9 +260,7 @@ export async function main(args = process.argv.slice(2)) {
       'Command failed. Appending friction signal to NDJSON stream...',
     );
 
-    // An abnormal termination classifies itself: the marker scan reads output
-    // the kill may have truncated (or never produced), so it cannot name the
-    // signal.
+    // A killed command's output may be truncated, so it classifies itself.
     const classified = classifyFrictionCategory(errorOutput);
     const category = abnormal?.category ?? classified.category;
     const remediation = abnormal?.remediation ?? classified.remediation;
@@ -359,11 +277,7 @@ export async function main(args = process.argv.slice(2)) {
       terminationDetails: abnormal?.details ?? null,
     });
 
-    // Story #2874 — accept story-only context (no parent Epic). When
-    // only the story is resolved, write to the standalone signals
-    // stream at `<tempRoot>/standalone/stories/story-<sid>/signals.ndjson`
-    // by passing `epicId: null` through to the writer. The only case
-    // we still skip is fully-no-context (story unresolved).
+    // A null epicId routes to the standalone Story stream.
     if (resolvedStoryId != null) {
       try {
         const ok = await appendSignal({
@@ -394,18 +308,12 @@ export async function main(args = process.argv.slice(2)) {
     Logger.error(remediation);
     Logger.error('----------------------------------------\n');
 
-    // Never `process.exit(result.status)` on a null status — that exits 0 and
-    // reports success for a killed command.
     process.exit(abnormal?.exitCode ?? result.status);
   } else {
     process.exit(0);
   }
 }
 
-// ---------------------------------------------------------------------------
-// Call main if run directly
-// ---------------------------------------------------------------------------
-
 import { runAsCli } from './lib/cli-utils.js';
 
 runAsCli(import.meta.url, main, {

package/.agents/scripts/drain-pending-cleanup.js

@@ -57,7 +57,7 @@ const escalateFrom = (value) => value !== false && value !== 'false';
  * without a real worktree ledger or a real process kill.
  *
  * Every seam on the optional final `deps` parameter defaults to the real
- * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * implementation (`docs/contributing/test-seams.md` rules 1-2, 4), so `main` and
  * every production caller are unchanged.
  *
  * @param {string[]} [argv]

package/.agents/scripts/evidence-gate.js

@@ -1,34 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * evidence-gate.js — evidence-aware wrapper around a single shell gate.
- *
- * Tech Spec #819 §"Evidence record (Story 7)" — `/mandrel-deliver` Phase 3
- * (close-validation) runs `npm run lint` and `npm test` against the Epic
- * branch before opening the PR.
- * If the same gate has already passed against the current `git rev-parse
- * HEAD` (recorded earlier in the local hot path), this wrapper logs a skip
- * and exits 0 instead of re-spawning the runner. On run, a successful
- * gate is recorded so the next invocation can skip in turn.
- *
- * Usage:
- *   node .agents/scripts/evidence-gate.js \
- *     --standalone --scope-id <storyId> --gate <name> \
- *     [--worktree <path>] [--no-evidence] -- <cmd> [args...]
- *
- * Examples:
- *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate lint \
- *     --worktree .worktrees/story-4250 -- npm run lint
- *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate test \
- *     --worktree .worktrees/story-4250 -- npm test
- *
- * `--standalone` (Story #4250) is required: the evidence file is anchored on
- * the Story id at
- * `<tempRoot>/standalone/stories/story-<sid>/validation-evidence.json` — the
- * same keyspace the standalone close consults, so the acceptance-self-eval
- * critic's verify[] runs (lint / typecheck) are shared with the close.
- * v2.0.0 removed the Epic tier along with the `--epic-id` Epic-keyed
- * keyspace.
+ * Runs one gate, skipping it when evidence shows the same gate already
+ * passed for the current HEAD and tree, and recording a pass for the next
+ * caller. `--standalone` is required: it keys evidence by Story id, the same
+ * keyspace close consults, so worker-side verify[] runs credit the close.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -44,12 +20,6 @@ import {
   treeFingerprint,
 } from './lib/validation-evidence.js';
 
-/**
- * Split argv at the first `--` and return both halves. The wrapper consumes
- * everything before `--`; the runner receives everything after.
- *
- * Exported for testing.
- */
 export function splitOnDashDash(argv) {
   const idx = argv.indexOf('--');
   if (idx === -1) return { wrapperArgs: argv, runnerArgs: [] };
@@ -59,11 +29,6 @@ export function splitOnDashDash(argv) {
   };
 }
 
-/**
- * Parse the wrapper-side argv (before `--`).
- *
- * Exported for testing.
- */
 export function parseWrapperArgs(argv) {
   const { values } = parseArgs({
     args: argv,
@@ -96,16 +61,9 @@ function resolveHeadShaDefault(cwd, gitSpawnFn) {
 }
 
 /**
- * The pair of keys an evidence record is written and read under: the commit
- * this gate ran at, and the content identity of the tree it ran against
- * (Story #5278).
- *
- * Both are read from the **spawn** cwd — the Story worktree when one is
- * supplied — so the keys describe the tree the gate actually saw. The tree
- * fingerprint is what keeps this gate credited across close's own base-sync
- * fast-forward, which moves HEAD between the deposit and the gates that would
- * spend it; see `validation-evidence.js#treeFingerprint`.
- *
+ * Read from the spawn cwd so the keys describe the tree the gate saw. The
+ * tree fingerprint keeps credit across close's base-sync fast-forward, which
+ * moves HEAD between deposit and spend.
  * @param {{ spawnCwd: string, gitSpawnFn: Function, useEvidence: boolean }} args
  * @returns {{ headSha: string|null, inputFingerprint: string|null }}
  */
@@ -118,34 +76,21 @@ function resolveEvidenceKeys({ spawnCwd, gitSpawnFn, useEvidence }) {
 }
 
 /**
- * Runner-shaped entry-point: takes the parsed wrapper args + runner args and
- * executes the gate. Pure-ish (modulo IO) — all side-effects are routed via
- * the injection hooks so tests can stub `gitSpawn`, `spawnSync`, and the
- * evidence store without touching disk or spawning processes.
- *
- * Exported for tests + the CLI `main()`.
- *
  * @param {object} params
- * @param {number}   params.scopeId      — Story ID (positive integer).
- * @param {boolean}  [params.standalone] — Required. Routes to the
- *   storyId-anchored standalone keyspace (Story #4250).
- * @param {string}   params.gate         — Logical gate name (`lint`, `typecheck`, …).
- * @param {boolean}  params.useEvidence  — When false, force the runner.
- * @param {string}   params.cwd          — Evidence cwd (locates the temp
- *   tree). The runner is spawned in `worktreePath` when set, else `cwd`.
- * @param {string|null} [params.worktreePath] — Spawn cwd override (Story #1120).
- *   When set, the runner runs in the Story worktree and the HEAD-SHA used as
- *   the evidence cache key is read from the worktree, not from `cwd`.
- * @param {string[]} params.runnerArgs   — `[cmd, ...args]` from after `--`.
- * @param {object}   [deps]              — Optional injection hooks (tests).
- * @param {Function} [deps.gitSpawnFn]   — Stub for `gitSpawn`.
- * @param {Function} [deps.spawnFn]      — Stub for `spawnSync`.
- * @param {Function} [deps.shouldSkipFn] — Stub for `shouldSkip`.
- * @param {Function} [deps.recordPassFn] — Stub for `recordPass`.
- * @param {object}   [deps.logger]       — Logger-shaped object (info/error/warn/fatal).
- * @returns {{ status: number, skipped: boolean }} Outcome summary. `status`
- *   is the runner's exit code (0 = pass), `skipped` is true when evidence
- *   short-circuited the runner.
+ * @param {number}   params.scopeId
+ * @param {boolean}  [params.standalone]
+ * @param {string}   params.gate
+ * @param {boolean}  params.useEvidence
+ * @param {string}   params.cwd          — evidence cwd (locates the temp tree)
+ * @param {string|null} [params.worktreePath] — spawn cwd and HEAD source
+ * @param {string[]} params.runnerArgs
+ * @param {object}   [deps]
+ * @param {Function} [deps.gitSpawnFn]
+ * @param {Function} [deps.spawnFn]
+ * @param {Function} [deps.shouldSkipFn]
+ * @param {Function} [deps.recordPassFn]
+ * @param {object}   [deps.logger]
+ * @returns {{ status: number, skipped: boolean }}
  */
 export async function runEvidenceGate(params, deps = {}) {
   const {
@@ -165,9 +110,6 @@ export async function runEvidenceGate(params, deps = {}) {
     runnerArgs,
   } = params ?? {};
 
-  // `--standalone` (Story #4250) routes the evidence file to the
-  // storyId-anchored keyspace so the acceptance-self-eval critic can record
-  // verify[] evidence into the same keyspace the standalone close consults.
   if (
     !scopeId ||
     !standalone ||
@@ -180,14 +122,10 @@ export async function runEvidenceGate(params, deps = {}) {
     );
     return { status: 1, skipped: false };
   }
-  // Evidence-store opts shared by shouldSkip + recordPass below.
   const evidenceStoreOpts = { cwd, standalone };
 
-  // Spawn cwd is the worktree when supplied — every gate command sees the
-  // Story branch's tree, not the main checkout. Evidence cwd stays anchored
-  // to the main checkout so the temp tree resolves under the main
-  // `.git/`. The HEAD-SHA used as the cache key is read from the spawn cwd
-  // (the worktree), so cache entries key against the Story branch's HEAD.
+  // The gate runs in the worktree; evidence stays anchored to the main
+  // checkout so the temp tree resolves under the main `.git/`.
   const spawnCwd = worktreePath ?? cwd;
   const [cmd, ...cmdArgs] = runnerArgs;
   const configHash = hashCommandConfig({ cmd, args: cmdArgs, cwd: spawnCwd });

package/.agents/scripts/file-ci-gap.js

@@ -1,18 +1,9 @@
 #!/usr/bin/env node
 /**
- * file-ci-gap.js — the CI-remediation Option-2 filing command.
- *
- * `rules/ci-remediation.md` sends three verdicts here — `pre-existing`,
- * `capacity`, `unreproducible-tier` — each meaning "this red check is real,
- * and fixing it is not this delivery's job". The rule used to say "file a
- * `meta::framework-gap` issue" and stop, leaving the agent to hand-run
- * `gh issue create` wherever it was standing. This is the mechanism behind
- * that sentence: evidence from the CI digest, ownership routing, fingerprint
- * dedup, the `friction` comment, and the `agent::blocked` flip in one call.
- *
- * It files an **intake** issue, never a Story: `/mandrel-plan <id>` graduates
- * it on the next planning pass. Delivery never blocks on planning — see
- * `lib/orchestration/ci-gap-intake.js` for why that split is load-bearing.
+ * CI-remediation Option-2 filing: for a red check that is real but not this
+ * delivery's to fix, files (or updates, by fingerprint) an intake issue in
+ * the owning repo, comments `friction` on the Story, and optionally blocks it.
+ * It files intake, never a Story, so delivery never blocks on planning.
  */
 
 import { parseArgs } from 'node:util';
@@ -35,7 +26,11 @@ import {
   INTAKE_VERDICTS,
   REFUSED_VERDICT,
 } from './lib/orchestration/ci-gap-intake.js';
-import { readCiDigest } from './lib/orchestration/ci-rerun-guard.js';
+import {
+  RERUN_ALLOWANCE_VERDICTS,
+  readCiDigest,
+  recordRerunAllowance,
+} from './lib/orchestration/ci-rerun-guard.js';
 import {
   STATE_LABELS,
   transitionTicketState,
@@ -55,7 +50,7 @@ const USAGE = {
     ],
     [
       '--verdict <verdict>',
-      `One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source.`,
+      `One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source. ${RERUN_ALLOWANCE_VERDICTS.join(' / ')} also record the one-rerun allowance on the CI digest.`,
     ],
     [
       '--owner <bucket>',
@@ -80,15 +75,9 @@ const USAGE = {
 };
 
 /**
- * Wire the live GitHub ports the intake filer writes through.
- *
- * `gh` is the transport rather than the provider facade because a filing can
- * target a repository other than the configured one, and `gh issue create
- * --repo` is the surface that already does that (the graduators file
- * cross-repo the same way).
- *
+ * `gh` rather than the provider facade: a filing may target another repo.
  * @param {object} opts
- * @returns {object} ports for `fileCiGapIntake`
+ * @returns {object}
  */
 function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
   const labelCache = new Map();
@@ -100,9 +89,7 @@ function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
         repo: searchRepo.repo,
       }),
     createIssue: async ({ owner, repo, title, body, labels }) => {
-      // `gh issue create --label <absent>` fails outright, so a brand-new
-      // routing label (meta::platform-gap, friction::unreproducible-tier)
-      // has to exist before the create — not after it errors.
+      // `gh issue create` fails outright on an absent label; ensure first.
       const ensured = await ensureIssueLabels({
         owner,
         repo,
@@ -132,13 +119,15 @@ function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
 }
 
 /**
- * Render the `friction` comment the Story carries so the blocker is legible
- * on the ticket itself, not only in the intake issue.
- *
  * @param {object} opts
  * @returns {string}
  */
-export function renderFrictionComment({ verdict, result, digest }) {
+export function renderFrictionComment({
+  verdict,
+  result,
+  digest,
+  rerunAllowance = null,
+}) {
   const target = result.issue?.url ?? result.issue?.number ?? '(not filed)';
   const lines = [
     `### CI gap filed — verdict \`${verdict}\``,
@@ -158,23 +147,28 @@ export function renderFrictionComment({ verdict, result, digest }) {
       `- **Routing:** deferred from \`${result.routing.deferredFrom}\` (${result.routing.deferralReason}) — filed locally instead.`,
     );
   }
-  lines.push(
-    '',
-    'This verdict does **not** license a re-run of the failed job. Graduate the',
-    'intake issue with `/mandrel-plan <issue number>` to turn it into a Story.',
-  );
+  lines.push('', renderRerunLine(rerunAllowance), GRADUATE_LINE);
   return lines.join('\n');
 }
 
+const GRADUATE_LINE =
+  'Graduate the intake issue with `/mandrel-plan <issue number>` to turn it into a Story.';
+
+/**
+ * @param {{ headSha: string } | null} rerunAllowance
+ * @returns {string}
+ */
+function renderRerunLine(rerunAllowance) {
+  return rerunAllowance
+    ? 'This verdict is environmental and proven, so **one** rerun of the failed ' +
+        `job is now admitted on head \`${rerunAllowance.headSha}\` — and one only. ` +
+        'A second red after it is real and routes to Option 1.'
+    : 'This verdict does **not** license a re-run of the failed job.';
+}
+
 /**
- * File the CI-gap intake issue for one Story, post the `friction` comment,
- * and optionally flip the Story to `agent::blocked`.
- *
- * Every port is injectable so the unit tests exercise the whole command with
- * no network and no live tracker.
- *
  * @param {object} opts
- * @returns {Promise<object>} the intake result, plus what the command did.
+ * @returns {Promise<object>}
  */
 export async function runFileCiGap({
   storyId,
@@ -198,7 +192,10 @@ export async function runFileCiGap({
     throw new Error('--story <id> is required (a positive issue number).');
   }
   const resolved = config ?? resolveConfig();
-  const ciDigest = digest ?? readCiDigest({ storyId: sid, tempRoot, cwd });
+  // Must resolve exactly as `pr-watch-with-update.js` does when writing it.
+  const digestRoot = tempRoot ?? resolved?.project?.paths?.tempRoot ?? 'temp';
+  const ciDigest =
+    digest ?? readCiDigest({ storyId: sid, tempRoot: digestRoot, cwd });
   if (!ciDigest) {
     throw new Error(
       `no CI digest for Story #${sid}. The digest is written by \`pr-watch-with-update.js --story ${sid}\` on the first red; without it there is no run link or failure signature to file.`,
@@ -237,9 +234,24 @@ export async function runFileCiGap({
     now,
   });
 
+  // A proven-environmental verdict earns one same-SHA rerun; never on dry run.
+  const rerunAllowance = dryRun
+    ? null
+    : recordRerunAllowance({
+        storyId: sid,
+        verdict,
+        tempRoot: digestRoot,
+        cwd,
+      });
+
   const actions = { commented: false, blocked: false };
   if (!dryRun && ticketing) {
-    const body = renderFrictionComment({ verdict, result, digest: ciDigest });
+    const body = renderFrictionComment({
+      verdict,
+      result,
+      digest: ciDigest,
+      rerunAllowance,
+    });
     try {
       await upsertStructuredComment(ticketing, sid, 'friction', body);
       actions.commented = true;
@@ -258,12 +270,10 @@ export async function runFileCiGap({
     }
   }
 
-  return { storyId: sid, verdict, ...result, actions };
+  return { storyId: sid, verdict, ...result, actions, rerunAllowance };
 }
 
 /**
- * CLI entrypoint.
- *
  * @returns {Promise<void>}
  */
 async function main() {
@@ -290,8 +300,6 @@ async function main() {
     block: values.block,
   });
 
-  // Single-line JSON per the script-output contract — an orchestrator parses
-  // this, and a pretty dump is noise in a delivery transcript.
   process.stdout.write(`${JSON.stringify(result)}\n`);
   for (const err of result.errors) {
     Logger.error(`[file-ci-gap] ${err}`);