mandrel 2.5.0 → 2.7.0

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -97,7 +97,9 @@ function metaSourceLabel(source) {
  * ({@link buildContentMarker}) at the Story #4415 cutover, but still
  * probed for so follow-ups filed before the cutover are recognized and
  * not re-filed. An HTML comment so it survives markdown rendering without
- * leaking into the visible body, but stays indexable via `gh search`.
+ * leaking into the visible body; the idempotency probe strips the comment
+ * delimiters before querying `gh search` (the raw `<!-- … -->` form never
+ * matches the index — Story #4657).
  *
  * @param {number} epicId
  * @param {number} index — zero-based finding ordinal within the Epic.
@@ -112,7 +114,10 @@ export function buildIdempotencyMarker(epicId, index) {
  * follow-up bodies. Derived from the finding's `lens|path|summary` triple
  * so the marker is stable across sibling insert/remove/reorder churn in
  * the source `audit-results` comment (Story #4415). An HTML comment so it
- * survives markdown rendering but stays indexable via `gh search`.
+ * survives markdown rendering without leaking into the visible body; the
+ * idempotency probe strips the comment delimiters before querying
+ * `gh search` (the raw `<!-- … -->` form never matches the index —
+ * Story #4657).
  *
  * @param {number} epicId
  * @param {{ lens?: string, path?: string, summary?: string }} finding

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -273,12 +273,34 @@ export async function probePathStatus({
   return { exists: res.code === 0, probeError: false };
 }
 
+/**
+ * Normalize an idempotency marker into a `gh search issues` query. Markers
+ * are HTML comments (`<!-- … -->`) so they survive markdown rendering
+ * without leaking into the visible body, but the `<` / `>` delimiters are
+ * NOT index-safe as a query: GitHub full-text search DOES index the text
+ * inside an HTML comment, yet a query that carries the `<!--` / `-->`
+ * delimiters never matches that indexed text (measured against this repo,
+ * Story #4657). Stripping the delimiters and trimming yields the bare marker
+ * text — `retro-proposal-followup: epic-1-<fp>` — which the index matches.
+ * The caller-facing marker is left untouched; normalization is the probe's
+ * own concern.
+ *
+ * @param {string} marker
+ * @returns {string}
+ */
+function normalizeMarkerQuery(marker) {
+  if (typeof marker !== 'string') return '';
+  return marker.replaceAll('<!--', '').replaceAll('-->', '').trim();
+}
+
 /**
  * Probe whether a follow-up issue carrying the given idempotency marker
  * already exists in the routed repo. Uses `gh search issues` so we hit
- * the body field directly. Returns `true` when at least one match is
- * present; degrades to `false` on any spawn/parse error (better to risk
- * a duplicate than swallow the finding entirely).
+ * the body field directly, querying the delimiter-stripped marker text
+ * (see {@link normalizeMarkerQuery}) — the raw `<!-- … -->` form never
+ * matches the index. Returns `true` when at least one match is present;
+ * degrades to `false` on any spawn/parse error (better to risk a duplicate
+ * than swallow the finding entirely).
  */
 export async function probeMarkerExists({
   marker,
@@ -292,7 +314,7 @@ export async function probeMarkerExists({
   const args = [
     'search',
     'issues',
-    marker,
+    normalizeMarkerQuery(marker),
     '--repo',
     `${owner}/${repo}`,
     '--json',
@@ -312,6 +334,71 @@ export async function probeMarkerExists({
   }
 }
 
+/**
+ * Strongly-consistent confirmation that a follow-up carrying `marker`
+ * already exists, run ONLY on the would-file path as the last gate before
+ * creating. `gh search issues` reads an eventually-consistent index whose
+ * catch-up latency (measured under 20s against this repo, Story #4657) is
+ * exactly wide enough to miss a byte-identical duplicate filed seconds
+ * earlier in the same rollup. A label-scoped `gh issue list … --state all`
+ * is strongly consistent, so it closes that window. The list is narrowed by
+ * the follow-up's own labels (supplied by the same `spec.buildFollowUp` that
+ * writes the marker, so the two agree by construction) to keep the read
+ * bounded, and the marker is matched as a substring of each returned body.
+ *
+ * Degrades to `false` (i.e. proceed to file) on any spawn/parse error — the
+ * deliberate degrade-toward-filing posture: an undecidable probe risks a
+ * duplicate rather than swallowing the finding.
+ *
+ * @param {object} opts
+ * @param {string} opts.marker — the content-hash marker embedded in the body.
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string[]} [opts.labels] — the follow-up's labels; scopes the list.
+ * @param {string} [opts.ghPath]
+ * @param {Function} [opts.spawnImpl]
+ * @param {string} [opts.cwd]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<boolean>}
+ */
+async function confirmMarkerFiled({
+  marker,
+  owner,
+  repo,
+  labels,
+  ghPath,
+  spawnImpl,
+  cwd,
+  timeoutMs,
+}) {
+  const args = [
+    'issue',
+    'list',
+    '--repo',
+    `${owner}/${repo}`,
+    '--state',
+    'all',
+    '--json',
+    'number,body',
+  ];
+  for (const label of Array.isArray(labels) ? labels : []) {
+    args.push('--label', label);
+  }
+  const res = await runChild({ cmd: ghPath, args, spawnImpl, cwd, timeoutMs });
+  if (res.spawnError || (typeof res.code === 'number' && res.code !== 0)) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(res.stdout || '[]');
+    if (!Array.isArray(parsed)) return false;
+    return parsed.some(
+      (issue) => typeof issue?.body === 'string' && issue.body.includes(marker),
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * File a new follow-up issue via `gh issue create` and resolve to
  * `{ url, error }`. On success `url` is the trimmed stdout and `error` is
@@ -421,21 +508,22 @@ async function loadGraduateFindings({ epicId, provider, spec }) {
 /**
  * Probe whether a finding was already filed, checking both the current
  * content-hash marker AND the legacy `(epicId, parse-index)` marker so
- * findings filed before the fingerprint cutover are not re-filed. Returns
- * the content-hash marker (embedded in a freshly filed body) alongside the
- * `alreadyFiled` decision.
+ * findings filed before the fingerprint cutover are not re-filed. The
+ * content-hash marker is passed in precomputed so a caller can consult an
+ * in-process memo before spending a spawn. Returns the `alreadyFiled`
+ * decision.
  */
 async function resolveAlreadyFiled({
   finding,
   epicId,
   routedRepo,
+  contentMarker,
   ghPath,
   spawnImpl,
   cwd,
   timeoutMs,
   spec,
 }) {
-  const contentMarker = spec.buildContentMarker(epicId, finding);
   const probe = (marker) =>
     probeMarkerExists({
       marker,
@@ -448,17 +536,17 @@ async function resolveAlreadyFiled({
     });
 
   if (await probe(contentMarker)) {
-    return { alreadyFiled: true, contentMarker };
+    return { alreadyFiled: true };
   }
   // Legacy recognition — a pre-cutover follow-up carries the ordinal
   // marker, not the content hash. Skip re-filing when it is present.
   if (typeof spec.buildLegacyMarker === 'function') {
     const legacyMarker = spec.buildLegacyMarker(epicId, finding.index);
     if (legacyMarker && (await probe(legacyMarker))) {
-      return { alreadyFiled: true, contentMarker };
+      return { alreadyFiled: true };
     }
   }
-  return { alreadyFiled: false, contentMarker };
+  return { alreadyFiled: false };
 }
 
 /**
@@ -483,6 +571,7 @@ async function processGraduateFinding({
   timeoutMs,
   maxFilingsPerRun,
   crossRepoDeferred,
+  filedMarkers,
   logger,
   spec,
 }) {
@@ -531,10 +620,20 @@ async function processGraduateFinding({
     return skip('cross-repo-deferred');
   }
 
-  const { alreadyFiled, contentMarker } = await resolveAlreadyFiled({
+  const contentMarker = spec.buildContentMarker(epicId, finding);
+
+  // In-process memo (Story #4657): a marker already filed earlier in THIS
+  // invocation — e.g. the framework bucket of a retro rollup that also has
+  // the same category in the consumer bucket — short-circuits a repeat in a
+  // later bucket without spending a single spawn, and closes the same-rollup
+  // race the eventually-consistent search index cannot.
+  if (filedMarkers?.has(contentMarker)) return skip('already-filed');
+
+  const { alreadyFiled } = await resolveAlreadyFiled({
     finding,
     epicId,
     routedRepo,
+    contentMarker,
     ghPath,
     spawnImpl,
     cwd,
@@ -548,12 +647,37 @@ async function processGraduateFinding({
   // a re-run picks it up next time.
   if (envelope.filed.length >= maxFilingsPerRun) return skip('cap-reached');
 
+  // Resolve the follow-up (title/body/labels) BEFORE the dedup decision so
+  // the strong read can scope its `gh issue list` by the very labels this
+  // filing would carry (they agree with the marker by construction).
   const { title, body, labels } = spec.buildFollowUp({
     finding,
     source,
     epicId,
     idMarker: contentMarker,
   });
+
+  // Strong read (would-file path only, Story #4657): the search probe reads
+  // an eventually-consistent index that can miss a byte-identical duplicate
+  // filed seconds earlier. Confirm against a strongly-consistent,
+  // label-scoped `gh issue list` before creating. Skipped entirely on the
+  // already-filed path above, so it never fires when the search probe
+  // already matched.
+  const confirmed = await confirmMarkerFiled({
+    marker: contentMarker,
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    labels,
+    ghPath,
+    spawnImpl,
+    cwd,
+    timeoutMs,
+  });
+  if (confirmed) {
+    filedMarkers?.add(contentMarker);
+    return skip('already-filed');
+  }
+
   const created = await createFollowUpIssue({
     owner: routedRepo.owner,
     repo: routedRepo.repo,
@@ -571,6 +695,7 @@ async function processGraduateFinding({
     );
     return;
   }
+  filedMarkers?.add(contentMarker);
   envelope.filed.push(
     decorate(
       {
@@ -681,6 +806,11 @@ async function persistCrossRepoDeferred({
  * @param {Array<object>} [opts.findings] — pre-parsed findings; when
  *   provided, the structured-comment read/parse is bypassed (the retro
  *   auto-filer seam).
+ * @param {Set<string>} [opts.filedMarkers] — in-process memo of content
+ *   markers filed so far. Pass a shared Set across multiple `graduate()`
+ *   calls in one logical invocation (e.g. the retro graduator's two source
+ *   buckets) so a marker filed in one call short-circuits a repeat in the
+ *   next without a spawn. Defaults to a fresh per-call Set.
  * @param {{info?: Function, warn?: Function, debug?: Function}} [opts.logger]
  * @param {object} opts.spec — the per-graduator behaviour bundle
  * @returns {Promise<{ filed: object[], skipped: object[], errors: string[] }>}
@@ -699,6 +829,7 @@ export async function graduate({
   timeoutMs = DEFAULT_RUN_CHILD_TIMEOUT_MS,
   maxFilingsPerRun = DEFAULT_MAX_FILINGS_PER_RUN,
   findings: preParsedFindings,
+  filedMarkers = new Set(),
   logger,
   spec,
 }) {
@@ -745,6 +876,7 @@ export async function graduate({
       timeoutMs,
       maxFilingsPerRun,
       crossRepoDeferred,
+      filedMarkers,
       logger,
       spec,
     });

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -54,7 +54,9 @@ export const isAutoFileEnabled = makeIsAutoFileEnabled('retroProposals');
  * are path-less and the rendered title embeds a mutable recurrence count)
  * so the marker is stable across sibling insert/remove/reorder churn AND
  * across re-runs that change the count. An HTML comment so it survives
- * markdown rendering but stays indexable via `gh search`.
+ * markdown rendering without leaking into the visible body; the idempotency
+ * probe strips the comment delimiters before querying `gh search` (the raw
+ * `<!-- … -->` form never matches the index — Story #4657).
  *
  * @param {number} epicId
  * @param {{ category?: string, title?: string }} finding
@@ -223,6 +225,13 @@ export async function graduateRetroProposals({
     { source: 'consumer', items: consumer },
   ];
 
+  // One memo of content markers filed so far, SHARED across both buckets: the
+  // two scopes mint an identical marker for the same category by construction
+  // (Story #4657), so without it the framework and consumer buckets could each
+  // file the same category. The shared set makes the second bucket short-
+  // circuit the repeat with no spawn.
+  const filedMarkers = new Set();
+
   let remaining = maxFilingsPerRun;
   for (const { source, items } of buckets) {
     if (items.length === 0) continue;
@@ -242,6 +251,7 @@ export async function graduateRetroProposals({
       timeoutMs,
       maxFilingsPerRun: Math.max(0, remaining),
       findings,
+      filedMarkers,
       logger,
       spec: makeSpec(source),
     });

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -45,7 +45,7 @@
 import crypto from 'node:crypto';
 
 import { Logger } from '../Logger.js';
-import { appendSignal } from './signals-writer.js';
+import { appendSignal, forEachLine } from './signals-writer.js';
 
 /**
  * The friction categories this module emits.
@@ -202,19 +202,187 @@ export async function emitBlockRecoveredFriction({
 }
 
 /**
- * Pure predicate: is this signal a recovery-marked `story-blocked` record?
+ * Emit the recovery counterpart of an earlier friction record in `category`
+ * when a Story ultimately lands, netting a transient incident out of the
+ * retro (generalized from the `close-failed`-only emitter of Story #4649 by
+ * Story #4654).
+ *
+ * An incident that fires once — a transient block, a CI/lease/GitHub fault at
+ * close, a merge wait that outran one window — but is provably resolved by the
+ * time the Story lands still left an un-netted record on the stream, which the
+ * composer counts exactly like an incident that never recovered. This appends
+ * the companion record carrying the `recovered: true` discriminator in the
+ * **same** `category` (a distinct bucket would itself aggregate into a routable
+ * proposal, re-introducing the noise), so `netOutRecoveredIncidents` /
+ * `deriveUnresolvedBlockedEvents` in `retro-proposals.js` can cancel the whole
+ * `(category, storyId)` incident out.
+ *
+ * **Why this is not emitted from `frictionForTerminal`.** A `landed` terminal
+ * envelope is emitted at the very END of close — *after* the post-land tail
+ * has already gathered the signal stream and filed its follow-ups. A marker
+ * written there would arrive too late to net anything out of the run that
+ * produced it. So the emit hangs off `runPostLandTail`, which is the single
+ * shared land point (reached from both the in-close land and the standalone
+ * `single-story-confirm-merge.js` resume) and runs BEFORE follow-up capture.
+ * The tail runs *because* the PR merged, so every incident on the stream is
+ * provably resolved at that point.
+ *
+ * **Conditional on an actual incident.** The marker is appended only when the
+ * Story's stream already carries an un-recovered record in `category`. Emitting
+ * unconditionally on every land would write a category-mislabelled row for
+ * Stories that never had the incident — and, because the netting is per
+ * `(category, storyId)` over the cumulative stream, that spurious marker would
+ * suppress the Story's whole bucket for `category`, making it un-routable at
+ * story scope for a Story that never hit the incident at all.
+ *
+ * What this guard does NOT do is bound the netting once a *legitimate* marker
+ * exists. The netting inherits the Story #4622 coarsening — per
+ * `(category, storyId)` across the whole stream, not 1:1 pairing — so a
+ * later, genuinely un-landed record in `category` for a Story that already
+ * recovered once is still netted away, and does not even reach `discarded`.
+ * Reaching that needs a re-close after a land (a confirm-merge resume, or a
+ * close after a revert). Deliberate, inherited, and called out here rather
+ * than papered over: an aggregate is a routing heuristic, not an incident
+ * ledger.
+ *
+ * Best-effort; never throws. A read failure yields no marker (the incident
+ * stays counted) rather than a speculative write.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {string} args.category One of {@link RUNTIME_FRICTION_CATEGORIES}.
+ * @param {string} [args.tool]   Emitting surface (default `runPostLandTail`).
+ * @param {object} [args.config]
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitRecoveredFrictionMarker({
+  storyId,
+  category,
+  tool,
+  config,
+} = {}) {
+  const sid = positiveIntOrNull(storyId);
+  if (sid === null) return false;
+  if (typeof category !== 'string' || category.trim() === '') {
+    Logger.warn(
+      '[runtime-friction] refusing to emit a category-less recovery marker',
+    );
+    return false;
+  }
+  const cat = category.trim();
+
+  let incident = false;
+  let recovered = false;
+  try {
+    await forEachLine(
+      null,
+      sid,
+      (parsed) => {
+        if (!parsed || typeof parsed !== 'object') return;
+        if (parsed.category !== cat) return;
+        if (isRecoveredSignal(parsed)) recovered = true;
+        else incident = true;
+      },
+      config,
+    );
+  } catch (err) {
+    Logger.warn(
+      `[runtime-friction] ${cat} recovery probe failed for Story #${sid}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return false;
+  }
+  // Nothing to cancel, or already cancelled — a second marker would be noise.
+  if (!incident || recovered) return false;
+
+  return emitRuntimeFriction({
+    storyId: sid,
+    category: cat,
+    tool: tool || 'runPostLandTail',
+    details: { recovered: true },
+    config,
+  });
+}
+
+/**
+ * Emit the recovery counterpart of a `close-failed` record when a Story's
+ * close ultimately lands (Story #4649). Thin wrapper over
+ * {@link emitRecoveredFrictionMarker} bound to the `close-failed` category —
+ * retained as its own export so the post-land seam that injects it stays
+ * stable.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {object} [args.config]
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
+  return emitRecoveredFrictionMarker({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED,
+    config,
+  });
+}
+
+/**
+ * Normalize one raw signals-stream row into the shape the retro composer
+ * consumes, or `null` when the row carries no usable category.
+ *
+ * Single-homed because BOTH production gathers need it identically —
+ * `gatherStoryFrictionSignals` (story scope) and `executeFollowUpRollup`
+ * (run scope) — and the bug this exists to prevent is precisely the two of
+ * them drifting: they each independently flattened rows to
+ * `{ category, source }`, dropping the `storyId` / `details` the composer's
+ * recovery-netting keys on, which left that netting unreachable on real data
+ * while its unit tests stayed green (Story #4649).
+ *
+ * The row's own `storyId` wins over `fallbackStoryId` so a stream carrying
+ * foreign rows attributes each one correctly; the fallback covers records
+ * written before the field existed.
+ *
+ * @param {unknown} parsed          One parsed NDJSON row.
+ * @param {number}  fallbackStoryId Stream owner, used when the row has none.
+ * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, details: object }|null}
+ */
+export function normalizeGatheredSignal(parsed, fallbackStoryId) {
+  if (!parsed || typeof parsed !== 'object') return null;
+  const category =
+    typeof parsed.category === 'string' ? parsed.category.trim() : '';
+  if (!category) return null;
+  const recordStoryId = Number(parsed.storyId);
+  return {
+    category,
+    source: parsed.source === 'framework' ? 'framework' : 'consumer',
+    storyId: Number.isInteger(recordStoryId) ? recordStoryId : fallbackStoryId,
+    details:
+      parsed.details && typeof parsed.details === 'object'
+        ? parsed.details
+        : {},
+  };
+}
+
+/**
+ * Pure predicate: is this signal a recovery marker for its own category?
  * Shared with the retro composer so the "recovered" discriminator is read
- * from one place. A record is a recovery marker when its category is
- * `story-blocked` and `details.recovered === true`.
+ * from one place.
+ *
+ * **Category-agnostic by design (Story #4649).** The predicate used to hard-
+ * code `story-blocked`, which meant every new category needing recovery
+ * semantics had to re-implement the netting. A record is a recovery marker
+ * when it carries a usable `category` and `details.recovered === true`; the
+ * composer nets per `(category, storyId)`, so a marker can only ever cancel
+ * records in its OWN bucket.
  *
  * @param {object} signal
  * @returns {boolean}
  */
-export function isRecoveredBlockSignal(signal) {
+export function isRecoveredSignal(signal) {
   return (
     signal !== null &&
     typeof signal === 'object' &&
-    signal.category === RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED &&
+    typeof signal.category === 'string' &&
+    signal.category.trim() !== '' &&
     signal.details !== null &&
     typeof signal.details === 'object' &&
     signal.details.recovered === true
@@ -237,12 +405,21 @@ export function isRecoveredBlockSignal(signal) {
  *     would count the same block twice.
  *   - `landed`   → null. Nothing happened worth a retro.
  *   - `failed`   → friction. A close that ended non-zero.
- *   - `pending`  → friction **only when a `waitBudget` was exhausted**. That
- *     is the parked worker from the report: a bounded wait expired with the
- *     PR in flight and a human must resume it. A `pending` with **no**
- *     `waitBudget` is the `--no-wait-merge` / operator-merge path, where the
- *     human deliberately owns the land and nothing is broken — flagging it
- *     would train operators to ignore the channel.
+ *   - `pending`  → friction **only when the cumulative wait budget is provably
+ *     exhausted** (`waitBudget.cumulativeSeconds >= waitBudget.maxBudgetSeconds`).
+ *     A `pending` return is reached at the per-invocation `maxWaitSeconds`
+ *     bound (`phases/confirm-merge.js`); genuine cumulative exhaustion returns
+ *     earlier as a **blocked** terminal via `blockOnUnlanded` (Story #4654).
+ *     So a routine long-CI window rollover under budget is NOT exhaustion and
+ *     emits nothing — its category name would otherwise assert an exhaustion
+ *     that did not occur. Only the residual case the merge-wait guard cannot
+ *     suppress — a merge that genuinely spends its whole budget and lands on a
+ *     later resume — reaches here. A missing or non-numeric `cumulativeSeconds`
+ *     / `maxBudgetSeconds` means exhaustion cannot be proven → emit nothing. A
+ *     `pending` with **no** `waitBudget` is the `--no-wait-merge` /
+ *     operator-merge path, where the human deliberately owns the land and
+ *     nothing is broken — flagging it would train operators to ignore the
+ *     channel.
  *
  * Deliberately **not exported**: it is this module's internal policy, and
  * `emitTerminalFriction` is the contract callers (and tests) exercise. An
@@ -267,6 +444,21 @@ function frictionForTerminal(envelope) {
   }
 
   if (status === 'pending' && waitBudget) {
+    // Only a PROVEN cumulative-budget exhaustion is friction. The `pending`
+    // return is reached at the per-invocation `maxWaitSeconds` bound, not at
+    // the cumulative `maxBudgetSeconds` (that returns a blocked terminal
+    // earlier), so a routine window rollover carries `cumulativeSeconds`
+    // still under budget — emit nothing. A missing/non-numeric field means
+    // exhaustion cannot be proven, which is likewise not a record.
+    const cumulativeSeconds = Number(waitBudget.cumulativeSeconds);
+    const maxBudgetSeconds = Number(waitBudget.maxBudgetSeconds);
+    if (
+      !Number.isFinite(cumulativeSeconds) ||
+      !Number.isFinite(maxBudgetSeconds) ||
+      cumulativeSeconds < maxBudgetSeconds
+    ) {
+      return null;
+    }
     return {
       category: RUNTIME_FRICTION_CATEGORIES.MERGE_WAIT_EXHAUSTED,
       details: {

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -19,10 +19,10 @@ import { selectAudits } from '../audit-suite/index.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
-import { forEachLine } from '../observability/signals-writer.js';
 import { composeRoutedProposals } from './retro-proposals.js';
 import {
   buildFollowUpsCommentBody,
+  gatherRunFrictionSignals,
   resolveFollowUpRepos,
 } from './story-follow-ups.js';
 import { upsertStructuredComment } from './ticketing.js';
@@ -551,24 +551,10 @@ async function executeFollowUpRollup({
   config,
   cwd,
 }) {
-  const signals = [];
-  for (const raw of stories) {
-    const sid = Number(raw);
-    if (!Number.isInteger(sid) || sid <= 0) continue;
-    await forEachLine(
-      null,
-      sid,
-      (parsed) => {
-        if (!parsed || typeof parsed !== 'object') return;
-        const category =
-          typeof parsed.category === 'string' ? parsed.category.trim() : '';
-        if (!category) return;
-        const source = parsed.source === 'framework' ? 'framework' : 'consumer';
-        signals.push({ category, source });
-      },
-      config,
-    );
-  }
+  // Shared with the story-scoped gather (Story #4649): `storyId` + `details`
+  // are what the composer's recovery-netting keys on, and two hand-rolled
+  // copies of this loop are how they got dropped in the first place.
+  const signals = await gatherRunFrictionSignals(stories, config);
   const repos = resolveFollowUpRepos(config);
   const primaryId = Number(stories[0]);
   const proposals = composeRoutedProposals({

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -33,6 +33,11 @@ import path from 'node:path';
 
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
+import {
+  emitCloseRecoveredFriction as defaultEmitCloseRecoveredFriction,
+  emitRecoveredFrictionMarker as defaultEmitRecoveredFrictionMarker,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../../observability/runtime-friction.js';
 import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
 import {
   executeFastForward as defaultExecuteFastForward,
@@ -250,6 +255,8 @@ async function stepBaseFastForward({
  * @param {object} [args.config]
  * @param {(tag: string, msg: string) => void} [args.progress]
  * @param {Function} [args.captureStoryFollowUpsFn] Test seam.
+ * @param {Function} [args.emitCloseRecoveredFrictionFn] Test seam.
+ * @param {Function} [args.emitRecoveredFrictionMarkerFn] Test seam.
  * @param {Function} [args.reassertStatusColumnFn]  Test seam.
  * @param {Function} [args.gitSpawnFn]              Test seam.
  * @param {Function} [args.planFastForwardFn]       Test seam.
@@ -266,6 +273,8 @@ export async function runPostLandTail({
   config,
   progress,
   captureStoryFollowUpsFn = defaultCaptureStoryFollowUps,
+  emitCloseRecoveredFrictionFn = defaultEmitCloseRecoveredFriction,
+  emitRecoveredFrictionMarkerFn = defaultEmitRecoveredFrictionMarker,
   reassertStatusColumnFn = defaultReassertStatusColumn,
   gitSpawnFn = defaultGitSpawn,
   planFastForwardFn = defaultPlanFastForward,
@@ -274,6 +283,32 @@ export async function runPostLandTail({
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
+  // The close landed, so every friction incident on this Story's stream is
+  // provably resolved. Emit the recovery markers BEFORE follow-up capture
+  // reads the stream: the `landed` terminal envelope is emitted after this
+  // whole tail, so a marker written there would arrive too late to net
+  // anything out of the very run that produced the incident. Each emit is
+  // conditional on an un-recovered record already present, so a Story that
+  // never hit the incident gets no spurious (and bucket-suppressing) row.
+  //   - `close-failed`         — Story #4649.
+  //   - `story-blocked`        — a Story that blocked then reached
+  //     `agent::done` (Story #4654); resolves the occurrence-1 force-file.
+  //   - `merge-wait-exhausted` — a merge that spent its whole budget and
+  //     landed on a later resume (Story #4654); the residual case the
+  //     `frictionForTerminal` budget guard cannot suppress at the source.
+  // Best-effort and never throws, exactly like every other tail step.
+  await emitCloseRecoveredFrictionFn({ storyId, config });
+  await emitRecoveredFrictionMarkerFn({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
+    config,
+  });
+  await emitRecoveredFrictionMarkerFn({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.MERGE_WAIT_EXHAUSTED,
+    config,
+  });
+
   const followUps = await step(
     () =>
       stepFollowUps({

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -12,8 +12,12 @@
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
 import { Logger } from '../Logger.js';
+import { normalizeGatheredSignal } from '../observability/runtime-friction.js';
 import { forEachLine } from '../observability/signals-writer.js';
-import { composeRoutedProposals } from './retro-proposals.js';
+import {
+  composeRoutedProposals,
+  deriveUnresolvedBlockedEvents,
+} from './retro-proposals.js';
 import { upsertStructuredComment } from './ticketing.js';
 
 export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
@@ -46,9 +50,23 @@ export function resolveFollowUpRepos(config) {
 }
 
 /**
+ * Gather the Story's friction signals for the composer.
+ *
+ * **`storyId` and `details` are load-bearing (Story #4649).** This function
+ * used to flatten every record to `{ category, source }`, which silently
+ * dropped exactly the two fields `netOutRecoveredIncidents` keys on — so the
+ * Story #4622 recovery-netting could never fire on real data, and every
+ * transient friction event survived to be auto-filed. The composer's unit
+ * tests passed throughout, because they fed it synthetic signals carrying
+ * both fields that no production path ever produced. Preserve them.
+ *
+ * The record's own `storyId` is preferred over the argument so a stream that
+ * carries foreign rows attributes each one correctly; the argument is the
+ * fallback for records written before the field existed.
+ *
  * @param {number} storyId
  * @param {object} [config]
- * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer' }>>}
+ * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer', storyId: number, details: object }>>}
  */
 export async function gatherStoryFrictionSignals(storyId, config) {
   const signals = [];
@@ -56,22 +74,40 @@ export async function gatherStoryFrictionSignals(storyId, config) {
     null,
     storyId,
     (parsed) => {
-      if (!parsed || typeof parsed !== 'object') return;
-      const kind = parsed.kind;
-      if (kind !== 'friction' && kind !== undefined) {
-        // Prefer friction records; also accept category-bearing rows.
-      }
-      const category =
-        typeof parsed.category === 'string' ? parsed.category.trim() : '';
-      if (!category) return;
-      const source = parsed.source === 'framework' ? 'framework' : 'consumer';
-      signals.push({ category, source });
+      const signal = normalizeGatheredSignal(parsed, storyId);
+      if (signal) signals.push(signal);
     },
     config,
   );
   return signals;
 }
 
+/**
+ * Gather friction signals across every Story in a run, for the run-scoped
+ * roll-up.
+ *
+ * Homed beside {@link gatherStoryFrictionSignals} on purpose: the two used to
+ * be independent copies of the same loop in two modules, and they drifted in
+ * exactly the way that made the recovery-netting unreachable (Story #4649).
+ * One reader, one normalizer, no second place to forget a field.
+ *
+ * Unusable ids are skipped rather than throwing — a roll-up must not fail the
+ * epilogue over one malformed entry.
+ *
+ * @param {Array<number|string>} storyIds
+ * @param {object} [config]
+ * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer', storyId: number, details: object }>>}
+ */
+export async function gatherRunFrictionSignals(storyIds, config) {
+  const signals = [];
+  for (const raw of Array.isArray(storyIds) ? storyIds : []) {
+    const sid = Number(raw);
+    if (!Number.isInteger(sid) || sid <= 0) continue;
+    signals.push(...(await gatherStoryFrictionSignals(sid, config)));
+  }
+  return signals;
+}
+
 /**
  * Render the empty-roll-up line.
  *
@@ -250,7 +286,11 @@ export async function captureStoryFollowUps({
       frameworkRepo: repos.frameworkRepo,
       consumerRepo: repos.consumerRepo,
       signals,
-      unresolvedBlockedEvents: [],
+      // Derived, not hardcoded `[]` (Story #4649). This is the escape hatch
+      // the retired story-scope threshold carve-out was standing in for: a
+      // Story still parked at `agent::blocked` files at a single occurrence,
+      // while one that blocked and self-resolved nets out entirely.
+      unresolvedBlockedEvents: deriveUnresolvedBlockedEvents(signals),
     });
     const graduated = await graduateRetroProposals({
       epicId: sid,

package/docs/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.7.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.6.0...mandrel-v2.7.0) (2026-07-21)
+
+
+### Fixed
+
+* **feedback-loop:** repair the graduator idempotency probe — an HTML-comment-wrapped search query never matches, so every rollup re-files ([#4657](https://github.com/dsj1984/mandrel/issues/4657)) ([#4661](https://github.com/dsj1984/mandrel/issues/4661)) ([9bb9d3a](https://github.com/dsj1984/mandrel/commit/9bb9d3ad674dafb11bcd2fbce771a81b79e8cd51))
+* **retro:** generalize post-land recovery marking and gate merge-wait-exhausted on real budget exhaustion (refs [#4654](https://github.com/dsj1984/mandrel/issues/4654)) ([#4658](https://github.com/dsj1984/mandrel/issues/4658)) ([54c45ae](https://github.com/dsj1984/mandrel/commit/54c45ae4f522688e018c092da0137cc6562e0c73))
+
+## [2.6.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.5.0...mandrel-v2.6.0) (2026-07-20)
+
+
+### Fixed
+
+* **retro:** generalize friction recovery-netting, preserve signal fields on gather, and retire the story-scope singleton auto-file ([#4649](https://github.com/dsj1984/mandrel/issues/4649)) ([#4650](https://github.com/dsj1984/mandrel/issues/4650)) ([bdb8250](https://github.com/dsj1984/mandrel/commit/bdb82507d188bfe53bbd47fea7b18b2c3160439c))
+
 ## [2.5.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.4.0...mandrel-v2.5.0) (2026-07-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",