mandrel 2.6.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

@@ -202,16 +202,20 @@ export async function emitBlockRecoveredFriction({
 }
 
 /**
- * Emit the recovery counterpart of a `close-failed` record when a Story's
- * close ultimately lands (Story #4649).
- *
- * A close that fails once — CI/lease contention, a transient GitHub fault —
- * and succeeds on a later attempt still fired a `close-failed` record at the
- * failed terminal, which the composer counts exactly like a close that never
- * recovered. This is the `close-failed` analogue of
- * {@link emitBlockRecoveredFriction}: same `recovered: true` discriminator,
- * same category (a distinct bucket would itself aggregate into a routable
- * proposal, re-introducing the noise).
+ * 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
@@ -220,39 +224,54 @@ export async function emitBlockRecoveredFriction({
  * 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 failure.** The marker is appended only when the
- * Story's stream already carries an un-recovered `close-failed`. Emitting
- * unconditionally on every land would write a `close-failed` row for Stories
- * whose close never failed — a category-mislabelled record — and, because the
- * netting is per `(category, storyId)` over the cumulative stream, that
- * spurious marker would suppress the Story's `close-failed` bucket outright,
- * making the category un-routable at story scope for a Story that never had
- * a close failure at all.
+ * **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 `close-failed` for a Story that already
+ * 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 failure
+ * 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 emitCloseRecoveredFriction({ storyId, config } = {}) {
+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 failed = false;
+  let incident = false;
   let recovered = false;
   try {
     await forEachLine(
@@ -260,34 +279,52 @@ export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
       sid,
       (parsed) => {
         if (!parsed || typeof parsed !== 'object') return;
-        if (parsed.category !== RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED) {
-          return;
-        }
+        if (parsed.category !== cat) return;
         if (isRecoveredSignal(parsed)) recovered = true;
-        else failed = true;
+        else incident = true;
       },
       config,
     );
   } catch (err) {
     Logger.warn(
-      `[runtime-friction] close-recovery probe failed for Story #${sid}: ${
+      `[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 (!failed || recovered) return false;
+  if (!incident || recovered) return false;
 
   return emitRuntimeFriction({
     storyId: sid,
-    category: RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED,
-    tool: 'runPostLandTail',
+    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.
@@ -368,12 +405,21 @@ export function isRecoveredSignal(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
@@ -398,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/single-story-close/phases/post-land.js

@@ -33,7 +33,11 @@ import path from 'node:path';
 
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
-import { emitCloseRecoveredFriction as defaultEmitCloseRecoveredFriction } from '../../../observability/runtime-friction.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,
@@ -252,6 +256,7 @@ async function stepBaseFastForward({
  * @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.
@@ -269,6 +274,7 @@ export async function runPostLandTail({
   progress,
   captureStoryFollowUpsFn = defaultCaptureStoryFollowUps,
   emitCloseRecoveredFrictionFn = defaultEmitCloseRecoveredFriction,
+  emitRecoveredFrictionMarkerFn = defaultEmitRecoveredFrictionMarker,
   reassertStatusColumnFn = defaultReassertStatusColumn,
   gitSpawnFn = defaultGitSpawn,
   planFastForwardFn = defaultPlanFastForward,
@@ -277,13 +283,31 @@ export async function runPostLandTail({
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
-  // Story #4649 — the close landed, so any earlier `close-failed` for this
-  // Story was transient. Emit the recovery marker BEFORE follow-up capture
+  // 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 failure. Best-effort and
-  // never throws, exactly like every other tail step.
+  // 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(
     () =>

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.6.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/",